src/man/uss_bulk.1

   1 uss bulk                   AFS Commands                uss bulk
   2
   3
   4 NAME
   5
   6    uss bulk -- execute multiple uss commands.
   7
   8
   9    uss bulk  -file <bulk input file>  [-template <pathname of
  10    template file>]
  11    [-verbose]  [-cell <cell name>]
  12    [-admin <administrator to authenticate>]  [-dryrun]
  13    [-overwrite]
  14    [-help]
  15
  16    uss b  -f <bulk input file>  [-t <pathname of template
  17    file>] [-v]  [-c <cell name>]
  18    [-a <administrator to authenticate>]  [-d]  [-o]  [-h]
  19
  20 DESCRIPTION
  21
  22    Executes  the  uss commands listed in bulk input file, which
  23    must already exist.  If bulk input file has add commands  in
  24    it  that  create  complete (rather than authentication-only)
  25    accounts, then the issuer must also specify a template using
  26    pathname of template file.
  27
  28 WARNING
  29
  30    The  following warning applies when all of the following are
  31    true:
  32
  33       - this command is issued on machines running Ultrix
  34
  35       - the bulk file contains add lines
  36
  37       - the template file used for the  account  creations
  38         is not 0-length.
  39
  40    In this set of circumstances, the issuer must use the -admin
  41    argument to adopt a privileged AFS identity while  remaining
  42    "root"  in  the  local  machine's  UNIX file system.  Ultrix
  43    allows only "root" to issue the /etc/chown command that  the
  44    add   command   invokes  to  set  the  owner  of  files  and
  45    directories created by template lines.  At  the  same  time,
  46    AFS  allows only a privileged administrator to issue the AFS
  47    commands invoked; "root" is not normally  a  privileged  AFS
  48    administrator.
  49
  50    Other  operating  systems  allow  users other than "root" to
  51    issue /etc/chown, but users may still find it convenient  to
  52    adopt different identities in the AFS and UNIX file systems.
  53    Being authenticated in AFS as a privileged user is  required
  54    under all operating systems.
  55
  56 ARGUMENTS
  57
  58    -file     names  the  file  containing  the  uss commands to
  59              execute.    If  the  issuer  does  not  provide  a
  60              pathname, the command interpreter assumes the file
  61              is in the working directory.  The BULK FILE FORMAT
  62              section  details  the  proper  format  for command
  63              lines in the bulk file.
  64
  65    -template names the template file for any add commands  that
  66
  67
  68
  69              appear in the bulk input file.  If the issuer does
  70              not provide a pathname,  the  command  interpreter
  71              assumes  the  template  file  is  in  the  working
  72              directory.  See  the  AFS  System  Administrator's
  73              Guide for a definition of template format.
  74
  75    -verbose  causes  the  command  interpreter  to  produce (on
  76              stdout) a more detailed trace of the actions it is
  77              executing.    By  default, only warnings and error
  78              messages appear.
  79
  80    -cell     specifies the cell in which to  run  the  command.
  81              See  section  7.1 in the Reference Manual for more
  82              details.  -admin
  83              names  the  user  whom  the Authentication Servers
  84              should authenticate for purposes  of  creating  an
  85              Authentication Database entry.  See section 7.1 in
  86              the Reference Manual for more details.  Note: When
  87              the  bulk  file contains add lines, issuers of the
  88              uss bulk command on machines running  Ultrix  must
  89              use  this argument in order to adopt an privileged
  90              AFS identity while remaining "root" in  the  local
  91              machine's  UNIX  file  system.   See the preceding
  92              WARNING.
  93
  94    -dryrun   indicates that the command interpreter should  not
  95              actually  execute  the  command, but should report
  96              all the actions it would perform if executing  it.
  97              See  section  7.1 in the Reference Manual for more
  98              details.
  99
 100    -overwrite
 101              instructs  the command interpreter (when add lines
 102              appear  in  the  bulk  file)  to   overwrite   any
 103              directories,  files  and  links  that exist in the
 104              file system related to the user for which it  also
 105              finds  definitions  on template "D", "E", "F", "L"
 106              and "S" lines.   If  this  flag  is  omitted,  the
 107              command  interpreter  prompts,  once  for each add
 108              line in the bulk file, for confirmation  that  the
 109              issuer  really  wants to overwrite those elements.
 110              This flag should not be used if the bulk file does
 111              not contain add lines.
 112
 113    -help     prints  the  online help for this command.  Do not
 114              provide any other arguments  or  flags  with  this
 115              one.   See section 7.1 in the Reference Manual for
 116              more details.
 117
 118 BULK FILE FORMAT
 119
 120    Five types of command lines can appear  in  the  bulk  file:
 121    add,  delete, exec, savevolume, and delvolume.  Each command
 122    line should have a carriage return only  at  the  end,  even
 123    though it may cover several lines on the screen.
 124
 125
 126
 127    The add line
 128
 129    Each  add line is the equivalent of a uss add command issued
 130    on the command line.  Begin the line with  "add"  only,  not
 131    "uss add",  and provide the arguments in the same order they
 132    would appear on the uss add command  line,  separating  each
 133    with a colon.  Only the first argument, corresponding to the
 134    command line argument -user, is required.  To omit  a  value
 135    for  an  argument  (presumably because it is optional or the
 136    template specifies a constant value for  it),  type  nothing
 137    between  two  colons.  After the last argument provided, end
 138    the line with either a  colon  and  carriage  return,  or  a
 139    carriage return alone.
 140
 141    The  eighth  through  seventeenth  fields  are for assigning
 142    values to the number variables, with the  fields  listed  in
 143    increasing numerical order.  The issuer must indicate either
 144    a value or an empty field (nothing between two  colons)  for
 145    every  variable that precedes the last one being assigned an
 146    actual value.  It  is  acceptable,  but  not  necessary,  to
 147    indicate empty fields for any number variables following the
 148    last one actually assigned a value.
 149
 150    The  following  concrete  representation   uses   the   same
 151    identifiers for arguments as the uss add definition.  The "{
 152    }" notation indicates that each entry between vertical  bars
 153    is  one  possible choice.  Remember that an instruction like
 154    this would appear on a single line in the actual bulk file.
 155
 156       add <login name>[:<full name>][:<initial passwd>][:<file
 157       [:<file server's disk partition for home volume>][:<home
 158       [:<uid to assign the user>][:{<var1> | :<var1>:<var2> | :
 159            . . . . et cetera through.  . . .
 160       | :<var1>:<var2>:<var3>:<var4>:<var5>:<var6>:<var7>:<var8
 161
 162    Do not surround full name with double  quotes  in  the  bulk
 163    file,  even  though  its  counterpart on the regular uss add
 164    command line must be so surrounded.
 165
 166    The EXAMPLES section below may help to clarify the format of
 167    the add line.
 168
 169    The delete line
 170
 171    Each  delete  line is the equivalent of a uss delete command
 172    issued on the command line.  Begin the  line  with  "delete"
 173    only,  not  "uss delete",  and  provide the arguments in the
 174    same order they would appear on the uss delete command line,
 175    separating  each  with a colon.  Provide values for at least
 176    the  first  two  arguments  (corresponding  to   -user   and
 177    -mountpoint   on  the  command  line).    The  third  field,
 178    corresponding to -savevolume, is optional; there  are  three
 179    possible values:
 180
 181       - if  the  word  savevolume  appears, the volume and
 182         VLDB entry will not be removed
 183
 184       - if the word delvolume appears, the volume and VLDB
 185         entry will be removed
 186
 187       - if  the  field  is  blank, then the volume will be
 188
 189
 190
 191         treated according to the prevailing  default  (see
 192         the  following  description  of the savevolume and
 193         delvolume lines to learn how to set the default).
 194
 195    After the last argument provided, end the line with either a
 196    colon and carriage return or a carriage return alone.
 197
 198    The   following   concrete   representation  uses  the  same
 199    identifiers for arguments as does the uss delete definition.
 200    The  "{    }"  notation  indicates that each entry between a
 201    vertical line is one possible  choice.    Remember  that  an
 202    instruction  like  this would appear on a single line in the
 203    actual bulk file.  The EXAMPLES section illustrates  use  of
 204    this line.
 205
 206       delete <account name>:<full mount point pathname>
 207              [:{savevolume | delvolume |  }]
 208
 209    The exec line
 210
 211    This  line  causes  the  indicated  UNIX shell command to be
 212    executed.  Its format is
 213
 214       exec <command string to execute>
 215
 216    The savevolume and delvolume lines
 217
 218    The savevolume and delvolume lines set the default treatment
 219    of  volumes  in  delete  lines  that follow them in the bulk
 220    file.  The savevolume line prevents the  removal  of  volume
 221    and  VLDB  entry  for  all  subsequent  delete  lines.   The
 222    delvolume line causes the removal of volume and  VLDB  entry
 223    for  all  subsequent delete lines.  The default treatment if
 224    neither line appears in a bulk file is to remove the  volume
 225    and   VLDB;  delete  lines  that  appear  before  the  first
 226    savevolume line are also treated this way.
 227
 228    An explicit savevolume or delvolume instruction in the third
 229    field  of an individual delete line overrides the default in
 230    effect at the time.  If nothing appears in the third  field,
 231    the default is obeyed.
 232
 233    Neither  command  takes  arguments  (the  word savevolume or
 234    delvolume should appear by itself on the line).  The  effect
 235    of  either  line  lasts  until  the end of the bulk file, or
 236    until its opposite appears in the file.  Multiple  instances
 237    of each command can be used to toggle back and forth between
 238    removal and non-removal of volumes.
 239
 240 EXAMPLES
 241
 242    The following shows the proper format for an add line in the
 243    bulk  file  when  only  the  first  (required)  argument  is
 244    provided, and when the first three arguments  are  provided.
 245    In the first case, the user's "real name" is set to anderson
 246    and password to changeme (the defaults).
 247
 248       add anderson
 249       add smith:John Smith:js_pswd
 250
 251    The following add line example supposes  that  the  Transarc
 252
 253
 254
 255    Corporation cell uses a template with the following "V" line
 256    in it:
 257
 258    V user.$USER $SERVER.transarc.com /vicep$PART 2000
 259           /afs/transarc.com/usr/$3/$USER $UID $USER all
 260
 261    To create an account for users John Smith from the Marketing
 262    Department  and  Pat  Jones from the Finance Department, the
 263    appropriate add commands in the bulk file might be:
 264
 265       add smith:John Smith::fs1:a:::::marketing
 266       add jones:Pat Jones::fs3:c:::::finance
 267
 268    The effect would be to establish an account called smith  in
 269    the Protection and Authentication Databases, with an initial
 270    password changeme and a  value  for  $UID  provided  by  the
 271    Protection  Server.  His volume, user.smith, would reside on
 272    partition    "/vicepa"    of     file     server     machine
 273    "fs1.transarc.com"     and     would     be    mounted    at
 274    /afs/transarc.com/usr/marketing/smith.   He  would  own  his
 275    home  directory and have full access to it.  The account for
 276    jones would be similar,  except  that  it  would  reside  on
 277    partition     "/vicepc"     of     file    server    machine
 278    "fs3.transarc.com"    and    would     be     mounted     at
 279    /afs/transarc.com/usr/finance/jones.
 280
 281    Notice  that  the  fields  corresponding  to <home directory
 282    mount point>, <uid to assign the user>,  <var1>  and  <var2>
 283    are  empty  (between  a  and  marketing on the first example
 284    line) since their corresponding variables do not  appear  in
 285    the  template  file.    The  <initial  passwd> field is also
 286    empty.
 287
 288    The issuer could, if he or she choose, specify  values/empty
 289    fields  for  all  nine  number variables.  In this case, the
 290    bulk file lines shown above would look like:
 291
 292       add smith:John Smith::fs1:a:::::marketing::::::
 293       add jones:Pat Jones::fs3:c:::::finance::::::
 294
 295    The following shows a complete bulk file containing a set of
 296    delete  lines  combined  with  a  savevolume  line.  Because
 297    smith, pat, and rogers appear before the savevolume  command
 298    and  their third field is blank, the volume will be removed.
 299    The volume for terry will not be removed, but johnson's will
 300    be  because  the  delvolume in the third field overrides the
 301    current default.
 302
 303        delete smith:/afs/transarc.com/usr/smith
 304        delete pat:/afs/transarc.com/usr/pat
 305        delete rogers:/afs/transarc.com/usr/rogers
 306        savevolume
 307        delete terry:/afs/transarc.com/usr/terry
 308        delete johnson:/afs/transarc.com/usr/johnson:delvolu
 309
 310    The following exec  example  supposes  that  the  bulk  file
 311    contains  a  set of add lines followed by delete lines.  The
 312    operator places this line between the two sets to flag  when
 313    the additions are finished and the deletions beginning.
 314
 315        exec echo "Additions completed; beginning deletions.
 316
 317
 318
 319 PRIVILEGE REQUIRED
 320
 321    Issuer  (or  person  named by -admin argument) must have the
 322    privileges necessary to run all of the commands in the  bulk
 323    file individually.
 324
 325 MORE INFORMATION