man-page-vos-shadow-20080331
[openafs.git] / doc / man-pages / pod1 / vos_shadow.pod
1 =head1 NAME
2
3 vos_shadow - Creates a shadow copy of a volume on a different server/partition
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos shadow> S<<< [B<-id>] <I<volume name or ID on source>> >>>
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     S<<< [B<-toname> <I<volume name on destination>>] >>>
16     S<<< [B<-toid> <I<volume ID on destination>>] >>> [B<-offline>] [B<-readonly>]
17     [B<-live>] [B<-incremental>] S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>]
18     [B<-localauth>] [B<-verbose>] [B<-encrypt>] [B<-help>]
19
20 =for html
21 </div>
22
23 =head1 DESCRIPTION
24
25 The B<vos shadow> command creates a shadow copy of a volume on a
26 different partition or server.
27
28 A shadow volume is a copy of a volume that does not normally appear in
29 the volume location database (VLDB). It is a primitive operation that
30 is meant to be used in backup or disaster recovery situations.
31
32 =head1 CAUTIONS
33
34 This command is not used during normal OpenAFS administration and may
35 have adverse effects on the VLDB if not used properly! This command
36 should only be used by an expert.
37
38 Using this command on a volume when the source volume is not the same
39 as parent volume used to create the shadow will leave the destination
40 volume in a unknown state.
41
42 Do NOT run the B<vos syncserv> or B<vos syncvldb> on any fileserver
43 containing shadow volumes. This would update the VLDB to show all
44 shadowed Read/Write volumes instead of the source volumes from which
45 they were copied.
46
47 Currently, the maximum size of a volume is 2 terabytes (2^31 bytes).
48
49 =head1 OPTIONS
50
51 =over 4
52
53 =item [B<-id>] <I<volume name or ID>>
54
55 Specifies either the complete name or volume ID number of a read/write
56 volume.
57
58 =item [B<-fromserver>] <I<machine name for source>>
59
60 Identifies the file server machine where the source volume resides. Provide
61 the machine's IP address or its host name (either fully qualified or using
62 an unambiguous abbreviation). For details, see L<vos(1)>.
63
64 =item [B<-frompartition>] <I<partition name for source>>
65
66 Names the partition where the source volume resides. Provide the full
67 partition name (for, example, B</vicepa>) or one of the abbreviated forms
68 described in L<vos(1)>.
69
70 =item [B<-toserver>] <I<machine name for destination>>
71
72 Identifies the file server machine to which to copy the volume.  Provide
73 the machine's IP address or its host name (either fully qualified or using
74 an unambiguous abbreviation). For details, see L<vos(1)>.
75
76 =item [B<-topartition>] <I<partition name for destination>>
77
78 Names the partition to which to copy the volume. Provide the full partition
79 name (for, example, B</vicepa>) or one of the abbreviated forms described in
80 L<vos(1)>.
81
82 =item B<-toname> <I<volume name for new copy>>
83
84 The complete name of the new volume to create.
85
86 =item B<-offline>
87
88 Leaves the new volume flagged as off-line in the volume database.
89
90 =item B<-readonly>
91
92 Flags the new volume as read-only in the volume database.
93
94 =item B<-live>
95
96 Copies the live volume without cloning.  This is normally not necessary and
97 causes the volume to be kept locked for longer than the normal copy
98 mechanism.
99
100 =item B<-incremental>
101
102 Copy the changes from the source volume to a previously created shadow
103 volume.
104
105 =item B<-cell> <I<cell name>>
106
107 Names the cell in which to run the command. Do not combine this argument
108 with the B<-localauth> flag. For more details, see L<vos(1)>.
109
110 =item B<-noauth>
111
112 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
113 combine this flag with the B<-localauth> flag. For more details, see
114 L<vos(1)>.
115
116 =item B<-localauth>
117
118 Constructs a server ticket using a key from the local
119 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents
120 it to the Volume Server and Volume Location Server during mutual
121 authentication. Do not combine this flag with the B<-cell> argument or
122 B<-noauth> flag. For more details, see L<vos(1)>.
123
124 =item B<-verbose>
125
126 Produces on the standard output stream a detailed trace of the command's
127 execution. If this argument is omitted, only warnings and error messages
128 appear.
129
130 =item B<-encrypt>
131
132 Encrypts the command so that the operation's results are not transmitted
133 across the network in clear text.
134
135 =item B<-help>
136
137 Prints the online help for this command. All other valid options are
138 ignored.
139
140 =back
141
142 =head1 OUTPUT
143
144 This command has no output unless C<-verbose> is specified or there is
145 an error.
146
147 =head1 PRIVILEGE REQUIRED
148
149 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
150 machines specified with the B<-toserver> and B<-fromserver> arguments and
151 on each database server machine.  If the B<-localauth> flag is included,
152 the issuer must instead be logged on to a server machine as the local
153 superuser C<root>.
154
155 =head1 SEE ALSO
156
157 L<vos(1)>,
158 L<vos_backup(1)>,
159 L<vos_copy(1)>,
160 L<vos_move(1)>
161
162 L<http://www.openafs.org/pipermail/openafs-info/2005-July/018469.html>
163 discusses motivation for the creation of this command.
164
165 L<http://workshop.openafs.org/afsbpw06/talks/drh.scs.html> discusses
166 one possible use for it.
167
168 =head1 COPYRIGHT
169
170 Copyright 2008 Jason Edgecombe <jason@rampaginggeek.com>
171
172 This documentation is covered by the BSD License as written in the
173 doc/LICENSE file. This man page was written by Jason Edgecombe for
174 OpenAFS.