Managing Server IP Addresses and VLDB Server Entries

The AFS support for multihomed file server machines is largely automatic. The File Server process records the IP addresses of its file server machine's network interfaces in the local /usr/afs/local/sysid file and also registers them in a server entry in the Volume Location Database (VLDB). The sysid file and server entry are identified by the same unique number, which creates an association between them.

When the Cache Manager requests volume location information, the Volume Location (VL) Server provides all of the interfaces registered for each server machine that houses the volume. This enables the Cache Manager to make use of multiple addresses when accessing AFS data stored on a multihomed file server machine.

If you wish, you can control which interfaces the File Server registers in its VLDB server entry by creating two files in the local /usr/afs/local directory: NetInfo and NetRestrict. Each time the File Server restarts, it builds a list of the local machine's interfaces by reading the NetInfo file, if it exists. If you do not create the file, the File Server uses the list of network interfaces configured with the operating system. It then removes from the list any addresses that appear in the NetRestrict file, if it exists. The File Server records the resulting list in the sysid file and registers the interfaces in the VLDB server entry that has the same unique identifier.

On database server machines, the NetInfo and NetRestrict files also determine which interfaces the Ubik database synchronization library uses when communicating with the database server processes running on other database server machines.

There is a maximum number of IP addresses in each server entry, as documented in the OpenAFS Release Notes. If a multihomed file server machine has more interfaces than the maximum, AFS simply ignores the excess ones. It is probably appropriate for such machines to use the NetInfo and NetRestrict files to control which interfaces are registered.

If for some reason the sysid file no longer exists, the File Server creates a new one with a new unique identifier. When the File Server registers the contents of the new file, the Volume Location (VL) Server normally recognizes automatically that the new file corresponds to an existing server entry, and overwrites the existing server entry with the new file contents and identifier. However, it is best not to remove the sysid file if that can be avoided.

Similarly, it is important not to copy the sysid file from one file server machine to another. If you commonly copy the contents of the /usr/afs directory from an existing machine as part of installing a new file server machine, be sure to remove the sysid file from the /usr/afs/local directory on the new machine before starting the File Server.

There are certain cases where the VL Server cannot determine whether it is appropriate to overwrite an existing server entry with a new sysid file's contents and identifier. It then refuses to allow the File Server to register the interfaces, which prevents the File Server from starting. This can happen if, for example, a new sysid file includes two interfaces that currently are registered by themselves in separate server entries. In such cases, error messages in the /usr/afs/log/VLLog file on the VL Server machine and in the /usr/afs/log/FileLog file on the file server machine indicate that you need to use the vos changeaddr command to resolve the problem. Contact the AFS Product Support group for instructions and assistance.

Except in this type of rare error case, the only appropriate use of the vos changeaddr command is to remove a VLDB server entry completely when you remove a file server machine from service. The VLDB can accommodate a maximum number of server entries, as specified in the OpenAFS Release Notes. Removing obsolete entries makes it possible to allocate server entries for new file server machines as required. See the instructions that follow.

Do not use the vos changeaddr command to change the list of interfaces registered in a VLDB server entry. To change a file server machine's IP addresses and server entry, see the instructions that follow.

To create or edit the server NetInfo file

  1. Become the local superuser root on the machine, if you are not already, by issuing the su command.

       % su root
       Password: root_password
    
  2. Using a text editor, open the /usr/afs/local/NetInfo file. Place one IP address in dotted decimal format (for example, 192.12.107.33) on each line. The order of entries is not significant.

  3. If you want the File Server to start using the revised list immediately, use the bos restart command to restart the fs process. For instructions, see Stopping and Immediately Restarting Processes.

To create or edit the server NetRestrict file

  1. Become the local superuser root on the machine, if you are not already, by issuing the su command.

       % su root
       Password: root_password
    
  2. Using a text editor, open the /usr/afs/local/NetRestrict file. Place one IP address in dotted decimal format on each line. The order of the addresses is not significant. Use the value 255 as a wildcard that represents all possible addresses in that field. For example, the entry 192.12.105.255 indicates that the Cache Manager does not register any of the addresses in the 192.12.105 subnet.

  3. If you want the File Server to start using the revised list immediately, use the bos restart command to restart the fs process. For instructions, see Stopping and Immediately Restarting Processes.

To display all server entries from the VLDB

  1. Issue the vos listaddrs command to display all server entries from the VLDB.

       % vos listaddrs
    

    where lista is the shortest acceptable abbreviation of listaddrs.

    The output displays all server entries from the VLDB, each on its own line. If a file server machine is multihomed, all of its registered addresses appear on the line. The first one is the one reported as a volume's site in the output from the vos examine and vos listvldb commands.

    VLDB server entries record IP addresses, and the command interpreter has the local name service (either a process like the Domain Name Service or a local host table) translate them to hostnames before displaying them. If an IP address appears in the output, it is not possible to translate it.

    The existence of an entry does not necessarily indicate that the machine that is still an active file server machine. To remove obsolete server entries, see the following instructions.

To remove obsolete server entries from the VLDB

  1. 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>
    
  2. Issue the vos changeaddr command to remove a server entry from the VLDB.

       % vos changeaddr <original IP address> -remove
    

    where

    ch

    Is the shortest acceptable abbreviation of changeaddr.

    original IP address

    Specifies one of the IP addresses currently registered for the file server machine in the VLDB. Any of a multihomed file server machine's addresses are acceptable to identify it.

    -remove

    Removes the server entry.

To change a server machine's IP addresses

  1. 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>
    
  2. If the machine is the system control machine or a binary distribution machine, and you are also changing its hostname, redefine all relevant upclient processes on other server machines to refer to the new hostname. Use the bos delete and bos create commands as instructed in Creating and Removing Processes.

  3. If the machine is a database server machine, edit its entry in the /usr/afs/etc/CellServDB file on every server machine in the cell to list one of the new IP addresses. If you use the United States edition of AFS, you can edit the file on the system control machine and wait the required time (by default, five minutes) for the Update Server to distribute the changed file to all server machines.

  4. If the machine is a database server machine, issue the bos shutdown command to stop all server processes. If the machine is also a file server, the volumes on it are inaccessible during this time. For a complete description of the command, see To stop processes temporarily.

       % bos shutdown <machine name>
    
  5. Use the utilities provided with the operating system to change one or more of the machine's IP addresses.

  6. If appropriate, edit the /usr/afs/local/NetInfo file, the /usr/afs/local/NetRestrict file, or both, to reflect the changed addresses. Instructions appear earlier in this section.

  7. If the machine is a database server machine, issue the bos restart command to restart all server processes on the machine. For complete instructions for the bos restart command, see Stopping and Immediately Restarting Processes.

       % bos restart <machine name> -all
    

    At the same time, issue the bos restart command on all other database server machines in the cell to restart the database server processes only (the Authentication, Backup, Protection, and Volume Location Servers). Issue the commands in quick succession so that all of the database server processes vote in the quorum election.

       % bos restart <machine name> kaserver buserver ptserver vlserver
    

    If you are changing IP addresses on every database server machine in the cell, you must also issue the bos restart command on every file server machine in the cell to restart the fs process.

  8. If the machine is not a database server machine, issue the bos restart command to restart the fs process (if the machine is a database server, you already restarted the process in the previous step). The File Server automatically compiles a new list of interfaces, records them in the /usr/afs/local/sysid file, and registers them in its VLDB server entry.

       % bos restart <machine name> fs
    
  9. If the machine is a database server machine, edit its entry in the /usr/vice/etc/CellServDB file on every client machine in the cell to list one of the new IP addresses. Instructions appear in Maintaining Knowledge of Database Server Machines.

  10. If there are machine entries in the Protection Database for the machine's previous IP addresses, use the pts rename command to change them to the new addresses. For instructions, see Changing a Protection Database Entry's Name.