doc: vos manpage fixes
[openafs.git] / doc / man-pages / pod1 / vos_size.pod.in
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 =include fragments/vos-common.pod
76
77 =back
78
79 =head1 OUTPUT
80
81 When run without B<-verbose>, the output will be:
82
83    Volume: <volume>
84    dump_size: <size>
85
86 where <volume> is the name of the volume and <size> is the size of the
87 dump in bytes. With B<-verbose>, additional status messages will be
88 printed between those two lines.
89
90 =head1 EXAMPLES
91
92 Sizing a single user volume:
93
94    % vos size user.thoron -dump
95    Volume: user.thoron
96    dump_size: 36430
97
98 or, more verbosely:
99
100    % vos size user.thoron -dump -verbose
101    Volume: user.thoron
102    Starting transaction on volume 2003434023... done
103    Getting size of volume on volume 2003434023... done
104    Ending transaction on volume 2003434023... done
105    dump_size: 36430
106
107 Sizing an incremental dump for the same volume:
108
109    % vos size -id user.thoron -time '05/04/2007 00:00:00' -dump 
110    Volume: user.thoron
111    dump_size: 21095
112
113 =head1 PRIVILEGE REQUIRED
114
115 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
116 machine specified with the B<-server> argument or the machine on which the
117 volume is located if B<-server> was not given.  If the B<-localauth> flag
118 is included, the issuer must instead be logged on to a server machine as
119 the local superuser C<root>.
120
121 =head1 SEE ALSO
122
123 L<fs_listquota(1)>,
124 L<vos_dump(1)>,
125 L<vos_examine(1)>
126
127 =head1 COPYRIGHT
128
129 Copyright 2007 Jason Edgecombe <jason@rampaginggeek.com>
130
131 This documentation is covered by the BSD License as written in the
132 doc/LICENSE file. This man page was written by Jason Edgecombe for
133 OpenAFS.