HOMECTL(1)

📦
version 261.3 · 13 versions
, in ubuntu stonking

✨ NAME ✨

Bestie, welcome to homectl — the manual page for homectl and systemd-homed-firstboot.service. What does it do? It creates, removes, changes, or inspects home directories. That's the whole vibe. 💅

🎀 SYNOPSIS 🎀

homectl [OPTIONS...] {COMMAND} [NAME...]

🌸 DESCRIPTION 🌸

Okay so, homectl is your girl for creating, removing, changing, or inspecting a user's home directory. It's basically a command-line bestie that talks to systemd-homed.service(8), the thing that actually manages home directories of users.

Here's the iconic part: home directories managed by systemd-homed.service are self-contained. Like, the user's full metadata record lives inside the home's own data storage. So migrating between machines? A breeze, no cap. In particular, a home directory describes a matching user record, and every user record managed by systemd-homed.service also implies the existence and encapsulation of a home directory. The user account and home directory literally become the same concept. Main character energy — they're one entity. 👑

These are the backing storage mechanisms that are supported, bestie:

  • An individual LUKS2 encrypted loopback file for each user, stored in /home/*.home. At login the filesystem inside this file gets mounted, after the LUKS2 encrypted volume has been attached. The user's password is identical to the encryption passphrase of the LUKS2 volume. So access to data without prior user authentication? Literally impossible, even for the system administrator. This mechanism provides the strongest data security and is therefore the recommended one. Periodt. 🔥
  • Similar, but the LUKS2 encrypted filesystem lives on a regular block device, like a USB storage stick. In this mode, home directories and all the data they include are nicely migratable between machines — you just plug the USB stick into different systems at different times. It's giving ✨portable✨.
  • An encrypted directory using "fscrypt" on filesystems that support it (at the moment this is primarily "ext4"), located in /home/*.homedir. This mechanism also provides encryption, but substantially weaker than LUKS2, because most filesystem metadata is unprotected. Also, it currently does not support changing user passwords once the home directory has been created. Yeah. 😭
  • A "btrfs" subvolume for each user, also located in /home/*.homedir. Provides no encryption, but good quota support. Ngl, quota game strong.
  • A regular directory for each user, also located in /home/*.homedir. No encryption, but it's a suitable fallback available on all machines — even where LUKS2, "fscrypt" or "btrfs" support isn't available. The reliable friend of the group. 🫶
  • An individual Windows file share (CIFS) for each user.
Heads up, bestie: systemd-homed.service and homectl will not manage "classic" UNIX user accounts as created with useradd(8) or similar tools. In particular, this functionality isn't suitable for managing system users (i.e. users with a UID below 1000) — it's exclusive to regular ("human") users. 💀

Also a lil note: users/home directories managed via systemd-homed.service don't show up in /etc/passwd and similar files. They're synthesized via glibc NSS during runtime. So they're still resolvable and can be enumerated via the getent(1) tool. Slay. ✨

This tool interfaces directly with systemd-homed.service, and it may execute specific commands on the home directories it manages. And since every home directory managed that way also defines a JSON user and group record, these home directories can also be inspected and enumerated via userdbctl(1). iykyk. 🌈

Home directories managed by systemd-homed.service are usually in one of two states, or in a transition state between them:

  • "active" — they're unlocked and mounted, and thus accessible to the system and its programs. She's out and about! 💃
  • "inactive" — they're not mounted and thus not accessible. She's resting. 😴

Activation happens automatically at login of the user, and usually can only complete after a password (or other authentication token) has been supplied. Deactivation happens after the user fully logged out. A home directory remains active as long as the user is logged in at least once, i.e. has at least one login session. When the user logs in a second time simultaneously, the home directory remains active. It is deactivated only after the last of the user's sessions ends. Fr fr, that's how it works. 🌸

✨ OPTIONS ✨

okay bestie, welcome to the general option menu 💅 these are the options homectl understands globally, and there are also further options that control the various properties of user records managed by systemd-homed.service — those are documented further down, don't worry.

  • --identity=FILE — read the user's JSON record from the file you point at. If you pass it as -, it reads the user record from standard input instead. the JSON object you feed in must follow the structure documented in JSON User Records[1]. This option can be used with the create and update commands (see below), where it lets you configure the user record in JSON as-is instead of setting the individual user record properties one by one (see below). Added in version 245.
  • --json=FORMAT, -j — controls whether to output the user record in JSON format, if the inspect command (see below) is used. Takes one of "pretty", "short" or "off". If "pretty" is picked, human-friendly whitespace and newlines are inserted in the output to make the JSON data more readable. If "short", all superfluous whitespace is suppressed. If "off" — the default — the user information is not shown in JSON format but in a friendly human-readable formatting instead. The -j option picks "pretty" when run interactively and "short" otherwise. Added in version 245.
  • --export-format=FORMAT, -E, -EE — when used with the inspect verb in JSON mode (see above), this may be used to suppress certain aspects of the JSON user record on output. Specifically, if "stripped" format is used, the binding and runtime fields of the record are removed. If "minimal" format is used, the cryptographic signature is removed too. If "full" format is used, the full JSON record is shown (this is the default). This option is useful for copying an existing user record to a different system in order to create a similar user there with the same settings. Specifically: homectl inspect -EE | ssh root@othersystem homectl create -i- may be used as a simple command line for replicating a user on another host. -E is equivalent to -j --export-format=stripped, and -EE to -j --export-format=minimal. Note that when replicating user accounts, user records acquired in "stripped" mode will retain the original cryptographic signatures and thus may only be modified when the private key to update them is available on the destination machine. When replicating users in "minimal" mode, the signature is removed during the replication and thus the record will be implicitly signed with the key of the destination machine and may be updated there without any private key replication. Added in version 245.
  • --offline — do not attempt to update the copy of the user record and blob directory that is embedded inside of the home area. This allows for operation on home areas that are absent, or without needing to authenticate as the user being modified. Added in version 256.
  • --key-name= — when used with the add-signing-key command, specify or override the name under which to store the public key being added. The specified name can be chosen freely, but must be suffixed with .public. If this option is not used, the name is derived from the specified filename. If a key is read from standard input, this option is mandatory in order to provide a suitable name for the key being added. Added in version 258.
  • --seize= — takes a boolean argument. When used with create or register, controls whether to strip cryptographic signatures from the provided JSON user records, which has the effect of signing them with the local signing key (local.public) instead. If this switch is set to true, added user records hence become locally managed (and thus can be modified locally), while if it is set to false the user records remain managed and owned by its origin (and thus cannot be modified locally). This switch defaults to true for create and false for register. Added in version 258.
  • --prompt-new-user — if used in conjunction with firstboot and no regular user account exists on the system so far, the tool will interactively query for user information and create an account. Added in version 256.
  • --prompt-shell= — takes a boolean argument. Controls whether to interactively query for a login shell, if firstboot --prompt-new-user is used. Defaults to true. Added in version 259.
  • --prompt-groups= — takes a boolean argument. Controls whether to interactively query for auxiliary groups to add the new user to, if firstboot --prompt-new-user is used. Defaults to true. Added in version 259.
  • --chrome= — takes a boolean argument. By default the interactive user creation via firstboot --prompt-new-user screen will show reverse color "chrome" bars at the top and the bottom of the terminal screen, which may be disabled by setting this option to false. Added in version 259.
  • --mute-console= — takes a boolean argument. If true, kernel log output and service manager status output to the system console is temporarily disabled while firstboot --prompt-new-user is running, so that its own output is not interrupted. Defaults to false. Added in version 259.
  • --match=this|other|any|auto, -A, -N, -T — option --match= takes one of "this", "other", "any" or "auto". Some user record settings can be defined to match only specific machines, or all machines but one, or all machines. With this switch it's possible to control to which machines to apply the settings appearing on the command line after it. If "this" is specified, the setting will only apply to the local system (positive match); if "other", it will apply to all but the local system (negative match); if "any", it will apply to all systems (unless there's a matching positive or negative per-machine setting). If "auto" is used, it returns to the default logic: whether a setting applies by default to the local system or all systems depends on the option in question. Note that only some user record settings can be conditioned like this. This option has no effect on the others and is ignored there. This option may appear multiple times in a single command line to apply settings conditioned by different matches to the same user record. See JSON User Records[1] for details on which settings may be used with such per-machine matching and which ones may not. -A is a shortcut for --match=any, -T is short for --match=this and -N is short for --match=other. Here's an example call that sets the storage field to "luks" on the local system, but to "cifs" on all others:
# homectl update lennart -T --storage=luks -N --storage=cifs

Added in version 258.

  • -H, --host= — execute the operation remotely. Specify a hostname, or a username and hostname separated by @, to connect to. The hostname may optionally be suffixed by a port ssh is listening on, separated by :, and then a container name, separated by /, which connects directly to a specific container on the specified host. This will use SSH to talk to the remote machine manager instance. Container names may be enumerated with machinectl -H HOST. Put IPv6 addresses in brackets.
  • -M, --machine= — execute operation on a local container. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating @ character. If the special string .host is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user's user bus: "--user --machine=lennart@.host"). If the @ syntax is not used, the connection is made as root user. If the @ syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and .host are implied.
  • --no-pager — do not pipe output into a pager.
  • --no-legend — do not print the legend, i.e. column headers and the footer with hints.
  • --no-ask-password — do not query the user for authentication for privileged operations.
  • -h, --help — print a short help text and exit.
  • --version — print a short version string and exit.

✨ GENERAL USER RECORD PROPERTIES ✨

Okay bestie, this next batch of options is all about the vibes of a user record — like, the actual personality of the home directory and the account that systemd-homed.service is out here managing. 🫶 These switches get to hang out with the create and update commands, and they're how you configure all the little aspects of the home directory and the user account. Let's go, one by one 💅

  • --real-name=NAME, -c NAME — the actual human name for the user, the one that goes in the GECOS field on classic UNIX NSS records. Yes, that field. Iconic behavior. ✨

Added in version 245.

  • --realm=REALM — sets the realm for the user. A realm ties a user to a specific organization or installation, so you can tell apart users with the same name living in different contexts. The realm can be literally any string that also passes as a valid DNS domain name, and yeah, it's recommended to use your org's or installation's domain name for it — but that's not enforced, nor required, no cap. On each system only a single user of the same name may exist: if a user with the same name and realm shows up, it's assumed to be the same user; same name but different realm = a different user. And heads up, that means two users sharing a name but with distinct realms are not allowed on the same system. Assigning a realm is optional, btw. 🦋

Added in version 245.

  • --alias=NAME[,NAME...] — extra names for the user. Takes one or more valid UNIX user names, separated by commas. You can use this multiple times to define multiple aliases. Any alias username can be used anywhere the primary user name works, and it resolves to the same user record. Slay, one user, many hats 👑

Added in version 258.

  • --email-address=EMAIL — hands over an electronic mail address to associate with the user. On log-in, the $EMAIL environment variable gets initialized from this value. Cute and functional 💌

Added in version 245.

  • --location=TEXT — a location spec for the user. It's free-form text, so it might or might not be usable by geo-location apps — your mileage may vary, fr fr. Examples: --location="Berlin, Germany" or --location="Basement, Room 3a" 🗺️

Added in version 245.

  • --birth-date=[DATE] — takes a birth date for the user in ISO 8601 calendar date format ("YYYY-MM-DD"). The earliest representable year is 1900. And if you pass an empty string, the birth date gets reset to unset. 🎂

Added in version 261.

  • --icon-name=ICON — an icon name to associate with the user, following the scheme defined by the Icon Naming Specification[2]. Give the people a face 🎀

Added in version 245.

  • --home-dir=PATH, -dPATH — takes a path to use as the home directory for the user. Real talk though: this is the directory the user's home directory gets mounted to while the user is logged in. It is not where the user's data is actually stored — for that, see --image-path=. If you don't specify it, it defaults to /home/$USER. 🏠

Added in version 245.

  • --uid=UID — takes a preferred numeric UNIX UID to assign this user. If a user is gonna be created with the specified UID and that UID is already taken by a different user on the local system, then creation of the home directory is refused, periodt. But note: if, after creating the home directory, it gets used on a different system and the configured UID is taken by another user there, then systemd-homed may assign the user a different UID on that system. The specified UID must be outside of the system user range — it's recommended to use the 60001...60513 UID range for this purpose. If you don't specify one, the UID is automatically picked. And if the home directory turns out to be owned by a different UID when logging in, the home directory and everything underneath it will have its ownership changed automatically before login completes. 😤
Note that changing this option for existing home directories generally has no effect on home directories that already have been registered locally (have a local binding), because the UID used for an account on the local system is determined when the home directory is first activated on it, and then it remains in effect until the home directory is removed. So like… it's locked in, bestie. 💀

Also note: users managed by systemd-homed always have a matching group with the same name as well as a GID matching the UID of the user. So configuring the GID separately is not permitted — them's the rules. 🚫

Added in version 245.

  • --member-of=GROUP, -G GROUP — takes a comma-separated list of auxiliary UNIX groups this user shall belong to. Example: --member-of=wheel to give the user administrator privileges. Note that systemd-homed doesn't manage any groups besides a group matching the user in name and numeric UID/GID — so any groups you list here must be registered independently, for example with groupadd(8). Any non-existent groups are just ignored. This option may be used more than once, and all the specified group lists get combined. Oh, and if the user is currently a member of a group which isn't listed… the user gets removed from the group. Sorry babe, it's a full sync 🫡

Added in version 245.

  • --capability-bounding-set=CAPABILITIES, --capability-ambient-set=CAPABILITIES — these take a space-separated list of process capabilities (e.g. CAP_WAKE_ALARM, CAP_BLOCK_SUSPEND, ...) that shall be set in the capability bounding and ambient sets for all the user's sessions. See capabilities(7) for the whole capabilities concept, iykyk. These options may be used more than once, in which case the specified lists are combined. And if the parameter begins with a "~" character, the effect is inverted: the specified capability is dropped from that specific set. Reverse uno card 🔥

Added in version 254.

  • --access-mode=MODE — takes a UNIX file access mode written in octal. Configures the access mode of the home directory itself. Note that this is only used when the directory is first created — the user can change this any time afterwards. Example: --access-mode=0700 🔐

Added in version 245.

  • --umask=MASK — takes the access mode mask (in octal syntax) to apply to newly created files and directories of the user (the "umask"). If set, this controls the initial umask set for all login sessions of the user, possibly overriding the system's defaults. Set it and forget it ✨

Added in version 245.

  • --skel=PATH — takes a file system path to a directory. Specifies the skeleton directory to initialize the home directory with. All files and directories in the specified path get copied into any newly created home directory. If not specified, it defaults to /etc/skel/. 🧚

Added in version 245.

  • --shell=SHELL — takes a file system path. Specifies the shell binary to execute on terminal logins. If not specified, it defaults to /bin/bash. 🐚

Added in version 245.

  • --setenv=VARIABLE[=VALUE] — takes an environment variable assignment to set for all user processes. May be used multiple times to set multiple environment variables. When "=" and VALUE are omitted, the value of the variable with the same name in the program environment gets used instead. Neat 🌸
Note that a number of other settings also result in environment variables being set for the user, including --email=, --timezone= and --language=. So like, don't be surprised, it's giving teamwork 💖

Added in version 245.

  • --timezone=TIMEZONE — takes a time zone location name that sets the timezone for the specified user. When the user logs in, the $TZ environment variable is initialized from this setting. Example: --timezone=Europe/Amsterdam will result in the environment variable "TZ=:Europe/Amsterdam". (That ":" is used intentionally as part of the timezone specification, see tzset(3).) ⏰

Added in version 245.

  • --language=LANG — takes a comma- or colon-separated list of languages preferred by the user, ordered by descending priority. The $LANG and $LANGUAGE environment variables get initialized from this value on login, and thus values suitable for these environment variables are accepted here — for example --language=de_DE.UTF-8. This option may be used more than once, in which case the language lists are concatenated. Multilingual queen 🌈

Added in version 245.

  • --default-area=AREA — takes a string identifying a home directory "area" to use as default. So, areas are secondary home directories within the primary home directory of a user. When logging in, a user can specify the area they wish to log into, which ensures that the $HOME environment variable is set to ~/Areas/ suffixed by the area name. 🗂️

For the details on the whole area concept, see pam_systemd_home(8). And note that this option just defines the default — it can be overridden at login time.

When this option is specified with an empty string as value, any previously declared default area gets removed from the user record. Poof, gone 💨

Added in version 258.

✨ AUTHENTICATION USER RECORD PROPERTIES ✨

okay bestie, this whole cluster is about how you prove you're you — keys, tokens, all that 🎀

  • --ssh-authorized-keys=KEYS — takes either one SSH authorized key line to hand to the user record, or a @ character followed by a path to a file that has one or more such lines in it. Keys you set up this way get made available to SSH so it can let people into this home directory and user record. You can use this option more than once if you've got multiple keys to configure 💅

Added in version 245.

  • --pkcs11-token-uri=URI — takes an RFC 7512 PKCS#11 URI that points at a security token (think YubiKey or PIV smartcard) that should be able to unlock the user account. The security token URI should reference a token with exactly one pair of X.509 certificate and private key. A random secret key gets generated, encrypted with the public key of the X.509 certificate, and stored as part of the user record. Then at login time it gets decrypted with the PKCS#11 module and used to unlock the account and all the associated resources. There's an example below for setting up authentication with a security token, iykyk 🔥

Instead of a real PKCS#11 URI you can pass the special strings "list" and "auto". If you pass "list", you get a brief table of suitable, currently plugged-in PKCS#11 hardware tokens with their URIs. If you pass "auto", a suitable PKCS#11 hardware token gets picked automatically (and this will fail if there isn't exactly one suitable token discovered). "auto" is the shortcut for the most common case: one single PKCS#11 hardware token is plugged in, done ✨

Note that many hardware security tokens implement both PKCS#11/PIV and FIDO2 with the "hmac-secret" extension (the YubiKey 5 series, for example), as supported with the --fido2-device= option below. Both mechanisms are similarly powerful, though FIDO2 is the more modern technology. PKCS#11/PIV tokens have the benefit of being recognizable before authentication and hence can be used for implying the user identity to use for logging in, which FIDO2 does not allow. PKCS#11/PIV devices generally require initialization (i.e. storing a private/public key pair on them, see example below) before they can be used; FIDO2 security tokens generally don't require that, and work out of the box 💖

Added in version 245.

  • --fido2-credential-algorithm=STRING — specifies the COSE algorithm used in credential generation. The default value is "es256". Supported values are "es256", "rs256" and "eddsa".

"es256" denotes ECDSA over NIST P-256 with SHA-256. "rs256" denotes 2048-bit RSA with PKCS#1.5 padding and SHA-256. "eddsa" denotes EDDSA over Curve25519 with SHA-512.

Note that your authenticator may choose not to support some algorithms 🫶

Added in version 251.

  • --fido2-device=PATH — takes a path to a Linux "hidraw" device (e.g. /dev/hidraw1), referring to a FIDO2 security token implementing the "hmac-secret" extension that should be able to unlock the user account. A random salt value gets generated on the host and passed to the FIDO2 device, which calculates a HMAC hash of the salt using an internal secret key. That result is then used as the key to unlock the user account. The random salt is included in the user record, so whenever authentication is needed it can be passed to the FIDO2 token again 💫

Instead of a valid path to a FIDO2 "hidraw" device you can pass the special strings "list" and "auto". If you pass "list", you get a brief table of suitable discovered FIDO2 devices. If you pass "auto", a suitable FIDO2 token gets selected automatically, if exactly one is discovered. "auto" is the shortcut for the most common case where a single FIDO2 hardware token is plugged in 👑

Note that FIDO2 devices suitable for this option must implement the "hmac-secret" extension. Most current devices (like the YubiKey 5 series) do. If the extension isn't implemented, the device can't be used for unlocking home directories, periodt.

The FIDO2 device may be subsequently removed by setting the device path to an empty string (e.g. homectl update $USER --fido2-device="").

Note that many hardware security tokens implement both FIDO2 and PKCS#11/PIV (so they can be used with either --fido2-device= or --pkcs11-token-uri=), for a discussion see above 🦋

Added in version 246.

  • --fido2-with-client-pin=BOOL — when enrolling a FIDO2 security token, this controls whether to require the user to enter a PIN when unlocking the account (the FIDO2 "clientPin" feature). Defaults to "yes". (Note: this setting is without effect if the security token doesn't support the "clientPin" feature at all, or doesn't allow enabling or disabling it.) 🎀

Added in version 249.

  • --fido2-with-user-presence=BOOL — when enrolling a FIDO2 security token, this controls whether to require the user to verify presence (tap the token, the FIDO2 "up" feature) when unlocking the account. Defaults to "yes". (Note: this setting is without effect if the security token doesn't support the "up" feature at all, or doesn't allow enabling or disabling it.) 🫶

Added in version 249.

  • --fido2-with-user-verification=BOOL — when enrolling a FIDO2 security token, this controls whether to require user verification when unlocking the account (the FIDO2 "uv" feature). Defaults to "no". (Note: this setting is without effect if the security token doesn't support the "uv" feature at all, or doesn't allow enabling or disabling it.) 🌸

Added in version 249.

  • --recovery-key=BOOL — accepts a boolean argument. If enabled, a recovery key is configured for the account. A recovery key is a computer generated access key that may be used to regain access to an account if the password has been forgotten or the authentication token lost. The key is generated and shown on screen, and should be printed or otherwise transferred to a secure location. A recovery key may be entered instead of a regular password to unlock the account 💖
bestie please actually write it down and put it somewhere safe, this is your "not me locked out of my whole account 😭" insurance policy

Added in version 247.

🎀 BLOB DIRECTORY USER RECORD PROPERTIES 🎀

this is the part where you shove files into a user's blob directory. yes, that's really what it's called, no cap 💀

  • --blob=PATH, -b PATH, --blob=FILENAME=PATH, -b FILENAME=PATH — accepts either a directory path, or a file name followed by a file path. If you just specify a directory path, then the user's entire blob directory is replaced with the specified path. Note that this replacement is performed before per-file manipulations are applied, which means those per-file manipulations get applied on top of the specified directory. If you specify a filename and file path, then that single specified blob file gets overwritten with the specified path. If it's completely blank, the entire blob directory is emptied out (which also resets all previous blob-related flags up to this point). If a filename is specified but the corresponding path is blank, that single file gets deleted from the blob directory. All changes are performed in temporary copies of the specified files in directories, which means the originals you specified on the command line are not modified 🦋 See User Record Blob Directories[3] for more info about blob directories.

Added in version 256.

  • --avatar=PATH, --login-background=PATH — accept a file path. If set, the specified file is used to overwrite the corresponding file in the user's blob directory. If blank, the corresponding file gets deleted from the blob directory. Essentially, these options are shortcuts to --blob=FILENAME=PATH for the known filenames defined in User Record Blob Directories[3] ✨
you literally get a profile pic and a login background, it's giving main character energy 👑

Added in version 256.

🌸 ACCOUNT MANAGEMENT USER RECORD PROPERTIES 🌸

okay so this whole cluster is the account-vibe section: locking, login windows, rate limits, password hints, and password-expiry rules. it’s giving “who gets in and when,” and every knob here is literally real, so keep the values exact, bestie. 💅

  • --locked=BOOLEAN — takes a boolean argument. true means this user account is locked and logins are prohibited; false (the default) means logins are permitted — but of course only if authorization otherwise succeeds. ✨ Added in version 245.
  • --not-before=TIMESTAMP, --not-after=TIMESTAMP — these take a timestamp string in the format documented in systemd.time(7). They set the points in time before and after which logins into this account are not permitted. ✨ Added in version 245.
  • --rate-limit-interval=SECS, --rate-limit-burst=NUMBER — configures a rate limit on authentication attempts for this user. If the user tries to authenticate more often than the specified number, on a specific system, within the specified time interval, authentication is refused until the time interval passes. Defaults to 10 times per 1min. ✨ Added in version 245.
  • --password-hint=TEXT — takes a password hint to store alongside the user record. This string is stored accessible only to privileged users and the user itself, and may not be queried by other users. Example: --password-hint="My first pet's name". ✨ Added in version 245.
  • --enforce-password-policy=BOOL, -P — takes a boolean argument. Configures whether to enforce the system's password policy for this user, regarding quality and strength of selected passwords. Defaults to on. -P is short for --enforce-password-policy=no. ✨ Added in version 245.
  • --password-change-now=BOOL — takes a boolean argument. If true, the user is asked to change their password on next login. ✨ Added in version 245.
  • --password-change-min=TIME, --password-change-max=TIME, --password-change-warn=TIME, --password-change-inactive=TIME — each one takes a time span specification as argument (in the syntax documented in systemd.time(7)) and configures various aspects of the user's password expiration policy. Specifically:
    • --password-change-min= sets how much time has to pass after changing the user's password until it may be changed again. If the user tries to change it before this time passes, the attempt is refused.
    • --password-change-max= sets how soon after it has been changed the password expires and needs to be changed again. After this time passes, logging in may only proceed after the password is changed.
    • --password-change-warn= sets how much earlier than the time configured with --password-change-max= the user is warned at login to change their password because it will expire soon.
    • --password-change-inactive= sets the time which has to pass after the password has expired until the user is not permitted to log in or change the password anymore.

Note that these options only apply to password authentication, and do not apply to other forms of authentication, for example PKCS#11-based security token authentication. ✨ Added in version 245.

🦋 RESOURCE MANAGEMENT USER RECORD PROPERTIES 🦋

next up: resource management, aka the “how much machine can this user eat” section. disk, nice, rlimits, tasks, memory, CPU/IO weights — all the allocation vibes. 🍓

  • --disk-size=BYTES — either takes a size in bytes as argument (possibly using the usual K, M, G, ... suffixes for 1024 base values), a percentage value, or the special strings "min" or "max", and configures the disk space to assign to the user. If a percentage value is specified (i.e. the argument suffixed with %) it is taken relative to the available disk space of the backing file system. If specified as "min" it assigns the minimal disk space permitted by the constraints of the backing file system and other limits; when specified as "max" it assigns the maximum disk space available. If the LUKS2 backend is used, this configures the size of the loopback file and file system contained therein. For the other storage backends it configures disk quota using the filesystem's native quota logic, if available. If not specified, defaults to 85% of the available disk space for the LUKS2 backend and to no quota for the others. ✨ Added in version 245.
  • --nice=NICE — takes the numeric scheduling priority ("nice level") to apply to the processes of the user at login time. Takes a numeric value in the range -20 (highest priority) to 19 (lowest priority). ✨ Added in version 245.
  • --rlimit=LIMIT=VALUE[:VALUE] — allows configuration of resource limits for processes of this user; see getrlimit(2) for details. Takes a resource limit name (e.g. LIMIT_NOFILE) followed by an equal sign, followed by a numeric limit. Optionally, separated by colon, a second numeric limit may be specified. If two are specified, this refers to the soft and hard limits, respectively. If only one limit is specified, the setting sets both limits in one. ✨ Added in version 245.
  • --tasks-max=TASKS — takes a non-zero unsigned integer as argument. Configures the maximum number of tasks (i.e. threads, where each process is at least one thread) the user may have at any given time. This limit applies to all tasks forked off the user's sessions, even if they change user identity via su(1) or a similar tool. Use --rlimit=LIMIT_NPROC= to place a limit on the tasks actually running under the UID of the user, thus excluding any child processes that might have changed user identity. This controls the TasksMax= setting of the per-user systemd slice unit user-$UID.slice. See systemd.resource-control(5) for further details. ✨ Added in version 245.
  • --memory-high=BYTES, --memory-max=BYTES — set a limit on the memory a user may take up on a system at any given time in bytes (the usual K, M, G, ... suffixes are supported, to the base of 1024). This includes all memory used by the user itself and all processes they forked off that changed user credentials. This controls the MemoryHigh= and MemoryMax= settings of the per-user systemd slice unit user-$UID.slice. See systemd.resource-control(5) for further details. ✨ Added in version 245.
  • --cpu-weight=WEIGHT, --io-weight=WEIGHT — set CPU and IO scheduling weights of the processes of the user, including those of processes forked off by the user that changed user credentials. Takes a numeric value in the range 1...10000. This controls the CPUWeight= and IOWeight= settings of the per-user systemd slice unit user-$UID.slice. See systemd.resource-control(5) for further details. ✨ Added in version 245.

🎀 STORAGE USER RECORD PROPERTIES 🎀

storage section, bestie: where the home directory actually lives, what backs it, and the tmp/shm quota situation. 🫶

  • --tmp-limit=BYTES, --tmp-limit=PERCENT, --dev-shm-limit=BYTES, --dev-shm-limit=PERCENT — controls the per-user quota on /tmp/ and /dev/shm/ that is applied when the user logs in. Takes either an absolute value in bytes (with the usual K, M, G, T suffixes to the base of 1024), or a percentage. In the latter case the limit is applied relative to the size of the respective file system. This limit is only applied if the relevant file system is "tmpfs" and has no effect otherwise. Note that if these options are not used, a default quota might still be enforced (typically 80%.) ✨ Added in version 258.
  • --storage=STORAGE — selects the storage mechanism to use for this home directory. Takes one of "luks", "fscrypt", "directory", "subvolume", "cifs". For details about these mechanisms, see above. If a new home directory is created and the storage type is not specifically specified, homed.conf(5) defines which default storage to use. ✨ Added in version 245.
  • --image-path=PATH — takes a file system path. Configures where to place the user's home directory. When LUKS2 storage is used it refers to the path to the loopback file; otherwise it refers to the path to the home directory (which may be in /home/ or any other accessible filesystem). When unspecified it defaults to /home/$USER.home when LUKS storage is used and /home/$USER.homedir for the other storage mechanisms. Not defined for the "cifs" storage mechanism. To use LUKS2 storage on a regular block device (for example a USB stick), pass the path to the block device here. Specifying the path to a directory here when using LUKS2 storage is not allowed. Similar, specifying the path to a regular file or device node is not allowed if any of the other storage backends are used. ✨ Added in version 245.
  • --drop-caches=BOOL — automatically flush OS file system caches on logout. This is useful in combination with the fscrypt storage backend to ensure the OS does not keep decrypted versions of the files and directories in memory (and accessible) after logout. This option is also supported on other backends, but should not bring any benefit there. Defaults to off, except if the selected storage backend is fscrypt, where it defaults to on. Note that flushing OS caches will negatively influence performance of the OS shortly after logout. ✨ Added in version 250.

🔐 LUKS STORAGE USER RECORD PROPERTIES 🔐

  • --fs-type=TYPE — okay so when you're rolling with LUKS2 storage, this picks which file system type lives inside your home directory's LUKS2 container. Your options are literally just "btrfs", "ext4", "xfs". Don't specify it and homed.conf(5) decides the default for you. Fr though, "xfs" is not recommended — its file system resizing support is just way too limited, no cap.

Added in version 245.

  • --luks-discard=BOOL — with LUKS2 storage this toggles the "discard" feature of the file system. Turn it on and the fs sitting on top of the LUKS2 volume reports its empty block info down to LUKS2 and the loopback file below it, so empty space in your home dir gets handed back to the backing file system underneath the LUKS2 volume — which gives you a "sparse" loopback file. 💅 This one mostly defaults to off, and here's why: it lets you over-commit home directories, which means I/O errors if the underlying file system runs full while the upper file system is trying to allocate a block. And bestie, those I/O errors are generally not handled well by file systems nor applications. 😭 When LUKS2 storage sits on top of regular block devices (instead of on top of a loopback file), the discard logic defaults to on.

Added in version 245.

  • --luks-offline-discard=BOOL — basically the sibling of --luks-discard=, also controlling trimming of the file system. The difference is when: --luks-discard= is about what happens while the home directory is active, whereas --luks-offline-discard= is about what happens when it becomes inactive — i.e. whether to trim/allocate the storage when deactivating the home directory. Defaults to on, so disk space stays minimized while a user isn't logged in. Iconic behavior honestly.

Added in version 246.

  • --luks-extra-mount-options=OPTIONS — takes a string of extra mount options to use when mounting the LUKS volume. Specify it and this string gets appended to the default, built-in mount options. Defaults to "compress=zstd:1,noacl,user_subvol_rm_allowed".

Added in version 250.

  • --luks-cipher=CIPHER, --luks-cipher-mode=MODE, --luks-volume-key-size=BYTES, --luks-pbkdf-type=TYPE, --luks-pbkdf-hash-algorithm=ALGORITHM, --luks-pbkdf-force-iterations=ITERATIONS, --luks-pbkdf-time-cost=SECONDS, --luks-pbkdf-memory-cost=BYTES, --luks-pbkdf-parallel-threads=THREADS, --luks-sector-size=BYTES — all the cryptographic parameter knobs for the LUKS2 storage mechanism. Peep cryptsetup(8) for the tea on what each specific attribute actually does. 🧚
Heads up bestie: homectl uses bytes for key size, like /proc/crypto, but cryptsetup(8) uses bits. Don't mix those up or it's giving chaos.

Added in version 245.

  • --auto-resize-mode= — configures whether to automatically grow and/or shrink the backing file system on login and logout. Takes one of the strings "off", "grow", "shrink-and-grow". Right now it only applies to the LUKS2 backend, and only if the btrfs file system is used inside it (since that's the only way online growing/shrinking of the file system is supported). Defaults to "shrink-and-grow" if LUKS2/btrfs is in play, otherwise it's off. Setting it to "off" means no automatic shrinking/growing happens during login or logout, periodt. Set it to "grow" and the home area gets grown to the size configured via --disk-size= — but only should it currently be smaller. If it already matches the configured size or is larger, no operation is executed. Set it to "shrink-and-grow" and the home area also gets resized during logout down to the minimal size that the used disk space and file system constraints permit. So this mode ensures that while a home area is activated it's sized to the configured size, but while deactivated it's compacted, taking up only the minimal space possible. ✨ One thing though: if the system is powered off abnormally, or the user otherwise isn't logged out cleanly, the shrinking operation will not take place — the user has to re-login/logout again before it's executed again. 🙈

Added in version 250.

  • --rebalance-weight= — sets the weight parameter for the free disk space rebalancing logic. Only applies to the LUKS2 backend (since for LUKS2, disk space is allocated from a per-user loopback file system instead of immediately from a common pool like the other backends do it). At regular intervals, free disk space in the active home areas and their backing storage gets redistributed among them, taking the weight value configured here into account. Expects an integer in the range 1...10000, or the special string "off". If not specified, defaults to 100. The weight scales the free space handed to home areas: a home area with a weight of 200 gets twice the free space as one with a weight of 100; a home area with a weight of 50 gets half of that. And the backing file system gets assigned space for a weight of 20. If set to "off", no automatic free space distribution happens for this home area. 🌸 Note that resizing the home area explicitly (with homectl resize, see below) will implicitly turn off the automatic rebalancing. To reenable the automatic rebalancing, use --rebalance-weight= with an empty parameter.

Added in version 250.

📂 MOUNTING USER RECORD PROPERTIES 📂

  • --nosuid=BOOL, --nodev=BOOL, --noexec=BOOL — configures the "nosuid", "nodev" and "noexec" mount options for the home directories. Out the box, "nodev" and "nosuid" are on, while "noexec" is off. For the deets on what these mount options actually do, see mount(8). 🫶

Added in version 245.

🪟 CIFS USER RECORD PROPERTIES 🪟

  • --cifs-domain=DOMAIN, --cifs-user-name=USER, --cifs-service=SERVICE, --cifs-extra-mount-options=OPTIONS — configures the Windows File Sharing (CIFS) domain and user to associate with the home directory/user account, plus the file share ("service") to mount as the directory. That last one is used when "cifs" storage is selected. The file share should be specified in the format "//host/share/directory/...". The directory part is optional — if you don't specify it, the home directory gets placed in the top-level directory of the share. The --cifs-extra-mount-options= setting lets you specify additional mount options when mounting the share; see mount.cifs(8) for details. 💖

Added in version 245.

🚪 LOGIN BEHAVIOUR RECORD PROPERTIES 🚪

  • --stop-delay=SECS — configures the time the per-user service manager shall continue to run after all sessions of the user ended. The default is configured in logind.conf(5) (though for home directories of LUKS2 storage located on removable media this defaults to 0). A longer time makes sure quick, repetitive logins are more efficient, since the user's service manager doesn't have to be started every single time. Efficiency slay.

Added in version 245.

  • --kill-processes=BOOL — configures whether to kill all processes of the user on logout. The default is configured in logind.conf(5).

Added in version 245.

  • --auto-login=BOOL — takes a boolean argument. Configures whether the graphical UI of the system should automatically log this user in if possible. Defaults to off. And if less or more than one user is marked this way, automatic login is disabled entirely. 👑

Added in version 245.

  • --session-launcher=LAUNCHER — takes a string argument. Configures the user's preferred session launcher .desktop entry file (i.e. "gnome", "plasma", or other names that appear in /usr/share/xesssions/ or /usr/share/wayland-sessions). This is read by the display manager to pick the default session that gets launched when the user logs in.

Added in version 256.

  • --session-type=TYPE — takes a string argument. Configures the user's preferred session type (i.e. "x11", "wayland", and other values accepted by $XDG_SESSION_TYPE). This is read by the display manager to pick the default session type the user is logged into.

Added in version 256.

💫 COMMANDS 💫

The following commands are understood:

  • list — lists all home directories (along with brief details) currently managed by systemd-homed.service. This command also runs if none is specified on the command line. (Note that the list of users shown by this command does not include users managed by other subsystems, such as system users or any traditional users listed in /etc/passwd.) 📋

Added in version 245.

  • activate USER [USER...] — activates one or more home directories. The home directories of each listed user get activated and made available under their mount points (typically in /home/$USER). Note that any home activated this way stays active indefinitely, until it's explicitly deactivated again (with deactivate, see below), or the user logs in and out again and it thus gets deactivated due to the automatic deactivation-on-logout logic.

Activation of a home directory involves various operations that depend on the selected storage mechanism. If the LUKS2 mechanism is used, this generally involves: inquiring the user for a password, setting up a loopback device, validating and activating the LUKS2 volume, checking the file system, mounting the file system, and potentially changing the ownership of all included files to the correct UID/GID. It's giving a whole ritual, honestly. 🔥

Added in version 245.

  • deactivate USER [USER...] — deactivates one or more home directories. This undoes the effect of activate. Simple as that bestie. 💅

Added in version 245.

  • inspect USER [USER...] — shows various details about the specified home directories. This shows various information about the home directory and its user account, including runtime data such as current state, disk use and similar. Combine with --json= to show the detailed JSON user record instead, possibly combined with --export-format= to suppress certain aspects of the output. 🦋

Added in version 245.

  • authenticate USER [USER...] — validates the authentication credentials of a home directory. This queries the caller for a password (or similar) and checks that it correctly unlocks the home directory. And it leaves the home directory in the state it's in — i.e. it leaves the home directory in inactive state if it was inactive before, and in active state if it was active before. No surprises, no drama. ✨

Added in version 245.

  • create USER, create --identity=PATH [USER] — creates a new home directory/user account of the specified name. Use the various user record property options (as documented above) to control various aspects of the home directory and its user accounts. 🎀

The username you give it has to follow the strict syntax laid out over in User/Group Name Syntax[4] — no chaotic names, bestie. 💅

Added in version 245.

  • adopt PATH [PATH...] — adopts one or more home directories that already exist on your local system. You hand it one or more paths to *.home LUKS home directories, or to *.homedir/ standalone home directories or subvolumes that systemd-homed made earlier, and it makes them locally available for login. Lowkey the best part: the referenced files do not get moved. It's the alternative to shoving those home directories into /home/ (where they'd get picked up automatically anyway). ✨

Added in version 258.

  • register FILE [FILE...] — registers one or more users without creating their home directories. You pass one or more paths to JSON user record files. If the path is -, it reads the JSON user record from standard input. 🫶

Registering a user makes them accessible on the local system without making a new home directory. Genuinely useful for making a user accessible on a system it wasn't originally created on.

Here's the example, and it's giving main character energy — making a local user account with its home directory accessible on a remote system via SMB/CIFS file sharing. With Samba installed in its default configuration, invoke as root:

# smbpasswd -a lennart

Then continue as regular user lennart:

$ homectl update lennart --ssh-authorized-keys=... -N --storage=cifs --cifs-service="//$HOSTNAME/lennart"
$ homectl get-signing-key | ssh targetsystem homectl add-signing-key --key-name="$HOSTNAME".public
$ homectl inspect -E lennart | ssh targetsystem homectl register -
$ ssh lennart@targetsystem

So what's happening here: first it ensures the user account lennart is known to and accessible by Samba. Then it registers a local SSH access that shall be used for accessing this user, and configures CIFS as the default storage for non-local systems on the account. After that it adds the local system's account signing key to the target system. Then it registers the local user account with the target system. Finally it logs into the account on the target system — and the target system will then connect back via SMB/CIFS to access the home directory. Iconic. 👑

Added in version 258.

  • unregister USER... — unregisters one or more user accounts. Important: this only removes the user record from the local system, it does not delete the home directory. You can readd the home directory later via the register or adopt command, on this system or another one. 💖
Heads up: unregistering a user whose home directory sits in /home/ will not make the user disappear from the local user database — all supported home directories placed there show up in the user database. What happens instead is the user record becomes "unfixated", i.e. it loses its binding to the local system. When you log into it, it automatically regains the binding and acquires a local UID/GID pair. 🦋

Added in version 258.

  • remove USER — removes a home directory/user account. This removes both the home directory's user record and the home directory itself — so yes, it deletes all files and directories owned by the user. 😭

Added in version 245.

  • update USER, update --identity=PATH [USER] — updates a home directory/user account. Use the various user record property options (documented above) to change the account, or alternatively hand over a full, updated JSON user record via the --identity= option. ✨

Note that changes to user records that aren't signed by a cryptographic private key available locally are not permitted — unless --identity= is used with a user record that's already correctly signed by a recognized private key.

Added in version 245.

  • passwd USER — changes the password of the specified home directory/user account. 🔑

Added in version 245.

  • resize USER BYTES — changes the disk space assigned to the specified home directory. If the LUKS2 storage mechanism is in use, this automatically resizes the loopback file and the file system contained inside it. 💅
Real talk on the file systems: if ext4 is used inside the LUKS2 volume, you have to deactivate the home directory before shrinking it (meaning the user has to log out). Growing can be done while the home directory is active. If xfs is used inside the LUKS2 volume, the home directory may not be shrunk whatsoever. On all three of ext4, xfs and btrfs the home directory may be grown while the user is logged in, and on the latter also shrunk while the user is logged in. If the subvolume, directory, fscrypt storage mechanisms are used, resizing will change the file system quota. 🫶

The size parameter may make use of the usual suffixes B, K, M, G, T (to the base of 1024). The special strings min and max may be specified in place of a numeric size value, for minimizing or maximizing the disk space assigned to the home area — taking constraints of the file system, disk usage inside the home area and on the backing storage into account. 🌸

Added in version 245.

  • lock USER — temporarily suspends access to the user's home directory and removes any associated cryptographic keys from memory. Any attempts to access the user's home directory will stall until the home directory is unlocked again (i.e. re-authenticated). This is primarily intended for use during system suspend, so the user's data can't be accessed until the user re-authenticates on resume. This operation is only defined for home directories that use the LUKS2 storage mechanism. 🔒

Added in version 245.

  • unlock USER — resumes access to the user's home directory again, undoing the effect of lock above. This requires authentication of the user, because the cryptographic keys needed for access to the home directory have to be reacquired. 🔓

Added in version 245.

  • lock-all — runs the lock command on all suitable home directories at once. This is generally executed on system suspend (i.e. by systemctl suspend and related commands), to make sure all active users' cryptographic keys for accessing their home directories are removed from memory. 💀

Added in version 245.

  • deactivate-all — runs the deactivate command on all active home directories at once. This is generally executed on system shut down (i.e. by systemctl poweroff and related commands), to make sure all active users' home directories are fully deactivated before /home/ and related file systems are unmounted. 🌙

Added in version 247.

  • with USER COMMAND... — activates the specified user's home directory, runs the specified command (under the caller's identity, not the specified user's), and deactivates the home directory afterwards again (unless the user is logged in otherwise). Handy for running privileged backup scripts and such — but it requires authentication with the user's credentials in order to be able to unlock the user's home directory. 🎀

Added in version 245.

  • rebalance — rebalances free disk space between active home areas and the backing storage. See --rebalance-weight= above. This executes no operation unless there's at least one active LUKS2 home area with disk space rebalancing enabled. This operation is synchronous: it only completes once disk space is rebalanced according to the rebalancing weights. Note that rebalancing also takes place automatically in the background at regular intervals. Use this command to synchronously ensure disk space is properly redistributed before kicking off an operation that needs large amounts of disk space. ⚖️

Added in version 250.

  • firstboot — this command is supposed to be invoked during the initial boot of the system. It checks whether any regular home area exists so far, and if not, queries the user interactively on the console for user name and password and creates one (only if --prompt-new-user is specified). Alternatively, if one or more service credentials whose name starts with home.create. are passed to the command (containing a user record in JSON format), those users are automatically created at boot. 🌅

This command is invoked by the systemd-homed-firstboot.service service unit.

Added in version 256.

  • list-signing-keys — shows a list of public keys that home directories can be signed with in order to be allowed for local login. One such key (local.public) is generated automatically for signing locally created home directories, but additional public keys may be registered to accept home directories from other origins too (see add-signing-key below). 🗝️

Added in version 258.

  • get-signing-key [NAME...] — writes the public key identified by the specified name to standard output (in PEM format). If no name is specified it defaults to local.public, i.e. the automatically generated key for locally created home directories. ✨

Added in version 258.

  • add-signing-key [FILE...] — adds public key(s) from the specified PEM key file(s) to the list of keys that home areas have to be signed by in order to be permitted for local login. If a path of - is specified, or if no file is specified at all, the key is read from standard input. The key file name(s) must carry the .public suffix, and the file name(s) will also be used to name the key(s) once added. If a key is added from standard input, the key name must be specified explicitly via --key-name=, see above. 💖

This command is useful for permitting local home directories to be used on a remote system. Example:

homectl get-signing-key | ssh myotherhost homectl add-signing-key --key-name="$HOSTNAME".public

Added in version 258.

  • remove-signing-key NAME... — removes the public key identified by the specified name from the list of keys that control from which origins home directories are permitted for login. 🙈

Added in version 258.

🎀 CREDENTIALS 🎀

When invoked with the firstboot command, homectl supports the service credentials logic as implemented by ImportCredential=, LoadCredential= and SetCredential= (see systemd.exec(5) for the deets). The following credentials are used when passed in:

🌟 home.create.*

If one or more credentials whose names begin with home.create., followed by a valid UNIX username, are passed, a new home area is created — one for each specified user record. 🦋

Added in version 256.

🌸 KERNEL COMMAND LINE 🌸

  • systemd.firstboot= — this boolean straight-up disables the effect of the homectl firstboot command. It's mostly read by systemd-firstboot(1), so that's where the real main-character energy lives.

Added in version 256. ✨

💅 EXIT STATUS 💅

On success you get 0 back, bestie. Anything else? Non-zero failure code, no cap. 😭

When a command is invoked with with, the exit status of the child gets propagated. Basically: homectl exits without error if the command is successfully invoked and finishes successfully. Both, okay? Both. 🫶

🦋 ENVIRONMENT 🦋

  • $SYSTEMD_LOG_LEVEL — the maximum log level of emitted messages, i.e. messages with a higher log level (the less important ones) get suppressed, periodt. Takes a comma-separated list of values. Each value can be either one of these, listed in order of decreasing importance: emerg, alert, crit, err, warning, notice, info, debug — or an integer in the range 0...7. See syslog(3) for more info, iykyk.

Each value may optionally be prefixed with one of console, syslog, kmsg or journal, followed by a colon, to set the maximum log level for that specific log target (e.g. SYSTEMD_LOG_LEVEL=debug,console:info says: log at debug level except when logging to the console, which should be at info level). Note that the global maximum log level takes priority over any per-target maximum log levels. 👑

  • $SYSTEMD_LOG_COLOR — a boolean. If true, messages written to the tty will be colored according to priority. 🌈

This setting is only useful when messages are written directly to the terminal, because journalctl(1) and other tools that display logs will color messages based on the log level on their own. So like, don't stress about it elsewhere.

  • $SYSTEMD_LOG_TIME — a boolean. If true, console log messages will be prefixed with a timestamp. ⭐

Again, only useful when messages are written directly to the terminal or a file, because journalctl(1) and other tools that display logs will attach timestamps based on the entry metadata on their own.

  • $SYSTEMD_LOG_LOCATION — a boolean. If true, messages get prefixed with a filename and line number in the source code where the message originates. 🔍

Note that the log location is often attached as metadata to journal entries anyway. Including it directly in the message text can nevertheless be convenient when debugging programs. Ngl it's giving helpful.

  • $SYSTEMD_LOG_TID — a boolean. If true, messages get prefixed with the current numerical thread ID (TID). 🧵

Note that this information is attached as metadata to journal entries anyway. Including it directly in the message text can nevertheless be convenient when debugging programs.

  • $SYSTEMD_LOG_TARGET — the destination for log messages. One of:
    • console — log to the attached tty
    • console-prefixed — log to the attached tty but with prefixes encoding the log level and "facility", see syslog(3)
    • kmsg — log to the kernel circular log buffer
    • journal — log to the journal
    • journal-or-kmsg — log to the journal if available, and to kmsg otherwise
    • auto — determine the appropriate log target automatically, this is the default
    • null — disable log output entirely
  • $SYSTEMD_LOG_RATELIMIT_KMSG — whether to ratelimit kmsg or not. Takes a boolean. Defaults to "true". If disabled, systemd will not ratelimit messages written to kmsg. 🔥
  • $SYSTEMD_PAGER, $PAGER — the pager to use when --no-pager is not given. $SYSTEMD_PAGER is used if set; otherwise $PAGER is used. If neither $SYSTEMD_PAGER nor $PAGER are set, a set of well-known pager implementations is tried in turn, including less(1) and more(1), until one is found. If no pager implementation is discovered, no pager is invoked. Setting those environment variables to an empty string or the value "cat" is equivalent to passing --no-pager. 🐈
Note: if $SYSTEMD_PAGERSECURE is not set, $SYSTEMD_PAGER and $PAGER can only be used to disable the pager (with "cat" or ""), and are otherwise ignored. Yeah, she's strict.
  • $SYSTEMD_LESS — override the options passed to less (by default "FRSXMK").

Users might want to change two options in particular:

  • K — this option instructs the pager to exit immediately when Ctrl+C is pressed. To allow less to handle Ctrl+C itself to switch back to the pager command prompt, unset this option.

If the value of $SYSTEMD_LESS does not include "K", and the pager that is invoked is less, Ctrl+C will be ignored by the executable, and needs to be handled by the pager. 😬

  • X — this option instructs the pager to not send termcap initialization and deinitialization strings to the terminal. It is set by default to allow command output to remain visible in the terminal even after the pager exits. Nevertheless, this prevents some pager functionality from working, in particular paged output cannot be scrolled with the mouse. 🖱️

Note that setting the regular $LESS environment variable has no effect for less invocations by systemd tools. Sorry bestie.

See less(1) for more discussion.

  • $SYSTEMD_LESSCHARSET — override the charset passed to less (by default "utf-8", if the invoking terminal is determined to be UTF-8 compatible).

Note that setting the regular $LESSCHARSET environment variable has no effect for less invocations by systemd tools. Same deal as above. ✨

  • $SYSTEMD_PAGERSECURE — okay so this one's a whole thing, buckle up. 💀

Common pager commands like less(1), in addition to "paging" (i.e. scrolling through the output), support opening of or writing to other files and running arbitrary shell commands. When commands are invoked with elevated privileges — for example under sudo(8) or pkexec(1) — the pager becomes a security boundary. Care must be taken that only programs with strictly limited functionality are used as pagers, and that unintended interactive features like opening or creation of new files or starting of subprocesses are not allowed. "Secure mode" for the pager may be enabled as described below, if the pager supports that (most pagers are not written in a way that takes this into consideration). It is recommended to either explicitly enable "secure mode" or to completely disable the pager using --no-pager or PAGER=cat when allowing untrusted users to execute commands with elevated privileges. 🚨

This option takes a boolean argument. When set to true, the "secure mode" of the pager is enabled. In "secure mode", LESSSECURE=1 will be set when invoking the pager, which instructs the pager to disable commands that open or create new files or start new subprocesses. Currently only less(1) is known to understand this variable and implement "secure mode".

When set to false, no limitation is placed on the pager. Setting SYSTEMD_PAGERSECURE=0 or not removing it from the inherited environment may allow the user to invoke arbitrary commands. Like, actual arbitrary commands. Be careful. 😭

When $SYSTEMD_PAGERSECURE is not set, systemd tools attempt to automatically figure out if "secure mode" should be enabled and whether the pager supports it. "Secure mode" is enabled if the effective UID is not the same as the owner of the login session, see geteuid(2) and sd_pid_get_owner_uid(3), or when running under sudo(8) or similar tools ($SUDO_UID is set [5]). In those cases, SYSTEMD_PAGERSECURE=1 will be set and pagers which are not known to implement "secure mode" will not be used at all. Note that this autodetection only covers the most common mechanisms to elevate privileges and is intended as convenience. It is recommended to explicitly set $SYSTEMD_PAGERSECURE or disable the pager. 👑

Note: if the $SYSTEMD_PAGER or $PAGER variables are to be honoured — other than to disable the pager — $SYSTEMD_PAGERSECURE must be set too. That's the deal, iykyk.
  • $SYSTEMD_COLORS — takes a boolean argument, or a special value. By default (unset), systemd and related utilities will use colors in their output if possible. If $COLORTERM is set to "truecolor" or "24bit", 24-bit colors will be enabled, 256 colors otherwise — unless $NO_COLOR or $TERM indicates colors are disabled. 🌈💖
    • true — same as unset, except that $NO_COLOR is ignored.
    • false — the output will be monochrome. 🖤
    • "16", "256", "24bit" — always use the base 16 ANSI colors, 256 colors, or 24-bit color, respectively.
    • "auto-16", "auto-256", "auto-24bit" — use the given quantity of colours, subject to $TERM, and what the console is connected to.
  • $SYSTEMD_URLIFY — the value must be a boolean. Controls whether clickable links should be generated in the output for terminal emulators supporting this. This can be specified to override the decision that systemd makes based on $TERM and other conditions. 🔗

🎀 EXAMPLES 🎀

Example 1. Create a user "waldo" in the administrator group "wheel", and assign 500 MiB disk space to them.

homectl create waldo --real-name="Waldo McWaldo" -G wheel --disk-size=500M

Example 2. Create a user "wally" on a USB stick, and assign a maximum of 500 concurrent tasks to them.

homectl create wally --real-name="Wally McWally" --image-path=/dev/disk/by-id/usb-SanDisk_Ultra_Fit_476fff954b2b5c44-0:0 --tasks-max=500

Example 3. Change nice level of user "odlaw" to +5 and make sure the environment variable $SOME is set to the string "THING" for them on login.

homectl update odlaw --nice=5 --setenv=SOME=THING

Example 4. Set up authentication with a YubiKey security token using PKCS#11/PIV:

# Clear the Yubikey from any old keys (careful!)
ykman piv reset

# Generate a new private/public key pair on the device, store the public key in 'pubkey.pem'.
ykman piv generate-key -a RSA2048 9d pubkey.pem

# Create a self-signed certificate from this public key, and store it on the device.
ykman piv generate-certificate --subject "Knobelei" 9d pubkey.pem

# We do not need the public key on disk anymore
rm pubkey.pem

# Allow the security token to unlock the account of user 'lafcadio'.
homectl update lafcadio --pkcs11-token-uri=auto
Careful bestie: that first line resets the YubiKey from any old keys. It literally says "(careful!)" in the original and I'm passing the message along. 🫶

Example 5. Set up authentication with a FIDO2 security token:

# Allow a FIDO2 security token to unlock the account of user 'nihilbaxter'.
homectl update nihilbaxter --fido2-device=auto

Example 6. Add a recovery key to an existing user account:

# Generate and add a recovery key for user 'emily'.
homectl update emily --recovery-key=yes

⭐ SEE ALSO ⭐

systemd(1), systemd-homed.service(8), homed.conf(5), userdbctl(1), useradd(8), cryptsetup(8) — go read those too, they're iconic in their own right. 💜

📝 NOTES 📝

Okay bestie, these are the receipts — the sources every claim in this page is standing on. Numbered, cited, and honestly kinda iconic for a manpage:

  1. JSON User Records — the whole user-record situation explained in full, at https://systemd.io/USER_RECORD 💖
  2. Icon Naming Specification — the freedesktop standard that says what your Icon= value is actually allowed to be, at https://standards.freedesktop.org/icon-naming-spec/icon-naming-spec-latest.html 🎀
  3. User Record Blob Directories — the deep lore on where blobs live, at https://systemd.io/USER_RECORD_BLOB_DIRS ✨
  4. User/Group Name Syntax — the rules for what counts as a legal name, at https://systemd.io/USER_NAMES 🦋
  5. Heads up for the devs in the chat: it is recommended for other tools to set and check $SUDO_UID as appropriate, treating it as a common interface 👑
Like, genuinely — if you're writing a tool that plays in this space, note 5 is your vibe check. $SUDO_UID is the shared language. Don't be the one who breaks it. 🙈

okay that's literally the whole page, bestie, you made it to the end 🫶 this was HOMECTL(1) from systemd 261.3, and the date is right down there at the bottom of the page doing its little footer thing 💅 go forth and manage your home directories with main character energy, no cap ✨👑💜

📦 where this page comes from