doc: vos manpage fixes
[openafs.git] / doc / man-pages / pod1 / vos_size.pod
1 =head1 NAME
2
3 vos_size - Computes the size of a volume dump
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos size> S<<< [B<-id>] <I<volume name or id>> >>>
11     S<<< [B<-partition> <I<partition name>>] >>>
12     S<<< [B<-server> <I<machine name>>] >>>
13     [B<-dump>] S<<< [B<-time> <I<dump from time>>] >>>
14     S<<< [B<-cell> <I<cell name>>] >>>
15     [B<-noauth>] [B<-localauth>] 
16     [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
17     S<<< [B<-config> <I<config directory>>] >>>
18     [B<-help>]
19
20 B<vos si> S<<< [B<-i>] <I<volume name or id>> >>>
21     S<<< [B<-p> <I<partition name>>] >>>
22     S<<< [B<-s> <I<machine name>>] >>>
23     [B<-d>] S<<< [B<-t> <I<dump from time>>] >>>
24     S<<< [B<-c> <I<cell name>>] >>>
25     [B<-no>] [B<-l>] 
26     [B<-v>] [B<-e>] [B<-nor>]
27     S<<< [B<-co> <I<config directory>>] >>>
28     [B<-h>]
29
30 =for html
31 </div>
32
33 =head1 DESCRIPTION
34
35 The B<vos size> command shows the size of a volume's dump for backup
36 purposes. The size of the dump may differ from the volume size as reported
37 by B<vos examine> or B<fs listquota>. The size is shown in bytes.
38
39 This command is intended for use with backup systems that want to size
40 volume dumps before performing them (to optimize use of tape resources,
41 for example).
42
43 =head1 OPTIONS
44
45 =over 4
46
47 =item B<-id> <I<volume name or id>>
48
49 Specifies either the complete name or volume ID number of the read/write,
50 read-only, or backup volume to size.
51
52 =item B<-partition> <I<partition name>>
53
54 Specifies the partition on which the volume resides. Provide the
55 B<-server> argument along with this one.
56
57 =item B<-server> <I<machine name>>
58
59 Specifies the file server machine on which the volume resides.  Provide
60 the B<-partition> argument along with this one.
61
62 =item B<-dump>
63
64 Show the size of the volume dump for the specified volume. Currently, this
65 flag should always be given for B<vos size> to give useful information.
66 It is present to allow this command to provide other size estimates in the
67 future.
68
69 =item B<-time> <I<dump from time>>
70
71 Specifies whether the dump is full or incremental. Omit this argument to
72 size a full dump. See L<vos_dump(1)> for the valid values for this
73 option.
74
75 =item B<-cell> <I<cell name>>
76
77 The cell in which the volume resides, if it's not in the current cell.
78
79 =item B<-noauth>
80
81 Assigns the unprivileged identity anonymous to the issuer. Do not combine
82 this flag with the B<-localauth> flag. For more details, see L<vos(1)>.
83
84 =item B<-localauth>
85
86 Constructs a server ticket using a key from the local
87 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
88 to the Volume Server and Volume Location Server during mutual
89 authentication. Do not combine this flag with the B<-cell> argument or
90 B<-noauth> flag. For more details, see L<vos(1)>.
91
92 =item B<-verbose>
93
94 Show more output about what's going on.
95
96 =item B<-encrypt>
97
98 Encrypts the command so that the operation's results are not transmitted
99 across the network in clear text. This option is available in OpenAFS
100 versions 1.4.11 or later and 1.5.60 or later.
101
102 =item B<-noresolve>
103
104 Shows all servers as IP addresses instead of the DNS name. This is very
105 useful when the server address is registered as 127.0.0.1 or when dealing
106 with multi-homed servers. This option is available in OpenAFS
107 versions 1.4.8 or later and 1.5.35 or later.
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 When run without B<-verbose>, the output will be:
119
120    Volume: <volume>
121    dump_size: <size>
122
123 where <volume> is the name of the volume and <size> is the size of the
124 dump in bytes. With B<-verbose>, additional status messages will be
125 printed between those two lines.
126
127 =head1 EXAMPLES
128
129 Sizing a single user volume:
130
131    % vos size user.thoron -dump
132    Volume: user.thoron
133    dump_size: 36430
134
135 or, more verbosely:
136
137    % vos size user.thoron -dump -verbose
138    Volume: user.thoron
139    Starting transaction on volume 2003434023... done
140    Getting size of volume on volume 2003434023... done
141    Ending transaction on volume 2003434023... done
142    dump_size: 36430
143
144 Sizing an incremental dump for the same volume:
145
146    % vos size -id user.thoron -time '05/04/2007 00:00:00' -dump 
147    Volume: user.thoron
148    dump_size: 21095
149
150 =head1 PRIVILEGE REQUIRED
151
152 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
153 machine specified with the B<-server> argument or the machine on which the
154 volume is located if B<-server> was not given.  If the B<-localauth> flag
155 is included, the issuer must instead be logged on to a server machine as
156 the local superuser C<root>.
157
158 =head1 SEE ALSO
159
160 L<fs_listquota(1)>,
161 L<vos_dump(1)>,
162 L<vos_examine(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.