doc: Make all vos pages =include common options
[openafs.git] / doc / man-pages / pod1 / vos_shadow.pod.in
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>>] >>>
17     [B<-offline>] [B<-readonly>] [B<-live>] [B<-incremental>]
18     S<<< [B<-cell> <I<cell name>>] >>>
19     [B<-noauth>] [B<-localauth>]
20     [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
21     S<<< [B<-config> <I<config directory>>] >>>
22     [B<-help>]
23
24 B<vos sh> S<<< [B<-id>] <I<volume name or ID on source>> >>>
25     S<<< [B<-froms>] <I<machine name on source>> >>>
26     S<<< [B<-fromp>] <I<partition name on source>> >>>
27     S<<< [B<-tos>] <I<machine name on destination>> >>>
28     S<<< [B<-top>] <I<partition name on destination>> >>>
29     S<<< [B<-ton> <I<volume name on destination>>] >>>
30     S<<< [B<-toi> <I<volume ID on destination>>] >>>
31     [B<-o>] [B<-r>] [B<-l>] [B<-in>]
32     S<<< [B<-c> <I<cell name>>] >>>
33     [B<-noa>] [B<-lo>] [B<-v>] [B<-e>] [B<-nor>]
34     S<<< [B<-co> <I<config directory>>] >>>
35     [B<-h>]
36
37 =for html
38 </div>
39
40 =head1 DESCRIPTION
41
42 The B<vos shadow> command creates a shadow copy of a volume on a
43 different partition or server.
44
45 A shadow volume is a copy of a volume that does not normally appear in
46 the volume location database (VLDB). It is a primitive operation that
47 is meant to be used in backup or disaster recovery situations.
48
49 =head1 CAUTIONS
50
51 This command is not used during normal OpenAFS administration and may
52 have adverse effects on the VLDB if not used properly! This command
53 should only be used by an expert.
54
55 Using this command on a volume when the source volume is not the same
56 as parent volume used to create the shadow will leave the destination
57 volume in a unknown state.
58
59 Running B<vos syncserv> or B<vos syncvldb> on a fileserver containing 
60 shadow volumes will not update the VLDB with the shadowed Read/Write
61 volumes as long as the entries for the source volumes still exist. In
62 a disaster recovery situation the VLDB entries for the corresponding
63 source volumes need hence to be deleted first.
64
65 =include fragments/volsize-caution.pod
66
67 =head1 OPTIONS
68
69 =over 4
70
71 =item B<-id> <I<volume name or ID>>
72
73 Specifies either the complete name or volume ID number of a read/write
74 volume.
75
76 =item B<-fromserver> <I<machine name for source>>
77
78 Identifies the file server machine where the source volume resides. Provide
79 the machine's IP address or its host name (either fully qualified or using
80 an unambiguous abbreviation). For details, see L<vos(1)>.
81
82 =item B<-frompartition> <I<partition name for source>>
83
84 Names the partition where the source volume resides. Provide the full
85 partition name (for, example, B</vicepa>) or one of the abbreviated forms
86 described in L<vos(1)>.
87
88 =item B<-toserver> <I<machine name for destination>>
89
90 Identifies the file server machine to which to copy the volume.  Provide
91 the machine's IP address or its host name (either fully qualified or using
92 an unambiguous abbreviation). For details, see L<vos(1)>.
93
94 =item B<-topartition> <I<partition name for destination>>
95
96 Names the partition to which to copy the volume. Provide the full partition
97 name (for, example, B</vicepa>) or one of the abbreviated forms described in
98 L<vos(1)>.
99
100 =item B<-toname> <I<volume name for new copy>>
101
102 The complete name of the new volume to create.
103
104 =item B<-toid> <I<volume ID for new copy>>
105
106 The volume ID number to use for the new volume.
107
108 =item B<-offline>
109
110 Leaves the new volume flagged as off-line in the volume database.
111
112 =item B<-readonly>
113
114 Flags the new volume as read-only in the volume database.
115
116 =item B<-live>
117
118 Copies the live volume without cloning.  This is normally not necessary and
119 causes the volume to be kept locked for longer than the normal copy
120 mechanism.
121
122 =item B<-incremental>
123
124 Copy the changes from the source volume to a previously created shadow
125 volume.
126
127 =include fragments/vos-common.pod
128
129 =back
130
131 =head1 OUTPUT
132
133 This command has no output unless C<-verbose> is specified or there is
134 an error.
135
136 =head1 PRIVILEGE REQUIRED
137
138 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
139 machines specified with the B<-toserver> and B<-fromserver> arguments and
140 on each database server machine.  If the B<-localauth> flag is included,
141 the issuer must instead be logged on to a server machine as the local
142 superuser C<root>.
143
144 =head1 SEE ALSO
145
146 L<vos(1)>,
147 L<vos_backup(1)>,
148 L<vos_copy(1)>,
149 L<vos_move(1)>
150
151 L<http://www.openafs.org/pipermail/openafs-info/2005-July/018469.html>
152 discusses motivation for the creation of this command.
153
154 L<http://workshop.openafs.org/afsbpw06/talks/drh.scs.html> discusses
155 one possible use for it.
156
157 =head1 COPYRIGHT
158
159 Copyright 2008 Jason Edgecombe <jason@rampaginggeek.com>
160
161 This documentation is covered by the BSD License as written in the
162 doc/LICENSE file. This man page was written by Jason Edgecombe for
163 OpenAFS.