doc/en/openafs.xml

<?xml version='1.0' encoding="UTF-8"?>
<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/openafs.xml,v 1.14 2004/04/11 10:52:16 cam Exp $ -->

<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">

<guide link = "/doc/en/openafs.xml">
<title>Gentoo Linux OpenAFS Guide</title>
<author title="Editor">
  <mail link="darks@gentoo.org">Holger Brueckner</mail>
</author>
<author title="Editor">
  <mail link="bennyc@gentoo.org">Benny Chuang</mail>
</author>
<author title="Editor">
  <mail link="blubber@gentoo.org">Tiemo Kieft</mail>
</author>

<abstract>
This guide shows you how to install a openafs server and client on gentoo linux 
</abstract>

<license/>

<version>0.6</version>
<date>September 09, 2004</date>

<chapter>
  <title>Overview</title>
  <section>
    <title>About this Document</title>
    <body>
      <p>This document provides you with all neccessary steps to install an openafs server on Gentoo Linux.
      Parts of this document are taken from the AFS FAQ and IBM's Quick Beginnings guide on AFS. Well, never reinvent
      the wheel :)</p>
    </body>
  </section>
  <section>
    <title>What is AFS ?</title>
    <body>
    
    <p>
    AFS is a distributed filesystem that enables co-operating hosts
   (clients and servers) to efficiently share filesystem resources
   across both local area and wide area networks. Clients hold a 
   cache for often used objects (files), to get quicker
   access to them.
   </p>
   <p>
   AFS is based on a distributed file system originally developed
   at the Information Technology Center at Carnegie-Mellon University
   that was called the "Andrew File System". "Andrew" was the name of the research project at CMU - honouring the
   founders of the University.  Once Transarc was formed and AFS became a
   product, the "Andrew" was dropped to indicate that AFS had gone beyond
   the Andrew research project and had become a supported, product quality
   filesystem. However, there were a number of existing cells that rooted
   their filesystem as /afs. At the time, changing the root of the filesystem
   was a non-trivial undertaking. So, to save the early AFS sites from having
   to rename their filesystem, AFS remained as the name and filesystem root.
   </p> 
   </body>
  </section>  
    <section>
    <title>What is an AFS cell ?</title>
    <body>
    <p>An AFS cell is a collection of servers grouped together administratively
    and presenting a single, cohesive filesystem.  Typically, an AFS cell is a set of 
    hosts that use the same Internet domain name (like for example gentoo.org)
    Users log into AFS client workstations which request information and files
    from the cell's servers on behalf of the users. Users won't know on which server
    a file which they are accessing, is located. They even won't notice if a server
    will be located to another room, since every volume can be replicated and moved
    to another server without any user noticing. The files are always accessable.
    Well it's like NFS on steroids :) 
   </p>
    </body>
  </section>  
  <section>
    <title>What are the benefits of using AFS ?</title>
    <body>
    <p>The main strengths of AFS are its:
 
       caching facility (on client side, typically 100M to 1GB),
       security features (Kerberos 4 based, access control lists),
       simplicity of addressing (you just have one filesystem),
       scalability (add further servers to your cell as needed),
       communications protocol. 
    </p>
    </body>
  </section>  
  <section>
    <title>Where can i get more information ?</title>
    <body>
    <p>
    Read the <uri link="http://www.angelfire.com/hi/plutonic/afs-faq.html">AFS FAQ</uri>.
    </p>
    <p>
    Openafs main page is at <uri link="http://www.openafs.org">www.openafs.org</uri>.
    </p>
    <p>
    AFS was originally developed by Transarc which is now owned by IBM.
    You can find some information about AFS on
    <uri link="http://www.transarc.ibm.com/Product/EFS/AFS/index.html">Transarcs Webpage</uri>
    </p>
    </body>
  </section>  

</chapter>

<chapter>
<title>Documentation</title>
  <section>
    <title>Getting AFS Documentation</title>
    <body>
    <p>
    You can get the original IBM AFS Documentation. It is very well written and you 
    really want 
    read it if it is up to you to administer a AFS Server.
    </p>
<pre>
# <i>emerge app-doc/afsdoc</i>
</pre>
    </body>   
  </section>
</chapter>

<chapter>
<title>Client Installation</title>
   <section>
     <title>Preliminary Work</title>
     <body>
       <note>
         All commands should be written in one line !! In this document they are
         sometimes wrapped to two lines to make them easier to read.
       </note>
       <note>
         Unfortunately the AFS Client needs a ext2 partiton for it's cache to run 
         correctly, because there are some locking issues with reiserfs. You need to 
         create a ext2 partition of approx. 200MB (more won't hurt) and mount it to 
         <path>/usr/vice/cache</path>
       </note>
       <p>
       You should adjust the two files CellServDB and ThisCell before you build the 
       afs client. (These files are in <path>/usr/portage/net-fs/openafs/files</path>)
       </p>
 <pre>
 CellServDB:
 >netlabs        #Cell name
 10.0.0.1        #storage
 
 ThisCell:
 netlabs       
 </pre>

 <warn>
 Only use spaces inside the <path>CellServDB</path> file. The client will most
 likely fail if you use TABs.
 </warn>
 
       <p>
       CellServDB tells your client which server(s) he needs to contact for a 
       specific cell. ThisCell should be quite obvious. Normally you use a name
       which is unique for your organisation. Your (official) domain might be a
       good choice. 
       </p>
     </body>
   </section>
   <section>
     <title>Building the Client</title>
     <body>
<pre>
# <i>emerge net-fs/openafs</i>
</pre>
       <p>
       After successful compilation you're ready to go.
       </p>
     </body>
   </section>
   <section>
     <title>Starting afs on startup</title>
     <body>
       <p>
       The following command will create the appropriate links to start your afs client
       on system startup.
       </p>
       <warn>
       You should always have a running afs server in your domain when trying to start the afs client. You're system won't boot
       until it gets some timeout if your afs server is down. (and this is quite a long long time)
       </warn>
<pre>
# <i>rc-update add afs default</i>
</pre>
     </body>
   </section>
</chapter>

<chapter>
<title>Server Installation</title>
   <section>
     <title>Building the Server</title>
     <body>
       <p>
       The following command will install all necessary binaries for setting up a AFS Server 
       <e>and</e> Client.
       </p>
<pre>
# <i>emerge net-fs/openafs</i>
</pre>
     </body>
   </section>
  <section>
    <title>Starting AFS Server</title>    
    <body>
      <p>
      You need to remove the sample CellServDB and ThisCell file first.
      </p>
<pre>
# <i>rm /usr/vice/etc/ThisCell</i>
# <i>rm /usr/vice/etc/CellServDB</i>
</pre>
      <p>
      Next you will run the <b>bosserver</b> command to initialize the Basic OverSeer (BOS) 
      Server, which monitors and controls other AFS server processes on its server 
      machine. Think of it as init for the system. Include the <b>-noauth</b>
      flag to disable authorization checking, since you haven't added the admin user yet.
      </p>
      <warn>
      Disabling authorization checking gravely compromises cell security. 
      You must complete all subsequent steps in one uninterrupted pass 
      and must not leave the machine unattended until you restart the BOS Server with
      authorization checking enabled. Well this is what the AFS documentation says :)
      </warn>
<pre>
# <i>/usr/afs/bin/bosserver -noauth &amp;</i>
</pre>
      <p>
      Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path> 
      and <path>/usr/vice/etc/ThisCell</path>
      </p>
<pre>
# <i>ls -al /usr/vice/etc/</i>
-rw-r--r--    1 root     root           41 Jun  4 22:21 CellServDB
-rw-r--r--    1 root     root            7 Jun  4 22:21 ThisCell
</pre>
      
    </body>    
  </section>
  <section>
    <title>Defining Cell Name and Membership for Server Process</title>
    <body>
      <p>
      Now assign your cells name. 
      </p>
      <impo>There are some restrictions on the name format. 
      Two of the most important restrictions are that the name
      cannot include uppercase letters or more than 64 characters. Remember that
      your cell name will show up under <path>/afs</path>, so you might want to choose
      a short one.</impo>
      <note>In the following and every instruction in this guide, for the &lt;server name&gt;
      argument substitute the full-qualified hostname 
      (such as <b>afs.gentoo.org</b>) of the machine you are installing. 
      For the &lt;cell name&gt;
      argument substitute your cell's complete name (such as <b>gentoo</b>)</note>
      <p>
      Run the <b>bos setcellname</b> command to set the cell name:
      </p>
<pre>
# <i>/usr/afs/bin/bos setcellname &lt;server name&gt; &lt;cell name&gt; -noauth</i>
</pre>
    </body>
  </section>
  <section>
    <title>Starting the Database Server Process</title>
    <body><p>
       Next use the <b>bos create</b> command to create entries for the four database 
       server processes in the
       <path>/usr/afs/local/BosConfig</path> file. The four processes run on database 
       server machines only.
       </p>

       <table>
       <tr>
         <ti>kaserver</ti>
         <ti>The Authentication Server maintains the Authentication Database.
             This can be replaced by a Kerberos 5 daemon. If anybody want's to try that
             feel free to update this document :)</ti>
       </tr>
       <tr>
         <ti>buserver</ti>
         <ti>The Backup Server maintains the Backup Database</ti>
       </tr>
       <tr>
         <ti>ptserver</ti>
         <ti>The Protection Server maintains the Protection Database</ti>
       </tr>
       <tr>
         <ti>vlserver</ti>
         <ti>The Volume Location Server maintains the Volume Location Database (VLDB).
             Very important :)</ti>
       </tr>
       </table>    
<pre>
# <i>/usr/afs/bin/bos create &lt;server name&gt; kaserver simple 
    /usr/afs/bin/kaserver -cell &lt;cell name&gt; -noauth</i>
# <i>/usr/afs/bin/bos create &lt;server name&gt; buserver simple 
    /usr/afs/bin/buserver -cell &lt;cell name&gt; -noauth</i>
# <i>/usr/afs/bin/bos create &lt;server name&gt; ptserver simple 
    /usr/afs/bin/ptserver -cell &lt;cell name&gt; -noauth</i>
# <i>/usr/afs/bin/bos create &lt;server name&gt; vlserver simple 
    /usr/afs/bin/vlserver -cell &lt;cell name&gt; -noauth</i>
</pre>
       <p>
       You can verify that all servers are running with the <b>bos status</b> command:
       </p>
<pre>
# <i>/usr/afs/bin/bos status &lt;server name&gt; -noauth</i>
Instance kaserver, currently running normally.
Instance buserver, currently running normally.
Instance ptserver, currently running normally.
Instance vlserver, currently running normally.
</pre>
       
    </body>
  </section>
  <section>
    <title>Initializing Cell Security</title>
    <body>
      <p>
      Now we'll initialize the cell's security mechanisms. We'll begin by creating the 
      following two initial entries in the
      Authentication Database: The main administrative account, called <b>admin</b> by 
      convention and an entry for
      the AFS server processes, called <b>afs</b>. No user logs in under the 
      identity <b>afs</b>, but the Authentication
      Server's Ticket Granting Service (TGS) module uses the account
      to encrypt the server tickets that it grants to AFS clients. This sounds 
      pretty much like Kerberos :)
      </p>
      <p>
      Enter <b>kas</b> interactive mode
      </p>
<pre>
# <i>/usr/afs/bin/kas -cell &lt;cell name&gt; -noauth</i>
ka&gt; <i>create afs</i>
initial_password:
Verifying, please re-enter initial_password:
ka&gt; <i>create admin</i>
initial_password:
Verifying, please re-enter initial_password:
ka&gt; <i>examine afs</i>

User data for afs
  key (0) cksum is 2651715259, last cpw: Mon Jun  4 20:49:30 2001
  password will never expire.
  An unlimited number of unsuccessful authentications is permitted.
  entry never expires.  Max ticket lifetime 100.00 hours.
  last mod on Mon Jun  4 20:49:30 2001 by $lt;none&gt;
  permit password reuse
ka&gt; <i>setfields admin -flags admin</i>
ka&gt; <i>examine admin</i>
 
User data for admin (ADMIN)
  key (0) cksum is 2651715259, last cpw: Mon Jun  4 20:49:59 2001
  password will never expire.
  An unlimited number of unsuccessful authentications is permitted.
  entry never expires.  Max ticket lifetime 25.00 hours.
  last mod on Mon Jun  4 20:51:10 2001 by $lt;none&gt;
  permit password reuse
ka&gt;
</pre>
      <p>
        Run the <b>bos adduser</b> command, to add the <b>admin</b> user to 
        the <path>/usr/afs/etc/UserList</path>.
      </p>
<pre>
# <i>/usr/afs/bin/bos adduser &lt;server name&gt; admin -cell &lt;cell name&gt; -noauth</i>
</pre>
      <p>
        Issue the <b>bos addkey</b> command to define the AFS Server 
        encryption key in <path>/usr/afs/etc/KeyFile</path>
      </p>
      <note>
        If asked for the input key, give the password you entered when creating 
        the afs entry with <b>kas</b>
      </note>
<pre>
# <i>/usr/afs/bin/bos addkey  &lt;server name&gt; -kvno 0 -cell &lt;cell name&gt; -noauth</i>
    input key:
    Retype input key:
</pre>
      <p>
        Issue the <b>pts createuser</b> command to create a Protection Database 
        entry for the admin user
      </p>
      <note>
        By default, the Protection Server assigns AFS UID 1 to the <b>admin</b> user, because 
        it is the first user
        entry you are creating. If the local password file (/etc/passwd or equivalent) 
        already has an entry for
        <b>admin</b> that assigns a different UID use the <b>-id</b> argument 
        to create matching UID's
       </note>
<pre>
# <i>/usr/afs/bin/pts createuser -name admin -cell &lt;cell name&gt; [-id &lt;AFS UID&gt;] -noauth</i>
</pre>
      <p>
        Issue the <b>pts adduser</b> command to make the <b>admin</b> user a member 
        of the system:administrators group,
        and the <b>pts membership</b> command to verify the new membership
      </p>
<pre>
# <i>/usr/afs/bin/pts adduser admin system:administrators -cell &lt;cell name&gt; -noauth</i>
# <i>/usr/afs/bin/pts membership admin -cell &lt;cell name&gt; -noauth</i>
      Groups admin (id: 1) is a member of:
        system:administrators
</pre>
      <p>
        Restart all AFS Server processes
      </p>
<pre>
# <i>/usr/afs/bin/bos restart &lt;server name&gt; -all -cell &lt;cell name&gt; -noauth</i>
</pre>
    </body>
  </section>
  <section>
    <title>Starting the File Server, Volume Server and Salvager</title>
    <body>
    <p>
      Start the <b>fs</b> process, which consists of the File Server, Volume Server and Salvager (fileserver,
      volserver and salvager processes).
    </p>
<pre>
# <i>/usr/afs/bin/bos create &lt;server name&gt; fs fs /usr/afs/bin/fileserver 
                                              /usr/afs/bin/volserver 
                                              /usr/afs/bin/salvager 
                                              -cell &lt;cell name&gt; -noauth</i>
</pre>
    <p>
    Verify that all processes are running
    </p>
<pre>
 # <i>/usr/afs/bin/bos status &lt;server name&gt; -long -noauth</i>
 Instance kaserver, (type is simple) currently running normally.
     Process last started at Mon Jun  4 21:07:17 2001 (2 proc starts)
     Last exit at Mon Jun  4 21:07:17 2001
     Command 1 is '/usr/afs/bin/kaserver'

 Instance buserver, (type is simple) currently running normally.
     Process last started at Mon Jun  4 21:07:17 2001 (2 proc starts)
     Last exit at Mon Jun  4 21:07:17 2001
     Command 1 is '/usr/afs/bin/buserver'

 Instance ptserver, (type is simple) currently running normally.
     Process last started at Mon Jun  4 21:07:17 2001 (2 proc starts)
     Last exit at Mon Jun  4 21:07:17 2001
     Command 1 is '/usr/afs/bin/ptserver'

 Instance vlserver, (type is simple) currently running normally.
     Process last started at Mon Jun  4 21:07:17 2001 (2 proc starts)
     Last exit at Mon Jun  4 21:07:17 2001
     Command 1 is '/usr/afs/bin/vlserver'

 Instance fs, (type is fs) currently running normally.
     Auxiliary status is: file server running.
     Process last started at Mon Jun  4 21:09:30 2001 (2 proc starts)
     Command 1 is '/usr/afs/bin/fileserver'
     Command 2 is '/usr/afs/bin/volserver'
     Command 3 is '/usr/afs/bin/salvager'
</pre>
    <p>
      Your next action depends on whether you have ever run AFS file server machines 
      in the cell:
    </p>
    <p>
      If you are installing the first AFS Server ever in the cell create the 
      first AFS volume, <b>root.afs</b>
    </p>
    <note>
    For the partition name argument, substitute the name of one of the machine's 
    AFS Server partitions. By convention
    these partitions are named <path>/vicepx</path>, where x is in the range of a-z.
    </note>
<pre>
  # <i>/usr/afs/bin/vos create &lt;server name&gt; 
                            &lt;partition name&gt; root.afs 
                                -cell &lt;cell name&gt; -noauth</i>
</pre>
    <p>
      If there are existing AFS file server machines and volumes in the cell 
      issue the <b>vos sncvldb</b> and <b>vos
      syncserv</b> commands to synchronize the VLDB (Volume Location Database) with 
      the actual state of volumes on the local machine. This will copy all necessary data to your
      new server.
    </p>
    <p>
      If the command fails with the message "partition /vicepa does not exist on
      the server" ensure that the partition is mounted before runningt OpenAFS
      servers, or mount the directory and restart the processes using
      <c>/usr/afs/bin/bos restart &lt;server name&gt; -all -cell &lt;cell
      name&gt; -noauth</c>.
    </p>
<pre>
  # <i>/usr/afs/bin/vos syncvldb &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i>
  # <i>/usr/afs/bin/vos syncserv &lt;server name&gt; -cell &lt;cell name&gt; -verbose -noauth</i> 
</pre>
    </body>
  </section>
  <section>
    <title>Starting the Server Portion of the Update Server</title>
    <body>
<pre>
# <i>/usr/afs/bin/bos create &lt;server name&gt; 
                    upserver simple "/usr/afs/bin/upserver 
                    -crypt /usr/afs/etc -clear /usr/afs/bin" 
                    -cell &lt;cell name&gt; -noauth</i>
</pre>
    </body>
  </section>
  <section>
    <title>Configuring the Top Level of the AFS filespace</title>
    <body>
      <p>
        First you need to set some acl's, so that any user can lookup <path>/afs</path>.        
      </p>
<pre>
# <i>/usr/afs/bin/fs setacl /afs system:anyuser rl</i>
</pre>
      <p>
       Then you need to create the root volume, mount it readonly on <path>/afs/&lt;cell name&gt;</path> and read/write
       on <path>/afs/.&lt;cell name&gt;</path>
      </p>
<pre>
# <i>/usr/afs/bin/vos create &lt;server name&gt;&lt;partition name&gt; root.cell</i>
# <i>/usr/afs/bin/fs mkmount /afs/&lt;cell name&gt; root.cell </i>
# <i>/usr/afs/bin/fs setacl /afs/&lt;cell name&gt; system:anyuser rl</i>
# <i>/usr/afs/bin/fs mkmount /afs/.&lt;cell name&gt; root.cell -rw</i>
</pre>
      <p>
        Finally you're done !!! You should now have a working AFS file server 
        on your local network. Time to get a big
        cup of coffee and print out the AFS documentation !!!
      </p>
      <note>
        It is very important for the AFS server to function properly, that all system 
        clock's are synchronized. 
        This is best
        accomplished by installing a ntp server on one machine (e.g. the AFS server) 
        and synchronize all client clock's
        with the ntp client. This can also be done by the afs client. 
      </note>
    </body>
  </section>
  
</chapter>

<chapter>
  <title>Basic Administration</title>
  <section>
  <title></title>
  <body>
    <p>To be done ... For now read the AFS Documentation :)</p>
  </body>
  </section>
</chapter>
</guide>
1	zhen	1.3	<?xml version='1.0' encoding="UTF-8"?>
2	swift	1.15	<!-- $Header: /home/cvsroot/gentoo/xml/htdocs/doc/en/openafs.xml,v 1.14 2004/04/11 10:52:16 cam Exp $ -->
3	drobbins	1.1
4			<!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
5
6	zhen	1.2	<guide link = "/doc/en/openafs.xml">
7	drobbins	1.1	<title>Gentoo Linux OpenAFS Guide</title>
8			<author title="Editor">
9			<mail link="darks@gentoo.org">Holger Brueckner</mail>
10			</author>
11	bennyc	1.8	<author title="Editor">
12			<mail link="bennyc@gentoo.org">Benny Chuang</mail>
13			</author>
14	blubber	1.10	<author title="Editor">
15			<mail link="blubber@gentoo.org">Tiemo Kieft</mail>
16			</author>
17	drobbins	1.1
18			<abstract>
19			This guide shows you how to install a openafs server and client on gentoo linux
20			</abstract>
21
22	swift	1.9	<license/>
23
24	swift	1.15	<version>0.6</version>
25			<date>September 09, 2004</date>
26	drobbins	1.1
27			<chapter>
28			<title>Overview</title>
29			<section>
30			<title>About this Document</title>
31			<body>
32			<p>This document provides you with all neccessary steps to install an openafs server on Gentoo Linux.
33			Parts of this document are taken from the AFS FAQ and IBM's Quick Beginnings guide on AFS. Well, never reinvent
34	blubber	1.10	the wheel :)</p>
35	drobbins	1.1	</body>
36			</section>
37			<section>
38			<title>What is AFS ?</title>
39			<body>
40
41			<p>
42			AFS is a distributed filesystem that enables co-operating hosts
43			(clients and servers) to efficiently share filesystem resources
44			across both local area and wide area networks. Clients hold a
45			cache for often used objects (files), to get quicker
46			access to them.
47			</p>
48			<p>
49			AFS is based on a distributed file system originally developed
50			at the Information Technology Center at Carnegie-Mellon University
51			that was called the "Andrew File System". "Andrew" was the name of the research project at CMU - honouring the
52			founders of the University. Once Transarc was formed and AFS became a
53			product, the "Andrew" was dropped to indicate that AFS had gone beyond
54			the Andrew research project and had become a supported, product quality
55			filesystem. However, there were a number of existing cells that rooted
56			their filesystem as /afs. At the time, changing the root of the filesystem
57			was a non-trivial undertaking. So, to save the early AFS sites from having
58			to rename their filesystem, AFS remained as the name and filesystem root.
59			</p>
60			</body>
61			</section>
62			<section>
63			<title>What is an AFS cell ?</title>
64			<body>
65			<p>An AFS cell is a collection of servers grouped together administratively
66			and presenting a single, cohesive filesystem. Typically, an AFS cell is a set of
67			hosts that use the same Internet domain name (like for example gentoo.org)
68			Users log into AFS client workstations which request information and files
69			from the cell's servers on behalf of the users. Users won't know on which server
70			a file which they are accessing, is located. They even won't notice if a server
71			will be located to another room, since every volume can be replicated and moved
72	swift	1.11	to another server without any user noticing. The files are always accessable.
73	drobbins	1.1	Well it's like NFS on steroids :)
74			</p>
75			</body>
76			</section>
77			<section>
78			<title>What are the benefits of using AFS ?</title>
79			<body>
80			<p>The main strengths of AFS are its:
81
82			caching facility (on client side, typically 100M to 1GB),
83			security features (Kerberos 4 based, access control lists),
84			simplicity of addressing (you just have one filesystem),
85			scalability (add further servers to your cell as needed),
86			communications protocol.
87			</p>
88			</body>
89			</section>
90			<section>
91			<title>Where can i get more information ?</title>
92			<body>
93			<p>
94			Read the <uri link="http://www.angelfire.com/hi/plutonic/afs-faq.html">AFS FAQ</uri>.
95			</p>
96			<p>
97			Openafs main page is at <uri link="http://www.openafs.org">www.openafs.org</uri>.
98			</p>
99			<p>
100			AFS was originally developed by Transarc which is now owned by IBM.
101			You can find some information about AFS on
102			<uri link="http://www.transarc.ibm.com/Product/EFS/AFS/index.html">Transarcs Webpage</uri>
103			</p>
104			</body>
105			</section>
106
107			</chapter>
108
109			<chapter>
110			<title>Documentation</title>
111			<section>
112			<title>Getting AFS Documentation</title>
113			<body>
114			<p>
115			You can get the original IBM AFS Documentation. It is very well written and you
116			really want
117			read it if it is up to you to administer a AFS Server.
118			</p>
119			<pre>
120			# <i>emerge app-doc/afsdoc</i>
121			</pre>
122			</body>
123			</section>
124			</chapter>
125
126			<chapter>
127			<title>Client Installation</title>
128			<section>
129			<title>Preliminary Work</title>
130			<body>
131			<note>
132	swift	1.11	All commands should be written in one line !! In this document they are
133	drobbins	1.1	sometimes wrapped to two lines to make them easier to read.
134			</note>
135			<note>
136			Unfortunately the AFS Client needs a ext2 partiton for it's cache to run
137			correctly, because there are some locking issues with reiserfs. You need to
138			create a ext2 partition of approx. 200MB (more won't hurt) and mount it to
139			<path>/usr/vice/cache</path>
140			</note>
141			<p>
142	swift	1.11	You should adjust the two files CellServDB and ThisCell before you build the
143			afs client. (These files are in <path>/usr/portage/net-fs/openafs/files</path>)
144	drobbins	1.1	</p>
145			<pre>
146			CellServDB:
147			>netlabs #Cell name
148			10.0.0.1 #storage
149
150			ThisCell:
151			netlabs
152			</pre>
153	swift	1.13
154			<warn>
155			Only use spaces inside the <path>CellServDB</path> file. The client will most
156			likely fail if you use TABs.
157			</warn>
158
159	drobbins	1.1	<p>
160			CellServDB tells your client which server(s) he needs to contact for a
161			specific cell. ThisCell should be quite obvious. Normally you use a name
162			which is unique for your organisation. Your (official) domain might be a
163			good choice.
164			</p>
165			</body>
166			</section>
167			<section>
168			<title>Building the Client</title>
169			<body>
170			<pre>
171	swift	1.11	# <i>emerge net-fs/openafs</i>
172	drobbins	1.1	</pre>
173			<p>
174	blubber	1.10	After successful compilation you're ready to go.
175	drobbins	1.1	</p>
176			</body>
177			</section>
178			<section>
179			<title>Starting afs on startup</title>
180			<body>
181			<p>
182			The following command will create the appropriate links to start your afs client
183			on system startup.
184			</p>
185			<warn>
186			You should always have a running afs server in your domain when trying to start the afs client. You're system won't boot
187			until it gets some timeout if your afs server is down. (and this is quite a long long time)
188			</warn>
189			<pre>
190			# <i>rc-update add afs default</i>
191			</pre>
192			</body>
193			</section>
194			</chapter>
195
196			<chapter>
197			<title>Server Installation</title>
198			<section>
199			<title>Building the Server</title>
200			<body>
201			<p>
202	swift	1.4	The following command will install all necessary binaries for setting up a AFS Server
203	cam	1.14	<e>and</e> Client.
204	drobbins	1.1	</p>
205			<pre>
206	swift	1.11	# <i>emerge net-fs/openafs</i>
207	drobbins	1.1	</pre>
208			</body>
209			</section>
210			<section>
211			<title>Starting AFS Server</title>
212			<body>
213			<p>
214			You need to remove the sample CellServDB and ThisCell file first.
215			</p>
216			<pre>
217			# <i>rm /usr/vice/etc/ThisCell</i>
218			# <i>rm /usr/vice/etc/CellServDB</i>
219			</pre>
220			<p>
221			Next you will run the <b>bosserver</b> command to initialize the Basic OverSeer (BOS)
222			Server, which monitors and controls other AFS server processes on its server
223			machine. Think of it as init for the system. Include the <b>-noauth</b>
224			flag to disable authorization checking, since you haven't added the admin user yet.
225			</p>
226			<warn>
227			Disabling authorization checking gravely compromises cell security.
228			You must complete all subsequent steps in one uninterrupted pass
229			and must not leave the machine unattended until you restart the BOS Server with
230			authorization checking enabled. Well this is what the AFS documentation says :)
231			</warn>
232			<pre>
233			# <i>/usr/afs/bin/bosserver -noauth &</i>
234			</pre>
235			<p>
236			Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path>
237			and <path>/usr/vice/etc/ThisCell</path>
238			</p>
239			<pre>
240			# <i>ls -al /usr/vice/etc/</i>
241			-rw-r--r-- 1 root root 41 Jun 4 22:21 CellServDB
242			-rw-r--r-- 1 root root 7 Jun 4 22:21 ThisCell
243			</pre>
244
245			</body>
246			</section>
247			<section>
248			<title>Defining Cell Name and Membership for Server Process</title>
249			<body>
250			<p>
251			Now assign your cells name.
252			</p>
253			<impo>There are some restrictions on the name format.
254			Two of the most important restrictions are that the name
255			cannot include uppercase letters or more than 64 characters. Remember that
256			your cell name will show up under <path>/afs</path>, so you might want to choose
257			a short one.</impo>
258	cam	1.14	<note>In the following and every instruction in this guide, for the <server name>
259	drobbins	1.1	argument substitute the full-qualified hostname
260			(such as <b>afs.gentoo.org</b>) of the machine you are installing.
261	cam	1.14	For the <cell name>
262	drobbins	1.1	argument substitute your cell's complete name (such as <b>gentoo</b>)</note>
263			<p>
264			Run the <b>bos setcellname</b> command to set the cell name:
265			</p>
266			<pre>
267	cam	1.14	# <i>/usr/afs/bin/bos setcellname <server name> <cell name> -noauth</i>
268			</pre>
269	drobbins	1.1	</body>
270			</section>
271			<section>
272			<title>Starting the Database Server Process</title>
273			<body><p>
274			Next use the <b>bos create</b> command to create entries for the four database
275			server processes in the
276			<path>/usr/afs/local/BosConfig</path> file. The four processes run on database
277			server machines only.
278			</p>
279	cam	1.14
280	drobbins	1.1	<table>
281			<tr>
282			<ti>kaserver</ti>
283	bennyc	1.8	<ti>The Authentication Server maintains the Authentication Database.
284	drobbins	1.1	This can be replaced by a Kerberos 5 daemon. If anybody want's to try that
285			feel free to update this document :)</ti>
286			</tr>
287			<tr>
288			<ti>buserver</ti>
289			<ti>The Backup Server maintains the Backup Database</ti>
290			</tr>
291			<tr>
292			<ti>ptserver</ti>
293			<ti>The Protection Server maintains the Protection Database</ti>
294			</tr>
295			<tr>
296			<ti>vlserver</ti>
297			<ti>The Volume Location Server maintains the Volume Location Database (VLDB).
298			Very important :)</ti>
299			</tr>
300			</table>
301			<pre>
302			# <i>/usr/afs/bin/bos create <server name> kaserver simple
303			/usr/afs/bin/kaserver -cell <cell name> -noauth</i>
304			# <i>/usr/afs/bin/bos create <server name> buserver simple
305			/usr/afs/bin/buserver -cell <cell name> -noauth</i>
306			# <i>/usr/afs/bin/bos create <server name> ptserver simple
307			/usr/afs/bin/ptserver -cell <cell name> -noauth</i>
308			# <i>/usr/afs/bin/bos create <server name> vlserver simple
309			/usr/afs/bin/vlserver -cell <cell name> -noauth</i>
310			</pre>
311			<p>
312			You can verify that all servers are running with the <b>bos status</b> command:
313			</p>
314			<pre>
315			# <i>/usr/afs/bin/bos status <server name> -noauth</i>
316			Instance kaserver, currently running normally.
317			Instance buserver, currently running normally.
318			Instance ptserver, currently running normally.
319			Instance vlserver, currently running normally.
320			</pre>
321
322			</body>
323			</section>
324			<section>
325			<title>Initializing Cell Security</title>
326			<body>
327			<p>
328			Now we'll initialize the cell's security mechanisms. We'll begin by creating the
329			following two initial entries in the
330	bennyc	1.8	Authentication Database: The main administrative account, called <b>admin</b> by
331	drobbins	1.1	convention and an entry for
332			the AFS server processes, called <b>afs</b>. No user logs in under the
333			identity <b>afs</b>, but the Authentication
334			Server's Ticket Granting Service (TGS) module uses the account
335			to encrypt the server tickets that it grants to AFS clients. This sounds
336			pretty much like Kerberos :)
337			</p>
338			<p>
339			Enter <b>kas</b> interactive mode
340			</p>
341			<pre>
342			# <i>/usr/afs/bin/kas -cell <cell name> -noauth</i>
343			ka> <i>create afs</i>
344			initial_password:
345			Verifying, please re-enter initial_password:
346			ka> <i>create admin</i>
347			initial_password:
348			Verifying, please re-enter initial_password:
349			ka> <i>examine afs</i>
350
351			User data for afs
352			key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:30 2001
353			password will never expire.
354			An unlimited number of unsuccessful authentications is permitted.
355			entry never expires. Max ticket lifetime 100.00 hours.
356			last mod on Mon Jun 4 20:49:30 2001 by $lt;none>
357			permit password reuse
358			ka> <i>setfields admin -flags admin</i>
359			ka> <i>examine admin</i>
360
361			User data for admin (ADMIN)
362			key (0) cksum is 2651715259, last cpw: Mon Jun 4 20:49:59 2001
363			password will never expire.
364			An unlimited number of unsuccessful authentications is permitted.
365			entry never expires. Max ticket lifetime 25.00 hours.
366			last mod on Mon Jun 4 20:51:10 2001 by $lt;none>
367			permit password reuse
368			ka>
369			</pre>
370			<p>
371			Run the <b>bos adduser</b> command, to add the <b>admin</b> user to
372			the <path>/usr/afs/etc/UserList</path>.
373			</p>
374			<pre>
375			# <i>/usr/afs/bin/bos adduser <server name> admin -cell <cell name> -noauth</i>
376			</pre>
377			<p>
378			Issue the <b>bos addkey</b> command to define the AFS Server
379			encryption key in <path>/usr/afs/etc/KeyFile</path>
380			</p>
381			<note>
382			If asked for the input key, give the password you entered when creating
383			the afs entry with <b>kas</b>
384			</note>
385			<pre>
386			# <i>/usr/afs/bin/bos addkey <server name> -kvno 0 -cell <cell name> -noauth</i>
387			input key:
388			Retype input key:
389			</pre>
390			<p>
391			Issue the <b>pts createuser</b> command to create a Protection Database
392			entry for the admin user
393			</p>
394			<note>
395			By default, the Protection Server assigns AFS UID 1 to the <b>admin</b> user, because
396			it is the first user
397			entry you are creating. If the local password file (/etc/passwd or equivalent)
398			already has an entry for
399			<b>admin</b> that assigns a different UID use the <b>-id</b> argument
400			to create matching UID's
401			</note>
402			<pre>
403			# <i>/usr/afs/bin/pts createuser -name admin -cell <cell name> [-id <AFS UID>] -noauth</i>
404			</pre>
405			<p>
406			Issue the <b>pts adduser</b> command to make the <b>admin</b> user a member
407			of the system:administrators group,
408	swift	1.5	and the <b>pts membership</b> command to verify the new membership
409	drobbins	1.1	</p>
410			<pre>
411			# <i>/usr/afs/bin/pts adduser admin system:administrators -cell <cell name> -noauth</i>
412			# <i>/usr/afs/bin/pts membership admin -cell <cell name> -noauth</i>
413			Groups admin (id: 1) is a member of:
414			system:administrators
415			</pre>
416			<p>
417			Restart all AFS Server processes
418			</p>
419			<pre>
420			# <i>/usr/afs/bin/bos restart <server name> -all -cell <cell name> -noauth</i>
421			</pre>
422			</body>
423			</section>
424			<section>
425			<title>Starting the File Server, Volume Server and Salvager</title>
426			<body>
427			<p>
428	swift	1.5	Start the <b>fs</b> process, which consists of the File Server, Volume Server and Salvager (fileserver,
429	drobbins	1.1	volserver and salvager processes).
430			</p>
431			<pre>
432			# <i>/usr/afs/bin/bos create <server name> fs fs /usr/afs/bin/fileserver
433			/usr/afs/bin/volserver
434			/usr/afs/bin/salvager
435			-cell <cell name> -noauth</i>
436			</pre>
437			<p>
438			Verify that all processes are running
439			</p>
440			<pre>
441			# <i>/usr/afs/bin/bos status <server name> -long -noauth</i>
442			Instance kaserver, (type is simple) currently running normally.
443			Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
444			Last exit at Mon Jun 4 21:07:17 2001
445			Command 1 is '/usr/afs/bin/kaserver'
446
447			Instance buserver, (type is simple) currently running normally.
448			Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
449			Last exit at Mon Jun 4 21:07:17 2001
450			Command 1 is '/usr/afs/bin/buserver'
451
452			Instance ptserver, (type is simple) currently running normally.
453			Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
454			Last exit at Mon Jun 4 21:07:17 2001
455			Command 1 is '/usr/afs/bin/ptserver'
456
457			Instance vlserver, (type is simple) currently running normally.
458			Process last started at Mon Jun 4 21:07:17 2001 (2 proc starts)
459			Last exit at Mon Jun 4 21:07:17 2001
460			Command 1 is '/usr/afs/bin/vlserver'
461
462			Instance fs, (type is fs) currently running normally.
463			Auxiliary status is: file server running.
464			Process last started at Mon Jun 4 21:09:30 2001 (2 proc starts)
465			Command 1 is '/usr/afs/bin/fileserver'
466			Command 2 is '/usr/afs/bin/volserver'
467			Command 3 is '/usr/afs/bin/salvager'
468			</pre>
469			<p>
470			Your next action depends on whether you have ever run AFS file server machines
471			in the cell:
472			</p>
473			<p>
474			If you are installing the first AFS Server ever in the cell create the
475			first AFS volume, <b>root.afs</b>
476			</p>
477			<note>
478			For the partition name argument, substitute the name of one of the machine's
479			AFS Server partitions. By convention
480	swift	1.15	these partitions are named <path>/vicepx</path>, where x is in the range of a-z.
481	drobbins	1.1	</note>
482			<pre>
483			# <i>/usr/afs/bin/vos create <server name>
484			<partition name> root.afs
485			-cell <cell name> -noauth</i>
486			</pre>
487			<p>
488			If there are existing AFS file server machines and volumes in the cell
489			issue the <b>vos sncvldb</b> and <b>vos
490			syncserv</b> commands to synchronize the VLDB (Volume Location Database) with
491			the actual state of volumes on the local machine. This will copy all necessary data to your
492			new server.
493			</p>
494	swift	1.15	<p>
495			If the command fails with the message "partition /vicepa does not exist on
496			the server" ensure that the partition is mounted before runningt OpenAFS
497			servers, or mount the directory and restart the processes using
498			<c>/usr/afs/bin/bos restart <server name> -all -cell <cell
499			name> -noauth</c>.
500			</p>
501	drobbins	1.1	<pre>
502			# <i>/usr/afs/bin/vos syncvldb <server name> -cell <cell name> -verbose -noauth</i>
503			# <i>/usr/afs/bin/vos syncserv <server name> -cell <cell name> -verbose -noauth</i>
504			</pre>
505			</body>
506			</section>
507			<section>
508			<title>Starting the Server Portion of the Update Server</title>
509			<body>
510			<pre>
511			# <i>/usr/afs/bin/bos create <server name>
512			upserver simple "/usr/afs/bin/upserver
513			-crypt /usr/afs/etc -clear /usr/afs/bin"
514			-cell <cell name> -noauth</i>
515			</pre>
516			</body>
517			</section>
518			<section>
519			<title>Configuring the Top Level of the AFS filespace</title>
520			<body>
521			<p>
522			First you need to set some acl's, so that any user can lookup <path>/afs</path>.
523			</p>
524			<pre>
525			# <i>/usr/afs/bin/fs setacl /afs system:anyuser rl</i>
526			</pre>
527			<p>
528	swift	1.6	Then you need to create the root volume, mount it readonly on <path>/afs/<cell name></path> and read/write
529	drobbins	1.1	on <path>/afs/.<cell name></path>
530	cam	1.14	</p>
531	drobbins	1.1	<pre>
532			# <i>/usr/afs/bin/vos create <server name><partition name> root.cell</i>
533			# <i>/usr/afs/bin/fs mkmount /afs/<cell name> root.cell </i>
534			# <i>/usr/afs/bin/fs setacl /afs/<cell name> system:anyuser rl</i>
535	cam	1.14	# <i>/usr/afs/bin/fs mkmount /afs/.<cell name> root.cell -rw</i>
536	drobbins	1.1	</pre>
537			<p>
538			Finally you're done !!! You should now have a working AFS file server
539			on your local network. Time to get a big
540			cup of coffee and print out the AFS documentation !!!
541			</p>
542			<note>
543			It is very important for the AFS server to function properly, that all system
544			clock's are synchronized.
545			This is best
546			accomplished by installing a ntp server on one machine (e.g. the AFS server)
547			and synchronize all client clock's
548			with the ntp client. This can also be done by the afs client.
549			</note>
550			</body>
551			</section>
552
553			</chapter>
554
555			<chapter>
556			<title>Basic Administration</title>
557			<section>
558			<title></title>
559			<body>
560			<p>To be done ... For now read the AFS Documentation :)</p>
561			</body>
562			</section>
563			</chapter>
564			</guide>