.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "USS 5" .TH USS 5 "2021-12-09" "OpenAFS" "AFS File Reference" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" uss \- Provides instructions for the uss add command (deprecated) .SH "CAUTIONS" .IX Header "CAUTIONS" The \fBuss\fR command suite is currently designed for cells using the obsolete Authentication Server, and therefore is primarily useful for sites that have not yet migrated to a Kerberos version 5 \s-1KDC\s0. The Authentication Server and supporting commands will be removed in a future version of OpenAFS, which may include \fBuss\fR unless someone who finds it useful converts it to work with a Kerberos version 5 \s-1KDC\s0. .SH "DESCRIPTION" .IX Header "DESCRIPTION" The uss template file defines the components of an \s-1AFS\s0 user account that the \fBuss add\fR command (or \fBadd\fR instruction in a \fBuss\fR bulk input file) creates. Use the \fB\-template\fR argument to the \fBuss add\fR or \fBuss bulk\fR command to identify the template file. .SS "Summary of Template File Instructions" .IX Subsection "Summary of Template File Instructions" The template file can include the following instructions, each on its own line. A more detailed description of each instruction's syntax follows this list. .IP "A" 4 .IX Item "A" Imposes restrictions on user passwords and authentication attempts. .IP "D" 4 .IX Item "D" Creates a directory. .IP "E" 4 .IX Item "E" Creates a single-line file. .IP "F" 4 .IX Item "F" Creates a file by copying a prototype. .IP "G" 4 .IX Item "G" Defines a directory that is one of a set of parent directories into which the \fBuss\fR command interpreter evenly distributes newly created home directories. .IP "L" 4 .IX Item "L" Creates a hard link. .IP "S" 4 .IX Item "S" Creates a symbolic link. .IP "V" 4 .IX Item "V" Creates a volume, mounts it in the file space and sets the \s-1ACL\s0 on the mount point. .IP "X" 4 .IX Item "X" Executes a command. .PP If the template file is empty (zero-length), the \fBuss add\fR command or \&\f(CW\*(C`add\*(C'\fR instruction in a bulk input file only creates an entry in the Protection and Authentication Databases, naming them according to the name specified with the \fBuss add\fR command's \fB\-user\fR argument, or in the bulk input file \f(CW\*(C`add\*(C'\fR instruction's \fIusername\fR field. .SS "The A Instruction for Setting the Default Treatment of Volumes" .IX Subsection "The A Instruction for Setting the Default Treatment of Volumes" The \f(CW\*(C`A\*(C'\fR instruction in a uss template file enhances cell security by imposing the following restrictions on users' password choice and authentication attempts. For further information on these limits, see the \&\fIOpenAFS Administration Guide\fR and the \fBkas setfields\fR reference page. .IP "\(bu" 4 Limiting the user's password lifetime. When the lifetime expires, the user can no longer authenticate using that password, and must change it. .IP "\(bu" 4 Prohibiting the reuse of the user's 20 most recently used passwords. .IP "\(bu" 4 Limiting the number of consecutive times that a user can provide an incorrect password during authentication, and for how long the Authentication Server refuses further authentication attempts after the limit is exceeded (referred to as an \fIaccount lockout\fR). For regular user accounts in most cells, the recommended limit is nine and lockout time is 25 minutes. .PP The instruction has the following syntax: .PP .Vb 1 \& A .Ve .PP where .IP "A" 4 .IX Item "A" Indicates a security-enhancing instruction. It must be a capital letter. .IP "" 4 .IX Item "" Names the Authentication Database entry on which to impose security restrictions. Specify the value \f(CW$USER\fR to read in the username from the \&\fBuss add\fR command's \fB\-user\fR argument, or from the \fIusername\fR field of an \f(CW\*(C`add\*(C'\fR instruction in a bulk input file. .IP "" 4 .IX Item "" Sets the number of days after the user's password is changed that it remains valid. When the password becomes invalid (expires), the user is unable to authenticate, but has 30 more days in which to issue the \&\fBkpasswd\fR command to change the password (after that, only an administrator can change it). .Sp Specify an integer from the range \f(CW1\fR through \f(CW254\fR to specify the number of days until expiration, the value \f(CW0\fR to indicate that the password never expires, or the value \f(CW$PWEXPIRES\fR to read in the number of days from the \fBuss add\fR or \fBuss bulk\fR command's \fB\-pwexpires\fR argument. If the \f(CW\*(C`A\*(C'\fR instruction does not appear in the template file, the default is for the user's password never to expire. .IP "" 4 .IX Item "" Determines whether or not the user can change his or her password (using the \fBkpasswd\fR or \fBkas setpassword\fR command) to one that is similar to any of the last twenty passwords. The acceptable values are \f(CW\*(C`reuse\*(C'\fR to allow reuse and \f(CW\*(C`noreuse\*(C'\fR to prohibit it. If the \f(CW\*(C`A\*(C'\fR instruction does not appear in the template file, the default is to allow password reuse. .IP "" 4 .IX Item "" Sets the number of consecutive times the user can provide an incorrect password during authentication (using the \fBklog\fR command or a login utility that grants \s-1AFS\s0 tokens). When the user exceeds the limit, the Authentication Server rejects further authentication attempts for the amount of time specified in the field. .Sp Specify an integer from the range \f(CW1\fR through \f(CW254\fR to specify the number of failures permitted, or the value \f(CW0\fR to indicate that there is no limit to the number of unsuccessful attempts. If the \f(CW\*(C`A\*(C'\fR instruction does not appear in the template file, the default is to allow an unlimited number of failures. .IP "" 4 .IX Item "" Specifies how long the Authentication Server refuses authentication attempts from a user who has exceeded the failure limit set in the field. .Sp Specify a number of hours and minutes (\fIhh:mm\fR) or minutes only (\fImm\fR), from the range \f(CW01\fR (one minute) through \f(CW\*(C`36:00\*(C'\fR (36 hours). The Authentication Server automatically reduces any larger value to \f(CW\*(C`36:00\*(C'\fR and also rounds up any non-zero value to the next higher multiple of 8.5 minutes. A value of \f(CW0\fR (zero) sets an infinite lockout time; an administrator must always issue the \fBkas unlock\fR command to unlock the account. .SS "The D Instruction for Creating a Directory" .IX Subsection "The D Instruction for Creating a Directory" The \f(CW\*(C`D\*(C'\fR instruction in a uss template file creates a directory. Its intended use is to create a subdirectory in the user home directory created by the \f(CW\*(C`V\*(C'\fR instruction in the template file. .PP Any number of \f(CW\*(C`D\*(C'\fR instructions can appear in the template file. If any variables in the instruction take their values from the \f(CW\*(C`V\*(C'\fR instruction (notably, the \f(CW$MTPT\fR variable), the instruction must follow the \f(CW\*(C`V\*(C'\fR instruction in the file. .PP Although it is possible to use the \f(CW\*(C`D\*(C'\fR instruction to create a directory on the local disk of the machine where the \fBuss\fR command is issued, it is not recommended. Two complications arise if the field refers to a local disk directory: .IP "\(bu" 4 The \fBuss\fR command prints a warning message because it cannot associate an access control list (\s-1ACL\s0) with a local disk directory. It creates the directory nonetheless, and some syntactically correct value must appear in the instruction's <\s-1ACL\s0> field. .IP "\(bu" 4 To designate any user other than the issuer as the new directory's owner, the issuer must log onto the machine as the local superuser \f(CW\*(C`root\*(C'\fR. For local disk directories, only the local superuser \f(CW\*(C`root\*(C'\fR is allowed to issue the \s-1UNIX\s0 \fBchown\fR command that the \fBuss\fR command interpreter invokes to change the owner from the default value (the directory's creator, which in this case is the issuer of the \fBuss\fR command). The issuer must then also use the \fB\-admin\fR argument to the \fBuss add\fR or \&\fBuss bulk\fR command to authenticate as a privileged \s-1AFS\s0 administrator, which is required for creating the Authentication Database and Protection Database entries that the \fBuss\fR command interpreter always creates for a new account. .PP The instruction has the following syntax: .PP .Vb 1 \& D .Ve .PP where .IP "D" 4 .IX Item "D" Indicates a directory creation instruction. It must be a capital letter. .IP "" 4 .IX Item "" Specifies the directory's full pathname. It can include variables. .Sp Specify the read/write path to the directory, to avoid the failure that results from attempting to create a new directory in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, \&\fI/afs/.example.com\fR). For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the \fBfs mkmount\fR command. .IP "" 4 .IX Item "" Sets the directory's \s-1UNIX\s0 mode bits. Acceptable values are the standard three\- or four-digit numbers corresponding to combinations of permissions. Examples: \f(CW755\fR corresponds to \f(CW\*(C`rwxr\-xr\-x\*(C'\fR, and \f(CW644\fR to \&\f(CW\*(C`rw\-r\-\-r\-\-\*(C'\fR. The first (owner) \f(CW\*(C`x\*(C'\fR bit must be turned on to enable access to a directory. .IP "" 4 .IX Item "" Specifies the username or \s-1UNIX\s0 user \s-1ID\s0 (\s-1UID\s0) of the user to be designated the directory's owner in the output from the \s-1UNIX\s0 \f(CW\*(C`ls \-ld\*(C'\fR command. If the directory resides in \s-1AFS\s0, place the \f(CW$UID\fR variable in this field. If the directory resides on the local disk, this field must be the username or \s-1UID\s0 of the \fBuss\fR command's issuer, unless the issuer is logged in as the local superuser \f(CW\*(C`root\*(C'\fR. .IP "<\s-1ACL\s0>" 4 .IX Item "" Sets the \s-1ACL\s0 on the new directory. It must appear even if the new directory resides on the local disk rather than in \s-1AFS\s0, but is ignored in that case. Provide one or more paired values, each pair consisting of an \&\s-1AFS\s0 username or group name and the desired permissions, in that order. Separate the two parts of the pair, and each pair, with a space. The \fBfs setacl\fR reference page describes the available permissions. .Sp For an \s-1AFS\s0 directory, grant all permissions to the directory's owner at least. Usually that is the new user, in which case the appropriate value is \f(CW\*(C`$USER all\*(C'\fR. .Sp It is not possible to grant any permissions to the issuer of the \fBuss\fR command. As the last step in account creation, the \fBuss\fR command interpreter automatically deletes that person from any ACLs set during the creation process. .SS "The E Instruction for Creating a Single-line File" .IX Subsection "The E Instruction for Creating a Single-line File" The \f(CW\*(C`E\*(C'\fR instruction in a uss template file creates a file by echoing a specified character string into it. Its intended use is to create files in the user home directory created by the \f(CW\*(C`V\*(C'\fR instruction in the template file, or in a subdirectory created by a \f(CW\*(C`D\*(C'\fR instruction. .PP Any number of \f(CW\*(C`E\*(C'\fR instructions can appear in the template file. If the file resides in a directory created by a \f(CW\*(C`D\*(C'\fR instruction, the \f(CW\*(C`E\*(C'\fR instruction must follow the \f(CW\*(C`D\*(C'\fR instruction in the file. .PP The \f(CW\*(C`E\*(C'\fR and \f(CW\*(C`F\*(C'\fR instructions have complementary advantages. The character string echoed into the file by an \f(CW\*(C`E\*(C'\fR instruction can be customized for each user, because it can include the standard variables for which the \fBuss\fR command interpreter substitutes the values specified by arguments to the \fBuss add\fR command or fields in a bulk input file \&\fBadd\fR instruction. In contrast, a file created using the \f(CW\*(C`F\*(C'\fR instruction cannot include variables and so has the same content for all users. However, a file created by an \f(CW\*(C`E\*(C'\fR instruction can be a single line only, because no carriage returns (newline characters) are allowed in the character string. .PP Although it is possible to use the \f(CW\*(C`E\*(C'\fR instruction to create a file on the local disk of the machine where the \fBuss\fR command is issued, it is not recommended. The main complication is that designating any user other than the issuer as the new file's owner requires logging onto the machine as the local superuser \f(CW\*(C`root\*(C'\fR. For local disk files, only the local superuser \f(CW\*(C`root\*(C'\fR is allowed to issue the \&\s-1UNIX\s0 \fBchown\fR command that the \fBuss\fR command interpreter invokes to change the owner from the default value (the file's creator, which in this case is the issuer of the \fBuss\fR command). The issuer must then also use the \fB\-admin\fR argument to the \fBuss add\fR or \fBuss bulk\fR command to authenticate as a privileged \s-1AFS\s0 administrator, which is required for creating the Authentication Database and Protection Database entries that the \fBuss\fR command interpreter always creates for a new account. .PP The instruction has the following syntax: .PP .Vb 1 \& E "" .Ve .PP where .IP "E" 4 .IX Item "E" Indicates a file creation instruction. It must be a capital letter. .IP "" 4 .IX Item "" Specifies the file's full pathname. It can include variables. .Sp Specify the read/write path to the file, to avoid the failure that results from attempting to create a new file in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, \fI/afs/.example.com\fR). For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the \fBfs mkmount\fR command. .IP "" 4 .IX Item "" Sets the file's \s-1UNIX\s0 mode bits. Acceptable values are the standard three\- or four-digit numbers corresponding to combinations of permissions. Examples: \f(CW755\fR corresponds to \f(CW\*(C`rwxr\-xr\-x\*(C'\fR, and \f(CW644\fR to \&\f(CW\*(C`rw\-r\-\-r\-\-\*(C'\fR. .IP "" 4 .IX Item "" Specifies the username or \s-1UNIX\s0 user \s-1ID\s0 (\s-1UID\s0) of the user to be designated the file's owner in the output from the \s-1UNIX\s0 \f(CW\*(C`ls \-l\*(C'\fR command. If the file resides in \s-1AFS\s0, place the \f(CW$UID\fR variable in this field. If the file resides on the local disk, specify the username or \s-1UID\s0 of the \fBuss\fR command's issuer; otherwise, the account creation operation halts immediately. .IP "" 4 .IX Item "" Specifies the one-line character string to write into the new file. Surround it with double quotes if it contains one or more spaces. It cannot contain the newline character, but can contain any of the standard variables, which the command interpreter resolves as it creates the file. .SS "The F Instruction for Creating a File from a Prototype" .IX Subsection "The F Instruction for Creating a File from a Prototype" The \f(CW\*(C`F\*(C'\fR instruction in a uss template file creates a file by copying the contents of an existing file (the ) into it. Its intended use is to create files in the user home directory created by the \f(CW\*(C`V\*(C'\fR instruction in the template file, or in a subdirectory created by a \f(CW\*(C`D\*(C'\fR instruction. .PP Any number of \f(CW\*(C`F\*(C'\fR instructions can appear in the template file. If the file resides in a directory created by a \f(CW\*(C`D\*(C'\fR instruction, the \f(CW\*(C`F\*(C'\fR instruction must follow the \f(CW\*(C`D\*(C'\fR instruction in the file. .PP The \f(CW\*(C`E\*(C'\fR and \f(CW\*(C`F\*(C'\fR instructions have complementary advantages. A file created using the \f(CW\*(C`F\*(C'\fR instruction has the same content for all users, whereas a file created by an \f(CW\*(C`E\*(C'\fR instruction can be customized for each user if it includes variables. However, a file created by an \f(CW\*(C`E\*(C'\fR instruction can be a single line only, whereas the prototype file copied by an \f(CW\*(C`F\*(C'\fR instruction can be any length. .PP Although it is possible to use the \f(CW\*(C`F\*(C'\fR instruction to create a file on the local disk of the machine where the \fBuss\fR command is issued, it is not recommended. The main complication is that designating any user other than the issuer as the new file's owner requires logging onto the machine as the local superuser \f(CW\*(C`root\*(C'\fR. For local disk files, only the local superuser \f(CW\*(C`root\*(C'\fR is allowed to issue the \&\s-1UNIX\s0 \fBchown\fR command that the \fBuss\fR command interpreter invokes to change the owner from the default value (the file's creator, which in this case is the issuer of the \fBuss\fR command). The issuer must then also use the \fB\-admin\fR argument to the \fBuss add\fR or \fBuss bulk\fR command to authenticate as a privileged \s-1AFS\s0 administrator, which is required for creating the Authentication Database and Protection Database entries that the \fBuss\fR command interpreter always creates for a new account. .PP The instruction has the following syntax: .PP .Vb 1 \& F .Ve .PP where .IP "F" 4 .IX Item "F" Indicates a file creation instruction. It must be a capital letter. .IP "" 4 .IX Item "" Specifies the full pathname of the file to create, including the filename. It can include variables. .Sp Specify the read/write path to the file, to avoid the failure that results from attempting to create a new file in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, \fI/afs/.example.com\fR). For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the \fBfs mkmount\fR command. .IP "" 4 .IX Item "" Sets the file's \s-1UNIX\s0 mode bits. Acceptable values are the standard three\- or four-digit numbers corresponding to combinations of permissions. Examples: \f(CW755\fR corresponds to \f(CW\*(C`rwxr\-xr\-x\*(C'\fR, and \f(CW644\fR to \&\f(CW\*(C`rw\-r\-\-r\-\-\*(C'\fR. .IP "" 4 .IX Item "" Specifies the username or \s-1UNIX\s0 user \s-1ID\s0 (\s-1UID\s0) of the user to be designated the file's owner in the output from the \s-1UNIX\s0 \f(CW\*(C`ls \-l\*(C'\fR command. If the file resides in \s-1AFS\s0, place the \f(CW$UID\fR variable in this field. If the file resides on the local disk, specify the username or \s-1UID\s0 of the \fBuss\fR command's issuer; otherwise, the account creation operation halts immediately. .IP "" 4 .IX Item "" Names the \s-1AFS\s0 or local disk directory that houses the prototype file to copy. The prototype file's name must match the final element in the field. .SS "The G Instruction for Even Distribution of Home Directories" .IX Subsection "The G Instruction for Even Distribution of Home Directories" The \f(CW\*(C`G\*(C'\fR instruction in a uss template file creates a directory as one of the set of directories from which the \fBuss\fR command interpreter selects when choosing a new user home directory's parent directory. More specifically, when the \f(CW$AUTO\fR variable appears in the field of a \f(CW\*(C`V\*(C'\fR instruction, the command interpreter substitutes for it the directory defined by a \f(CW\*(C`G\*(C'\fR instruction that currently has the fewest entries. .PP The instruction's intended use is to distribute user accounts evenly among several directories, rather than using directories that reflect divisions such as departmental affiliation. Distributing home directories in this fashion is useful mainly in very large cells where storing all user home directories under a single parent directory potentially slows directory lookup, or where a workplace-based division results in unevenly sized directories such that some users consistently experience slower directory lookup than others. See the chapter on \fBuss\fR in the \fIOpenAFS Administration Guide\fR for more information. .PP Any number of \f(CW\*(C`G\*(C'\fR instructions can appear in the template file. If the \&\f(CW\*(C`V\*(C'\fR instruction includes the \f(CW$AUTO\fR variable, it must appear after all of the \f(CW\*(C`G\*(C'\fR instructions in the file. .PP The instruction has the following syntax: .PP .Vb 1 \& G .Ve .PP where .IP "G" 4 .IX Item "G" Indicates an instruction that creates a directory to be considered as a value for the \f(CW$AUTO\fR variable. It must be a capital letter. .IP "" 4 .IX Item "" Specifies the directory's name as either a complete pathname or only the directory name. The choice determines the appropriate format for the field of a \f(CW\*(C`V\*(C'\fR instruction, as discussed in the following example. .Sp Specify the read/write path to the directory, to avoid the failure that results from attempting to create a new mount point in a read-only volume when the \f(CW$AUTO\fR variable is used in a \f(CW\*(C`V\*(C'\fR instruction's field. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, \&\fI/afs/.example.com\fR). For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the \fBfs mkmount\fR command. .SS "The L and S Instructions for Creating a Link" .IX Subsection "The L and S Instructions for Creating a Link" The \f(CW\*(C`L\*(C'\fR instruction in a uss template file creates a hard link between two files, as achieved by the standard \s-1UNIX\s0 \fBln\fR command. The \f(CW\*(C`S\*(C'\fR instruction creates a symbolic link between two files, as achieved by the standard \s-1UNIX\s0 \f(CW\*(C`ln \-s\*(C'\fR command. A full explanation of links is beyond the scope of this document, but the basic effect is to create a second name for an existing file, enabling access via either name. Creating a link does not create a second copy of the file. .PP \&\s-1AFS\s0 allows hard links only if the linked files reside in the same directory, because it becomes difficult to determine which access control list (\s-1ACL\s0) applies to the file if the two copies reside in directories with different ACLs. \s-1AFS\s0 allows symbolic links between two files that reside in different directories, or even different volumes. The File Server uses the \s-1ACL\s0 associated with the actual file rather than the link. .PP Any number of \f(CW\*(C`L\*(C'\fR and \f(CW\*(C`S\*(C'\fR instructions can appear in the template file. If the existing file or link is to reside in a directory created by a \f(CW\*(C`D\*(C'\fR instruction, or if the existing file was created by an \f(CW\*(C`E\*(C'\fR or \f(CW\*(C`F\*(C'\fR instruction, the \f(CW\*(C`L\*(C'\fR or \f(CW\*(C`S\*(C'\fR instruction must follow the \f(CW\*(C`D\*(C'\fR, \f(CW\*(C`E\*(C'\fR, or \&\f(CW\*(C`F\*(C'\fR instruction. .PP The instructions share the following syntax: .PP .Vb 2 \& L \& S .Ve .PP where .IP "L" 4 .IX Item "L" Indicates a hard link creation instruction. It must be a capital letter. .IP "S" 4 .IX Item "S" Indicates a symbolic link creation instruction. It must be a capital letter. .IP "" 4 .IX Item "" Specifies the complete pathname of the existing file. .IP "" 4 .IX Item "" Specifies the complete pathname of the second name for the file. .Sp Specify the read/write path to the link, to avoid the failure that results from attempting to create a new link in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, \fI/afs/.example.com\fR). For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the \fBfs mkmount\fR command. .SS "The V Instruction for Creating and Mounting a Volume" .IX Subsection "The V Instruction for Creating and Mounting a Volume" The \f(CW\*(C`V\*(C'\fR instruction in a uss template file creates a volume on a specified file server machine and partition and creates an entry for it in the Volume Location Database (\s-1VLDB\s0). It mounts the volume at a location in the \s-1AFS\s0 file space that becomes the user's home directory, then designates the directory's owner and sets its access control list (\s-1ACL\s0). .PP Only one \f(CW\*(C`V\*(C'\fR instruction can appear in the template file, and one must appear if the template file contains any instructions at all (is not empty). All other instructions are optional, except that the template must include \f(CW\*(C`G\*(C'\fR instructions if the \f(CW$AUTO\fR variable appears in it. (The \&\f(CW\*(C`V\*(C'\fR instruction is not necessarily the first line in the template. If the template includes the \f(CW$AUTO\fR variable, then the \f(CW\*(C`G\*(C'\fR instructions which provide values for the variable must precede it in the file.) .PP The instruction has the following syntax: .PP .Vb 1 \& V .Ve .PP where .IP "V" 4 .IX Item "V" Indicates a volume creation instruction. It must be a capital letter. .IP "" 4 .IX Item "" Specifies the volume's name. To follow the convention for \s-1AFS\s0 user volume names, specify the value \f(CW\*(C`user.$USER\*(C'\fR. Provide a value for the \f(CW$USER\fR variable via the \fBuss add\fR command's \fB\-user\fR argument or the field in the bulk input file \fBadd\fR instruction. .IP "" 4 .IX Item "" Names the file server machine on which to create the new user's volume. It is best to provide the fully-qualified hostname (for example, \&\f(CW\*(C`fs1.example.com\*(C'\fR), but an abbreviated form is acceptable provided that the cell's naming service is available to resolve it at the time the volume is created. To read in the value from the \fBuss add\fR command's \fB\-server\fR argument, specify the value \f(CW$SERVER\fR. .IP "" 4 .IX Item "" Specifies the partition on which to create the user's volume; it must be on the file server machine named in the field. Identify the partition by its complete name (for example, \fI/vicepa\fR) or use or use one of the following abbreviations. .Sp .Vb 2 \& /vicepa = vicepa = a = 0 \& /vicepb = vicepb = b = 1 .Ve .Sp After \fI/vicepz\fR (for which the index is 25) comes .Sp .Vb 2 \& /vicepaa = vicepaa = aa = 26 \& /vicepab = vicepab = ab = 27 .Ve .Sp and so on through .Sp .Vb 1 \& /vicepiv = vicepiv = iv = 255 .Ve .Sp To read in the value from the \fBuss add\fR command's \fB\-partition\fR argument, specify the value \f(CW$PART\fR. .IP "" 4 .IX Item "" Sets the maximum number of kilobyte blocks the volume can occupy on the file server machine's disk. Specify an integer constant if all volumes have the same quota (\f(CW1024\fR equals a megabyte), or use one of the number variables ($1 through \f(CW$9\fR) to assign different values to different volumes. .IP "" 4 .IX Item "" Creates a mount point for the volume, which serves as the volume's root directory. Include the \f(CW$USER\fR variable as part of the pathname to follow the convention that user home directory names include the username. .Sp Specify the read/write path to the mount point, to avoid the failure that results from attempting to create a new mount point in a read-only volume. By convention, the read/write path is indicated by placing a period before the cell name at the pathname's second level (for example, \&\fI/afs/.example.com\fR). If the \f(CW$AUTO\fR variable appears in this field, the directories named by each \f(CW\*(C`G\*(C'\fR instruction possibly already indicate the read/write path. For further discussion of the concept of read/write and read-only paths through the filespace, see the reference page for the \fBfs mkmount\fR command. .IP "" 4 .IX Item "" Specifies the username or \s-1UNIX\s0 user \s-1ID\s0 (\s-1UID\s0) of the user to be designated the mount point's owner in the output from the \s-1UNIX\s0 \f(CW\*(C`ls \-ld\*(C'\fR command. To follow the convention for home directory ownership, place the value \&\f(CW$UID\fR in this field. .IP "<\s-1ACL\s0>" 4 .IX Item "" Sets the \s-1ACL\s0 on the new directory. Provide one or more paired values, each pair consisting of an \s-1AFS\s0 username or group name and the desired permissions, in that order. Separate the two parts of the pair, and each pair, with a space. The \fBfs setacl\fR reference page describes the available permissions. .Sp Grant all permissions to the new user at least. The appropriate value is \f(CW\*(C`$USER all\*(C'\fR. .Sp \&\s-1AFS\s0 automatically grants the system:administrators group all permissions as well. It is not possible to grant any permissions to the issuer of the \&\fBuss\fR command. As the last step in account creation, the \fBuss\fR command interpreter automatically deletes that user from any ACLs set during the creation process. .SS "The X Instruction for Running a Command" .IX Subsection "The X Instruction for Running a Command" The \f(CW\*(C`X\*(C'\fR instruction in a uss template file runs the indicated command, which can be a standard \s-1UNIX\s0 or \s-1AFS\s0 command. It can include any variables from the template file, which the \fBuss\fR command interpreter resolves before passing the command on to the appropriate other command interpreter. It must be a single line only, however (cannot contain carriage returns or newline characters). .PP Any number of \f(CW\*(C`X\*(C'\fR instructions can appear in the template file. If an instruction manipulates an element created by another instruction, it must follow that instruction in the file. .PP The instruction has the following syntax: .PP .Vb 1 \& X "" .Ve .PP where .IP "X" 4 .IX Item "X" Indicates a command execution instruction. It must be a capital letter. .IP "" 4 .IX Item "" Specifies the command to run. Surround it with double quotes as shown if it contains one or more spaces. It can contain any variables from the template file, but not newline characters. .SH "EXAMPLES" .IX Header "EXAMPLES" The following example A instruction sets a password lifetime of 254 days, prohibits password reuse, limits the number of consecutive failed authentication attempts to nine and sets the corresponding locktime to 25:30 minutes (which is a multiple of 8.5 minutes). The username is read in from the \fB\-user\fR argument to the \fBuss add\fR command or from the \&\fIusername\fR field in each \f(CW\*(C`add\*(C'\fR instruction in a bulk input file. .PP .Vb 1 \& A $USER 254 noreuse 9 25:30 .Ve .PP The following example \f(CW\*(C`D\*(C'\fR instruction creates a directory called \&\fIpublic\fR in a new user's home directory, designates the user as the directory's owner, and grants him or her all \s-1ACL\s0 permissions. .PP .Vb 1 \& D $MTPT/public 0755 $UID $USER all .Ve .PP The following example \f(CW\*(C`E\*(C'\fR instruction creates a file in the current working directory called \fI\fIusername\fI.etcp\fR. The contents are an entry suitable for incorporating into the cell's global \fI/etc/password\fR file. .PP .Vb 1 \& E $USER.etcp 0644 root "$USER:X:$UID:10:$NAME:$MTPT:/bin/csh" .Ve .PP The following example \f(CW\*(C`F\*(C'\fR instruction, appropriate for the Example Corporation cell, copies a prototype \fI.login\fR file into the user's home directory. .PP .Vb 1 \& F $MTPT/.login 0644 $UID /afs/example.com/common/uss/skel/.login .Ve .PP In the following example, the Example Organization cell's administrators have decided to distribute user home directories evenly into three directories. They define three \f(CW\*(C`G\*(C'\fR instructions: .PP .Vb 3 \& G usr1 \& G usr2 \& G usr3 .Ve .PP and then put the following value in the field of the \f(CW\*(C`V\*(C'\fR instruction: .PP .Vb 1 \& /afs/example.org/$AUTO/$USER .Ve .PP Alternatively, if they include the entire directory pathname in the \f(CW\*(C`G\*(C'\fR instruction: .PP .Vb 3 \& G /afs/example.org/usr1 \& G /afs/example.org/usr2 \& G /afs/example.org/usr3 .Ve .PP then the field of the \f(CW\*(C`V\*(C'\fR instruction specifies only the following: .PP .Vb 1 \& $AUTO/$USER .Ve .PP The following example \f(CW\*(C`L\*(C'\fR instruction creates a hard link between the files \fImail\fR and \fImbox\fR in the user's home directory. .PP .Vb 1 \& L $MTPT/mbox $MTPT/mail .Ve .PP The following example \f(CW\*(C`S\*(C'\fR instruction, appropriate for the Example Corporation cell, links the file \fIMail/outgoing\fR in the user's home directory to the file \fI/afs/example.com/common/mail/outgoing\fR. .PP .Vb 1 \& S /afs/example.com/common/mail/outgoing $MTPT/Mail/outgoing .Ve .PP The following example \f(CW\*(C`V\*(C'\fR instruction creates a volume called \&\f(CW\*(C`user.\f(CIusername\f(CW\*(C'\fR on the \fI/vicepa\fR partition of the specified file server machine, assigning it a quota of 3000 kilobyte blocks. The mount point is under \fI/afs/example.com/usr\fR and matches the username (the value of the \f(CW$USER\fR variable). The user owns the home directory and has all access rights to it. The instruction appears on two lines only for legibility; it must appear on a single line in the template file. .PP .Vb 2 \& V user.$USER $SERVER.example.com /vicepa 3000 \e \& /afs/example.com/usr/$USER $UID $USER all .Ve .PP The following example \f(CW\*(C`X\*(C'\fR instruction mounts the backup version of the user's volume at the \fIOldFiles\fR subdirectory. .PP .Vb 1 \& X "fs mkm /afs/example.com/usr/$USER/OldFiles user.$USER.backup" .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIuss_bulk\fR\|(5), \&\fIfs_mkmount\fR\|(1), \&\fIuss_add\fR\|(8) .SH "COPYRIGHT" .IX Header "COPYRIGHT" \&\s-1IBM\s0 Corporation 2000. All Rights Reserved. .PP This documentation is covered by the \s-1IBM\s0 Public License Version 1.0. It was converted from \s-1HTML\s0 to \s-1POD\s0 by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.