829cefbc4d7112d8946bb08c7bb92b051ce42783
[openafs.git] / doc / man-pages / pod8 / uss_add.pod
1 =head1 NAME
2
3 uss_add - Creates a user account (deprecated)
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<uss add> S<<< B<-user> <I<login name>> >>> S<<< [B<-realname> <I<full name in quotes>>] >>>
11     S<<< [B<-pass> <I<initial password>>] >>>
12     [B<-pwexpires> <I<< password expires in [0..254] days (0 => never) >>>]
13     S<<< [B<-server> <I<file server for home volume>>] >>>
14     S<<< [B<-partition> <I<file server's disk partition for home volume>>] >>>
15     S<<< [B<-mount> <I<home directory mount point>>] >>>
16     S<<< [B<-uid> <I<uid to assign the user>>] >>>
17     S<<< [B<-template> <I<pathname of template file>>] >>>
18     [B<-verbose>] S<<< [B<-var> <I<auxiliary argument pairs (Num val)>>+] >>>
19     S<<< [B<-cell> <I<cell name>>] >>> S<<< [B<-admin> <I<administrator to authenticate>>] >>>
20     [B<-dryrun>] [B<-skipauth>] [B<-overwrite>] [B<-help>]
21
22 B<uss ad> S<<< B<-us> <I<login name>> >>> S<<< [B<-r> <I<full name in quotes>>] >>>
23     S<<< [B<-pas> <I<initial password>>] >>>
24     [B<-pw> <I<< password expires in [0..254] days (0 => never) >>>]
25     S<<< [B<-se> <I<FileServer for home volume>>] >>>
26     S<<< [B<-par> <I<FileServer's disk partition for home volume>>] >>>
27     S<<< [B<-m> <I<home directory mount point>>] >>>
28     S<<< [B<-ui> <I<uid to assign the user>>] >>>
29     S<<< [B<-t> <I<pathname of template file>>] >>> [B<-ve>]
30     S<<< [B<-va> <I<auxiliary argument pairs (Num val)>>+] >>> S<<< [B<-c> <I<cell name>>] >>>
31     S<<< [B<-a> <I<administrator to authenticate>>] >>> [B<-d>] [B<-sk>] [B<-o>]
32     [B<-h>]
33
34 =for html
35 </div>
36
37 =head1 CAUTIONS
38
39 The B<uss> command suite is currently designed for cells using the
40 obsolete Authentication Server, and therefore is primarily useful for
41 sites that have not yet migrated to a Kerberos version 5 KDC. The
42 Authentication Server and supporting commands will be removed in a future
43 version of OpenAFS, which may include B<uss> unless someone who finds it
44 useful converts it to work with a Kerberos version 5 KDC.
45
46 =head1 DESCRIPTION
47
48 The B<uss add> command creates entries in the Protection Database and
49 Authentication Database for the user name specified by the B<-user>
50 argument. By default, the Protection Server automatically allocates an AFS
51 user ID (UID) for the new user; to specify an alternate AFS UID, include
52 the B<-uid> argument. If a password is provided with the B<-pass>
53 argument, it is stored as the user's password in the Authentication
54 Database after conversion into a form suitable for use as an encryption
55 key. Otherwise, the string C<changeme> is assigned as the user's initial
56 password.
57
58 The other results of the command depend on which instructions and which of
59 a defined set of variables appear in the template file specified with the
60 B<-template> argument. Many of the command's arguments supply a value for
61 one of the defined variables, and failure to provide an argument when the
62 corresponding variable appears in the template file halts the account
63 creation process at the point where the command interpreter first
64 encounters the variable in the template file.
65
66 To create multiple accounts with a single command, use the B<uss bulk>
67 command. To delete accounts with a single command, use the B<uss delete>
68 command.
69
70 =head1 OPTIONS
71
72 =over 4
73
74 =item B<-user> <I<login name>>
75
76 Names the user's Authentication Database and Protection Database
77 entries. It can include up to eight alphanumeric characters, but not any
78 of the following characters: C<:> (colon), C<@> (at-sign), C<.> (period),
79 space, or newline. Because it becomes the username (the name under which a
80 user logs in), it is best not to include shell metacharacters and to obey
81 the restrictions that many operating systems impose on usernames (usually,
82 to contain no more than eight lowercase letters).
83
84 Corresponding variable in the template file: $USER.
85
86 =item B<-realname> <I<full name in quotes>>
87
88 Specifies the user's full name. If it contains spaces or punctuation,
89 surround it with double quotes. If not provided, it defaults to the user
90 name provided with the B<-user> argument.
91
92 Corresponding variable in the template file: $NAME. Many operating systems
93 include a field for the full name in a user's entry in the local password
94 file (F</etc/passwd> or equivalent), and this variable can be used to pass
95 a value to be used in that field.
96
97 =item B<-pass> <I<initial password>>
98
99 Specifies the user's initial password. Although the AFS commands that
100 handle passwords accept strings of virtually unlimited length, it is best
101 to use a password of eight characters or less, which is the maximum length
102 that many applications and utilities accept. If not provided, this
103 argument defaults to the string C<changeme>.
104
105 Corresponding variable in the template file: none.
106
107 =item B<-pwexpires> <I<password expiration>>
108
109 Sets the number of days after a user's password is changed that it remains
110 valid. Provide an integer from the range C<1> through C<254> to specify
111 the number of days until expiration, or the value C<0> to indicate that
112 the password never expires (the default).
113
114 When the password becomes invalid (expires), the user is unable to
115 authenticate, but has 30 more days in which to issue the B<kpasswd>
116 command to change the password (after that, only an administrator can
117 change it).
118
119 Corresponding variable in the template file: $PWEXPIRES.
120
121 =item B<-server> <I<file server name>>
122
123 Names the file server machine on which to create the new user's volume. It
124 is best to provide a fully qualified hostname (for example,
125 C<fs1.example.com>), but an abbreviated form is acceptable provided that the
126 cell's naming service is available to resolve it at the time the volume is
127 created.
128
129 Corresponding variable in the template file: $SERVER.
130
131 =item B<-partition> <I<file server partition>>
132
133 Specifies the partition on which to create the user's volume; it must be
134 on the file server machine named by the B<-server> argument. Provide the
135 complete partition name (for example F</vicepa>) or one of the following
136 abbreviated forms:
137
138    /vicepa     =     vicepa      =      a      =      0
139    /vicepb     =     vicepb      =      b      =      1
140
141 After F</vicepz> (for which the index is 25) comes
142
143    /vicepaa    =     vicepaa     =      aa     =      26
144    /vicepab    =     vicepab     =      ab     =      27
145
146 and so on through
147
148    /vicepiu    =     vicepiu     =      iu     =      254
149
150 Corresponding variable in the template file: $PART.
151
152 =item B<-mount> <I<home directory mount point>>
153
154 Specifies the pathname for the user's home directory. Partial pathnames
155 are interpreted relative to the current working directory.
156
157 Specify the read/write path to the directory, to avoid the failure that
158 results from attempting to create a new mount point in a read-only
159 volume. By convention, the read/write path is indicated by placing a
160 period before the cell name at the pathname's second level (for example,
161 F</afs/.example.com>). For further discussion of the concept of read/write and
162 read-only paths through the filespace, see the B<fs mkmount> reference
163 page.
164
165 Corresponding variable in template: $MTPT, but in the template file's C<V>
166 instruction only. Occurrences of the $MTPT variable in template
167 instructions that follow the C<V> instruction take their value from the
168 C<V> instruction's I<mount_point> field. Thus the value of this command
169 line argument becomes the value for the $MTPT variable in instructions
170 that follow the C<V> instruction only if the string $MTPT appears alone in
171 the C<V> instruction's I<mount_point> field.
172
173 =item B<-uid> <I<uid to assign the user>>
174
175 Specifies a positive integer other than 0 (zero) to assign as the user's
176 AFS UID. If this argument is omitted, the Protection Server assigns an AFS
177 UID that is one greater than the current value of the C<max user id>
178 counter (use the B<pts listmax> command to display the counter). If
179 including this argument, it is best first to use the B<pts examine>
180 command to verify that no existing account already has the desired AFS
181 UID; it one does, the account creation process terminates with an error.
182
183 Corresponding variable in the template file: $UID.
184
185 =item B<-template> <I<pathname of template file>>
186
187 Specifies the pathname of the template file. If this argument is omitted,
188 the command interpreter searches the following directories in the
189 indicated order for a file called C<uss.template>:
190
191 =over 4
192
193 =item *
194
195 The current working directory.
196
197 =item *
198
199 F</afs/I<cellname>/common/uss>, where I<cellname> names the local cell.
200
201 =item *
202
203 F</etc>
204
205 =back
206
207 If the issuer provides a filename other than C<uss.template> but without a
208 pathname, the command interpreter searches for it in the indicated
209 directories. If the issuer provides a full or partial pathname, the
210 command interpreter consults the specified file only; it interprets
211 partial pathnames relative to the current working directory.
212
213 If the specified template file is empty (zero-length), the command creates
214 Protection and Authentication Database entries only.
215
216 L<uss(5)> details the file's format.
217
218 =item B<-verbose>
219
220 Produces on the standard output stream a detailed trace of the command's
221 execution. If this argument is omitted, only warnings and error messages
222 appear.
223
224 =item B<-var> <I<auxilliary argument pairs>>
225
226 Specifies values for each of the number variables $1 through $9 that can
227 appear in the template file. Use the number variables to assign values to
228 variables in the B<uss> template file that are not part of the standard
229 set.
230
231 Corresponding variables in the template file: $1 through $9.
232
233 For each instance of this argument, provide two parts in the indicated
234 order, separated by a space:
235
236 =over 4
237
238 =item *
239
240 The integer from the range C<1> through C<9> that matches the variable in
241 the template file. Do not precede it with a dollar sign.
242
243 =item *
244
245 A string of alphanumeric characters to assign as the value of the
246 variable.
247
248 =back
249
250 See the chapter on uss in the I<OpenAFS Administration Guide> for further
251 explanation.
252
253 =item B<-cell> <I<cell name>>
254
255 Specifies the cell in which to run the command. For more details, see
256 L<uss(8)>.
257
258 =item B<-admin> <I<administrator to authenticate>>
259
260 Specifies the AFS user name under which to establish authenticated
261 connections to the AFS server processes that maintain the various
262 components of a user account. For more details, see L<uss(8)>.
263
264 =item B<-dryrun>
265
266 Reports actions that the command interpreter needs to perform while
267 executing the command, without actually performing them. For more details,
268 see L<uss(8)>.
269
270 =item B<-skipauth>
271
272 Prevents authentication with the AFS Authentication Server, allowing a
273 site using Kerberos to substitute that form of authentication.
274
275 =item B<-overwrite>
276
277 Overwrites any directories, files and links that exist in the file system
278 and for which there are definitions in C<D>, C<E>, C<F>, C<L>, or C<S>
279 instructions in the template file named by the B<-template> argument. If
280 this flag is omitted, the command interpreter prompts once for
281 confirmation that it is to overwrite all such elements.
282
283 =item B<-help>
284
285 Prints the online help for this command. All other valid options are
286 ignored.
287
288 =back
289
290 =head1 EXAMPLES
291
292 The combination of the following example uss add command and C<V>
293 instruction in a template file called C<uss.tpl> creates Protection and
294 Authentication Database entries named C<smith>, and a volume called
295 C<user.smith> with a quota of 2500 kilobyte blocks, mounted at the
296 pathname F</afs/example.com/usr/smith>. The access control list (ACL) on the
297 mount point grants C<smith> all rights.
298
299 The issuer of the B<uss add> command provides only the template file's
300 name, not its complete pathname, because it resides in the current working
301 directory. The command and C<V> instruction appear here on two lines only
302 for legibility; there are no line breaks in the actual instruction or
303 command.
304
305    V user.$USER $SERVER.example.com /vice$PART $1 \
306        /afs/example.com/usr/$USER $UID $USER all
307
308    % uss add -user smith -realname "John Smith" -pass js_pswd \
309        -server fs2 -partition b -template uss.tpl -var 1 2500
310
311 =head1 PRIVILEGE REQUIRED
312
313 The issuer (or the user named by the B<-admin> argument) must belong to
314 the system:administrators group in the Protection Database and must have
315 the C<ADMIN> flag turned on in his or her Authentication Database entry.
316
317 If the template contains a C<V> instruction, the issuer must be listed in
318 the F</usr/afs/etc/UserList> file and must have at least C<a> (administer)
319 and C<i> (insert) permissions on the ACL of the directory that houses the
320 new mount point. If the template file includes instructions for creating
321 other types of objects (directories, files or links), the issuer must have
322 each privilege necessary to create them.
323
324 =head1 SEE ALSO
325
326 L<UserList(5)>,
327 L<uss(5)>,
328 L<fs_mkmount(1)>,
329 L<uss(8)>,
330 L<uss_bulk(8)>,
331 L<uss_delete(8)>
332
333 =head1 COPYRIGHT
334
335 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
336
337 This documentation is covered by the IBM Public License Version 1.0.  It was
338 converted from HTML to POD by software written by Chas Williams and Russ
339 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.