Linux Directory Infrastructure (LDI) Customer Documentation

Linux Directory Infrastructure is a common LDAP directory service geared toward the needs of Linux-based servers and desktops.

This is an IT-to-IT service intended for use by campus units as a building block for IT infrastructure. The core feature of LDI is that the directory stores and provides user account and group data which is synchronized with UW data sources for groups (Groups Web Service) and users (Person Web Service). This allows easy integration of Linux clients with common UW user data. Each campus unit which consumes LDI has a delegated organizational unit in the directory, has control over the synchronization process, and ability to add unit specific directory information.

LDI is a service of UW-IT supported by Standard Managed Server and offered at no cost to campus units.

Overview

This service was designed and built for use by any department/group that maintains Unix/Linux systems and currently runs and maintains their own LDAP servers no matter how large or small.  One of the goals is to mimic the delegated ou infrastructure that provides a shared Windows infrastructure for use by any group on campus, but optimized in a Unix-centric way.  This shared infrastructure helps to eliminate the expense of purchasing and maintaining local LDAP servers while enabling and encouraging use of common UW group and person data sources.

The core functionality of LDI is a LDAP directory which is synchronized with central UW data sources.  An organizational unit is configured for each customer (departmental unit) of the service. The departmental unit creates and manages groups in the UW Groups Service in the usual way. The LDI synchronization process then populates the LDAP ou using GWS as the source. Using the list of all UWNetIDs seen as group members during the group sync an account and user private group is created for the UWNetID. Changes to groups and users are regularly synchronized. User account objects also contain non-synchronized files allowing customizations and a sub-unit is completely delegated for local purposes.

Getting Started

To begin using LDI you must request that your LDAP organizational unit be created and the LDI automation initialized. 

1. Make a request to help@uw.edu for Linux Directory Infrastructure.
2. Provide the following information:
   1. Name of your LDAP organizational unit. Suggested to be concise and meaningful, this is the ou= component of your LDAP directory. For example, UW-IT might use "uwit".
   2. The name of the UW Groups Service stem from which to source your groups. All groups under this stem will be synchronized. For example: "uw_uwit", or "uw_physics_unixgroups"
   3. One or more email addresses for the technical contacts for this service. The synchronization process will notify the technical contacts when any errors occur. These addresses may also be used to announce service changes.
3. LDI will be configured and we will send an initial password for the unitAdmin account.
4. Connect to LDI at ldi.s.uw.edu using TLS on port 389 (preferred) or SSL on port 636.
5. Using the documentation here you will configure the following (see Getting started):
   1. A new unitAdmin password
   2. LDI Control Variables to enable and control synchronization
   3. Add Incommon client certificates for authentication of administrators.
   4. Add Incommon client certificates for read-only consumers.
   5. Configure and Maintain Groups under your Groups Service Stem.
   6. Optionally add other LDAP data to your organizational unit.
6. When everything is ready you must manually enable LDI synchronization using the enableSync Control attribute.

Continue reading or see more setup detail in Getting started

Getting Help / Assistance

• LDI-users mailman list. This is where service announcements will go and, as an "IT-to-IT" service, where the community shares information about using the service. We strongly suggest subscribing to the mailman list. It is a good place to ask questions and seek advice. http://mailman.u.washington.edu/mailman/listinfo/ldi-users 
• Contact us at help@uw.edu mentioning Linux Directory Infrastructure.

LDAP Directory Structure

The top level dn in LDI is dc=ldi,dc=uw,dc=edu. All departmental units will appear below this. You will only be able to see and access those to which you have access. The base dn of your DIT will be of the form ou=yourunit,dc=ldi,dc=uw,dc=edu and below this the following structure exists:  

• ou=auth is populated with unit LDAP authorization info.
  • cn=unitAdmin is an object with a password for administrator access. See Administrative Access below.
  • cn=AdminAccess (objectClass groupOfNames) contains one or more “member” attributes. Each member attribute is the cn of an Incommon certificate allowed for administrative access to the unit out. 
  • cn=BasicAccess (objectClass groupOfNames) contains one or more “member” attributes. Each member attribute is the cn of a Incommon certificate allowed for client-level read-only access to the unit outU.
• ou=control contains attributes which control the synchronization process. See Controlling the Sychronization Process for details. Admin users can change these controls.
• ou=status contains informational attributes which reflect the state of the synchronization process. This is not the only source of information, errors are also sent by email to the technical contact.
• ou=groups is populated with groups from GWS by the synchronization process. This OU is not writable by departmental admins, only by the synchronization process. Any groups that need to appear here should be created in the Groups Service under the syncStem.
  • cn=<a_group> group objects within this ou are ldiPosixGroup class but contain the standard rfc2307 posixGroup attributes.
• ou=accounts is populated with user accounts by the synchronization process. This OU is writable by department admins. Certain individual account object attributes can be modified (see Synchronization Process), including non-synchronized attributes and unit controlled attributes. Account objects can be created and exist here outside of the synchronization process if the account creation and deletion control attributes are set appropriately.
  • uid=<a_user> account objects within this ou are ldiPosixAccount class but also contain the standard rfc2307 posixAccount attributes.
• ou=unit is entirely within the control of the department to be used for any purpose (Netgroups, Automounts, etc...). Writable by administrators in AdminAccess and readable by those in BasicAccess.

See this more terse technical overview of the LDI Schema

Administrative Access

Departmental administrators will have write access to LDAP and control of the departmental DIT. Administrators will typically authenticate using an Incommon client certificate. Departments can configure one or more full-access client certificates as needed. (This service strives to NOT create "yet another" insecure password database, and discourage the hardcoding of LDAP passwords in configuration files and scripts. Thus the reason certificate auth is the primary method.)

In addition to client certificate authentication, each departmental OU will have one LDAP administrator account with password access. This account can be used to bootstrap the directory or as access of last resort for misconfiguration of certificate authentication. In all cases the departmental administrator dn is "cn=unitAdmin,ou=auth,ou=<your_ou>,dc=ldi,dc=uw,dc=edu". An initial password will be sent and should be changed and kept secure.

Administrators will use normal LDAP tools and techniques to manage the directory. LDI does not dictate or provide those tools.

• Configuring Certificate Access

Client Access

LDI is a service to be consumed by computers (servers and desktops) configured to use LDI for their user and group data sources. Thus, when we refer to “client access” we refer to consuming computers, not end-users. End-users will never directly access this service.

Most clients are expected to be computers with LDAP-enabled authorization mechanisms integrated into their operating system. NSS and SSSD are two such mechanisms available in current Linux distributions. These clients will be allowed read-only access to a single departmental DIT.

Clients will authenticate to LDI a Incommon client certificate. Passwords will not be used. Departments will configure one or more read-only client certificates as needed. It is anticipated that many clients will share a single client certificate. For example, UW-IT Standard Managed Server might have an Incommon certificate with cn=sms-ldi-reader.s.uw.edu which we would distribute to all servers which need read access. This is easier to maintain than individual certs for every computer and superior to hardcoding passwords in config files.

• Configuring Certificate Access
• Configuring Linux Clients for LDI

Configuring and Maintaining Groups

The GWS source of groups for LDI is specified by the syncStem Control attribute. All creation and maintenance of groups is performed through the Groups Service web interface at https://groups.uw.edu. You may create groups at a root stem or at a lower level. It may not be desirable to synchronize all of your groups and their membership to LDI so typically a sub-stem would be created to define the groups that are explicitly intended for LDI.

For each group under the syncStem, the group will be created in LDI and synchronized. The name will be shortened by removing the syncStem before creating it in LDI. For example, with a syncStem of uw_uwit_ldigroups the group uw_uwit_ldigroups_project_x will appear in LDI as "project_x". When naming groups you must be cautious to not create naming conflicts with user private groups. For example, uw_uwit_ldigroups_regents would become "regents" and conflict with the user private group created for the UWNetID "regents". If conflicts arise, a warning will be issued.  Linux has a group name limit of 32 characters. The name of each group must be less than 33 characters after the syncStem is removed. A warning will be issued on non-compliant names.

All groups synchronized to LDI must have a data classification of public. The synchronization process has no special access privileges and cannot read the membership of restricted or confidential groups. In this case the group will be created but there will be zero memberUids. If a group changes from public to something more restrictive all members will be removed from LDAP. A warning will be issued for groups without public data classification.

Groups you configure for synchronization with LDI and typically visible on Linux systems which do not have group privacy controls must consider FERPA guidelines. It is your responsibility to not create groups that reveal course names or membership. However, official course groups can be added as nested members of groups you create for LDI, in which case the effective membership will include the course group membership. For example, a departmental group that allows access to common lab materials named "dept_lab_users" could be created that allows students of a list of courses to access the lab, the course groups nested in that group would add the students but not reveal the specific courses.

Controlling and Managing the Synchronization Process

Process Overview

The LDI synchronization process runs hourly to populate and maintain the LDAP database with data from the Groups Web Service (GWS) and the Person Web Service (PWS). Group creation/deletion and user creation/deletion is performed twice each hour, the exact time it runs varies. Updates to user account name (gecos) and uidNumber changes are done once a day during a daily reconciliation since this is a more time consuming process. Other than the data synchronization of specific objects and attributes, LDI does not update or audit unit defined attributes, objects or sub-trees.

The control attributes below define the behaviour of the process. It is otherwise completely automated. All control attributes must exist and have values in order for the process to run.

Synchronized Data

All groups under the Control attribute "syncStem" are read from GWS and populate the ldap groups OU (ou=groups). The syncStem is stripped from the group name. For example with a syncStem of “uw_physics_tosync”, the group “uw_physics_tosync_agroup” becomes “agroup” in LDAP. The group is created if it does not exist. The GWS gidNumber populates the gidNumber. The GWS title populates the description attribute. The effective membership of the group (only members of type UWNetID) populates the memberUid list. The GWS group must have public data classification to read the membership and any nested groups must also be public. If the group is becomes unreadable in GWS due to data classification change, the membership will be cleared. If any nested group is unreadable or becomes unreadable due to data classification, those members will be cleared. Finally, if any group has been removed from GWS it is removed from the groups OU.

The union of member UWNetIDs seen across all groups under syncStem is the list of candidate uids to be added to the accounts OU (ou=accounts). If enableAccountCreation is set, account objects will be created for every candidate uid. If not set, no account objects will be created.

If enableAccountDeletion is set, the account object for any uid not appearing in the union of uids will be deleted from the accounts OU. If not set, no account objects will be deleted. If account deletion is disabled, no LDI process will ever delete accounts; this must then be done by some other method.

When creating an account object the following attributes are set. Note that five of these values are MUST values in the posixAccount schema and we consider loginShell required as well, so these must be set to comply and provide consistent behaviour to clients. To achieve this we use default values where necessary. The assertion is that the sync process should always result in an account object that “works”.

• cn: UWNetID
• uid: UWNetID
• uidNumber: the numeric uid from Person Web Service (PWS)
• gidNumber:
  • If enableUserPrivateGroup enabled: a calculated gid = 2120000000 + uidNumber
  • If enableUserPrivateGroup disabled: the value of defaultUserGIDNumber
• gecos: displayName attribute from PWS.
• homeDirectory: concatenation of defaultHomeDirPath, a forward slash and the uid.
• loginShell: the value of defaultShell
• No attributes prefixed with “unit” are set.

If an account object already exists these values are checked and updated during the nightly reconciliation:

• uidNumber: the numeric uid from Person Web Service (PWS)
• gidNumber: one of
  • If enableUserPrivateGroup enabled: a calculated gid = 2120000000 + uidNumber
  • If enableUserPrivateGroup disabled and a value is set: the value is not updated, allowing unit customization.
  • If enableUserPrivateGroup disabled and a value is not set: the value of defaultUserGIDNumber
• gecos: displayName attribute from PWS.
• homeDirectory:
  • if value already set: not updated, allowing customization to user or administrator preference;
  • if  value is not already set: concatenation of defaultHomeDirPath, a forward slash and the uid.
• loginShell:
  • if value already set: not updated, allowing customization to user or administrator preference;
  • if  value is not already set: the value of defaultShell.
• No attributes prefixed with “unit” are modified.

For each account user private groups are created in groups OU if enableUserPrivateGroup is enabled. The name of the user private group will be the same as the uid. For example, the group for “erich” will be “erich”. As above, the gid = 2120000000 + uidNumber.

If enableUserPrivateGroup is not set, any existing user private groups in groups OU will be removed. Existing user private groups will be identified by their gidNumber in the 2120000000 range.

Control Attributes

The attributes in cn=control direct the operation of the synchronization process. All are writable by departmental administrators. These will be set to reasonable defaults upon creation of a departmental DIT. All values must be set for the synchronization process to run.

Status Notifications

The synchronization process will send output to the techContact email addresses if any warnings are generated in the process of synchronizing the ou. Warnings are issues which the techContact should correct. Errors and critical faults are also visible but are generally LDI faults.

It is important that techContacts actively address any warnings raised. The LDI service does not monitor or correct warnings within the synchronization of individual ou's.

Status Attributes

The status object (cn=status) in LDAP contains read-only attributes indicating the state of the most recent synchronization. These are pretty self explanatory.

Service Server Infrastructure

LDI consists of three redundant servers with LDAP synchronous replication between them. Two servers are located in data centers on the main UW campus in Seattle and one located at our data center in Spokane.

Specialized Details

• Accessing LDI from the command-line
• Accessing LDI Programatically