neysx 07/06/29 08:33:12 Modified: openafs.xml Log: Update from #176407
Revision Changes Path 1.24 xml/htdocs/doc/en/openafs.xml file : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/openafs.xml?rev=1.24&view=markup plain: http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/openafs.xml?rev=1.24&content-type=text/plain diff : http://sources.gentoo.org/viewcvs.py/gentoo/xml/htdocs/doc/en/openafs.xml?r1=1.23&r2=1.24 Index: openafs.xml =================================================================== RCS file: /var/cvsroot/gentoo/xml/htdocs/doc/en/openafs.xml,v retrieving revision 1.23 retrieving revision 1.24 diff -u -r1.23 -r1.24 --- openafs.xml 9 Nov 2005 20:58:07 -0000 1.23 +++ openafs.xml 29 Jun 2007 08:33:12 -0000 1.24 @@ -1,5 +1,5 @@ <?xml version='1.0' encoding="UTF-8"?> -<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openafs.xml,v 1.23 2005/11/09 20:58:07 fox2mike Exp $ --> +<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/openafs.xml,v 1.24 2007/06/29 08:33:12 neysx Exp $ --> <!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> @@ -7,6 +7,9 @@ <title>Gentoo Linux OpenAFS Guide</title> <author title="Editor"> + <mail link="[EMAIL PROTECTED]">Stefaan De Roeck</mail> +</author> +<author title="Editor"> <mail link="[EMAIL PROTECTED]">Holger Brueckner</mail> </author> <author title="Editor"> @@ -19,9 +22,6 @@ <mail link="[EMAIL PROTECTED]">Steven McCoy</mail> </author> <author title="Editor"> - <mail link="[EMAIL PROTECTED]">Stefaan De Roeck</mail> -</author> -<author title="Editor"> <mail link="[EMAIL PROTECTED]">Shyam Mani</mail> </author> @@ -34,8 +34,8 @@ <!-- See http://creativecommons.org/licenses/by-sa/2.5 --> <license/> -<version>1.1</version> -<date>2005-11-10</date> +<version>1.2</version> +<date>2007-06-29</date> <chapter> <title>Overview</title> @@ -44,7 +44,7 @@ <body> <p> -This document provides you with all neccessary steps to install an OpenAFS +This document provides you with all necessary 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> @@ -78,7 +78,7 @@ </p> </body> -</section> +</section> <section> <title>What is an AFS cell?</title> <body> @@ -92,11 +92,11 @@ 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 -accessible. Well, it's like NFS on steroids :) +accessible. Well, it's like NFS on steroids :) </p> </body> -</section> +</section> <section> <title>What are the benefits of using AFS?</title> <body> @@ -111,7 +111,7 @@ </p> </body> -</section> +</section> <section> <title>Where can I get more information?</title> <body> @@ -134,7 +134,7 @@ </p> </body> -</section> +</section> <section> <title>How Can I Debug Problems?</title> <body> @@ -160,7 +160,7 @@ This section aims to help you through the process of upgrading an existing OpenAFS installation to OpenAFS version 1.4.0 or higher (or 1.2.x starting from 1.2.13. The latter will not be handled specifically, as most people will want -1.4 for a.o.linux-2.6 support, large file support and bug fixes). +1.4 for a.o. linux-2.6 support, large file support and bug fixes). </p> <p> @@ -168,7 +168,7 @@ safely skip this chapter. However, if you're upgrading from a previous version, we strongly urge you to follow the guidelines in the next sections. The transition script in the ebuild is designed to assist you in quickly upgrading -and restarting. Please not that it will (for safety reasons) not delete +and restarting. Please note that it will (for safety reasons) not delete configuration files and startup scripts in old places, not automatically change your boot configuration to use the new scripts, etc. If you need further convincing, using an old OpenAFS kernel module together with the updated system @@ -289,7 +289,7 @@ into <path>/etc/conf.d/openafs-client</path> and <path>/etc/conf.d/openafs-server</path>. Also, options in <path>/etc/conf.d/afs</path> to turn either client or server on or off have -been obsoleted. +been obsoleted. </p> <p> @@ -309,7 +309,7 @@ <li> Some people use soft-links to point to the real disk cache location. The init script didn't like this, because then this cache location - didn't turn up in <path>/proc/mounts</path>. + didn't turn up in <path>/proc/mounts</path>. </li> <li> Many prefer ext3 over ext2 nowadays. Both filesystems are valid for @@ -342,7 +342,7 @@ </p> <pre caption="Checking your CONFIG_PROTECT_MASK"> -# <i>emerge info | grep "CONFIG_PROTECT_MASK</i> +# <i>emerge info | grep "CONFIG_PROTECT_MASK"</i> CONFIG_PROTECT_MASK="/etc/gconf /etc/terminfo /etc/texmf/web2c /etc/env.d" </pre> @@ -367,7 +367,7 @@ <ul> <li> - <path>/usr/afs/etc</path> is copied to<path>/etc/openafs/server</path> + <path>/usr/afs/etc</path> is copied to <path>/etc/openafs/server</path> </li> <li> <path>/usr/vice/etc</path> is copied to <path>/etc/openafs</path> @@ -378,7 +378,7 @@ <li> <path>/usr/afs/local/BosConfig</path> is copied to <path>/etc/openafs/BosConfig</path>, while replacing occurrences of - <path>/usr/afs/bin/</path> with <path>/usr/libexec/openafs</path>, + <path>/usr/afs/bin/</path> with <path>/usr/libexec/openafs</path>, <path>/usr/afs/etc</path> with <path>/etc/openafs/server</path> and <path>/usr/afs/bin</path> (without the / as previously) with <path>/usr/bin</path> @@ -459,7 +459,7 @@ <p> Before starting the OpenAFS client again, please take time to check your -cache settings. They are determined by <path>/etc/openafs/cacheinfo</path>. +cache settings. They are determined by <path>/etc/openafs/cacheinfo</path>. To restart your OpenAFS client installation, please type the following: </p> @@ -533,7 +533,7 @@ the OpenAFS client and server on startup. Those who don't can safely skip this section. If you had your system configured to start them automatically, you will need to re-enable this, because the names of the init scripts have -changed. +changed. </p> <pre caption="Re-enabling OpenAFS startup at boot time"> @@ -555,10 +555,10 @@ <body> <p> -Don't panic. You shouldn't have lost any data or configuration files. So -let's analyze the situation. Please file a bug at -<uri link="http://bugs.gentoo.org";>bugs.gentoo.org</uri> in any case, -preferably with as much information as possible. +Don't panic. You shouldn't have lost any data or configuration files. So let's +analyze the situation. Please file a bug at <uri +link="http://bugs.gentoo.org";>bugs.gentoo.org</uri> in any case, preferably +with as much information as possible. </p> <p> @@ -572,7 +572,7 @@ </li> <li> Check <path>/etc/openafs/cacheinfo</path>. It should be of the form: - /afs:{path to disk cache}:{number of blocks for disk cache}. + /afs:{path to disk cache}:{number of blocks for disk cache}. Normally, your disk cache will be located at <path>/var/cache/openafs</path>. </li> @@ -638,7 +638,7 @@ Documentation. </p> -</body> +</body> </section> </chapter> @@ -648,11 +648,6 @@ <title>Building the Client</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> - <pre caption="Installing openafs"> # <i>emerge net-fs/openafs</i> </pre> @@ -702,7 +697,7 @@ 10.0.0.1 #storage ThisCell: -netlabs +netlabs </pre> <warn> @@ -711,7 +706,14 @@ </warn> <p> -For a quick start, you can now start <path>/etc/init.d/openafs/client</path> and +CellServDB tells your client which server(s) it 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> + +<p> +For a quick start, you can now start <path>/etc/init.d/openafs-client</path> and use <c>klog</c> to authenticate yourself and start using your access to the cell. For automatic logons to you cell, you want to consult the appropriate section below. @@ -725,12 +727,13 @@ <note> Unfortunately the AFS Client needs a ext2/3 filesystem for its cache to run -correctly, because there are some issues with reiserfs. +correctly. There are some issues when using other filesystems (using e.g. +reiserfs is not a good idea). </note> <p> -You can house your cache on an existing filesystem (if it's ext2/3), but some -may want to create a separate partition for that. The default location of the +You can house your cache on an existing filesystem (if it's ext2/3), or you +may want to have a separate partition for that. The default location of the cache is <path>/var/cache/openafs</path>, but you can change that by editing <path>/etc/openafs/cacheinfo</path>. A standard size for your cache is 200MB, but more won't hurt. @@ -739,39 +742,6 @@ </body> </section> <section> -<title>Adjusting the cell access configuration</title> -<body> - -<p> -In case you want to do more than just read-only browsing of globally available -AFS cells, you need to adjust the two files CellServDB and ThisCell. These -are located in <path>/etc/openafs</path>. -</p> - -<pre caption="Adjusting CellServDB and ThisCell"> -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) it 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>Starting AFS on startup</title> <body> @@ -786,8 +756,8 @@ if your AFS server is down. (And this is quite a long long time) </warn> -<pre caption="Adding AFS server to the default runlevel"> -# <i>rc-update add openafs-server default</i> +<pre caption="Adding AFS client to the default runlevel"> +# <i>rc-update add openafs-client default</i> </pre> </body> @@ -800,9 +770,14 @@ <title>Building the Server</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> + <p> -The following command will install all necessary binaries for setting up an AFS -Server <e>and</e> Client. +If you haven't already done so, the following command will install all +necessary binaries for setting up an AFS Server <e>and</e> Client. </p> <pre caption="Installing openafs"> @@ -812,20 +787,11 @@ </body> </section> <section> -<title>Starting AFS Server</title> +<title>Starting AFS Server</title> <body> <p> -You need to remove the sample CellServDB and ThisCell file first. -</p> - -<pre caption="Remove sample files"> -# <i>rm /usr/vice/etc/ThisCell</i> -# <i>rm /usr/vice/etc/CellServDB</i> -</pre> - -<p> -Next you will run the <c>bosserver</c> command to initialize the Basic OverSeer +You need to run the <c>bosserver</c> 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 <c>-noauth</c> flag to disable authorization checking, since you haven't added the admin user @@ -844,17 +810,17 @@ </pre> <p> -Verify that the BOS Server created <path>/usr/vice/etc/CellServDB</path> -and <path>/usr/vice/etc/ThisCell</path> +Verify that the BOS Server created <path>/etc/openafs/server/CellServDB</path> +and <path>/etc/openafs/server/ThisCell</path> </p> <pre caption="Check if CellServDB and ThisCell are created"> -# <i>ls -al /usr/vice/etc/</i> +# <i>ls -al /etc/openafs/server/</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> +</body> </section> <section> <title>Defining Cell Name and Membership for Server Process</title> @@ -894,8 +860,8 @@ <body> <p> -Next use the <c>bos create</c> command to create entries for the four database -server processes in the <path>/etc/openafs/BosConfig</path> file. The four +Next use the <c>bos create</c> command to create entries for the four database +server processes in the <path>/etc/openafs/BosConfig</path> file. The four processes run on database server machines only. </p> @@ -923,13 +889,21 @@ Very important :) </ti> </tr> -</table> +</table> <pre caption="Create entries for the database processes"> -# <i>bos create <server name> kaserver simple /usr/libexec/openafs/kaserver -cell <cell name> -noauth</i> -# <i>bos create <server name> buserver simple /usr/libexec/openafs/buserver -cell <cell name> -noauth</i> -# <i>bos create <server name> ptserver simple /usr/libexec/openafs/ptserver -cell <cell name> -noauth</i> -# <i>bos create <server name> vlserver simple /usr/libexec/openafs/vlserver -cell <cell name> -noauth</i> +# <i>bos create <server name> kaserver \ +simple /usr/libexec/openafs/kaserver \ +-cell <cell name> -noauth</i> +# <i>bos create <server name> buserver \ +simple /usr/libexec/openafs/buserver \ +-cell <cell name> -noauth</i> +# <i>bos create <server name> ptserver \ +simple /usr/libexec/openafs/ptserver \ +-cell <cell name> -noauth</i> +# <i>bos create <server name> \ +vlserver simple /usr/libexec/openafs/vlserver \ +-cell <cell name> -noauth</i> </pre> <p> @@ -995,7 +969,7 @@ </pre> <p> -Run the <c>bos adduser</c> command, to add the <b>admin</b> user to +Run the <c>bos adduser</c> command, to add the <b>admin</b> user to the <path>/etc/openafs/server/UserList</path>. </p> @@ -1004,7 +978,7 @@ </pre> <p> -Issue the <c>bos addkey</c> command to define the AFS Server +Issue the <c>bos addkey</c> command to define the AFS Server encryption key in <path>/etc/openafs/server/KeyFile</path> </p> @@ -1049,13 +1023,50 @@ system:administrators </pre> +</body> +</section> +<section> +<title>Properly (re-)starting the AFS server</title> +<body> + +<p> +At this moment, proper authentication is possible, and the OpenAFS server can +be started in a normal fashion. Note that authentication also requires a +running OpenAFS client (set it up is described in the previous chapter). +<!-- Left out because deemed confusing> +Continuing without this step is possible, but in that case a quick restart of +the server is required, as demonstrated at the end of this section. +<--> +</p> + +<pre caption="Shutdown bosserver"> +# <i>bos shutdown <server name> -wait -noauth</i> +# <i>killall bosserver</i> +</pre> + +<pre caption="Normal OpenAFS server (and client) startup"> +# <i>/etc/init.d/openafs-server start</i> +# <i>/etc/init.d/openafs-client start</i> +</pre> + +<pre caption="Adding AFS server to the default runlevel"> +# <i>rc-update add openafs-server default</i> +</pre> + +<pre caption="Getting a token as the admin user"> +# <i>klog admin</i> +</pre> + +<!-- Left out because deemed confusing> <p> -Restart all AFS Server processes +If you chose not to restart OpenAFS without the -noauth flag, you can simply +perform the following procedure instead: </p> <pre caption="Restart all AFS server processes"> # <i>bos restart <server name> -all -cell <cell name> -noauth</i> </pre> +<--> </body> </section> @@ -1064,18 +1075,18 @@ <body> <p> -Start the <c>fs</c> process, which consists of the -File Server, -Volume Server and Salvager (fileserver, -volserver and salvager processes). +Start the <c>fs</c> process, which consists of the File Server, Volume Server +and Salvager (fileserver, volserver and salvager processes). </p> <pre caption="Start the fs process"> -# <i>bos create <server name> fs fs /usr/libexec/openafs/fileserver /usr/libexec/openafs/volserver /usr/libexec/openafs/salvager -cell <cell name> -noauth</i> +# <i>bos create <server name> fs \ +fs /usr/libexec/openafs/fileserver /usr/libexec/openafs/volserver /usr/libexec/openafs/salvager \ +-cell <cell name> -noauth</i> </pre> <p> -Verify that all processes are running +Verify that all processes are running: </p> <pre caption="Check if all processes are running"> @@ -1114,14 +1125,19 @@ </p> <p> -If you are installing the first AFS Server ever in the cell create the -first AFS volume, <b>root.afs</b> +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. +AFS Server partitions. Any filesystem mounted under a directory called +<path>/vicepx</path>, where x is in the range of a-z, will be considered and +used as an AFS Server partition. Any unix filesystem will do (as opposed to the +client's cache, which can only be ext2/3). Tip: the server checks for each +<path>/vicepx</path> mount point whether a filesystem is mounted there. If not, +the server will not attempt to use it. This behaviour can be overridden by +putting a file named <path>AlwaysAttach</path> in this directory. </note> <pre caption="Create the root.afs volume"> @@ -1145,7 +1161,7 @@ <pre caption="Synchronise the VLDB"> # <i>vos syncvldb <server name> -cell <cell name> -verbose -noauth</i> -# <i>vos syncserv <server name> -cell <cell name> -verbose -noauth</i> +# <i>vos syncserv <server name> -cell <cell name> -verbose -noauth</i> </pre> </body> @@ -1155,9 +1171,9 @@ <body> <pre caption="Start the update server"> -# <i>bos create <server name> -upserver simple "/usr/libexec/openafs/upserver --crypt /etc/openafs/server -clear /usr/libexec/openafs" +# <i>bos create <server name> \ +upserver simple "/usr/libexec/openafs/upserver \ +-crypt /etc/openafs/server -clear /usr/libexec/openafs" \ -cell <cell name> -noauth</i> </pre> @@ -1172,6 +1188,16 @@ <path>/afs</path>. </p> +<note> +The default OpenAFS client configuration has <b>dynroot</b> enabled. +This option turns <path>/afs</path> into a virtual directory composed of the +contents of your <path>/etc/openafs/CellServDB</path> file. As such, the +following command will not work, because it requires a real AFS directory. +You can temporarily switch dynroot off by setting <b>ENABLE_DYNROOT</b> to +<b>no</b> in <path>/etc/conf.d/openafs-client</path>. Don't forget to issue +a client after changing parameters. +</note> + <pre caption="Set access control lists"> # <i>fs setacl /afs system:anyuser rl</i> </pre> @@ -1183,12 +1209,19 @@ </p> <pre caption="Prepare the root volume"> -# <i>vos create <server name><partition name> root.cell</i> -# <i>fs mkmount /afs/<cell name> root.cell </i> +# <i>vos create <server name> <partition name> root.cell</i> +# <i>fs mkmount /afs/<cell name> root.cell</i> # <i>fs setacl /afs/<cell name> system:anyuser rl</i> # <i>fs mkmount /afs/.<cell name> root.cell -rw</i> </pre> +<pre caption="Adding volumes underneath"> +# <i>vos create <server name> <partition name> <myvolume></i> +# <i>fs mkmount /afs/<cell name>/<mymountpoint> <myvolume></i> +# <i>fs mkmount /afs/<cell name>/.<mymountpoint> <myvolume> -rw</i> +# <i>fs setquota /afs/<cell name>/.<mymountpoint> -max <quotum></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 -- [EMAIL PROTECTED] mailing list
