Fixes and clarifications to vos setaddrs man page
[openafs.git] / doc / man-pages / pod1 / vos_setaddrs.pod
index 395e4a0..8d4c84c 100644 (file)
@@ -22,30 +22,45 @@ B<vos seta> S<<< B<-u> <I<UUID of server>> >>>
 
 =head1 DESCRIPTION
 
-The B<vos setaddrs> command sets the IP addresses for a server entry 
-in the Volume Location Database (VLDB). Specify one or serveral hosts.
-All existing hosts in the VLDB entry are replaced with the new entries
-on the command line. 
+The B<vos setaddrs> command sets the IP addresses for a server entry in
+the Volume Location Database (VLDB). Specify one or several IP addresses.
+All existing addresses in the VLDB server entry are replaced with the new
+addresses given on the command line.
 
-To display all VLDB server entries, for example to find the UUID,
-use the B<vos listaddrs> command.
+To find the UUID for a server entry, use the C<vos listaddrs -printuuid>
+command to display all VLDB server entries with their UUIDs.
 
 =head1 CAUTIONS
 
+Normally, the best way to change the registered addresses for a server
+entry is to restart the File Server process after changing the network
+configuration for that server and possibly the F<NetInfo> and
+F<NetRestrict> files for that server.  See L<NetInfo(5)> and
+L<NetRestrict(5)> for more information about configuring the File Server
+to register the correct set of addresses.  This command can be used to
+change the registered addresses without restarting the File Server, but
+the next time the File Server is restarted, it will register all of its
+known addresses again.  You should therefore always ensure that the File
+Server configuration is correct for whenever it is next restarted before
+using this command.
+
 Setting the wrong addresses will make the volumes on that file server 
 unreachable from AFS clients.
 
+This command was introduced in OpenAFS 1.5.74, but can be used with any
+version of the Volume Location Server.
+
 =head1 OPTIONS
 
 =over 4
 
 =item B<-uuid> <I<UUID of server>>
 
-The unique ID as provided by the B<vos listaddrs> command.
+The unique ID as provided by the C<vos listaddrs -printuuid> command.
 
 =item B<-host> <I<IP address>>+
 
-List of IP addresses for the file server.
+The new list of IP addresses for the File Server.
 
 =item B<-cell> <I<cell name>>
 
@@ -75,8 +90,7 @@ appear.
 =item B<-encrypt>
 
 Encrypts the command so that the operation's results are not transmitted
-across the network in clear text. This option is available in OpenAFS
-versions 1.4.11 or later and 1.5.60 or later.
+across the network in clear text.
 
 =item B<-noresolve>
 
@@ -93,9 +107,11 @@ ignored.
 
 =head1 EXAMPLES
 
-The following command sets addresses C<192.12.107.214> and C<10.47.11.17> for the UUID 008f157e-bad0-157c-0ffee-357c4d1faa77
+The following command sets addresses C<192.12.107.214> and C<10.47.11.17>
+for the UUID 008f157e-bad0-157c-0ffee-357c4d1faa77
 
-   % vos setaddrs -uuid 008f157e-bad0-157c-0ffee-357c4d1faa77 -host 192.12.107.214 -host 10.47.11.17 -verbose
+   % vos setaddrs -uuid 008f157e-bad0-157c-0ffee-357c4d1faa77 \
+       -host 192.12.107.214 -host 10.47.11.17 -verbose
    vos: Changed UUID with addresses:
    UUID: 008f157e-bad0-157c-0ffee-357c4d1faa77
    192.12.107.214
@@ -103,12 +119,14 @@ The following command sets addresses C<192.12.107.214> and C<10.47.11.17> for th
 
 =head1 PRIVILEGE REQUIRED
 
-Issuer must be listed in the F</usr/afs/etc/UserList> file on 
-each database server machine.
+Issuer must be listed in the F</usr/afs/etc/UserList> file on each
+database server machine.
 
 =head1 SEE ALSO
 
 L<CellServDB(5)>,
+L<NetInfo(5)>,
+L<NetRestrict(5)>,
 L<UserList(5)>,
 L<sysid(5)>,
 L<fileserver(8)>,