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