3 uss - Provides instructions for the uss add command
7 The uss template file defines the components of an AFS user account that
8 the B<uss add> command (or B<add> instruction in a B<uss> bulk input file)
9 creates. Use the B<-template> argument to the B<uss add> or B<uss bulk>
10 command to identify the template file.
12 =head2 Summary of Template File Instructions
14 The template file can include the following instructions, each on its own
15 line. A more detailed description of each instruction's syntax follows
22 Imposes restrictions on user passwords and authentication attempts.
30 Creates a single-line file.
34 Creates a file by copying a prototype.
38 Defines a directory that is one of a set of parent directories into which
39 the B<uss> command interpreter evenly distributes newly created home
48 Creates a symbolic link.
52 Creates a volume, mounts it in the file space and sets the ACL on the
61 If the template file is empty (zero-length), the B<uss add> command or
62 C<add> instruction in a bulk input file only creates an entry in the
63 Protection and Authentication Databases, naming them according to the name
64 specified with the B<uss add> command's B<-user> argument, or in the bulk
65 input file C<add> instruction's I<username> field.
67 =head2 The A Instruction for Setting the Default Treatment of Volumes
69 The C<A> instruction in a uss template file enhances cell security by
70 imposing the following restrictions on users' password choice and
71 authentication attempts. For further information on these limits, see the
72 I<OpenAFS Administration Guide> and the B<kas setfields> reference page.
78 Limiting the user's password lifetime. When the lifetime expires, the user
79 can no longer authenticate using that password, and must change it.
83 Prohibiting the reuse of the user's 20 most recently used passwords.
87 Limiting the number of consecutive times that a user can provide an
88 incorrect password during authentication, and for how long the
89 Authentication Server refuses further authentication attempts after the
90 limit is exceeded (referred to as an I<account lockout>). For regular user
91 accounts in most cells, the recommended limit is nine and lockout time is
96 The instruction has the following syntax:
98 A <username> <lifetime> <reuse> <failures> <locktime>
106 Indicates a security-enhancing instruction. It must be a capital letter.
110 Names the Authentication Database entry on which to impose security
111 restrictions. Specify the value $USER to read in the username from the
112 B<uss add> command's B<-user> argument, or from the I<username> field of
113 an C<add> instruction in a bulk input file.
117 Sets the number of days after the user's password is changed that it
118 remains valid. When the password becomes invalid (expires), the user is
119 unable to authenticate, but has 30 more days in which to issue the
120 B<kpasswd> command to change the password (after that, only an
121 administrator can change it).
123 Specify an integer from the range C<1> through C<254> to specify the
124 number of days until expiration, the value C<0> to indicate that the
125 password never expires, or the value $PWEXPIRES to read in the number
126 of days from the B<uss add> or B<uss bulk> command's B<-pwexpires>
127 argument. If the C<A> instruction does not appear in the template file,
128 the default is for the user's password never to expire.
132 Determines whether or not the user can change his or her password (using
133 the B<kpasswd> or B<kas setpassword> command) to one that is similar to
134 any of the last twenty passwords. The acceptable values are C<reuse> to
135 allow reuse and C<noreuse> to prohibit it. If the C<A> instruction does
136 not appear in the template file, the default is to allow password reuse.
140 Sets the number of consecutive times the user can provide an incorrect
141 password during authentication (using the B<klog> command or a login
142 utility that grants AFS tokens). When the user exceeds the limit, the
143 Authentication Server rejects further authentication attempts for the
144 amount of time specified in the <locktime> field.
146 Specify an integer from the range C<1> through C<254> to specify the
147 number of failures permitted, or the value C<0> to indicate that there is
148 no limit to the number of unsuccessful attempts. If the C<A> instruction
149 does not appear in the template file, the default is to allow an unlimited
154 Specifies how long the Authentication Server refuses authentication
155 attempts from a user who has exceeded the failure limit set in the
158 Specify a number of hours and minutes (I<hh:mm>) or minutes only (I<mm>),
159 from the range C<01> (one minute) through C<36:00> (36 hours). The
160 Authentication Server automatically reduces any larger value to C<36:00>
161 and also rounds up any non-zero value to the next higher multiple of 8.5
162 minutes. A value of C<0> (zero) sets an infinite lockout time; an
163 administrator must always issue the B<kas unlock> command to unlock the
168 =head2 The D Instruction for Creating a Directory
170 The C<D> instruction in a uss template file creates a directory. Its
171 intended use is to create a subdirectory in the user home directory
172 created by the C<V> instruction in the template file.
174 Any number of C<D> instructions can appear in the template file. If any
175 variables in the instruction take their values from the C<V> instruction
176 (notably, the $MTPT variable), the instruction must follow the C<V>
177 instruction in the file.
179 Although it is possible to use the C<D> instruction to create a directory
180 on the local disk of the machine where the B<uss> command is issued, it is
181 not recommended. The preferred method for automated creation of
182 directories on a local disk is the B<package> program. Two complications
183 arise if the <pathname> field refers to a local disk directory:
189 The B<uss> command prints a warning message because it cannot associate an
190 access control list (ACL) with a local disk directory. It creates the
191 directory nonetheless, and some syntactically correct value must appear in
192 the instruction's <ACL> field.
196 To designate any user other than the issuer as the new directory's owner,
197 the issuer must log onto the machine as the local superuser C<root>. For
198 local disk directories, only the local superuser C<root> is allowed to
199 issue the UNIX B<chown> command that the B<uss> command interpreter
200 invokes to change the owner from the default value (the directory's
201 creator, which in this case is the issuer of the B<uss> command). The
202 issuer must then also use the B<-admin> argument to the B<uss add> or
203 B<uss bulk> command to authenticate as a privileged AFS administrator,
204 which is required for creating the Authentication Database and Protection
205 Database entries that the B<uss> command interpreter always creates for a
210 The instruction has the following syntax:
212 D <pathname> <mode> <owner> <ACL>
220 Indicates a directory creation instruction. It must be a capital letter.
224 Specifies the directory's full pathname. It can include variables.
226 Specify the read/write path to the directory, to avoid the failure that
227 results from attempting to create a new directory in a read-only
228 volume. By convention, the read/write path is indicated by placing a
229 period before the cell name at the pathname's second level (for example,
230 F</afs/.abc.com>). For further discussion of the concept of read/write and
231 read-only paths through the filespace, see the reference page for the B<fs
236 Sets the directory's UNIX mode bits. Acceptable values are the standard
237 three- or four-digit numbers corresponding to combinations of
238 permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
239 C<rw-r--r-->. The first (owner) C<x> bit must be turned on to enable
240 access to a directory.
244 Specifies the username or UNIX user ID (UID) of the user to be designated
245 the directory's owner in the output from the UNIX C<ls -ld> command. If
246 the directory resides in AFS, place the $UID variable in this field. If
247 the directory resides on the local disk, this field must be the username
248 or UID of the B<uss> command's issuer, unless the issuer is logged in as
249 the local superuser C<root>.
253 Sets the ACL on the new directory. It must appear even if the new
254 directory resides on the local disk rather than in AFS, but is ignored in
255 that case. Provide one or more paired values, each pair consisting of an
256 AFS username or group name and the desired permissions, in that order.
257 Separate the two parts of the pair, and each pair, with a space. The B<fs
258 setacl> reference page describes the available permissions.
260 For an AFS directory, grant all permissions to the directory's owner at
261 least. Usually that is the new user, in which case the appropriate value
264 It is not possible to grant any permissions to the issuer of the B<uss>
265 command. As the last step in account creation, the B<uss> command
266 interpreter automatically deletes that person from any ACLs set during the
271 =head2 The E Instruction for Creating a Single-line File
273 The C<E> instruction in a uss template file creates a file by echoing a
274 specified character string into it. Its intended use is to create files in
275 the user home directory created by the C<V> instruction in the template
276 file, or in a subdirectory created by a C<D> instruction.
278 Any number of C<E> instructions can appear in the template file. If the
279 file resides in a directory created by a C<D> instruction, the C<E>
280 instruction must follow the C<D> instruction in the file.
282 The C<E> and C<F> instructions have complementary advantages. The
283 character string echoed into the file by an C<E> instruction can be
284 customized for each user, because it can include the standard variables
285 for which the B<uss> command interpreter substitutes the values specified
286 by arguments to the B<uss add> command or fields in a bulk input file
287 B<add> instruction. In contrast, a file created using the C<F> instruction
288 cannot include variables and so has the same content for all
289 users. However, a file created by an C<E> instruction can be a single line
290 only, because no carriage returns (newline characters) are allowed in the
293 Although it is possible to use the C<E> instruction to create a file on
294 the local disk of the machine where the B<uss> command is issued, it is
295 not recommended. The preferred method for automated creation of files on a
296 local disk is the B<package> program. The main complication is that
297 designating any user other than the issuer as the new file's owner
298 requires logging onto the machine as the local superuser C<root>. For
299 local disk files, only the local superuser C<root> is allowed to issue the
300 UNIX B<chown> command that the B<uss> command interpreter invokes to
301 change the owner from the default value (the file's creator, which in this
302 case is the issuer of the B<uss> command). The issuer must then also use
303 the B<-admin> argument to the B<uss add> or B<uss bulk> command to
304 authenticate as a privileged AFS administrator, which is required for
305 creating the Authentication Database and Protection Database entries that
306 the B<uss> command interpreter always creates for a new account.
308 The instruction has the following syntax:
310 E <pathname> <mode> <owner> "<contents>"
318 Indicates a file creation instruction. It must be a capital letter.
322 Specifies the file's full pathname. It can include variables.
324 Specify the read/write path to the file, to avoid the failure that results
325 from attempting to create a new file in a read-only volume. By convention,
326 the read/write path is indicated by placing a period before the cell name
327 at the pathname's second level (for example, F</afs/.abc.com>). For
328 further discussion of the concept of read/write and read-only paths
329 through the filespace, see the reference page for the B<fs mkmount>
334 Sets the file's UNIX mode bits. Acceptable values are the standard three-
335 or four-digit numbers corresponding to combinations of
336 permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
341 Specifies the username or UNIX user ID (UID) of the user to be designated
342 the file's owner in the output from the UNIX C<ls -l> command. If the file
343 resides in AFS, place the $UID variable in this field. If the file
344 resides on the local disk, specify the username or UID of the B<uss>
345 command's issuer; otherwise, the account creation operation halts
350 Specifies the one-line character string to write into the new file.
351 Surround it with double quotes if it contains one or more spaces. It
352 cannot contain the newline character, but can contain any of the standard
353 variables, which the command interpreter resolves as it creates the file.
357 =head2 The F Instruction for Creating a File from a Prototype
359 The C<F> instruction in a uss template file creates a file by copying the
360 contents of an existing file (the <prototype>) into it. Its intended use
361 is to create files in the user home directory created by the C<V>
362 instruction in the template file, or in a subdirectory created by a C<D>
365 Any number of C<F> instructions can appear in the template file. If the
366 file resides in a directory created by a C<D> instruction, the C<F>
367 instruction must follow the C<D> instruction in the file.
369 The C<E> and C<F> instructions have complementary advantages. A file
370 created using the C<F> instruction has the same content for all users,
371 whereas a file created by an C<E> instruction can be customized for each
372 user if it includes variables. However, a file created by an C<E>
373 instruction can be a single line only, whereas the prototype file copied
374 by an C<F> instruction can be any length.
376 Although it is possible to use the C<F> instruction to create a file on
377 the local disk of the machine where the B<uss> command is issued, it is
378 not recommended. The preferred method for automated creation of files on a
379 local disk is the B<package> program. The main complication is that
380 designating any user other than the issuer as the new file's owner
381 requires logging onto the machine as the local superuser C<root>. For
382 local disk files, only the local superuser C<root> is allowed to issue the
383 UNIX B<chown> command that the B<uss> command interpreter invokes to
384 change the owner from the default value (the file's creator, which in this
385 case is the issuer of the B<uss> command). The issuer must then also use
386 the B<-admin> argument to the B<uss add> or B<uss bulk> command to
387 authenticate as a privileged AFS administrator, which is required for
388 creating the Authentication Database and Protection Database entries that
389 the B<uss> command interpreter always creates for a new account.
391 The instruction has the following syntax:
393 F <pathname> <mode> <owner> <prototype_file>
401 Indicates a file creation instruction. It must be a capital letter.
405 Specifies the full pathname of the file to create, including the
406 filename. It can include variables.
408 Specify the read/write path to the file, to avoid the failure that results
409 from attempting to create a new file in a read-only volume. By convention,
410 the read/write path is indicated by placing a period before the cell name
411 at the pathname's second level (for example, F</afs/.abc.com>). For
412 further discussion of the concept of read/write and read-only paths
413 through the filespace, see the reference page for the B<fs mkmount>
418 Sets the file's UNIX mode bits. Acceptable values are the standard three-
419 or four-digit numbers corresponding to combinations of
420 permissions. Examples: C<755> corresponds to C<rwxr-xr-x>, and C<644> to
425 Specifies the username or UNIX user ID (UID) of the user to be designated
426 the file's owner in the output from the UNIX C<ls -l> command. If the file
427 resides in AFS, place the $UID variable in this field. If the file
428 resides on the local disk, specify the username or UID of the B<uss>
429 command's issuer; otherwise, the account creation operation halts
432 =item <prototype_file>
434 Names the AFS or local disk directory that houses the prototype file to
435 copy. The prototype file's name must match the final element in the
440 =head2 The G Instruction for Even Distribution of Home Directories
442 The C<G> instruction in a uss template file creates a directory as one of
443 the set of directories from which the B<uss> command interpreter selects
444 when choosing a new user home directory's parent directory. More
445 specifically, when the $AUTO variable appears in the <mount_point>
446 field of a C<V> instruction, the command interpreter substitutes for it
447 the directory defined by a C<G> instruction that currently has the fewest
450 The instruction's intended use is to distribute user accounts evenly among
451 several directories, rather than using directories that reflect divisions
452 such as departmental affiliation. Distributing home directories in this
453 fashion is useful mainly in very large cells where storing all user home
454 directories under a single parent directory potentially slows directory
455 lookup, or where a workplace-based division results in unevenly sized
456 directories such that some users consistently experience slower directory
457 lookup than others. See the chapter on B<uss> in the I<OpenAFS
458 Administration Guide> for more information.
460 Any number of C<G> instructions can appear in the template file. If the
461 C<V> instruction includes the $AUTO variable, it must appear after all
462 of the C<G> instructions in the file.
464 The instruction has the following syntax:
474 Indicates an instruction that creates a directory to be considered as a
475 value for the $AUTO variable. It must be a capital letter.
479 Specifies the directory's name as either a complete pathname or only the
480 directory name. The choice determines the appropriate format for the
481 <mount_point> field of a C<V> instruction, as discussed in the following
484 Specify the read/write path to the directory, to avoid the failure that
485 results from attempting to create a new mount point in a read-only volume
486 when the $AUTO variable is used in a C<V> instruction's <mount_point>
487 field. By convention, the read/write path is indicated by placing a period
488 before the cell name at the pathname's second level (for example,
489 F</afs/.abc.com>). For further discussion of the concept of read/write and
490 read-only paths through the filespace, see the reference page for the B<fs
495 =head2 The L and S Instructions for Creating a Link
497 The C<L> instruction in a uss template file creates a hard link between
498 two files, as achieved by the standard UNIX B<ln> command. The C<S>
499 instruction creates a symbolic link between two files, as achieved by the
500 standard UNIX C<ln -s> command. A full explanation of links is beyond the
501 scope of this document, but the basic effect is to create a second name
502 for an existing file, enabling access via either name. Creating a link
503 does not create a second copy of the file.
505 AFS allows hard links only if the linked files reside in the same
506 directory, because it becomes difficult to determine which access control
507 list (ACL) applies to the file if the two copies reside in directories
508 with different ACLs. AFS allows symbolic links between two files that
509 reside in different directories, or even different volumes. The File
510 Server uses the ACL associated with the actual file rather than the link.
512 Any number of C<L> and C<S> instructions can appear in the template
513 file. If the existing file or link is to reside in a directory created by
514 a C<D> instruction, or if the existing file was created by an C<E> or C<F>
515 instruction, the C<L> or C<S> instruction must follow the C<D>, C<E>, or
518 The instructions share the following syntax:
520 L <existing_file> <link>
521 S <existing_file> <link>
529 Indicates a hard link creation instruction. It must be a capital letter.
533 Indicates a symbolic link creation instruction. It must be a capital
536 =item <existing_file>
538 Specifies the complete pathname of the existing file.
542 Specifies the complete pathname of the second name for the file.
544 Specify the read/write path to the link, to avoid the failure that results
545 from attempting to create a new link in a read-only volume. By convention,
546 the read/write path is indicated by placing a period before the cell name
547 at the pathname's second level (for example, F</afs/.abc.com>). For
548 further discussion of the concept of read/write and read-only paths
549 through the filespace, see the reference page for the B<fs mkmount>
554 =head2 The V Instruction for Creating and Mounting a Volume
556 The C<V> instruction in a uss template file creates a volume on a
557 specified file server machine and partition and creates an entry for it in
558 the Volume Location Database (VLDB). It mounts the volume at a location in
559 the AFS file space that becomes the user's home directory, then designates
560 the directory's owner and sets its access control list (ACL).
562 Only one C<V> instruction can appear in the template file, and one must
563 appear if the template file contains any instructions at all (is not
564 empty). All other instructions are optional, except that the template must
565 include C<G> instructions if the $AUTO variable appears in it. (The
566 C<V> instruction is not necessarily the first line in the template. If the
567 template includes the $AUTO variable, then the C<G> instructions which
568 provide values for the variable must precede it in the file.)
570 The instruction has the following syntax:
572 V <vname> <server> <partition> <quota> <mount_point> <owner> <ACL>
580 Indicates a volume creation instruction. It must be a capital letter.
584 Specifies the volume's name. To follow the convention for AFS user volume
585 names, specify the value C<user.$USER>. Provide a value for the $USER
586 variable via the B<uss add> command's B<-user> argument or the <username>
587 field in the bulk input file B<add> instruction.
591 Names the file server machine on which to create the new user's volume. It
592 is best to provide the fully-qualified hostname (for example,
593 C<fs1.abc.com>), but an abbreviated form is acceptable provided that the
594 cell's naming service is available to resolve it at the time the volume is
595 created. To read in the value from the B<uss add> command's B<-server>
596 argument, specify the value $SERVER.
600 Specifies the partition on which to create the user's volume; it must be
601 on the file server machine named in the <server> field. Identify the
602 partition by its complete name (for example, F</vicepa>) or use or use one
603 of the following abbreviations.
605 /vicepa = vicepa = a = 0
606 /vicepb = vicepb = b = 1
608 After F</vicepz> (for which the index is 25) comes
610 /vicepaa = vicepaa = aa = 26
611 /vicepab = vicepab = ab = 27
615 /vicepiv = vicepiv = iv = 255
617 To read in the value from the B<uss add> command's B<-partition> argument,
618 specify the value $PART.
622 Sets the maximum number of kilobyte blocks the volume can occupy on the
623 file server machine's disk. Specify an integer constant if all volumes
624 have the same quota (C<1024> equals a megabyte), or use one of the number
625 variables ($1 through $9) to assign different values to different volumes.
629 Creates a mount point for the volume, which serves as the volume's root
630 directory. Include the $USER variable as part of the pathname to follow
631 the convention that user home directory names include the username.
633 Specify the read/write path to the mount point, to avoid the failure that
634 results from attempting to create a new mount point in a read-only
635 volume. By convention, the read/write path is indicated by placing a
636 period before the cell name at the pathname's second level (for example,
637 F</afs/.abc.com>). If the $AUTO variable appears in this field, the
638 directories named by each C<G> instruction possibly already indicate the
639 read/write path. For further discussion of the concept of read/write and
640 read-only paths through the filespace, see the reference page for the B<fs
645 Specifies the username or UNIX user ID (UID) of the user to be designated
646 the mount point's owner in the output from the UNIX C<ls -ld> command. To
647 follow the convention for home directory ownership, place the value
652 Sets the ACL on the new directory. Provide one or more paired values, each
653 pair consisting of an AFS username or group name and the desired
654 permissions, in that order. Separate the two parts of the pair, and each
655 pair, with a space. The B<fs setacl> reference page describes the
656 available permissions.
658 Grant all permissions to the new user at least. The appropriate
659 value is C<$USER all>.
661 AFS automatically grants the system:administrators group all permissions
662 as well. It is not possible to grant any permissions to the issuer of the
663 B<uss> command. As the last step in account creation, the B<uss> command
664 interpreter automatically deletes that user from any ACLs set during the
669 =head2 The X Instruction for Running a Command
671 The C<X> instruction in a uss template file runs the indicated command,
672 which can be a standard UNIX or AFS command. It can include any variables
673 from the template file, which the B<uss> command interpreter resolves
674 before passing the command on to the appropriate other command
675 interpreter. It must be a single line only, however (cannot contain
676 carriage returns or newline characters).
678 Any number of C<X> instructions can appear in the template file. If an
679 instruction manipulates an element created by another instruction, it must
680 follow that instruction in the file.
682 The instruction has the following syntax:
692 Indicates a command execution instruction. It must be a capital letter.
696 Specifies the command to run. Surround it with double quotes as shown if
697 it contains one or more spaces. It can contain any variables from the
698 template file, but not newline characters.
704 The following example A instruction sets a password lifetime of 254 days,
705 prohibits password reuse, limits the number of consecutive failed
706 authentication attempts to nine and sets the corresponding locktime to
707 25:30 minutes (which is a multiple of 8.5 minutes). The username is read
708 in from the B<-user> argument to the B<uss add> command or from the
709 I<username> field in each C<add> instruction in a bulk input file.
711 A $USER 254 noreuse 9 25:30
713 The following example C<D> instruction creates a directory called
714 F<public> in a new user's home directory, designates the user as the
715 directory's owner, and grants him or her all ACL permissions.
717 D $MTPT/public 0755 $UID $USER all
719 The following example C<E> instruction creates a file in the current
720 working directory called F<I<username>.etcp>. The contents are an entry
721 suitable for incorporating into the cell's global F</etc/password> file.
723 E $USER.etcp 0644 root "$USER:X:$UID:10:$NAME:$MTPT:/bin/csh"
725 The following example C<F> instruction, appropriate for the ABC
726 Corporation cell, copies a prototype F<.login> file into the user's home
729 F $MTPT/.login 0644 $UID /afs/abc.com/common/uss/skel/.login
731 In the following example, the State University cell's administrators
732 have decided to distribute user home directories evenly into three
733 directories. They define three C<G> instructions:
739 and then put the following value in the <mount_point> field of the C<V>
742 /afs/stateu.edu/$AUTO/$USER
744 Alternatively, if they include the entire directory pathname in the C<G>
747 G /afs/stateu.edu/usr1
748 G /afs/stateu.edu/usr2
749 G /afs/stateu.edu/usr3
751 then the <mount_point> field of the C<V> instruction specifies only the
756 The following example C<L> instruction creates a hard link between the
757 files F<mail> and F<mbox> in the user's home directory.
759 L $MTPT/mbox $MTPT/mail
761 The following example C<S> instruction, appropriate for the ABC
762 Corporation cell, links the file F<Mail/outgoing> in the user's home
763 directory to the file F</afs/abc.com/common/mail/outgoing>.
765 S /afs/abc.com/common/mail/outgoing $MTPT/Mail/outgoing
767 The following example C<V> instruction creates a volume called
768 C<user.I<username>> on the F</vicepa> partition of the specified file
769 server machine, assigning it a quota of 3000 kilobyte blocks. The mount
770 point is under F</afs/abc.com/usr> and matches the username (the value of
771 the $USER variable). The user owns the home directory and has all
772 access rights to it. The instruction appears on two lines only for
773 legibility; it must appear on a single line in the template file.
775 V user.$USER $SERVER.abc.com /vicepa 3000 \
776 /afs/abc.com/usr/$USER $UID $USER all
778 The following example C<X> instruction mounts the backup version of the
779 user's volume at the F<OldFiles> subdirectory.
781 X "fs mkm /afs/abc.com/usr/$USER/OldFiles user.$USER.backup"
791 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
793 This documentation is covered by the IBM Public License Version 1.0. It was
794 converted from HTML to POD by software written by Chas Williams and Russ
795 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.