--- /dev/null
+=head1 NAME
+
+volscan - Produces detailed information about AFS volumes
+
+=head1 SYNOPSIS
+
+=for html
+<div class="synopsis">
+
+B<volscan>
+ [B<-checkout>]
+ S<<< [B<-partition> <I<AFS partition name or id>>] >>>
+ S<<< [B<-volumeid> <I<Volume id>>] >>>
+ S<<< [B<-type> <I<Volume types (rw, ro, bk)>>+] >>>
+ S<<< [B<-find> <I<Objects to find (file, dir, mount, symlink, acl)>>+] >>>
+ S<<< [B<-output> <I<Column>>+] >>>
+ S<<< [B<-delim> <I<Output field delimiter>>] >>>
+ [B<-noheading>]
+ [B<-ignore-magic>]
+ [B<-help>]
+
+=for html
+</div>
+
+
+=head1 DESCRIPTION
+
+The B<volscan> command displays volume meta-data stored on AFS file servers. The
+output is intended for debugging purposes and is meaningful to someone familiar
+with the internal structure of AFS volumes. The B<volscan> command must be
+issued directly on a file server machine as the root superuser. The B<volscan>
+command does not modify volume information.
+
+The B<volscan> command will produce output for all the volumes on the file
+server by default. To display output for the volumes in one partition only,
+include the B<-partition> argument. To display output for one volume only,
+include the B<-partition> and B<-volumeid> arguments.
+
+The B<volscan> command will produce output for read-write, read-only, and
+backup volumes by default. To limit the output to particular types of volumes,
+include the B<-type> argument with one or more volume types (C<rw>, C<ro>,
+C<bk>).
+
+The B<volscan> command will produce output for each type of vnode object found
+in the volumes scanned. The command will output information for files,
+directories, AFS mount points, and symbolic links by default. The B<volscan>
+command can output access control lists (ACLs) for directory vnode objects
+scanned. To limit the output to particular types of vnode objects, or to
+output access control lists (ACLs), include the B<-find> argument with one or
+more object types (C<file>, C<dir>, C<mount>, C<symlink>, C<acl>).
+
+The output of the B<volscan> command is tabular. The output consists of an
+optional heading line, followed by zero or more lines of delimiter separated
+values. By default, the output values are the file server hostname (C<host>),
+the object type (C<desc>), the vnode FID (C<fid>), the vnode data version
+(C<dv>), and the directory path (C<path>). The directory path is relative to
+the root directory of the volume. When C<acl> is included as an argument to
+C<-find>, the default output values also include the user/group id (C<aid>) and
+the access rights (C<arights>). To specify different output values, include the
+C<-output> argument with one or more column names. See L<OUTPUT> for the column
+names.
+
+Values are space delimited by default. To use a different delimiter character,
+include the B<-delim> argument. Include the B<-noheading> flag to suppress the
+output heading line.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-checkout>
+
+Checkout the specified volume from the running file server. This ensures that
+the file server or other processes will not be modifying volume meta-data at the
+same time we are trying to read it, leading to invalid or incorrect results.
+
+=item B<-partition> <I<partition name or id>>+
+
+Specifies the partition that houses each volume for which to produce output.
+Use the format F</vicepI<xx>> or I<xx>, where I<xx> is one or two lowercase
+letters.
+
+This argument can be omitted if the current working directory is the mount
+location for an AFS server partition. If the current working directory is not
+the mount location for an AFS server partition, the command produces output for
+every volume on all local AFS server partitions.
+
+=item B<-volumeid> <I<volume id>>+
+
+Specifies the ID number of one volume for which to produce output. The
+B<-partition> argument must be provided along with this one unless the current
+working directory is the mount location for the AFS server partition that
+houses the volume.
+
+=item B<-type> <I<Volume types: rw, ro, bk>>+
+
+Limit the volumes to be scanned by read/write, read-only, or backup volumes.
+Specify one or more of C<rw><rw>, C<ro>, C<bk>. The B<volscan> command will scan
+all types of volumes by default.
+
+=item B<-find> <I<Objects to find: file, dir, mount, symlink, acl>>+
+
+Output the specified volume objects within the scanned volumes. Specify one or
+more of C<file>, C<dir>, C<mount>, C<symlink>, C<acl>. By default, the
+B<volscan> command will find C<file>, C<dir>, C<mount>, C<symlink> objects.
+
+=item B<-output> <I<Column>>+
+
+The B<-output> argument specifies the output columns produced by the B<volscan>
+command. See the L<OUTPUT> section for <I<Column>> names.
+
+The default output columns are the file server hostname (C<host>), the object
+type (C<desc>), the vnode FID (C<fid>), the vnode data version (C<dv>), and the
+directory path (C<path>). When C<acl> is included as an argument to C<-find>,
+the default output values also include the user/group id (C<aid>) and the
+access rights (C<arights>).
+
+=item B<-delim> <I<Output field delimiter>>
+
+The B<-delim> argument specifies the record delimiter character. The default
+value is the space (C<' '>) character.
+
+=item B<-noheading>
+
+The B<-noheading> flags prevents the B<volscan> command from printing the
+heading line.
+
+=item B<-ignore-magic>
+
+Display vnodes even with incorrect vnode magic numbers. By default, the
+B<volscan> command will not process vnodes objects with incorrect vnode
+magic numbers.
+
+=item B<-help>
+
+Prints the online help for this command. All other valid options are
+ignored.
+
+=back
+
+=head1 OUTPUT
+
+The following column names are valid for the B<-output> argument:
+
+=over 4
+
+=item C<host>
+
+The hostname of the current machine. This field may be useful when
+combining the B<volscan> output from several hosts.
+
+=item C<desc>
+
+The descriptive name of the type of volume object. Values are C<file>, C<dir>,
+C<symlink>, C<mount>, and C<acl>.
+
+=item C<vid>
+
+The numeric volume id.
+
+=item C<offset>
+
+The vnode index table offset.
+
+=item C<vtype>
+
+The volume type. Values are C<RW>, C<RO>, C<BK>.
+
+=item C<vname>
+
+The volume name.
+
+=item C<part>
+
+The partition path.
+
+=item C<partid>
+
+The AFS partition id.
+
+=item C<fid>
+
+The AFS File Identifier (FID).
+
+=item C<path>
+
+The directory path and filename. The path is relative to the volume root directory.
+
+=item C<target>
+
+The symlink target. Empty if the vnode is not a symlink.
+
+=item C<mount>
+
+The mount point value. Empty if the vnode is not a mount point. See L<fs lsmount>
+for the mount point value format.
+
+=item C<mtype>
+
+The mount point type. Empty if the vnode is not a mount point. Values are C<'#'> for
+regular mount points and C<'%'> for read-write mount points.
+
+=item C<mcell>
+
+The mount point target cell. Empty if the vnode is not a cellular mount point.
+
+=item C<mvol>
+
+The mount point target volume. Empty if the vnode is not a mount point.
+
+=item C<aid>
+
+Access entry user or group id. Empty if the object is not an ACL.
+
+=item C<arights>
+
+Access entry rights. Empty if the object is not an ACL.
+
+=item C<vntype>
+
+The vnode type. Values are C<file>, C<dir>, C<symlink>.
+
+=item C<cloned>
+
+The vnode cloned flag. Values are C<y> or C<n>.
+
+=item C<mode>
+
+The vnode Unix mode bits, as an octal number.
+
+=item C<links>
+
+The vnode link count.
+
+=item C<length>
+
+The vnode data length.
+
+=item C<uniq>
+
+The vnode uniquifier number.
+
+=item C<dv>
+
+The vnode data version number.
+
+=item C<inode>
+
+The vnode inode number. This is an internally used number on namei file servers.
+
+=item C<namei>
+
+The vnode namei path.
+
+=item C<modtime>
+
+The vnode modification time.
+
+=item C<author>
+
+The vnode author user id.
+
+=item C<owner>
+
+The vnode Unix owner id.
+
+=item C<parent>
+
+The parent directory vnode number.
+
+=item C<magic>
+
+The vnode magic number.
+
+=item C<lock>
+
+The vnode lock count and time. The format is <I<count>>.<I<time>>, where <I<time>> is
+the epoch time.
+
+=item C<smodtime>
+
+The vnode server modify time.
+
+=item C<group>
+
+The vnode unix group id.
+
+=back
+
+=head1 EXAMPLES
+
+The following command displays the FID, data version, and relative path for each
+vnode object in a volume.
+
+ # volscan -partition a -volumeid 536870916
+ HOST DESC FID DV PATH
+ fs1 dir 536870916.1.1 3 /
+ fs1 mount 536870916.2.2 0 /test
+ fs1 mount 536870916.4.3 0 /xyzzy
+
+
+The following command displays the AFS mount points in all the read-write
+volumes on the file server. For each mount point the following is shown: the
+volume containing the mount point, the type of mount point, regular (C<#>) or
+read-write (C<%>), the target cell (or C<-> if not a cellular mount point), the
+name of the target volume, the path of the mount point within the volume
+(relative to the volume root directory).
+
+ # volscan -type rw -find mount -output vid mtype mcell mvol path -noheading
+ 536870915 # - test /test
+ 536870912 # example.com root.cell /example.com
+ 536870912 % example.com root.cell /.example.com
+
+
+The following command displays access control lists for a volume.
+
+ # volscan -partition a -volumeid 536870918 -find acl \
+ -output fid aid arights path -delim : -noheading
+ 536870918.1.1:-204:+rlidwka:/
+ 536870918.1.1:-101:+rl:/
+ 536870918.3.3:-204:+rlidwka:/xyzzy
+ 536870918.3.3:-101:+rl:/xyzzy
+ 536870918.3.3:1027:+rlidwk:/xyzzy
+
+
+The following commands find files which have unix permissions bit C<04000>
+(C<suid>) or C<02000> (C<sgid>):
+
+ # volscan -find file -output fid mode -noheading | \
+ perl -lane 'print if oct($F[1]) & 06000'
+
+
+=head1 PRIVILEGE REQUIRED
+
+The issuer must be logged in as the local superuser C<root>.
+
+=head1 SEE ALSO
+
+L<volinfo(8)>,
+L<vldb.DB0(5)>,
+L<volserver(8)>
+
+=head1 COPYRIGHT
+
+IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
+Sine Nomine Associates 2014. All Rights Reserved.
+
+This documentation is covered by the IBM Public License Version 1.0.
git://git.openafs.org / openafs.git / commitdiff