Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | volscan - Produces detailed information about AFS volumes | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | B<volscan> | |
11 | [B<-checkout>] | |
12 | S<<< [B<-partition> <I<AFS partition name or id>>] >>> | |
13 | S<<< [B<-volumeid> <I<Volume id>>] >>> | |
14 | S<<< [B<-type> <I<Volume types (rw, ro, bk)>>+] >>> | |
15 | S<<< [B<-find> <I<Objects to find (file, dir, mount, symlink, acl)>>+] >>> | |
16 | S<<< [B<-output> <I<Column>>+] >>> | |
17 | S<<< [B<-delim> <I<Output field delimiter>>] >>> | |
18 | [B<-noheading>] | |
19 | [B<-ignore-magic>] | |
20 | [B<-help>] | |
21 | ||
22 | =for html | |
23 | </div> | |
24 | ||
25 | ||
26 | =head1 DESCRIPTION | |
27 | ||
28 | The B<volscan> command displays volume meta-data stored on AFS file servers. The | |
29 | output is intended for debugging purposes and is meaningful to someone familiar | |
30 | with the internal structure of AFS volumes. The B<volscan> command must be | |
31 | issued directly on a file server machine as the root superuser. The B<volscan> | |
32 | command does not modify volume information. | |
33 | ||
34 | The B<volscan> command will produce output for all the volumes on the file | |
35 | server by default. To display output for the volumes in one partition only, | |
36 | include the B<-partition> argument. To display output for one volume only, | |
37 | include the B<-partition> and B<-volumeid> arguments. | |
38 | ||
39 | The B<volscan> command will produce output for read-write, read-only, and | |
40 | backup volumes by default. To limit the output to particular types of volumes, | |
41 | include the B<-type> argument with one or more volume types (C<rw>, C<ro>, | |
42 | C<bk>). | |
43 | ||
44 | The B<volscan> command will produce output for each type of vnode object found | |
45 | in the volumes scanned. The command will output information for files, | |
46 | directories, AFS mount points, and symbolic links by default. The B<volscan> | |
47 | command can output access control lists (ACLs) for directory vnode objects | |
48 | scanned. To limit the output to particular types of vnode objects, or to | |
49 | output access control lists (ACLs), include the B<-find> argument with one or | |
50 | more object types (C<file>, C<dir>, C<mount>, C<symlink>, C<acl>). | |
51 | ||
52 | The output of the B<volscan> command is tabular. The output consists of an | |
53 | optional heading line, followed by zero or more lines of delimiter separated | |
54 | values. By default, the output values are the file server hostname (C<host>), | |
55 | the object type (C<desc>), the vnode FID (C<fid>), the vnode data version | |
56 | (C<dv>), and the directory path (C<path>). The directory path is relative to | |
57 | the root directory of the volume. When C<acl> is included as an argument to | |
58 | C<-find>, the default output values also include the user/group id (C<aid>) and | |
59 | the access rights (C<arights>). To specify different output values, include the | |
60 | C<-output> argument with one or more column names. See L<OUTPUT> for the column | |
61 | names. | |
62 | ||
63 | Values are space delimited by default. To use a different delimiter character, | |
64 | include the B<-delim> argument. Include the B<-noheading> flag to suppress the | |
65 | output heading line. | |
66 | ||
67 | =head1 OPTIONS | |
68 | ||
69 | =over 4 | |
70 | ||
71 | =item B<-checkout> | |
72 | ||
73 | Checkout the specified volume from the running file server. This ensures that | |
74 | the file server or other processes will not be modifying volume meta-data at the | |
75 | same time we are trying to read it, leading to invalid or incorrect results. | |
76 | ||
77 | =item B<-partition> <I<partition name or id>>+ | |
78 | ||
79 | Specifies the partition that houses each volume for which to produce output. | |
80 | Use the format F</vicepI<xx>> or I<xx>, where I<xx> is one or two lowercase | |
81 | letters. | |
82 | ||
83 | This argument can be omitted if the current working directory is the mount | |
84 | location for an AFS server partition. If the current working directory is not | |
85 | the mount location for an AFS server partition, the command produces output for | |
86 | every volume on all local AFS server partitions. | |
87 | ||
88 | =item B<-volumeid> <I<volume id>>+ | |
89 | ||
90 | Specifies the ID number of one volume for which to produce output. The | |
91 | B<-partition> argument must be provided along with this one unless the current | |
92 | working directory is the mount location for the AFS server partition that | |
93 | houses the volume. | |
94 | ||
95 | =item B<-type> <I<Volume types: rw, ro, bk>>+ | |
96 | ||
97 | Limit the volumes to be scanned by read/write, read-only, or backup volumes. | |
98 | Specify one or more of C<rw><rw>, C<ro>, C<bk>. The B<volscan> command will scan | |
99 | all types of volumes by default. | |
100 | ||
101 | =item B<-find> <I<Objects to find: file, dir, mount, symlink, acl>>+ | |
102 | ||
103 | Output the specified volume objects within the scanned volumes. Specify one or | |
104 | more of C<file>, C<dir>, C<mount>, C<symlink>, C<acl>. By default, the | |
105 | B<volscan> command will find C<file>, C<dir>, C<mount>, C<symlink> objects. | |
106 | ||
107 | =item B<-output> <I<Column>>+ | |
108 | ||
109 | The B<-output> argument specifies the output columns produced by the B<volscan> | |
110 | command. See the L<OUTPUT> section for <I<Column>> names. | |
111 | ||
112 | The default output columns are the file server hostname (C<host>), the object | |
113 | type (C<desc>), the vnode FID (C<fid>), the vnode data version (C<dv>), and the | |
114 | directory path (C<path>). When C<acl> is included as an argument to C<-find>, | |
115 | the default output values also include the user/group id (C<aid>) and the | |
116 | access rights (C<arights>). | |
117 | ||
118 | =item B<-delim> <I<Output field delimiter>> | |
119 | ||
120 | The B<-delim> argument specifies the record delimiter character. The default | |
121 | value is the space (C<' '>) character. | |
122 | ||
123 | =item B<-noheading> | |
124 | ||
125 | The B<-noheading> flags prevents the B<volscan> command from printing the | |
126 | heading line. | |
127 | ||
128 | =item B<-ignore-magic> | |
129 | ||
130 | Display vnodes even with incorrect vnode magic numbers. By default, the | |
131 | B<volscan> command will not process vnodes objects with incorrect vnode | |
132 | magic numbers. | |
133 | ||
134 | =item B<-help> | |
135 | ||
136 | Prints the online help for this command. All other valid options are | |
137 | ignored. | |
138 | ||
139 | =back | |
140 | ||
141 | =head1 OUTPUT | |
142 | ||
143 | The following column names are valid for the B<-output> argument: | |
144 | ||
145 | =over 4 | |
146 | ||
147 | =item C<host> | |
148 | ||
149 | The hostname of the current machine. This field may be useful when | |
150 | combining the B<volscan> output from several hosts. | |
151 | ||
152 | =item C<desc> | |
153 | ||
154 | The descriptive name of the type of volume object. Values are C<file>, C<dir>, | |
155 | C<symlink>, C<mount>, and C<acl>. | |
156 | ||
157 | =item C<vid> | |
158 | ||
159 | The numeric volume id. | |
160 | ||
161 | =item C<offset> | |
162 | ||
163 | The vnode index table offset. | |
164 | ||
165 | =item C<vtype> | |
166 | ||
167 | The volume type. Values are C<RW>, C<RO>, C<BK>. | |
168 | ||
169 | =item C<vname> | |
170 | ||
171 | The volume name. | |
172 | ||
173 | =item C<part> | |
174 | ||
175 | The partition path. | |
176 | ||
177 | =item C<partid> | |
178 | ||
179 | The AFS partition id. | |
180 | ||
181 | =item C<fid> | |
182 | ||
183 | The AFS File Identifier (FID). | |
184 | ||
185 | =item C<path> | |
186 | ||
187 | The directory path and filename. The path is relative to the volume root directory. | |
188 | ||
189 | =item C<target> | |
190 | ||
191 | The symlink target. Empty if the vnode is not a symlink. | |
192 | ||
193 | =item C<mount> | |
194 | ||
195 | The mount point value. Empty if the vnode is not a mount point. See L<fs lsmount> | |
196 | for the mount point value format. | |
197 | ||
198 | =item C<mtype> | |
199 | ||
200 | The mount point type. Empty if the vnode is not a mount point. Values are C<'#'> for | |
201 | regular mount points and C<'%'> for read-write mount points. | |
202 | ||
203 | =item C<mcell> | |
204 | ||
205 | The mount point target cell. Empty if the vnode is not a cellular mount point. | |
206 | ||
207 | =item C<mvol> | |
208 | ||
209 | The mount point target volume. Empty if the vnode is not a mount point. | |
210 | ||
211 | =item C<aid> | |
212 | ||
213 | Access entry user or group id. Empty if the object is not an ACL. | |
214 | ||
215 | =item C<arights> | |
216 | ||
217 | Access entry rights. Empty if the object is not an ACL. | |
218 | ||
219 | =item C<vntype> | |
220 | ||
221 | The vnode type. Values are C<file>, C<dir>, C<symlink>. | |
222 | ||
223 | =item C<cloned> | |
224 | ||
225 | The vnode cloned flag. Values are C<y> or C<n>. | |
226 | ||
227 | =item C<mode> | |
228 | ||
229 | The vnode Unix mode bits, as an octal number. | |
230 | ||
231 | =item C<links> | |
232 | ||
233 | The vnode link count. | |
234 | ||
235 | =item C<length> | |
236 | ||
237 | The vnode data length. | |
238 | ||
239 | =item C<uniq> | |
240 | ||
241 | The vnode uniquifier number. | |
242 | ||
243 | =item C<dv> | |
244 | ||
245 | The vnode data version number. | |
246 | ||
247 | =item C<inode> | |
248 | ||
249 | The vnode inode number. This is an internally used number on namei file servers. | |
250 | ||
251 | =item C<namei> | |
252 | ||
253 | The vnode namei path. | |
254 | ||
255 | =item C<modtime> | |
256 | ||
257 | The vnode modification time. | |
258 | ||
259 | =item C<author> | |
260 | ||
261 | The vnode author user id. | |
262 | ||
263 | =item C<owner> | |
264 | ||
265 | The vnode Unix owner id. | |
266 | ||
267 | =item C<parent> | |
268 | ||
269 | The parent directory vnode number. | |
270 | ||
271 | =item C<magic> | |
272 | ||
273 | The vnode magic number. | |
274 | ||
275 | =item C<lock> | |
276 | ||
277 | The vnode lock count and time. The format is <I<count>>.<I<time>>, where <I<time>> is | |
278 | the epoch time. | |
279 | ||
280 | =item C<smodtime> | |
281 | ||
282 | The vnode server modify time. | |
283 | ||
284 | =item C<group> | |
285 | ||
286 | The vnode unix group id. | |
287 | ||
288 | =back | |
289 | ||
290 | =head1 EXAMPLES | |
291 | ||
292 | The following command displays the FID, data version, and relative path for each | |
293 | vnode object in a volume. | |
294 | ||
295 | # volscan -partition a -volumeid 536870916 | |
296 | HOST DESC FID DV PATH | |
297 | fs1 dir 536870916.1.1 3 / | |
298 | fs1 mount 536870916.2.2 0 /test | |
299 | fs1 mount 536870916.4.3 0 /xyzzy | |
300 | ||
301 | ||
302 | The following command displays the AFS mount points in all the read-write | |
303 | volumes on the file server. For each mount point the following is shown: the | |
304 | volume containing the mount point, the type of mount point, regular (C<#>) or | |
305 | read-write (C<%>), the target cell (or C<-> if not a cellular mount point), the | |
306 | name of the target volume, the path of the mount point within the volume | |
307 | (relative to the volume root directory). | |
308 | ||
309 | # volscan -type rw -find mount -output vid mtype mcell mvol path -noheading | |
310 | 536870915 # - test /test | |
311 | 536870912 # example.com root.cell /example.com | |
312 | 536870912 % example.com root.cell /.example.com | |
313 | ||
314 | ||
315 | The following command displays access control lists for a volume. | |
316 | ||
317 | # volscan -partition a -volumeid 536870918 -find acl \ | |
318 | -output fid aid arights path -delim : -noheading | |
319 | 536870918.1.1:-204:+rlidwka:/ | |
320 | 536870918.1.1:-101:+rl:/ | |
321 | 536870918.3.3:-204:+rlidwka:/xyzzy | |
322 | 536870918.3.3:-101:+rl:/xyzzy | |
323 | 536870918.3.3:1027:+rlidwk:/xyzzy | |
324 | ||
325 | ||
326 | The following commands find files which have unix permissions bit C<04000> | |
327 | (C<suid>) or C<02000> (C<sgid>): | |
328 | ||
329 | # volscan -find file -output fid mode -noheading | \ | |
330 | perl -lane 'print if oct($F[1]) & 06000' | |
331 | ||
332 | ||
333 | =head1 PRIVILEGE REQUIRED | |
334 | ||
335 | The issuer must be logged in as the local superuser C<root>. | |
336 | ||
337 | =head1 SEE ALSO | |
338 | ||
339 | L<volinfo(8)>, | |
340 | L<vldb.DB0(5)>, | |
341 | L<volserver(8)> | |
342 | ||
343 | =head1 COPYRIGHT | |
344 | ||
345 | Copyright 2014 Sine Nomine Associates. All Rights Reserved. | |
346 | ||
347 | This documentation is covered by the BSD License as written in the | |
348 | doc/LICENSE file. This man page was written by Michael Meffie for | |
349 | OpenAFS. |