Schema_Handling

When developing new features it may be necessary to extended the LDAP schema on the server. This operation is delicate, what follows are best practices and requirements to handle schema changes in the FreeIPA project.

Prior Art

We generally try to use existing standard schema if at all available, so the first step when any new schema is needed is to search the literature and find out if anything exists and is a good fit for the task at hand. If prior schema exist but is not sufficient we also prefer to use what is available and then only extend it with additional auxiliary objectclasses and attributes. If no schema exists or existing schema is an odd fit, then new schema can be considered.

General Considerations

FreeIPA is a distributed system, where multiple servers act on the same data at the same time, this introduces additional constraints on the kind of operations that can be performed on a server. Extreme care should be used when defining and introducing new schema. The author (And reviewers) always need to keep in mind how all servers will operate during a transition phase in which some servers have the new code and schema and some servers don’t. Although schema is propagated via replication that only happens after a new server send new changes to an older one. For some amount of time two servers may run at different schema revisions. This need to be accounted for. Race conditions may happen when objects are updated at the same time on two different servers, there are techniques that can be used to make sure updates between two servers do not stomp on each other, if in doubt open a discussion on the mailing list about how to best handle updates for the specific case at hand.

Choosing attributes and objectclasses

Creating new schema requires considereing a number of factors.

Naming Conventions

If the schema is very FreeIPA specific we try to namespace attributes and objectclasses by using the prefix ‘ipa’ in fron of attribute and objectclass names. If the schema is of general use and nothing standardized exist then other prefixes may be considered. We always advice to use meaningful prefixes nonetheless to avoid potential future name clashes with other popular schema.

OIDs

The FreeIPA project have been assigned its own OID space under the original 389ds OID space. The FreeIPA toplevel OID is: 2.16.840.1.113730.3.8 If you plan to create new attributes and objectclasses please announce that on the development list and ask for assignment, with a full schema description if available. If you haven’t worked out the details of each new object but you know exactly how many you will need, you can get an allotment reserved too.

ObjectClasses and Attribute types

Please chose the most appropriate type for attributes, it is important to make sure you think through each attribute syntax, and equality, as well as how using these attributes will impact performances and whether indexes should be created. For objectclasses it is important to decide whether the class is structural or auxiliary, and which of the attributes should be always required (MUST) and which should be optional (MAY). In case of doubt open a discussion on the development mailing list.

Changing existing Schema

In rare cases it may be necessary to modify an existing objectclass or an attribute to add more capabilities. We stgrongly recommend to avoid changes if at all possible, and allow only “safe” changes.

For objectclasses we allow changing from auxiliary to structural only, not the other way around. For attributes, an attribute can only go from MUST to MAY, not the other way around. Attributes cannot be dropped, and new attributes can only be added as MAY. For attributes, changes in syntax are allowed only if the new syntax is a complete superset of the previous one. Changes in equality matches are allowed. A SINGLE-VALUE attribute can become multivalued but not the other way around.

Technical Details

To change the schema, edit (or add) an appropriate install/share/*.ldif file in the FreeIPA source. When creating a new file, it needs to be added to install/share/Makefile.am and to IPA_SCHEMA_FILES in ipaserver/install/dsinstance.py. See Contribute/Code for how to submit your change.

Background

A good place to learn about LDAP schema concepts is “LDAP for Rocket Scientists” at zytrax.com.