8a6b3b3b91517bf72e23f75dbd0e176fb4198ab0
[openafs.git] / doc / man-pages / pod1 / vos_changeloc.pod
1 =head1 NAME
2
3 vos_changeloc - Change a volume's entry in the VLDB
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos changeloc> S<<< [B<-server>] <I<new server name>> >>>
11    S<<< [B<-partition>] <I<new partition location>> >>>
12    S<<< [B<-id>] <I<volume name or ID>> >>>
13    S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
14    [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
15    S<<< [B<-config> <I<config directory>>] >>>
16    [B<-help>]
17
18 B<vos changel> S<<< [B<-s>] <I<new server name>> >>>
19    S<<< [B<-p>] <I<new partition location>> >>>
20    S<<< [B<-i>] <I<volume name or ID>> >>>
21    S<<< [B<-c> <I<cell name>>] >>>
22    [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>]
23    S<<< [B<-co> <I<config directory>>] >>>
24    [B<-h>]
25
26 =for html
27 </div>
28
29 =head1 DESCRIPTION
30
31 The B<vos changeloc> command changes the location of a volume in the
32 Volume Location Database (VLDB) without needing to contact the original
33 file server on which the volume was hosted. This is useful when a file
34 server has gone down permanently and the data that was stored on that
35 server has been moved to a new file server with a different name and IP
36 address (perhaps by mounting the same /vicepX partitions on a different
37 host). After moving the data and running B<vos changeloc>, run B<vos
38 syncvldb> and then B<vos syncserv> against the new server to ensure full
39 synchronization of the VLDB with the file server.
40
41 In essence, B<vos changeloc> performs the same operations on the VLDB as
42 B<vos move>, but it does NOT move the data from one server's file system
43 to another.
44
45 =head1 CAUTIONS
46
47 Using B<vos changeloc> changes the VLDB without modifying the file server
48 data, so it inherently causes the VLDB to be out of sync with the data on
49 the servers. It should only be used when recovering from server failure.
50 If the servers are on-line, B<vos move> should be used instead. It is
51 highly recommended that B<vos syncvldb> and B<vos syncserv> be run after
52 using the B<vos changeloc> command to ensure properly synchronization of
53 the VLDB with the file servers.
54
55 =head1 OPTIONS
56
57 B<vos changeloc> takes the following options:
58
59 =over 4
60
61 =item B<-server> <I<new server name>>
62
63 Specifies the new server where the VLDB should believe the volume resides.
64 Provide the machine's IP address or its host name (either fully qualified
65 or using an unambiguous abbreviation). For details, see L<vos(1)>.
66
67 =item B<-partition> <I<partition name>>
68
69 Specifies the partition where the VLDB should believe the volume resides.
70 Provide the B<-server> argument along with this one. Provide the
71 partition's complete name with preceding slash (for example, C</vicepa>)
72 or use one of the three acceptable abbreviated forms. For details, see
73 L<vos(1)>.
74
75 =item B<-id> <I<volume name or ID>>
76
77 Specifies the name or volume ID number on which to operate.
78
79 =item B<-cell> <I<cell name>>
80
81 Names the cell in which to run the command. Do not combine this argument
82 with the B<-localauth> flag. For more details, see L<vos(1)>.
83
84 =item B<-noauth>
85
86 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
87 combine this flag with the B<-localauth> flag. For more details, see
88 L<vos(1)>.
89
90 =item B<-localauth>
91
92 Constructs a server ticket using a key from the local
93 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
94 to the Volume Server and Volume Location Server during mutual
95 authentication. Do not combine this flag with the B<-cell> argument or
96 B<-noauth> flag. For more details, see L<vos(1)>.
97
98 =item B<-verbose>
99
100 Produces on the standard output stream a detailed trace of the command's
101 execution. If this argument is omitted, only warnings and error messages
102 appear.
103
104 =item B<-encrypt>
105
106 Encrypts the command so that the operation's results are not transmitted
107 across the network in clear text. This option is available in OpenAFS
108 versions 1.4.11 or later and 1.5.60 or later.
109
110 =item B<-noresolve>
111
112 Shows all servers as IP addresses instead of the DNS name. This is very
113 useful when the server address is registered as 127.0.0.1 or when dealing
114 with multi-homed servers. This option is available in OpenAFS
115 versions 1.4.8 or later and 1.5.35 or later.
116
117 =item B<-help>
118
119 Prints the online help for this command. All other valid options are
120 ignored.
121
122 =back
123
124 =head1 OUTPUT
125
126 B<vos changeloc> shows a brief message upon completion:
127
128    Changed location to server2 /vicepa for volume user.jdoe
129
130 =head1 EXAMPLES
131
132 The following command changes the location of the C<user.jdoe> volume to
133 be F</vicepa> on the file server machine C<server2> while being verbose:
134
135    % vos changeloc server2 a user.jdoe -verbose
136     done
137    Changed location to server2 /vicepa for volume user.jdoe
138
139 The following command changes the location of the C<user.jdoe> volume to
140 be F</vicepa> on C<server1> without being verbose:
141
142    % vos changeloc server1 a user.jdoe
143    Changed location to server1 /vicepa for volume user.jdoe
144
145 =head1 PRIVILEGE REQUIRED
146
147 The issuer must be listed in the F</usr/afs/etc/UserList> file on each
148 database server machine. If the B<-localauth> flag is included, the issuer
149 must instead be logged on to a server machine as the local superuser
150 C<root>.
151
152 =head1 SEE ALSO
153
154 L<vos(1)>,
155 L<vos_move(1)>,
156 L<vos_syncserv(1)>,
157 L<vos_syncvldb(1)>
158
159 =head1 COPYRIGHT
160
161 Copyright 2007 Jason Edgecombe <jason@rampaginggeek.com>
162
163 This documentation is covered by the BSD License as written in the
164 doc/LICENSE file. This man page was written by Jason Edgecombe for
165 OpenAFS.