mirror of
https://git.openafs.org/openafs.git
synced 2025-01-18 23:10:58 +00:00
1cc8feb6fc
There were several different real and made-up hostnames and company names used throughout our documentation examples. The IETF has reserved "example.com" and other "example" TLDs for use in examples (RFC 2606). Replace almost all references to ABC Corporation, DEF Corporation, and State University, as well as "abc.com", "bigcell.com", "def.com", "def.gov", "ghi.com", "ghi.gov", "jkl.com", "mit.edu", "stanford.edu", "state.edu", "stateu.edu", "uncc.edu", and "xyz.com". Standardize on "Example Corporation", "Example Network", "Example Organization" (example.com, example.net, and example.org). The Scout documentation in the Admin Guide contains PNG images that contain the old cell names, so I left those references until the images can be replaced. Change-Id: I4e44815b2d2ffe204810b7fd850842248f67c367 Reviewed-on: http://gerrit.openafs.org/6697 Reviewed-by: Jeffrey Altman <jaltman@secure-endpoints.com> Tested-by: Jeffrey Altman <jaltman@secure-endpoints.com>
335 lines
21 KiB
XML
335 lines
21 KiB
XML
<?xml version="1.0" encoding="utf-8"?>
|
|
<appendix id="HDRWQ86"><title>OpenAFS Command Syntax and Online Help</title>
|
|
|
|
<para>
|
|
<indexterm><primary>syntax of AFS commands described</primary></indexterm>
|
|
|
|
The AFS commands available to you are used to authenticate, list AFS information, protect directories, create
|
|
and manage groups, and create and manage ACLs. There are three general types of commands available to all AFS
|
|
users: file server commands, protection server commands, and miscellaneous commands. This chapter discusses the
|
|
syntax of these AFS commands, the rules that must be followed when issuing them, and ways of accessing help
|
|
relevant to them.</para>
|
|
<sect1 id="HDRWQ87"><title>OpenAFS Command Syntax</title>
|
|
<para>
|
|
<indexterm><primary>commands</primary><secondary>syntax for AFS</secondary></indexterm>
|
|
Most AFS commands use the following syntax:</para>
|
|
<programlisting>
|
|
<emphasis role="bold">command_suite operation_code -switch</emphasis> <<replaceable>value</replaceable>><superscript>[+]</superscript> <emphasis role="bold">-flag</emphasis>
|
|
</programlisting>
|
|
<para>The <emphasis>command suite</emphasis> indicates the general type of command and the server process that
|
|
performs the command. Regular AFS users have access to two main command suites and a miscellaneous set of commands:
|
|
|
|
<indexterm><primary>commands</primary><secondary>suite organization for AFS</secondary></indexterm>
|
|
|
|
<indexterm><primary>suite, defined for AFS command</primary></indexterm>
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem><para>The <emphasis role="bold">fs</emphasis> command suite is used to issue file server commands that
|
|
interact with the File Server process.</para></listitem>
|
|
<listitem><para>The <emphasis role="bold">pts</emphasis> command suite is used to issue protection-related
|
|
commands.</para></listitem>
|
|
<listitem><para>The miscellaneous commands are not associated with any command suite.</para></listitem>
|
|
</itemizedlist>
|
|
<para>The <emphasis>operation code</emphasis> indicates the action that the command performs. Miscellaneous
|
|
commands have operation codes only.
|
|
<indexterm><primary>operation codes in AFS commands</primary><secondary>defined</secondary></indexterm>
|
|
</para>
|
|
<para>A command can have multiple <emphasis>options</emphasis>, which can be <emphasis>arguments</emphasis> or
|
|
<emphasis>flags</emphasis>:</para>
|
|
<itemizedlist>
|
|
<listitem><para>Arguments are used to supply additional information for use by the command.
|
|
|
|
<indexterm><primary>arguments to AFS commands</primary></indexterm>
|
|
They consist of a paired <emphasis>switch</emphasis> and <emphasis>instance</emphasis>.
|
|
|
|
<indexterm><primary>switches on AFS commands</primary><secondary>defined</secondary></indexterm>
|
|
|
|
<indexterm><primary>instances to AFS commands</primary></indexterm>
|
|
A switch defines the type of argument and is always preceded
|
|
by a hyphen; arguments can take multiple instances if a plus sign (+) appears after the instance. An instance
|
|
represents some variable piece of information that is used by the command. Arguments can be optional or
|
|
required.</para></listitem>
|
|
<listitem><para>Flags are used to direct a command to perform in a specific way (for example, to generate a
|
|
specific type of output).
|
|
<indexterm><primary>flags on AFS commands</primary></indexterm>
|
|
Flags are always preceded by a hyphen and are always
|
|
optional.</para></listitem>
|
|
</itemizedlist>
|
|
<sect2 id="Header_169"><title>Command Syntax Example</title>
|
|
<para>In the following AFS command</para>
|
|
<programlisting>
|
|
% <emphasis role="bold">fs setacl -dir $HOME -acl pat all terry none -negative</emphasis>
|
|
</programlisting>
|
|
<itemizedlist>
|
|
<listitem><para><emphasis role="bold">fs</emphasis> is the command suite.</para></listitem>
|
|
<listitem><para><emphasis role="bold">setacl</emphasis> is the <emphasis>operation code</emphasis>, which directs
|
|
the File Server process to set an access control list.</para></listitem>
|
|
<listitem><para>
|
|
<emphasis role="bold">-dir $HOME</emphasis> and <emphasis role="bold">-acl pat all terry none</emphasis> are
|
|
<emphasis>arguments</emphasis>.
|
|
</para><itemizedlist>
|
|
<listitem><para><emphasis role="bold">-dir</emphasis> and <emphasis role="bold">-acl</emphasis> are switches;
|
|
<emphasis role="bold">-dir</emphasis> indicates the name of the directory on which to set the ACL, and
|
|
<emphasis role="bold">-acl</emphasis> defines the entries to set on it.</para></listitem>
|
|
<listitem><para><emphasis role="bold">$HOME</emphasis> and <emphasis role="bold">pat all terry
|
|
none</emphasis> are <emphasis>instances</emphasis> of the arguments. <emphasis role="bold">$HOME</emphasis>
|
|
defines a specific directory for the directory argument. The <emphasis role="bold">-acl</emphasis> argument
|
|
has two instances specifying two ACL entries: <emphasis role="bold">pat all</emphasis> and
|
|
<emphasis role="bold">terry none</emphasis>.</para></listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem><para><emphasis role="bold">-negative</emphasis> is a flag; it directs the command to put the access
|
|
list entries on the negative rather than the normal permissions list.</para></listitem>
|
|
</itemizedlist>
|
|
</sect2></sect1><sect1 id="HDRWQ88"><title>Rules for Using OpenAFS Commands</title>
|
|
<para>This section describes the rules to follow when using AFS commands.</para>
|
|
<sect2 id="Header_171"><title>Spaces and Lines</title>
|
|
<para>Separate each command element (command suite, operation code, switches, instances, and flags) with a space.
|
|
Multiple instances of an argument are also separated by a space.</para>
|
|
<para>Type all AFS commands on one line, followed by a carriage return. Some commands in this document appear on
|
|
more than one line, but that is for legibility only.</para>
|
|
</sect2><sect2 id="Header_172"><title>Abbreviations and Aliases for Operation Codes</title>
|
|
|
|
<indexterm><primary>operation codes in AFS commands</primary><secondary>abbreviating</secondary></indexterm>
|
|
|
|
<para>You can type operation codes in one of three ways:</para>
|
|
<itemizedlist>
|
|
<listitem><para>You can type the operation code in full.</para></listitem>
|
|
<listitem><para>You can abbreviate the operation code to the shortest form that distinguishes it from the other
|
|
operation codes in its command suite.</para></listitem>
|
|
<listitem><para>You can use the alias for the operation code, if one exists.</para></listitem>
|
|
</itemizedlist>
|
|
<para>For example, the <emphasis role="bold">fs listacl</emphasis> command can be issued as follows:</para>
|
|
<itemizedlist>
|
|
<listitem><para><emphasis role="bold">fs listacl</emphasis> (full command)</para></listitem>
|
|
<listitem><para><emphasis role="bold">fs lista</emphasis> (abbreviation)</para></listitem>
|
|
<listitem><para><emphasis role="bold">fs la</emphasis> (alias)</para></listitem>
|
|
</itemizedlist>
|
|
<para>The <emphasis>OpenAFS Administration Reference</emphasis> provides information on the full and abbreviated
|
|
command syntax as well as any aliases for all of the commands discussed in this guide.</para>
|
|
</sect2><sect2 id="Header_173"><title>Omitting Argument Switches</title>
|
|
|
|
<indexterm><primary>switches on AFS commands</primary><secondary>omitting</secondary></indexterm>
|
|
|
|
<para>You can omit an argument's switch if the command takes only one argument, or if the following conditions are
|
|
met.</para>
|
|
<itemizedlist>
|
|
<listitem><para>All of the command's required arguments appear in the order prescribed by the syntax
|
|
statement.</para></listitem>
|
|
<listitem><para>No switches are used on any arguments, even if they are in the correct order.</para></listitem>
|
|
<listitem><para>There is only one value for each argument. The important exception to this condition is if the
|
|
final required argument accepts multiple values; in this case, it is acceptable to provide multiple values
|
|
without providing the switch.</para></listitem>
|
|
</itemizedlist>
|
|
<para>For example, the following two commands are equivalent:</para>
|
|
<programlisting>
|
|
% <emphasis role="bold">fs setacl -dir /afs/example.com/usr/terry/private -acl pat rl</emphasis>
|
|
% <emphasis role="bold">fs setacl /afs/example.com/usr/terry/private pat rl</emphasis>
|
|
</programlisting>
|
|
<para>However, the following is not an acceptable short form because the arguments are not in the prescribed
|
|
order:</para>
|
|
<programlisting>
|
|
% <emphasis role="bold">fs setacl -acl pat rl /afs/example.com/usr/terry/private</emphasis>
|
|
</programlisting>
|
|
</sect2><sect2 id="Header_174"><title>Shortening Switches and Flags</title>
|
|
<para>
|
|
<indexterm><primary>switches on AFS commands</primary><secondary>abbreviating</secondary></indexterm>
|
|
If you are required to use a switch, or if you decide to use a flag, you can often
|
|
shorten the name of that switch or flag provided that the shortened form still distinguishes it from the command's
|
|
other flags and switches.</para>
|
|
<para>For example, when you issue the <emphasis role="bold">fs setacl</emphasis> command, you can abbreviate all of
|
|
the switches and flags of the command to their initial letter because they all begin with a different letter.
|
|
However, when you issue the <emphasis role="bold">knfs</emphasis> command, the
|
|
<emphasis role="bold">-host</emphasis> argument and <emphasis role="bold">-help</emphasis> flag both begin with the
|
|
letter <emphasis role="bold">h</emphasis>, so the shortest unambiguous abbreviations are
|
|
<emphasis role="bold">-ho</emphasis> and <emphasis role="bold">-he</emphasis> respectively.</para>
|
|
</sect2><sect2 id="Header_175"><title>Shortening Directory References</title>
|
|
<para>
|
|
<indexterm><primary>directories</primary><secondary>shorthand notation for referencing</secondary></indexterm>
|
|
Most AFS command arguments that require directory or pathnames instances accept one
|
|
or more of the following short forms:</para>
|
|
<itemizedlist>
|
|
<listitem><para>A single period (<emphasis role="bold">.</emphasis>) indicates the current working
|
|
directory.</para></listitem>
|
|
<listitem><para>Two periods (<emphasis role="bold">..</emphasis>) indicate the parent directory of the current
|
|
working directory.</para></listitem>
|
|
<listitem><para>The $HOME environment variable indicates the issuer's home directory.</para></listitem>
|
|
</itemizedlist>
|
|
<para>For example, if the user <emphasis role="bold">terry</emphasis> wants to grant
|
|
<emphasis role="bold">r</emphasis> (<emphasis role="bold">read</emphasis>) and <emphasis role="bold">l</emphasis>
|
|
(<emphasis role="bold">lookup</emphasis>) permissions on his home directory to his manager
|
|
<emphasis role="bold">pat</emphasis>, <emphasis role="bold">terry</emphasis> can issue the following
|
|
command.</para>
|
|
<programlisting>
|
|
% <emphasis role="bold">fs setacl -dir $HOME -acl pat rl</emphasis>
|
|
</programlisting>
|
|
<para>If the current working directory is <emphasis role="bold">terry</emphasis>'s home directory, he can issue the
|
|
following command.</para>
|
|
<programlisting>
|
|
% <emphasis role="bold">fs setacl -dir . -acl pat rl</emphasis>
|
|
</programlisting>
|
|
<para>Both of the previous examples are acceptable short forms for the following command:</para>
|
|
<programlisting>
|
|
% <emphasis role="bold">fs setacl -dir /afs/example.com/usr/terry -acl pat rl</emphasis>
|
|
</programlisting>
|
|
</sect2></sect1><sect1 id="Header_176"><title>Commonly Used fs and pts Commands</title>
|
|
<para>This section provides additional information on the commonly used AFS <emphasis role="bold">fs</emphasis> and
|
|
<emphasis role="bold">pts</emphasis> commands. For more detailed information, see the <emphasis>OpenAFS
|
|
Administration Reference</emphasis>.</para>
|
|
<sect2 id="Header_177"><title>About the fs Commands</title>
|
|
|
|
<indexterm><primary>fs commands</primary><secondary>introduction</secondary></indexterm>
|
|
|
|
<para>Some <emphasis role="bold">fs</emphasis> commands extend UNIX file system semantics by invoking file-related
|
|
functions that UNIX does not provide (setting access control lists, for example). Other
|
|
<emphasis role="bold">fs</emphasis> commands help you control the performance of the Cache Manager running on your
|
|
local client machine.
|
|
<indexterm><primary>fs commands</primary><secondary>help flag</secondary></indexterm>
|
|
|
|
<indexterm><primary>fs commands</primary><secondary>getting help</secondary></indexterm>
|
|
</para>
|
|
<para>All <emphasis role="bold">fs</emphasis> commands accept the optional <emphasis role="bold">-help</emphasis>
|
|
flag. It has the same function as the <emphasis role="bold">fs help</emphasis> command: it prints a command's
|
|
online help message on the screen. Do not provide other options at the same time as this flag. It overrides them,
|
|
and the only effect of issuing the command is to display the help message.
|
|
<indexterm><primary>fs commands</primary><secondary>privileges required</secondary></indexterm>
|
|
</para>
|
|
<para>The privilege required for issuing <emphasis role="bold">fs</emphasis> commands varies. The necessary
|
|
privileges for the <emphasis role="bold">fs</emphasis> commands described in this guide include the
|
|
following:</para>
|
|
<itemizedlist>
|
|
<listitem><para>Having certain permissions on a directory's access control list. For example, creating and
|
|
removing mount points requires <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>),
|
|
<emphasis role="bold">i</emphasis> (<emphasis role="bold">insert</emphasis>), and
|
|
<emphasis role="bold">d</emphasis> (<emphasis role="bold">delete</emphasis>) permissions for the directory in
|
|
which the mount point resides.</para></listitem>
|
|
<listitem><para>Belonging to the <emphasis role="bold">system:administrators</emphasis> group (see
|
|
<link linkend="HDRWQ50">Using the System Groups on ACLs</link>).</para></listitem>
|
|
<listitem><para>No privilege. Many <emphasis role="bold">fs</emphasis> commands simply list information and so do
|
|
not require any special privilege.</para></listitem>
|
|
</itemizedlist>
|
|
</sect2><sect2 id="Header_178"><title>About the pts Commands</title>
|
|
|
|
<indexterm><primary>pts commands</primary><secondary>privilege required</secondary></indexterm>
|
|
|
|
<indexterm><primary>Protection Database</primary></indexterm>
|
|
|
|
<para>The <emphasis role="bold">pts</emphasis> command suite is the interface through which you can create
|
|
protection groups and add members to them. System administrators who belong to a special system group called
|
|
<emphasis role="bold">system:administrators</emphasis> group can manipulate any group, and also create the user and
|
|
machine entries that can belong to groups. Users who do not belong to the
|
|
<emphasis role="bold">system:administrators</emphasis> group can always list the information associated with the
|
|
group entries they own, as well as their own user entries. Depending on the setting of an entry's privacy flags,
|
|
regular users can sometimes access and manipulate group entries in certain ways.</para>
|
|
<para>All <emphasis role="bold">pts</emphasis> commands accept optional arguments and flags. They are listed in the
|
|
command descriptions in the <emphasis>OpenAFS Administration Reference</emphasis> and are described here in
|
|
detail:</para>
|
|
<variablelist>
|
|
|
|
<indexterm><primary>pts commands</primary><secondary>cell argument</secondary></indexterm>
|
|
|
|
<varlistentry><term><emphasis role="bold">[-cell <<replaceable>cell name</replaceable>>]</emphasis></term>
|
|
<listitem><para>
|
|
This argument indicates that the command runs in the indicated cell. The issuer can abbreviate the
|
|
<replaceable>cell name</replaceable> value to the shortest form that distinguishes it from the other cells
|
|
listed in the <emphasis role="bold">/usr/vice/etc/CellServDB</emphasis> file on the client machine on which the
|
|
command is issued. By default, commands are executed in the local cell as defined
|
|
</para><itemizedlist>
|
|
<listitem><para>First, by the value of the environment variable AFSCELL. (This variable is normally not
|
|
defined by default. If you are working in another, nonlocal cell for an extended period of time, you can set
|
|
the variable to the name of that cell.)</para></listitem>
|
|
<listitem><para>Second, in the <emphasis role="bold">/usr/vice/etc/ThisCell</emphasis> file on the client
|
|
machine on which the command is issued.</para></listitem>
|
|
</itemizedlist>
|
|
</listitem></varlistentry>
|
|
</variablelist>
|
|
<variablelist>
|
|
<varlistentry><term><emphasis role="bold">[-force]</emphasis></term>
|
|
<listitem><para>This flag directs the <emphasis role="bold">pts</emphasis> command interpreter to continue
|
|
executing the command, if possible, even if it encounters problems during the command's execution.
|
|
|
|
<indexterm><primary>pts commands</primary><secondary>force flag</secondary></indexterm>
|
|
The command interpreter performs as much of the requested operation as possible, rather
|
|
than halting if it encounters a problem. The command interpreter reports any errors it encounters during the
|
|
command's execution. This flag is especially useful if you provide many instances for an argument; if one of the
|
|
instances is invalid, the command reports the error and proceeds with the remaining
|
|
arguments.</para></listitem></varlistentry>
|
|
</variablelist>
|
|
<variablelist>
|
|
<varlistentry><term><emphasis role="bold">[-help]
|
|
<indexterm><primary>pts commands</primary><secondary>help flag</secondary></indexterm>
|
|
|
|
|
|
<indexterm><primary>pts commands</primary><secondary>getting help</secondary></indexterm>
|
|
</emphasis></term>
|
|
<listitem><para>This flag has the same function as the <emphasis role="bold">pts help</emphasis> command: it
|
|
prints the command's online help message on the screen. Do not provide other options at the same time as this
|
|
flag. It overrides them, and the only effect of issuing the command is to display the help
|
|
message.</para></listitem></varlistentry>
|
|
</variablelist>
|
|
</sect2></sect1><sect1 id="HDRWQ89"><title>Getting Help in AFS</title>
|
|
|
|
<indexterm><primary>help</primary><secondary>online for AFS commands</secondary></indexterm>
|
|
|
|
<indexterm><primary>online help</primary></indexterm>
|
|
|
|
<para>AFS online help consists of basic syntax messages. The AFS distribution also includes help in HTML format
|
|
which your system administrator can make available to you.</para>
|
|
<sect2 id="Header_180"><title>Displaying Command Syntax and Aliases</title>
|
|
|
|
<indexterm><primary>apropos operation code</primary></indexterm>
|
|
|
|
<indexterm><primary>help</primary><secondary>operation code in AFS command suites</secondary></indexterm>
|
|
|
|
<indexterm><primary>help</primary><secondary>examples</secondary></indexterm>
|
|
|
|
<para>To display a brief description of a command, its syntax statement, and alias if any, use the
|
|
<emphasis role="bold">help</emphasis> operation code. For example, to display the online help entry for the
|
|
<emphasis role="bold">fs listacl</emphasis> command, enter the following command:</para>
|
|
<programlisting>
|
|
% <emphasis role="bold">fs help listacl</emphasis>
|
|
fs listacl: list access control list
|
|
aliases: la
|
|
Usage: fs listacl [-path <dir/file path>+] [-id] [-if] [-help]
|
|
</programlisting>
|
|
<para>To display the syntax statement only, use the <emphasis role="bold">-help</emphasis> flag, which is available
|
|
on most AFS commands. For example, to display the syntax statement for the <emphasis role="bold">fs
|
|
setacl</emphasis> command, enter the following command:</para>
|
|
<programlisting>
|
|
% <emphasis role="bold">fs setacl -help</emphasis>
|
|
Usage: fs setacl -dir <directory>+ -acl <access list entries>+ [-clear] [-negative]
|
|
[-id] [-if] [-help]
|
|
</programlisting>
|
|
</sect2><sect2 id="Header_181"><title>Displaying Operation Code Descriptions</title>
|
|
<para>To display a short description of all of a command suite's operation codes, issue the
|
|
<emphasis role="bold">help</emphasis> operation code without any other arguments. For example, the
|
|
<emphasis role="bold">fs help</emphasis> command displays a short description of every operation code in the
|
|
<emphasis role="bold">fs</emphasis> command suite.
|
|
<indexterm><primary>keyword for apropos command</primary></indexterm>
|
|
</para>
|
|
<para>To display a list of the commands in a command suite that concern a certain type of object, provide a
|
|
relevant keyword argument to the <emphasis role="bold">apropos</emphasis> operation code. For example, if you want
|
|
to set an ACL but cannot remember which <emphasis role="bold">fs</emphasis> command to use, issue the following
|
|
command:</para>
|
|
<programlisting>
|
|
% <emphasis role="bold">fs apropos set</emphasis>
|
|
setacl: set access control list
|
|
setcachesize: set cache size
|
|
setcell: set cell status
|
|
setclientaddrs: set client network interface addresses
|
|
setquota: set volume quota
|
|
setserverprefs: set file server ranks
|
|
setvol: set volume status
|
|
sysname: get/set sysname (i.e. @sys) value
|
|
</programlisting>
|
|
<para>The following message indicates that there are no commands whose names or descriptions include the keyword
|
|
string you have provided:</para>
|
|
<programlisting>
|
|
Sorry, no commands found
|
|
</programlisting>
|
|
<note>
|
|
<para>If the keyword you provide has spaces in it, enclose it in double quotes (<emphasis role="bold">"
|
|
"</emphasis>).</para>
|
|
</note>
|
|
</sect2></sect1></appendix>
|