doc/man-pages/pod8/uss_add.pod

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