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