doc: vos manpage fixes
[openafs.git] / doc / man-pages / pod1 / vos_setfields.pod.in
1 =head1 NAME
2
3 vos_setfields - Sets the quota or clear the access counter on a volume.
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<vos setfields> S<<< B<-id> <I<volume name or ID>> >>>
11     S<<< B<-maxquota> <I<quota (KB)>> >>>
12     [B<-clearuse>] [B<-clearVolUpCounter>]
13     S<<< [B<-cell> <I<cell name>>] >>>
14     [B<-noauth>] [B<-localauth>]
15     [B<-verbose>] [B<-encrypt>] [B<-noresolve>]
16     S<<< [B<-config> <I<config directory>>] >>>
17     [B<-help>]
18
19 B<vos se> S<<< B<-id> <I<volume name or ID>> >>>
20     S<<< B<-m> <I<quota (KB)>> >>> [B<-cl>]
21     S<<< [B<-ce> <I<cell name>>] >>>
22     [B<-noa>] [B<-l>] [B<-v>] [B<-e>] [B<-nor>]
23     S<<< [B<-co> <I<config directory>>] >>>
24     [B<-h>]
25
26 =for html
27 </div>
28
29 =head1 DESCRIPTION
30
31 The B<vos setfields> command can set the quota on a volume, and it can
32 clear the access counter on a volume. This command differs from
33 B<fs setquota> because only the volume name is needed to set the quota,
34 whereas the path to the volume is needed with B<fs setquota>.
35
36 If the B<-maxquota> and B<-clearuse> flags are missing, then no action is
37 taken.
38
39 =head1 CAUTIONS
40
41 This command is not effective on read-only or backup volumes.
42
43 =head1 OPTIONS
44
45 =over 4
46
47 =item B<-id> <I<volume name or id>>
48
49 Identifies the volume on which to operate, either by its complete name or
50 volume ID number.
51
52 =item B<-maxquota> <I<quota>>
53
54 Sets the maximum amount of file server disk space the volume can occupy.
55 The quota should be a positive integer followed by an optional suffix:
56 C<K> for kibibytes (1024 bytes, the default), C<M> for mebibytes (1024
57 kibibytes), C<G> for gibibytes (1024 mebibytes), and C<T> for tebibytes
58 (1024 gibibytes).  A value of C<0> sets an unlimited quota, but the size
59 of the disk partition that houses the volume places an absolute limit on
60 the volume's size.
61
62 =item B<-clearuse>
63
64 Clears the access counter on a volume, which is shown as C<X accesses in
65 the past day (i.e., vnode references)> in the B<vos examine> output.
66
67 =item B<-clearVolUpCounter>
68
69 Clears the modification counter on a volume. The modification counter
70 will increment with time and stop updating when it reaches the maximum
71 value. This option will reset it to 0. This option is available in OpenAFS
72 version 1.5.0 or later.
73
74 =include fragments/vos-common.pod
75
76 =back
77
78 =head1 OUTPUT
79
80 This command produces no output other than error messages.
81
82 =head1 EXAMPLES
83
84 To set a 123KB quota on the root.cell volume, the following command may be
85 used:
86
87    % vos setfields -id root.cell -maxquota 123
88
89 To clear the access counter on the root.cell volume, use the following
90 command:
91
92    % vos setfields -id root.cell -clearuse
93
94 The above commands may be combined as follows:
95
96    % vos setfields -id root.cell -maxquota 123 -clearuse
97
98 =head1 PRIVILEGE REQUIRED
99
100 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
101 machine specified with the B<-server> argument and on each database server
102 machine. If the B<-localauth> flag is included, the issuer must instead be
103 logged on to a server machine as the local superuser C<root>.
104
105 =head1 SEE ALSO
106
107 L<fs_setquota(1)>,
108 L<vos(1)>,
109 L<vos_examine(1)>
110
111 =head1 COPYRIGHT
112
113 Copyright 2009 Jason Edgecombe <jason@rampaginggeek.com>
114
115 This documentation is covered by the BSD License as written in the
116 doc/LICENSE file. This man page was written by Jason Edgecombe for
117 OpenAFS.