3 uss_add - Creates a user account
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>]
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>]
39 The B<uss add> command creates entries in the Protection Database and
40 Authentication Database for the user name specified by the B<-user>
41 argument. By default, the Protection Server automatically allocates an AFS
42 user ID (UID) for the new user; to specify an alternate AFS UID, include
43 the B<-uid> argument. If a password is provided with the B<-pass>
44 argument, it is stored as the user's password in the Authentication
45 Database after conversion into a form suitable for use as an encryption
46 key. Otherwise, the string C<changeme> is assigned as the user's initial
49 The other results of the command depend on which instructions and which of
50 a defined set of variables appear in the template file specified with the
51 B<-template> argument. Many of the command's arguments supply a value for
52 one of the defined variables, and failure to provide an argument when the
53 corresponding variable appears in the template file halts the account
54 creation process at the point where the command interpreter first
55 encounters the variable in the template file.
57 To create multiple accounts with a single command, use the B<uss bulk>
58 command. To delete accounts with a single command, use the B<uss delete>
65 =item B<-user> <I<login name>>
67 Names the user's Authentication Database and Protection Database
68 entries. It can include up to eight alphanumeric characters, but not any
69 of the following characters: C<:> (colon), C<@> (at-sign), C<.> (period),
70 space, or newline. Because it becomes the username (the name under which a
71 user logs in), it is best not to include shell metacharacters and to obey
72 the restrictions that many operating systems impose on usernames (usually,
73 to contain no more than eight lowercase letters).
75 Corresponding variable in the template file: $USER.
77 =item B<-realname> <I<full name in quotes>>
79 Specifies the user's full name. If it contains spaces or punctuation,
80 surround it with double quotes. If not provided, it defaults to the user
81 name provided with the B<-user> argument.
83 Corresponding variable in the template file: $NAME. Many operating systems
84 include a field for the full name in a user's entry in the local password
85 file (F</etc/passwd> or equivalent), and this variable can be used to pass
86 a value to be used in that field.
88 =item B<-pass> <I<initial password>>
90 Specifies the user's initial password. Although the AFS commands that
91 handle passwords accept strings of virtually unlimited length, it is best
92 to use a password of eight characters or less, which is the maximum length
93 that many applications and utilities accept. If not provided, this
94 argument defaults to the string C<changeme>.
96 Corresponding variable in the template file: none.
98 =item B<-pwexpires> <I<password expiration>>
100 Sets the number of days after a user's password is changed that it remains
101 valid. Provide an integer from the range C<1> through C<254> to specify
102 the number of days until expiration, or the value C<0> to indicate that
103 the password never expires (the default).
105 When the password becomes invalid (expires), the user is unable to
106 authenticate, but has 30 more days in which to issue the B<kpasswd>
107 command to change the password (after that, only an administrator can
110 Corresponding variable in the template file: $PWEXPIRES.
112 =item B<-server> <I<file server name>>
114 Names the file server machine on which to create the new user's volume. It
115 is best to provide a fully qualified hostname (for example,
116 C<fs1.abc.com>), but an abbreviated form is acceptable provided that the
117 cell's naming service is available to resolve it at the time the volume is
120 Corresponding variable in the template file: $SERVER.
122 =item B<-partition> <I<file server partition>>
124 Specifies the partition on which to create the user's volume; it must be
125 on the file server machine named by the B<-server> argument. Provide the
126 complete partition name (for example F</vicepa>) or one of the following
129 /vicepa = vicepa = a = 0
130 /vicepb = vicepb = b = 1
132 After F</vicepz> (for which the index is 25) comes
134 /vicepaa = vicepaa = aa = 26
135 /vicepab = vicepab = ab = 27
139 /vicepiv = vicepiv = iv = 255
141 Corresponding variable in the template file: $PART.
143 =item B<-mount> <I<home directory mount point>>
145 Specifies the pathname for the user's home directory. Partial pathnames
146 are interpreted relative to the current working directory.
148 Specify the read/write path to the directory, to avoid the failure that
149 results from attempting to create a new mount point in a read-only
150 volume. By convention, the read/write path is indicated by placing a
151 period before the cell name at the pathname's second level (for example,
152 F</afs/.abc.com>). For further discussion of the concept of read/write and
153 read-only paths through the filespace, see the B<fs mkmount> reference
156 Corresponding variable in template: $MTPT, but in the template file's C<V>
157 instruction only. Occurrences of the $MTPT variable in template
158 instructions that follow the C<V> instruction take their value from the
159 C<V> instruction's I<mount_point> field. Thus the value of this command
160 line argument becomes the value for the $MTPT variable in instructions
161 that follow the C<V> instruction only if the string $MTPT appears alone in
162 the C<V> instruction's I<mount_point> field.
164 =item B<-uid> <I<uid to assign the user>>
166 Specifies a positive integer other than 0 (zero) to assign as the user's
167 AFS UID. If this argument is omitted, the Protection Server assigns an AFS
168 UID that is one greater than the current value of the C<max user id>
169 counter (use the B<pts listmax> command to display the counter). If
170 including this argument, it is best first to use the B<pts examine>
171 command to verify that no existing account already has the desired AFS
172 UID; it one does, the account creation process terminates with an error.
174 Corresponding variable in the template file: $UID.
176 =item B<-template> <I<pathname of template file>>
178 Specifies the pathname of the template file. If this argument is omitted,
179 the command interpreter searches the following directories in the
180 indicated order for a file called C<uss.template>:
186 The current working directory.
190 F</afs/I<cellname>/common/uss>, where I<cellname> names the local cell.
198 If the issuer provides a filename other than C<uss.template> but without a
199 pathname, the command interpreter searches for it in the indicated
200 directories. If the issuer provides a full or partial pathname, the
201 command interpreter consults the specified file only; it interprets
202 partial pathnames relative to the current working directory.
204 If the specified template file is empty (zero-length), the command creates
205 Protection and Authentication Database entries only.
207 L<uss(5)> details the file's format.
211 Produces on the standard output stream a detailed trace of the command's
212 execution. If this argument is omitted, only warnings and error messages
215 =item B<-var> <I<auxilliary argument pairs>>
217 Specifies values for each of the number variables $1 through $9 that can
218 appear in the template file. Use the number variables to assign values to
219 variables in the B<uss> template file that are not part of the standard
222 Corresponding variables in the template file: $1 through $9.
224 For each instance of this argument, provide two parts in the indicated
225 order, separated by a space:
231 The integer from the range C<1> through C<9> that matches the variable in
232 the template file. Do not precede it with a dollar sign.
236 A string of alphanumeric characters to assign as the value of the
241 See the chapter on uss in the I<IBM AFS Administration Guide> for further
244 =item B<-cell> <I<cell name>>
246 Specifies the cell in which to run the command. For more details, see
249 =item B<-admin> <I<administrator to authenticate>>
251 Specifies the AFS user name under which to establish authenticated
252 connections to the AFS server processes that maintain the various
253 components of a user account. For more details, see L<uss(8)>.
257 Reports actions that the command interpreter needs to perform while
258 executing the command, without actually performing them. For more details,
263 Prevents authentication with the AFS Authentication Server, allowing a
264 site using Kerberos to substitute that form of authentication.
268 Overwrites any directories, files and links that exist in the file system
269 and for which there are definitions in C<D>, C<E>, C<F>, C<L>, or C<S>
270 instructions in the template file named by the B<-template> argument. If
271 this flag is omitted, the command interpreter prompts once for
272 confirmation that it is to overwrite all such elements.
276 Prints the online help for this command. All other valid options are
283 The combination of the following example uss add command and C<V>
284 instruction in a template file called C<uss.tpl> creates Protection and
285 Authentication Database entries named C<smith>, and a volume called
286 C<user.smith> with a quota of 2500 kilobyte blocks, mounted at the
287 pathname F</afs/abc.com/usr/smith>. The access control list (ACL) on the
288 mount point grants C<smith> all rights.
290 The issuer of the B<uss add> command provides only the template file's
291 name, not its complete pathname, because it resides in the current working
292 directory. The command and C<V> instruction appear here on two lines only
293 for legibility; there are no line breaks in the actual instruction or
296 V user.$USER $SERVER.abc.com /vice$PART $1 \
297 /afs/abc.com/usr/$USER $UID $USER all
299 % uss add -user smith -realname "John Smith" -pass js_pswd \
300 -server fs2 -partition b -template uss.tpl -var 1 2500
302 =head1 PRIVILEGE REQUIRED
304 The issuer (or the user named by the B<-admin> argument) must belong to
305 the system:administrators group in the Protection Database and must have
306 the C<ADMIN> flag turned on in his or her Authentication Database entry.
308 If the template contains a C<V> instruction, the issuer must be listed in
309 the F</usr/afs/etc/UserList> file and must have at least C<a> (administer)
310 and C<i> (insert) permissions on the ACL of the directory that houses the
311 new mount point. If the template file includes instructions for creating
312 other types of objects (directories, files or links), the issuer must have
313 each privilege necessary to create them.
326 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
328 This documentation is covered by the IBM Public License Version 1.0. It was
329 converted from HTML to POD by software written by Chas Williams and Russ
330 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.