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