doc: Make all vos pages =include common options
[openafs.git] / doc / man-pages / pod1 / vos_changeloc.pod.in
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 =include fragments/vos-common.pod
80
81 =back
82
83 =head1 OUTPUT
84
85 B<vos changeloc> shows a brief message upon completion:
86
87    Changed location to server2 /vicepa for volume user.jdoe
88
89 =head1 EXAMPLES
90
91 The following command changes the location of the C<user.jdoe> volume to
92 be F</vicepa> on the file server machine C<server2> while being verbose:
93
94    % vos changeloc server2 a user.jdoe -verbose
95     done
96    Changed location to server2 /vicepa for volume user.jdoe
97
98 The following command changes the location of the C<user.jdoe> volume to
99 be F</vicepa> on C<server1> without being verbose:
100
101    % vos changeloc server1 a user.jdoe
102    Changed location to server1 /vicepa for volume user.jdoe
103
104 =head1 PRIVILEGE REQUIRED
105
106 The issuer must be listed in the F</usr/afs/etc/UserList> file on each
107 database server machine. If the B<-localauth> flag is included, the issuer
108 must instead be logged on to a server machine as the local superuser
109 C<root>.
110
111 =head1 SEE ALSO
112
113 L<vos(1)>,
114 L<vos_move(1)>,
115 L<vos_syncserv(1)>,
116 L<vos_syncvldb(1)>
117
118 =head1 COPYRIGHT
119
120 Copyright 2007 Jason Edgecombe <jason@rampaginggeek.com>
121
122 This documentation is covered by the BSD License as written in the
123 doc/LICENSE file. This man page was written by Jason Edgecombe for
124 OpenAFS.