src/packaging/Debian/README.servers

   1                     Setting up a Debian OpenAFS Server
   2
   3 Introduction
   4
   5   This document describes how to set up an OpenAFS server using the Debian
   6   packages.  If you are not already familiar with the basic concepts of
   7   OpenAFS, you should review the documentation at:
   8
   9       <http://www.openafs.org/doc/index.htm>
  10
  11   particularly the AFS Administrator's Guide.  This documentation is
  12   somewhat out of date (it doesn't talk about how to use a Kerberos v5 KDC
  13   instead of the AFS kaserver, for example), but it's a good introduction
  14   to the basic concepts and servers you will need to run.
  15
  16   The Debian OpenAFS packages follow the FHS and therefore use different
  17   paths than the standard AFS documentation or the paths that experienced
  18   AFS administrators may be used to.  In the first column below are the
  19   traditional paths, and in the second column, the Debian paths:
  20
  21       /usr/afs/etc        /etc/openafs/server
  22       /usr/afs/local      /var/lib/openafs/local
  23       /usr/afs/db         /var/lib/openafs/db
  24       /usr/afs/logs       /var/log/openafs
  25       /usr/afs/bin        /usr/lib/openafs
  26       /usr/vice/etc       /etc/openafs
  27
  28   The AFS kaserver (a Kerberos v4 KDC) is not packaged for Debian.  Any
  29   new OpenAFS installation should use Kerberos v5 for authentication in
  30   conjunction with either the tools packaged in the openafs-krb5 package
  31   or the Heimdal KDC.  When setting up a new cell, you should therefore
  32   not set up a kaserver as described in the AFS Administrator's Guide, and
  33   you will need to follow a slightly different method of setting the cell
  34   key.
  35
  36 Creating a New Cell
  37
  38   For documentation on adding a server to an existing cell, see below.
  39
  40   These instructions assume that you are using MIT Kerberos and the
  41   openafs-krb5 package.  If you are using Heimdal instead, some of the
  42   steps will be slightly different (Heimdal can write the AFS KeyFile
  43   directly, for example, so you don't have to use asetkey).  The
  44   afs-newcell and afs-rootvol scripts are the same, however.
  45
  46   /usr/share/doc/openafs-dbserver/configuration-transcript.txt.gz has a
  47   transcript of the results of these directions, which you may want to
  48   follow along with as you do this.
  49
  50   1.  If you do not already have a Kerberos KDC (Key Distribution Center,
  51       the daemon that handles Kerberos authentication) configured, do so.
  52       You can run the KDC on the same system as your OpenAFS db server,
  53       although if you plan on using Kerberos for other things, you may
  54       eventually want to use separate systems.  If you do not have a
  55       Kerberos realm set up already, you can do so in Debian with:
  56
  57           apt-get install krb5-admin-server
  58           krb5_newrealm
  59
  60       This will install a KDC and kadmind server (the server that handles
  61       password changes and account creations) on the local system.  Please
  62       be aware that the security of everything that uses Kerberos for
  63       authentication, including AFS, depends on the security of the KDC.
  64
  65       The name of your Kerberos realm should, for various reasons, be in
  66       all uppercase and be a domain name that you control, although
  67       neither is technically required.
  68
  69   2.  It is traditional (and recommended) in AFS (and for Kerberos) to
  70       give administrators two separate Kerberos principals, one regular
  71       principal to use for regular purposes and a separate admin principal
  72       to use for privileged actions.  This is similar to the distinction
  73       between a regular user and the root user in Unix, except that
  74       everyone can have their own separate root identity.  Kerberos
  75       recommends username/admin as the admin principal for username, and
  76       this will work for AFS as well.
  77
  78       If you have not already created such an admin principal for yourself
  79       in your Kerberos realm, do so now (using kadmin.local on your KDC,
  80       unless you have a local method that you prefer).  Also create a
  81       regular (non-admin) principal for yourself if you have not already;
  82       this is the identity that you'll use for regular operations, like
  83       storing files or reading mail.  To do this with kadmin.local, run
  84       that program and then run the commands:
  85
  86           addprinc username/admin
  87           addprinc username
  88
  89       at the kadmin prompt.  You'll be prompted for passwords for both
  90       accounts.
  91
  92       If the KDC is not on the same system that the OpenAFS db server will
  93       be on, you will also need to give your admin principal the rights to
  94       download the afs keytab in /etc/krb5kdc/kadm5.acl by adding a lines
  95       like:
  96
  97           username/admin@REALM    *
  98
  99       where REALM is your Kerberos realm and username/admin is the admin
 100       principal that you created.  That line gives you full admin access
 101       to the Kerberos v5 realm.  You can be more restrictive if you want;
 102       see the kadmind man page for the syntax.
 103
 104   3.  Install the OpenAFS db server package on an appropriate system with:
 105
 106           apt-get install openafs-dbserver openafs-krb5
 107
 108       The openafs-krb5 package will be used to create the AFS KeyFile.
 109
 110       As part of this installation, you will need to configure
 111       openafs-client with the cell you are creating as the local cell name
 112       and the server on which you're working as the db server.  This name
 113       is technically arbitrary but should, for various reasons, be a valid
 114       domain name that you control; unlike Kerberos realms, it should be
 115       in all lowercase.  Enter the name of the local system when prompted
 116       for the names of your OpenAFS db servers.  Don't start the client;
 117       that will happen below.  For right now, say that you don't want it
 118       to start at boot.  You can change that later with dpkg-reconfigure
 119       openafs-client.
 120
 121       If you have already installed openafs-client and configured it for
 122       some other cell, you do need to configure it to point to your new
 123       cell for these instructions to work.  Stop the AFS client on the
 124       system with /etc/init.d/openafs-client stop and then run:
 125
 126            dpkg-reconfigure openafs-client
 127
 128       pointing it to the new cell you're about to create instead.
 129       Remember, your cell name should be in lowercase.  If you have had to
 130       do this several times, double-check /etc/openafs/CellServDB when
 131       you're done and make sure that there is only one entry for your new
 132       cell at the top of that file and that it lists the correct IP
 133       address for your new db server.
 134
 135       In order to complete the AFS installation, you will also need a
 136       working AFS client installed on that system, which means that you
 137       need to install an OpenAFS kernel module.  Please see:
 138
 139           /usr/share/doc/openafs-client/README.modules
 140
 141       for information on how to do that.
 142
 143   4.  Create an AFS principal in Kerberos.  This is the AFS service
 144       principal, used by clients to authenticate to AFS and for AFS
 145       servers to authenticate to each other.  It *must* be a DES key; AFS
 146       does not support any other encryption type.  Run kadmin.local on
 147       your KDC and then, at the kadmin.local prompt, run:
 148
 149           addprinc -randkey -e des-cbc-crc:v4 afs
 150
 151       If your Kerberos realm name does not match your AFS cell name (if,
 152       for instance, you have one Kerberos realm with multiple AFS cells),
 153       use "afs/cell.name" as the name of the principal above instead of
 154       just "afs", where cell.name is the name of your new AFS cell.
 155
 156   5.  On the db server, download this key into a keytab.  If this is the
 157       same system as the KDC, you can use kadmin.local again.  If not, you
 158       should use kadmin (make sure that krb5-user is installed), and you
 159       may need to pass -p username/admin to kadmin to tell it what
 160       principal to authenticate as.  Whichever way you get into kadmin,
 161       run:
 162
 163           ktadd -k /tmp/afs.keytab -e des-cbc-crc:v4 afs
 164
 165       (or afs/cell.name if you used that instead).  In the message that
 166       results, note the kvno number reported, since you'll need it later
 167       (it will normally be 3).
 168
 169       Don't forget the -e des-cbc-crc:v4 to force the afs key to be DES.
 170       You can verify this with:
 171
 172           getprinc afs
 173
 174       and checking to be sure that the only key listed is a DES key.  If
 175       there are multiple keys listed, delprinc the afs principal, delete
 176       the /tmp/afs.keytab file, and then start over with addprinc, making
 177       sure not to forget the -e option.
 178
 179   6.  Create the AFS KeyFile with:
 180
 181           asetkey add <kvno> /tmp/afs.keytab afs
 182
 183       (or afs/cell.name if you used that instead).  <kvno> should be
 184       replaced by the kvno number reported by kadmin.  This tells AFS the
 185       Kerberos key that it should use, making it match the key in the
 186       Kerberos KDC.
 187
 188   7.  If the name of your Kerberos realm does not match the name of your
 189       AFS cell, tell AFS what Kerberos realm to use with:
 190
 191           echo REALM > /etc/openafs/server/krb.conf
 192
 193       where REALM is the name of your Kerberos realm.  If your AFS cell
 194       and Kerberos realm have the same name, this is unnecessary.
 195
 196   8.  Create some space to use for AFS volumes.  You can set up a separate
 197       AFS file server on a different system from the Kerberos KDC and AFS
 198       db server, and for a larger cell you will want to do so, but when
 199       getting started you can make the db server a file server as well.
 200       For a production cell, you will want to create a separate partition
 201       devoted to AFS and mount it as /vicepa (and may want to make
 202       multiple partitions mounted as /vicepb, /vicepc, etc.), but for
 203       testing purposes, you can use the commands below to create a
 204       zero-filled file, create a file system in it, and then mount it:
 205
 206           dd if=/dev/zero of=/var/lib/openafs/vicepa bs=1024k count=32
 207           mke2fs /var/lib/openafs/vicepa
 208           mkdir /vicepa
 209           mount -oloop /var/lib/openafs/vicepa /vicepa
 210
 211       mke2fs will ask you if you're sure you want to create a file system
 212       on a non-block device; say yes.
 213
 214   9.  Run afs-newcell.  This will prompt you to be sure that the above
 215       steps have been complete and will ask you for the Kerberos principal
 216       to use for AFS administrative access.  You should use the
 217       username/admin principal discussed above.  afs-newcell sets up the
 218       initial protection database (which stores users and groups),
 219       configures the AFS database and file server daemons, and creates the
 220       root volume for AFS clients.
 221
 222       At the completion of this step, you should see bosserver and several
 223       other AFS server processes running, and you should be able to see
 224       the status of those processes with:
 225
 226           bos status localhost -local
 227
 228       bosserver is a master server that starts and monitors all the
 229       individual AFS servers, and bos is the program used to send it
 230       commands.
 231
 232       Now, you should be able to run:
 233
 234           kinit username/admin@REALM
 235           aklog cell.name -k REALM
 236
 237       where username/admin is the admin principal discussed above, REALM
 238       is the name of your Kerberos realm, and cell.name is the name of
 239       your AFS cell.  This will obtain Kerberos tickets and AFS tokens in
 240       your Kerberos realm and new AFS cell.  You should be able to see
 241       your AFS tokens by running:
 242
 243           tokens
 244
 245       Finally, you should be able to see the status of the AFS server
 246       processes with:
 247
 248           bos status <hostname>
 249
 250       where <hostname> is the hostname of the local system, once you've
 251       done the above.  This tests authenticated bos access as your admin
 252       principal (rather than using the local KeyFile to authenticate).
 253
 254   10. Run afs-rootvol.  This creates the basic AFS volume structure for
 255       your new cell, including the top-level volume, the mount point for
 256       your cell in the AFS root volume, and the mount points for all known
 257       public cells.  It will prompt you to be sure that the above steps
 258       are complete and then will ask you what file server and partition to
 259       create the volume on.  If you were following the above instructions,
 260       use the local hostname and "a" as the partition (without the
 261       quotes), which will use /vicepa.
 262
 263       After this command completes, you should be able to /bin/ls /afs and
 264       see your local cell (and, if you aren't using dynroot, mount points
 265       for several other cells).  Note that if you're not using fakestat,
 266       run /bin/ls rather than just ls to be sure that ls isn't aliased to
 267       ls -F, ls --color, or some other option that would stat each file in
 268       /afs, since this would require contacting lots of foreign cells and
 269       could take a very long time.
 270
 271       You should now be able to cd to /afs/cell.name where cell.name is
 272       the AFS cell name that you used.  Currently, there isn't anything in
 273       your cell except two volumes, user and service, created by
 274       afs-rootvol.  To make modifications, cd to /afs/.cell.name (note the
 275       leading period) and make changes there.  To make those changes show
 276       up at /afs/cell.name, run vos release root.cell.  For more details
 277       on what you can do now, see the AFS Administrator's Reference.
 278
 279   11. While this is optional, you probably want to add AFSDB records to
 280       DNS for your new AFS cell.  These special DNS records let AFS
 281       clients find the db servers for your cell without requiring local
 282       configuration.  To do this, create a DNS record like:
 283
 284           <cell>.        3600    IN      AFSDB   1 <server>.
 285
 286       where <cell> is the name of your AFS cell and <server> is the name
 287       of your db server.  Note the trailing periods to prevent the DNS
 288       server from appending the origin.  You can, of course, choose what
 289       you prefer for the lifetime.  The 1 is not a priority; it's a
 290       special indicator saying that this record is for an AFS database
 291       server.
 292
 293       If you have multiple db servers (see below for adding new ones), you
 294       should create multiple records of this type, one per db server.
 295
 296   Congratulations!  You now have an AFS cell.  If any of the above steps
 297   failed, please check the steps carefully and make sure that you've done
 298   them all in order.  If that doesn't reveal the cause of the problem,
 299   please feel free to submit a bug report with reportbug.  Include as many
 300   details as possible on exactly what you typed and exactly what you saw
 301   as a result, particularly any error messages.
 302
 303 Adding Additional Servers
 304
 305   If you decide one server is not enough, or if you're adding a server to
 306   an existing cell, here is roughly what you should do:
 307
 308   1.  Copy securely (using scp, encrypted Kerberos rcp, or some other
 309       secure method) all of /etc/openafs/server to the new server.
 310
 311   2.  Install the openafs-fileserver package on the new server.
 312
 313   3.  If the machine is to be a file server, create an fs instance using
 314       bos create:
 315
 316           bos create <host> fs fs -cmd /usr/lib/openafs/fileserver \
 317               -cmd /usr/lib/openafs/volserver \
 318               -cmd /usr/lib/openafs/salvager -localauth
 319
 320       For a file server, this is all you have to do.  The above uses the
 321       default fileserver options, however, which are not particularly
 322       well-tuned for modern systems.  afs-newcell uses the following
 323       parameters from Harald Barth:
 324
 325           -p 23 -busyat 600 -rxpck 400 -s 1200 -l 1200 -cb 65535
 326           -b 240 -vc 1200
 327
 328       If you want to add any additional fileserver options, enclose
 329       /usr/lib/openafs/fileserver and the following options in double
 330       quotes when giving the bos create command.
 331
 332   4.  For database servers, also install openafs-dbserver and then use bos
 333       addhost to add the new server to /etc/openafs/server/CellServDB:
 334
 335           bos addhost <server> <new-server>
 336
 337       for each db server <server> in your cell (including the new one).
 338       Then, restart the ptserver and vlserver instances on each of your
 339       existing servers with:
 340
 341           bos restart <server> ptserver
 342           bos restart <server> vlserver
 343
 344       It's best to wait a few seconds after doing this for each server
 345       before doing the next server so that voting finishes and you never
 346       lose a quorum.
 347
 348       Only after ptserver and vlserver have been restarted on each of your
 349       existing servers, create ptserver and vlserver instances on the new
 350       server:
 351
 352           bos create <host> ptserver simple /usr/lib/openafs/ptserver \
 353               -localauth
 354           bos create <host> vlserver simple /usr/lib/openafs/vlserver \
 355               -localauth
 356
 357       The existing servers should then propagate the database to the new
 358       server.  If you are using buserver, you will need to do the same
 359       thing for it as with ptserver and vlserver.
 360
 361       Note that you do not need to run a file server on a db server if you
 362       don't want to (and larger sites probably will not want to), but you
 363       always need to have the openafs-fileserver package installed on db
 364       servers.  It contains the bosserver binary and some of the shared
 365       infrastructure.
 366
 367   5.  If you added a new db server, configure your clients to use it.  If
 368       you are using AFSDB records in DNS, you can just add a new record
 369       (see point 10 in the instructions for creating a new cell).
 370       Otherwise, clients will need to have the new server IP address added
 371       to their /etc/openafs/CellServDB file (or /usr/vice/etc/CellServDB
 372       for non-Debian clients using the standard AFS paths), and the client
 373       will have to be restarted before it will know about the new db
 374       server.
 375
 376   The standard rule of thumb is that all of your database servers and file
 377   servers should ideally be running the same version of OpenAFS.  However,
 378   in practice OpenAFS is fairly good at backward compatibility and you can
 379   generally mix and match different versions.  Be careful, though, to
 380   ensure that all of your database servers are built the same when it
 381   comes to options like --enable-supergroups (enabled in the Debian
 382   packages).
 383
 384 Upgrades
 385
 386   Currently, during an upgrade of the openafs-fileserver package, all
 387   services will be stopped and restarted.  If openafs-dbserver is upgraded
 388   without upgrading openafs-fileserver, those server binaries will not be
 389   stopped and restarted; that restart will have to be done by hand.
 390
 391   It is possible that future versions of this package will install for
 392   example /usr/lib/openafs/fileserver.package instead of
 393   /usr/lib/openafs/fileserver and then create links to the actual binaries
 394   in postinst.  Upgrades would then not replace the old binaries, but
 395   instead a script will be provided to roll the links forward to the new
 396   versions.  The intent is that people could install the new package on
 397   all their servers and then quickly move the links before restarting the
 398   bosserver.  This has not yet been implemented.