Skip to content

User management

System users on our compute cluster is managed through LDAP. This page describes common operations for user management. For details on how the LDAP service is set up, see LDAP.

Management commands

All management commands ldap* can be executed in two ways:

  • SSH into the LDAP VM and run the command as root.
  • Run the command on any other machine, using -D cn=admin,dc=acsa and supply the LDAP admin password.

Add new user

Create an LDIF file with the following content:

dn: uid=ibug,ou=user,dc=acsa
objectClass: posixAccount
objectClass: shadowAccount
objectClass: inetOrgPerson
objectClass: sambaSamAccount
cn: Jiawei Fu
sn: Fu
uid: ibug
uidNumber: 2001
gidNumber: 2000
homeDirectory: /home/ibug
loginShell: /bin/bash
gecos: Jiawei Fu
sambaSID: S-1-5-21-0000000000-0000000000-0000000000-2001

Replace the following keys from the above example content:

  • The first component of dn should be the same as UID (below)
  • cn is the user's full name (common name).
  • givenName is the user's given name.
  • sn is the user's surname.
  • uid is the user's login name, or POSIX user name.
  • uidNumber is the user's UID number. Make sure it's unique.
  • gidNumber is the user's GID number. For ease of management we set this to 2000 (staff) for everyone.
  • homeDirectory is self-explanatory.
  • loginShell is also self-explanatory.
  • gecos is the user's full name. Could be arbitrary but it's recommended to match CN. Note that neither CN nor SN is read by Linux, only this "gecos" key is.
  • sambaSID should be S-1-5-21-0000000000-0000000000-0000000000-<uidNumber>.

Note

To avoid UID conflict, here is a one-line script to find the existing max UID number.

ldapsearch -LLLQ uidNumber | grep uidNumber | sort | tail -1

Alternatively, you can use this one on any machine:

getent -s ldap passwd | sort -t : -k 3 -g

Warning

getent passwd may return users in any order and is not sorted by UID. Sort it yourself if you must.

Samba SMB access

The object class sambaSamAccount is required for SMB access and OpenVPN to our Synology DiskStation. If you don't want to grant either access, you can omit this object class and the sambaSID attribute.

Add the user to LDAP:

ldapadd -x -D "cn=admin,dc=acsa" -W -f <filename.ldif>
Obsolete: Add user to group

Obsolete reason: It's not necessary to add a user to their primary group.

Now create another LDIF file to add the user to our staff group:

dn: cn=acsastaff,ou=group,dc=acsa
changetype: modify
add: memberUid
memberUid: ibug

Submit the changes with the following command. Note that the command is ldapmodify, not ldapadd.

ldapmodify -D "cn=admin,dc=acsa" -W -f <filename.ldif>

Set a password for the new user:

ldappasswd -D "cn=admin,dc=acsa" -W -S uid=<user>,ou=user,dc=acsa

Instead of -S, the new password may be specified on the command line directly using -s <password>. Alternatively, omit both -S and -s to let the tool generate a random password so you can hand out to the user.

This command can also be used to reset a forgotten password.

Create home directory

Finally, log in to NFS server (as root) and create their home directory:

Helper script

A helper script is present at /root/mkhomedir.sh with the following content:

#!/bin/sh

if [ $# -ne 1 ]; then
  echo "Usage: $0 USER" >&2
  exit 1
fi

set -e
user="$1"
dir=/home/"$user"
zfs create rpool"$dir"
rsync -a /etc/skel/ "$dir"/
chown -R "$user": "$dir"

Usage is straightforward: ~/mkhomedir.sh <user>

Manual method 
zfs create rpool/home/<user>
rsync -a /etc/skel/ /home/<user>
chown <user>: /home/<user>

Make sure to create a separate ZFS filesystem for each user. This will make future maintenance easier.

ZFS refquota

The dataset at rpool/home has its refquota set to 1 MB intentionally as a reminder to create children datasets. The property refquota does not propagate to descendants and applies to rpool/home itself only.

If for any reason this limit is reached, consider increasing it slightly (e.g. zfs set refquota=2M) instead of removing it (zfs inherit refquota).

Hint: Use ncdu -x /home to quickly spot any anomalies.

Update on ZFS refquota

We discovered severe performance regressions of zfs create / zfs destroy with refquota=1M. Consequently, we removed the setting (zfs inherit -S refquota rpool/home) and are now relying on Grafana alerting about abnormal usage on /home itself.

References for the performance issue:

Add new group

The LDIF content for a new group is much shorter:

dn: cn=staff,ou=group,dc=acsa
objectClass: posixGroup
cn: staff
gidNumber: 2000
description: ACSA staff
#memberUid: ibug
#memberUid: chivier

Pay attention to the the first component of DN, as well as CN and gidNumber. Apply this file with ldapadd.

You can also add some initial users using the memberUid keys. After the group is created, additional users must be added with ldapmodify.

Info

LDAP does not provide a built-in mechanism to restrict login to specific machines, though SSH access control can be configured on the SSH server. See SSH.

Change user information

To change the user information such as homeDirectory, gecos or uidNumber (which is rarely a good idea), use ldapmodify:

dn: uid=<user>,ou=group,dc=acsa
changetype: modify
replace: homeDirectory
homeDirectory: /home/example

Reset password

Usually you should use ldappasswd that generates a random 8-character password. The user can then change the password at their will.

Import Unix password

If you're importing existing passwords from a typical Linux system's /etc/shadow file, ldapmodify should work here.

The shadow file contains lines like this:

root:$y$j9T$egdUbc2x4FiVY42xxEH4z.$OJA25VwJ2fIEZizIqUDkS/yUtz8z5tuRiSS3XLum/F3:19064:0:99999:7:::

The 2nd field delimited by colon is the encrypted password in Bcrypt format (sometimes referred to as Bcrypt2). To import that into LDAP, prepend the hash with {CRYPT}, like this:

dn: uid=<user>,ou=group,dc=acsa
changetype: modify
replace: userPassword
userPassword: {CRYPT}$y$j9T$egdUbc2x4FiVY42xxEH4z.$OJA25VwJ2fIEZizIqUDkS/yUtz8z5tuRiSS3XLum/F3

It will be replaced with LDAP's default password hash type when the user changes their password for the next time.

Delete user

Use ldapdelete:

ldapdelete uid=example,ou=user,dc=acsa

Remove their home directory on the NFS server:

Destructive operation

This command does NOT prompt for confirmation. Use with extreme caution.

zfs destroy rpool/home/example

Numeric ID assignment

Assigned UID ranges

Range Description
1090-1100 Competition students
2001-2099 Regular staff
3001-3099 Undergraduate Interns

Assigned groups

Group GID Description
intern 2002 ACSA interns
sscc 2001 Competition
staff 2000 ACSA staff
sudo 1999 Sudo users

Notes

List and sort existing users

getent passwd | awk -F : '{print $3, $1}' | sort -n

For groups, use getent group instead.