cffb583c24408e452625c5083f500ccf91db76fa
[openafs.git] / doc / man-pages / pod1 / vos_move.pod.in
1 =head1 NAME
2
3 vos_move - Moves a read/write volume to another site
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos move> S<<< B<-id> <I<volume name or ID>> >>>
11     S<<< B<-fromserver> <I<machine name on source>> >>>
12     S<<< B<-frompartition> <I<partition name on source>> >>>
13     S<<< B<-toserver> <I<machine name on destination>> >>>
14     S<<< B<-topartition> <I<partition name on destination>> >>>
15     [B<-live>] S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
16     [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
17     S<<< [B<-config> <I<config directory>>] >>>
18     [B<-help>]
19
20 B<vos m> S<<< B<-i> <I<volume name or ID>> >>>
21     S<<< B<-froms> <I<machine name on source>> >>>
22     S<<< B<-fromp> <I<partition name on source>> >>>
23     S<<< B<-tos> <I<machine name on destination>> >>>
24     S<<< B<-top> <I<partition name on destination>> >>>
25     [B<-li>] S<<< [B<-c> <I<cell name>>] >>> [B<-noa>]
26     [B<-lo>] [B<-v>] [B<-e>] [B<-nor>]
27     S<<< [B<-co> <I<config directory>>] >>>
28     [B<-h>]
29
30 =for html
31 </div>
32
33 =head1 DESCRIPTION
34
35 The B<vos move> command moves the indicated read/write volume from its
36 current site (specified with the B<-fromserver> and B<-frompartition>
37 arguments) to the destination site (specified with the B<-toserver> and
38 B<-topartition> arguments). This command automatically removes the backup
39 copy from the current site, if it exists. To create a new backup volume at
40 the destination site, use the B<vos backup> command.
41
42 This command works on read/write volumes only. To move a read-only volume,
43 use the B<vos addsite> and B<vos release> commands to define a new
44 read-only site and release the volume contents to it, and then use the
45 B<vos remove> command to remove the previous read-only volume's definition
46 from the Volume Location Database (VLDB) and data from the partition. To
47 move a backup volume, use this command to move its read/write source and
48 then issue the B<vos backup> command.
49
50 Before executing this command, the B<vos> command interpreter initiates a
51 check that the destination partition contains enough space to house the
52 volume being moved. If there is not enough space, the move operation is
53 not attempted and the following message appears:
54
55    vos: no space on target partition <dest_part> to move volume <volume>
56
57 =head1 CAUTIONS
58
59 Unless there is a compelling reason, do not interrupt a B<vos move>
60 command in progress. Interrupting a move can result in one or more of the
61 following inconsistent states:
62
63 =over 4
64
65 =item *
66
67 There are two versions of the volume, one at the source site and one at
68 the destination site. (If this happens, retain the version identified by
69 the VLDB and use the B<vos zap> command to remove the other version.)
70
71 =item *
72
73 The backup version of the volume is stranded at the old site. (If this
74 happens, use the B<vos zap> command to remove it.)
75
76 =item *
77
78 The volume is off-line. (If this happens, run the B<bos salvage> command
79 to bring it back on line.)
80
81 =back
82
83 If the Ctrl-C interrupt signal is pressed while a vos move operation is
84 executing, the following message warns of the consequences and requests
85 confirmation of the kill signal:
86
87    SIGINT handler: vos move operation in progress
88    WARNING: may leave AFS storage and metadata in indeterminate state
89    enter second control-c to exit
90
91 To confirm termination of the operation, press Ctrl-C a second time; press
92 any other key to continue the operation.
93
94 =include fragments/volsize-caution.pod
95
96 =head1 OPTIONS
97
98 =over 4
99
100 =item B<-id> <I<volume name or ID>>
101
102 Specifies either the complete name or volume ID number of a read/write
103 volume.
104
105 =item B<-fromserver> <I<server name>>
106
107 Identifies the file server machine where the volume currently
108 resides. Provide the machine's IP address or its host name (either fully
109 qualified or using an unambiguous abbreviation). For details, see
110 L<vos(1)>.
111
112 =item B<-frompartition> <I<partition name>>
113
114 Names the partition where the volume currently resides. Provide the full
115 partition name (for, example, B</vicepa>) or one of the abbreviated forms
116 described in L<vos(1)>.
117
118 =item B<-toserver> <I<server name>>
119
120 Identifies the file server machine to which to move the volume.  Provide
121 the machine's IP address or its host name (either fully qualified or using
122 an unambiguous abbreviation). For details, see L<vos(1)>.
123
124 =item B<-topartition> <I<partition name>>
125
126 Names the partition to which to move the volume. Provide the full
127 partition name (for, example, B</vicepa>) or one of the abbreviated forms
128 described in L<vos(1)>.
129
130 =item B<-live>
131
132 Avoids making a temporary copy of the volume during the move. This is
133 useful if the partition is full, but the administrator needs to move
134 volumes to a another partition or server to free up disk space. The
135 caveat is that the volume is locked during the entire operation
136 instead of the short time that is needed to make the temporary clone.
137
138 =item B<-cell> <I<cell name>>
139
140 Names the cell in which to run the command. Do not combine this argument
141 with the B<-localauth> flag. For more details, see L<vos(1)>.
142
143 =item B<-noauth>
144
145 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
146 combine this flag with the B<-localauth> flag. For more details, see
147 L<vos(1)>.
148
149 =item B<-localauth>
150
151 Constructs a server ticket using a key from the local
152 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
153 to the Volume Server and Volume Location Server during mutual
154 authentication. Do not combine this flag with the B<-cell> argument or
155 B<-noauth> flag. For more details, see L<vos(1)>.
156
157 =item B<-verbose>
158
159 Produces on the standard output stream a detailed trace of the command's
160 execution. If this argument is omitted, only warnings and error messages
161 appear.
162
163 =item B<-encrypt>
164
165 Encrypts the command so that the operation's results are not transmitted
166 across the network in clear text. This option is available in OpenAFS
167 versions 1.4.11 or later and 1.5.60 or later.
168
169 =item B<-noresolve>
170
171 Shows all servers as IP addresses instead of the DNS name. This is very
172 useful when the server address is registered as 127.0.0.1 or when dealing
173 with multi-homed servers. This option is available in OpenAFS
174 versions 1.4.8 or later and 1.5.35 or later.
175
176 =item B<-help>
177
178 Prints the online help for this command. All other valid options are
179 ignored.
180
181 =back
182
183 =head1 EXAMPLES
184
185 The following example moves the volume C<user.smith> from the F</vicepb>
186 partition on the file server machine C<fs3.example.com> to the F</vicepg>
187 partition on the file server machine C<fs7.example.com>.
188
189    % vos move -id user.smith -fromserver fs3.example.com -frompartition b \
190        -toserver fs7.example.com -topartition g
191
192 =head1 PRIVILEGE REQUIRED
193
194 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
195 machines specified with the B<-toserver> and B<-fromserver> arguments and
196 on each database server machine.  If the B<-localauth> flag is included,
197 the issuer must instead be logged on to a server machine as the local
198 superuser C<root>.
199
200 =head1 SEE ALSO
201
202 L<vos(1)>,
203 L<vos_addsite(1)>,
204 L<vos_backup(1)>,
205 L<vos_copy(1)>,
206 L<vos_release(1)>,
207 L<vos_listvol(1)>,
208 L<vos_remove(1)>
209
210 =head1 COPYRIGHT
211
212 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
213
214 This documentation is covered by the IBM Public License Version 1.0.  It was
215 converted from HTML to POD by software written by Chas Williams and Russ
216 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.