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