Creating and Deleting Multiple Accounts with the uss bulk Command

The uss bulk command allows you to create and delete many accounts at once. Before executing the command, you must

Constructing a Bulk Input File

You can include five types of instructions in a bulk input file: add, delete, exec, savevolume, and delvolume. The following sections discuss their uses.

Creating a User Account with the add Instruction

Each add instruction creates a single user account, and so is basically the equivalent of issuing one uss add command. There is no limit to the number of add instructions in the bulk input file.

As indicated by the following syntax statement, the order of the instruction's fields matches the order of arguments to the uss add command (though some of the command's arguments do not have a corresponding field). Like the uss add command's arguments, many of the fields provide a value for a variable in the uss template file. Each instruction must be a single line in the file (have a newline character only at its end); it appears on multiple lines here only for legibility.

add username[:full_name][:initial_password][:password_expires]
   [:file_server][:partition][:mount_point][:uid]
   [:var1][:var2][:var3][:var4][:var5][:var6][:var7][:var8][:var9][:]

For a complete description of the acceptable values in each field, see the uss Bulk Input File reference page in the OpenAFS Administration Reference, or the description of the corresponding arguments to the uss add command, in To create an AFS account with the uss add command. Following are some basic notes:

  • Begin the line with the string add only, not uss add.

  • Only the first argument, username, is required. It corresponds to the -user argument to the uss add command.

  • Do not surround the full_name value with double quotes, even though you must use them around the value for the -realname argument to the uss add command.

  • If you want to omit a value for an argument, indicate an empty field by using two colons with nothing between them. Leaving a field empty is acceptable if the corresponding command line argument is optional or if the corresponding variable does not appear in the template file. For every field that precedes the last one to which you assign an actual value, you must either provide a value or indicate an empty field. It is acceptable, but not necessary, to indicate empty fields after the last one in which you assign a value.

  • After the last field, end the line with either a colon and newline character (<Return>), or a newline alone.

  • The final nine fields are for assigning values to the number variables ($1 through $9), with the fields listed in increasing numerical order. Specify the value only, not the variable number.

Deleting a User Account with the delete Instruction

Each delete instruction deletes a single user account, and so is basically the equivalent of issuing one uss delete command. There is no limit to the number of delete instructions in the bulk input file.

Like all instructions in the bulk input file, each delete instruction must be a single line in the file (have a newline character only at its end), even though it can cover multiple lines on a display screen. The curly braces ({ }) indicate two mutually exclusive choices.

delete username:mount_point_path[:{ savevolume | delvolume }][:]

For a complete description of the acceptable values in each field, see the uss Bulk Input File reference page in the OpenAFS Administration Reference or the description of the corresponding arguments to the uss delete command, in To delete an AFS account. Following are some basic notes:

  • Begin the line with the string delete only, not uss delete.

  • The first two arguments, username and mount_point_path, are required. They correspond to the -user and -mountpoint arguments to the uss delete command.

  • The third field, which is optional, controls whether the user's home volume is removed from the file server where it resides, along with the corresponding VLDB entry. There are three possible values:

    • No value treats the volume and VLDB entry according to the prevailing default, which is established by a preceding savevolume or delvolume instruction in the template file. See the following discussion of those instructions to learn how the default is set.

    • The string savevolume preserves the volume and VLDB entry, overriding the default.

    • The string delvolume removes the volume and VLDB entry, overriding the default.

  • After the last field, end the line with either a colon and newline character (<Return>), or a newline alone.

Running a Command or Script with the exec Instruction

The exec instruction runs the indicated AFS command, compiled program, or UNIX shell script or command. The command processor assumes the AFS and local identities of the issuer of the uss bulk command, who must have the privileges required to run the command.

The instruction's syntax is as follows:

exec command

It is not necessary to surround the command string with double quotes (" ") or other delimiters.

Setting the Default Treatment of Volumes with the delvolume and savevolume Instructions

The savevolume and delvolume instructions set the default treatment of volumes referenced by the delete instructions that follow them in the bulk input file. Their syntax is as follows:

        savevolume
        delvolume
      

Both instructions are optional and take no arguments. If neither appears in the bulk input file, then by default all volumes and VLDB entries referenced by delete instructions are removed. If the savevolume instruction appears in the file, it prevents the removal of the volume and VLDB entry referenced by all subsequent delete instructions in the file. The delvolume instruction explicitly establishes the default (which is deletion) for subsequent delete instructions.

The effect of either instruction lasts until the end of the bulk input file, or until its opposite appears. To override the prevailing default for a particular delete instruction, put the savevolume or delvolume string in the instruction's third field. (You can also use multiple instances of the savevolume and delvolume instructions to toggle back and forth between default preservation and deletion of volumes.)

Example Bulk Input File Instructions

To create an authentication-only account, use an add instruction like the following example, which includes only the first (username) argument. The user's real name is set to match the username (anderson) and her initial password is set to the string changeme.

   add anderson 

The following example also creates an authentication-only account, but sets nondefault values for the real name and initial password.

   add smith:John Smith:js_pswd

The next two example add instructions require that the administrator of the ABC Corporation cell (abc.com) has written a uss template file with the following V instruction in it:

   V user.$USER $SERVER.abc.com /vicep$PART 10000 /afs/.abc.com/usr/$3/$USER \
       $UID $USER all

To create accounts for users named John Smith from the Marketing Department and Pat Jones from the Finance Department, the appropriate add instructions in the bulk input file are as follows:

   add smith:John Smith:::fs1:a:::::marketing
   add jones:Pat Jones:::fs3:c:::::finance

The new account for Smith consists of Protection and Authentication Database entries called smith. His initial password is the default string changeme, and the Protection Server generates his AFS UID. His home volume, called user.smith, has a 10,000 KB quota, resides on partition /vicepa of file server machine fs1.abc.com, and is mounted at /afs/.abc.com/usr/marketing/smith. The final $UID $USER all part of the V instruction gives him ownership of his home directory and all permissions on its ACL. The account for jones is similar, except that it resides on partition /vicepc of file server machine fs3.abc.com and is mounted at /afs/.abc.com/usr/finance/jones.

Notice that the fields corresponding to mount_point, uid, var1, and var2 are empty (between the values a and marketing on the first example line) because the corresponding variables do not appear in the V instruction in the template file. The initial_passwd and password_expires fields are also empty.

If you wish, you can specify values or empty fields for all nine number variables in an add instruction. In that case, the bulk input file instructions are as follows:

   add smith:John Smith:::fs1:a:::::marketing::::::
   add jones:Pat Jones:::fs3:c:::::finance::::::

The following example is a section of a bulk input file with a number of delete instructions and a savevolume instruction. Because the first three instructions appear before the savevolume instruction and their third field is blank, the corresponding volumes and VLDB entries are removed. The delete instruction for user terry follows the savevolume instruction, so her volume is not removed, but the volume for user johnson is, because the delvolume string in the third field of the delete instruction overrides the current default.

   delete smith:/afs/abc.com/usr/smith
   delete pat:/afs/abc.com/usr/pat
   delete rogers:/afs/abc.com/usr/rogers
   savevolume
   delete terry:/afs/abc.com/usr/terry
   delete johnson:/afs/abc.com/usr/johnson:delvolume

The following example exec instruction is useful as a separator between a set of add instructions and a set of delete instructions. It generates a message on the standard output stream that informs you of the uss bulk command's progress.

   exec echo "Additions completed; beginning deletions..."

To create and delete multiple AFS user accounts

  1. Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the admin user account has them, or you possibly have a personal administrative account. (To increase cell security, it is best to create special privileged accounts for use only while performing administrative procedures; for further discussion, see An Overview of Administrative Privilege.) If necessary, issue the klog command to authenticate.

       % klog admin_user
       Password: <admin_password>
    

    The following list specifies the necessary privileges and indicates how to check that you have them.

    • Membership in the system:administrators group. If necessary, issue the pts membership command, which is fully described in To display the members of the system:administrators group.

         % pts membership system:administrators
      
    • Inclusion in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

         % bos listusers <machine name>
      
    • The ADMIN flag on the Authentication Database entry. However, the Authentication Server always prompts you for a password in order to perform its own authentication. The following instructions direct you to specify the administrative identity on the uss command line itself.

    • The d (delete), i (insert) and l (lookup) permissions on the ACL of the parent directory for each volume mount point. If necessary, issue the fs listacl command, which is fully described in Displaying ACLs.

         % fs listacl [<dir/file path>]
      

      Members of the system:administrators group always implicitly have the a (administer) and by default also the l (lookup) permission on every ACL and can use the fs setacl command to grant other rights as necessary.

  2. (Optional.) Log in as the local superuser root. This is necessary only if you are creating new files or directories in the local file system and want to designate an alternate owner as the object is created. For a discussion of the issues involved, see About Creating Local Disk Directories and Files.

  3. If the bulk input file includes add instructions, verify the location and functionality of the template you are using. For a description of where the uss command interpreter expects to find the template, see Where to Place Template Files. You can always provide an alternate pathname if you wish. Also note which variables appear in the template, to be sure that you provide the corresponding arguments in the add instruction or on the uss bulk command line.

  4. Create a bulk input file that complies with the rules listed in Constructing a Bulk Input File. It is simplest to put the file in the same directory as the template file you are using.

  5. (Optional.) Change to the directory where the bulk input file and template file reside.

       % cd template_directory
    

  6. Issue the uss bulk command to create or delete accounts, or both. Enter the command on a single line; it appears here on multiple lines only for legibility.

    The bulk operation always manipulates user entries in the Authentication Database. The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the ADMIN flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.

       % uss bulk <bulk input file>  \
                  [-template <pathname of template file>]  \
                  -admin <administrator to authenticate>  \
                  [-dryrun] [-overwrite]  \
                  [-pwexpires <password expires in [0..254] days (0 => never)>]  \
                  [-pipe]
       Administrator's (admin_user) password: <admin_password>
    

    where

    b

    Is the shortest acceptable abbreviation of bulk.

    bulk input file

    Specifies the pathname of the bulk input file. Partial pathnames are interpreted relative to the current working directory. For a discussion of the required file format, see Constructing a Bulk Input File.

    -template

    Specifies the pathname of the template file for any uss add commands that appear in the bulk input file. Partial pathnames are interpreted relative to the current working directory. For a discussion of the required file format, see Constructing a uss Template File.

    -admin

    Names an administrative account that has the ADMIN flag on its Authentication Database entry, such as the admin account. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

    -dryrun

    Reports actions that the command interpreter needs to perform to run the command, without actually performing them.

    -overwrite

    Overwrites any directories, files and links that exist in the file system and for which there are also D, E, F, L, or S instructions in the template file named by the -template argument. If this flag is omitted, the command interpreter prompts, once for each add instruction in the bulk input file, for confirmation that it is to overwrite such elements. Do not include this flag if there are no add instructions in the bulk input file.

    -pwexpires

    Sets the number of days after a user's password is changed that it remains valid, for each user named by an add instruction in the bulk input file. Provide an integer from the range 1 through 254 to specify the number of days until expiration, or the value 0 to indicate that the password never expires (the default).

    When the password becomes invalid (expires), the user is unable to authenticate, but has 30 more days in which to issue the kpasswd command to change the password (after that, only an administrator can change it).

    -pipe

    Suppresses the Authentication Server's prompt for the password of the issuer or the user named by the -admin argument (the Authentication Server always separately authenticates the user who is creating or deleting an entry in the Authentication Database). Instead, the command interpreter accepts the password as piped input from another program, enabling you to run the uss bulk command in unattended batch jobs.

  7. If a newly created or deleted user home directory resides in a replicated volume, use the vos release command to release the volume, as described in To replicate a read/write volume (create a read-only volume).

       % vos release <volume name or ID>
    

    Note

    This step can be necessary even if the home directory's parent directory is not itself a mount point for a replicated volume (and is easier to overlook in that case). For example, the ABC Corporation template puts the mount points for user volumes in the /afs/abc.com/usr directory. Because that is a regular directory rather than a mount point, it resides in the root.cell volume mounted at the /afs/abc.com directory. That volume is replicated, so after changing it by creating or deleting a mount point, the administrator must issue the vos release command.

  8. If you are creating accounts, create an entry for the new user in the local password file (/etc/passwd or equivalent) on each AFS client machine that he or she can log into. For suggestions on automating this step, see Creating a Common Source Password File.

    Even if you do not use the automated method, set the user's UNIX UID to match the AFS UID assigned automatically by the Protection Server or assigned with the -uid argument. The new user's AFS UID appears in the trace produced by the uss add output or you can use the pts examine command to display it, as described in To display a Protection Database entry.

  9. If you are deleting accounts, delete the user's entry from the local password file (/etc/passwd or equivalent) of each client machine. If you use the AFS package utility, it is sufficient to remove the entry from the common source version of the file. If you intend to reactivate the user's account in the future, it is simpler to comment out the entry or place an asterisk (*) in the password field.