Deutsche Version

Back to overview

SSH Users

User management creates one system user per domain that accesses the files of that domain via SSH. Several developers share the user and each adds their own key.

The model is 1:1: one user belongs to exactly one domain. The tool recognizes every account with a home directory under /var/www/ and a UID of 1000 or higher as a domain user. The domain is derived from the directory name.

The user commands need neither Apache nor Nginx on the server. They require setfacl and getfacl from the package acl.

Create a user

server-tools user create --domain example.com --username exampledev

Prerequisites, checked in this order:

1. --domain is a valid domain name. --username is a POSIX name: lowercase letters, digits, _ and -, starts with a letter or _, at most 32 characters. An existing account with a UID below 1000 is rejected.
2. The directory /var/www/<domain> exists and is not a symlink.
3. setfacl and getfacl are installed and getfacl /var/www works, meaning the filesystem supports ACLs.
4. The domain does not have a user yet and the username is not taken.
5. If there is no Apache configuration <domain>.conf for the domain, the tool warns and asks Continue without vhost?. This also applies with ST_WEBSERVER=nginx.
6. ST_USER_DEFAULT_SHELL is an absolute, executable path. If it is not listed in /etc/shells, there is a warning.

Then the tool creates the user with useradd (home /var/www/<domain>, without creating a home directory, comment server-tools domain user for <domain>), creates .ssh and sets the permissions. If .ssh or the ACL setup fails, the user is deleted again and a newly created .ssh is removed.

The new user has no password and no key. Set both as described below.

Permissions

html and logs must already exist under /var/www/<domain>, otherwise the ACL setup fails and the user is rolled back. A DocumentRoot elsewhere that you chose with vhost create --docroot is not covered by the tool.

The tool uses ACLs instead of chroot. It only changes permissions under /var/www/<domain>. The user has a normal login shell and sees everything the system leaves readable for others. DocumentRoots created by the tool have mode 755, so other domains are readable for the user.

Add an SSH key

server-tools user add-key --username exampledev --key "ssh-ed25519 AAAAC3Nza... dev@laptop"

Allowed are ssh-rsa, ssh-ed25519, ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521 and the FIDO variants with the prefix sk-. The key must be a single line of 40 to 8192 characters. An identical line that is already in authorized_keys is not added twice.

The tool checks that the account exists and has no UID below 1000. It does not check whether it is a domain user. The file authorized_keys is located in the home directory of the account.

Set a password

server-tools user set-password --username exampledev
server-tools user set-password --username exampledev --password 'a-long-password'

Without --password the tool generates a password with ST_PASSWORD_LENGTH characters. It is only shown if stdout is a terminal. In scripts a generated password is therefore not retrievable. Pass it there with --password. Passwords you set yourself need at least ST_PASSWORD_MIN_LENGTH characters and must not contain a colon.

List and info

server-tools user list
server-tools user info --username exampledev

list shows username, domain and shell of all domain users. info shows username, domain, UID, home, shell, the comment, the number of keys in authorized_keys and whether html belongs to the user and carries a www-data ACL.

Delete a user

server-tools user delete --username exampledev

The account must have a home under /var/www/. After the prompt this happens:

1. The ACLs are removed and html is given back to www-data recursively. The user ACL on logs is removed.
2. The directory /var/www/<domain>/.ssh is deleted along with all keys.
3. All processes of the user are terminated (SIGTERM, SIGKILL after one second, at most five more seconds of waiting).
4. userdel without -r.

Files in html are kept. Only after that can the VHost of the domain be deleted with vhost delete.

Next

• Virtual hosts
• Security and safeguards