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