This is a guide to using the Gentoo Infrastructure LDAP system for developers, recruiters and administrators.
LDAP stands for Lightweight Directory Access Protocol, a lightweight client-server protocol for accessing directory services. LDAP directory service is based on a client-server model. One or more servers contain the data making up the LDAP directory tree. An LDAP client connects to an LDAP server and requests information. The server responds with the data or points the client to another source (typically another LDAP server).
Just like a database, an entry in LDAP consists of fields of data or 'Attributes'. This collection of attributes is called a 'Schema'. This guide will explain which attributes are available, who can change them and give role based examples for modifying the Gentoo LDAP Schema.
When a developer accesses a resource, like dev.gentoo.org (woodpecker.gentoo.org), the resource acts as an LDAP client and queries the LDAP server (ldap1, ldap2, ldap3, ldap4) to see if that user is in the database and authorized for access.
LDAP Access Levels
LDAP is used by Gentoo to secure the infrastructure. Gentoo resources are spread across the globe and LDAP gives us a central location to manage them. There are four levels of access: anonymous, user, recruiter and infra that are used to control what can be changed in the LDAP database. These are controlled via special values in the gentooAccess attribute.
You must connect or bind to the LDAP database either anonymously, or as a known user. Binding anonymously will always grant only the anonymous level, while binding as a known user will grant you the level based on your user and potentially where you are connecting from.
The anonymous level is used for simple read only informational queries. All developers and staff can bind to LDAP as anonymous. If you don't specify a mode when you bind, anonymous is assumed.
The user level is used to add or change information in your own LDAP record. Things like your latitude and longitude, ssh public key and so on. All users can access the user level, by binding as themselves with the mode specified, and providing their password.
The recruiter level enables recruiters to add new users, and perform some administrative changes to users.
The infra level enables the infrastructure team full power over LDAP, and is additionally protected by only being available from ldap1.gentoo.org.
Gentoo LDAP Implementation
Currently we have four LDAP servers available. The master server and three slave servers. The master LDAP server is reachable at ldap1.gentoo.org. The slave servers are ldap2.gentoo.org, ldap3.gentoo.org, ldap4.gentoo.org and they connect every 60 seconds to the master to replicate changes from the master.
Every update operation must be done on ldap1.gentoo.org, if an update (which means writing some entry) is performed on the slave a referral to the master is issued. This is transparently handled and all attempts to update against the slave will be redirected to the master. Connections are validated via TLS + password. The password is your dev one and is the same for all LDAP-aware boxes.
We use a custom script,
perl_ldap that uses Net::LDAP, for accessing and modifying the database, it allows only a predefined set of actions but it should cover 95% of the cases. In the following chapters we explain how to use it.
The following attributes are included in the Gentoo Schema. Note the 'Access Level' needed to write each attribute. Anonymous reading is allowed unless otherwise noted. Required fields are emphasised.
|Attribute Name||Access Level||Description||Type||Format|
|birthday||user (not globally readable)||developer birthday||single, optional||UTF-8|
|gentooAccess||infra, top level recruiters only||developer access level||multiple, required||UTF-8|
|gentooAlias||infra, recruiters||alternate names for this developer||multiple, optional||UTF-8|
|gentooDevBug||infra, recruiters (not globally readable)||bug numbers for any recruitment, retirement or developer relations bugs||multiple, optional||integer|
|gentooGPGFingerprint, gpgfingerprint||user||GPG key fingerprint||multiple, optional||UTF-8|
|gentooGPGkey, gpgkey||user||GPG key uid||multiple, required||UTF-8|
|gentooIM||user||instant messaging ID||multiple, optional||UTF-8|
|gentooJoin||infra, recruiters||developer join date||multiple, required||UTF-8|
|gentooLatitude, lat||user||latitude coordinate||single, optional||signed decimal string|
|gentooLocation||user||developer location||single, required||UTF-8|
|gentooLongitude, lon||user||longitude coordinate||single, optional||signed decimal string|
|gentooMentor||infra, recruiters||username of mentors||multiple, optional||UTF-8|
|gentooRetire||infra, recruiters||developer retirement date||multiple, optional||UTF-8|
|gentooRoles||user||developer projects||single, required||UTF-8|
|gentooSPF||user||developer SPF record||single, optional||ASCII|
|gentooStatus||infra, recruiters||developer status||single, required||UTF-8|
|sshPublicKey||user||OpenSSH public key||multiple, required||UTF-8|
The following attributes were in use at some point in the past, but have been retired: gentooHerd/herd, gentooAltMail/altMail, gentooForumsUID/forumsUID.
Additionally, we use a number of standard LDAP schemas for user records: inetOrgPerson, organizationalPerson, person, posixAccount, shadowAccount. Some of the attributes in these schemas are listed below.
|Attribute Name||Access Level||Description||Type||Format|
|user||alternative email addresses||multiple, required||UTF-8|
|cn, sn, givenName||recruiters||real name of developer||single, required||UTF-8|
|gecos||recruiters||real name of developer for script usage||single, required||ASCII, 7-bit clean|
|initials||recruiters||real name of developer||single, optional||UTF-8|
|loginShell||user||login shell, change with chsh||single, required||ASCII|
|userPassword||user||password, change with passwd ONLY||single, required||ASCII, hashed|
LDAP management with perl_ldap
These are the main concepts of the perl_ldap script used for user administration. Invoking perl_ldap without arguments shows a nice help. Your own LDAP password is required when binding.
The script is the infra supported method for managing entries, nothing prevents you from using any LDAP browser you like for modifying your attributes. If you like to use something else, ask infra for connection details but keep in mind that we won't support and/or troubleshoot other browser's issues.
The following are the most common options.
-b MODEused to bind to the LDAP server. If you don't specify user, the script will default to anonymous and be read only.
-s <username>shows the entire LDAP record for the user
-S ATTRIBUTEsearches for a specific attribute across all users
-M ATTRIBUTE NEWVALUE <username>overwrites the value of an attribute for the specified user
-C ATTRIBUTE NEWVALUE <username>creates a new attribute for the specified user
-E ATTRIBUTE OLDVALUE <username>erases an attribute
Gentoo Developers and Staff members (recruiters and infra please refer to the following sections) can update their LDAP record directly. Here are examples of the most commonly changed attributes. The most common error is using a actual username in place of the
-b MODE argument, which takes user as the parameter.
- Show attributes for a user entry (substitute <username> for an actual user name)
- Binding as 'user' will show additional information
- Change your roles
- Change your GPG key (substitute <*keyid> with your GPG key ID, with the leading 0x included)
- Add a new public SSH key (substitute 'pubkey' with the path to your public SSH key. ex: "~/.ssh/id_dsa.pub")
- You should have one sshPublicKey attribute per key! No newlines! Only replace <username>, not "user"
- Erase an old public SSH key
- Change your LDAP password
- To change your password, simply use the normal passwd command on any LDAP-enabled server.
- Do not use perl_ldap to change your password, as it does not perform any password hashing.
- Change your login shell
- To change your login shell, simply use the normal chsh command on any LDAP-enabled server.
- If you want to use a shell other than bash, ask infra about it's availability on other machines
- Change your SPF rules
Recruiters can change their own attributes or those of another user. You must bind as recruiters to change any attributes including your own. The following examples show how to change attributes for other users. To change your own attributes use the examples from the "users" section above but bind as a recruiter.
When dealing with users that belong to a sub-OU the
-o OU option must be used, this will be clarified in the examples. The command
-o OU must be used if the target user belongs to a sub-OU.
The following examples will show you how to change attributes for users, recruiters and infra. All write operations performed by infra against another user must be performed on dev.gentoo.org (woodpecker.gentoo.org).
Some attributes, like sshPublickey, and mail, allow multi-values. To append an additional value to the exiting ones use
-C. You may not use
-M with multi-valued attributes.
- Modify (overwrite) an existing single-instance attribute for a user
- Modify (overwrite) an existing multiple-instance attribute for a user
- Delete an attribute for a user
- Add a new user (infra, recruiters)
- Delete a user (infra)
- Create or modify multi-value attributes
- Create a new attribute while preserving the existing ones. Use the command multiple times to add addtional attributes
- Reset a user password
- Only available to senior recruiters and infrastructure admins in the useradmin group on woodpecker, as well as either the recruiters or infra-ldapadmin groups in LDAP. You will be prompted for YOUR password. The new user password will NOT be shown to you, it will only be placed in /home/<username>/passwd.
Infra can change their own attributes or those of another user. You must bind as user to change any attributes, including your own. To change your own attributes use the examples from the "users" section above from any LDAP-aware machine. To change another users record, you must be using perl_ldap from ldap1.gentoo.org (duck.gentoo.org).
gentooAccess controls which boxes a user can login to. Only infra and a few selected recruiters are allowed to create and modify this multi-value attribute. The FQDN must be used (ex. roadrunner.gentoo.org). Some special values also exist: infra.group, infra-ldapadmin.group, infra-cvsadmin.group, infra-system.group, recruiters.group.
We would like to thank the following authors and editors for their contributions to this guide:
- Andrea Barisani
- Robin H. Johnson
- Luis Medinas
- Curtis Napier