NAME

       libuser.conf - configuration for libuser and libuser utilities

FILE FORMAT

       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 and sha512, 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.

[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.

BUGS

       Invalid lines in the configuration file (or the imported shadow configuration  files)  are
       silently ignored.

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.