libuser.conf - configuration for libuser and libuser utilities
libuser.conf is a text file. Leading and trailing white
space on each line is ignored. Lines starting with # are ignored.
The file defines variables grouped into sections. Each section
starts with a section header:
[section name]
A single section header can appear more than once in the file.
The lines following a section header define variables from that
section:
variable = value
The value can be empty.
A variable can have more than one value, specified by using
more than one line defining that variable. All currently defined
variables accept only the first value and ignore the others, if any.
[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.
- 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:
| Variable |
Imported as |
| 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
- 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:
| Variable |
Imported as |
| 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.
[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.
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.
After the userdefaults section is processed, modules may
define additional attributes or even override the attributes defined in this
section.
[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.
- 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.
- 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.
- 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.
Invalid lines in the configuration file (or the imported
shadow configuration files) are silently ignored.
- /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.