man-page-vos-setfields-20090316
[openafs.git] / doc / man-pages / pod1 / vos_setfields.pod
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)>> >>> [B<-clearuse>]
12     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
13     [B<-verbose>] [B<-encrypt>] [b<-noresolve>] [B<-help>]
14
15 B<vos se> S<<< B<-id> <I<volume name or ID>> >>>
16     S<<< B<-maxquota> <I<quota (KB)>> >>> [B<-clearuse>]
17     S<<< [B<-cell> <I<cell name>>] >>> [B<-noauth>] [B<-localauth>]
18     [B<-verbose>] [B<-encrypt>] [b<-noresolve>] [B<-help>]
19
20 =for html
21 </div>
22
23 =head1 DESCRIPTION
24
25 The B<vos setfields> command can set the quota on a volume, and it can
26 clear the access counter on a volume. This command differs from
27 B<fs setquota> because only the volume name is needed to set the quota,
28 whereas the path to the volume is needed with B<fs setquota>.
29
30 If the B<-maxquota> and B<-clearuse> flags are missing, then no action is
31 taken.
32
33 =head1 CAUTIONS
34
35 This command is not effective on read-only or backup volumes.
36
37 =head1 OPTIONS
38
39 =over 4
40
41 =item B<-id> <I<volume name or id>>
42
43 Identifies the volume on which to operate, either by its complete name or
44 volume ID number.
45
46 =item B<-maxquota> <I<cell name>>
47
48 Sets the maximum amount of file server disk space the volume can
49 occupy. Specify the number of one-kilobyte blocks as a positive integer
50 (C<1024> is one megabyte). A value of C<0> sets an unlimited quota, but
51 the size of the disk partition that houses the volume places an absolute
52 limit on the volume's size.
53
54 =item B<-clearuse>
55
56 Clears the access counter on a volumes, which is shown as C<X accesses in
57 the past day (i.e., vnode references)> in the B<vos examine> output.
58
59 =item B<-cell> <I<cell name>>
60
61 Names the cell in which to run the command. Do not combine this argument
62 with the B<-localauth> flag. For more details, see L<vos(1)>.
63
64 =item B<-noauth>
65
66 Assigns the unprivileged identity C<anonymous> to the issuer. Do not
67 combine this flag with the B<-localauth> flag. For more details, see
68 L<vos(1)>.
69
70 =item B<-localauth>
71
72 Constructs a server ticket using a key from the local
73 F</usr/afs/etc/KeyFile> file. The B<vos> command interpreter presents it
74 to the Volume Server and Volume Location Server during mutual
75 authentication. Do not combine this flag with the B<-cell> argument or
76 B<-noauth> flag. For more details, see L<vos(1)>.
77
78 =item B<-encrypt>
79
80 Encrypts the command so that the operation's results are not transmitted
81 across the network in clear text.
82
83 =item B<-noresolve>
84
85 Shows all servers as IP addresses instead of the DNS name. This is very
86 useful when the server address is registered as 127.0.0.1 or when dealing
87 with multi-homed servers. The B<-noresolve> option is available in OpenAFS
88 versions 1.4.8 or later and 1.5.35 or later.
89
90 =item B<-verbose>
91
92 Produces on the standard output stream a detailed trace of the command's
93 execution. If this argument is omitted, only warnings and error messages
94 appear.
95
96 =item B<-help>
97
98 Prints the online help for this command. All other valid options are
99 ignored.
100
101 =back
102
103 =head1 OUTPUT
104
105 This command produces no output other than error messages.
106
107 =head1 EXAMPLES
108
109 To set a 123KB quota on the root.cell volume, the following command may be
110 used:
111
112    % vos setfields -id root.cell -maxquota 123
113
114 To clear the access counter on the root.cell volume, use the following
115 command:
116
117    % vos setfields -id root.cell -clearuse
118
119 The above commands may be combined as follows:
120
121    % vos setfields -id root.cell -maxquota 123 -clearuse
122
123 =head1 PRIVILEGE REQUIRED
124
125 The issuer must be listed in the F</usr/afs/etc/UserList> file on the
126 machine specified with the B<-server> argument and on each database server
127 machine. If the B<-localauth> flag is included, the issuer must instead be
128 logged on to a server machine as the local superuser C<root>.
129
130 =head1 SEE ALSO
131
132 L<fs_setquota(1)>,
133 L<vos(1)>,
134 L<vos_examine(1)>
135
136 =head1 COPYRIGHT
137
138 Copyright 2009 Jason Edgecombe <jason@rampaginggeek.com>
139
140 This documentation is covered by the BSD License as written in the
141 doc/LICENSE file. This man page was written by Jason Edgecombe for
142 OpenAFS.