ldap.md

LDAP is a directory service we use to inventory the users, groups, passwords, (some) email forwards and machines. It distributes some configuration and password files to all machines and can reload services.

Note that this documentation needs work, particularly regarding user management procedures, see issue 40129.

• Tutorial
  • Getting to know LDAP
  • How to change my email forward?
• How-to
  • Set a sudo password
  • Know when will my change take effect?
  • Locking an account
  • Connecting to LDAP
  • Restoring from backups
    • Partial restore
    • Full rollback
  • Listing members of a group
  • Adding/removing users in a group
    • Adding/removing an admin
  • Searching LDAP
  • Modifying the schema
  • Deploying new userdir-ldap releases
  • Pager playbook
    • LDAP server failure
    • Git server failure
    • Deadlocks in ud-replicate
    • Troubleshooting changes@ failures
    • Dependency loop on new installs
  • Disaster recovery
• Reference
  • Installation
  • SLA
  • Design
    • Architecture overview
    • Configuration file distribution
    • Files managed by ud-generate
    • How files get distributed by ud-replicate
      • makedb template files
      • self-configuration: sshdist authorized_keys
      • other special files
    • Authentication mechanisms
    • SSH access controls
    • LDAP user fields
      • sudoPassword field format
      • sshRSAAuthKey field format
    • LDAP host fields
      • rebootPolicy field values
      • purpose field values
      • exportOptions field values
    • Email gateway
    • Web interface
    • Interactions with Puppet
    • DNS zone file management
    • Source file analysis
  • Issues
  • Monitoring and testing
  • Logs and metrics
  • Backups
  • Other documentation
• Discussion
  • Overview
    • Major issues with userdir-ldap
  • Goals
    • Must have
    • Nice to have
    • Non-Goals
  • Approvals required
  • Proposed Solution
    • Short term: merge with upstream, port to Python 3 if necessary
    • Mid term: move hosts to Puppet, possibly replace ud-ldap with simpler dashboard
    • Long term: replace LDAP completely, with Puppet, GitLab and Kubernetes, possibly SSO dashboard
  • Cost
  • Alternatives considered
    • Replacement web interfaces
    • commandline tools
    • others

Tutorial

The main LDAP documentation is on web interface. See specifically the instructions on how to:

• reset a lost password
• change your SSH key

The rest of this document is targeted at sysadmins troubleshooting LDAP issues, setting up new services, or trying to understand the setup.

Getting to know LDAP

You should have received an email like this when your LDAP account was created:

Subject: New ud-ldap account for <your name here>

That includes information about how to configure email forwarding and SSH keys. You should follow those steps to configure your SSH key to get SSH access to servers (see ssh-jump-host).

How to change my email forward?

Send an (inline!) signed OpenPGP email to changes@db.torproject.org to change your email forward. A command like this, in a UNIX shell, would do it:

echo "emailForward: user@example.com" | gpg --armor --sign

Then copy-paste that in your email client, making sure to avoid double-signing the email and sending in clear text (instead of HTML).

The email forward can also be changed in the web interface.

How-to

Set a sudo password

See the sudo password user configuration.

Know when will my change take effect?

Once a change is saved to LDAP, the actual change will take at least 5 minutes and at most 15 minutes to propagate to the relevant host. See the configuration file distribution section for more details on why it is so.

Locking an account

See the user retirement procedures.

Connecting to LDAP

LDAP is not accessible to the outside world, so you need to get behind the firewall. Most operations are done directly on the LDAP server, by logging in as a regular user on db.torproject.org (currently alberti).

Once that's resolved, you can use ldapvi(1) or ldapsearch(1) to inspect the database. User documentation on that process is in doc/accounts and https://db.torproject.org. See also the rest of this documentation.

Restoring from backups

There's no special backup procedures for the LDAP server: it's backed up like everything else in the howto/backup system.

To restore the OpenLDAP database, you need to head over the Bacula director, and enter the console:

ssh -tt bacula-director-01 bconsole

Then call the restore command and select 6: Select backup for a client before a specified time. Then pick the server (currently alberti.torproject.org) and a date. Then you need to "mark" the right files:

cd /var/lib/ldap
mark *
done

Then confirm the restore. The files will end up in /var/tmp/bacula-restores on the LDAP server.

The next step depends on whether this is a partial or total restore.

Partial restore

If you only need to access a specific field or user or part of the database, you can use slapcat to dump the database from the restored files even if the server is not running. You first need to "configure" a "fake" server in the restore directory. You will need to create two files under /var/tmp/bacula-restores:

• /var/tmp/bacula-restores/etc/ldap/slapd.conf
• /var/tmp/bacula-restores/etc/ldap/userdir-ldap-slapd.conf

They can be copied from /etc, with the following modifications:

diff -ru /etc/ldap/slapd.conf etc/ldap/slapd.conf
--- /etc/ldap/slapd.conf	2011-10-30 15:43:43.000000000 +0000
+++ etc/ldap/slapd.conf	2019-11-25 19:48:57.106055596 +0000
@@ -17,10 +17,10 @@
 
 # Where the pid file is put. The init.d script
 # will not stop the server if you change this.
-pidfile         /var/run/slapd/slapd.pid
+pidfile         /var/tmp/bacula-restores/var/run/slapd/slapd.pid
 
 # List of arguments that were passed to the server
-argsfile        /var/run/slapd/slapd.args
+argsfile        /var/tmp/bacula-restores/var/run/slapd/slapd.args
 
 # Read slapd.conf(5) for possible values
 loglevel        none
@@ -57,4 +57,4 @@
 #backend		<other>
 
 # userdir-ldap
-include /etc/ldap/userdir-ldap-slapd.conf
+include /var/tmp/bacula-restores/etc/ldap/userdir-ldap-slapd.conf
diff -ru /etc/ldap/userdir-ldap-slapd.conf etc/ldap/userdir-ldap-slapd.conf
--- /etc/ldap/userdir-ldap-slapd.conf	2019-11-13 20:55:58.789411014 +0000
+++ etc/ldap/userdir-ldap-slapd.conf	2019-11-25 19:49:45.154197081 +0000
@@ -5,7 +5,7 @@
 suffix          "dc=torproject,dc=org"
 
 # Where the database file are physically stored
-directory       "/var/lib/ldap"
+directory       "/var/tmp/bacula-restores/var/lib/ldap"
 
 moduleload      accesslog
 overlay accesslog
@@ -123,7 +123,7 @@
 
 
 database hdb
-directory       "/var/lib/ldap-log"
+directory       "/var/tmp/bacula-restores/var/lib/ldap-log"
 suffix cn=log
 #
 sizelimit 10000

Then slapcat is able to read those files directly:

slapcat -f /var/tmp/bacula-restores/etc/ldap/slapd.conf -F /var/tmp/bacula-restores/etc/ldap

Copy-paste the stuff you need into ldapvi.

Full rollback

Untested procedure.

If you need to roll back the entire server to this version, you first need to stop the LDAP server:

service slapd stop

Then move the files into place (in /var/lib/ldap):

mv /var/lib/ldap{,.orig}
cp -R /var/tmp/bacula-restores/var/lib/ldap /var/lib/ldap
chown -R openldap:openldap /var/lib/ldap

And start the server again:

service slapd start

Listing members of a group

To tell which users are part of a given group (LDAP or otherwise), you can use the getent(1) command. For example, to see which users are part of the tordnsel group, you would call this command:

$ getent group tordnsel
tordnsel:x:1532:arlo,arma

In the above, arlo and arma are members of the tordnsel group. The fields in the output are in the format of the group(5) file.

Note that the group membership will vary according to the machine on which the command is run, as not all users are present everywhere.

Adding/removing users in a group

Using this magical ldapvi command on the LDAP server (db.torproject.org):

ldapvi -ZZ --encoding=ASCII --ldap-conf -h db.torproject.org -D "uid=$USER,ou=users,dc=torproject,dc=org"

... you get thrown in a text editor showing you the entire dump of the LDAP database. Be careful.

To add or remove a user to/from a group, first locate that user with your editor search function (e.g. in vi, you'd type /uid=ahf to look for the ahf user). You should see a block that looks like this: