libuser.conf(5)

💖 libuser.conf — the config file for libuser & friends 💖

okay bestie, this is the File Formats Manual page for libuser.conf, and honestly? it's giving "quiet config file that runs your whole system's user database." let's get into it 🫶

---

✨ NAME ✨

libuser.conf — configuration for libuser and libuser utilities 💅

---

📝 FILE FORMAT 📝

okay so libuser.conf is a text file. leading and trailing white space on each line? ignored, we don't care. lines starting with # are ignored too — those are the little side comments, slay.

the file defines variables grouped into sections. every section starts with a section header:

[section name]

and bestie, a single section header can appear more than once in the file. it's flexible like that. 💁‍♀️

the lines following a section header define variables from that section:

variable = value

the value can be empty. (yes, truly empty. it's valid. no cap.)

a variable can have more than one value — you do that by using more than one line defining that variable. but heads up: all currently defined variables accept only the first value and ignore the others, if any. so don't get cute with it 🙈

---

🌸 [defaults] 🌸

• create_modules — a list of module names to use when creating user or group entries, unless the application specifies a different list. the module names in the list can be separated using space, tab or comma. default value is files shadow.
• crypt_style — the algorithm to use for password encryption when creating new passwords. the current algorithm may be retained when changing a password of an existing user, depending on the application.

possible values are des, md5, blowfish, sha256, sha512, and yescrypt, all case-insensitive. unrecognized values are treated as des. default value is des.

• hash_rounds_min, hash_rounds_max — these variables specify an inclusive range of hash rounds used when crypt_style is sha256 or sha512. a number of hash rounds is chosen from this interval randomly. a larger number of rounds makes password checking, and brute-force attempts to guess the password by reversing the hash, more CPU-intensive. the number of rounds is restricted to the interval [1000, 999999999].

if only one of the above variables is specified, the number of rounds used is specified by the other variable. if neither variable is specified, the number of rounds is chosen by libc. (libc said "i got this" 💅)

• mailspooldir — the directory containing user's mail spool files. default value is /var/mail.
• moduledir — the directory containing libuser modules. default value uses the modules installed with libuser, corresponding to the architecture of the libuser library, e.g. /usr/lib/libuser or /usr/lib64/libuser (assuming libuser was configured with --prefix=/usr).
• modules — a list of module names to use when not creating user or group entries, unless the application specifies a different list. the module names in the list can be separated using space, tab or comma. default value is files shadow.
• skeleton — the directory containing files to copy to newly created home directories. default value is /etc/skel.

---

🧚 [import] 🧚

• login_defs — a path to the login.defs file from shadow. if this variable is defined, the variables from the named file are used in place of some libuser variables. variables explicitly defined in libuser.conf are not affected by contents of login.defs.

the following variables are imported:

• ENCRYPT_METHOD → defaults/crypt_style
• GID_MIN → groupdefaults/LU_GIDNUMBER
• MAIL_DIR → defaults/mailspooldir
• MD5_CRYPT_ENAB → defaults/crypt_style
• PASS_MAX_DAYS → userdefaults/LU_SHADOWMAX
• PASS_MIN_DAYS → userdefaults/LU_SHADOWMIN
• PASS_WARN_AGE → userdefaults/LU_SHADOWWARNING
• SHA_CRYPT_MIN_ROUNDS → defaults/hash_rounds_min
• SHA_CRYPT_MAX_ROUNDS → defaults/hash_rounds_max
• UID_MIN → userdefaults/LU_UIDNUMBER

the following variables are not imported: CREATE_HOME, GID_MAX, MAIL_FILE, SYSLOG_SG_ENAB, UID_MAX, UMASK, USERDEL_CMD, USERGROUPS_ENAB. they're just not invited to the party, sorry 😭

• default_useradd — a path to the default/useradd file from useradd in shadow. if this variable is defined, the variables from the named file are used in place of some libuser variables. variables explicitly defined in libuser.conf are not affected by contents of default/useradd.

the following variables are imported:

• EXPIRE → userdefaults/LU_SHADOWEXPIRE
• GROUP → userdefaults/LU_GIDNUMBER
• HOME → userdefaults/LU_HOMEDIRECTORY
• INACTIVE → userdefaults/LU_SHADOWINACTIVE
• SHELL → userdefaults/LU_LOGINSHELL
• SKEL → defaults/skeleton

the HOME variable value has /%n appended to it before importing. periodt.

---

👑 [userdefaults] 👑

this section defines attribute values of newly created user entities. there is one special variable:

• LU_UIDNUMBER — a decimal number, the first allowed UID value for regular users (not system users). default value is 500.

all other variables have the same names as the attribute names from <libuser/entity.h> and define attribute values. either the macro name (e.g. LU_GECOS) or the macro content (e.g. pw_gecos) can be used; if both are used, the one appearing later in the configuration file is used. last one wins, that's the rule 💅

the % character in the value of the variable introduces an escape sequence: %n is replaced by the user name, %d is replaced by current date in days since the epoch, %u is replaced by the user's UID. there is no way to escape the % character and avoid this substitution. so if you were trying to be sneaky with a literal %, nope, it's getting substituted, no cap 😭

after the userdefaults section is processed, modules may define additional attributes or even override the attributes defined in this section. main character modules fr.

---

💜 [groupdefaults] 💜

the groupdefaults section is similar to userdefaults. there is one special variable:

• LU_GIDNUMBER — a decimal number, the first allowed GID value for regular groups (not system groups). default value is 500.

the other variables follow the same rules as in the userdefaults section, except that %n and %u are replaced by the group name and group's GID, respectively.

after the groupdefaults section is processed, modules may define additional attributes or even override the attributes defined in this section.

---

🗂️ [files] 🗂️

configures the files module, which manages /etc/group and /etc/passwd. the configuration variables are probably useful only for libuser development. (iykyk 🔧)

• directory — the directory containing the group and passwd files. default value is /etc.
• nonroot — allow module initialization when not invoked as the root user if the value is yes.
• allow_id_duplicates — allow to use duplicate uid/gid. the default value is no.

---

🌈 [shadow] 🌈

configures the files module, which manages /etc/gshadow and /etc/shadow. the configuration variables are probably useful only for libuser development.

• directory — the directory containing the gshadow and shadow files. default value is /etc.
• nonroot — allow module initialization when not invoked as the root user if the value is yes.

---

🦋 [ldap] 🦋

configures the ldap module, which manages an user database accessible using LDAP. buckle up bestie, this section is long.

• userBranch — the LDAP suffix for user entities. default value is ou=People.
• groupBranch — the LDAP suffix for group entities. default value is ou=Group.
• server — a domain name or an URI of the LDAP server. the URI can use the ldap, ldapi or the ldaps protocol. when a simple domain name is used, the connection fails if TLS can not be used; an URI using the ldap protocol allows connection without TLS. TLS is never used with the ldapi protocol. default value is ldap.
• basedn — the base DN of the server. default value is dc=example,dc=com.
• binddn — a DN for binding to the server. if the value is empty or binding using this DN fails, a DN of uid=user,userBranch,basedn is used, where userBranch and basedn are variables from this section and user is the user name of the invoking user, unless overridden by the user variable from this section. default value is cn=manager,dc=example,dc=com.
• user — the SASLv2 identity for authenticating to the LDAP server, also overrides the user name for generating a bind DN. default value is the name of the invoking user.
• password — the password used for a simple bind by default. if not specified, there is no default and the user must supply the password each time.

🚨 IT IS STRONGLY RECOMMENDED NOT TO STORE A PASSWORD IN THE SYSTEM-WIDE /etc/libuser.conf FILE. the configuration file is world-readable by default, and setuid programs that prompt for a server name could be used to send the password to an attacker-controlled server. bestie. do NOT do this. i am begging 🙏💀

• authuser — the SASLv2 authorization user, if non-empty. default value is empty.
• bindtype — the list of bind types to use, separated by commas. allowed bind types are simple, sasl, and sasl/mechanism, where mechanism is a SASL mechanism. the bind types (but not necessarily mechanism) are case-insensitive. if more than one bind type is specified, their relative order is ignored. default value is simple,sasl.

---

🎀 [sasl] 🎀

configures the sasl module, which manages a SASLv2 user database.

• appname — name of the SASLv2 application. default value is empty.
• domain — domain used by libuser for the SASLv2 authentication object. default value is empty.

---

💀 BUGS 💀

invalid lines in the configuration file (or the imported shadow configuration files) are silently ignored. no error, no warning, just vibes. it'll just sit there pretending nothing happened 🙈

---

📁 FILES 📁

• /etc/libuser.conf — the default location of the configuration file. can be overridden by the LIBUSER_CONF environment variable, except in set-uid or set-gid programs.

---

and that's the whole page, bestie 🫶 this was libuser, dated 2010-02-08, and you just read libuser.conf(5). go forth and configure responsibly ✨💖🌸