Provided by: openafs-fileserver_1.8.9-1ubuntu1_amd64 bug

NAME

       volscan - Produces detailed information about AFS volumes

SYNOPSIS

       volscan
           [-checkout]
           [-partition <AFS partition name or id>]
           [-volumeid <Volume id>]
           [-type <Volume types (rw, ro, bk)>+]
           [-find <Objects to find (file, dir, mount, symlink, acl)>+]
           [-output <Column>+]
           [-delim <Output field delimiter>]
           [-noheading]
           [-ignore-magic]
           [-help]

DESCRIPTION

       The 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 volscan command must be issued directly on a file server
       machine as the root superuser.  The volscan command does not modify volume information.

       The 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 -partition argument.
       To display output for one volume only, include the -partition and -volumeid arguments.

       The 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 -type argument
       with one or more volume types ("rw", "ro", "bk").

       The 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 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 -find argument with one or
       more object types ("file", "dir", "mount", "symlink", "acl").

       The output of the 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 ("host"), the object type ("desc"), the vnode
       FID ("fid"), the vnode data version ("dv"), and the directory path ("path"). The directory
       path is relative to the root directory of the volume.  When "acl" is included as an
       argument to "-find", the default output values also include the user/group id ("aid") and
       the access rights ("arights").  To specify different output values, include the "-output"
       argument with one or more column names. See OUTPUT for the column names.

       Values are space delimited by default. To use a different delimiter character, include the
       -delim argument.  Include the -noheading flag to suppress the output heading line.

OPTIONS

       -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.

       -partition <partition name or id>+
           Specifies the partition that houses each volume for which to produce output.  Use the
           format /vicepxx or xx, where 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.

       -volumeid <volume id>+
           Specifies the ID number of one volume for which to produce output.  The -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.

       -type <Volume types: rw, ro, bk>+
           Limit the volumes to be scanned by read/write, read-only, or backup volumes.  Specify
           one or more of "rw"<rw>, "ro", "bk".  The volscan command will scan all types of
           volumes by default.

       -find <Objects to find: file, dir, mount, symlink, acl>+
           Output the specified volume objects within the scanned volumes. Specify one or more of
           "file", "dir", "mount", "symlink", "acl".  By default, the volscan command will find
           "file", "dir", "mount", "symlink" objects.

       -output <Column>+
           The -output argument specifies the output columns produced by the volscan command. See
           the OUTPUT section for <Column> names.

           The default output columns are the file server hostname ("host"), the object type
           ("desc"), the vnode FID ("fid"), the vnode data version ("dv"), and the directory path
           ("path").  When "acl" is included as an argument to "-find", the default output values
           also include the user/group id ("aid") and the access rights ("arights").

       -delim <Output field delimiter>
           The -delim argument specifies the record delimiter character. The default value is the
           space (' ') character.

       -noheading
           The -noheading flags prevents the volscan command from printing the heading line.

       -ignore-magic
           Display vnodes even with incorrect vnode magic numbers. By default, the volscan
           command will not process vnodes objects with incorrect vnode magic numbers.

       -help
           Prints the online help for this command. All other valid options are ignored.

OUTPUT

       The following column names are valid for the -output argument:

       "host"
           The hostname of the current machine. This field may be useful when combining the
           volscan output from several hosts.

       "desc"
           The descriptive name of the type of volume object.  Values are "file", "dir",
           "symlink", "mount", and "acl".

       "vid"
           The numeric volume id.

       "offset"
           The vnode index table offset.

       "vtype"
           The volume type. Values are "RW", "RO", "BK".

       "vname"
           The volume name.

       "part"
           The partition path.

       "partid"
           The AFS partition id.

       "fid"
           The AFS File Identifier (FID).

       "path"
           The directory path and filename. The path is relative to the volume root directory.

       "target"
           The symlink target. Empty if the vnode is not a symlink.

       "mount"
           The mount point value. Empty if the vnode is not a mount point. See "fs lsmount" for
           the mount point value format.

       "mtype"
           The mount point type. Empty if the vnode is not a mount point. Values are '#' for
           regular mount points and '%' for read-write mount points.

       "mcell"
           The mount point target cell. Empty if the vnode is not a cellular mount point.

       "mvol"
           The mount point target volume. Empty if the vnode is not a mount point.

       "aid"
           Access entry user or group id. Empty if the object is not an ACL.

       "arights"
           Access entry rights. Empty if the object is not an ACL.

       "vntype"
           The vnode type. Values are "file", "dir", "symlink".

       "cloned"
           The vnode cloned flag. Values are "y" or "n".

       "mode"
           The vnode Unix mode bits, as an octal number.

       "links"
           The vnode link count.

       "length"
           The vnode data length.

       "uniq"
           The vnode uniquifier number.

       "dv"
           The vnode data version number.

       "inode"
           The vnode inode number. This is an internally used number on namei file servers.

       "namei"
           The vnode namei path.

       "modtime"
           The vnode modification time.

       "author"
           The vnode author user id.

       "owner"
           The vnode Unix owner id.

       "parent"
           The parent directory vnode number.

       "magic"
           The vnode magic number.

       "lock"
           The vnode lock count and time. The format is <count>.<time>, where <time> is the epoch
           time.

       "smodtime"
           The vnode server modify time.

       "group"
           The vnode unix group id.

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 ("#") or read-write ("%"), the target cell (or "-"
       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 04000 ("suid") or 02000
       ("sgid"):

           # volscan -find file -output fid mode -noheading | \
              perl -lane 'print if oct($F[1]) & 06000'

PRIVILEGE REQUIRED

       The issuer must be logged in as the local superuser "root".

SEE ALSO

       volinfo(8), vldb.DB0(5), volserver(8)

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.