LOGIN.CONF(5)             OpenBSD Programmer's Manual            LOGIN.CONF(5)

NAME
     login.conf - login class capability database

SYNOPSIS
     /etc/login.conf

DESCRIPTION
     The login.conf file describes the various attributes of login classes.  A
     login class determines what styles of authentication are available as
     well as session resource limits and environment setup.  While designed
     primarily for the login(1) program, it is also used by other programs,
     e.g., ftpd(8), to determine what means of authentication are available.
     It is also used by programs, e.g., rshd(8), which need to set up a user
     environment.

     A special record, ``default'', in /etc/login.conf is used for any user
     without a valid login class in /etc/master.passwd.

     Sites with very large /etc/login.conf files may wish to create a database
     version of the file, /etc/login.conf.db, for improved performance.  Using
     a database version for small files does not result in a performance im-
     provement.  To build /etc/login.conf.db from /etc/login.conf the follow-
     ing command may be used:

           # cap_mkdb /etc/login.conf

     Note that cap_mkdb(1) must be run after each edit of /etc/login.conf to
     keep the database version in sync with the plain file.

CAPABILITIES
     Refer to getcap(3) for a description of the file layout.  All entries in
     the login.conf file are either boolean or use a `=' to separate the capa-
     bility from the value.  The types are described after the capability
     table.

     Name              Type       Default      Description
     approve           program                 Default program to approve lo-
                                               gin.

     approve-service   program                 Program to approve login for
                                               service.

     auth              list       passwd       Allowed authentication styles.
                                               The first value is the default
                                               styles.

     auth-type         list                    Allowed authentication styles
                                               for the authentication type
                                               type.

     classify          program                 Classify type of login.

     copyright         file                    File containing additional
                                               copyright information.

     coredumpsize      size                    Maximum coredump size limit.

     cputime           time                    CPU usage limit.

     datasize          size                    Maximum data size limit.

     expire-warn       time       2w           If the user's account will ex-
                                               pire within this length of time
                                               then warn the user of this.

     filesize          size                    Maximum file size limit.

     hushlogin         bool       false        Same as having a
                                               $HOME/.hushlogin file.  See
                                               login(1).

     ignorenologin     bool       false        Not affected by nologin files.
                                               See login(1).

     localcipher       string     blowfish,6   The cipher to use for local
                                               passwords.  Possible values
                                               are: ``old'',
                                               ``newsalt,<rounds>'', ``md5'',
                                               and ``blowfish,<rounds>'' where
                                               ``old'' means classic 56-bit
                                               DES.  For ``newsalt'' the value
                                               of rounds is a 24-bit integer
                                               with a minimum of 7250 rounds.
                                               For ``blowfish'' the value can
                                               be between 4 and 31.  It speci-
                                               fies the base 2 logarithm of
                                               the number of rounds.

     ypcipher          string     old          The cipher to use for YP pass-
                                               words.  The possible values are
                                               the same as for localcipher.

     login-backoff     number     3            After login-backoff unsuccess-
                                               ful login attempts during a
                                               single session, login(1) will
                                               start sleeping a bit in between
                                               attempts.

     login-timeout     time       300          Number of seconds before
                                               login(1) times out at the pass-
                                               word prompt.  Note that this
                                               setting is only valid for the
                                               default record.

     login-tries       number     10           Number of tries a user gets to
                                               successfully login before
                                               login(1) closes the connection.

     stacksize         size                    Maximum stack size limit.

     maxproc           number                  Maximum number of processes.

     memorylocked      size                    Maximum locked in core memory
                                               size limit.

     memoryuse         size                    Maximum in core memoryuse size
                                               limit.

     minpasswordlen    number     6            The minimum length a local
                                               password may be.  If a negative
                                               value or zero, no length re-
                                               strictions are enforced.  Used
                                               by the passwd(1) utility.

     nologin           file                    If the file exists it will be
                                               displayed and the login session
                                               will be terminated.

     openfiles         number                  Maximum number of open file de-
                                               scriptors per process.

     password-dead     time       0            Length of time a password may
                                               be expired but not quite dead
                                               yet.  When set (for both the
                                               client and remote server ma-
                                               chine when doing remote authen-
                                               tication), a user is allowed to
                                               log in just one more time after
                                               their password (but not ac-
                                               count) has expired.  This al-
                                               lows a grace period for updat-
                                               ing their password.

     password-warn     time       2w           If the user's password will ex-
                                               pire within this length of time
                                               then warn the user of this.

     passwordcheck     program                 An external program that checks
                                               the quality of the password.
                                               The password is passed to the
                                               program on stdin.  An exit code
                                               of 0 indicates that the quality
                                               of the password is sufficient,
                                               an exit code of 1 signals that
                                               the password failed the check.

     passwordtime      time                    The lifetime of a password in
                                               seconds, reset every time a us-
                                               er changes their password.
                                               When this value is exceeded the
                                               user will no longer be able to
                                               login unless the password-dead
                                               option has been specified.
                                               Used by the passwd(1) utility.

     passwordtries     number     3            The number of times the
                                               passwd(1) utility enforces a
                                               check on the password.  If 0,
                                               the new password will only be
                                               accepted if it passes the pass-
                                               word quality check.

     path              path       value of _PATH_DEFPATH
                                               Default search path.  See
                                               /usr/include/paths.h.

     priority          number                  Initial priority (nice) level.

     requirehome       bool       false        Require home directory to lo-
                                               gin.

     setenv            envlist                 A list of environment variables
                                               and associated values to be set
                                               for the class.

     shell             program                 Session shell to execute rather
                                               than the shell specified in the
                                               password file.  The SHELL envi-
                                               ronment variable will contain
                                               the shell specified in the
                                               password file.

     term              string     su           Default terminal type if not
                                               able to determine from other
                                               means.

     umask             number     022          Initial umask.  Should always
                                               have a leading 0 to ensure oc-
                                               tal interpretation.  See
                                               umask(2).

     vmemoryuse        size                    Maximum virtual memoryuse size
                                               limit.

     welcome           file       /etc/motd    File containing welcome mes-
                                               sage.

     The resource limit entries (cputime, filesize, datasize, memoryuse,
     memorylocked, maxproc, and openfiles) actually specify both the maximum
     and current limits (see getrlimit(2)).  The current limit is the one nor-
     mally used, although the user is permitted to increase the current limit
     to the maximum limit.  The maximum and current limits may be specified
     individually by appending a -max or -cur to the capability name (e.g.,
     openfiles-max and openfiles-cur).

     OpenBSD will never define capabilities which start with x- or X-, these
     are reserved for external use (unless included through contributed soft-
     ware).

     The argument types are defined as:

     envlist    A comma-separated list of environment variables of the form
                variable=value.  If no value is specified, the `=' is option-
                al.  A ~ in the path name is expanded to the user's home di-
                rectory if it is at the end of a string or is followed by a
                slash (`/') or the user's login name.  A $ in the path name is
                expanded to the user's login name.

     file       Path name to a text file.

     list       A comma-separated list of values.

     number     A number.  A leading 0x implies the number is expressed in
                hexadecimal.  A leading 0 implies the number is expressed in
                octal.  Any other number is treated as decimal.

     path       A space-separated list of path names.  Login name and directo-
                ry are substituted as for envlist.  Additionally, a ~ is only
                expanded at the beginning of a path name.

     program    A path name to program.

     size       A number which expresses a size in bytes.  It may have a
                trailing b to multiply the value by 512, a k to multiply the
                value by 1 K (1024), and an m to multiply the value by 1 M
                (1048576).

     time       A time in seconds.  A time may be expressed as a series of
                numbers which are added together.  Each number may have a
                trailing character to represent time units:

                y    Indicates a number of 365 day years.

                w    Indicates a number of 7 day weeks.

                d    Indicates a number of 24 hour days.

                h    Indicates a number of 60 minute hours.

                m    Indicates a number of 60 second minutes.

                s    Indicates a number of seconds.

                For example, to indicate 1 and 1/2 hours, the following string
                could be used: 1h30m.

AUTHENTICATION
     OpenBSD 4.7 uses BSD Authentication, which is made up of a variety of au-
     thentication styles.  The authentication styles currently provided are:

     activ          Authenticate using an ActivCard token.  See
                    login_activ(8).

     chpass         Change user's password.  See login_chpass(8).

     crypto         Authenticate using a CRYPTOCard token.  See
                    login_crypto(8).

     krb5           Request a password and use it to request a ticket from the
                    kerberos 5 server.  See login_krb5(8).

     krb5-or-pwd    Request a password and first try the krb5 authentication
                    style and if that fails use the same password with the
                    passwd authentication style.  See login_krb5-or-pwd(8).

     lchpass        Change user's local password.  See login_lchpass(8).

     passwd         Request a password and check it against the password in
                    the master.passwd file.  See login_passwd(8).

     radius         Normally linked to another authentication type, contact
                    the radius server to do authentication.  See
                    login_radius(8).

     reject         Request a password and reject any request.  See
                    login_reject(8).

     rpasswd        Request a password and check it against the password in
                    the rpasswd.db file.

     skey           Send a challenge and request a response, checking it with
                    S/Key (tm) authentication.  See login_skey(8).

     snk            Authenticate using a SecureNet Key token.  See
                    login_snk(8).

     token          Authenticate using a generic X9.9 token.  See
                    login_token(8).

     Local authentication styles may be added by creating a login script for
     the style (see below).  To prevent collisions with future official BSD
     Authentication style names, all local style names should start with a
     dash (-).  Current plans are for all official BSD Authentication style
     names to begin with a lower case alphabetic character.  For example, if
     you have a new style you refer to as slick then you should create an au-
     thentication script named /usr/libexec/auth/login_-slick using the style
     name -slick.  When logging in via the login(1) program, the syntax
     user:-slick would be used.

     Authentication requires several pieces of information:

     class       The login class being used.

     service     The type of service requesting authentication.  The service
                 type is used to determine what information the authentication
                 program can provide to the user and what information the user
                 can provide to the authentication program.

                 The service type login is appropriate for most situations.
                 Two other service types, challenge and response, are provided
                 for use by programs like ftpd(8) and radiusd.  If no service
                 type is specified, login is used.

     style       The authentication style being used.

     type        The authentication type, used to determine the available au-
                 thentication styles.

     username    The name of the user to authenticate.  The name may contain
                 an instance, e.g. ``user/root'', as used by Kerberos authen-
                 tication.  If the authentication style being used does not
                 support such instances, the request will fail.

     The program requesting authentication must specify a username and an au-
     thentication style.  (For example, login(1) requests a username from the
     user.  Users may enter usernames of the form ``user:style'' to optionally
     specify the authentication style.)  The requesting program may also spec-
     ify the type of authentication that will be done.  Most programs will on-
     ly have a single type, if any at all, i.e., ftpd(8) will always request
     the ftp type authentication, and su(1) will always request the su type
     authentication.  The login(1) utility is special in that it may select an
     authentication type based on information found in the /etc/ttys file for
     the appropriate tty (see ttys(5)).

     The class to be used is normally determined by the class field in the
     password file (see passwd(5)).

     The class is used to look up a corresponding entry in the login.conf
     file.  If an authentication type is defined and a value for auth-type ex-
     ists in that entry, it will be used as a list of potential authentication
     styles.  If an authentication type is not defined, or auth-type is not
     specified for the class, the value of auth is used as the list of avail-
     able authentication styles.

     If the user did not specify an authentication style the first style in
     the list of available styles is used.  If the user did specify an authen-
     tication style and the style is in the list of available styles it will
     be used, otherwise the request is rejected.

     For any given style, the program /usr/libexec/auth/login_style is used to
     perform the authentication.  The synopsis of this program is:

     /usr/libexec/auth/login_style [-v name=value] [-s service] username class

     The -v option is used to specify arbitrary information to the authentica-
     tion programs.  Any number of -v options may be used.  The login(1) pro-
     gram provides the following through the -v option:

     auth_type       The type of authentication to use.

     fqdn            The hostname provided to login by the -h option.

     hostname        The name login(1) will place in the utmp file for the re-
                     mote hostname.

     local_addr      The local IP address given to login(1) by the -L option.

     lastchance      Set to ``yes'' when a user's password has expired but the
                     user is being given one last chance to login and update
                     the password.

     login           This is a new login session (as opposed to a simple iden-
                     tity check).

     remote_addr     The remote IP address given to login(1) by the -R option.

     style           The style of authentication used for this user (see ap-
                     proval scripts below).

     The su(1) program provides the following through the -v option:

     invokinguser    Set to the name of the user being authenticated; used for
                     Kerberos authentication.

     wheel           Set to either ``yes'' or ``no'' to indicate if the user
                     is in group wheel when they are trying to become root.
                     Some authentication types require the user to be in group
                     wheel when using the su(1) program to become super user.

     When the authentication program is executed, the environment will only
     contain the values PATH=/bin:/usr/bin and SHELL=/bin/sh.  File descriptor
     3 will be open for reading and writing.  The authentication program
     should write one or more of the following strings to this file descrip-
     tor:

     authorize  The user has been authorized.

     authorize secure
                The user has been authorized and root should be allowed to lo-
                gin even if this is not a secure terminal.  This should only
                be sent by authentication styles that are secure over insecure
                lines.

     reject     Authorization is rejected.  This overrides any indication that
                the user was authorized (though one would question the wisdom
                in sending both a reject and an authorize command).

     reject challenge
                Authorization was rejected and a challenge has been made
                available via the value challenge.

     reject silent
                Authorization is rejected, but no error messages should be
                generated.

     remove file
                If the login session fails for any reason, remove file before
                termination (a kerberos ticket file, for example).

     setenv name value
                If the login session succeeds, the environment variable name
                should be set to the specified value.

     unsetenv name
                If the login session succeeds, the environment variable name
                should be removed.

     value name value
                Set the internal variable name to the specified value.  The
                value should only contain printable characters.  Several \ se-
                quences may be used to introduce non printing characters.
                These are:

                \n      A newline.

                \r      A carriage return.

                \t      A tab.

                \xxx    The character represented by the octal value xxx.  The
                        value may be one, two, or three octal digits.

                \c      The string is replaced by the value of c.  This allows
                        quoting an initial space or the \ character itself.

                The following values are currently defined:

                challenge
                        See section on challenges below.

                errormsg
                        If set, the value is the reason authentication failed.
                        The calling program may choose to display this when
                        rejecting the user, but display is not required.

     In order for authentication to be successful, the authentication program
     must exit with a value of 0 as well as provide an authorize or authorize
     root statement on file descriptor 3.

     An authentication program must not assume it will be called as root, nor
     must it assume it will not be called as root.  If it needs special per-
     missions to access files it should be setuid or setgid to the appropriate
     user/group.  See chmod(1).

CHALLENGES
     When an authentication program is called with a service of challenge it
     should do one of three things:

     If this style of authentication supports challenge response it should set
     the internal variable challenge to be the appropriate challenge for the
     user.  This is done by the value command listed above.  The program
     should also issue a reject challenge and then exit with a 0 status.  See
     the section on responses below.

     If this style of authentication does not support challenge response, but
     does support the response service (described below) it should issue
     reject silent and then exit with a 0 status.

     If this style of authentication does not support the response service it
     should simply fail, complaining about an unknown service type.  It should
     exit with a non-zero status.

RESPONSES
     When an authentication program is called with a service of response, and
     this style supports this mode of authentication, it should read two null
     terminated strings from file descriptor 3.  The first string is a chal-
     lenge that was issued to the user (obtained from the challenge service
     above).  The second string is the response the user gave (i.e., the pass-
     word).  If the response is correct for the specified challenge, the au-
     thentication should be accepted, else it should be rejected.  It is pos-
     sible for the challenge to be any empty string, which implies the calling
     program did first obtain a challenge prior to getting a response from the
     user.  Not all authentication styles support empty challenges.

APPROVAL
     An approval program has the synopsis of:

           approve [-v name=value] username class service

     Just as with an authentication program, file descriptor 3 will be open
     for writing when the approval program is executed.  The -v option is the
     same as in the authentication program.  Unlike an authentication program,
     the approval program need not explicitly send an authorize or authorize
     root statement, it only need exit with a value of 0 or non-zero.  An exit
     value of 0 is equivalent to an authorize statement, and non-zero to a
     reject statement.  This allows for simple programs which have no informa-
     tion to provide other than approval or denial.

CLASSIFICATION
     A classify program has the synopsis of:

           classify [-v name=value] [-f] [user]

     See login(1) for a description of the -f, option.  The -v option is the
     same as for the authentication programs.  The user is the username passed
     to login(1) login, if any.

     The typical job of the classify program is to determine what authentica-
     tion type should actually be used, presumably based on the remote IP ad-
     dress.  It might also re-specify the hostname to be included in the
     utmp(5) file, reject the login attempt outright, or even print an addi-
     tional login banner (e.g., /etc/issue).

     The classify entry is only valid for the default class as it is used pri-
     or to knowing who the user is.  The classify script may pass environment
     variables or other commands back to login(1) on file descriptor 3, just
     as an authentication program does.  The two variables AUTH_TYPE and
     REMOTE_NAME are used to specify a new authentication type (the type must
     have the form auth-type) and override the -h option to login, respective-
     ly.

SEE ALSO
     cap_mkdb(1), login(1), authenticate(3), bsd_auth(3), getcap(3),
     login_cap(3), passwd(5), ttys(5), ftpd(8)

OpenBSD 4.7                     January 3, 2010                              9
