Import Upstream version 1.8.5

[hcoop/debian/openafs.git] / doc / xml / AdminGuide / auagd005.xml

<?xml version="1.0" encoding="UTF-8"?>

<preface id="Header_3">
  <title>About This Guide</title>

  <para>This section describes the purpose, organization, and conventions
  of this document.</para>

  <sect1 id="HDRWQ1">
    <title>Audience and Purpose</title>

    <para>This guide describes the concepts and procedures that an AFS(R)
    system administrator needs to know. It assumes familiarity with
    UNIX(R) administration, but no previous knowledge of AFS.</para>

    <para>This document describes AFS commands in the context of specific
    tasks. Thus, it does not describe all commands in detail.  Refer to
    the OpenAFS Administration Reference for detailed command
    descriptions.</para>
  </sect1>

  <sect1 id="HDRWQ2">
    <title>Document Organization</title>

    <para>
      This document groups AFS administrative tasks into the following
      conceptual sections:
      <itemizedlist>
        <listitem>
          <para>Concepts and Configuration Issues</para>
        </listitem>

        <listitem>
          <para>Managing File Server Machines</para>
        </listitem>

        <listitem>
          <para>Managing Client Machines</para>
        </listitem>

        <listitem>
          <para>Managing Users and Groups</para>
        </listitem>
      </itemizedlist>
    </para>

    <para>
      The individual chapters in each section contain the following:
      <itemizedlist>
        <listitem>
          <para>A chapter overview</para>
        </listitem>

        <listitem>
          <para>A quick reference list of the tasks and commands described
          in the chapter</para>
        </listitem>

        <listitem>
          <para>An introduction to concepts that pertain to all of the
          tasks described in the chapter</para>
        </listitem>

        <listitem>
          <para>A set of sections devoted to specific tasks. Each section
          begins with a discussion of concepts specific to that task,
          followed by step-by-step instructions for performing the
          task. The instructions are as specific as has been judged
          practical. If two related procedures differ from one another in
          important details, separate sets of instructions are usually
          provided.</para>
        </listitem>
    </itemizedlist>
    </para>
  </sect1>

  <sect1 id="HDRWQ3">
    <title>How to Use This Document</title>

    <para>When you need to perform a specific administrative task, follow
    these steps:

    <orderedlist>
      <listitem>
        <para>Determine if the task concerns file server machines, client
        machines, or users and groups. Turn to the appropriate section in
        this document and then to the appropriate chapter.</para>
      </listitem>

      <listitem>
        <para>Read or review the general introductory material at the
        beginning of the chapter.</para>
      </listitem>

      <listitem>
        <para>Read or review the introductory material concerning the
        specific task you wish to perform.</para>
      </listitem>

      <listitem>
        <para>Follow the step-by-step instructions for the task.</para>
      </listitem>

      <listitem>
        <para>If necessary, refer to the OpenAFS Administration Reference
        for more detailed information about the commands.</para>
      </listitem>
    </orderedlist>
    </para>
  </sect1>

  <sect1 id="HDRWQ4">
    <title>Related Documents</title>

    <para>The following documents are also included in the AFS
    documentation set.
    <variablelist>
      <varlistentry>
        <term>OpenAFS Quick Start Guide</term>

        <listitem>
          <para>
            This guide provides instructions for installing AFS server and
            client machines. It is assumed that the installer is an
            experienced UNIX(R) system administrator.
          </para>

          <para>
            For predictable performance, machines must be installed and
            configured in accordance with the instructions in this guide.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>OpenAFS User Guide</term>

        <listitem>
          <para>
            This guide presents the basic concepts and procedures
            necessary for using AFS effectively. It assumes that the
            reader has some experience with UNIX, but does not require
            familiarity with networking or AFS.
          </para>

          <para>
            The guide explains how to perform basic functions, including
            authenticating, changing a password, protecting AFS data,
            creating groups, and troubleshooting. It provides illustrative
            examples for each function and describes some of the
            differences between the UNIX file system and AFS.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>OpenAFS Reference Manual</term>

        <listitem>
          <para>
            This reference manual details the syntax and effect of each
            AFS command. It is intended for the experienced AFS
            administrator, programmer, or user. It contains a reference
            page for each command or file specifying its syntax, including
            the acceptable aliases and abbreviations. It then describes
            the command's function, arguments, and output if any. Examples
            and a list of related commands are provided, as are warnings
            where appropriate.
          </para>

          <para>
            This manual complements the OpenAFS Administration Guide:  it
            does not include procedural information, but describes
            commands in more detail than the OpenAFS Administration Guide.
          </para>

          <para>
            The OpenAFS Reference Manual is provided in the form of
            UNIX(R) manual pages and as HTML pages.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>OpenAFS for Windows Release Notes</term>

        <listitem>
          <para>
            This document provides a series of usage notes regarding the
            OpenAFS for Windows client, supported platforms, contribution
            information, debugging techniques, and a reference to
            supported Windows registry values.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
    </para>
  </sect1>

  <sect1 id="HDRTYPO_CONV">
    <title>Typographical Conventions</title>

    <para>This document uses the following typographical conventions:

    <itemizedlist>
      <listitem>
        <para>
          Command and option names appear in <emphasis role="bold">bold
          type</emphasis> in syntax definitions, examples, and running
          text. Names of directories, files, machines, partitions,
          volumes, and users also appear in <emphasis role="bold">bold
          type</emphasis>.
        </para>
      </listitem>

      <listitem>
        <para>
          Variable information appears in <emphasis>italic
          type</emphasis>. This includes user-supplied information on
          command lines and the parts of prompts that differ depending on
          who issues the command. New terms also appear in
          <emphasis>italic type</emphasis>.
        </para>
      </listitem>

      <listitem>
        <para>
          Examples of screen output and file contents appear in
          <computeroutput>monospace type</computeroutput>.
      </para>
      </listitem>
    </itemizedlist>
    </para>

    <para>In addition, the following symbols appear in command syntax
    definitions, both in the documentation and in AFS online help
    statements. When issuing a command, do not type these
    symbols.
    <itemizedlist>
      <listitem>
        <para>Square brackets <emphasis role="bold">[ ]</emphasis>
        surround optional items.</para>
      </listitem>

      <listitem>
        <para>Angle brackets <emphasis role="bold">&lt; &gt;</emphasis>
        surround user-supplied values in AFS commands.</para>
      </listitem>

      <listitem>
        <para>A superscripted plus sign <emphasis role="bold">+</emphasis>
        follows an argument that accepts more than one value.</para>
      </listitem>

      <listitem>
        <para>The percent sign <computeroutput>%</computeroutput>
        represents the regular command shell prompt. Some operating
        systems possibly use a different character for this prompt.</para>
      </listitem>

      <listitem>
        <para>The number sign <computeroutput>#</computeroutput>
        represents the command shell prompt for the local superuser
        <emphasis role="bold">root</emphasis>.  Some operating systems
        possibly use a different character for this prompt.</para>
      </listitem>

      <listitem>
        <para>The pipe symbol <emphasis role="bold">|</emphasis> in a
        command syntax statement separates mutually exclusive values for
        an argument.</para>
      </listitem>
    </itemizedlist>
    </para>

    <para>For additional information on AFS commands, including a
    description of command string components, acceptable abbreviations and
    aliases, and how to get online help for commands, see <link
    linkend="HDRCOMMANDS">Appendix B, Using AFS Commands</link>.</para>
  </sect1>
</preface>