man-page-fileserver-limits-20080119
[openafs.git] / doc / man-pages / pod1 / vos_copy.pod
1 =head1 NAME
2
3 vos_copy - Make a copy of a volume
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos copy> S<<< [B<-id>] <I<volume name or ID of source>> >>>
11    S<<< [B<-fromserver>] <I<machine name for source>> >>>
12    S<<< [B<-frompartition>] <I<partition name for source>> >>>
13    S<<< [B<-toname>] <I<volume name for new copy>> >>>
14    S<<< [B<-toserver>] <I<machine name for destination>> >>>
15    S<<< [B<-topartition>] <I<partition name for destination>> >>>
16    [B<-offline>] [B<-readonly>] [B<-live>] S<<< [B<-cell> <I<cell name>>] >>>
17    [B<-noauth>] [B<-localauth>] [B<-verbose>] [B<-encrypt>] [B<-help>]
18
19 =for html
20 </div>
21
22 =head1 DESCRIPTION
23
24 The B<vos copy> command makes a copy of a volume with a new name.  It is
25 equivalent to B<vos dump> followed by B<vos restore>, but doesn't require
26 the volume be stored locally by the client.
27
28 =head1 CAUTIONS
29
30 Currently, the maximum size of a volume is 2 terabytes (2^31 bytes)
31 and the maximum size of a /vicepX partition on a fileserver is also 2
32 terabytes. The fileserver will not report an error when it has access
33 to a partition larger than 2 terabytes, but it will probably fail if
34 the administrator attempts to use more than 2 terabytes of space. In
35 addition, there are reports of erroneous disk usage numbers when
36 B<vos partinfo> or other OpenAFS disk reporting tools are used with
37 partitions larger than 2 terabytes.
38
39 =head1 OPTIONS
40
41 =over 4
42
43 =item [B<-id>] <I<volume name or ID>>
44
45 Specifies either the complete name or volume ID number of a read/write
46 volume.
47
48 =item [B<-fromserver>] <I<machine name for source>>
49
50 Identifies the file server machine where the source volume resides. Provide
51 the machine's IP address or its host name (either fully qualified or using
52 an unambiguous abbreviation). For details, see L<vos(1)>.
53
54 =item [B<-frompartition>] <I<partition name for source>>
55
56 Names the partition where the source volume resides. Provide the full
57 partition name (for, example, B</vicepa>) or one of the abbreviated forms
58 described in L<vos(1)>.
59
60 =item [B<-toname>] <I<volume name for new copy>>
61
62 The complete name of the new volume to create.
63
64 =item [B<-toserver>] <I<machine name for destination>>
65
66 Identifies the file server machine to which to copy the volume.  Provide
67 the machine's IP address or its host name (either fully qualified or using
68 an unambiguous abbreviation). For details, see L<vos(1)>.
69
70 =item [B<-topartition>] <I<partition name for destination>>
71
72 Names the partition to which to copy the volume. Provide the full partition
73 name (for, example, B</vicepa>) or one of the abbreviated forms described in
74 L<vos(1)>.
75
76 =item B<-offline>
77
78 Leaves the new volume flagged as off-line in the volume database.
79
80 =item B<-readonly>
81
82 Flags the new volume as read-only in the volume database.
83
84 =item B<-live>
85
86 Copies the live volume without cloning.  This is normally not necessary and
87 causes the volume to be kept locked for longer than the normal copy
88 mechanism.
89
90 =item B<-localauth>
91
92 Constructs a server ticket using a key from the local
93 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it to
94 the Volume Server and Volume Location Server during mutual
95 authentication. Do not combine this flag with the B<-cell> argument or
96 B<-noauth> flag. For more details, see L<vos(1)>.
97
98 =item B<-verbose>
99
100 Produces on the standard output stream a detailed trace of the command's
101 execution. If this argument is omitted, only warnings and error messages
102 appear.
103
104 =item B<-encrypt>
105
106 Encrypts the command so that the operation's results are not transmitted
107 across the network in clear text.
108
109 =item B<-help>
110
111 Prints the online help for this command. All other valid options are
112 ignored.
113
114 =back
115
116 =head1 OUTPUT
117
118 This command has no output unless C<-verbose> is specified or there is
119 an error.
120
121 =head1 EXAMPLES
122
123 The following example makes a verbose copy of the C<test> volume named
124 C<test2> in the cell C<localcell>. The volume and copy both reside on
125 C</vicepa> of C<server1>.
126
127    % vos copy test server1  a test2 server1 a -cell localcell -verbose
128    Starting transaction on source volume 536870921 ... done
129    Allocating new volume id for clone of volume 536870921 ... done
130    Allocating new volume id for copy of volume 536870921 ... done
131    Cloning source volume 536870921 ... done
132    Ending the transaction on the source volume 536870921 ... done
133    Starting transaction on the cloned volume 536870926 ... done
134    Setting flags on cloned volume 536870926 ... done
135    Getting status of cloned volume 536870926 ... done
136    Creating the destination volume 536870927 ... done
137    Setting volume flags on destination volume 536870927 ... done
138    Dumping from clone 536870926 on source to volume 536870927 on destination ... done
139    Ending transaction on cloned volume 536870926 ... done
140    Starting transaction on source volume 536870921 ... done
141    Doing the incremental dump from source to destination for volume 536870921 ...  done
142    Setting volume flags on destination volume 536870927 ... done
143    Ending transaction on destination volume 536870927 ... done
144    Ending transaction on source volume 536870921 ... done
145    Starting transaction on the cloned volume 536870926 ... done
146    Deleting the cloned volume 536870926 ... done
147    Ending transaction on cloned volume 536870926 ... done
148    Created the VLDB entry for the volume test2 536870927
149    Volume 536870921 copied from server1 /vicepa to test2 on server1 /vicepa 
150
151 =head1 PRIVILEGE REQUIRED
152
153 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
154 machine specified with the B<-server> argument and on each database server
155 machine. If the B<-localauth> flag is included, the issuer must instead be
156 logged on to a server machine as the local superuser C<root>.
157
158 =head1 SEE ALSO
159
160 L<vos(1)>,
161 L<vos_clone(1)>,
162 L<vos_move(1)>
163
164 =head1 COPYRIGHT
165
166 Copyright 2007 Jason Edgecombe <jason@rampaginggeek.com>
167
168 This documentation is covered by the BSD License as written in the
169 doc/LICENSE file. This man page was written by Jason Edgecombe for
170 OpenAFS.