crypto/heimdal-0.6.3/appl/login/login.1

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