| blob | 29771c0cf332c46913b9bbee9118a221aae58f93 |
1 .\" $Id$
2 .\"
3 .Dd April 22, 2005
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 .It Li limits
193 Points to a file containing ulimit settings for various users. Syntax
194 is inspired by what pam_limits uses, and the default is
195 .Pa /etc/security/limits.conf .
196 .El
197 .It Pa /etc/nologin
198 If it exists, login is denied to all but root. The contents of this
199 file is printed before login exits.
200 .El
201 .Pp
202 Other
203 .Nm login
204 programs typically print all sorts of information by default, such as
205 last time you logged in, if you have mail, and system message files.
206 This version of
207 .Nm login
208 does not, so there is no reason for
209 .Pa .hushlogin
210 files or similar. We feel that these tasks are best left to the user's
211 shell, but the
212 .Li login_program
213 facility allows for a shell independent solution, if that is desired.
214 .Sh EXAMPLES
215 A
216 .Pa login.conf
217 file could look like:
218 .Bd -literal -offset indent
219 default:\\
220 :motd=/etc/motd,/etc/motd.local:\\
221 :limits=/etc/limits.conf:
222 .Ed
223 .Pp
224 The
225 .Pa limits.conf
226 file consists of a table with four whitespace separated fields. First
227 field is a username or a groupname (prefixed with
228 .Sq @ ) ,
229 or
230 .Sq * .
231 Second field is
232 .Sq soft ,
233 .Sq hard ,
234 or
235 .Sq -
236 (the last meaning both soft and hard).
237 Third field is a limit name (such as
238 .Sq cpu
239 or
240 .Sq core ) .
241 Last field is the limit value (a number or
242 .Sq -
243 for unlimited). In the case of data sizes, the value is in kilobytes,
244 and cputime is in minutes.
245 .Sh SEE ALSO
246 .Xr su 1 ,
247 .Xr login.access 5 ,
248 .Xr getty 8 ,
249 .Xr telnetd 8
250 .Sh AUTHORS
251 This login program was written for the Heimdal Kerberos 5
252 implementation. The login.access code was written by Wietse Venema.
253 .\".Sh BUGS