doc/html/AdminReference/auarf054.htm

   1 <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 4//EN">
   2 <HTML><HEAD>
   3 <TITLE>Administration Reference</TITLE>
   4 <!-- Begin Header Records  ========================================== -->
   5 <!-- /tmp/idwt3672/auarf000.scr converted by idb2h R4.2 (359) ID      -->
   6 <!-- Workbench Version (AIX) on 3 Oct 2000 at 16:18:30                -->
   7 <META HTTP-EQUIV="updated" CONTENT="Tue, 03 Oct 2000 16:18:29">
   8 <META HTTP-EQUIV="review" CONTENT="Wed, 03 Oct 2001 16:18:29">
   9 <META HTTP-EQUIV="expires" CONTENT="Thu, 03 Oct 2002 16:18:29">
  10 </HEAD><BODY>
  11 <!-- (C) IBM Corporation 2000. All Rights Reserved    -->
  12 <BODY bgcolor="ffffff">
  13 <!-- End Header Records  ============================================ -->
  14 <A NAME="Top_Of_Page"></A>
  15 <H1>Administration Reference</H1>
  16 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf053.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Bot_Of_Page"><IMG SRC="../bot.gif" BORDER="0" ALT="[Bottom of Topic]"></A> <A HREF="auarf055.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
  17 <P>
  18 <H2><A NAME="HDRUSSBULKINPUT" HREF="auarf002.htm#ToC_52">uss Bulk Input File</A></H2>
  19 <A NAME="IDX4099"></A>
  20 <A NAME="IDX4100"></A>
  21 <A NAME="IDX4101"></A>
  22 <P><STRONG>Purpose</STRONG>
  23 <P>Provides instructions for the <B>uss bulk</B> command
  24 <P><STRONG>Description</STRONG>
  25 <P>The <B>uss</B> bulk input file lists instructions for the
  26 <B>uss</B> command interpreter to execute when running the <B>uss
  27 bulk</B> command. If the file includes <B>add</B> instructions
  28 that reference a <B>uss</B> template file, then the template file must
  29 also exist.
  30 <P><B>Summary of Bulk Input File Instructions</B>
  31 <P>The bulk input file can include the following instructions, each on its own
  32 line. A more detailed description of each instruction's syntax
  33 follows this list.
  34 <DL>
  35 <P><DT><B>add
  36 </B><DD>Creates a user account. Equivalent to the <B>uss add</B>
  37 command.
  38 <P><DT><B>delete
  39 </B><DD>Deletes a user account. Equivalent to the <B>uss delete</B>
  40 command.
  41 <P><DT><B>delvolume
  42 </B><DD>Removes the volume and VLDB entry for each account referenced by a
  43 <B>delete</B> instruction that follows this instruction in the bulk input
  44 file.
  45 <P><DT><B>exec
  46 </B><DD>Executes a command.
  47 <P><DT><B>savevolume
  48 </B><DD>Preserves the volume and VLDB entry for each account referenced by a
  49 <B>delete</B> instruction that follows this instruction in the bulk input
  50 file.
  51 </DL>
  52 <P><B>The add Instruction for Creating an Account</B>
  53 <A NAME="IDX4102"></A>
  54 <A NAME="IDX4103"></A>
  55 <P>The <B>add</B> instruction creates a user account. Each instance
  56 in the bulk input file is equivalent in effect to a <B>uss add</B> command
  57 issued on the command line. The order of the instruction's fields
  58 matches the order of arguments to the <B>uss add</B> command, although
  59 some arguments do not have a corresponding field. Like the <B>uss
  60 add</B> command's arguments, many of the fields correspond to (provide
  61 a value for) a variable in the <B>uss</B> template file, as indicated in
  62 the following description of each field.
  63 <P>The instruction's syntax is as follows. It appears on multiple
  64 lines here only for the sake of legibility--each <B>add</B>
  65 instruction must appear on a single line in the bulk input file.
  66 <PRE>   add <VAR>username</VAR>[:<VAR>full_name</VAR>][:<VAR>initial_password</VAR>][:<VAR>password_expires</VAR>]
  67        [:<VAR>file_server</VAR>][:<VAR>partition</VAR>][:<VAR>mount_point</VAR>][:<VAR>uid</VAR>][:<VAR>var1</VAR>][:<VAR>var2</VAR>]
  68        [:<VAR>var3</VAR>][:<VAR>var4</VAR>][:<VAR>var5</VAR>][:<VAR>var6</VAR>][:<VAR>var7</VAR>][:<VAR>var8</VAR>][:<VAR>var9</VAR>][:]
  69
  70 </PRE>
  71 <P>To omit a value for a field (presumably because it is optional or the
  72 template specifies a constant value for it), type nothing between the two
  73 colons that surround it. After the last argument provided, end the line
  74 with either a colon and carriage return, or a carriage return alone.
  75 <P>The meaning of, and acceptable values for, each field are as
  76 follows.
  77 <DL>
  78 <P><DT><B><VAR>username</VAR>
  79 </B><DD>Names the user's Authentication Database and Protection Database
  80 entries. It can include up to eight alphanumeric characters, but not
  81 the <B>:</B> (colon), <B>.</B> (period), or <B>@</B>
  82 (at-sign) characters. Because it becomes the username (the name under
  83 which a user logs in), it is best not to include shell metacharacters and to
  84 obey the restrictions that many operating systems impose on usernames
  85 (usually, to contain no more than eight lowercase letters).
  86 <P>Corresponding argument to the <B>uss add</B> command:
  87 <B>-user</B>. Corresponding variable in the template file:
  88 $USER.
  89 <P><DT><B><VAR>full_name</VAR>
  90 </B><DD>Specifies the user's full name. Do not surround it with double
  91 quotes (""), even if it contains spaces. If not provided, it defaults
  92 to the username in the <VAR>username</VAR> field.
  93 <P>Corresponding argument to the <B>uss add</B> command:
  94 <B>-realname</B>. Corresponding variable in the template
  95 file: $NAME. Many operating systems include a field for the full
  96 name in a user's entry in the local password file (<B>/etc/passwd</B>
  97 or equivalent), and this variable can be used to pass a value to be used in
  98 that field.
  99 <P><DT><B><VAR>initial_password</VAR>
 100 </B><DD>Specifies the user's initial password. Although the AFS
 101 commands that handle passwords accept strings of virtually unlimited length,
 102 it is best to use a password of eight characters or less, which is the maximum
 103 length that many applications and utilities accept. If not provided,
 104 this argument defaults to the string <B>changeme</B>.
 105 <P>Corresponding argument to the <B>uss add</B> command:
 106 <B>-pass</B>. Corresponding variable in the template file:
 107 none.
 108 <P><DT><B><VAR>password_expires</VAR>
 109 </B><DD>Sets the number of days after a user's password is changed that it
 110 remains valid. Provide an integer from the range <B>1</B> through
 111 <B>254</B> to specify the number of days until expiration, or the value
 112 <B>0</B> to indicate that the password never expires (the default).
 113 <P>When the password becomes invalid (expires), the user is unable to
 114 authenticate, but has 30 more days in which to issue the <B>kpasswd</B>
 115 command to change the password (after that, only an administrator can change
 116 it).
 117 <P>Corresponding argument to the <B>uss add</B> command:
 118 <B>-pwexpires</B>. Corresponding variable in the template
 119 file: $PWEXPIRES.
 120 <P><DT><B><VAR>file_server</VAR>
 121 </B><DD>Names the file server machine on which to create the new user's
 122 volume. It is best to provide a fully-qualified hostname (for example,
 123 <B>fs1.abc.com</B>), but an abbreviated form is acceptable
 124 provided that the cell's naming service is available to resolve it at the
 125 time the volume is created.
 126 <P>Corresponding argument to the <B>uss add</B> command:
 127 <B>-server</B>. Corresponding variable in the template file:
 128 $SERVER.
 129 <P><DT><B><VAR>partition</VAR>
 130 </B><DD>Specifies the partition on which to create the user's volume; it
 131 must reside on the file server machine named in the <VAR>file_server</VAR>
 132 field. Identify the partition by its complete name (for example,
 133 <B>/vicepa</B>, or use one of the following abbreviations:
 134 <PRE>   <B>/vicepa</B>     =     <B>vicepa</B>      =      <B>a</B>      =      <B>0</B>
 135    <B>/vicepb</B>     =     <B>vicepb</B>      =      <B>b</B>      =      <B>1</B>
 136
 137 </PRE>
 138 <P>
 139 <P>After <B>/vicepz</B> (for which the index is 25) comes
 140 <PRE>   <B>/vicepaa</B>    =     <B>vicepaa</B>     =      <B>aa</B>     =      <B>26</B>
 141    <B>/vicepab</B>    =     <B>vicepab</B>     =      <B>ab</B>     =      <B>27</B>
 142
 143 </PRE>
 144 <P>and so on through
 145 <PRE>   <B>/vicepiv</B>    =     <B>vicepiv</B>     =      <B>iv</B>     =      <B>255</B>
 146
 147 </PRE>
 148 <P>Corresponding argument to the <B>uss add</B> command:
 149 <B>-partition</B>. Corresponding variable in template:
 150 $PART.
 151 <P><DT><B><VAR>mount_point</VAR>
 152 </B><DD>Specifies the complete pathname for the user's home directory.
 153 <P>Corresponding argument to the <B>uss add</B> command:
 154 <B>-mount</B>.
 155 <P>Corresponding variable in template: $MTPT, but in the template
 156 file's <B>V</B> instruction only. Occurrences of the $MTPT
 157 variable in template instructions that follow the <B>V</B> instruction
 158 take their value from the <B>V</B> instruction's <VAR>mount_point</VAR>
 159 field. Thus the value of this command line argument becomes the value
 160 for the $MTPT variable in instructions that follow the <B>V</B>
 161 instruction only if the string $MTPT appears alone in the <B>V</B>
 162 instruction's <VAR>mount_point</VAR> field.
 163 <P><DT><B><VAR>uid</VAR>
 164 </B><DD>Specifies a positive integer other than <B>0</B> (zero) to assign as
 165 the user's AFS UID. If this argument is omitted, the Protection
 166 Server assigns an AFS UID that is one greater than the current value of the
 167 <TT>max</TT> <TT>user</TT> <TT>id</TT> counter (use the <B>pts
 168 listmax</B> command to display the counter). If including this
 169 argument, first use the <B>pts examine</B> command to verify that no
 170 existing account already has the desired AFS UID; if one does, the
 171 account-creation process terminates with an error.
 172 <P>Corresponding argument to the <B>uss add</B> command:
 173 <B>-uid</B>. Corresponding variable in template: $UID.
 174 <P><DT><B><VAR>var1</VAR> through <VAR>var9</VAR>
 175 </B><DD>Specifies values for each of the number variables $1 through $9 that can
 176 appear in the template file. The number variables allow the
 177 administrator to provide values for variables other than the set defined by
 178 the <B>uss</B> command suite.
 179 <P>Corresponding argument to the <B>uss add</B> command:
 180 <B>-var</B>. Corresponding variables in template: $1 through
 181 $9.
 182 <P>If providing a value in any of the fields, then in every field that
 183 precedes it either provide an actual value or indicate an empty field by
 184 putting nothing between two colons. It is acceptable, but not
 185 necessary, to indicate empty fields by putting colons after the last field
 186 that contains an actual value.
 187 </DL>
 188 <P><B>The delete Instruction for Deleting an Account</B>
 189 <A NAME="IDX4104"></A>
 190 <A NAME="IDX4105"></A>
 191 <P>The <B>delete</B> instruction deletes a user account from the
 192 system. Each instance in the bulk input file is equivalent in effect to
 193 a <B>uss delete</B> command issued on the command line. The order
 194 of the instruction's fields matches the order of arguments to the
 195 <B>uss delete</B> command:
 196 <PRE>   delete <VAR>username</VAR>:<VAR>mount_point_path</VAR>[:{ savevolume | delvolume }][:]
 197
 198 </PRE>
 199 <P>where
 200 <DL>
 201 <P><DT><B><VAR>username</VAR>
 202 </B><DD>Names the entry to delete from the Protection and Authentication
 203 Databases.
 204 <P><DT><B><VAR>mount_point_path</VAR>
 205 </B><DD>Specifies the complete pathname to the user's home directory, which
 206 is deleted from the filespace. By default, the volume mounted there is
 207 also deleted from the file server machine where it resides, as is its record
 208 from the Volume Location Database (VLDB). To prevent deletion, include
 209 the <B>savevolume</B> string in the instruction's third field, or
 210 precede this <B>delete</B> instruction with a <B>savevolume</B>
 211 instruction. Partial pathnames are interpreted relative to the current
 212 working directory.
 213 <P><DT><B>savevolume
 214 </B><DD>Retains the volume on its file server machine, and the corresponding entry
 215 in the VLDB. Provide this value or <B>delvolume</B> in the third
 216 field, or omit both values to treat the volume according to the prevailing
 217 default, which is set by a preceding <B>savevolume</B> or
 218 <B>delvolume</B> instruction in the bulk input file.
 219 <P><DT><B>delvolume
 220 </B><DD>Removes the volume from its file server machine, and the corresponding
 221 entry from the VLDB. Provide this value or <B>savevolume</B> in the
 222 third field, or omit both values to treat the volume according to the
 223 prevailing default, which is set by a preceding <B>savevolume</B> or
 224 <B>delvolume</B> instruction in the bulk input file.
 225 </DL>
 226 <P>After the last argument provided, end the line with either a colon and
 227 carriage return or a carriage return alone.
 228 <P><B>The exec Instruction for Executing a Command</B>
 229 <P>The <B>exec</B> instruction executes the specified command, which can
 230 be a UNIX shell script or command, a program, or an AFS command. The
 231 <B>uss</B> command interpreter must have the necessary privileges in AFS
 232 and the local file system; it assumes the AFS and local identities of the
 233 issuer of the <B>uss bulk</B> command.
 234 <P>The instruction's syntax is as follows:
 235 <PRE>   exec <VAR>command</VAR>
 236
 237 </PRE>
 238 <P><B>The delvolume and savevolume Instructions for Setting the Default
 239 Treatment of Volumes</B>
 240 <A NAME="IDX4106"></A>
 241 <A NAME="IDX4107"></A>
 242 <A NAME="IDX4108"></A>
 243 <A NAME="IDX4109"></A>
 244 <P>The <B>savevolume</B> and <B>delvolume</B> instructions determine
 245 the default treatment of volumes referenced by the <B>delete</B>
 246 instructions that follow them in the bulk input file. Their syntax is
 247 as follows:
 248 <PRE>   savevolume
 249    delvolume
 250
 251 </PRE>
 252 <P>The <B>savevolume</B> instruction prevents the removal of the volume
 253 and VLDB entry for all <B>delete</B> instruction that follow it in the
 254 bulk input file, and the <B>delvolume</B> instruction removes the volume
 255 and VLDB entry for all subsequent <B>delete</B> instructions.
 256 Either setting persists until its opposite appears in the file, or until the
 257 end of the bulk file.
 258 <P>If neither line appears in the bulk input file, the default is to remove
 259 the volume and the VLDB entry; <B>delete</B> instructions that appear
 260 before the first <B>savevolume</B> instruction are also subject to this
 261 default. If a <B>delete</B> instruction's third field
 262 specifies either <B>savevolume</B> or <B>delvolume</B>, that setting
 263 overrides the default.
 264 <P><STRONG>Examples</STRONG>
 265 <P>The following example <B>add</B> instruction creates an
 266 authentication-only account. The user's initial password is
 267 <B>changeme</B> (the default).
 268 <PRE>   add anderson
 269
 270 </PRE>
 271 <P>The following example <B>add</B> instructions refer to the indicated
 272 <B>V</B> instruction in a template file (which must appear on a single
 273 line in the template file).
 274 <PRE>   add smith:John Smith:::fs1:a:::::marketing
 275    add jones:Pat Jones:::fs3:c:::::finance
 276    V user.$USER $SERVER.abc.com /vicep$PART 2000 \
 277        /afs/abc.com/usr/$3/$USER $UID $USER all
 278
 279 </PRE>
 280 <P>The first <B>add</B> instruction creates an account called
 281 <B>smith</B> in the Protection and Authentication Databases, with an
 282 initial password <B>changeme</B> and a value for $UID provided by the
 283 Protection Server. The volume <B>user.smith</B> resides on
 284 partition <B>/vicepa</B> of file server machine
 285 <B>fs1.abc.com</B> and is mounted at
 286 <B>/afs/abc.com/usr/marketing/smith</B>. He owns his home
 287 directory and has all access permissions on its root directory's access
 288 control list (ACL). The account for <B>jones</B> is similar, except
 289 that the volume resides on partition <B>/vicepc</B> of file server machine
 290 <B>fs3.abc.com</B> and is mounted at
 291 <B>/afs/abc.com/usr/finance/jones</B>.
 292 <P>Notice that the fields corresponding to the volume mount point, UID, $1
 293 variable, and $2 variable are empty (between <TT>a</TT> and
 294 <TT>marketing</TT> on the first example line), because their corresponding
 295 variables do not appear in the template file. The initial password
 296 field is also empty.
 297 <P>The following <B>add</B> instructions are equivalent in effect to the
 298 preceding example, but explicitly indicate empty fields for all of the number
 299 variables that don't have a value:
 300 <PRE>   add smith:John Smith:::fs1:a:::::marketing::::::
 301    add jones:Pat Jones:::fs3:c:::::finance::::::
 302
 303 </PRE>
 304 <P>The following example shows a complete bulk file containing a set of
 305 <B>delete</B> instructions combined with a <B>savevolume</B>
 306 instruction. Because the <B>delete</B> instruction for users
 307 <B>smith</B>, <B>pat</B>, and <B>rogers</B> appear before the
 308 <B>savevolume</B> instruction and the third field is blank in each, the
 309 corresponding home volumes are removed. The volume for user
 310 <B>terry</B> is retained because the default established by the
 311 <B>savevolume</B> instruction applies to it, but user
 312 <B>johnson</B>'s volume is removed because the third field of her
 313 <B>delete</B> instruction overrides the current default.
 314 <PRE>   delete smith:/afs/abc.com/usr/smith
 315    delete pat:/afs/abc.com/usr/pat
 316    delete rogers:/afs/abc.com/usr/rogers
 317    savevolume
 318    delete terry:/afs/abc.com/usr/terry
 319    delete johnson:/afs/abc.com/usr/johnson:delvolume
 320
 321 </PRE>
 322 <P>The following example <B>exec</B> instruction appears between sets of
 323 <B>add</B> and <B>delete</B> instructions in a bulk input file.
 324 A message appears in the command shell where the <B>uss bulk</B> command
 325 is issued, to indicate when the additions are finished and the deletions
 326 beginning.
 327 <PRE>   exec echo "Additions completed; beginning deletions..."
 328
 329 </PRE>
 330 <P><STRONG>Related Information</STRONG>
 331 <P><A HREF="auarf055.htm#HDRUSSFILE">uss Template File</A>
 332 <P><A HREF="auarf243.htm#HDRUSS_ADD">uss add</A>
 333 <P><A HREF="auarf245.htm#HDRUSS_BULK">uss bulk</A>
 334 <P><A HREF="auarf246.htm#HDRUSS_DELETE">uss delete</A>
 335 <P>
 336 <HR><P ALIGN="center"> <A HREF="../index.htm"><IMG SRC="../books.gif" BORDER="0" ALT="[Return to Library]"></A> <A HREF="auarf002.htm#ToC"><IMG SRC="../toc.gif" BORDER="0" ALT="[Contents]"></A> <A HREF="auarf053.htm"><IMG SRC="../prev.gif" BORDER="0" ALT="[Previous Topic]"></A> <A HREF="#Top_Of_Page"><IMG SRC="../top.gif" BORDER="0" ALT="[Top of Topic]"></A> <A HREF="auarf055.htm"><IMG SRC="../next.gif" BORDER="0" ALT="[Next Topic]"></A> <A HREF="auarf284.htm#HDRINDEX"><IMG SRC="../index.gif" BORDER="0" ALT="[Index]"></A> <P>
 337 <!-- Begin Footer Records  ========================================== -->
 338 <P><HR><B>
 339 <br>&#169; <A HREF="http://www.ibm.com/">IBM Corporation 2000.</A>  All Rights Reserved
 340 </B>
 341 <!-- End Footer Records  ============================================ -->
 342 <A NAME="Bot_Of_Page"></A>
 343 </BODY></HTML>