=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

Copyright 2014 Sine Nomine Associates.  All Rights Reserved.

This documentation is covered by the BSD License as written in the
doc/LICENSE file. This man page was written by Michael Meffie for
OpenAFS.