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.