crypto/heimdal/appl/login/login.1

   1 .\" $Id$
   2 .\"
   3 .Dd April 22, 2005
   4 .Dt LOGIN 1
   5 .Os HEIMDAL
   6 .Sh NAME
   7 .Nm login
   8 .Nd authenticate a user and start new session
   9 .Sh SYNOPSIS
  10 .Nm
  11 .Op Fl fp
  12 .Op Fl a Ar level
  13 .Op Fl h Ar hostname
  14 .Ar [username]
  15 .Sh DESCRIPTION
  16 This manual page documents  the
  17 .Nm login
  18 program distributed with the Heimdal Kerberos 5 implementation, it may
  19 differ in important ways from your system version.
  20 .Pp
  21 The
  22 .Nm login
  23 programs logs users into the system. It is intended to be run by
  24 system daemons like
  25 .Xr getty 8
  26 or
  27 .Xr telnetd 8 .
  28 If you are already logged in, but want to change to another user, you
  29 should use
  30 .Xr su 1 .
  31 .Pp
  32 A username can be given on the command line, else one will be prompted
  33 for.
  34 .Pp
  35 A password is required to login, unless the
  36 .Fl f
  37 option is given (indicating that the calling program has already done
  38 proper authentication). With
  39 .Fl f
  40 the user will be logged in without further questions.
  41 .Pp
  42 For password authentication Kerberos 5, Kerberos 4 (if compiled in),
  43 OTP (if compiled in) and local
  44 .No ( Pa /etc/passwd )
  45 passwords are supported. OTP will be used if the the user is
  46 registered to use it, and
  47 .Nm login
  48 is given the option
  49 .Fl a Li otp .
  50 When using OTP, a challenge is shown to the user.
  51 .Pp
  52 Further options are:
  53 .Bl -tag -width Ds
  54 .It Fl a Ar string
  55 Which authentication mode to use, the only supported value is
  56 currently
  57 .Dq otp .
  58 .It Fl f
  59 Indicates that the user is already authenticated. This happens, for
  60 instance, when login is started by telnetd, and the user has proved
  61 authentic via Kerberos.
  62 .It Fl h Ar hostname
  63 Indicates which host the user is logging in from. This is passed from
  64 telnetd, and is entered into the login database.
  65 .It Fl p
  66 This tells
  67 .Nm login
  68 to preserve all environment variables. If not given, only the
  69 .Dv TERM
  70 and
  71 .Dv TZ
  72 variables are preserved. It could be a security risk to pass random
  73 variables to
  74 .Nm login
  75 or the user shell, so the calling daemon should make sure it only
  76 passes
  77 .Dq safe
  78 variables.
  79 .El
  80 .Pp
  81 The process of logging user in proceeds as follows.
  82 .Pp
  83 First a check is made that logins are allowed at all. This usually
  84 means checking
  85 .Pa /etc/nologin .
  86 If it exists, and the user trying to login is not root, the contents
  87 is printed, and then login exits.
  88 .Pp
  89 Then various system parameters are set up, like changing the owner of
  90 the tty to the user, setting up signals, setting the group list, and
  91 user and group id. Also various machine specific tasks are performed.
  92 .Pp
  93 Next
  94 .Nm login
  95 changes to the users home directory, or if that fails, to
  96 .Pa / .
  97 The environment is setup, by adding some required variables (such as
  98 .Dv PATH ) ,
  99 and also authentication related ones (such as
 100 .Dv KRB5CCNAME ) .
 101 If an environment file exists
 102 .No ( Pa /etc/environment ) ,
 103 variables are set according to
 104 it.
 105 .Pp
 106 If one or more login message files are configured, their contents is
 107 printed to the terminal.
 108 .Pp
 109 If a login time command is configured, it is executed. A logout time
 110 command can also be configured, which makes
 111 .Nm login
 112 fork, and wait for the user shell to exit, and then run the command.
 113 This can be used to clean up user credentials.
 114 .Pp
 115 Finally, the user's shell is executed. If the user logging in is root,
 116 and root's login shell does not exist, a default shell (usually
 117 .Pa /bin/sh )
 118 is also tried before giving up.
 119 .Sh ENVIRONMENT
 120 These environment variables are set by login (not including ones set by
 121 .Pa /etc/environment ) :
 122 .Pp
 123 .Bl -tag -compact -width USERXXLOGNAME
 124 .It Dv PATH
 125 the default system path
 126 .It Dv HOME
 127 the user's home directory (or possibly
 128 .Pa / )
 129 .It Dv USER , Dv LOGNAME
 130 both set to the username
 131 .It Dv SHELL
 132 the user's shell
 133 .It Dv TERM , Dv TZ
 134 set to whatever is passed to
 135 .Nm login
 136 .It Dv KRB5CCNAME
 137 if the password is verified via Kerberos 5, this will point to the
 138 credentials cache file
 139 .It Dv KRBTKFILE
 140 if the password is verified via Kerberos 4, this will point to the
 141 ticket file
 142 .El
 143 .Sh FILES
 144 .Bl -tag -compact -width Ds
 145 .It Pa /etc/environment
 146 Contains a set of environment variables that should be set in addition
 147 to the ones above. It should contain sh-style assignments like
 148 .Dq VARIABLE=value .
 149 Note that they are not parsed the way a shell would. No variable
 150 expansion is performed, and all strings are literal, and quotation
 151 marks should not be used. Everything after a hash mark is considered a
 152 comment. The following are all different (the last will set the
 153 variable
 154 .Dv BAR ,
 155 not
 156 .Dv FOO ) .
 157 .Bd -literal -offset indent
 158 FOO=this is a string
 159 FOO="this is a string"
 160 BAR= FOO='this is a string'
 161 .Ed
 162 .It Pa /etc/login.access
 163 See
 164 .Xr login.access 5 .
 165 .It Pa /etc/login.conf
 166 This is a termcap style configuration file, that contains various
 167 settings used by
 168 .Nm login .
 169 Currently only the
 170 .Dq default
 171 capability record is used. The possible capability strings include:
 172 .Pp
 173 .Bl -tag -compact -width Ds
 174 .It Li environment
 175 This is a comma separated list of environment files that are read in
 176 the order specified. If this is missing the default
 177 .Pa /etc/environment
 178 is used.
 179 .It Li login_program
 180 This program will be executed just before the user's shell is started.
 181 It will be called without arguments.
 182 .It Li logout_program
 183 This program will be executed just after the user's shell has
 184 terminated. It will be called without arguments. This program will be
 185 the parent process of the spawned shell.
 186 .It Li motd
 187 A comma separated list of text files that will be printed to the
 188 user's terminal before starting the shell. The string
 189 .Li welcome
 190 works similarly, but points to a single file.
 191 .It Li limits
 192 Points to a file containing ulimit settings for various users. Syntax
 193 is inspired by what pam_limits uses, and the default is
 194 .Pa /etc/security/limits.conf .
 195 .El
 196 .It Pa /etc/nologin
 197 If it exists, login is denied to all but root. The contents of this
 198 file is printed before login exits.
 199 .El
 200 .Pp
 201 Other
 202 .Nm login
 203 programs typically print all sorts of information by default, such as
 204 last time you logged in, if you have mail, and system message files.
 205 This version of
 206 .Nm login
 207 does not, so there is no reason for
 208 .Pa .hushlogin
 209 files or similar. We feel that these tasks are best left to the user's
 210 shell, but the
 211 .Li login_program
 212 facility allows for a shell independent solution, if that is desired.
 213 .Sh EXAMPLES
 214 A
 215 .Pa login.conf
 216 file could look like:
 217 .Bd -literal -offset indent
 218 default:\\
 219         :motd=/etc/motd,/etc/motd.local:\\
 220         :limits=/etc/limits.conf:
 221 .Ed
 222 .Pp
 223 The
 224 .Pa limits.conf
 225 file consists of a table with four whitespace separated fields. First
 226 field is a username or a groupname (prefixed with
 227 .Sq @ ) ,
 228 or
 229 .Sq * .
 230 Second field is
 231 .Sq soft ,
 232 .Sq hard ,
 233 or
 234 .Sq -
 235 (the last meaning both soft and hard).
 236 Third field is a limit name (such as
 237 .Sq cpu
 238 or
 239 .Sq core ) .
 240 Last field is the limit value (a number or
 241 .Sq -
 242 for unlimited). In the case of data sizes, the value is in kilobytes,
 243 and cputime is in minutes.
 244 .Sh SEE ALSO
 245 .Xr su 1 ,
 246 .Xr login.access 5 ,
 247 .Xr getty 8 ,
 248 .Xr telnetd 8
 249 .Sh AUTHORS
 250 This login program was written for the Heimdal Kerberos 5
 251 implementation. The login.access code was written by Wietse Venema.
 252 .\".Sh BUGS