Fixes and clarifications to vos setaddrs man page
[openafs.git] / doc / man-pages / pod1 / vos_setaddrs.pod
1 =head1 NAME
2
3 vos_setaddrs - Set new addresses for a file server's entry in the VLDB
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos setaddrs> S<<< B<-uuid> <I<UUID of server>> >>>
11     S<<< B<-host> <I<IP address>>+ >>>
12     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
13     [B<-verbose>] [B<-encrypt>] [B<-noresolve>] [B<-help>]
14
15 B<vos seta> S<<< B<-u> <I<UUID of server>> >>>
16     S<<< B<-ho> <I<IP address>>+ >>>
17     S<<< [B<-c> <I<cell name>>] >>>
18     [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>] [B<-h>]
19
20 =for html
21 </div>
22
23 =head1 DESCRIPTION
24
25 The B<vos setaddrs> command sets the IP addresses for a server entry in
26 the Volume Location Database (VLDB). Specify one or several IP addresses.
27 All existing addresses in the VLDB server entry are replaced with the new
28 addresses given on the command line.
29
30 To find the UUID for a server entry, use the C<vos listaddrs -printuuid>
31 command to display all VLDB server entries with their UUIDs.
32
33 =head1 CAUTIONS
34
35 Normally, the best way to change the registered addresses for a server
36 entry is to restart the File Server process after changing the network
37 configuration for that server and possibly the F<NetInfo> and
38 F<NetRestrict> files for that server.  See L<NetInfo(5)> and
39 L<NetRestrict(5)> for more information about configuring the File Server
40 to register the correct set of addresses.  This command can be used to
41 change the registered addresses without restarting the File Server, but
42 the next time the File Server is restarted, it will register all of its
43 known addresses again.  You should therefore always ensure that the File
44 Server configuration is correct for whenever it is next restarted before
45 using this command.
46
47 Setting the wrong addresses will make the volumes on that file server 
48 unreachable from AFS clients.
49
50 This command was introduced in OpenAFS 1.5.74, but can be used with any
51 version of the Volume Location Server.
52
53 =head1 OPTIONS
54
55 =over 4
56
57 =item B<-uuid> <I<UUID of server>>
58
59 The unique ID as provided by the C<vos listaddrs -printuuid> command.
60
61 =item B<-host> <I<IP address>>+
62
63 The new list of IP addresses for the File Server.
64
65 =item B<-cell> <I<cell name>>
66
67 Names the cell in which to run the command. Do not combine this argument
68 with the B<-localauth> flag. For more details, see L<vos(1)>.
69
70 =item B<-noauth>
71
72 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
73 combine this flag with the B<-localauth> flag. For more details, see
74 L<vos(1)>.
75
76 =item B<-localauth>
77
78 Constructs a server ticket using a key from the local
79 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
80 to the Volume Server and Volume Location Server during mutual
81 authentication. Do not combine this flag with the B<-cell> argument or
82 B<-noauth> flag. For more details, see L<vos(1)>.
83
84 =item B<-verbose>
85
86 Produces on the standard output stream a detailed trace of the command's
87 execution. If this argument is omitted, only warnings and error messages
88 appear.
89
90 =item B<-encrypt>
91
92 Encrypts the command so that the operation's results are not transmitted
93 across the network in clear text.
94
95 =item B<-noresolve>
96
97 Shows all servers as IP addresses instead of the DNS name. Lets you
98 work with IP addresses for input, without the DNS translation between
99 the input and the registration of the IP address in the VLDB.
100
101 =item B<-help>
102
103 Prints the online help for this command. All other valid options are
104 ignored.
105
106 =back
107
108 =head1 EXAMPLES
109
110 The following command sets addresses C<192.12.107.214> and C<10.47.11.17>
111 for the UUID 008f157e-bad0-157c-0ffee-357c4d1faa77
112
113    % vos setaddrs -uuid 008f157e-bad0-157c-0ffee-357c4d1faa77 \
114        -host 192.12.107.214 -host 10.47.11.17 -verbose
115    vos: Changed UUID with addresses:
116    UUID: 008f157e-bad0-157c-0ffee-357c4d1faa77
117    192.12.107.214
118    10.47.11.17
119
120 =head1 PRIVILEGE REQUIRED
121
122 Issuer must be listed in the F</usr/afs/etc/UserList> file on each
123 database server machine.
124
125 =head1 SEE ALSO
126
127 L<CellServDB(5)>,
128 L<NetInfo(5)>,
129 L<NetRestrict(5)>,
130 L<UserList(5)>,
131 L<sysid(5)>,
132 L<fileserver(8)>,
133 L<vos(1)>,
134 L<vos_listaddrs(1)>
135
136 =head1 COPYRIGHT
137
138 KTH 2010. All Rights Reserved.
139
140 This documentation is covered by the IBM Public License Version 1.0.