doc/man-pages/pod8/uss_add.pod

   1 =head1 NAME
   2
   3 uss_add - Creates a user account
   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 DESCRIPTION
  38
  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
  47 password.
  48
  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.
  56
  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>
  59 command.
  60
  61 =head1 OPTIONS
  62
  63 =over 4
  64
  65 =item B<-user> <I<login name>>
  66
  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).
  74
  75 Corresponding variable in the template file: $USER.
  76
  77 =item B<-realname> <I<full name in quotes>>
  78
  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.
  82
  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.
  87
  88 =item B<-pass> <I<initial password>>
  89
  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>.
  95
  96 Corresponding variable in the template file: none.
  97
  98 =item B<-pwexpires> <I<password expiration>>
  99
 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).
 104
 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
 108 change it).
 109
 110 Corresponding variable in the template file: $PWEXPIRES.
 111
 112 =item B<-server> <I<file server name>>
 113
 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
 118 created.
 119
 120 Corresponding variable in the template file: $SERVER.
 121
 122 =item B<-partition> <I<file server partition>>
 123
 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
 127 abbreviated forms:
 128
 129    /vicepa     =     vicepa      =      a      =      0
 130    /vicepb     =     vicepb      =      b      =      1
 131
 132 After F</vicepz> (for which the index is 25) comes
 133
 134    /vicepaa    =     vicepaa     =      aa     =      26
 135    /vicepab    =     vicepab     =      ab     =      27
 136
 137 and so on through
 138
 139    /vicepiv    =     vicepiv     =      iv     =      255
 140
 141 Corresponding variable in the template file: $PART.
 142
 143 =item B<-mount> <I<home directory mount point>>
 144
 145 Specifies the pathname for the user's home directory. Partial pathnames
 146 are interpreted relative to the current working directory.
 147
 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
 154 page.
 155
 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.
 163
 164 =item B<-uid> <I<uid to assign the user>>
 165
 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.
 173
 174 Corresponding variable in the template file: $UID.
 175
 176 =item B<-template> <I<pathname of template file>>
 177
 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>:
 181
 182 =over 4
 183
 184 =item *
 185
 186 The current working directory.
 187
 188 =item *
 189
 190 F</afs/I<cellname>/common/uss>, where I<cellname> names the local cell.
 191
 192 =item *
 193
 194 F</etc>
 195
 196 =back
 197
 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.
 203
 204 If the specified template file is empty (zero-length), the command creates
 205 Protection and Authentication Database entries only.
 206
 207 L<uss(5)> details the file's format.
 208
 209 =item B<-verbose>
 210
 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
 213 appear.
 214
 215 =item B<-var> <I<auxilliary argument pairs>>
 216
 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
 220 set.
 221
 222 Corresponding variables in the template file: $1 through $9.
 223
 224 For each instance of this argument, provide two parts in the indicated
 225 order, separated by a space:
 226
 227 =over 4
 228
 229 =item *
 230
 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.
 233
 234 =item *
 235
 236 A string of alphanumeric characters to assign as the value of the
 237 variable.
 238
 239 =back
 240
 241 See the chapter on uss in the I<IBM AFS Administration Guide> for further
 242 explanation.
 243
 244 =item B<-cell> <I<cell name>>
 245
 246 Specifies the cell in which to run the command. For more details, see
 247 L<uss(8)>.
 248
 249 =item B<-admin> <I<administrator to authenticate>>
 250
 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)>.
 254
 255 =item B<-dryrun>
 256
 257 Reports actions that the command interpreter needs to perform while
 258 executing the command, without actually performing them. For more details,
 259 see L<uss(8)>.
 260
 261 =item B<-skipauth>
 262
 263 Prevents authentication with the AFS Authentication Server, allowing a
 264 site using Kerberos to substitute that form of authentication.
 265
 266 =item B<-overwrite>
 267
 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.
 273
 274 =item B<-help>
 275
 276 Prints the online help for this command. All other valid options are
 277 ignored.
 278
 279 =back
 280
 281 =head1 EXAMPLES
 282
 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.
 289
 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
 294 command.
 295
 296    V user.$USER $SERVER.abc.com /vice$PART $1 \
 297        /afs/abc.com/usr/$USER $UID $USER all
 298
 299    % uss add -user smith -realname "John Smith" -pass js_pswd \
 300        -server fs2 -partition b -template uss.tpl -var 1 2500
 301
 302 =head1 PRIVILEGE REQUIRED
 303
 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.
 307
 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.
 314
 315 =head1 SEE ALSO
 316
 317 L<UserList(5)>,
 318 L<uss(5)>,
 319 L<fs_mkmount(1)>,
 320 L<uss(8)>,
 321 L<uss_bulk(8)>,
 322 L<uss_delete(8)>
 323
 324 =head1 COPYRIGHT
 325
 326 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 327
 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.