Project:Infrastructure/LDAP Guide

From Gentoo Wiki
Jump to:navigation Jump to:search

This is a guide to using the Gentoo Infrastructure's LDAP system for developers, recruiters, and administrators.

Key concepts


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 (, 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 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 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

All write operations performed by infra must be performed on Normal user and recruiter write operations may be performed on any LDAP-connected Gentoo box, however it is strongly recommended to use

Gentoo LDAP implementation

LDAP servers

Currently we have four LDAP servers available. The master server and three slave servers. The master LDAP server is reachable at The slave servers are,, and they connect every 60 seconds to the master to replicate changes from the master.

Every update operation must be done on, 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.

Note is currently using as its first server so any update you do could take up to 60 seconds for being seen on nscd (Name Service Caching Daemon) is used to cache negative and positive lookups. This means the changes may not become active for some time. If you need to force the change we can restart nscd for you. Ask in #gentoo-infra (webchat) for help with this. Additionally, nsscache is used to provide resiliency against LDAP servers being temporarily unavailable for NSS lookups, but we do NOT keep local copies of SSH keys.

Git commit access

Infra uses dev-vcs/gitolite-gentoo to control access to the Gentoo git repositories. At this moment, there is no automation of key updates and one of the Infra members needs to manually sync the keys from LDAP to gitolite and commit the change.

If you change your SSH key, you need to ping Infra to update gitolite. Otherwise commit access will not be available after the key change.

Available attributes

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 emphasized.

All dates must be formatted as ISO8601, YYYY/MM/DD.

Standard attributes

We use a number of standard LDAP schemas for user records where possible: inetOrgPerson, organizationalPerson, person, posixAccount, shadowAccount. Some of the attributes in these schemas are listed below.

Attribute Name Access Level Description Type Format
mail user Alternative email address(es). 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 command). single, required ASCII
userPassword user Password (change with passwd ONLY). single, required ASCII, hashed

Required custom attributes

Attribute Name Access Level Description Type Format, notes
gentooAccess infra, partial recruiter access [specific values] Developer access level(s). multiple, required ASCII
gentooGPGFingerprint, gpgfingerprint user GPG key fingerprint(s). multiple, required ASCII, 40 characters hex, grouped as 1x40 or 5x8 or 10x4, unique over all developers; should list your primary key and NOT subkeys.
gentooJoin infra, recruiters Developer join/rejoin date(s). multiple, required ASCII, YYYY/MM/DD
gentooLocation user Developer location. single, required UTF-8
gentooRoles user Developer project involvement. single, required UTF-8
gentooStatus infra, recruiters Developer status. single, required ASCII, "active" or "retired"
sshPublicKey user OpenSSH public key(s). multiple, required UTF-8, unique over all developers

Optional custom attributes

Attribute Name Access Level Description Type Format
gentooAlias infra, recruiters Alternate name(s) for developer. multiple, optional UTF-8
gentooDevBug infra, recruiters (not globally readable) Bug numbers for any recruitment, retirement, or developer relations bug(s). multiple, optional integer
gentooIM user Instant messaging nickname(s)/handle(s). multiple, optional UTF-8
gentooLatitude, lat user Latitude coordinate (for appearing on developer map). single, optional signed decimal string
gentooLongitude, lon user Longitude coordinate (for appearing on developer map). single, optional signed decimal string
gentooMentor infra, recruiters Username of mentor(s). multiple, optional UTF-8
gentooRetire infra, recruiters Developer retirement date(s). multiple, optional ASCII, YYYY/MM/DD
gentooSPF user Developer SPF record. single, optional ASCII
gentooGitHubUser user Github username. single, optional ASCII
gentooWikiUser user Gentoo Wiki username. single, optional ASCII, ^[A-Z0-9][-._[:alnum:]]{2,}$

Retired attributes

Attribute Name Description Type Format
gentooHerd, herd Herd membership(s) (deprecated). multiple, optional ASCII
gentooAltMail, altMail Alternative email address(es). multiple, optional ASCII
gentooForumsUID, forumsUID Gentoo Forums member UID. single, optional INTEGER
gentooGPGkey, gpgkey GPG key(s) UID(s). multiple, required ASCII

LDAP management with perl_ldap

The following describes the main concepts of the perl_ldap script used for user administration. Invoking perl_ldap without arguments or with -h shows a help output.

user $perl_ldap -h
LDAP Perl interface v1.5
Usage: perl_ldap [common-options] [command-options]
Common options:
  [-b <anon|user|admin>] [-c] [-g] [-Z] [-L] [-H HOST] [-o OU]
Mutually exclusive command options:

Common options:
  -b bind mode (defaults to anon)
  -c interactive mode
  -g group mode
  -Z sudo mode
  -L schema dump
  -H target host
  -o organizational unit
  -e account expiry date: yyyy-mm-dd

Mutually exclusive commands:
  -A add user
  -D del user

  -C create attribute
  -E erase  attribute
  -M modify attribute (single-valued attributes only)

  -P update password
  -R renew account

  -S search attribute
  -s show user
  -U generate userinfo.xml

  -h 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 commonly used options:

Used to bind to the LDAP server. If you don't specify user, the script will default to anonymous and be read-only.
-s $USER
Shows the entire LDAP record for the user username .
Searches for a specific attribute across all users.
Overwrites the value of an attribute for the specified user.
Creates a new attribute for the specified user.
Erases an attribute.



Gentoo Developers (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 $USER for an actual user name)

user $perl_ldap -s $USER

Binding as a user will show additional information

user $perl_ldap -b user -s $USER

Change user's roles

user $perl_ldap -b user -M gentooRoles "<role string>" $USER

Change your GPG key

(substitute <**fp> with your GPG key fingerprint. It should be a 40 character sha1 sum. Exclude the leading 0x if it exists):

user $perl_ldap -b user -C gpgfingerprint "<newfp>" $USER
user $perl_ldap -b user -E gpgfingerprint "<oldfp>" $USER

Add a new public SSH key

(substitute 'pubkey' with the path to your public SSH key. ex: ~/.ssh/

You should have one sshPublicKey attribute per key! No newlines! Only replace $USER, not "user" after the -b flag:

user $perl_ldap -b user -C sshPublicKey "$(cat pubkey)" $USER

Erase an old public SSH key

user $perl_ldap -b user -E sshPublicKey "$(cat oldpubkey)" $USER

Change your LDAP password

To change your password, simply use the normal passwd command on any LDAP-enabled server.

Do not use the perl_ldap utility to change your password. It does not perform any password hashing.
user $passwd

Change your login shell

To change your login shell, simply use the normal chsh command on any LDAP-enabled server.

To use a shell other than bash, ask infra about it's availability on other machines

user $chsh

Change your SPF rules

user $perl_ldap -b user -M gentooSPF "<SPF string>" $USER

Set latitude and longitude

Add latitude (lets you appear on the developers map):

user $perl_ldap -b user -M gentooLatitude "<Latitude number>" $USER

Add longitude (lets you appear on the developers map):

user $perl_ldap -b user -M gentooLongitude "<Longitude number>" $USER

Add gentooIM with your Libera.Chat handle:

user $perl_ldap -b user -C gentooIM "ircs://<nickname>" $USER


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 (

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

user $perl_ldap -b user -M gentooLocation "new location" $USER

Modify (overwrite) an existing multiple-instance attribute for a user

user $perl_ldap -b user -C gentooGPGfingerprint "<newfp>" $USER
user $perl_ldap -b user -E gentooGPGfingerprint "<oldfp>" $USER

Delete an attribute for a user

user $perl_ldap -b user -E mail "" $USER

Add a new user (infra, recruiters)

user $perl_ldap -b user -A $USER

Delete a user (infra)

user $perl_ldap -b user -D $USER

Create or modify multi-value attributes

Create a new attribute while preserving the existing ones. Use the command multiple times to add additional attributes

user $perl_ldap -b user -C mail "" $USER
user $perl_ldap -b user -C mail "" $USER

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, encrypted with the user's GnuPG key, into /home/$USER/passwd.$TIMESTAMP.asc:

user $sudo recruiters-newpasswd-gpg $USER


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 (

The attribute gentooAccess controls which boxes to which a user can login. Only infra and a few selected recruiters are allowed to create and modify this multi-value attribute. The FQDN must be used (ex. Some special values also exist:,,,,

External resources

    This page is based on a document formerly found on our main website
    The following people contributed to the original document: Andrea Barisani, Robin Johnson (robbat2) , Luis Medinas, Curtis Napier
    They are listed here because wiki history does not allow for any external attribution. If you edit the wiki article, please do not add yourself here; your contributions are recorded on each article's associated history page.