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