bec37e534e3aa612da85811cf2ef5f7a7d591a35
[openafs.git] / doc / man-pages / pod5 / uss.pod
1 =head1 NAME
2
3 uss Template File - Provides instructions for the uss add command
4
5 =head1 DESCRIPTION
6
7 The uss template file defines the components of an AFS user
8 account that the B<uss add> command (or B<add> instruction in
9 a B<uss> bulk input file) creates. Use the B<-template>
10 argument to the B<uss add> or B<uss bulk> command to identify
11 the template file.
12
13 Summary of Template File Instructions
14
15 The template file can include the following instructions, each on its own
16 line. A more detailed description of each instruction's syntax
17 follows this list.
18
19 =over 4
20
21 =item A
22
23 Imposes restrictions on user passwords and authentication attempts
24
25 =item D
26
27 Creates a directory
28
29 =item E
30
31 Creates a single-line file
32
33 =item F
34
35 Creates a file by copying a prototype
36
37 =item G
38
39 Defines a directory that is one of a set of parent directories into which
40 the B<uss> command interpreter evenly distributes newly created home
41 directories
42
43 =item L
44
45 Creates a hard link
46
47 =item S
48
49 Creates a symbolic link
50
51 =item V
52
53 Creates a volume, mounts it in the file space and sets the ACL on the
54 mount point
55
56 =item X
57
58 Executes a command
59
60 =back
61
62 If the template file is empty (zero-length), the uss add command
63 or B<add> instruction in a bulk input file only creates an entry in
64 the Protection and Authentication Databases, naming them according to the name
65 specified with the B<uss add> command's B<-user>
66 argument, or in the bulk input file B<add> instruction's
67 I<username> field.
68
69 The A Instruction for Setting the Default Treatment of Volumes
70 L<(1)>
71 L<(1)>
72 L<(1)>
73 L<(1)>
74 L<(1)>
75 L<(1)>
76 L<(1)>
77
78 The B<A> instruction in a uss template file enhances
79 cell security by imposing the following restrictions on users' password
80 choice and authentication attempts. For further information on these
81 limits, see the I<IBM AFS Administration Guide> and the B<kas
82 setfields> reference page.
83
84 =over 4
85
86 =item *
87
88 Limiting the user's password lifetime. When the lifetime
89 expires, the user can no longer authenticate using that password, and must
90 change it.
91
92
93 =item *
94
95 Prohibiting the reuse of the user's 20 most recently used
96 passwords.
97
98
99 =item *
100
101 Limiting the number of consecutive times that a user can provide an
102 incorrect password during authentication, and for how long the Authentication
103 Server refuses further authentication attempts after the limit is exceeded
104 (referred to as an I<account lockout>). For regular user
105 accounts in most cells, the recommended limit is nine and lockout time is 25
106 minutes.
107
108
109 =back
110
111 The instruction has the following syntax:
112
113    A  I<username>  I<password_lifetime>  I<password_reuse>  I<failures>  I<locktime>
114
115 where
116
117 =over 4
118
119 =item A
120
121 Indicates a security-enhancing instruction. It must be a capital
122 letter.
123
124 =item I<username
125 >
126
127 Names the Authentication Database entry on which to impose security
128 restrictions. Specify the value B<$USER> to read in the
129 username from the B<uss add> command's B<-user> argument,
130 or from the I<username> field of an B<add> instruction in a bulk
131 input file.
132
133 =item I<password_lifetime
134 >
135
136 Sets the number of days after the user's password is changed that it
137 remains valid. When the password becomes invalid (expires), the user is
138 unable to authenticate, but has 30 more days in which to issue the
139 B<kpasswd> command to change the password (after that, only an
140 administrator can change it).
141
142 Specify an integer from the range B<1> through 254 to
143 specify the number of days until expiration, the value B<0> to
144 indicate that the password never expires, or the value B<$PWEXPIRES>
145 to read in the number of days from the B<uss add> or B<uss
146 bulk> command's B<-pwexpires> argument. If the
147 B<A> instruction does not appear in the template file, the default is
148 for the user's password never to expire.
149
150 =item I<password_reuse
151 >
152
153 Determines whether or not the user can change his or her password (using
154 the B<kpasswd> or B<kas setpassword> command) to one that is
155 similar to any of the last twenty passwords. The acceptable values are
156 B<reuse> to allow reuse and B<noreuse> to prohibit it.
157 If the B<A> instruction does not appear in the template file, the
158 default is to allow password reuse.
159
160 =item I<failures
161 >
162
163 Sets the number of consecutive times the user can provide an incorrect
164 password during authentication (using the B<klog> command or a login
165 utility that grants AFS tokens). When the user exceeds the limit, the
166 Authentication Server rejects further authentication attempts for the amount
167 of time specified in the I<locktime> field.
168
169 Specify an integer from the range B<1> through 254 to
170 specify the number of failures permitted, or the value B<0> to
171 indicate that there is no limit to the number of unsuccessful attempts.
172 If the B<A> instruction does not appear in the template file, the
173 default is to allow an unlimited number of failures.
174
175 =item I<locktime
176 >
177
178 Specifies how long the Authentication Server refuses authentication
179 attempts from a user who has exceeded the failure limit set in the
180 I<failures> field.
181
182 Specify a number of hours and minutes (I<hh:mm>) or minutes
183 only (I<mm>), from the range B<01> (one minute) through
184 B<36:00> (36 hours). The Authentication Server
185 automatically reduces any larger value to B<36:00> and also
186 rounds up any non-zero value to the next higher multiple of 8.5
187 minutes. A value of B<0> (zero) sets an infinite lockout
188 time; an administrator must always issue the B<kas unlock>
189 command to unlock the account.
190
191 =back
192
193 The D Instruction for Creating a Directory
194 L<(1)>
195 L<(1)>
196 L<(1)>
197 L<(1)>
198 L<(1)>
199 L<(1)>
200 L<(1)>
201 L<(1)>
202 L<(1)>
203 L<(1)>
204 L<(1)>
205
206 The B<D> instruction in a uss template file creates a
207 directory. Its intended use is to create a subdirectory in the user
208 home directory created by the B<V> instruction in the template
209 file.
210
211 Any number of D instructions can appear in the template
212 file. If any variables in the instruction take their values from the
213 B<V> instruction (notably, the $MTPT variable), the instruction must
214 follow the B<V> instruction in the file.
215
216 Although it is possible to use the D instruction to create a
217 directory on the local disk of the machine where the B<uss> command is
218 issued, it is not recommended. The preferred method for automated
219 creation of directories on a local disk is the B<package>
220 program. Two complications arise if the I<pathname> field refers
221 to a local disk directory:
222
223 =over 4
224
225 =item *
226
227 The uss command prints a warning message because it cannot
228 associate an access control list (ACL) with a local disk directory. It
229 creates the directory nonetheless, and some syntactically correct value must
230 appear in the instruction's I<ACL> field.
231
232
233 =item *
234
235 To designate any user other than the issuer as the new directory's
236 owner, the issuer must log onto the machine as the local superuser
237 B<root>. For local disk directories, only the local superuser
238 B<root> is allowed to issue the UNIX B<chown> command that the
239 B<uss> command interpreter invokes to change the owner from the
240 default value (the directory's creator, which in this case is the issuer
241 of the B<uss> command). The issuer must then also use the
242 B<-admin> argument to the B<uss add> or B<uss bulk>
243 command to authenticate as a privileged AFS administrator, which is required
244 for creating the Authentication Database and Protection Database entries that
245 the B<uss> command interpreter always creates for a new
246 account.
247
248
249 =back
250
251 The instruction has the following syntax:
252
253    D  I<pathname>  I<mode_bits>  I<owner>  I<ACL>
254
255 where
256
257 =over 4
258
259 =item D
260
261 Indicates a directory creation instruction. It must be a capital
262 letter.
263
264 =item I<pathname
265 >
266
267 Specifies the directory's full pathname. It can include
268 variables.
269
270 Specify the read/write path to the directory, to avoid the failure that
271 results from attempting to create a new directory in a read-only
272 volume. By convention, the read/write path is indicated by placing a
273 period before the cell name at the pathname's second level (for example,
274 B</afs/.abc.com>). For further discussion of the
275 concept of read/write and read-only paths through the filespace, see the
276 reference page for the B<fs mkmount> command.
277
278 =item I<mode_bits
279 >
280
281 Sets the directory's UNIX mode bits. Acceptable values are the
282 standard three- or four-digit numbers corresponding to combinations of
283 permissions. Examples: B<755> corresponds to
284 B<rwxr-xr-x>, and B<644> to B<rw-r--r-->. The
285 first (owner) B<x> bit must be turned on to enable access to a
286 directory.
287
288 =item I<owner
289 >
290
291 Specifies the username or UNIX user ID (UID) of the user to be designated
292 the directory's owner in the output from the UNIX B<ls -ld>
293 command. If the directory resides in AFS, place the $UID variable in
294 this field. If the directory resides on the local disk, this field must
295 be the username or UID of the B<uss> command's issuer, unless the
296 issuer is logged in as the local superuser B<root>.
297
298 =item I<ACL
299 >
300
301 Sets the ACL on the new directory. It must appear even if the new
302 directory resides on the local disk rather than in AFS, but is ignored in that
303 case. Provide one or more paired values, each pair consisting of an AFS
304 username or group name and the desired permissions, in that order.
305 Separate the two parts of the pair, and each pair, with a space. The
306 B<fs setacl> reference page describes the available
307 permissions.
308
309 For an AFS directory, grant all permissions to the directory's owner
310 at least. Usually that is the new user, in which case the appropriate
311 value is B<$USER all>.
312
313 It is not possible to grant any permissions to the issuer of the
314 B<uss> command. As the last step in account creation, the
315 B<uss> command interpreter automatically deletes that person from any
316 ACLs set during the creation process.
317
318 =back
319
320 The E Instruction for Creating a Single-line File
321 L<(1)>
322 L<(1)>
323 L<(1)>
324 L<(1)>
325 L<(1)>
326 L<(1)>
327
328 The B<E> instruction in a uss template file creates a
329 file by echoing a specified character string into it. Its intended use
330 is to create files in the user home directory created by the B<V>
331 instruction in the template file, or in a subdirectory created by a
332 B<D> instruction.
333
334 Any number of E instructions can appear in the template
335 file. If the file resides in a directory created by a B<D>
336 instruction, the B<E> instruction must follow the B<D>
337 instruction in the file.
338
339 The B<E> and F instructions have complementary
340 advantages. The character string echoed into the file by an
341 B<E> instruction can be customized for each user, because it can
342 include the standard variables for which the B<uss> command
343 interpreter substitutes the values specified by arguments to the B<uss
344 add> command or fields in a bulk input file B<add>
345 instruction. In contrast, a file created using the B<F>
346 instruction cannot include variables and so has the same content for all
347 users. However, a file created by an B<E> instruction can be a
348 single line only, because no carriage returns (newline characters) are allowed
349 in the character string.
350
351 Although it is possible to use the E instruction to create a
352 file on the local disk of the machine where the B<uss> command is
353 issued, it is not recommended. The preferred method for automated
354 creation of files on a local disk is the B<package> program.
355 The main complication is that designating any user other than the issuer as
356 the new file's owner requires logging onto the machine as the local
357 superuser B<root>. For local disk files, only the local
358 superuser B<root> is allowed to issue the UNIX B<chown>
359 command that the B<uss> command interpreter invokes to change the
360 owner from the default value (the file's creator, which in this case is
361 the issuer of the B<uss> command). The issuer must then also
362 use the B<-admin> argument to the B<uss add> or B<uss
363 bulk> command to authenticate as a privileged AFS administrator, which is
364 required for creating the Authentication Database and Protection Database
365 entries that the B<uss> command interpreter always creates for a new
366 account.
367
368 The instruction has the following syntax:
369
370    E  I<pathname>  I<mode_bits>  I<owner>  "I<contents>"
371
372 where
373
374 =over 4
375
376 =item E
377
378 Indicates a file creation instruction. It must be a capital
379 letter.
380
381 =item I<pathname
382 >
383
384 Specifies the file's full pathname. It can include
385 variables.
386
387 Specify the read/write path to the file, to avoid the failure that results
388 from attempting to create a new file in a read-only volume. By
389 convention, the read/write path is indicated by placing a period before the
390 cell name at the pathname's second level (for example,
391 B</afs/.abc.com>). For further discussion of the
392 concept of read/write and read-only paths through the filespace, see the
393 reference page for the B<fs mkmount> command.
394
395 =item I<mode_bits
396 >
397
398 Sets the file's UNIX mode bits. Acceptable values are the
399 standard three- or four-digit numbers corresponding to combinations of
400 permissions. Examples: B<755> corresponds to
401 B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
402
403 =item I<owner
404 >
405
406 Specifies the username or UNIX user ID (UID) of the user to be designated
407 the file's owner in the output from the UNIX B<ls -l>
408 command. If the file resides in AFS, place the $UID variable in this
409 field. If the file resides on the local disk, specify the username or
410 UID of the B<uss> command's issuer; otherwise, the account
411 creation operation halts immediately.
412
413 =item I<contents
414 >
415
416 Specifies the one-line character string to write into the new file.
417 Surround it with double quotes if it contains one or more spaces. It
418 cannot contain the newline character, but can contain any of the standard
419 variables, which the command interpreter resolves as it creates the
420 file.
421
422 =back
423
424 L<(1)>The F Instruction for Creating a File
425 from a Prototype
426 L<(1)>
427 L<(1)>
428 L<(1)>
429 L<(1)>
430 L<(1)>
431 L<(1)>
432
433 The B<F> instruction in a uss template file creates a
434 file by copying the contents of an existing file (the I<prototype>)
435 into it. Its intended use is to create files in the user home directory
436 created by the B<V> instruction in the template file, or in a
437 subdirectory created by a B<D> instruction.
438
439 Any number of F instructions can appear in the template
440 file. If the file resides in a directory created by a B<D>
441 instruction, the B<F> instruction must follow the B<D>
442 instruction in the file.
443
444 The B<E> and F instructions have complementary
445 advantages. A file created using the B<F> instruction has the
446 same content for all users, whereas a file created by an B<E>
447 instruction can be customized for each user if it includes variables.
448 However, a file created by an B<E> instruction can be a single line
449 only, whereas the prototype file copied by an B<F> instruction can be
450 any length.
451
452 Although it is possible to use the F instruction to create a
453 file on the local disk of the machine where the B<uss> command is
454 issued, it is not recommended. The preferred method for automated
455 creation of files on a local disk is the B<package> program.
456 The main complication is that designating any user other than the issuer as
457 the new file's owner requires logging onto the machine as the local
458 superuser B<root>. For local disk files, only the local
459 superuser B<root> is allowed to issue the UNIX B<chown>
460 command that the B<uss> command interpreter invokes to change the
461 owner from the default value (the file's creator, which in this case is
462 the issuer of the B<uss> command). The issuer must then also
463 use the B<-admin> argument to the B<uss add> or B<uss
464 bulk> command to authenticate as a privileged AFS administrator, which is
465 required for creating the Authentication Database and Protection Database
466 entries that the B<uss> command interpreter always creates for a new
467 account.
468
469 The instruction has the following syntax:
470
471    F  I<pathname>  I<mode_bits>  I<owner>  I<prototype_file>
472
473 where
474
475 =over 4
476
477 =item F
478
479 Indicates a file creation instruction. It must be a capital
480 letter.
481
482 =item I<pathname
483 >
484
485 Specifies the full pathname of the file to create, including the
486 filename. It can include variables.
487
488 Specify the read/write path to the file, to avoid the failure that results
489 from attempting to create a new file in a read-only volume. By
490 convention, the read/write path is indicated by placing a period before the
491 cell name at the pathname's second level (for example,
492 B</afs/.abc.com>). For further discussion of the
493 concept of read/write and read-only paths through the filespace, see the
494 reference page for the B<fs mkmount> command.
495
496 =item I<mode_bits
497 >
498
499 Sets the file's UNIX mode bits. Acceptable values are the
500 standard three- or four-digit numbers corresponding to combinations of
501 permissions. Examples: B<755> corresponds to
502 B<rwxr-xr-x>, and B<644> to B<rw-r--r-->.
503
504 =item I<owner
505 >
506
507 Specifies the username or UNIX user ID (UID) of the user to be designated
508 the file's owner in the output from the UNIX B<ls -l>
509 command. If the file resides in AFS, place the $UID variable in this
510 field. If the file resides on the local disk, specify the username or
511 UID of the B<uss> command's issuer; otherwise, the account
512 creation operation halts immediately.
513
514 =item I<prototype_file
515 >
516
517 Names the AFS or local disk directory that houses the prototype file to
518 copy. The prototype file's name must match the final element in
519 the I<pathname> field.
520
521 =back
522
523 L<(1)>The G Instruction for Facilitating Even
524 Distribution of Home Directories
525 L<(1)>
526 L<(1)>
527 L<(1)>
528 L<(1)>
529 L<(1)>
530 L<(1)>
531
532 The B<G> instruction in a uss template file creates a
533 directory as one of the set of directories from which the B<uss>
534 command interpreter selects when choosing a new user home directory's
535 parent directory. More specifically, when the $AUTO variable appears in
536 the I<mount_point> field of a B<V> instruction, the command
537 interpreter substitutes for it the directory defined by a B<G>
538 instruction that currently has the fewest entries.
539
540 The instruction's intended use is to distribute user accounts evenly
541 among several directories, rather than using directories that reflect
542 divisions such as departmental affiliation. Distributing home
543 directories in this fashion is useful mainly in very large cells where storing
544 all user home directories under a single parent directory potentially slows
545 directory lookup, or where a workplace-based division results in unevenly
546 sized directories such that some users consistently experience slower
547 directory lookup than others. See the chapter on B<uss> in the
548 I<IBM AFS Administration Guide> for more information.
549
550 Any number of G instructions can appear in the template
551 file. If the B<V> instruction includes the $AUTO variable, it
552 must appear after all of the B<G> instructions in the file.
553
554 The instruction has the following syntax:
555
556    G  I<directory>
557
558 where
559
560 =over 4
561
562 =item G
563
564 Indicates an instruction that creates a directory to be considered as a
565 value for the $AUTO variable. It must be a capital letter.
566
567 =item I<directory
568 >
569
570 Specifies the directory's name as either a complete pathname or only
571 the directory name. The choice determines the appropriate format for
572 the I<mount_point> field of a B<V> instruction, as discussed in
573 the following example.
574
575 Specify the read/write path to the directory, to avoid the failure that
576 results from attempting to create a new mount point in a read-only volume when
577 the $AUTO variable is used in a B<V> instruction's
578 I<mount_point> field. By convention, the read/write path is
579 indicated by placing a period before the cell name at the pathname's
580 second level (for example, B</afs/.abc.com>). For
581 further discussion of the concept of read/write and read-only paths through
582 the filespace, see the reference page for the B<fs mkmount>
583 command.
584
585 =back
586
587 The L and S Instructions for Creating a Link
588 L<(1)>
589 L<(1)>
590 L<(1)>
591 L<(1)>
592 L<(1)>
593 L<(1)>
594 L<(1)>
595 L<(1)>
596 L<(1)>
597 L<(1)>
598 L<(1)>
599 L<(1)>
600 L<(1)>
601
602 The B<L> instruction in a uss template file creates a
603 hard link between two files, as achieved by the standard UNIX B<ln>
604 command. The B<S> instruction creates a symbolic link between
605 two files, as achieved by the standard UNIX B<ln -s> command. A
606 full explanation of links is beyond the scope of this document, but the basic
607 effect is to create a second name for an existing file, enabling access via
608 either name. Creating a link does not create a second copy of the
609 file.
610
611 AFS allows hard links only if the linked files reside in the same
612 directory, because it becomes difficult to determine which access control list
613 (ACL) applies to the file if the two copies reside in directories with
614 different ACLs. AFS allows symbolic links between two files that reside
615 in different directories, or even different volumes. The File Server
616 uses the ACL associated with the actual file rather than the link.
617
618 Any number of B<L> and S instructions can appear in the
619 template file. If the existing file or link is to reside in a directory
620 created by a B<D> instruction, or if the existing file was created by
621 an B<E> or B<F> instruction, the B<L> or B<S>
622 instruction must follow the B<D>, B<E>, or B<F>
623 instruction.
624
625 The instructions share the following syntax:
626
627    L  I<existing_file>  I<link>
628    S  I<existing_file>  I<link>
629
630 where
631
632 =over 4
633
634 =item L
635
636 Indicates a hard link creation instruction. It must be a capital
637 letter.
638
639 =item S
640
641 Indicates a symbolic link creation instruction. It must be a
642 capital letter.
643
644 =item I<existing_file
645 >
646
647 Specifies the complete pathname of the existing file.
648
649 =item I<link
650 >
651
652 Specifies the complete pathname of the second name for the file.
653
654 Specify the read/write path to the link, to avoid the failure that results
655 from attempting to create a new link in a read-only volume. By
656 convention, the read/write path is indicated by placing a period before the
657 cell name at the pathname's second level (for example,
658 B</afs/.abc.com>). For further discussion of the
659 concept of read/write and read-only paths through the filespace, see the
660 reference page for the B<fs mkmount> command.
661
662 =back
663
664 L<(1)>The V Instruction for Creating and
665 Mounting a Volume
666 L<(1)>
667 L<(1)>
668 L<(1)>
669 L<(1)>
670 L<(1)>
671 L<(1)>
672 L<(1)>
673 L<(1)>
674 L<(1)>
675 L<(1)>
676 L<(1)>
677 L<(1)>
678 L<(1)>
679 L<(1)>
680 L<(1)>
681 L<(1)>
682 L<(1)>
683 L<(1)>
684 L<(1)>
685
686 The B<V> instruction in a uss template file creates a
687 volume on a specified file server machine and partition and creates an entry
688 for it in the Volume Location Database (VLDB). It mounts the volume at
689 a location in the AFS file space that becomes the user's home directory,
690 then designates the directory's owner and sets its access control list
691 (ACL).
692
693 Only one V instruction can appear in the template file, and one
694 must appear if the template file contains any instructions at all (is not
695 empty). All other instructions are optional, except that the template
696 must include B<G> instructions if the $AUTO variable appears in
697 it. (The B<V> instruction is not necessarily the first line in
698 the template. If the template includes the $AUTO variable, then the
699 B<G> instructions which provide values for the variable must precede
700 it in the file.)
701
702 The instruction has the following syntax:
703
704    V  I<volume_name>  I<server>  I<partition>  I<quota>  I<mount_point> I<owner>  I<ACL>
705
706 where
707
708 =over 4
709
710 =item V
711
712 Indicates a volume creation instruction. It must be a capital
713 letter.
714
715 =item I<volume_name
716 >
717
718 Specifies the volume's name. To follow the convention for AFS
719 user volume names, specify the value B<user.$USER>.
720 Provide a value for the $USER variable via the B<uss add>
721 command's B<-user> argument or the I<username> field in the
722 bulk input file B<add> instruction.
723
724 =item I<server
725 >
726
727 Names the file server machine on which to create the new user's
728 volume. It is best to provide the fully-qualified hostname (for
729 example, B<fs1.abc.com>), but an abbreviated form is
730 acceptable provided that the cell's naming service is available to
731 resolve it at the time the volume is created. To read in the value from
732 the B<uss add> command's B<-server> argument, specify the
733 value B<$SERVER>.
734
735 =item I<partition
736 >
737
738 Specifies the partition on which to create the user's volume; it
739 must be on the file server machine named in the I<server> field.
740 Identify the partition by its complete name (for example, B</vicepa>)
741 or use or use one of the following abbreviations. 
742
743    B</vicepa>     =     B<vicepa>      =      B<a>      =      0
744    B</vicepb>     =     B<vicepb>      =      B<b>      =      1
745
746 After /vicepz (for which the index is 25) comes 
747
748    B</vicepaa>    =     B<vicepaa>     =      B<aa>     =      26
749    B</vicepab>    =     B<vicepab>     =      B<ab>     =      27
750
751 and so on through 
752
753    B</vicepiv>    =     B<vicepiv>     =      B<iv>     =      255
754
755 To read in the value from the uss add command's
756 B<-partition> argument, specify the value B<$PART>.
757
758 =item I<quota
759 >
760
761 Sets the maximum number of kilobyte blocks the volume can occupy on the
762 file server machine's disk. Specify an integer constant if all
763 volumes have the same quota (B<1024> equals a megabyte), or use one of
764 the number variables ($1 through $9) to assign different values to different
765 volumes.
766
767 =item I<mount_point
768 >
769
770 Creates a mount point for the volume, which serves as the volume's
771 root directory. Include the $USER variable as part of the pathname to
772 follow the convention that user home directory names include the
773 username.
774
775 Specify the read/write path to the mount point, to avoid the failure that
776 results from attempting to create a new mount point in a read-only
777 volume. By convention, the read/write path is indicated by placing a
778 period before the cell name at the pathname's second level (for example,
779 B</afs/.abc.com>). If the $AUTO variable appears
780 in this field, the directories named by each B<G> instruction possibly
781 already indicate the read/write path. For further discussion of the
782 concept of read/write and read-only paths through the filespace, see the
783 reference page for the B<fs mkmount> command..
784
785 =item I<owner
786 >
787
788 Specifies the username or UNIX user ID (UID) of the user to be designated
789 the mount point's owner in the output from the UNIX B<ls -ld>
790 command. To follow the convention for home directory ownership, place
791 the value B<$UID> in this field.
792
793 =item I<ACL
794 >
795
796 Sets the ACL on the new directory. Provide one or more paired
797 values, each pair consisting of an AFS username or group name and the desired
798 permissions, in that order. Separate the two parts of the pair, and
799 each pair, with a space. The B<fs setacl> reference page
800 describes the available permissions.
801
802 Grant all permissions to the new user at least. The appropriate
803 value is B<$USER all>.
804
805 AFS automatically grants the system:administrators group
806 all permissions as well. It is not possible to grant any permissions to
807 the issuer of the B<uss> command. As the last step in account
808 creation, the B<uss> command interpreter automatically deletes that
809 user from any ACLs set during the creation process.
810
811 =back
812
813 L<(1)>The X Instruction for Running a
814 Command
815 L<(1)>
816 L<(1)>
817 L<(1)>
818
819 The B<X> instruction in a uss template file runs the
820 indicated command, which can be a standard UNIX or AFS command. It can
821 include any variables from the template file, which the B<uss> command
822 interpreter resolves before passing the command on to the appropriate other
823 command interpreter. It must be a single line only, however (cannot
824 contain carriage returns or newline characters).
825
826 Any number of X instructions can appear in the template
827 file. If an instruction manipulates an element created by another
828 instruction, it must follow that instruction in the file.
829
830 The instruction has the following syntax:
831
832    B<X ">I<command>"
833
834 where
835
836 =over 4
837
838 =item X
839
840 Indicates a command execution instruction. It must be a capital
841 letter.
842
843 =item I<command
844 >
845
846 Specifies the command to run. Surround it with double quotes as
847 shown if it contains one or more spaces. It can contain any variables
848 from the template file, but not newline characters.
849
850 =back
851
852 =head1 EXAMPLES
853
854 The following example A instruction sets a password lifetime of
855 254 days, prohibits password reuse, limits the number of consecutive failed
856 authentication attempts to nine and sets the corresponding locktime to
857 25:30 minutes (which is a multiple of 8.5 minutes). The
858 username is read in from the B<-user> argument to the B<uss
859 add> command or from the I<username> field in each B<add>
860 instruction in a bulk input file.
861
862    A $USER 254 noreuse 9 25:30
863
864 The following example D instruction creates a directory called
865 I<public> in a new user's home directory, designates the user as
866 the directory's owner, and grants him or her all ACL permissions.
867
868    D $MTPT/public 0755 $UID $USER all 
869
870 The following example E instruction creates a file in the
871 current working directory called
872 I<username>.B<etcp>. The contents are an entry
873 suitable for incorporating into the cell's global
874 B</etc/password> file.
875
876    E  $USER.etcp  0644 root "$USER:X:$UID:10:$NAME:$MTPT:/bin/csh"
877
878 The following example F instruction, appropriate for the ABC
879 Corporation cell, copies a prototype B<.login> file into the
880 user's home directory.
881
882    F $MTPT/.login 0644 $UID /afs/abc.com/common/uss/skel/.login 
883
884 In the following example, the State University cell's administrators
885 have decided to distribute user home directories evenly into three
886 directories. They define three B<G> instructions:
887
888    G usr1
889    G usr2
890    G usr3
891
892 and then put the following value in the I<mount_point> field of the
893 B<V> instruction:
894
895    /afs/stateu.edu/$AUTO/$USER
896
897 Alternatively, if they include the entire directory pathname in the
898 B<G> instruction:
899
900    G /afs/stateu.edu/usr1
901    G /afs/stateu.edu/usr2
902    G /afs/stateu.edu/usr3
903
904 then the I<mount_point> field of the V instruction
905 specifies only the following:
906
907    $AUTO/$USER
908
909 The following example L instruction creates a hard link between
910 the files B<mail> and B<mbox> in the user's home
911 directory.
912
913    L $MTPT/mbox $MTPT/mail
914
915 The following example S instruction, appropriate for the ABC
916 Corporation cell, links the file B<Mail/outgoing> in the user's
917 home directory to the file
918 B</afs/abc.com/common/mail/outgoing>.
919
920    S /afs/abc.com/common/mail/outgoing $MTPT/Mail/outgoing
921
922 The following example V instruction creates a volume called
923 B<user.>I<username> on the B</vicepa> partition
924 of the specified file server machine, assigning it a quota of 3000 kilobyte
925 blocks. The mount point is under B</afs/abc.com/usr> and
926 matches the username (the value of the $USER variable). The user owns
927 the home directory and has all access rights to it. The instruction
928 appears on two lines only for legibility; it must appear on a single line
929 in the template file.
930
931    V user.$USER $SERVER.abc.com /vicepa 3000   \
932            /afs/abc.com/usr/$USER $UID $USER all 
933
934 The following example X instruction mounts the backup version of
935 the user's volume at the B<OldFiles> subdirectory.
936
937    X "fs mkm /afs/abc.com/usr/$USER/OldFiles   user.$USER.backup"
938
939 =head1 SEE ALSO
940
941 L<uss Bulk Input File(1)>
942
943 L<fs_mkmount(1)>,
944 L<uss_add(1)>
945
946 =head1 COPYRIGHT
947
948 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
949
950 This documentation is covered by the IBM Public License Version 1.0.  It was
951 converted from HTML to POD by software written by Chas Williams and Russ
952 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.