Installing Server Process Software

Installing Server Process Software
	Chapter 3. Administering Server Machines

This section explains how to install new server process binaries on file server machines, how to revert to a previous version if the current version is not working properly, and how to install new disks to house AFS volumes on a file server machine.

The most frequent reason to replace a server process's binaries is to upgrade AFS to a new version. In general, installation instructions accompany the updated software, but this chapter provides an additional reference.

Each AFS server machine must store the server process binaries in a local disk directory, called /usr/afs/bin by convention. For predictable system performance, it is best that all server machines run the same build level, or at least the same version, of the server software. For instructions on checking AFS build level, see Displaying A Binary File's Build Level.

The Update Server makes it easy to distribute a consistent version of software to all server machines. You designate one server machine of each system type as the binary distribution machine by running the server portion of the Update Server (upserver process) on it. All other server machines of that system type run the client portion of the Update Server (upclientbin process) to retrieve updated software from the binary distribution machine. The OpenAFS Quick Beginnings explains how to install the appropriate processes. For more on binary distribution machines, see Binary Distribution Machines.

When you use the Update Server, you install new binaries on binary distribution machines only. If you install binaries directly on a machine that is running the upclientbin process, they are overwritten the next time the process compares the contents of the local /usr/afs/bin directory to the contents on the system control machine, by default within five minutes.

The following instructions explain how to use the appropriate commands from the bos suite to install and uninstall server binaries.

Installing New Binaries

An AFS server process does not automatically switch to a new process binary file as soon as it is installed in the /usr/afs/bin directory. The process continues to use the previous version of the binary file until it (the process) next restarts. By default, the BOS Server restarts processes for which there are new binary files every day at 5:00 a.m., as specified in the /usr/afs/local/BosConfig file. To display or change this binary restart time, use the bos getrestart and bos setrestart commands, as described in Setting the BOS Server's Restart Times.

You can force the server machine to start using new server process binaries immediately by issuing the bos restart command as described in the following instructions.

You do not need to restart processes when you install new command suite binaries. The new binary is invoked automatically the next time a command from the suite is issued.

When you use the bos install command, the BOS Server automatically saves the current version of a binary file by adding a .BAK extension to its name. It renames the current .BAK version, if any, to the .OLD version, if there is no .OLD version already. If there is a current .OLD version, the current .BAK version must be at least seven days old to replace it.

It is best to store AFS binaries in the /usr/afs/bin directory, because that is the only directory the BOS Server automatically checks for new binaries. You can, however, use the bos install command's -dir argument to install non-AFS binaries into other directories on a server machine's local disk. See the command's reference page in the OpenAFS Administration Reference for further information.

To install new server binaries

Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Verify that the binaries are available in the source directory from which you are installing them. If the machine is also an AFS client, you can retrieve the binaries from a central directory in AFS. Otherwise, you can obtain them directly from the AFS distribution media, from a local disk directory where you previously installed them, or from a remote machine using a transfer utility such as the ftp command.
Issue the bos install command for the binary distribution machine. (If you have forgotten which machine is performing that role, see To locate the binary distribution machine for a system type.)
```
   % bos install <machine name> <files to install>+
```
where
i
Is the shortest acceptable abbreviation of install.
machine name
Names the binary distribution machine.
files to install
Names each binary file to install into the local /usr/afs/bin directory. Partial pathnames are interpreted relative to the current working directory. The last element in each pathname (the filename itself) matches the name of the file it is replacing, such as bosserver or volserver for server processes, bos or vos for commands.
Each AFS server process other than the fs process uses a single binary file. The fs process uses three binary files: fileserver, volserver, and salvager. Installing a new version of one component does not necessarily mean that you need to replace all three.
Repeat Step 3 for each binary distribution machine.
(Optional) If you want to restart processes to use the new binaries immediately, wait until the upclientbin process retrieves them from the binary distribution machine. You can verify the timestamps on binary files by using the bos getdate command as described in Displaying Binary Version Dates. When the binary files are available on each server machine, issue the bos restart command, for which complete instructions appear in Stopping and Immediately Restarting Processes.
If you are working on an AFS client machine, it is a wise precaution to have a copy of the bos command suite binaries on the local disk before restarting server processes. In the conventional configuration, the /usr/afsws/bin directory that houses the bos command binary on client machines is a symbolic link into AFS, which conserves local disk space. However, restarting certain processes (particularly the database server processes) can make the AFS filespace inaccessible, particularly if a problem arises during the restart. Having a local copy of the bos binary enables you to uninstall or reinstall process binaries or restart processes even in this case. Use the cp command to copy the bos command binary from the /usr/afsws/bin directory to a local directory such as /tmp.
Restarting a process causes a service outage. It is best to perform the restart at times of low system usage if possible.
```
   % bos restart <machine name> <instances>+
```

Reverting to the Previous Version of Binaries

In rare cases, installing a new binary can cause problems serious enough to require reverting to the previous version. Just as with installing binaries, consistent system performance requires reverting every server machine back to the same version. Issue the bos uninstall command described here on each binary distribution machine.

When you use the bos uninstall command, the BOS Server discards the current version of a binary file and promotes the .BAK version of the file by removing the extension. It renames the current .OLD version, if any, to .BAK.

If there is no current .BAK version, the bos uninstall command operation fails and generates an error message. If a .OLD version still exists, issue the mv command to rename it to .BAK before reissuing the bos uninstall command.

Just as when you install new binaries, the server processes do not start using a reverted version immediately. Presumably you are reverting because the current binaries do not work, so the following instructions have you restart the relevant processes.

To revert to the previous version of binaries

Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Verify that the .BAK version of each relevant binary is available in the /usr/afs/bin directory on each binary distribution machine. If necessary, you can use the bos getdate command as described in Displaying Binary Version Dates. If necessary, rename the .OLD version to .BAK
Issue the bos uninstall command for a binary distribution machine. (If you have forgotten which machine is performing that role, see To locate the binary distribution machine for a system type.)
```
   % bos uninstall <machine name> <files to uninstall>+
```
where
u
Is the shortest acceptable abbreviation of uninstall.
machine name
Names the binary distribution machine.
files to uninstall
Names each binary file in the /usr/afs/bin directory to replace with its .BAK version. The file name alone is sufficient, because the /usr/afs/bin directory is assumed.
Repeat Step 3 for each binary distribution machine.
Wait until the upclientbin process on each server machine retrieves the reverted from the binary distribution machine. You can verify the timestamps on binary files by using the bos getdate command as described in Displaying Binary Version Dates. When the binary files are available on each server machine, issue the bos restart command, for which complete instructions appear in Stopping and Immediately Restarting Processes.
If you are working on an AFS client machine, it is a wise precaution to have a copy of the bos command suite binaries on the local disk before restarting server processes. In the conventional configuration, the /usr/afsws/bin directory that houses the bos command binary on client machines is a symbolic link into AFS, which conserves local disk space. However, restarting certain processes (particularly the database server processes) can make the AFS filespace inaccessible, particularly if a problem arises during the restart. Having a local copy of the bos binary enables you to uninstall or reinstall process binaries or restart processes even in this case. Use the cp command to copy the bos command binary from the /usr/afsws/bin directory to a local directory such as /tmp.
```
   % bos restart <machine name> <instances>+
```

Displaying Binary Version Dates

You can check the compilation dates for all three versions of a binary file in the /usr/afs/bin directory--the current, .BAK and .OLD versions. This is useful for verifying that new binaries have been copied to a file server machine from its binary distribution machine before restarting a server process to use the new binaries.

To check dates on binaries in a directory other than /usr/afs/bin, add the -dir argument. See the OpenAFS Administration Reference.

To display binary version dates

Issue the bos getdate command.
```
   % bos getdate <machine name> <files to check>+
```
where
getd
Is the shortest acceptable abbreviation of getdate.
machine name
Name the file server machine for which to display binary dates.
files to check
Names each binary file to display.

Removing Obsolete Binary Files

When processes with new binaries have been running without problems for a number of days, it is generally safe to remove the .BAK and .OLD versions from the /usr/afs/bin directory, both to reduce clutter and to free space on the file server machine's local disk.

You can use the bos prune command's flags to remove the following types of files:

To remove files in the /usr/afs/bin directory with a .BAK extension, use the -bak flag.
To remove files in the /usr/afs/bin directory with a .OLD extension, use the -old flag.
To remove files in the /usr/afs/logs directory called core, with any extension, use the -core flag.
To remove all three types of files, use the -all flag.

To remove obsolete binaries

Verify that you are listed in the /usr/afs/etc/UserList file. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.
```
   % bos listusers <machine name>
```
Issue the bos prune command with one or more of its flags.
```
   % bos prune <machine name> [-bak] [-old] [-core] [-all]
```
where
p
Is the shortest acceptable abbreviation of prune.
machine name
Names the file server machine on which to remove obsolete files.
-bak
Removes all the files with a .BAK extension from the /usr/afs/bin directory. Do not combine this flag with the -all flag.
-old
Removes all the files a .OLD extension from the /usr/afs/bin directory. Do not combine this flag with the -all flag.
-core
Removes all core files from the /usr/afs/logs directory. Do not combine this flag with the -all flag
-all
Combines the effect of the other three flags. Do not combine it with the other three flags.

Displaying A Binary File's Build Level

For the most consistent performance on a server machine, and cell-wide, it is best for all server processes to come from the same AFS distribution. Every AFS binary includes an ASCII string that specifies its version, or build level. To display it, use the strings and grep commands, which are included in most UNIX distributions.

To display an AFS binary's build level

Change to the directory that houses the binary file . If you are not sure where the binary resides, issue the which command.
```
   % which binary_file
   /bin_dir_path/binary_file
   % cd bin_dir_path
```
Issue the strings command to extract all ASCII strings from the binary file. Pipe the output to the grep command to locate the relevant line.
```
   % strings ./binary_file | grep Base
```
The output reports the AFS build level in a format like the following:
```
   @(#)Base configuration afsversion  build_level
```
For example, the following string indicates the binary is from AFS M.m build 3.0:
```
   @(#)Base configuration afsM.m 3.0
```


Administering Database Server Machines		Maintaining the Server CellServDB File