Starting the BOS Server

Starting the BOS Server
	Chapter 2. Installing the First AFS Machine

You are now ready to start the AFS server processes on this machine. If you are not working from a packaged distribution, begin by installing the AFS server binaries to the conventional local disk location, the /usr/afs/bin directory. The following instructions also create files in other subdirectories of the /usr/afs directory.

Then obtain a krb5 keytab for use by the servers in the cell. Once the keytab is in place, issue the bosserver command to initialize the Basic OverSeer (BOS) Server, which monitors and controls other AFS server processes on its server machine. Because you have not yet configured your cell's AFS authentication and authorization mechanisms, you must always use the -localauth flag to commands, to use a printed token that does not correspond to a normal krb5 identity.

Older versions of these instructions used the -noauth flag, which completely disables all authentication and authorization checking, allowing anyone at all to control the system. Do not use this flag! It is highly insecure, and is no longer needed.

As it initializes for the first time, the BOS Server creates the following directories and files, setting the owner to the local superuser root and the mode bits to limit the ability to write (and in some cases, read) them. For a description of the contents and function of these directories and files, see the chapter in the OpenAFS Administration Guide about administering server machines. For further discussion of the mode bit settings, see Protecting Sensitive AFS Directories.

/usr/afs/db
/usr/afs/etc/CellServDB
/usr/afs/etc/ThisCell
/usr/afs/local
/usr/afs/logs

The BOS Server also creates symbolic links called /usr/vice/etc/ThisCell and /usr/vice/etc/CellServDB to the corresponding files in the /usr/afs/etc directory. The AFS command interpreters consult the CellServDB and ThisCell files in the /usr/vice/etc directory because they generally run on client machines. On machines that are AFS servers only (as this machine currently is), the files reside only in the /usr/afs/etc directory; the links enable the command interpreters to retrieve the information they need. Later instructions for installing the client functionality replace the links with actual files.

Generating the Cell's Kerberos V5 Keys

This guide uses krb5 for authentication; do not use the legacy kaserver for new installations.

This section creates only the cell-wide shared secret key; administrative users will be created later in the procedure. This cell-wide key has the principal name afs/cell. No user logs in under this identity, but it is used to encrypt the server tickets that the KDC grants to AFS clients for presentation to server processes during mutual authentication. (The chapter in the OpenAFS Administration Guide about cell configuration and administration describes the role of server encryption keys in mutual authentication.)

The OpenAFS 1.8.x series stores the cell-wide shared keys in the file /usr/afs/etc/KeyFileExt, whereas the 1.6.x series uses a krb5 keytab format file in /usr/afs/etc/rxkad.keytab. These instructions create both files, but populating the KeyFileExt file will only succeed using the version of asetkey from OpenAFS 1.8.x.

The examples below assume you are using MIT Kerberos. Please refer to the documentation for your KDC's administrative interface if you are using a different vendor

Enter kadmin interactive mode.

     # kadmin
  Authenticating as principal you/admin@YOUR REALM with password
  Password for you/admin@REALM: your_password

Issue the add_principal command to create a Kerberos Database entry for afs/<cell name>.
Note that when creating the afs/<cell name> entry, the encryption type list does not include any single-DES encryption types. If such encryption types are included, additional asetkey commands will be needed to place those keys in the legacy KeyFile and ensure proper operation of the cell. For more details regarding encryption types, see the documentation for your Kerberos installation.
```
     kadmin: add_principal -randkey -e aes256-cts-hmac-sha1-96:normal,aes128-cts-hmac-sha1-96:normal afs/<cell name>
     Principal "afs/cell name@REALM" created.
  
```
Extract the newly created key for afs/cell to a keytab on the local machine.
The keytab contains the key material that ensures the security of your AFS cell. You should ensure that it is kept in a secure location at all times.
```
    kadmin: ktadd -k /usr/afs/etc/rxkad.keytab -e aes256-cts-hmac-sha1-96:normal,aes128-cts-hmac-sha1-96:normal afs/<cell name>
  Entry for principal afs/<cell name> with kvno 2, encryption type aes256-cts-hmac-sha1-96 added to keytab WRFILE:/usr/afs/etc/rxkad.keytab
  Entry for principal afs/<cell name> with kvno 2, encryption type aes128-cts-hmac-sha1-96 added to keytab WRFILE:/usr/afs/etc/rxkad.keytab
  
```
Make a note of the key version number (kvno) given in the response, as you will need it to load the key into the KeyFileExt in a later step
Note
Note that each time you run ktadd a new key is generated for the item being extracted. This means that you cannot run ktadd multiple times and end up with the same key material each time.
Issue the quit command to leave kadmin interactive mode.
```
     kadmin: quit
  
```
Issue the asetkey command to set the AFS server encryption key in the /usr/afs/etc/KeyFileExt file. This key is created from the rxkad.keytab file created earlier.
asetkey requires the key version number (or kvno) of the afs/cell key, as well as the encryption type number of the key. You should have made note of the kvno when creating the key earlier. The key version number can also be found by running the kvno command
```
     # kvno -kt /usr/afs/etc/rxkad.keytab
  
```
The encryption type numbers can be found in the local krb5 headers or the IANA registry. The most common numbers are 18 for aes256-cts-hmac-sha1-96 and 17 for aes128-cts-hmac-sha1-96.
Once the kvno and enctypes are known, the keys can then be extracted using asetkey
```
     # asetkey add rxkad_krb5 <kvno>  18 /usr/afs/etc/rxkad.keytab afs/<cell name>
     # asetkey add rxkad_krb5 <kvno>  17 /usr/afs/etc/rxkad.keytab afs/<cell name>
  
```

Starting the Server Processes

Now that the keys are in place, proceed to start the server processes:

If you are building from source, you need to install the compiled files to the local /usr/afs directory.
Issue the bosserver command.
```
   # /usr/afs/bin/bosserver
```
Verify that the BOS Server created /usr/vice/etc/ThisCell and /usr/vice/etc/CellServDB as symbolic links to the corresponding files in the /usr/afs/etc directory.
```
   # ls -l  /usr/vice/etc
```
If either or both of /usr/vice/etc/ThisCell and /usr/vice/etc/CellServDB do not exist, or are not links, issue the following commands.
```
   # cd /usr/vice/etc
   # ln -s /usr/afs/etc/ThisCell
   # ln -s /usr/afs/etc/CellServDB 
```


Getting Started on Solaris Systems		Defining Cell Name and Membership for Server Processes