mirror of
https://git.openafs.org/openafs.git
synced 2025-01-19 15:30:14 +00:00
9cde8b8854
"Empty" <anchor> entities seem to trigger a bug in fop. These are easily converted to reference on the containing block. Additionally, <indexterm>'s seem to need to be inside a non-structural entity (like a <para>) in order to determine their page number/location correctly. Change-Id: I2ab577f6ba8989685257fb9429e00a71dd51075c Reviewed-on: http://gerrit.openafs.org/4812 Tested-by: BuildBot <buildbot@rampaginggeek.com> Reviewed-by: Jeffrey Altman <jaltman@openafs.org>
4068 lines
217 KiB
XML
4068 lines
217 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter id="HDRWQ449">
|
|
<title>Creating and Deleting User Accounts with the uss Command Suite</title>
|
|
|
|
<para><indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>two methods for creating and deleting</secondary>
|
|
</indexterm></para>
|
|
|
|
<para>The <emphasis role="bold">uss</emphasis> command suite helps you create and delete AFS user accounts quickly and easily. You
|
|
can create a single account with the <emphasis role="bold">uss add</emphasis> command, delete a single account with the <emphasis
|
|
role="bold">uss delete</emphasis> command, or create and delete multiple accounts with the <emphasis role="bold">uss
|
|
bulk</emphasis> command.</para>
|
|
|
|
<para>A single <emphasis role="bold">uss add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command can create a complete
|
|
AFS user account because the <emphasis role="bold">uss</emphasis> command interpreter refers to a template file in which you
|
|
predefine the configuration of many account components. The <emphasis role="bold">uss delete</emphasis> command deletes most of
|
|
the components of a user account, but does not use a template file.</para>
|
|
|
|
<para>The <emphasis role="bold">uss</emphasis> suite also easily incorporates shell scripts or other programs that you write to
|
|
perform parts of account creation and deletion unique to your site. To invoke a script or program automatically as a <emphasis
|
|
role="bold">uss</emphasis> command runs, use the appropriate instructions in the template file or bulk input file. Various
|
|
sections of this chapter discuss possible uses for scripts.</para>
|
|
|
|
<para>Using the <emphasis role="bold">uss</emphasis> commands to create and delete accounts is the recommended method because it
|
|
automates and correctly orders most of the necessary steps. The alternative is to issue a series of separate commands to the
|
|
various AFS servers, which requires more careful record keeping. For instructions, see <link linkend="HDRWQ491">Administering User
|
|
Accounts</link>.</para>
|
|
|
|
<sect1 id="HDRWQ450">
|
|
<title>Summary of Instructions</title>
|
|
|
|
<para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
|
|
|
|
<informaltable frame="none">
|
|
<tgroup cols="2">
|
|
<colspec colwidth="80*" />
|
|
|
|
<colspec colwidth="20*" />
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>Add a single user account</entry>
|
|
|
|
<entry><emphasis role="bold">uss add</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Delete a single user account</entry>
|
|
|
|
<entry><emphasis role="bold">uss delete</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>Add and delete multiple accounts</entry>
|
|
|
|
<entry><emphasis role="bold">uss bulk</emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</informaltable>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ452">
|
|
<title>Overview of the uss Command Suite</title>
|
|
|
|
<para>The commands in the <emphasis role="bold">uss</emphasis> suite help you to automate the creation and deletion of AFS user
|
|
accounts: <itemizedlist>
|
|
<listitem>
|
|
<para>The <emphasis role="bold">uss add</emphasis> command creates all of the components of an account, one account at a
|
|
time. It consults a template file that defines account configuration.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <emphasis role="bold">uss delete</emphasis> command deletes the major components of an account, one account at a
|
|
time. It does not use a template file, so you possibly need to perform additional tasks manually.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <emphasis role="bold">uss bulk</emphasis> command can create and delete multiple accounts. It refers to a bulk
|
|
input file that can contain any number of account-creation and deletion instructions, along with other instructions for
|
|
further automating the process.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>components</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>user</primary>
|
|
|
|
<secondary>account</secondary>
|
|
|
|
<see>user account</see>
|
|
</indexterm>
|
|
|
|
<sect2 id="Header_538">
|
|
<title>The Components of an AFS User Account</title>
|
|
|
|
<para>An AFS user account can have many components. The only two required components are entries in the Protection Database
|
|
and Authentication Database, but the other components add functionality and usability. The following information also appears
|
|
in a corresponding section of <link linkend="HDRWQ491">Administering User Accounts</link>, but is repeated here for your
|
|
convenience. <itemizedlist>
|
|
<listitem>
|
|
<para>A <emphasis>Protection Database entry</emphasis> defines the username (the name provided when authenticating with
|
|
AFS), and maps it to an AFS user ID (AFS UID), a number that the AFS servers use internally when referencing users. The
|
|
Protection Database also tracks the groups to which the user belongs. For details, see <link
|
|
linkend="HDRWQ531">Administering the Protection Database</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>An <emphasis>Authentication Database entry</emphasis> records the user's AFS password in a scrambled form suitable
|
|
for use as an encryption key.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A home <emphasis>volume</emphasis> stores all the files in the user's home directory together on a single
|
|
partition of a file server machine. The volume has an associated quota that limits its size. For a complete discussion
|
|
of volumes, see <link linkend="HDRWQ174">Managing Volumes</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A <emphasis>mount point</emphasis> makes the contents of the user's volume visible and accessible in the AFS
|
|
filespace, and acts as the user's home directory. For more details about mount points, see <link
|
|
linkend="HDRWQ183">About Mounting Volumes</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Full access permissions on the home directory's <emphasis>access control list (ACL)</emphasis> and ownership of
|
|
the directory (as displayed by the UNIX <emphasis role="bold">ls -ld</emphasis> command) enable the user to manage his
|
|
or her files. For details on AFS file protection, see <link linkend="HDRWQ562">Managing Access Control
|
|
Lists</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A <emphasis>local password file entry</emphasis> (in the <emphasis role="bold">/etc/passwd</emphasis> file or
|
|
equivalent) of each AFS client machine enables the user to log in and access AFS files through the Cache Manager. A
|
|
subsequent section in this chapter further discusses local password file entries.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Other optional <emphasis>configuration files</emphasis> make the account more convenient to use. Such files help
|
|
the user log in and log out more easily, receive electronic mail, print, and so on.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>privilege required</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>privilege</primary>
|
|
|
|
<secondary>required for uss commands</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ453">
|
|
<title>Privilege Requirements for the uss Commands</title>
|
|
|
|
<para>To issue <emphasis role="bold">uss</emphasis> commands successfully, you usually need all of the standard AFS
|
|
administrative privileges: membership in the <emphasis role="bold">system:administrators</emphasis> group, inclusion in the
|
|
<emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on every relevant server machine, and the
|
|
<computeroutput>ADMIN</computeroutput> flag on your Authentication Database entry. For details on administrative privilege,
|
|
see <link linkend="HDRWQ581">Managing Administrative Privilege</link>. <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>add</secondary>
|
|
|
|
<tertiary>avoiding interruption</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>delete</secondary>
|
|
|
|
<tertiary>avoiding interruption</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>previewing</primary>
|
|
|
|
<secondary>user account creation/deletion with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>uss commands to create/delete</secondary>
|
|
|
|
<tertiary>previewing</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>creation using uss</secondary>
|
|
|
|
<tertiary>previewing</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>deletion using uss</secondary>
|
|
|
|
<tertiary>previewing</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss</primary>
|
|
|
|
<secondary>previewing effect of command</secondary>
|
|
</indexterm></para>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ454">
|
|
<title>Avoiding and Recovering from Errors and Interrupted Operations</title>
|
|
|
|
<para>As for any complex operation, there are a number of possible reasons that an account-creation or deletion operation can
|
|
halt before it completes. You can easily avoid several of the common reasons by making the following checks before issuing a
|
|
<emphasis role="bold">uss</emphasis> command: <itemizedlist>
|
|
<listitem>
|
|
<para>Verify that you have all of the administrative privileges you need to complete an operation, as described in <link
|
|
linkend="HDRWQ453">Privilege Requirements for the uss Commands</link>. The instructions for using the <emphasis
|
|
role="bold">uss add</emphasis>, <emphasis role="bold">uss delete</emphasis>, and <emphasis role="bold">uss
|
|
bulk</emphasis> commands include this check as a step.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Proofread the template and bulk input files for correct syntax and acceptable values. For discussion, see <link
|
|
linkend="HDRWQ463">Constructing a uss Template File</link> and <link linkend="HDRWQ489">Constructing a Bulk Input
|
|
File</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Do not issue <emphasis role="bold">uss</emphasis> commands when you are aware of network, server machine, or
|
|
server process outages. Because <emphasis role="bold">uss</emphasis> operations affect so many components of AFS, it is
|
|
unlikely that the command can succeed when there are outages.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>Another way to avoid errors that halt an operation is to preview the <emphasis role="bold">uss</emphasis> command by
|
|
combining the <emphasis role="bold">-dryrun</emphasis> flag with the other arguments to be used on the actual command. The
|
|
<emphasis role="bold">uss</emphasis> command interpreter generates a screen trace of the actions to be performed by the actual
|
|
command, without performing them.</para>
|
|
|
|
<para>Using the <emphasis role="bold">-dryrun</emphasis> flag reveals many basic errors that can halt an operation,
|
|
particularly the ones due to incorrect syntax in the command line, template file, or bulk input file. It does not catch all
|
|
possible errors, however, because the command interpreter is not actually attempting to perform the actions it is tracing. For
|
|
example, a Volume Server outage does not necessarily halt the volume creation step when the <emphasis
|
|
role="bold">-dryrun</emphasis> flag is included, because the command interpreter is not actually contacting the server; such
|
|
an outage halts the actual creation operation. <indexterm>
|
|
<primary>failure</primary>
|
|
|
|
<secondary>of uss account creation</secondary>
|
|
|
|
<tertiary>recovering from</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss</primary>
|
|
|
|
<secondary>account</secondary>
|
|
|
|
<tertiary>recovering from account creation failure</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss</primary>
|
|
|
|
<secondary>command</secondary>
|
|
|
|
<tertiary>reissuing, effect of</tertiary>
|
|
</indexterm></para>
|
|
|
|
<para>When the <emphasis role="bold">uss</emphasis> command interpreter encounters error conditions minor enough that they do
|
|
not require halting the operation, it usually generates a message that begins with the string <computeroutput>uss:
|
|
Warning:</computeroutput> and describes the action it is taking to avoid halting. For example, if a user's Protection Database
|
|
entry already exists, the following message appears on the standard output stream:</para>
|
|
|
|
<programlisting>
|
|
uss: Warning: User 'user' already in the protection database
|
|
The uid for user 'user' is AFS UID
|
|
</programlisting>
|
|
|
|
<para>If an error is more serious, the word <computeroutput>Warning</computeroutput> does not appear in the message, which
|
|
instead describes why the command interpreter cannot perform the requested action. Not all of these errors cause the <emphasis
|
|
role="bold">uss</emphasis> operation to halt, but they still require you to take corrective action. For example, attempting to
|
|
create a mount point fails if you lack the necessary permissions on the parent directory's ACL, or if the mount point pathname
|
|
in the <emphasis role="bold">V</emphasis> instruction's mount_point field is malformed. However, this error does not cause the
|
|
creation operation to halt until later instructions in the template attempt to install subdirectories or files under the
|
|
nonexistent mount point.</para>
|
|
|
|
<para>If the command shell prompts returns directly after an error message, then the error generally was serious enough to
|
|
halt the operation. When an error halts account creation or deletion, the best way to recover is to find and fix the cause,
|
|
and then reissue the same <emphasis role="bold">uss</emphasis> command. <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>overwriting existing account components</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>overwriting</primary>
|
|
|
|
<secondary>existing directories/files/links with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>directory</primary>
|
|
|
|
<secondary>overwritten by uss if exists</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>file</primary>
|
|
|
|
<secondary>overwritten by uss if exists</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>hard link</primary>
|
|
|
|
<secondary>overwritten by uss if exists</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>symbolic link</primary>
|
|
|
|
<secondary>overwritten by uss if exists</secondary>
|
|
</indexterm></para>
|
|
|
|
<para>The following list describes what happens when components of a user's account already exist when you reissue an
|
|
account-creation command (the <emphasis role="bold">uss add</emphasis> command, or the <emphasis role="bold">uss
|
|
bulk</emphasis> command when the bulk input file contains <emphasis role="bold">add</emphasis> instructions): <itemizedlist>
|
|
<listitem>
|
|
<para>If the Protection Database entry already exists, a message confirms its existence and specifies the associated AFS
|
|
UID.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the Authentication Database entry already exists, a message confirms its existence.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the volume and associated Volume Location Database (VLDB) entry already exist, a message confirms their
|
|
existence. However, the <emphasis role="bold">uss</emphasis> command interpreter does alter the volume's quota, mount
|
|
point, or ACL if any of the relevant fields in the template <emphasis role="bold">V</emphasis> instruction have changed
|
|
since the command last ran. If the value in the mount_point field has changed, the command interpreter creates the new
|
|
mount point but does not remove any existing mount points.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If any of the fields in the template <emphasis role="bold">A</emphasis> instruction have changed, the <emphasis
|
|
role="bold">uss</emphasis> command interpreter makes the changes without comment.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If a directory, file, or link defined by a template file <emphasis role="bold">D</emphasis>, <emphasis
|
|
role="bold">E</emphasis>, <emphasis role="bold">F</emphasis>, <emphasis role="bold">L</emphasis>, or <emphasis
|
|
role="bold">S</emphasis> instruction already exists, the <emphasis role="bold">uss</emphasis> command interpreter
|
|
replaces the existing element with one that conforms to the template definition. To control whether the <emphasis
|
|
role="bold">uss</emphasis> command interpreter prompts for confirmation that you wish to overwrite a given element, use
|
|
the <emphasis role="bold">-overwrite</emphasis> flag to the <emphasis role="bold">uss add</emphasis> or <emphasis
|
|
role="bold">uss bulk</emphasis> command: <itemizedlist>
|
|
<listitem>
|
|
<para>If you include the <emphasis role="bold">-overwrite</emphasis> flag, the command interpreter automatically
|
|
overwrites all elements without asking for confirmation.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you omit the flag, the command interpreter prompts once for each account to ask if you want to overwrite
|
|
all elements associated with it.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The command interpreter always reexecutes <emphasis role="bold">X</emphasis> instructions in the template file. If
|
|
a command's result already holds, reissuing it has the same effect as reissuing it outside the context of the <emphasis
|
|
role="bold">uss</emphasis> commands.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>The following describes what happens when a <emphasis role="bold">uss delete</emphasis> command references account
|
|
components that have already been deleted. <itemizedlist>
|
|
<listitem>
|
|
<para>If the volume and VLDB entry no longer exist, a message confirms their absence.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the Authentication Database entry no longer exists, a message confirms its absence.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<indexterm>
|
|
<primary>local password file</primary>
|
|
|
|
<secondary>creating entry for AFS user</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ455">
|
|
<title>Creating Local Password File Entries with uss</title>
|
|
|
|
<para>To obtain authenticated access to a cell's AFS filespace, a user must not only have a valid AFS token, but also an entry
|
|
in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of the AFS client machine. This section
|
|
discusses why it is important for the user's AFS UID to match to the UNIX UID listed in the local password file, the appropriate
|
|
value to put in the file's password field, and outlines a method for creating a single source password file.</para>
|
|
|
|
<para>For instructions on using the template file's <emphasis role="bold">E</emphasis> instruction to generate local password
|
|
file entries automatically as part of account creation, see <link linkend="HDRWQ458">Creating a Common Source Password
|
|
File</link>.</para>
|
|
|
|
<para>The following information also appears in a corresponding section of <link linkend="HDRWQ491">Administering User
|
|
Accounts</link>, but is repeated here for your convenience. <indexterm>
|
|
<primary>AFS UID</primary>
|
|
|
|
<secondary>matching with UNIX UID</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>matching AFS and UNIX UIDs</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss</primary>
|
|
|
|
<secondary>AFS UID, assigning</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>assigning</primary>
|
|
|
|
<secondary>AFS UID with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>UNIX UID</primary>
|
|
|
|
<secondary>matching with AFS UID</secondary>
|
|
</indexterm></para>
|
|
|
|
<sect2 id="HDRWQ456">
|
|
<title>Assigning AFS and UNIX UIDs that Match</title>
|
|
|
|
<para>A user account is easiest to administer and use if the AFS user ID number (AFS UID) and UNIX UID match. All instructions
|
|
in the AFS documentation assume that they do.</para>
|
|
|
|
<para>The most basic reason to make AFS and UNIX UIDs the same is so that the owner name reported by the UNIX <emphasis
|
|
role="bold">ls -l</emphasis> and <emphasis role="bold">ls -ld</emphasis> commands makes sense for AFS files and directories.
|
|
Following standard UNIX practice, the File Server records a number rather than a username in an AFS file or directory's owner
|
|
field: the owner's AFS UID. When you issue the <emphasis role="bold">ls -l</emphasis> command, it translates the UID to a
|
|
username according to the mapping in the local password file, not the AFS Protection Database. If the AFS and UNIX UIDs do not
|
|
match, the <emphasis role="bold">ls -l</emphasis> command reports an unexpected (and incorrect) owner. The output can even
|
|
vary on different client machines if their local password files map the same UNIX UID to different names.</para>
|
|
|
|
<para>Follow the recommendations in the indicated sections to make AFS and UNIX UIDs match when you are creating accounts for
|
|
various types of users: <itemizedlist>
|
|
<listitem>
|
|
<para>If creating an AFS account for a user who already has a UNIX UID, see <link linkend="HDRWQ459">Converting Existing
|
|
UNIX Accounts with uss</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If some users in your cell have existing UNIX accounts but the user for whom you are creating an AFS account does
|
|
not, then it is best to allow the Protection Server to allocate an AFS UID automatically. To avoid overlap of AFS UIDs
|
|
with existing UNIX UIDs, set the Protection Database's <computeroutput>max user id</computeroutput> counter higher than
|
|
the largest UNIX UID, using the instructions in <link linkend="HDRWQ560">Displaying and Setting the AFS UID and GID
|
|
Counters</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If none of your users have existing UNIX accounts, allow the Protection Server to allocate AFS UIDs automatically,
|
|
starting either at its default or at the value you have set for the <computeroutput>max user id</computeroutput>
|
|
counter.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<indexterm>
|
|
<primary>password</primary>
|
|
|
|
<secondary>setting in local password file</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>local password file</primary>
|
|
|
|
<secondary>setting password in</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ457">
|
|
<title>Specifying Passwords in the Local Password File</title>
|
|
|
|
<para>Authenticating with AFS is easiest for your users if you install and configure an AFS-modified login utility, which logs
|
|
a user into the local file system and obtains an AFS token in one step. In this case, the local password file no longer
|
|
controls a user's ability to login in most circumstances, because the AFS-modified login utility does not consult the local
|
|
password file if the user provides the correct AFS password. You can nonetheless use a password file entry's password field
|
|
(usually, the second field) in the following ways to control login and authentication: <itemizedlist>
|
|
<listitem>
|
|
<para>To prevent both local login and AFS authentication, place an asterisk ( * ) in the field. This is useful mainly in
|
|
emergencies, when you want to prevent a certain user from logging into the machine.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>To prevent login to the local file system if the user does not provide the correct AFS password, place a character
|
|
string of any length other than the standard thirteen characters in the field. This is appropriate if you want to allow
|
|
only people with local AFS accounts to log into to your machines. A single <emphasis role="bold">X</emphasis> or other
|
|
character is the most easily recognizable way to do this.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>To enable a user to log into the local file system even after providing an incorrect AFS password, record a
|
|
standard UNIX encrypted password in the field by issuing the standard UNIX password-setting command (<emphasis
|
|
role="bold">passwd</emphasis> or equivalent).</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>If you do not use an AFS-modified login utility, you must place a standard UNIX password in the local password file of
|
|
every client machine the user will use. The user logs into the local file system only, and then must issue the <emphasis
|
|
role="bold">klog</emphasis> command to authenticate with AFS. It is simplest if the passwords in the local password file and
|
|
the Authentication Database are the same, but this is not required. <indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>common local password file with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>local password file</primary>
|
|
|
|
<secondary>creating common source version with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>local password file</secondary>
|
|
|
|
<tertiary>creating common source version</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>passwd file</primary>
|
|
|
|
<secondary></secondary>
|
|
|
|
<see>local password file</see>
|
|
</indexterm></para>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ458">
|
|
<title>Creating a Common Source Password File</title>
|
|
|
|
<para>This section explains how to create a common source version of the local password file when using <emphasis
|
|
role="bold">uss</emphasis> commands to create user accounts. The sequence of steps is as follows: <orderedlist>
|
|
<listitem>
|
|
<para>Include an <emphasis role="bold">E</emphasis> instruction in the template file to create a one-line file that has
|
|
the format of a local password file entry.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Incorporate the one-line file into the common source version of the local password file. It makes sense to store
|
|
this file in AFS. See the following two example scripts for automating this step.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Distribute the common password file to each client machine, perhaps by using the AFS <emphasis
|
|
role="bold">package</emphasis> utility as described in <link linkend="HDRWQ419">Configuring Client Machines with the
|
|
package Program</link>.</para>
|
|
</listitem>
|
|
</orderedlist></para>
|
|
|
|
<para>As an example, the template file used by the ABC Corporation includes the following <emphasis role="bold">E</emphasis>
|
|
instruction to create a file called <emphasis role="bold">passwd_</emphasis>username in the directory <emphasis
|
|
role="bold">/afs/.abc.com/common/etc/newaccts</emphasis> (the entire contents of the template file appear in <link
|
|
linkend="HDRWQ471">Example uss Templates</link> and a full description of the <emphasis role="bold">E</emphasis> instruction
|
|
appears in <link linkend="HDRWQ476">Creating One-Line Files with the E Instruction</link>):</para>
|
|
|
|
<programlisting>
|
|
E /afs/.abc.com/common/etc/newaccts/passwd_$USER 0644 root \
|
|
"$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
|
|
</programlisting>
|
|
|
|
<para>For the user Joe L. Smith with username <emphasis role="bold">smith</emphasis>, this instruction creates a file called
|
|
<emphasis role="bold">passwd_smith</emphasis> which contains the following line:</para>
|
|
|
|
<programlisting>
|
|
smith:X:1205:11:Joe L. Smith:/afs/abc.com/usr/usr1/smith:/bin/csh
|
|
</programlisting>
|
|
|
|
<para>A shell script is probably the easiest way to incorporate a set of files created in this manner into a common source
|
|
password file, and two sample shell scripts appear here. To automate the process even further, you can create a <emphasis
|
|
role="bold">cron</emphasis> process in a file server machine's <emphasis role="bold">/usr/afs/local/BosConfig</emphasis>
|
|
directory to execute the shell script, perhaps each day at a given time; for details, see <link linkend="HDRWQ162">To create
|
|
and start a new process</link>.</para>
|
|
|
|
<note>
|
|
<para>The following example scripts are suggestions only. If you choose to use them, or to model similar scripts on them,
|
|
you must test that your script has the desired result, preferably in a test environment.</para>
|
|
</note>
|
|
|
|
<para><emphasis role="bold">Example C Shell Script</emphasis></para>
|
|
|
|
<para>The first example is a simple C shell script suitable for the ABC Corporation cell. It incorporates the individual files
|
|
found in the <emphasis role="bold">/afs/.abc.com/common/uss/newaccts</emphasis> directory into a new version of the global
|
|
password file found in the <emphasis role="bold">/afs/.abc.com/common/etc</emphasis> directory, sorting the files into
|
|
alphabetical order. It takes care to save the current version with a <emphasis role="bold">.old</emphasis> extension, then
|
|
removes the individual files when done.</para>
|
|
|
|
<programlisting>
|
|
set dir = /afs/.abc.com/common
|
|
cat $dir/uss/newaccts/passwd_* $dir/etc/passwd >! $dir/etc/passwd.new
|
|
mv $dir/etc/passwd $dir/etc/passwd.old
|
|
sort $dir/etc/passwd.new > $dir/etc/passwd
|
|
rm $dir/etc/passwd.new $dir/uss/newaccts/passwd_*
|
|
</programlisting>
|
|
|
|
<para><emphasis role="bold">Example Bourne Shell Script</emphasis></para>
|
|
|
|
<para>The second, more elaborate, example is a Bourne shell script that first verifies that there are new <emphasis
|
|
role="bold">passwd_</emphasis>username files to be incorporated into the global password file. While running, it checks that
|
|
each new entry does not already exist. Like the shorter C shell example, it incorporates the individual files found in the
|
|
<emphasis role="bold">/afs/.abc.com/common/uss/newaccts</emphasis> directory into a new version of the global <emphasis
|
|
role="bold">passwd</emphasis> file found in the <emphasis role="bold">/afs/.abc.com/common/etc</emphasis> directory.</para>
|
|
|
|
<programlisting>
|
|
#!/bin/sh
|
|
DESTDIR=/afs/.abc.com/common/uss/newaccts
|
|
cd $DESTDIR
|
|
DEST=/afs/.abc.com/common/etc
|
|
cp /afs/.abc.com/common/etc/passwd /afs/.abc.com/common/uss/newaccts/passwd
|
|
echo "copied in passwd file."
|
|
PASSWD=/afs/.abc.com/common/uss/newaccts/passwd
|
|
ENTRIES=`ls passwd_*`
|
|
case $ENTRIES in
|
|
"")
|
|
echo No new entry found to be added to passwd file
|
|
;;
|
|
*)
|
|
echo "Adding new users to passwd file."
|
|
for i in $ENTRIES
|
|
do
|
|
cat $i | awk -F: '{print $1 > "foo"}'
|
|
USER=`cat foo`
|
|
case `egrep -e \^$USER\: $PASSWD` in
|
|
"")
|
|
echo adding $USER
|
|
cat $i >> $PASSWD
|
|
;;
|
|
*)
|
|
echo $USER already in passwd file
|
|
;;
|
|
esac
|
|
mv $i ../old.passdir/done_${i}
|
|
done
|
|
cd /afs/.abc.com/common/uss/newaccts
|
|
echo "sorting password file"
|
|
sort ${PASSWD} > ${PASSWD}.sorted
|
|
echo "installing files"
|
|
install ${PASSWD}.sorted ${DEST}/passwd
|
|
echo "Password file is built, sorted and installed."
|
|
;;
|
|
esac
|
|
</programlisting>
|
|
|
|
<indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>converting existing UNIX accounts</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>converting</primary>
|
|
|
|
<secondary>existing UNIX accounts to AFS accounts</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>converting existing UNIX to AFS</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ459">
|
|
<title>Converting Existing UNIX Accounts with uss</title>
|
|
|
|
<para>This section discusses the three main issues you need to consider if there are existing UNIX accounts to be converted to
|
|
AFS accounts.</para>
|
|
|
|
<sect2 id="HDRWQ460">
|
|
<title>Making UNIX and AFS UIDs Match</title>
|
|
|
|
<para>As previously mentioned, AFS users must have an entry in the local password file on every client machine from which they
|
|
access the AFS filespace as an authenticated user. Both administration and use are much simpler if the UNIX UID and AFS UID
|
|
match. When converting existing UNIX accounts, you have two alternatives: <itemizedlist>
|
|
<listitem>
|
|
<para>Make the AFS UIDs match the existing UNIX UIDs. In this case, you need to assign the AFS UID yourself as you
|
|
create an AFS account: <itemizedlist>
|
|
<listitem>
|
|
<para>If using the <emphasis role="bold">uss add</emphasis> command, include the <emphasis
|
|
role="bold">-uid</emphasis> argument.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If using the <emphasis role="bold">uss bulk</emphasis> command, specify the desired UID in the uid field of
|
|
the <emphasis role="bold">add</emphasis> instruction in the bulk input file.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>Because you are retaining the user's UNIX UID, you do not need to alter the UID in the local password file entry.
|
|
However, if you are using an AFS-modified login utility, you possibly need to change the password field in the entry.
|
|
For a discussion of how the value in the password field affects login with an AFS-modified login utility, see <link
|
|
linkend="HDRWQ455">Creating Local Password File Entries with uss</link>.</para>
|
|
|
|
<para>If now or in the future you need to create AFS accounts for users who do not have an existing UNIX UID, then you
|
|
must guarantee that new AFS UIDs do not conflict with any existing UNIX UIDs. The simplest way is to set the
|
|
<computeroutput>max user id</computeroutput> counter in the Protection Database to a value higher than the largest
|
|
existing UNIX UID. See <link linkend="HDRWQ560">Displaying and Setting the AFS UID and GID Counters</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Change the existing UNIX UIDs to match the new AFS UIDs that the Protection Server assigns automatically.</para>
|
|
|
|
<para>Allow the Protection Server to allocate the AFS UIDs automatically as you create AFS accounts. For instructions on
|
|
creating a new entry for the local password file during account creation, see <link linkend="HDRWQ455">Creating Local
|
|
Password File Entries with uss</link>.</para>
|
|
|
|
<para>There is one drawback to changing the UNIX UID: any files and directories that the user owned in the local file
|
|
system before becoming an AFS user still have the former UID in their owner field. If you want the <emphasis
|
|
role="bold">ls -l</emphasis> and <emphasis role="bold">ls -ld</emphasis> commands to display the correct owner, you must
|
|
use the <emphasis role="bold">chown</emphasis> command to change the value to the user's new UID, whether you are
|
|
leaving the file in the local file system or moving it to AFS. See <link linkend="HDRWQ462">Moving Local Files into
|
|
AFS</link>.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ461">
|
|
<title>Setting the Password Field Appropriately</title>
|
|
|
|
<para>Existing UNIX accounts already have an entry in the local password file, probably with a (scrambled) password in the
|
|
password field. You possibly need to change the value in the field, depending on the type of login utility you use:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If the login utility is not modified for use with AFS, the actual password must appear (in scrambled form) in the
|
|
password field of the local password file entry.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the login utility is modified for use with AFS, choose one of the acceptable values, each of which affects the
|
|
login utility's behavior differently. See <link linkend="HDRWQ455">Creating Local Password File Entries with
|
|
uss</link>.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>If you choose to place an actual password in a local password file entry, then you can define a dummy password when you
|
|
use a template file <emphasis role="bold">E</emphasis> instruction to create the entry, as described in <link
|
|
linkend="HDRWQ476">Creating One-Line Files with the E Instruction</link>. Have the user issue the UNIX password-setting
|
|
command (<emphasis role="bold">passwd</emphasis> or equivalent) to replace the dummy with an actual secret password.</para>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ462">
|
|
<title>Moving Local Files into AFS</title>
|
|
|
|
<para>New AFS users with existing UNIX accounts probably already own files and directories stored in a machine's local file
|
|
system, and it usually makes sense to transfer them into the new home volume. The easiest method is to move them onto the
|
|
local disk of an AFS client machine, and then use the UNIX <emphasis role="bold">mv</emphasis> command to transfer them into
|
|
the user's new AFS home directory.</para>
|
|
|
|
<para>As you move files and directories into AFS, keep in mind that the meaning of their mode bits changes. AFS ignores the
|
|
second and third sets of mode bits (group and other), and does not use the first set (the owner bits) directly, but only in
|
|
conjunction with entries on the ACL (for details, see <link linkend="HDRWQ580">How AFS Interprets the UNIX Mode Bits</link>).
|
|
Be sure that the ACL protects the file or directory at least as securely as the mode bits.</para>
|
|
|
|
<para>If you have chosen to change a user's UNIX UID to match a new AFS UID, you must change the ownership of UNIX files and
|
|
directories as well. Only members of the <emphasis role="bold">system:administrators</emphasis> group can issue the <emphasis
|
|
role="bold">chown</emphasis> command on files and directories once they reside in AFS. <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>advantages over individual account-creation commands</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>advantages</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>instructions summarized</secondary>
|
|
</indexterm></para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ463">
|
|
<title>Constructing a uss Template File</title>
|
|
|
|
<para>Creating user accounts with <emphasis role="bold">uss</emphasis> commands is generally more convenient than using
|
|
individual commands. You control the account creation process just as closely, but the <emphasis role="bold">uss</emphasis>
|
|
template file enables you to predefine many aspects of account configuration. Because you construct the template before issuing
|
|
<emphasis role="bold">uss</emphasis> commands, you have time to consider configuration details carefully and correct syntax
|
|
errors. The following list summarizes some further advantages of using a template: <itemizedlist>
|
|
<listitem>
|
|
<para>You do not have to remember the correct order in which to create or delete account components, or the order of each
|
|
command's arguments, which reduces the likelihood of errors.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You do not have to type the same information multiple times. Instead, you can place constants and variables in the
|
|
template file that enable you to type as little on the command line as possible. See <link linkend="HDRWQ465">Using
|
|
Constants and Variables in the Template File</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You can create different templates for different types of users. Instead of having to remember which components
|
|
differ for a given user, specify the appropriate template when issuing the <emphasis role="bold">uss add</emphasis> or
|
|
<emphasis role="bold">uss bulk</emphasis> command.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You can create any of the three types of AFS account (authentication-only, basic, or full) by including or omitting
|
|
certain information in the template, as described in <link linkend="HDRWQ464">Creating the Three Types of User
|
|
Accounts</link>.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>The following list briefly describes the instructions that can appear in a template file and points you to a later section
|
|
for more details. It lists them in the order that is usually optimal for correct handling of dependencies between the different
|
|
types of instruction. <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">G</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Defines a directory that is one of a set of parent directories into which the <emphasis role="bold">uss</emphasis>
|
|
command interpreter evenly distributes newly created home directories. Place the corresponding template file variable,
|
|
$AUTO, in the mount_point field of the <emphasis role="bold">V</emphasis> instruction. See <link
|
|
linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link> and <link
|
|
linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">V</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Creates a volume, mounts it as the user's home directory at a specified location in the AFS filespace, sets the
|
|
volume's quota, and defines the owner and ACL for the directory. This instruction must appear in any template that is
|
|
not empty (zero-length). See <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">D</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Creates a directory, generally a subdirectory of the new home directory, and sets its mode bits, owner, and ACL.
|
|
See <link linkend="HDRWQ474">Creating a Directory with the D Instruction</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">F</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Creates a file by copying a prototype and sets its mode bits and owner. See <link linkend="HDRWQ475">Creating a
|
|
File from a Prototype with the F Instruction</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">E</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Creates a single-line file by copying in the contents of the instruction itself, then sets the file's mode bits
|
|
and owner. See <link linkend="HDRWQ476">Creating One-Line Files with the E Instruction</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">L</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Creates a hard link. See <link linkend="HDRWQ477">Creating Links with the L and S Instructions</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">S</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Creates a symbolic link. See <link linkend="HDRWQ477">Creating Links with the L and S Instructions</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">A</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Improves account security by imposing restrictions on passwords and authentication attempts. See <link
|
|
linkend="HDRWQ478">Increasing Account Security with the A Instruction</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">X</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Executes a command. See <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>instructions for different account types</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>creating different types with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>user account types with uss</secondary>
|
|
</indexterm>
|
|
|
|
<sect2 id="HDRWQ464">
|
|
<title>Creating the Three Types of User Accounts</title>
|
|
|
|
<para>Using the <emphasis role="bold">uss add</emphasis> and <emphasis role="bold">uss bulk</emphasis> commands, you can
|
|
create three types of accounts that differ in their levels of functionality. For a description of the types, see <link
|
|
linkend="HDRWQ57">Configuring AFS User Accounts</link>. The following list explains how to construct a template for each type:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>To create an authentication-only account, create an empty (zero-length) template file. Such an account has only
|
|
two components: entries in the Authentication Database and Protection Database.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>To create a basic account, include a <emphasis role="bold">V</emphasis> instruction, and <emphasis
|
|
role="bold">G</emphasis> instructions if you want to distribute home directories evenly as described in <link
|
|
linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link>. In addition to
|
|
Authentication Database and Protection Database entries, this type of account includes a volume mounted at the home
|
|
directory with owner and ACL set appropriately.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>To create a full account, include <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>,
|
|
<emphasis role="bold">F</emphasis>, <emphasis role="bold">L</emphasis>, and <emphasis role="bold">S</emphasis>
|
|
instructions as appropriate, in addition to the <emphasis role="bold">V</emphasis> and <emphasis
|
|
role="bold">G</emphasis> instructions. This type of account includes configuration files for basic functions such as
|
|
logging in, printing, and mail delivery. For a discussion of some useful types of configuration files, see <link
|
|
linkend="HDRWQ60">Creating Standard Files in New AFS Accounts</link>.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<indexterm>
|
|
<primary>constants</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>constants</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>variables</primary>
|
|
|
|
<secondary>in uss template file</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>variables</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ465">
|
|
<title>Using Constants and Variables in the Template File</title>
|
|
|
|
<para>Each instruction in the <emphasis role="bold">uss</emphasis> template file has several fields that define the
|
|
characteristics of the element that it creates. The <emphasis role="bold">D</emphasis> instruction's fields, for instance,
|
|
define a directory's pathname, owner, mode bits, and ACL.</para>
|
|
|
|
<para>You can place three types of values in a field: a variable, a constant, or a combination of the two. The appropriate
|
|
value depends on the desired configuration, and determines which arguments you provide to the <emphasis role="bold">uss
|
|
add</emphasis> command or which fields you include in a bulk input file <emphasis role="bold">add</emphasis>
|
|
instruction.</para>
|
|
|
|
<para>If an aspect of account configuration is the same for every user, define a constant value in the appropriate field by
|
|
inserting a character string. For example, to assign a space quota of 10,000 KB to every user volume, place the string
|
|
<emphasis role="bold">10000</emphasis> in the <emphasis role="bold">V</emphasis> instruction's quota field.</para>
|
|
|
|
<para>If, on the other hand, an aspect of account configuration varies for each user, put a variable in the appropriate field.
|
|
When creating each account, provide a value for the variable by providing either the corresponding argument to the <emphasis
|
|
role="bold">uss add</emphasis> command or a value in the corresponding field of the <emphasis role="bold">add</emphasis>
|
|
instruction in the bulk input file.</para>
|
|
|
|
<para>The <emphasis role="bold">uss</emphasis> command suite defines a set of template variables, each of which has a
|
|
corresponding source for its value, as summarized in <link linkend="TBLWQ466">Table 3</link>. For a discussion of their
|
|
intended uses, see the following sections about each template instruction (<link linkend="HDRWQ473">Creating a Volume with the
|
|
V Instruction</link> through <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>).</para>
|
|
|
|
<table id="TBLWQ466" label="3">
|
|
<title>Source for values of uss template variables</title>
|
|
|
|
<tgroup cols="2">
|
|
<colspec colwidth="20*" />
|
|
|
|
<colspec colwidth="80*" />
|
|
|
|
<thead>
|
|
<row>
|
|
<entry><emphasis role="bold">Variable</emphasis></entry>
|
|
|
|
<entry><emphasis role="bold">Source for value</emphasis></entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>$AUTO</entry>
|
|
|
|
<entry>Previous <emphasis role="bold">G</emphasis> instructions in template</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$MTPT</entry>
|
|
|
|
<entry><emphasis role="bold">-mount</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
|
|
mount_point field of bulk input file <emphasis role="bold">add</emphasis> instruction, when in <emphasis
|
|
role="bold">V</emphasis> instruction; <emphasis role="bold">V</emphasis> instruction's mount_point field when in
|
|
subsequent instructions</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$NAME</entry>
|
|
|
|
<entry><emphasis role="bold">-realname</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
|
|
mount_point field of bulk input file <emphasis role="bold">add</emphasis> instruction, if provided; otherwise,
|
|
<emphasis role="bold">-user</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or username field
|
|
of in bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$PART</entry>
|
|
|
|
<entry><emphasis role="bold">-partition</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
|
|
partition field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$PWEXPIRES</entry>
|
|
|
|
<entry><emphasis role="bold">-pwexpires</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
|
|
password_expires field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$SERVER</entry>
|
|
|
|
<entry><emphasis role="bold">-server</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or
|
|
file_server field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$UID</entry>
|
|
|
|
<entry><emphasis role="bold">-uid</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or uid field
|
|
of bulk input file <emphasis role="bold">add</emphasis> instruction, if provided; otherwise, allocated automatically
|
|
by Protection Server</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$USER</entry>
|
|
|
|
<entry><emphasis role="bold">-user</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or username
|
|
field of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$1 through $9</entry>
|
|
|
|
<entry><emphasis role="bold">-var</emphasis> argument to <emphasis role="bold">uss add</emphasis> command or var1
|
|
through var9 fields of bulk input file <emphasis role="bold">add</emphasis> instruction</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<para>A common use of variables is to define the file server machine and partition that house the user's volume, which often
|
|
vary from user to user. Place the $SERVER variable in the <emphasis role="bold">V</emphasis> instruction's server field, and
|
|
the $PART variable in its partition field. If using the <emphasis role="bold">uss add</emphasis> command, provide the desired
|
|
value with the <emphasis role="bold">-server</emphasis> and <emphasis role="bold">-partition</emphasis> arguments. If using
|
|
the <emphasis role="bold">uss bulk</emphasis> command, provide the desired values in the file_server and partition fields of
|
|
each user's <emphasis role="bold">add</emphasis> instruction in the bulk input file. <indexterm>
|
|
<primary>number variables</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>number variables</secondary>
|
|
</indexterm></para>
|
|
|
|
<para>The variables $1 through $9 can be used to customize other aspects of the account. Provide a value for these variables
|
|
with the <emphasis role="bold">-var</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or in the
|
|
appropriate field of the bulk input file <emphasis role="bold">add</emphasis> instruction. The <emphasis
|
|
role="bold">-var</emphasis> argument is unusual in that each instance for it has two parts: the number index and the value,
|
|
separated by a space. For examples of the use of a number variable, see the discussions of the mount_point and quota fields in
|
|
<link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
|
|
|
|
<para>If some aspect of account configuration is partly constant and partly variable, you can combine variables and constants
|
|
in an instruction field. For example, suppose that the ABC Corporation mounts user volumes in the <emphasis
|
|
role="bold">/afs/abc.com/usr</emphasis> directory. That part of the pathname is constant, but the name of the mount point and
|
|
home directory is the user's username, which corresponds to the $USER variable. To configure accounts in this way, combine a
|
|
constant string and a variable in the <emphasis role="bold">V</emphasis> instruction's mount_point field as follows:</para>
|
|
|
|
<programlisting>
|
|
/afs/abc.com/usr/$USER
|
|
</programlisting>
|
|
|
|
<para>Then provide the value for the $USER variable with the <emphasis role="bold">-user</emphasis> argument to the <emphasis
|
|
role="bold">uss add</emphasis> command, or in the username field of each user's <emphasis role="bold">add</emphasis>
|
|
instruction in the bulk input file. <indexterm>
|
|
<primary>location</primary>
|
|
|
|
<secondary>standard for uss template file</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>standard locations</secondary>
|
|
</indexterm></para>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ468">
|
|
<title>Where to Place Template Files</title>
|
|
|
|
<para>A template must be available to the <emphasis role="bold">uss</emphasis> command interpreter as it executes a <emphasis
|
|
role="bold">uss add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command, even if it is the zero-length file
|
|
appropriate for creating an authentication-only account.</para>
|
|
|
|
<para>If you do not provide the <emphasis role="bold">-template</emphasis> argument to the <emphasis role="bold">uss
|
|
add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command, then the command interpreter searches for a template file
|
|
called <emphasis role="bold">uss.template</emphasis> in each of the following directories in turn: <orderedlist>
|
|
<listitem>
|
|
<para>The current working directory</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">/afs/cellname/common/uss</emphasis>, where cellname is the local cell</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">/etc</emphasis></para>
|
|
</listitem>
|
|
</orderedlist></para>
|
|
|
|
<para>To use a template file with a different name or stored in a different directory, include the <emphasis
|
|
role="bold">-template</emphasis> argument to the <emphasis role="bold">uss add</emphasis> or <emphasis role="bold">uss
|
|
bulk</emphasis> command. If you provide a filename only, the command interpreter looks for it in the directories listed just
|
|
previously. If you provide a pathname and filename, it looks only in the specified directory, interpreting a partial pathname
|
|
relative to the current working directory. <indexterm>
|
|
<primary>rules</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>rules for constructing</secondary>
|
|
</indexterm></para>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ469">
|
|
<title>Some General Rules for Constructing a Template</title>
|
|
|
|
<para>This section summarizes some general rules to follow when constructing a template file. For each instruction's syntax
|
|
definition, see the following sections (<link linkend="HDRWQ472">Evenly Distributing User Home Directories with the G
|
|
Instruction</link> through <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>). <itemizedlist>
|
|
<listitem>
|
|
<para>If a variable takes its value from an element elsewhere within the template, the definition must precede the
|
|
reference. Putting the instruction lines in the following order usually results in correct resolution of
|
|
variables:</para>
|
|
|
|
<para><emphasis role="bold">G V D F E L S A X</emphasis></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The fields in each instruction must appear in the order specified by the instruction's syntax definition, which
|
|
appear in the following sections about each instruction. You cannot omit a field. Separate each field from its neighbors
|
|
with one or more spaces.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When specifying a pathname, provide a full one. Partial pathnames are interpreted relative to the current working
|
|
directory (the one in which the <emphasis role="bold">uss</emphasis> command is issued), with possibly unintended
|
|
results.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Each instruction must appear on a single line in the template file, with a newline character (<emphasis
|
|
role="bold"><Return></emphasis>) only at the end of the instruction. Some example instructions appear in this
|
|
document on more than one line, but that is only for legibility.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Provide a value for every variable that appears in the template by including the corresponding argument to the
|
|
<emphasis role="bold">uss add</emphasis> command or placing a value in the corresponding field of the bulk input file
|
|
<emphasis role="bold">add</emphasis> instruction. A missing value halts the entire creation operation. If a variable
|
|
does not appear in the template file, the command interpreter ignores the corresponding command-line argument or field
|
|
in the bulk input file, even if you provide it.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>You can use blank lines in the template file to increase its legibility. If you place comments in the file, begin
|
|
each comment line with the number sign (<emphasis role="bold">#</emphasis>).</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ470">
|
|
<title>About Creating Local Disk Directories and Files</title>
|
|
|
|
<para>It is possible to use the <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, and <emphasis
|
|
role="bold">F</emphasis> instructions to create directories or files in the local file system of the machine on which you are
|
|
issuing the <emphasis role="bold">uss</emphasis> command, but that usage is not recommended. It introduces two potential
|
|
complications: <itemizedlist>
|
|
<listitem>
|
|
<para>The local file system automatically assigns ownership of a new local disk directory or file to its creator.
|
|
Because you are the issuer of the <emphasis role="bold">uss</emphasis> command that is creating the object, it records
|
|
your current UNIX UID. If that is not appropriate and you want to designate another owner as the object is created, then
|
|
you must be logged in as the local superuser <emphasis role="bold">root</emphasis> (the local file system allows only
|
|
the <emphasis role="bold">root</emphasis> user to issue the UNIX <emphasis role="bold">chown</emphasis> command, which
|
|
the <emphasis role="bold">uss</emphasis> command interpreter invokes to change the owner from the default value). You
|
|
must also use the <emphasis role="bold">-admin</emphasis> argument to the <emphasis role="bold">uss add</emphasis> or
|
|
<emphasis role="bold">uss bulk</emphasis> command to authenticate as a privileged AFS administrator. Only an
|
|
administrator can create Authentication Database and Protection Database entries, which the <emphasis
|
|
role="bold">uss</emphasis> command interpreter always creates as part of a new account.</para>
|
|
|
|
<para>The alternative is to become the local superuser <emphasis role="bold">root</emphasis> after the <emphasis
|
|
role="bold">uss</emphasis> operation completes, and issue the necessary <emphasis role="bold">chown</emphasis> command
|
|
then. However, that makes the account creation process that much less automated.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Creating a local disk directory always generates an error message because the <emphasis role="bold">uss</emphasis>
|
|
command interpreter cannot successfully set a local directory's ACL. The directory is created nevertheless, and a value
|
|
still must appear in the <emphasis role="bold">D</emphasis> instruction's ACL field.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>The recommended method for configuring a machine's local disk is to use the AFS <emphasis role="bold">package</emphasis>
|
|
utility instead; see <link linkend="HDRWQ419">Configuring Client Machines with the package Program</link>. <indexterm>
|
|
<primary>examples</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>examples</secondary>
|
|
</indexterm></para>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ471">
|
|
<title>Example uss Templates</title>
|
|
|
|
<para>This section describes example templates for the basic and full account types (the template for an authentication-only
|
|
account is empty).</para>
|
|
|
|
<para>The first example creates a basic account. It contains two <emphasis role="bold">G</emphasis> instructions and a
|
|
<emphasis role="bold">V</emphasis> instruction that defines the volume name, file server machine, partition, quota in
|
|
kilobytes, mount point, home directory owner, and home directory access control list. In the ABC Corporation cell, a suitable
|
|
template is:</para>
|
|
|
|
<programlisting>
|
|
G /afs/.abc.com/usr1
|
|
G /afs/.abc.com/usr2
|
|
V user.$USER $SERVER.abc.com /vicep$PART 5000 $AUTO/$USER $UID \
|
|
$USER all staff rl
|
|
</programlisting>
|
|
|
|
<para>When issuing the <emphasis role="bold">uss add</emphasis> command with this type of template, provide the following
|
|
arguments: <itemizedlist>
|
|
<listitem>
|
|
<para><emphasis role="bold">-user</emphasis> to specify the username for the $USER variable</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">-server</emphasis> to specify the unique part of the file server machine name for the
|
|
$SERVER variable</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">-partition</emphasis> to specify the unique part of the partition name for the $PART
|
|
variable</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>The Protection Server automatically assigns an AFS UID for the $UID variable, and the <emphasis role="bold">G</emphasis>
|
|
instructions provide a value for the $AUTO variable.</para>
|
|
|
|
<para>The following example template file creates a full account in the ABC Corporation cell. The following sections about
|
|
each type of instruction describe the effect of the examples. Note that the <emphasis role="bold">V</emphasis> and <emphasis
|
|
role="bold">E</emphasis> instructions appear on two lines each only for the sake of legibility.</para>
|
|
|
|
<programlisting>
|
|
#
|
|
# Specify the available grouping directories
|
|
#
|
|
G /afs/.abc.com/usr1
|
|
G /afs/.abc.com/usr2
|
|
#
|
|
# Create the user's home volume
|
|
#
|
|
V user.$USER $SERVER.abc.com /vicep$PART 5000 /afs/.abc.com/$AUTO/$USER \
|
|
$UID $USER all abc:staff rl
|
|
#
|
|
# Create directories and files for mail
|
|
#
|
|
D $MTPT/.MESSAGES 0700 $UID $USER all abc:staff none
|
|
D $MTPT/.Outgoing 0700 $UID $USER rlidwk postman rlidwk
|
|
D $MTPT/Mailbox 0700 $UID $USER all abc:staff none system:anyuser lik
|
|
#
|
|
# Here are some useful scripts for login etc.
|
|
#
|
|
F $MTPT/.Xbiff 0755 $UID /afs/abc.com/admin/user/proto
|
|
F $MTPT/.Xresources 0644 $UID /afs/abc.com/admin/user/proto
|
|
F $MTPT/.Xsession 0755 $UID /afs/abc.com/admin/user/proto
|
|
F $MTPT/.cshrc 0755 $UID /afs/abc.com/admin/user/proto
|
|
F $MTPT/.login 0755 $UID /afs/abc.com/admin/user/proto
|
|
F $MTPT/.logout 0755 $UID /afs/abc.com/admin/user/proto
|
|
F $MTPT/.twmrc 0644 $UID /afs/abc.com/admin/user/proto
|
|
F $MTPT/preferences 0644 $UID /afs/abc.com/admin/user/proto
|
|
#
|
|
# Make a passwd entry
|
|
#
|
|
E /afs/.abc.com/common/etc/newaccts/passwd_$USER 0644 root \
|
|
"$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
|
|
#
|
|
# Put in the standard password/authentication checks
|
|
#
|
|
A $USER 250 noreuse 9 25
|
|
#
|
|
# Create and mount a public volume for the user
|
|
#
|
|
X "create_public_vol $USER $1 $2"
|
|
#
|
|
# Here we set up the symbolic link to public directory
|
|
#
|
|
S /afs/abc.com/public/$USER $MTPT/public
|
|
</programlisting>
|
|
|
|
<indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>directory</secondary>
|
|
|
|
<tertiary>distributing evenly with G instruction</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>defining</primary>
|
|
|
|
<secondary>directory for even distribution of accounts with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>directory</primary>
|
|
|
|
<secondary>defining for even distribution of accounts with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>G instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>directory</secondary>
|
|
|
|
<tertiary>G instruction for even distribution</tertiary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ472">
|
|
<title>Evenly Distributing User Home Directories with the G Instruction</title>
|
|
|
|
<para>In cells with thousands of user accounts, it often makes sense to distribute the mount points for user volumes into
|
|
multiple parent directories, because placing them all in one directory noticeably slows down directory lookup when a user home
|
|
directory is accessed. A possible solution is to create parent directories that group user home directories alphabetically, or
|
|
that reflect divisions like academic or corporate departments. However, in a really large cell, some such groups can still be
|
|
large enough to slow directory lookup, and users who belong to those groups are unfairly penalized every time they access
|
|
their home directory. Another drawback to groupings that reflect workplace divisions is that you must move mount points when
|
|
users change departmental affiliation.</para>
|
|
|
|
<para>An alternative is an even distribution of user home directories into multiple parent directories that do not represent
|
|
workplace divisions. The <emphasis role="bold">uss</emphasis> command suite enables you to define a list of directories by
|
|
placing a <emphasis role="bold">G</emphasis> instruction for each one at the top of the template file, and then using the
|
|
$AUTO variable in the <emphasis role="bold">V</emphasis> instruction's mount_point field. When the <emphasis
|
|
role="bold">uss</emphasis> command interpreter encounters the $AUTO variable, it substitutes the directory named by a
|
|
<emphasis role="bold">G</emphasis> instruction that currently has the fewest entries. (Actually, the $AUTO variable can appear
|
|
in any field that includes a pathname, in any type of instruction. In all cases, the command interpreter substitutes the
|
|
directory that currently has the fewest entries.)</para>
|
|
|
|
<para>The <emphasis role="bold">G</emphasis> instruction's syntax is as follows:</para>
|
|
|
|
<programlisting>
|
|
G directory
|
|
</programlisting>
|
|
|
|
<para>where directory specifies either a complete directory pathname or only the final element (the directory itself). The
|
|
choice determines the appropriate value to place in the <emphasis role="bold">V</emphasis> instruction's mount_point
|
|
field.</para>
|
|
|
|
<para>Specify the read/write path to each directory, to avoid the failure that results when you attempt to create a new mount
|
|
point in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
|
|
pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). For further discussion of the concept
|
|
of read/write and read-only paths through the filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
|
|
|
|
<para>For example, the ABC Corporation example template for a full account in <link linkend="HDRWQ471">Example uss
|
|
Templates</link> defines two directories:</para>
|
|
|
|
<programlisting>
|
|
G /afs/.abc.com/usr1
|
|
G /afs/.abc.com/usr2
|
|
</programlisting>
|
|
|
|
<para>and puts the value <emphasis role="bold">$AUTO/$USER</emphasis> in the <emphasis role="bold">V</emphasis> instruction's
|
|
mount_point field. An alternative with the same result is to define the directories as follows:</para>
|
|
|
|
<programlisting>
|
|
G usr1
|
|
G usr2
|
|
</programlisting>
|
|
|
|
<para>and specify a more complete pathname in the <emphasis role="bold">V</emphasis> instruction's mount_point field:
|
|
<emphasis role="bold">/afs/.abc.com/$AUTO/$USER</emphasis>. <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>volume</secondary>
|
|
|
|
<tertiary>creating with V instruction</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>volume with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>volume</primary>
|
|
|
|
<secondary>creating with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>V instruction</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>volume</secondary>
|
|
|
|
<tertiary>creating with V instruction</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>zero-length</secondary>
|
|
</indexterm></para>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ473">
|
|
<title>Creating a Volume with the V Instruction</title>
|
|
|
|
<para>Unless the template file is empty (zero-length), one and only one <emphasis role="bold">V</emphasis> instruction must
|
|
appear in it. (To create other volumes for a user as part of a <emphasis role="bold">uss</emphasis> account-creation
|
|
operation, use the <emphasis role="bold">X</emphasis> instruction to invoke the <emphasis role="bold">vos create</emphasis>
|
|
command or a script that invokes that command along with others, such as the <emphasis role="bold">fs mkmount</emphasis>
|
|
command. For an example, see <link linkend="HDRWQ479">Executing Commands with the X Instruction</link>.)</para>
|
|
|
|
<para>The <emphasis role="bold">V</emphasis> instruction defines the following AFS entities:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A volume and associated VLDB entry</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The volume's site (file server machine and partition)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The volume's mount point in the AFS filespace, which becomes the user's home directory</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The volume's space quota</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The home directory's owner, usually the new user</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The home directory's ACL, which normally at least grants all permissions to the user</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>The following discussion of the fields in a <emphasis role="bold">V</emphasis> instruction refers to the example in the
|
|
full account template from <link linkend="HDRWQ471">Example uss Templates</link> (the instruction appears here on two lines
|
|
only for legibility):</para>
|
|
|
|
<programlisting>
|
|
V user.$USER $SERVER.abc.com /vicep$PART 5000 \
|
|
/afs/.abc.com/$AUTO/$USER $UID $USER all abc:staff rl
|
|
</programlisting>
|
|
|
|
<para>The <emphasis role="bold">V</emphasis> instruction's syntax is as follows:</para>
|
|
|
|
<programlisting>
|
|
V volume_name server partition quota mount_point owner ACL
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">V</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Indicates a volume creation instruction.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">volume_name</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the volume's name as recorded in the VLDB.</para>
|
|
|
|
<para>To follow the convention of including the user's name as part of the volume name, include the $USER variable in
|
|
this field. The variable takes its value from the <emphasis role="bold">-user</emphasis> argument to the <emphasis
|
|
role="bold">uss add</emphasis> command or from the bulk input file <emphasis role="bold">add</emphasis> instruction's
|
|
username field.</para>
|
|
|
|
<para>The ABC Corporation example uses the value <emphasis role="bold">user.$USER</emphasis> to assign the
|
|
conventional volume name, <emphasis role="bold">user.</emphasis>username. When creating an account for user <emphasis
|
|
role="bold">smith</emphasis>, for example, you then include <emphasis role="bold">-user smith</emphasis> as an
|
|
argument to the <emphasis role="bold">uss add</emphasis> command, or place the value <emphasis
|
|
role="bold">smith</emphasis> in the bulk input file <emphasis role="bold">add</emphasis> instruction's username
|
|
field.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">server</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the file server machine on which to create the new volume. It is best to provide a fully qualified host
|
|
name (for example, <emphasis role="bold">fs1.abc.com</emphasis>), but an abbreviated form is acceptable if the cell's
|
|
naming service is available to resolve it at the time the volume is created.</para>
|
|
|
|
<para>To place different users' volumes on different file server machines, use the $SERVER variable in this field, and
|
|
provide a value for it either with the <emphasis role="bold">-server</emphasis> argument to the <emphasis
|
|
role="bold">uss add</emphasis> command or in the server field of the bulk input file <emphasis
|
|
role="bold">add</emphasis> instruction. One easy way to specify a fully qualified hostname without having to type it
|
|
completely on the command line is to combine a constant and the $SERVER variable. Specifically, the constant specifies
|
|
the domain-name suffix common to all the file server machines.</para>
|
|
|
|
<para>In the ABC Corporation example, all of the file server machines in the cell share the <emphasis
|
|
role="bold">abc.com</emphasis> domain name suffix, so the server field combines a variable and constant: <emphasis
|
|
role="bold">$SERVER.abc.com</emphasis>. To place the new volume on the machine <emphasis
|
|
role="bold">fs1.abc.com</emphasis>, you then include <emphasis role="bold">-server fs1</emphasis> as an argument to
|
|
the <emphasis role="bold">uss add</emphasis> command, or place the value <emphasis role="bold">fs1</emphasis> in the
|
|
bulk input file <emphasis role="bold">add</emphasis> instruction's server field.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">partition</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the partition on which to create the user's volume; it must be on the file server machine named in the
|
|
server field. Identify the partition by its complete name (for example, <emphasis role="bold">/vicepa</emphasis>) or
|
|
use one of the abbreviations listed in <link linkend="HDRWQ615">Rules for Using Abbreviations and
|
|
Aliases</link>.</para>
|
|
|
|
<para>To place different users' volumes on different partitions, use the $PART variable in this field, and provide a
|
|
value for it either with the <emphasis role="bold">-partition</emphasis> argument to the <emphasis role="bold">uss
|
|
add</emphasis> command or in the partition field of the bulk input file <emphasis role="bold">add</emphasis>
|
|
instruction. Because all full partition names start with the <emphasis role="bold">/vicep</emphasis> string, it is
|
|
convenient to combine that string as a constant with the $PART variable.</para>
|
|
|
|
<para>The ABC Corporation example template combines the constant string <emphasis role="bold">/vicep</emphasis> and
|
|
the $PART variable in this way, as <emphasis role="bold">/vicep$PART</emphasis>. <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>volume</secondary>
|
|
|
|
<tertiary>setting quota</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>volume quota</primary>
|
|
|
|
<secondary>setting</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>quota on volume, setting with V instruction</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>setting</primary>
|
|
|
|
<secondary>volume quota with uss</secondary>
|
|
</indexterm></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">quota</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Sets the maximum number of kilobyte blocks the volume can occupy on the file server machine's disk. It must be
|
|
an integer. If you assign the same quota to all user volumes, specify a constant value. To assign different quotas to
|
|
different volumes, place one of the number variables ($1 through $9) in this field, and provide a value for it either
|
|
with the <emphasis role="bold">-var</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or in
|
|
the appropriate field of the bulk input file <emphasis role="bold">add</emphasis> instruction.</para>
|
|
|
|
<para>The ABC Corporation example grants a 5000 KB initial quota to every new user. <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>volume</secondary>
|
|
|
|
<tertiary>mounting</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>mount point with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>mount point, creating with V instruction</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>mount point</primary>
|
|
|
|
<secondary>creating with uss</secondary>
|
|
</indexterm></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">mount_point</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Creates a mount point for the volume, which serves as the volume's root directory and the user's home directory.
|
|
By convention, user home directory names include the username, which you can read in by including the $USER variable
|
|
in this field.</para>
|
|
|
|
<para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to create the
|
|
new mount point in a read-only volume. By convention, you indicate the read/write path by placing a period before the
|
|
cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). If you use the
|
|
$AUTO variable in this field, the directories named by each <emphasis role="bold">G</emphasis> 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 <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
|
|
|
|
<para>If other parts of the mount point name also vary from user to user, you can use the $MTPT variable in this
|
|
field, and provide a value with the <emphasis role="bold">uss add</emphasis> command's <emphasis
|
|
role="bold">-mount</emphasis> argument or in the mount_point field of a bulk input file <emphasis
|
|
role="bold">add</emphasis> instruction. Note, however, that when the $MTPT variable appears in subsequent instructions
|
|
in the template (usually, in <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, or <emphasis
|
|
role="bold">F</emphasis> instructions), it instead takes as its value the complete contents of this field.</para>
|
|
|
|
<para>Combine constants and variables based on how you have decided to group home directories together in one or more
|
|
parent directories. Note that the parent directories must already exist before you run a <emphasis role="bold">uss
|
|
add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command that references the template. Possibilities for
|
|
grouping home directories include the following: <indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>methods for grouping</secondary>
|
|
</indexterm> <itemizedlist>
|
|
<listitem>
|
|
<para>Placing all user home directories in a single parent directory; the name <emphasis
|
|
role="bold">/afs/</emphasis>cellname<emphasis role="bold">/usr</emphasis> is an AFS-appropriate variation on the
|
|
UNIX <emphasis role="bold">/usr</emphasis> convention. This choice is most appropriate for a cell with a small
|
|
number of user accounts. The simplest way to implement this choice is to combine a constant string and the $USER
|
|
variable, as in <emphasis role="bold">/afs/.abc.com/usr/$USER</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Distributing home directories evenly into a set of parent directories that do not correspond to workplace
|
|
divisions. This choice is appropriate in cells with tens of thousands of accounts, where the number of home
|
|
directories is large enough to slow directory lookup significantly if they all reside together in one parent
|
|
directory, but distribution according to workplace divisions is not feasible.</para>
|
|
|
|
<para>The $AUTO variable is designed to distribute home directories evenly in this manner. As explained in <link
|
|
linkend="HDRWQ472">Evenly Distributing User Home Directories with the G Instruction</link>, the <emphasis
|
|
role="bold">uss</emphasis> command interpreter substitutes the directory that is defined by a preceding
|
|
<emphasis role="bold">G</emphasis> template instruction and that currently has the fewest entries. The example
|
|
ABC Corporation template illustrates this choice by using the value <emphasis
|
|
role="bold">/afs/.abc.com/$AUTO/$USER</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Distributing home directories into multiple directories that reflect divisions like academic or corporate
|
|
departments. Perhaps the simplest way to implement this scheme is to use the $MTPT variable to represent the
|
|
department, as in <emphasis role="bold">/afs/.ghi.com/usr/$MTPT/$USER</emphasis>. You then provide <emphasis
|
|
role="bold">-user smith</emphasis> and <emphasis role="bold">-mount acctg</emphasis> arguments to the <emphasis
|
|
role="bold">uss add</emphasis> command to create the mount point <emphasis
|
|
role="bold">/afs/.ghi.com/usr/acctg/smith</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Distributing home directories into alphabetic subdirectories of <emphasis role="bold">usr</emphasis>
|
|
(<emphasis role="bold">usr/a</emphasis>, <emphasis role="bold">usr/b</emphasis> and so on), based on the first
|
|
letter or letters in the username. The advantage is that knowing the username enables you easily to locate a
|
|
home directory. A potential drawback is that the distribution is not likely to be even, and if there are a large
|
|
number of accounts, then slowed directory lookup unfairly affects users whose names begins with popular
|
|
letters.</para>
|
|
|
|
<para>Perhaps the simplest way to implement this scheme is to use the $MTPT variable to represent the letter or
|
|
letters, as in <emphasis role="bold">/afs/.jkl.com/usr/$MTPT/$USER</emphasis>. Then provide the <emphasis
|
|
role="bold">-user smith</emphasis> and <emphasis role="bold">-mount s/m</emphasis> arguments to the <emphasis
|
|
role="bold">uss add</emphasis> command to create the mount point <emphasis
|
|
role="bold">/afs/.jkl.com/usr/s/m/smith</emphasis>.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">owner</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the username or UID of the user to be designated the mount point's owner in the output from the UNIX
|
|
<emphasis role="bold">ls -ld</emphasis> command. To follow the standard convention for home directory ownership, use
|
|
the $UID variable in this field, as in the ABC Corporation example template. The Protection Server then automatically
|
|
assigns an AFS UID unless you provide the <emphasis role="bold">-uid</emphasis> argument to the <emphasis
|
|
role="bold">uss add</emphasis> command or fill in the uid field in the bulk input file <emphasis
|
|
role="bold">add</emphasis> instruction. (If you are converting existing UNIX accounts, see the discussion of
|
|
additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link>.) <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>ACL, setting on home directory</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>ACL</primary>
|
|
|
|
<secondary>setting on user home directory with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>ACL, setting</secondary>
|
|
|
|
<tertiary>user home directory with V instruction</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>setting</primary>
|
|
|
|
<secondary>ACL on home directory with uss</secondary>
|
|
</indexterm></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">ACL</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Sets the ACL on the new home directory. Provide one or more paired values, each pair consisting of an AFS
|
|
username or group name and the desired permissions, in that order (a group name must already exist in the Protection
|
|
Database to be used). Separate the two parts of the pair, and each pair, with a space. For a discussion of the
|
|
available permissions, see <link linkend="HDRWQ567">The AFS ACL Permissions</link>.</para>
|
|
|
|
<para>At minimum, grant all permissions to the new user by including the value <emphasis role="bold">$USER
|
|
all</emphasis> in this field. The File Server automatically grants all permissions to the <emphasis
|
|
role="bold">system:administrators</emphasis> group as well. You cannot grant permissions to the issuer of the
|
|
<emphasis role="bold">uss</emphasis> command, because as the last step in account creation the <emphasis
|
|
role="bold">uss</emphasis> command interpreter automatically deletes that user from any ACLs set during the creation
|
|
process.</para>
|
|
|
|
<para>The ABC Corporation example uses the following value to grant all permissions to the new user and <emphasis
|
|
role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis
|
|
role="bold">lookup</emphasis>) permissions to the members of the <emphasis role="bold">abc:staff</emphasis>
|
|
group:</para>
|
|
|
|
<para><emphasis role="bold">$USER all abc:staff rl</emphasis></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>D instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>directory</secondary>
|
|
|
|
<tertiary>creating</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>directory</secondary>
|
|
|
|
<tertiary>creating with D instruction</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>directory with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>directory</primary>
|
|
|
|
<secondary>creating with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>D instruction</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ474">
|
|
<title>Creating a Directory with the D Instruction</title>
|
|
|
|
<para>Each <emphasis role="bold">D</emphasis> instruction in the template file creates a directory; there is no limit on the
|
|
number of them in the template. If a <emphasis role="bold">D</emphasis> instruction creates a subdirectory in a new user's
|
|
home directory (its intended use), then it must follow the <emphasis role="bold">V</emphasis> instruction. Creating a
|
|
directory on the local disk of the machine where the <emphasis role="bold">uss</emphasis> command runs is not recommended for
|
|
the reasons outlined in <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
|
|
|
|
<para>The following discussion of the fields in a <emphasis role="bold">D</emphasis> instruction refers to one of the examples
|
|
in the full account template in <link linkend="HDRWQ471">Example uss Templates</link>:</para>
|
|
|
|
<programlisting>
|
|
D $MTPT/Mailbox 0700 $UID $USER all abc:staff none system:anyuser lik
|
|
</programlisting>
|
|
|
|
<para>The <emphasis role="bold">D</emphasis> instruction's syntax is as follows:</para>
|
|
|
|
<programlisting>
|
|
D pathname mode_bits owner ACL
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">D</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Indicates a directory creation instruction.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">pathname</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the directory's full pathname. If it is a subdirectory of the user's home directory, it is simplest to
|
|
use the $MTPT variable to specify the home directory pathname. When the $MTPT variable appears in a <emphasis
|
|
role="bold">D</emphasis> instruction, it takes its value from the preceding <emphasis role="bold">V</emphasis>
|
|
instruction's mount_point field (this dependency is why a <emphasis role="bold">D</emphasis> instruction must follow
|
|
the <emphasis role="bold">V</emphasis> instruction).</para>
|
|
|
|
<para>Specify the read/write pathname to the directory, to avoid the failure that results when you attempt to create a
|
|
new directory in a read-only volume. By convention, you indicate the read/write path by placing a period before the
|
|
cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). If you use the
|
|
$MTPT variable in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field
|
|
possibly already indicates the read/write path. For further discussion of the concept of read/write and read-only
|
|
paths through the filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
|
|
|
|
<para>The ABC Corporation example uses the value <emphasis role="bold">$MTPT/Mailbox</emphasis> to place the <emphasis
|
|
role="bold">Mailbox</emphasis> subdirectory in the user's home directory.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">mode_bits</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Defines the directory's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers
|
|
corresponding to a combination of permissions. Examples: <emphasis role="bold">0755</emphasis> corresponds to
|
|
<emphasis role="bold">rwxr-xr-x</emphasis>, and <emphasis role="bold">0644</emphasis> to <emphasis
|
|
role="bold">rw-r--r--</emphasis>. The first (owner) <emphasis role="bold">x</emphasis> bit must be turned on to enable
|
|
access to a directory.</para>
|
|
|
|
<para>The ABC Corporation example uses the value <emphasis role="bold">0700</emphasis> to set the mode bits on the
|
|
<emphasis role="bold">Mailbox</emphasis> subdirectory to <emphasis role="bold">rwxr-----</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">owner</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the username or UID of the user to be designated the directory's owner in the output from the UNIX
|
|
<emphasis role="bold">ls -ld</emphasis> command.</para>
|
|
|
|
<para>If the directory resides in AFS, place the $UID variable in this field, as in the ABC Corporation example
|
|
template. The Protection Server then automatically assigns an AFS UID unless you provide the <emphasis
|
|
role="bold">-uid</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or fill in the uid field
|
|
in the bulk input file <emphasis role="bold">add</emphasis> instruction. (If you are converting existing UNIX
|
|
accounts, see the discussion of additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX
|
|
Accounts with uss</link>.)</para>
|
|
|
|
<para>If the directory resides on the local disk, it is simplest to specify the username or UNIX UID under which you
|
|
are issuing the <emphasis role="bold">uss</emphasis> command. For a discussion of the complications that arise from
|
|
designating another user, see <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.
|
|
<indexterm>
|
|
<primary>ACL</primary>
|
|
|
|
<secondary>setting for directory with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>setting</primary>
|
|
|
|
<secondary>ACL for directory with uss</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>ACL, setting</secondary>
|
|
|
|
<tertiary>directory created by D instruction</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>ACL, setting for directory</secondary>
|
|
</indexterm></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">ACL</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Sets the ACL on the new directory. Provide one or more paired values, each pair consisting of an AFS username or
|
|
group name and the desired permissions, in that order (a group name must already exist in the Protection Database to
|
|
be used). Separate the two parts of the pair, and each pair, with a space. For a description of the available
|
|
permissions, see <link linkend="HDRWQ567">The AFS ACL Permissions</link>.</para>
|
|
|
|
<para>At minimum, grant all permissions to the new user by including the value <emphasis role="bold">$USER
|
|
all</emphasis>. You cannot grant permissions to the issuer of the <emphasis role="bold">uss</emphasis> command,
|
|
because as the last step in account creation the <emphasis role="bold">uss</emphasis> command interpreter
|
|
automatically deletes that user from any ACLs set during the creation process. An error message always appears if the
|
|
directory is on the local disk, as detailed in <link linkend="HDRWQ470">About Creating Local Disk Directories and
|
|
Files</link>.</para>
|
|
|
|
<para>The ABC Corporation example uses the following value to grant all permissions to the new user, no permissions to
|
|
the members of the <emphasis role="bold">abc:staff</emphasis> group, and the <emphasis role="bold">l</emphasis>
|
|
(<emphasis role="bold">lookup</emphasis>), <emphasis role="bold">i</emphasis> (<emphasis
|
|
role="bold">insert</emphasis>), and <emphasis role="bold">k</emphasis> (<emphasis role="bold">lock</emphasis>)
|
|
permissions to the members of the <emphasis role="bold">system:anyuser</emphasis> group:</para>
|
|
|
|
<para><emphasis role="bold">$USER all abc:staff none system:anyuser lik</emphasis></para>
|
|
|
|
<para>It grants such extensive permissions to the <emphasis role="bold">system:anyuser</emphasis> group to enable any
|
|
system user (including a mail-delivery daemon) to insert mail into the <emphasis role="bold">Mailbox</emphasis>
|
|
directory. The absence of the <emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) permission
|
|
prevents members of the <emphasis role="bold">system:anyuser</emphasis> group from reading the mail files.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>file, creating from prototype</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>file with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>file</primary>
|
|
|
|
<secondary>creating with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>F instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>file</secondary>
|
|
|
|
<tertiary>creating from prototype</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>F instruction</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ475">
|
|
<title>Creating a File from a Prototype with the F Instruction</title>
|
|
|
|
<para>Each <emphasis role="bold">F</emphasis> instruction in the template file creates a file by copying the contents of an
|
|
existing prototype file; there is no limit on the number of them in the template, and each can refer to a different prototype.
|
|
If an <emphasis role="bold">F</emphasis> instruction creates a file in a new user's home directory or a subdirectory of it
|
|
(the intended use), then it must follow the <emphasis role="bold">V</emphasis> or <emphasis role="bold">D</emphasis>
|
|
instruction that creates the parent directory. Creating a file on the local disk of the machine where the <emphasis
|
|
role="bold">uss</emphasis> command runs is not recommended for the reasons detailed in <link linkend="HDRWQ470">About Creating
|
|
Local Disk Directories and Files</link>.</para>
|
|
|
|
<para>The <emphasis role="bold">E</emphasis> instruction also creates a file, but the two types of instruction have
|
|
complementary advantages. Files created with an <emphasis role="bold">E</emphasis> instruction can be customized for each
|
|
user, because variables can appear in the field that specifies the contents of the file. In contrast, the contents of a file
|
|
created using the <emphasis role="bold">F</emphasis> instruction are the same for every user. An <emphasis
|
|
role="bold">E</emphasis> file can be only a single line, however, whereas an <emphasis role="bold">F</emphasis> file can be
|
|
any length.</para>
|
|
|
|
<para>The following discussion of the fields in a <emphasis role="bold">F</emphasis> instruction refers to one of the examples
|
|
in the full account template in <link linkend="HDRWQ471">Example uss Templates</link>:</para>
|
|
|
|
<programlisting>
|
|
F $MTPT/.login 0755 $UID /afs/abc.com/admin/user/proto
|
|
</programlisting>
|
|
|
|
<para>The <emphasis role="bold">F</emphasis> instruction's syntax is as follows:</para>
|
|
|
|
<programlisting>
|
|
F pathname mode_bits owner prototype_file
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">F</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Indicates a file creation instruction.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">pathname</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the full pathname of the file to create, including the filename. If it resides in the user's home
|
|
directory or a subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname.
|
|
When the $MTPT variable appears in an <emphasis role="bold">F</emphasis> instruction, it takes its value from the
|
|
preceding <emphasis role="bold">V</emphasis> instruction's mount_point field (this dependency is why an <emphasis
|
|
role="bold">F</emphasis> instruction must follow the <emphasis role="bold">V</emphasis> instruction).</para>
|
|
|
|
<para>Specify the read/write path to the file, to avoid the failure that results when you attempt to create a new file
|
|
in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
|
|
pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). If you use the $MTPT variable
|
|
in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field possibly already
|
|
indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the
|
|
filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
|
|
|
|
<para>The ABC Corporation example uses the value <emphasis role="bold">$MTPT/.login</emphasis> to place a file called
|
|
<emphasis role="bold">.login</emphasis> in the user's home directory.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">mode_bits</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Defines the file's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding
|
|
to a combination of permissions. Examples: <emphasis role="bold">0755</emphasis> corresponds to <emphasis
|
|
role="bold">rwxr-xr-x</emphasis>, and <emphasis role="bold">0644</emphasis> to <emphasis
|
|
role="bold">rw-r--r--</emphasis>.</para>
|
|
|
|
<para>The ABC Corporation example uses the value <emphasis role="bold">0755</emphasis> to set the mode bits on the
|
|
<emphasis role="bold">.login</emphasis> file to <emphasis role="bold">rwxr-xr-x</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">owner</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the username or UID of the user to be designated the file's owner in the output from the UNIX
|
|
<emphasis role="bold">ls -l</emphasis> command.</para>
|
|
|
|
<para>If the file resides in AFS, place the $UID variable in this field, as in the ABC Corporation example template.
|
|
The Protection Server then automatically assigns an AFS UID unless you provide the <emphasis
|
|
role="bold">-uid</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command or fill in the uid field
|
|
in the bulk input file <emphasis role="bold">add</emphasis> instruction. (If you are converting existing UNIX
|
|
accounts, see the discussion of additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX
|
|
Accounts with uss</link>.)</para>
|
|
|
|
<para>If the file resides on the local disk, it is simplest to specify the username or UNIX UID under which you are
|
|
issuing the <emphasis role="bold">uss</emphasis> command. For a discussion of the complications that arise from
|
|
designating another user, see <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">prototype_file</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the AFS or local directory that houses the prototype file to copy. The prototype file's name must match
|
|
the final element in the pathname field.</para>
|
|
|
|
<para>The ABC Corporation example references a prototype file called <emphasis role="bold">.login</emphasis> in the
|
|
directory <emphasis role="bold">/afs/abc.com/admin/user/proto</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>file, creating by echoing one line</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>file with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>file</primary>
|
|
|
|
<secondary>creating with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>E instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>file</secondary>
|
|
|
|
<tertiary>creating by echoing one line</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>E instruction</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ476">
|
|
<title>Creating One-Line Files with the E Instruction</title>
|
|
|
|
<para>Each <emphasis role="bold">E</emphasis> instruction in the template file creates a file by echoing a specified single
|
|
line into it; there is no limit on the number of them in the template. If an <emphasis role="bold">E</emphasis> instruction
|
|
creates a file in a new user's home directory or a subdirectory of it (the intended use), then it must follow the <emphasis
|
|
role="bold">V</emphasis> or <emphasis role="bold">D</emphasis> instruction that creates the parent directory. Creating a file
|
|
on the local disk of the machine where the <emphasis role="bold">uss</emphasis> command runs is not recommended for the
|
|
reasons detailed in <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
|
|
|
|
<para>The <emphasis role="bold">F</emphasis> instruction also creates a file, but the two types of instruction have
|
|
complementary advantages. Files created with an <emphasis role="bold">E</emphasis> instruction can be customized for each
|
|
user, because variables can appear in the field that specifies the contents of the file. The command interpreter replaces the
|
|
variables with appropriate values before creating the file. In contrast, the contents of a file created using the <emphasis
|
|
role="bold">F</emphasis> instruction are the same for every user. An <emphasis role="bold">E</emphasis> file can be only a
|
|
single line, however, whereas an <emphasis role="bold">F</emphasis> file can be any length.</para>
|
|
|
|
<para>The <emphasis role="bold">E</emphasis> instruction is particularly suited to creating an entry for the new user in the
|
|
cell's common source password file, which is then copied to client machines to serve as the local password file (<emphasis
|
|
role="bold">/etc/passwd</emphasis> or equivalent). The following discussion of the fields refers to an example of this type of
|
|
use, from the ABC Corporation's full account template shown in <link linkend="HDRWQ471">Example uss Templates</link>. For
|
|
further discussion of how to incorporate the files created in this way into a common source password file, see <link
|
|
linkend="HDRWQ458">Creating a Common Source Password File</link>.</para>
|
|
|
|
<programlisting>
|
|
E /afs/.abc.com/common/etc/newaccts/passwd_$USER 0644 root \
|
|
"$USER:X:$UID:11:$NAME:$MTPT:/bin/csh"
|
|
</programlisting>
|
|
|
|
<para>The <emphasis role="bold">E</emphasis> instruction's syntax is as follows:</para>
|
|
|
|
<programlisting>
|
|
E pathname mode_bits owner "contents"
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">E</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Indicates a file creation instruction.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">pathname</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the full pathname of the file to create, including the filename. It can include variables. If it
|
|
resides in the user's home directory or a subdirectory of it, it is simplest to use the $MTPT variable to specify the
|
|
home directory pathname. When the $MTPT variable appears in an <emphasis role="bold">E</emphasis> instruction, it
|
|
takes its value from the preceding <emphasis role="bold">V</emphasis> instruction's mount_point field (this dependency
|
|
is why an <emphasis role="bold">E</emphasis> instruction must follow the <emphasis role="bold">V</emphasis>
|
|
instruction.)</para>
|
|
|
|
<para>Specify the read/write path to the file, to avoid the failure that results when you attempt to create a new file
|
|
in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
|
|
pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). If you use the $MTPT variable
|
|
in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field possibly already
|
|
indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the
|
|
filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
|
|
|
|
<para>The ABC Corporation example writes the file created by the <emphasis role="bold">E</emphasis> instruction to
|
|
<emphasis role="bold">/afs/.abc.com/common/etc/newaccts</emphasis> directory, naming it after the new user:</para>
|
|
|
|
<programlisting>
|
|
/afs/.abc.com/common/etc/newaccts/passwd_$USER
|
|
</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">mode_bits</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Defines the file's UNIX mode bits. Acceptable values are the standard three- or four-digit numbers corresponding
|
|
to a combination of permissions. Examples: <emphasis role="bold">0755</emphasis> corresponds to <emphasis
|
|
role="bold">rwxr-xr-x</emphasis>, and <emphasis role="bold">0644</emphasis> to <emphasis
|
|
role="bold">rw-r--r--</emphasis>.</para>
|
|
|
|
<para>The ABC Corporation example uses the value <emphasis role="bold">0644</emphasis> to set the mode bits on the
|
|
<emphasis role="bold">passwd_</emphasis>user file to <emphasis role="bold">r-xr--r--</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">owner</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the username or UID of the user to be designated the file's owner in the output from the UNIX
|
|
<emphasis role="bold">ls -l</emphasis> command.</para>
|
|
|
|
<para>If the file resides in AFS and is to be owned by the user, place the $UID variable in this field. The Protection
|
|
Server then automatically assigns an AFS UID unless you provide the <emphasis role="bold">-uid</emphasis> argument to
|
|
the <emphasis role="bold">uss add</emphasis> command or fill in the uid field in the bulk input file <emphasis
|
|
role="bold">add</emphasis> instruction. (If you are converting existing UNIX accounts, see the discussion of
|
|
additional considerations in <link linkend="HDRWQ459">Converting Existing UNIX Accounts with uss</link>.)</para>
|
|
|
|
<para>If the file resides on the local disk, specify the username or UNIX UID under which you are issuing the
|
|
<emphasis role="bold">uss</emphasis> command. For a discussion of the complications that arise from designating
|
|
another user, see <link linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
|
|
|
|
<para>The ABC Corporation example is creating an AFS file intended for incorporation into the common password file,
|
|
rather than for direct use by the new user. It therefore designates the local superuser <emphasis
|
|
role="bold">root</emphasis> as the owner of the new file. Designating an alternate owner on an AFS file does not
|
|
introduce complications: issuing the <emphasis role="bold">chown</emphasis> command on AFS files requires membership
|
|
in the <emphasis role="bold">system:administrators</emphasis> group, but the issuer of the <emphasis
|
|
role="bold">uss</emphasis> command is necessarily authenticated as a member of that group.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">contents</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>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.</para>
|
|
|
|
<para>The ABC Corporation example has the following value in the contents field, to create a password file
|
|
entry:</para>
|
|
|
|
<programlisting>
|
|
$USER:X:$UID:10:$NAME:$MTPT:/bin/csh
|
|
</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<indexterm>
|
|
<primary>L instruction</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>S instruction</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss</primary>
|
|
|
|
<secondary>hard link, creating</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>link (hard or symbolic) with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>hard link</primary>
|
|
|
|
<secondary>creating with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>L instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>hard link, creating</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss</primary>
|
|
|
|
<secondary>symbolic link, creating</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>symbolic link</primary>
|
|
|
|
<secondary>creating with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>S instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>symbolic link, creating</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ477">
|
|
<title>Creating Links with the L and S Instructions</title>
|
|
|
|
<para>Each <emphasis role="bold">L</emphasis> instruction in the template file creates a hard link between two files, as
|
|
achieved by the standard UNIX <emphasis role="bold">ln</emphasis> command. The <emphasis role="bold">S</emphasis> instruction
|
|
creates a symbolic link between two files, as achieved by the standard UNIX <emphasis role="bold">ln -s</emphasis> command. An
|
|
explanation of links is beyond the scope of this document, but the basic effect in both cases is to create a second name for
|
|
an existing file, so that it can be accessed via either name. Creating a link does not create a second copy of the
|
|
file.</para>
|
|
|
|
<para>There is no limit on the number of <emphasis role="bold">L</emphasis> or <emphasis role="bold">S</emphasis> instructions
|
|
in a template file. If the link is in a new user's home directory or a subdirectory of it (the intended use), then it must
|
|
follow the <emphasis role="bold">V</emphasis> or <emphasis role="bold">D</emphasis> instruction that creates the parent
|
|
directory, and the <emphasis role="bold">F</emphasis>, <emphasis role="bold">E</emphasis>, or <emphasis
|
|
role="bold">X</emphasis> instruction that creates the file being linked to. Creating a file on the local disk of the machine
|
|
where the <emphasis role="bold">uss</emphasis> command runs is not recommended, for the reasons detailed in <link
|
|
linkend="HDRWQ470">About Creating Local Disk Directories and Files</link>.</para>
|
|
|
|
<para>Note that AFS allows hard links only between files that reside in the same directory. This restriction is necessary to
|
|
eliminate the confusion that results from associating two potentially different ACLs (those of the two directories) with the
|
|
same file. Symbolic links are legal between two files that reside in different directories and even in different volumes. The
|
|
ACL on the actual file applies to the link as well.</para>
|
|
|
|
<para>You do not set the owner or mode bits on a link created with an <emphasis role="bold">L</emphasis> or <emphasis
|
|
role="bold">S</emphasis> instruction, as you do for directories or files. The <emphasis role="bold">uss</emphasis> command
|
|
interpreter automatically records the UNIX UID of the <emphasis role="bold">uss</emphasis> command's issuer as the owner, and
|
|
sets the mode bits to <emphasis role="bold">lrwxrwxrwx</emphasis> (777).</para>
|
|
|
|
<para>The following discussion of the fields in an <emphasis role="bold">L</emphasis> or <emphasis role="bold">S</emphasis>
|
|
instruction refers to an example in the full account template from <link linkend="HDRWQ471">Example uss Templates</link>,
|
|
namely</para>
|
|
|
|
<programlisting>
|
|
S /afs/abc.com/public/$USER $MTPT/public
|
|
</programlisting>
|
|
|
|
<para>The <emphasis role="bold">L</emphasis> and <emphasis role="bold">S</emphasis> instructions' syntax is as follows:</para>
|
|
|
|
<programlisting>
|
|
L existing_file link
|
|
S existing_file link
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">L</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Indicates a hard link creation instruction.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">S</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Indicates a symbolic link creation instruction.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">existing_file</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the complete pathname of the existing file. If it resides in the user's home directory or a
|
|
subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname. When the $MTPT
|
|
variable appears in an <emphasis role="bold">L</emphasis> or <emphasis role="bold">S</emphasis> instruction, it takes
|
|
its value from the preceding <emphasis role="bold">V</emphasis> instruction's mount_point field (this dependency is
|
|
why the instruction must follow the <emphasis role="bold">V</emphasis> instruction).</para>
|
|
|
|
<para>Do not create a symbolic link to a file whose name begins with the number sign (<emphasis
|
|
role="bold">#</emphasis>) or percent sign (<emphasis role="bold">%</emphasis>). When the Cache Manager reads a
|
|
symbolic link whose contents begin with one of those characters, it interprets it as a regular or read/write mount
|
|
point, respectively.</para>
|
|
|
|
<para>The ABC Corporation example creates a link to the publicly readable volume created and mounted by a preceding
|
|
<emphasis role="bold">X</emphasis> instruction, by specifying the path to its mount point:</para>
|
|
|
|
<programlisting>
|
|
/afs/abc.com/public/$USER
|
|
</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">link</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the complete pathname of the second name for the file. If it resides in the user's home directory or a
|
|
subdirectory of it, it is simplest to use the $MTPT variable to specify the home directory pathname.</para>
|
|
|
|
<para>Specify the read/write path to the link, to avoid the failure that results when you attempt to create a new link
|
|
in a read-only volume. By convention, you indicate the read/write path by placing a period before the cell name at the
|
|
pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). If you use the $MTPT variable
|
|
in this field, the value in the <emphasis role="bold">V</emphasis> instruction's mount_point field possibly already
|
|
indicates the read/write path. For further discussion of the concept of read/write and read-only paths through the
|
|
filespace, see <link linkend="HDRWQ208">Mounting Volumes</link>.</para>
|
|
|
|
<para>The ABC Corporation example creates a link called <emphasis role="bold">public</emphasis> in the user's home
|
|
directory:</para>
|
|
|
|
<programlisting>
|
|
$MTPT/public
|
|
</programlisting>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<indexterm>
|
|
<primary>A instruction</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>password/authentication security, setting with A instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>A instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>password/authentication security, setting with A instruction</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ478">
|
|
<title>Increasing Account Security with the A Instruction</title>
|
|
|
|
<para>The <emphasis role="bold">A</emphasis> instruction in the template file enhances cell security by imposing the following
|
|
restrictions on users' password choice and authentication attempts. <itemizedlist>
|
|
<listitem>
|
|
<para>Limiting the user's password lifetime. When the lifetime expires, the user can no longer use the password to
|
|
authenticate and must change it.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Prohibiting the reuse of the user's 20 most-recently used passwords.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>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 <emphasis>account lockout</emphasis>). For regular user accounts in most cells, the recommended limit is nine and
|
|
lockout time is 25 minutes.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>The following discussion of the fields in an <emphasis role="bold">A</emphasis> instruction refers to the example in the
|
|
full account template from <link linkend="HDRWQ471">Example uss Templates</link>, which sets a password lifetime of 250 days,
|
|
prohibits reuse of passwords, limits the number of failed authentication attempts to nine, and creates a lockout time of 25
|
|
minutes if the authentication limit is exceeded:</para>
|
|
|
|
<programlisting>
|
|
A $USER 250 noreuse 9 25
|
|
</programlisting>
|
|
|
|
<para>The <emphasis role="bold">A</emphasis> instruction's syntax is as follows:</para>
|
|
|
|
<programlisting>
|
|
A username password_lifetime password_reuse failures locktime
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">A</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Indicates a security enhancing instruction.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">username</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the Authentication Database entry on which to impose security restrictions. Use the $USER variable to read
|
|
in the username from the <emphasis role="bold">uss add</emphasis> command's <emphasis role="bold">-user</emphasis>
|
|
argument, or from the username field of an <emphasis role="bold">add</emphasis> instruction in the bulk input file.
|
|
The ABC Corporation example uses this value.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">password_lifetime</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>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 <emphasis
|
|
role="bold">kpasswd</emphasis> command to change the password (after that, only an administrator can change
|
|
it).</para>
|
|
|
|
<para>Specify an integer from the range <emphasis role="bold">1</emphasis> through <emphasis
|
|
role="bold">254</emphasis> to specify the number of days until expiration, the value <emphasis
|
|
role="bold">0</emphasis> to indicate that the password never expires, or the value $PWEXPIRES to read in the number of
|
|
days from the <emphasis role="bold">uss add</emphasis> or <emphasis role="bold">uss bulk</emphasis> command's
|
|
<emphasis role="bold">-pwexpires</emphasis> argument. If the <emphasis role="bold">A</emphasis> instruction does not
|
|
appear in the template file, by default the user's password never expires.</para>
|
|
|
|
<para>The ABC Corporation example sets a password lifetime of 250 days.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">password_reuse</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Determines whether or not the user can change his or her password (using the <emphasis
|
|
role="bold">kpasswd</emphasis> or <emphasis role="bold">kas setpassword</emphasis> command) to one that is similar to
|
|
any of his or her last 20 passwords. The acceptable values are <emphasis role="bold">reuse</emphasis> to allow reuse
|
|
and <emphasis role="bold">noreuse</emphasis> to prohibit it. If the <emphasis role="bold">A</emphasis> instruction
|
|
does not appear in the template file, the default is to allow password reuse.</para>
|
|
|
|
<para>The ABC Corporation example prohibits password reuse.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">failures</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Sets the number of consecutive times the user can provide an incorrect password during authentication (using the
|
|
<emphasis role="bold">klog</emphasis> command or a login utility that grants AFS tokens). When the user exceeds the
|
|
limit, the Authentication Server rejects further authentication attempts for the amount of time specified in the
|
|
locktime field.</para>
|
|
|
|
<para>Specify an integer from the range <emphasis role="bold">1</emphasis> through <emphasis
|
|
role="bold">254</emphasis> to specify the number of failures permitted, or the value <emphasis
|
|
role="bold">0</emphasis> to indicate that there is no limit to the number of unsuccessful attempts. If the <emphasis
|
|
role="bold">A</emphasis> instruction does not appear in the template file, the default is to allow an unlimited number
|
|
of failures.</para>
|
|
|
|
<para>The ABC Corporation example sets the limit to nine failed attempts.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">locktime</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies how long the Authentication Server refuses authentication attempts from a user who has exceeded the
|
|
failure limit set in the failures field.</para>
|
|
|
|
<para>Specify a number of hours and minutes (hh:mm) or minutes only (mm), from the range <emphasis
|
|
role="bold">01</emphasis> (one minute) through <emphasis role="bold">36:00</emphasis> (36 hours). The Authentication
|
|
Server automatically reduces any larger value to <emphasis role="bold">36:00</emphasis> and also rounds up any nonzero
|
|
value to the next highest multiple of 8.5 minutes. A value of <emphasis role="bold">0</emphasis> (zero) sets an
|
|
infinite lockout time, in which case an administrator must always issue the <emphasis role="bold">kas
|
|
unlock</emphasis> command to unlock the account.</para>
|
|
|
|
<para>The ABC Corporation example sets the lockout time to 25 minutes, which is rounded up to 25 minutes 30 seconds
|
|
(the next highest multiple of 8.5 minutes).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
|
|
<indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>command, executing with X instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>executing</primary>
|
|
|
|
<secondary>command using uss template line</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>executing from uss template file</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>X instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss template file</primary>
|
|
|
|
<secondary>command, executing with X instruction</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>X instruction</primary>
|
|
|
|
<secondary>uss template file</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
|
|
<sect2 id="HDRWQ479">
|
|
<title>Executing Commands with the X Instruction</title>
|
|
|
|
<para>The <emphasis role="bold">X</emphasis> instruction in the template file executes a command, which can be a standard UNIX
|
|
command, a shell script or program, or an AFS command. The command string can include standard template variables, and any
|
|
number of <emphasis role="bold">X</emphasis> instructions can appear in a template file. If an instruction manipulates an
|
|
element created by another instruction, it must appear after that instruction.</para>
|
|
|
|
<para>The following discussion of the field in an <emphasis role="bold">X</emphasis> instruction refers to the example in the
|
|
full account template from <link linkend="HDRWQ471">Example uss Templates</link>:</para>
|
|
|
|
<programlisting>
|
|
X "create_public_vol $USER $1 $2"
|
|
</programlisting>
|
|
|
|
<para>The <emphasis role="bold">X</emphasis> instruction's syntax is as follows:</para>
|
|
|
|
<programlisting>
|
|
X "command"
|
|
</programlisting>
|
|
|
|
<para>where command specifies the command to execute. Surround it with double quotes if it contains spaces. The command string
|
|
can contain any of the standard variables, which the <emphasis role="bold">uss</emphasis> command interpreter resolves before
|
|
passing the command on to the appropriate other command interpreter, but it cannot contain newline characters.</para>
|
|
|
|
<para>The ABC Corporation example invokes a script called <emphasis role="bold">create_public_vol</emphasis>, which creates
|
|
another volume associated with the new user and mounts it in a publicly readable part of the ABC Corporation's
|
|
filespace:</para>
|
|
|
|
<programlisting>
|
|
"create_public_vol $USER $1 $2"
|
|
</programlisting>
|
|
|
|
<para>It uses the $USER variable to read in the username and make it part of both the volume name and mount point name. The
|
|
<emphasis role="bold">uss</emphasis> command issuer supplies a file server machine name for the $1 variable and a partition
|
|
name for the $2 variable, to specify the site for the new volume. <indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>user account</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>user</primary>
|
|
|
|
<secondary>account</secondary>
|
|
|
|
<see>user account</see>
|
|
</indexterm> <indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>creating</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>username</primary>
|
|
|
|
<secondary>assigning</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>Protection Database user entry</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>Authentication Database entry</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>Protection Database</primary>
|
|
|
|
<secondary>user entry</secondary>
|
|
|
|
<tertiary>creating with uss</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>Authentication Database</primary>
|
|
|
|
<secondary>entry</secondary>
|
|
|
|
<tertiary>creating with uss</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>creating individual user account</secondary>
|
|
</indexterm> <indexterm>
|
|
<primary>AFS UID</primary>
|
|
|
|
<secondary>assigning</secondary>
|
|
|
|
<tertiary>with uss</tertiary>
|
|
</indexterm> <indexterm>
|
|
<primary>user</primary>
|
|
|
|
<secondary>AFS UID, assigning</secondary>
|
|
</indexterm></para>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ480">
|
|
<title>Creating Individual Accounts with the uss add Command</title>
|
|
|
|
<para>After you have created a template file, you can create an individual account by issuing the <emphasis role="bold">uss
|
|
add</emphasis> command (for template creation instructions see <link linkend="HDRWQ463">Constructing a uss Template
|
|
File</link>). When you issue the command, the <emphasis role="bold">uss</emphasis> command interpreter contacts various AFS
|
|
servers to perform the following actions: <itemizedlist>
|
|
<listitem>
|
|
<para>Create a Protection Database entry. By default, the Protection Server assigns an AFS UID which becomes the value of
|
|
the $UID variable used in the template.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Create an Authentication Database entry, recording an encrypted version of the initial password.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Create the account components defined in the indicated template file, contacting the File Server, Volume Server, and
|
|
Volume Location (VL) Server as necessary.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>To review which types of instructions to include in a template to create different file system objects, see <link
|
|
linkend="HDRWQ463">Constructing a uss Template File</link>. If the template is empty, the <emphasis role="bold">uss
|
|
add</emphasis> command creates an authentication-only account consisting of Protection Database and Authentication Database
|
|
entries.</para>
|
|
|
|
<para>When you issue the <emphasis role="bold">uss add</emphasis> command, provide a value for each variable in the template
|
|
file by including the corresponding command-line argument. If you fail to supply a value for a variable, the <emphasis
|
|
role="bold">uss</emphasis> command interpreter substitutes a null string, which usually causes the account creation to fail. If
|
|
you include a command line argument for which the corresponding variable does not appear in the template, it is ignored.</para>
|
|
|
|
<para><link linkend="TBLWQ481">Table 4</link> summarizes the mappings between variables and the arguments to the <emphasis
|
|
role="bold">uss add</emphasis> command. It is adapted from <link linkend="TBLWQ466">Table 3</link>, but includes only those
|
|
variables that take their value from command line arguments.</para>
|
|
|
|
<table id="TBLWQ481" label="4">
|
|
<title>Command-line argument sources for uss template variables</title>
|
|
|
|
<tgroup cols="2">
|
|
<colspec colwidth="20*" />
|
|
|
|
<colspec colwidth="80*" />
|
|
|
|
<thead>
|
|
<row>
|
|
<entry><emphasis role="bold">Variable</emphasis></entry>
|
|
|
|
<entry><emphasis role="bold">Command-line Argument</emphasis></entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>$MTPT</entry>
|
|
|
|
<entry><emphasis role="bold">-mount</emphasis> (for occurrence in <emphasis role="bold">V</emphasis>
|
|
instruction)</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$NAME</entry>
|
|
|
|
<entry><emphasis role="bold">-realname</emphasis> if provided; otherwise <emphasis role="bold">-user</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$PART</entry>
|
|
|
|
<entry><emphasis role="bold">-partition</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$PWEXPIRES</entry>
|
|
|
|
<entry><emphasis role="bold">-pwexpires</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$SERVER</entry>
|
|
|
|
<entry><emphasis role="bold">-server</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$UID</entry>
|
|
|
|
<entry><emphasis role="bold">-uid</emphasis> if provided; otherwise allocated by Protection Server</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$USER</entry>
|
|
|
|
<entry><emphasis role="bold">-user</emphasis></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>$1 through $9</entry>
|
|
|
|
<entry><emphasis role="bold">-var</emphasis></entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
|
|
<sect2 id="HDRWQ483">
|
|
<title>To create an AFS account with the uss add command</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the
|
|
<emphasis role="bold">admin</emphasis> 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 <link linkend="HDRWQ584">An Overview of Administrative Privilege</link>.) If
|
|
necessary, issue the <emphasis role="bold">klog</emphasis> command to authenticate. <programlisting>
|
|
% <emphasis role="bold">klog</emphasis> admin_user
|
|
Password: <<replaceable>admin_password</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>The following list specifies the necessary privileges and indicates how to check that you have them.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
|
|
<emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To
|
|
display the members of the system:administrators group</link>. <programlisting>
|
|
% <emphasis role="bold">pts membership system:administrators</emphasis>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue the <emphasis
|
|
role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the
|
|
users in the UserList file</link>. <programlisting>
|
|
% <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <computeroutput>ADMIN</computeroutput> 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 <emphasis role="bold">uss</emphasis> command
|
|
line itself.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <emphasis role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) and <emphasis
|
|
role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permissions on the ACL of the directory in which
|
|
you are mounting the user's volume. If necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which
|
|
is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
|
|
% <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
|
|
role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default also the <emphasis
|
|
role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
|
|
role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">(Optional)</emphasis> Log in as the local superuser <emphasis role="bold">root</emphasis>.
|
|
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 <link linkend="HDRWQ470">About
|
|
Creating Local Disk Directories and Files</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Verify the location and functionality of the template file you are using. For a description of where the <emphasis
|
|
role="bold">uss</emphasis> command interpreter expects to find the template, see <link linkend="HDRWQ468">Where to Place
|
|
Template Files</link>. You can always provide an alternate pathname if you wish. Also note the variables used in the
|
|
template, to be sure that you provide the corresponding arguments on the <emphasis role="bold">uss</emphasis> command
|
|
line.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">(Optional)</emphasis> Change to the directory where the template
|
|
resides. This affects the type of pathname you must type in Step <link linkend="LIWQ485">6</link>. <programlisting>
|
|
% <emphasis role="bold">cd</emphasis> template_directory
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">(Optional)</emphasis> Run the <emphasis role="bold">uss add</emphasis> command with the
|
|
<emphasis role="bold">-dryrun</emphasis> flag to preview the creation of the account. Note any error messages and correct
|
|
the cause before reissuing the command without the <emphasis role="bold">-dryrun</emphasis> flag. The next step describes
|
|
the <emphasis role="bold">uss add</emphasis> command's syntax. For more information on the <emphasis
|
|
role="bold">-dryrun</emphasis> flag, see <link linkend="HDRWQ454">Avoiding and Recovering from Errors and Interrupted
|
|
Operations</link>. <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>add</secondary>
|
|
</indexterm><indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>uss add</secondary>
|
|
</indexterm></para>
|
|
</listitem>
|
|
|
|
<listitem id="LIWQ485">
|
|
<para>Issue the <emphasis role="bold">uss add</emphasis> command to create the account. Enter the
|
|
command on a single line; it appears here on multiple lines only for legibility.</para>
|
|
|
|
<para>The <emphasis role="bold">uss add</emphasis> operation creates an Authentication Database entry. 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 <emphasis
|
|
role="bold">-admin</emphasis> argument to name an identity that has the <computeroutput>ADMIN</computeroutput> flag on its
|
|
Authentication Database entry. To verify that an entry has the flag, issue the <emphasis role="bold">kas
|
|
examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the ADMIN flag is set</link>.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">uss add</emphasis> <emphasis role="bold">-user</emphasis> <<replaceable>login name</replaceable>> <emphasis
|
|
role="bold">-admin</emphasis> <<replaceable>administrator to authenticate</replaceable>> \
|
|
[<emphasis role="bold">-realname</emphasis> <<replaceable>full name in quotes</replaceable>>] [<emphasis
|
|
role="bold">-pass</emphasis> <<replaceable>initial passwd</replaceable>>] \
|
|
[<emphasis role="bold">-pwexpires</emphasis> <<replaceable>password expires in [0..254] days (0 =</replaceable>> never)>] \
|
|
[<emphasis role="bold">-server</emphasis> <<replaceable>FileServer for home volume</replaceable>>] \
|
|
[<emphasis role="bold">-partition</emphasis> <<replaceable>FileServer's disk partition for home volume</replaceable>>] \
|
|
[<emphasis role="bold">-mount</emphasis> <<replaceable>home directory mount point</replaceable>>] \
|
|
[<emphasis role="bold">-uid</emphasis> <<replaceable>uid to assign the user</replaceable>>] \
|
|
[<emphasis role="bold">-template</emphasis> <<replaceable>pathname of template file</replaceable>>] \
|
|
[<emphasis role="bold">-var</emphasis> <<replaceable>auxiliary argument pairs (Numval)</replaceable>>+] [<emphasis
|
|
role="bold">-dryrun</emphasis>] \
|
|
[<emphasis role="bold">-overwrite</emphasis>]
|
|
Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">ad</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">add</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-user</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the user's Authentication Database and Protection Database entries. Because it becomes the username
|
|
(the name under which a user logs in), it must obey the restrictions that many operating systems impose on
|
|
usernames (usually, to contain no more than eight lowercase letters). Also avoid the following characters: colon
|
|
(<emphasis role="bold">:</emphasis>), semicolon (<emphasis role="bold">;</emphasis>), comma (<emphasis
|
|
role="bold">,</emphasis>), at sign (<emphasis role="bold">@</emphasis>), space, newline, and the period (<emphasis
|
|
role="bold">.</emphasis>), which is conventionally used only in special administrative names.</para>
|
|
|
|
<para>This argument provides the value for the $USER variable in the template file. For suggestions on
|
|
standardizing usernames, see <link linkend="HDRWQ58">Choosing Usernames and Naming Other Account
|
|
Components</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-admin</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
|
|
Authentication Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as
|
|
admin_user. Enter the appropriate password as admin_password.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-realname</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the user's actual full name. If it contains spaces or punctuation, surround it with double quotes.
|
|
If you do not provide it, it defaults to the username provided with the <emphasis role="bold">-user</emphasis>
|
|
argument.</para>
|
|
|
|
<para>This argument provides the value for the $NAME variable in the template file. For information about using
|
|
this argument and variable as part of an automated process for creating entries in a local password file such as
|
|
<emphasis role="bold">/etc/passwd</emphasis>, see <link linkend="HDRWQ458">Creating a Common Source Password
|
|
File</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-pass</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>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.</para>
|
|
|
|
<para>Possible choices for initial passwords include the username, a string of digits such as those from a Social
|
|
Security number, or a standard string such as <emphasis role="bold">changeme</emphasis>, which is the default if
|
|
you do not provide this argument. There is no corresponding variable in the template file.</para>
|
|
|
|
<para>Instruct users to change their passwords to a truly secret string as soon as they authenticate with AFS for
|
|
the first time. The <emphasis>OpenAFS User Guide</emphasis> explains how to use the <emphasis
|
|
role="bold">kpasswd</emphasis> command to change an AFS password.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-pwexpires</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Sets the number of days after a user's password is changed that it remains valid. Provide an integer from
|
|
the range <emphasis role="bold">1</emphasis> through <emphasis role="bold">254</emphasis> to specify the number of
|
|
days until expiration, or the value <emphasis role="bold">0</emphasis> to indicate that the password never expires
|
|
(the default if you do not provide this argument). When the password becomes invalid (expires), the user is unable
|
|
to authenticate, but has 30 more days in which to issue the <emphasis role="bold">kpasswd</emphasis> command to
|
|
change the password; after that, only an administrator can change it.</para>
|
|
|
|
<para>This argument provides the value for the $PWEXPIRES variable in the template file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-server</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the file server machine on which to create the new user's home volume. It is best to provide a fully
|
|
qualified hostname (for example, <emphasis role="bold">fs1.abc.com</emphasis>), but an abbreviated form is
|
|
acceptable provided that the cell's naming service is available to resolve it when you issue the <emphasis
|
|
role="bold">uss add</emphasis> command.</para>
|
|
|
|
<para>This argument provides the value for the $SERVER variable in the template file. To avoid having to type a
|
|
fully qualified hostname on the command line, combine the $SERVER variable with a constant (for example, the
|
|
cell's domain name) in the server field of the <emphasis role="bold">V</emphasis> instruction in the template
|
|
file. For an example, see <link linkend="HDRWQ473">Creating a Volume with the V Instruction</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-partition</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the partition on which to create the user's home volume; it must be on the file server machine
|
|
named by the <emphasis role="bold">-server</emphasis> argument. Identify the partition by its complete name (for
|
|
example, <emphasis role="bold">/vicepa</emphasis>), or use one of the abbreviations listed in <link
|
|
linkend="HDRWQ615">Rules for Using Abbreviations and Aliases</link>.</para>
|
|
|
|
<para>This argument provides the value for the $PART variable in the template file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-mount</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the pathname for the user's home directory in the cell's read/write filespace. Partial pathnames
|
|
are interpreted relative to the current working directory.</para>
|
|
|
|
<para>This argument provides the value for the $MTPT variable in the template file, but only when it appears in
|
|
the <emphasis role="bold">V</emphasis> instruction's mount_point field. When the $MTPT variable appears in any
|
|
subsequent instructions, it takes its value from the <emphasis role="bold">V</emphasis> instruction's mount_point
|
|
field, rather than directly from this argument. For more details, and for suggestions about how to use this
|
|
argument and the $MTPT variable, see <link linkend="HDRWQ473">Creating a Volume with the V
|
|
Instruction</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-uid</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies a positive integer other than <emphasis role="bold">0</emphasis> (zero) to assign as the user's
|
|
AFS UID. It is best to omit this argument and allow the Protection Server to assign an AFS UID that is one greater
|
|
than the current value of the <computeroutput>max user id</computeroutput> counter. (To display the counter, use
|
|
the <emphasis role="bold">pts listmax</emphasis> command as described in <link linkend="HDRWQ561">To display the
|
|
AFS ID counters</link>.)</para>
|
|
|
|
<para>If you have a reason to use this argument (perhaps because the user already has a UNIX UID), first use the
|
|
<emphasis role="bold">pts examine</emphasis> command to verify that there is no existing account with the desired
|
|
AFS UID; if there is, the account creation process terminates with an error.</para>
|
|
|
|
<para>This argument provides the value for the $UID variable in the template file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-template</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the pathname of the template file. If you omit this argument, the command interpreter searches for
|
|
a template file called <emphasis role="bold">uss.template</emphasis> in each of the following directories in turn:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The current working directory</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">/afs/</emphasis>cellname<emphasis role="bold">/common/uss</emphasis>, where
|
|
cellname names the local cell</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">/etc</emphasis></para>
|
|
</listitem>
|
|
</orderedlist></para>
|
|
|
|
<para>If you specify a filename other than <emphasis role="bold">uss.template</emphasis> but without a pathname,
|
|
the command interpreter searches for it in the indicated directories. If you provide a full or partial pathname,
|
|
the command interpreter consults the specified file only; it interprets partial pathnames relative to the current
|
|
working directory.</para>
|
|
|
|
<para>If the specified template file is empty (zero-length), the command creates Protection and Authentication
|
|
Database entries only.</para>
|
|
|
|
<para>To learn how to construct a template file, see <link linkend="HDRWQ463">Constructing a uss Template
|
|
File</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-var</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies values for each of the number variables $1 through $9 that can appear in the template file. You
|
|
can use the number variables to assign values to variables in the <emphasis role="bold">uss</emphasis> template
|
|
file that are not part of the standard set.</para>
|
|
|
|
<para>For each instance of this argument, provide two parts in the indicated order, separated by a space:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The integer from the range <emphasis role="bold">1</emphasis> through <emphasis
|
|
role="bold">9</emphasis> that matches the variable in the template file. Do not precede it with a dollar
|
|
sign.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>A string of alphanumeric characters to assign as the value of the variable.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>To learn about suggested uses for the number variables, see the description of the <emphasis
|
|
role="bold">V</emphasis> instruction's quota field in <link linkend="HDRWQ473">Creating a Volume with the V
|
|
Instruction</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-dryrun</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Reports actions that the command interpreter needs to perform to run the command, without actually
|
|
performing them.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-overwrite</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Overwrites any directories, files, and links that exist in the file system and for which there are
|
|
definitions in <emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, <emphasis
|
|
role="bold">F</emphasis>, <emphasis role="bold">L</emphasis>, or <emphasis role="bold">S</emphasis> instructions
|
|
in the template file named by the <emphasis role="bold">-template</emphasis> argument. If you omit this flag, the
|
|
command interpreter prompts you once for confirmation that you want to overwrite all such elements.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the new user home directory resides in a replicated volume, use the <emphasis role="bold">vos release</emphasis>
|
|
command to release the volume, as described in <link linkend="HDRWQ194">To replicate a read/write volume (create a
|
|
read-only volume)</link>. <programlisting>
|
|
% <emphasis role="bold">vos release</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<note>
|
|
<para>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 <emphasis role="bold">/afs/abc.com/usr</emphasis> directory. Because that is a regular
|
|
directory rather than a mount point, it resides in the <emphasis role="bold">root.cell</emphasis> volume mounted at the
|
|
<emphasis role="bold">/afs/abc.com</emphasis> directory. That volume is replicated, so after changing it by creating a
|
|
new mount point the administrator must issue the <emphasis role="bold">vos release</emphasis> command.</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Create an entry for the new user in the local password file (<emphasis role="bold">/etc/passwd</emphasis> or
|
|
equivalent) on each AFS client machine that he or she can log into. For suggestions on automating this step, see <link
|
|
linkend="HDRWQ458">Creating a Common Source Password File</link>.</para>
|
|
|
|
<para>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 <emphasis role="bold">-uid</emphasis> argument. The new user's AFS UID appears
|
|
in the trace produced by the <emphasis role="bold">uss add</emphasis> output, or you can use the <emphasis role="bold">pts
|
|
examine</emphasis> command to display it, as described in <link linkend="HDRWQ537">To display a Protection Database
|
|
entry</link>.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<indexterm>
|
|
<primary>deleting</primary>
|
|
|
|
<secondary>user accounts with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>deleting with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>deleting</primary>
|
|
|
|
<secondary>Protection Database user entry with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>deleting</primary>
|
|
|
|
<secondary>Authentication Database entry with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>Protection Database</primary>
|
|
|
|
<secondary>user entry</secondary>
|
|
|
|
<tertiary>deleting with uss</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>Authentication Database</primary>
|
|
|
|
<secondary>entry</secondary>
|
|
|
|
<tertiary>deleting with uss</tertiary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>deleting individual user account</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ486">
|
|
<title>Deleting Individual Accounts with the uss delete Command</title>
|
|
|
|
<para>The <emphasis role="bold">uss delete</emphasis> command deletes an AFS user account according to the arguments you provide
|
|
on the command line; unlike the <emphasis role="bold">uss add</emphasis> command, it does not use a template file. When you
|
|
issue the command, the <emphasis role="bold">uss</emphasis> command interpreter contacts various AFS servers to perform the
|
|
following actions: <itemizedlist>
|
|
<listitem>
|
|
<para>Remove the mount point for the user's home volume</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Remove the user's home volume and delete the associated VLDB entry, unless you include the <emphasis
|
|
role="bold">-savevolume</emphasis> flag</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Delete the user's Authentication Database entry</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Delete the user's Protection Database entry</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>Before issuing the <emphasis role="bold">uss delete</emphasis> command, you can also perform the following optional tasks:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Copy the user's home volume to tape or another permanent medium and record the username and UID on a reserved list.
|
|
This information enables you to restore the user's account easily if he or she returns to your cell. For information about
|
|
using the AFS Backup System to back up volumes, see <link linkend="HDRWQ248">Configuring the AFS Backup System</link> and
|
|
<link linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the user has exclusive use of any other volumes (such as a volume for storing project-related data), make a
|
|
backup copy of each one and then remove it and its mount point as instructed in <link linkend="HDRWQ235">Removing Volumes
|
|
and their Mount Points</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Use the <emphasis role="bold">pts listowned</emphasis> command to display any groups that the user owns;
|
|
instructions appear in <link linkend="HDRWQ540">To list the groups that a user or group owns</link>. Decide whether to use
|
|
the <emphasis role="bold">pts delete</emphasis> command to remove the groups or the <emphasis role="bold">pts
|
|
chown</emphasis> command to transfer ownership to another user or group. Instructions appear in <link
|
|
linkend="HDRWQ553">To delete Protection Database entries</link> and <link linkend="HDRWQ555">To change a group's
|
|
owner</link>. Alternatively, you can have the user remove or transfer ownership of the groups before leaving. A group that
|
|
remains in the Protection Database after its owner is removed is considered orphaned, and only members of the <emphasis
|
|
role="bold">system:administrators</emphasis> group can administer it.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para>You can automate some of these tasks by including <emphasis role="bold">exec</emphasis> instructions in the bulk input
|
|
file and using the <emphasis role="bold">uss bulk</emphasis> command to delete the account. See <link
|
|
linkend="HDRWQ488">Creating and Deleting Multiple Accounts with the uss bulk Command</link>.</para>
|
|
|
|
<sect2 id="HDRWQ487">
|
|
<title>To delete an AFS account</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the
|
|
<emphasis role="bold">admin</emphasis> 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 <link linkend="HDRWQ584">An Overview of Administrative Privilege</link>.) If
|
|
necessary, issue the <emphasis role="bold">klog</emphasis> command to authenticate. <programlisting>
|
|
% <emphasis role="bold">klog</emphasis> admin_user
|
|
Password: <<replaceable>admin_password</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>The following list specifies the necessary privileges and indicates how to check that you have them.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
|
|
<emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To
|
|
display the members of the system:administrators group</link>. <programlisting>
|
|
% <emphasis role="bold">pts membership system:administrators</emphasis>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue the <emphasis
|
|
role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the
|
|
users in the UserList file</link>. <programlisting>
|
|
% <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <computeroutput>ADMIN</computeroutput> 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 <emphasis role="bold">uss</emphasis> command
|
|
line itself.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>) permission on the ACL of the
|
|
directory that houses the user's home directory. If necessary, issue the <emphasis role="bold">fs listacl</emphasis>
|
|
command, which is fully described in <link linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
|
|
% <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
|
|
role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default also the <emphasis
|
|
role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
|
|
role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Consider and resolve the issues discussed in the introduction to this section concerning the continued maintenance
|
|
of a deleted user's account information, owned groups, and volumes.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">(Optional)</emphasis> Run the <emphasis role="bold">uss delete</emphasis> command with the
|
|
<emphasis role="bold">-dryrun</emphasis> flag to preview the deletion of the account. Note any error messages and correct
|
|
the cause before reissuing the command without the <emphasis role="bold">-dryrun</emphasis> flag. The next step describes
|
|
the <emphasis role="bold">uss delete</emphasis> command's syntax. <indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>delete</secondary>
|
|
</indexterm><indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>uss delete</secondary>
|
|
</indexterm></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">uss delete</emphasis> command to delete the account. Enter the command on a single
|
|
line; it appears here on multiple lines only for legibility.</para>
|
|
|
|
<para>The delete operation always removes the user's entry from 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 <emphasis
|
|
role="bold">-admin</emphasis> argument to name an identity that has the <computeroutput>ADMIN</computeroutput> flag on its
|
|
Authentication Database entry. To verify that an entry has the flag, issue the <emphasis role="bold">kas
|
|
examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the ADMIN flag is set</link>.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">uss delete</emphasis> <emphasis role="bold">-user</emphasis> <<replaceable>login name</replaceable>> \
|
|
<emphasis role="bold">-mountpoint</emphasis> <<replaceable>mountpoint for user's volume</replaceable>> \
|
|
[<emphasis role="bold">-savevolume</emphasis>] <emphasis role="bold">-admin</emphasis> <<replaceable>administrator to authenticate</replaceable>> \
|
|
[<emphasis role="bold">-dryrun</emphasis>]
|
|
Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">d</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">delete</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-user</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names the entry to delete from the Protection and Authentication Databases.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-mountpoint</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the pathname of the mount point to delete (the user's home directory). Unless the <emphasis
|
|
role="bold">-savevolume</emphasis> argument is included, the volume mounted there is also deleted from the file
|
|
server machine where it resides, as is its record from the VLDB. Partial pathnames are interpreted relative to the
|
|
current working directory.</para>
|
|
|
|
<para>Specify the read/write path to the mount point, to avoid the failure that results when you attempt to delete
|
|
a mount point from a read-only volume. By convention, you indicate the read/write path by placing a period before
|
|
the cell name at the pathname's second level (for example, <emphasis role="bold">/afs/.abc.com</emphasis>). For
|
|
further discussion of the concept of read/write and read-only paths through the filespace, see <link
|
|
linkend="HDRWQ208">Mounting Volumes</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-savevolume</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Retains the user's volume and VLDB entry.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-admin</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
|
|
Authentication Database entry, such as <emphasis role="bold">admin</emphasis>. The password prompt echoes it as
|
|
admin_user. Enter the appropriate password as admin_password.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-dryrun</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Reports actions that the command interpreter needs to perform to run the command, without actually
|
|
performing them.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the deleted user home directory resided in a replicated volume, use the <emphasis role="bold">vos
|
|
release</emphasis> command to release the volume, as described in <link linkend="HDRWQ194">To replicate a read/write
|
|
volume (create a read-only volume)</link>. <programlisting>
|
|
% <emphasis role="bold">vos release</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<note>
|
|
<para>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 <emphasis role="bold">/afs/abc.com/usr</emphasis> directory. Because that is a regular
|
|
directory rather than a mount point, it resides in the <emphasis role="bold">root.cell</emphasis> volume mounted at the
|
|
<emphasis role="bold">/afs/abc.com</emphasis> directory. That volume is replicated, so after changing it by deleting a
|
|
mount point the administrator must issue the <emphasis role="bold">vos release</emphasis> command.</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Delete the user's entry from the local password file (<emphasis role="bold">/etc/passwd</emphasis> or equivalent) of
|
|
each client machine. If you use the AFS <emphasis role="bold">package</emphasis> 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.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<indexterm>
|
|
<primary>creating</primary>
|
|
|
|
<secondary>user accounts in bulk with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>user account</primary>
|
|
|
|
<secondary>creating/deleting many at once</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>bulk mode in uss</primary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>deleting</primary>
|
|
|
|
<secondary>user accounts in bulk with uss</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>creating/deleting user accounts in bulk</secondary>
|
|
</indexterm>
|
|
</sect2>
|
|
</sect1>
|
|
|
|
<sect1 id="HDRWQ488">
|
|
<title>Creating and Deleting Multiple Accounts with the uss bulk Command</title>
|
|
|
|
<para>The <emphasis role="bold">uss bulk</emphasis> command allows you to create and delete many accounts at once. Before
|
|
executing the command, you must <itemizedlist>
|
|
<listitem>
|
|
<para>Construct a template if you plan to create any accounts, just as you must do before running the <emphasis
|
|
role="bold">uss add</emphasis> command. The same template applies to all accounts created by a single <emphasis
|
|
role="bold">uss bulk</emphasis> command.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Construct a bulk input file of instructions that create and delete accounts and execute any related commands, as
|
|
described in <link linkend="HDRWQ489">Constructing a Bulk Input File</link>.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<indexterm>
|
|
<primary>rules</primary>
|
|
|
|
<secondary>for uss bulk input file</secondary>
|
|
</indexterm>
|
|
|
|
<indexterm>
|
|
<primary>uss bulk input file</primary>
|
|
|
|
<secondary>rules for constructing</secondary>
|
|
</indexterm>
|
|
|
|
<sect2 id="HDRWQ489">
|
|
<title>Constructing a Bulk Input File</title>
|
|
|
|
<para>You can include five types of instructions in a bulk input file: <emphasis role="bold">add</emphasis>, <emphasis
|
|
role="bold">delete</emphasis>, <emphasis role="bold">exec</emphasis>, <emphasis role="bold">savevolume</emphasis>, and
|
|
<emphasis role="bold">delvolume</emphasis>. The following sections discuss their uses.</para>
|
|
|
|
<para><emphasis role="bold">Creating a User Account with the add Instruction</emphasis></para>
|
|
|
|
<para>Each <emphasis role="bold">add</emphasis> instruction creates a single user account, and so is basically the equivalent
|
|
of issuing one <emphasis role="bold">uss add</emphasis> command. There is no limit to the number of <emphasis
|
|
role="bold">add</emphasis> instructions in the bulk input file.</para>
|
|
|
|
<para>As indicated by the following syntax statement, the order of the instruction's fields matches the order of arguments to
|
|
the <emphasis role="bold">uss add</emphasis> command (though some of the command's arguments do not have a corresponding
|
|
field). Like the <emphasis role="bold">uss add</emphasis> command's arguments, many of the fields provide a value for a
|
|
variable in the <emphasis role="bold">uss</emphasis> 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.</para>
|
|
|
|
<programlisting><emphasis role="bold">add</emphasis> username[<emphasis role="bold">:</emphasis>full_name][<emphasis
|
|
role="bold">:</emphasis>initial_password][<emphasis role="bold">:</emphasis>password_expires]
|
|
[<emphasis role="bold">:</emphasis>file_server][<emphasis role="bold">:</emphasis>partition][<emphasis role="bold">:</emphasis>mount_point][<emphasis
|
|
role="bold">:</emphasis>uid]
|
|
[<emphasis role="bold">:</emphasis>var1][<emphasis role="bold">:</emphasis>var2][<emphasis role="bold">:</emphasis>var3][<emphasis
|
|
role="bold">:</emphasis>var4][<emphasis role="bold">:</emphasis>var5][<emphasis role="bold">:</emphasis>var6][<emphasis
|
|
role="bold">:</emphasis>var7][<emphasis role="bold">:</emphasis>var8][<emphasis role="bold">:</emphasis>var9][<emphasis
|
|
role="bold">:</emphasis>]
|
|
</programlisting>
|
|
|
|
<para>For a complete description of the acceptable values in each field, see the <emphasis role="bold">uss Bulk Input
|
|
File</emphasis> reference page in the <emphasis>OpenAFS Administration Reference</emphasis>, or the description of the
|
|
corresponding arguments to the <emphasis role="bold">uss add</emphasis> command, in <link linkend="HDRWQ483">To create an AFS
|
|
account with the uss add command</link>. Following are some basic notes: <itemizedlist>
|
|
<listitem>
|
|
<para>Begin the line with the string <emphasis role="bold">add</emphasis> only, not <emphasis role="bold">uss
|
|
add</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Only the first argument, username, is required. It corresponds to the <emphasis role="bold">-user</emphasis>
|
|
argument to the <emphasis role="bold">uss add</emphasis> command.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Do not surround the full_name value with double quotes, even though you must use them around the value for the
|
|
<emphasis role="bold">-realname</emphasis> argument to the <emphasis role="bold">uss add</emphasis> command.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>After the last field, end the line with either a colon and newline character (<emphasis
|
|
role="bold"><Return></emphasis>), or a newline alone.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>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.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para><emphasis role="bold">Deleting a User Account with the delete Instruction</emphasis></para>
|
|
|
|
<para>Each <emphasis role="bold">delete</emphasis> instruction deletes a single user account, and so is basically the
|
|
equivalent of issuing one <emphasis role="bold">uss delete</emphasis> command. There is no limit to the number of <emphasis
|
|
role="bold">delete</emphasis> instructions in the bulk input file.</para>
|
|
|
|
<para>Like all instructions in the bulk input file, each <emphasis role="bold">delete</emphasis> 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 (<emphasis role="bold">{ }</emphasis>) indicate two mutually exclusive choices.</para>
|
|
|
|
<programlisting><emphasis role="bold">delete</emphasis> username<emphasis role="bold">:</emphasis>mount_point_path[:{ <emphasis
|
|
role="bold">savevolume</emphasis> | <emphasis role="bold">delvolume</emphasis> }][<emphasis role="bold">:</emphasis>]
|
|
</programlisting>
|
|
|
|
<para>For a complete description of the acceptable values in each field, see the <emphasis role="bold">uss Bulk Input
|
|
File</emphasis> reference page in the <emphasis>OpenAFS Administration Reference</emphasis> or the description of the
|
|
corresponding arguments to the <emphasis role="bold">uss delete</emphasis> command, in <link linkend="HDRWQ487">To delete an
|
|
AFS account</link>. Following are some basic notes: <itemizedlist>
|
|
<listitem>
|
|
<para>Begin the line with the string <emphasis role="bold">delete</emphasis> only, not <emphasis role="bold">uss
|
|
delete</emphasis>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The first two arguments, username and mount_point_path, are required. They correspond to the <emphasis
|
|
role="bold">-user</emphasis> and <emphasis role="bold">-mountpoint</emphasis> arguments to the <emphasis role="bold">uss
|
|
delete</emphasis> command.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>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: <itemizedlist>
|
|
<listitem>
|
|
<para>No value treats the volume and VLDB entry according to the prevailing default, which is established by a
|
|
preceding <emphasis role="bold">savevolume</emphasis> or <emphasis role="bold">delvolume</emphasis> instruction in
|
|
the template file. See the following discussion of those instructions to learn how the default is set.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The string <emphasis role="bold">savevolume</emphasis> preserves the volume and VLDB entry, overriding the
|
|
default.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The string <emphasis role="bold">delvolume</emphasis> removes the volume and VLDB entry, overriding the
|
|
default.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>After the last field, end the line with either a colon and newline character (<emphasis
|
|
role="bold"><Return></emphasis>), or a newline alone.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
|
|
<para><emphasis role="bold">Running a Command or Script with the exec Instruction</emphasis></para>
|
|
|
|
<para>The <emphasis role="bold">exec</emphasis> 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 <emphasis role="bold">uss
|
|
bulk</emphasis> command, who must have the privileges required to run the command.</para>
|
|
|
|
<para>The instruction's syntax is as follows:</para>
|
|
|
|
<programlisting><emphasis role="bold">exec</emphasis> command
|
|
</programlisting>
|
|
|
|
<para>It is not necessary to surround the command string with double quotes (" ") or other delimiters.</para>
|
|
|
|
<para><emphasis role="bold">Setting the Default Treatment of Volumes with the delvolume and savevolume
|
|
Instructions</emphasis></para>
|
|
|
|
<para>The <emphasis role="bold">savevolume</emphasis> and <emphasis role="bold">delvolume</emphasis> instructions set the
|
|
default treatment of volumes referenced by the <emphasis role="bold">delete</emphasis> instructions that follow them in the
|
|
bulk input file. Their syntax is as follows:</para>
|
|
|
|
<programlisting>
|
|
<emphasis role="bold">savevolume</emphasis>
|
|
<emphasis role="bold">delvolume</emphasis>
|
|
</programlisting>
|
|
|
|
<para>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 <emphasis role="bold">delete</emphasis> instructions are removed. If the <emphasis
|
|
role="bold">savevolume</emphasis> instruction appears in the file, it prevents the removal of the volume and VLDB entry
|
|
referenced by all subsequent <emphasis role="bold">delete</emphasis> instructions in the file. The <emphasis
|
|
role="bold">delvolume</emphasis> instruction explicitly establishes the default (which is deletion) for subsequent <emphasis
|
|
role="bold">delete</emphasis> instructions.</para>
|
|
|
|
<para>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 <emphasis role="bold">delete</emphasis> instruction, put the <emphasis
|
|
role="bold">savevolume</emphasis> or <emphasis role="bold">delvolume</emphasis> string in the instruction's third field. (You
|
|
can also use multiple instances of the <emphasis role="bold">savevolume</emphasis> and <emphasis
|
|
role="bold">delvolume</emphasis> instructions to toggle back and forth between default preservation and deletion of
|
|
volumes.)</para>
|
|
</sect2>
|
|
|
|
<sect2 id="Header_570">
|
|
<title>Example Bulk Input File Instructions</title>
|
|
|
|
<para>To create an authentication-only account, use an <emphasis role="bold">add</emphasis> instruction like the following
|
|
example, which includes only the first (username) argument. The user's real name is set to match the username (<emphasis
|
|
role="bold">anderson</emphasis>) and her initial password is set to the string <emphasis
|
|
role="bold">changeme</emphasis>.</para>
|
|
|
|
<programlisting>
|
|
add anderson
|
|
</programlisting>
|
|
|
|
<para>The following example also creates an authentication-only account, but sets nondefault values for the real name and
|
|
initial password.</para>
|
|
|
|
<programlisting>
|
|
add smith:John Smith:js_pswd
|
|
</programlisting>
|
|
|
|
<para>The next two example <emphasis role="bold">add</emphasis> instructions require that the administrator of the ABC
|
|
Corporation cell (<emphasis role="bold">abc.com</emphasis>) has written a <emphasis role="bold">uss</emphasis> template file
|
|
with the following <emphasis role="bold">V</emphasis> instruction in it:</para>
|
|
|
|
<programlisting>
|
|
V user.$USER $SERVER.abc.com /vicep$PART 10000 /afs/.abc.com/usr/$3/$USER \
|
|
$UID $USER all
|
|
</programlisting>
|
|
|
|
<para>To create accounts for users named John Smith from the Marketing Department and Pat Jones from the Finance Department,
|
|
the appropriate <emphasis role="bold">add</emphasis> instructions in the bulk input file are as follows:</para>
|
|
|
|
<programlisting>
|
|
add smith:John Smith:::fs1:a:::::marketing
|
|
add jones:Pat Jones:::fs3:c:::::finance
|
|
</programlisting>
|
|
|
|
<para>The new account for Smith consists of Protection and Authentication Database entries called <emphasis
|
|
role="bold">smith</emphasis>. His initial password is the default string <emphasis role="bold">changeme</emphasis>, and the
|
|
Protection Server generates his AFS UID. His home volume, called <emphasis role="bold">user.smith</emphasis>, has a 10,000 KB
|
|
quota, resides on partition <emphasis role="bold">/vicepa</emphasis> of file server machine <emphasis
|
|
role="bold">fs1.abc.com</emphasis>, and is mounted at <emphasis role="bold">/afs/.abc.com/usr/marketing/smith</emphasis>. The
|
|
final <emphasis role="bold">$UID $USER all</emphasis> part of the <emphasis role="bold">V</emphasis> instruction gives him
|
|
ownership of his home directory and all permissions on its ACL. The account for <emphasis role="bold">jones</emphasis> is
|
|
similar, except that it resides on partition <emphasis role="bold">/vicepc</emphasis> of file server machine <emphasis
|
|
role="bold">fs3.abc.com</emphasis> and is mounted at <emphasis role="bold">/afs/.abc.com/usr/finance/jones</emphasis>.</para>
|
|
|
|
<para>Notice that the fields corresponding to mount_point, uid, var1, and var2 are empty (between the values
|
|
<computeroutput>a</computeroutput> and <computeroutput>marketing</computeroutput> on the first example line) because the
|
|
corresponding variables do not appear in the <emphasis role="bold">V</emphasis> instruction in the template file. The
|
|
initial_passwd and password_expires fields are also empty.</para>
|
|
|
|
<para>If you wish, you can specify values or empty fields for all nine number variables in an <emphasis
|
|
role="bold">add</emphasis> instruction. In that case, the bulk input file instructions are as follows:</para>
|
|
|
|
<programlisting>
|
|
add smith:John Smith:::fs1:a:::::marketing::::::
|
|
add jones:Pat Jones:::fs3:c:::::finance::::::
|
|
</programlisting>
|
|
|
|
<para>The following example is a section of a bulk input file with a number of <emphasis role="bold">delete</emphasis>
|
|
instructions and a <emphasis role="bold">savevolume</emphasis> instruction. Because the first three instructions appear before
|
|
the <emphasis role="bold">savevolume</emphasis> instruction and their third field is blank, the corresponding volumes and VLDB
|
|
entries are removed. The <emphasis role="bold">delete</emphasis> instruction for user <emphasis role="bold">terry</emphasis>
|
|
follows the <emphasis role="bold">savevolume</emphasis> instruction, so her volume is not removed, but the volume for user
|
|
<emphasis role="bold">johnson</emphasis> is, because the <emphasis role="bold">delvolume</emphasis> string in the third field
|
|
of the <emphasis role="bold">delete</emphasis> instruction overrides the current default.</para>
|
|
|
|
<programlisting>
|
|
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
|
|
</programlisting>
|
|
|
|
<para>The following example <emphasis role="bold">exec</emphasis> instruction is useful as a separator between a set of
|
|
<emphasis role="bold">add</emphasis> instructions and a set of <emphasis role="bold">delete</emphasis> instructions. It
|
|
generates a message on the standard output stream that informs you of the <emphasis role="bold">uss bulk</emphasis> command's
|
|
progress.</para>
|
|
|
|
<programlisting>
|
|
exec echo "Additions completed; beginning deletions..."
|
|
</programlisting>
|
|
</sect2>
|
|
|
|
<sect2 id="Header_571">
|
|
<title>To create and delete multiple AFS user accounts</title>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Authenticate as an AFS identity with all of the following privileges. In the conventional configuration, the
|
|
<emphasis role="bold">admin</emphasis> 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 <link linkend="HDRWQ584">An Overview of Administrative Privilege</link>.) If
|
|
necessary, issue the <emphasis role="bold">klog</emphasis> command to authenticate. <programlisting>
|
|
% <emphasis role="bold">klog</emphasis> admin_user
|
|
Password: <<replaceable>admin_password</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<para>The following list specifies the necessary privileges and indicates how to check that you have them.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Membership in the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
|
|
<emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To
|
|
display the members of the system:administrators group</link>. <programlisting>
|
|
% <emphasis role="bold">pts membership system:administrators</emphasis>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Inclusion in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If necessary, issue the <emphasis
|
|
role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the
|
|
users in the UserList file</link>. <programlisting>
|
|
% <emphasis role="bold">bos listusers</emphasis> <<replaceable>machine name</replaceable>>
|
|
</programlisting></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <computeroutput>ADMIN</computeroutput> 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 <emphasis role="bold">uss</emphasis> command
|
|
line itself.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>), <emphasis
|
|
role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>) and <emphasis role="bold">l</emphasis> (<emphasis
|
|
role="bold">lookup</emphasis>) permissions on the ACL of the parent directory for each volume mount point. If
|
|
necessary, issue the <emphasis role="bold">fs listacl</emphasis> command, which is fully described in <link
|
|
linkend="HDRWQ572">Displaying ACLs</link>. <programlisting>
|
|
% <emphasis role="bold">fs listacl</emphasis> [<<replaceable>dir/file path</replaceable>>]
|
|
</programlisting></para>
|
|
|
|
<para>Members of the <emphasis role="bold">system:administrators</emphasis> group always implicitly have the <emphasis
|
|
role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default also the <emphasis
|
|
role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permission on every ACL and can use the <emphasis
|
|
role="bold">fs setacl</emphasis> command to grant other rights as necessary.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">(Optional.)</emphasis> Log in as the local superuser <emphasis role="bold">root</emphasis>.
|
|
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 <link linkend="HDRWQ470">About
|
|
Creating Local Disk Directories and Files</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the bulk input file includes <emphasis role="bold">add</emphasis> instructions, verify the location and
|
|
functionality of the template you are using. For a description of where the <emphasis role="bold">uss</emphasis> command
|
|
interpreter expects to find the template, see <link linkend="HDRWQ468">Where to Place Template Files</link>. 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 <emphasis role="bold">add</emphasis> instruction or on the <emphasis
|
|
role="bold">uss bulk</emphasis> command line.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Create a bulk input file that complies with the rules listed in <link linkend="HDRWQ489">Constructing a Bulk Input
|
|
File</link>. It is simplest to put the file in the same directory as the template file you are using.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis role="bold">(Optional.)</emphasis> Change to the directory where the bulk input file and template file
|
|
reside. <programlisting>
|
|
% <emphasis role="bold">cd</emphasis> template_directory
|
|
</programlisting><indexterm>
|
|
<primary>uss commands</primary>
|
|
|
|
<secondary>bulk</secondary>
|
|
</indexterm><indexterm>
|
|
<primary>commands</primary>
|
|
|
|
<secondary>uss bulk</secondary>
|
|
</indexterm></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Issue the <emphasis role="bold">uss bulk</emphasis> command to create or delete accounts, or
|
|
both. Enter the command on a single line; it appears here on multiple lines only for legibility.</para>
|
|
|
|
<para>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 <emphasis
|
|
role="bold">-admin</emphasis> argument to name an identity that has the <computeroutput>ADMIN</computeroutput> flag on its
|
|
Authentication Database entry. To verify that an entry has the flag, issue the <emphasis role="bold">kas
|
|
examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the ADMIN flag is set</link>.</para>
|
|
|
|
<programlisting>
|
|
% <emphasis role="bold">uss bulk</emphasis> <<replaceable>bulk input file</replaceable>> \
|
|
[<emphasis role="bold">-template</emphasis> <<replaceable>pathname of template file</replaceable>>] \
|
|
<emphasis role="bold">-admin</emphasis> <<replaceable>administrator to authenticate</replaceable>> \
|
|
[<emphasis role="bold">-dryrun</emphasis>] [<emphasis role="bold">-overwrite</emphasis>] \
|
|
[<emphasis role="bold">-pwexpires</emphasis> <<replaceable>password expires in [0..254] days (0 =</replaceable>> never)>] \
|
|
[<emphasis role="bold">-pipe</emphasis>]
|
|
Administrator's (admin_user) password: <<replaceable>admin_password</replaceable>>
|
|
</programlisting>
|
|
|
|
<para>where <variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">b</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Is the shortest acceptable abbreviation of <emphasis role="bold">bulk</emphasis>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">bulk input file</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>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 <link linkend="HDRWQ489">Constructing a Bulk
|
|
Input File</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-template</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Specifies the pathname of the template file for any <emphasis role="bold">uss add</emphasis> 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 <link linkend="HDRWQ463">Constructing a uss Template
|
|
File</link>.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-admin</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Names an administrative account that has the <computeroutput>ADMIN</computeroutput> flag on its
|
|
Authentication Database entry, such as the <emphasis role="bold">admin</emphasis> account. The password prompt
|
|
echoes it as admin_user. Enter the appropriate password as admin_password.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-dryrun</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Reports actions that the command interpreter needs to perform to run the command, without actually
|
|
performing them.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-overwrite</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Overwrites any directories, files and links that exist in the file system and for which there are also
|
|
<emphasis role="bold">D</emphasis>, <emphasis role="bold">E</emphasis>, <emphasis role="bold">F</emphasis>,
|
|
<emphasis role="bold">L</emphasis>, or <emphasis role="bold">S</emphasis> instructions in the template file named
|
|
by the <emphasis role="bold">-template</emphasis> argument. If this flag is omitted, the command interpreter
|
|
prompts, once for each <emphasis role="bold">add</emphasis> instruction in the bulk input file, for confirmation
|
|
that it is to overwrite such elements. Do not include this flag if there are no <emphasis
|
|
role="bold">add</emphasis> instructions in the bulk input file.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-pwexpires</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Sets the number of days after a user's password is changed that it remains valid, for each user named by an
|
|
<emphasis role="bold">add</emphasis> instruction in the bulk input file. Provide an integer from the range
|
|
<emphasis role="bold">1</emphasis> through <emphasis role="bold">254</emphasis> to specify the number of days
|
|
until expiration, or the value <emphasis role="bold">0</emphasis> to indicate that the password never expires (the
|
|
default).</para>
|
|
|
|
<para>When the password becomes invalid (expires), the user is unable to authenticate, but has 30 more days in
|
|
which to issue the <emphasis role="bold">kpasswd</emphasis> command to change the password (after that, only an
|
|
administrator can change it).</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">-pipe</emphasis></term>
|
|
|
|
<listitem>
|
|
<para>Suppresses the Authentication Server's prompt for the password of the issuer or the user named by the
|
|
<emphasis role="bold">-admin</emphasis> 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 <emphasis role="bold">uss
|
|
bulk</emphasis> command in unattended batch jobs.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If a newly created or deleted user home directory resides in a replicated volume, use the <emphasis role="bold">vos
|
|
release</emphasis> command to release the volume, as described in <link linkend="HDRWQ194">To replicate a read/write
|
|
volume (create a read-only volume)</link>. <programlisting>
|
|
% <emphasis role="bold">vos release</emphasis> <<replaceable>volume name or ID</replaceable>>
|
|
</programlisting></para>
|
|
|
|
<note>
|
|
<para>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 <emphasis role="bold">/afs/abc.com/usr</emphasis> directory. Because that is a regular
|
|
directory rather than a mount point, it resides in the <emphasis role="bold">root.cell</emphasis> volume mounted at the
|
|
<emphasis role="bold">/afs/abc.com</emphasis> directory. That volume is replicated, so after changing it by creating or
|
|
deleting a mount point, the administrator must issue the <emphasis role="bold">vos release</emphasis> command.</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you are creating accounts, create an entry for the new user in the local password file (<emphasis
|
|
role="bold">/etc/passwd</emphasis> or equivalent) on each AFS client machine that he or she can log into. For suggestions
|
|
on automating this step, see <link linkend="HDRWQ458">Creating a Common Source Password File</link>.</para>
|
|
|
|
<para>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 <emphasis role="bold">-uid</emphasis> argument. The new user's AFS UID appears
|
|
in the trace produced by the <emphasis role="bold">uss add</emphasis> output or you can use the <emphasis role="bold">pts
|
|
examine</emphasis> command to display it, as described in <link linkend="HDRWQ537">To display a Protection Database
|
|
entry</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you are deleting accounts, delete the user's entry from the local password file (<emphasis
|
|
role="bold">/etc/passwd</emphasis> or equivalent) of each client machine. If you use the AFS <emphasis
|
|
role="bold">package</emphasis> 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.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|