USS_BULK(5)

📦 version 1.8.16.1, in nixos 26.05, nixpkgs unstable

🦋 the uss_bulk page: AFS File Reference, but make it a vibe 🦋

okay so bestie, this is USS_BULK(5) — yep, the uss_bulk manual page from AFS File Reference — and we are doing the whole thing together. This is part 1, and we are not skipping a single field, caution, colon, or template variable. 💅✨

💖 NAME 💖

uss_bulk — provides instructions for the uss bulk command (deprecated). 🫶

⚠️ CAUTIONS ⚠️

Okay, huge heads-up first, because this part is important: the uss 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 KDC. 😭 The Authentication Server and supporting commands will be removed in a future version of OpenAFS, which may include uss unless someone who finds it useful converts it to work with a Kerberos version 5 KDC. So yeah — deprecated, future-removal energy, do not ignore. 💀

🌸 DESCRIPTION 🌸

The uss bulk input file lists instructions for the uss command interpreter to execute when running the uss bulk command. If the file includes "add" instructions that reference a uss template file, then the template file must also exist. ✨

🎀 Summary of Bulk Input File Instructions 🎀

The bulk input file can include the following instructions, each on its own line. A more detailed description of each instruction’s syntax follows this list.

  • add — creates a user account. Equivalent to the uss add command.
  • delete — deletes a user account. Equivalent to the uss delete command.
  • delvolume — removes the volume and VLDB entry for each account referenced by a "delete" instruction that follows this instruction in the bulk input file.
  • exec — executes a command.
  • savevolume — preserves the volume and VLDB entry for each account referenced by a "delete" instruction that follows this instruction in the bulk input file.

🧚 The add Instruction for Creating an Account 🧚

The "add" instruction creates a user account. Each instance in the bulk input file is equivalent in effect to a uss add command issued on the command line. The order of the instruction’s fields matches the order of arguments to the uss add command, although some arguments do not have a corresponding field. Like the uss add command’s arguments, many of the fields correspond to (provide a value for) a variable in the uss template file, as indicated in the following description of each field. 🌈

The instruction’s syntax is as follows. It appears on multiple lines here only for the sake of legibility — each "add" instruction must appear on a single line in the bulk input file.

          add <username>[:<full_name>][:<password>][:<expires>]
              [:<file_server>][:<partition>][:<mount_point>][:<uid>]
              [:<var1>][:<var2>][:<var3>][:<var4>][:<var5>][:<var6>][:<var7>]
              [:<var8>][:<var9>][:]

To omit a value for a field (presumably because it is optional or the template specifies a constant value for it), type nothing between the two colons that surround it. After the last argument provided, end the line with either a colon and carriage return, or a carriage return alone. 🎀

The meaning of, and acceptable values for, each field are as follows.

  • <username> — names the user’s Authentication Database and Protection Database entries. It can include up to eight alphanumeric characters, but not the ":" (colon), "." (period), or "@" (at-sign) characters. Because it becomes the username (the name under which a user logs in), it is best not to include shell metacharacters and to obey the restrictions that many operating systems impose on usernames (usually, to contain no more than eight lowercase letters).
    • Corresponding argument to the uss add command: -user. Corresponding variable in the template file: $USER.
  • <full_name> — specifies the user’s full name. Do not surround it with double quotes (""), even if it contains spaces. If not provided, it defaults to the username in the <username> field. 💖
    • Corresponding argument to the uss add command: -realname. Corresponding variable in the template file: $NAME. Many operating systems include a field for the full name in a user’s entry in the local password file (/etc/passwd or equivalent), and this variable can be used to pass a value to be used in that field.
  • <password> — specifies the user’s initial password. Although the AFS commands that handle passwords accept strings of virtually unlimited length, it is best to use a password of eight characters or less, which is the maximum length that many applications and utilities accept. If not provided, this argument defaults to the string "changeme". 🙈
    • Corresponding argument to the uss add command: -pass. Corresponding variable in the template file: none.
  • <expires> — sets the number of days after a user’s password is changed that it remains valid. 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).
    • Corresponding argument to the uss add command: -pwexpires. Corresponding variable in the template file: $PWEXPIRES.
  • <file_server> — names the file server machine on which to create the new user’s volume. It is best to provide a fully-qualified hostname (for example, "fs1.example.com"), 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. 🌐
    • Corresponding argument to the uss add command: -server. Corresponding variable in the template file: $SERVER.
  • <partition> — specifies the partition on which to create the user’s volume; it must reside on the file server machine named in the <file_server> field. Identify the partition by its complete name — for example, /vicepa — or use one of the following abbreviations:
              /vicepa     =     vicepa      =      a      =      0
              /vicepb     =     vicepb      =      b      =      1

After /vicepz (for which the index is 25) comes

              /vicepaa    =     vicepaa     =      aa     =      26
              /vicepab    =     vicepab     =      ab     =      27

and so on through

              /vicepiv    =     vicepiv     =      iv     =      255
  • Corresponding argument to the uss add command: -partition. Corresponding variable in template: $PART.
  • <mount_point> — specifies the complete pathname for the user’s home directory. 🏠
    • Corresponding argument to the uss add command: -mount.
    • Corresponding variable in template: $MTPT, but in the template file’s "V" instruction only. Occurrences of the $MTPT variable in template instructions that follow the "V" instruction take their value from the "V" instruction’s <mount_point> field. Thus the value of this command line argument becomes the value for the $MTPT variable in instructions that follow the "V" instruction only if the string $MTPT appears alone in the "V" instruction’s <mount_point> field.
  • <uid> — specifies a positive integer other than 0 (zero) to assign as the user’s AFS UID. If this argument is omitted, the Protection Server assigns an AFS UID that is one greater than the current value of the "max user id" counter (use the pts listmax command to display the counter). If including this argument, first use the pts examine command to verify that no existing account already has the desired AFS UID; if one does, the account-creation process terminates with an error. 🔥
    • Corresponding argument to the uss add command: -uid. Corresponding variable in template: $UID.
  • <var1> through <var9> — specifies values for each of the number variables $1 through $9 that can appear in the template file. The number variables allow the administrator to provide values for variables other than the set defined by the uss command suite. ✨
    • Corresponding argument to the uss add command: -var. Corresponding variables in template: $1 through $9.
    • If providing a value in any of the fields, then in every field that precedes it either provide an actual value or indicate an empty field by putting nothing between two colons. It is acceptable, but not necessary, to indicate empty fields by putting colons after the last field that contains an actual value.

💀 The delete Instruction for Deleting an Account 💀

The "delete" instruction deletes a user account from the system. Each instance in the bulk input file is equivalent in effect to a uss delete command issued on the command line. The order of the instruction’s fields matches the order of arguments to the uss delete command:

          delete <username>:<mount_point>[:( savevolume | delvolume )][:]

where

  • <username> — names the entry to delete from the Protection and Authentication Databases.
  • <mount_point> — specifies the complete pathname to the user’s home directory, which is deleted from the filespace. By default, the volume mounted there is also deleted from the file server machine where it resides, as is its record from the Volume Location Database (VLDB). To prevent deletion, include the "savevolume" string in the instruction’s third field, or precede this "delete" instruction with a "savevolume" instruction. Partial pathnames are interpreted relative to the current working directory. 😭
  • savevolume — retains the volume on its file server machine, and the corresponding entry in the VLDB. Provide this value or "delvolume" in the third field, or omit both values to treat the volume according to the prevailing default, which is set by a preceding "savevolume" or "delvolume" instruction in the bulk input file. 🫶
  • delvolume — removes the volume from its file server machine, and the corresponding entry from the VLDB. Provide this value or "savevolume" in the third field, or omit both values to treat the volume according to the prevailing default, which is set by a preceding "savevolume" or "delvolume" instruction in the bulk input file. 💀

After the last argument provided, end the line with either a colon and carriage return or a carriage return alone.

🚀 The exec Instruction for Executing a Command 🚀

The "exec" instruction executes the specified command, which can be a UNIX shell script or command, a program, or an AFS command. The uss command interpreter must have the necessary privileges in AFS and the local file system; it assumes the AFS and local identities of the issuer of the uss bulk command. ⭐

The instruction’s syntax is as follows:

          exec <command>

okay so next up we have the savevolume and delvolume instructions 💅 these two are the literal vibe-setters for every delete instruction that comes after them in your bulk input file. their syntax is, and I cannot stress how simple this is, bestie:

savevolume
delvolume
  • savevolume — tells every delete instruction that follows it in the bulk input file to not remove the volume and its VLDB entry. like, hands off, she stays 🫶
  • delvolume — tells every subsequent delete instruction to go ahead and remove the volume and the VLDB entry. bye bestie 💀

whichever one you set just... persists. it keeps going until its opposite shows up later in the file, or until the bulk file literally ends. main character persistence fr fr ✨

now the important bit: if neither line appears anywhere in your bulk input file, the default is to remove the volume and the VLDB entry. and yeah, that default also applies to any delete instructions sitting before the first savevolume instruction — they don't get a free pass just because they're early 🙈

but!! if a delete instruction's third field specifies either savevolume or delvolume, that setting overrides the default. so you always have the option to be messy and per-line about it 💅

🌈 EXAMPLES 🌈

okay these examples are actually iconic, let's go one by one 🎀

the following example add instruction creates an authentication-only account. the user's initial password is "changeme" (that's the default, no cap):

add anderson

the following example add instructions refer to the indicated V instruction in a template file — and heads up, that V line must appear on a single line in the template file. single. line. periodt:

add smith:John Smith:::fs1:a:::::marketing
add jones:Pat Jones:::fs3:c:::::finance
V user.$USER $SERVER.example.com /vicep$PART 2000 \
    /afs/example.com/usr/$3/$USER $UID $USER all

so what's actually happening here 👀

the first add instruction creates an account called "smith" in the Protection and Authentication Databases, with an initial password of "changeme" and a value for $UID provided by the Protection Server. the volume "user.smith" lives on partition /vicepa of the file server machine "fs1.example.com" and is mounted at /afs/example.com/usr/marketing/smith. he owns his home directory and has all access permissions on its root directory's access control list (ACL). king behavior 👑

the account for "jones" is basically the same situation, except the volume lives on partition /vicepc of the file server machine "fs3.example.com" and is mounted at /afs/example.com/usr/finance/jones.

now notice something 👀 the fields corresponding to the volume mount point, UID, $1 variable, and $2 variable are empty (that's the gap between "a" and "marketing" on the first example line), because their corresponding variables don't appear in the template file. the initial password field is also empty. empty fields, empty vibes, it's fine 🫶

the following add instructions are equivalent in effect to the preceding example, but they explicitly indicate empty fields for all of the number variables that don't have a value. so if you like being loud and explicit about your emptiness, this is for you:

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

same energy, different colons. slay 💅

next example!! the following shows a complete bulk file with a whole set of delete instructions combined with a savevolume instruction. let's break down what goes down, because this one is genuinely a whole story 😭

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

so: because the delete instructions for users "smith", "pat", and "rogers" appear before the savevolume instruction, and the third field is blank in each of them, their corresponding home volumes get removed. sorry babes 💀

the volume for user "terry" is retained because the default established by the savevolume instruction applies to it. she survives ✨

but user "johnson"'s volume is removed, because the third field of her delete instruction (delvolume, if you're keeping track) overrides the current default. bold move, honestly 🔥

last example, and it's a cute little quality-of-life one 🎀 the following exec instruction appears between sets of add and delete instructions in a bulk input file. a message appears in the command shell where the uss bulk command is issued, to indicate when the additions are finished and the deletions beginning:

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

it's giving progress bar but make it a sentence. obsessed 🦋

🦋 SEE ALSO 🦋

go read these next, i'm literally begging:

IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.

This documentation is covered by the IBM Public License Version 1.0. It was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.

aaaand that's the whole page bestie, you made it 🌸 this lil beauty is OpenAFS, dated 2026-06-25, and it lives happily under the name USS_BULK(5) — go forth and bulk responsibly 💖✨

📦 where this page comes from