From: Michael Meffie Date: Thu, 13 Mar 2014 16:40:17 +0000 (-0400) Subject: doc: volscan man page X-Git-Tag: openafs-stable-1_8_0pre1~743 X-Git-Url: https://git.openafs.org/?p=openafs.git;a=commitdiff_plain;h=a30b98c97d6fbf87018bcb6943e09c1c75a3918d doc: volscan man page Provide a man page for the volscan utility Change-Id: Ibaecb2b9030ee71d81f13b897694c4cf3b4b9516 Reviewed-on: http://gerrit.openafs.org/10905 Reviewed-by: D Brashear Tested-by: D Brashear --- diff --git a/doc/man-pages/NTMakefile b/doc/man-pages/NTMakefile index d22f57a..eb6e4c5 100644 --- a/doc/man-pages/NTMakefile +++ b/doc/man-pages/NTMakefile @@ -343,6 +343,7 @@ PODS = \ pod8\vlserver.pod \ pod8\voldump.pod \ pod8\volinfo.pod \ + pod8\volscan.pod \ pod8\volserver.pod \ pod8\vsys.pod \ pod8\xfs_size_check.pod diff --git a/doc/man-pages/pod1/afs.pod b/doc/man-pages/pod1/afs.pod index 6da428b..66fcd5a 100644 --- a/doc/man-pages/pod1/afs.pod +++ b/doc/man-pages/pod1/afs.pod @@ -549,6 +549,7 @@ L, L, L, L, +L, L, L, L, diff --git a/doc/man-pages/pod8/volinfo.pod b/doc/man-pages/pod8/volinfo.pod index cd1c470..7570f59 100644 --- a/doc/man-pages/pod8/volinfo.pod +++ b/doc/man-pages/pod8/volinfo.pod @@ -130,6 +130,7 @@ The issuer must be logged in as the local superuser C. =head1 SEE ALSO +L, L, L diff --git a/doc/man-pages/pod8/volscan.pod b/doc/man-pages/pod8/volscan.pod new file mode 100644 index 0000000..496e405 --- /dev/null +++ b/doc/man-pages/pod8/volscan.pod @@ -0,0 +1,348 @@ +=head1 NAME + +volscan - Produces detailed information about AFS volumes + +=head1 SYNOPSIS + +=for html +
+ +B + [B<-checkout>] + S<<< [B<-partition> >] >>> + S<<< [B<-volumeid> >] >>> + S<<< [B<-type> >+] >>> + S<<< [B<-find> >+] >>> + S<<< [B<-output> >+] >>> + S<<< [B<-delim> >] >>> + [B<-noheading>] + [B<-ignore-magic>] + [B<-help>] + +=for html +
+ + +=head1 DESCRIPTION + +The B 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 command must be +issued directly on a file server machine as the root superuser. The B +command does not modify volume information. + +The B 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 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, C, +C). + +The B 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 +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, C, C, C, C). + +The output of the B 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), +the object type (C), the vnode FID (C), the vnode data version +(C), and the directory path (C). The directory path is relative to +the root directory of the volume. When C is included as an argument to +C<-find>, the default output values also include the user/group id (C) and +the access rights (C). To specify different output values, include the +C<-output> argument with one or more column names. See L 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> >+ + +Specifies the partition that houses each volume for which to produce output. +Use the format F> or I, where I 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> >+ + +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> >+ + +Limit the volumes to be scanned by read/write, read-only, or backup volumes. +Specify one or more of C, C, C. The B command will scan +all types of volumes by default. + +=item B<-find> >+ + +Output the specified volume objects within the scanned volumes. Specify one or +more of C, C, C, C, C. By default, the +B command will find C, C, C, C objects. + +=item B<-output> >+ + +The B<-output> argument specifies the output columns produced by the B +command. See the L section for > names. + +The default output columns are the file server hostname (C), the object +type (C), the vnode FID (C), the vnode data version (C), and the +directory path (C). When C is included as an argument to C<-find>, +the default output values also include the user/group id (C) and the +access rights (C). + +=item B<-delim> > + +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 command from printing the +heading line. + +=item B<-ignore-magic> + +Display vnodes even with incorrect vnode magic numbers. By default, the +B 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 + +The hostname of the current machine. This field may be useful when +combining the B output from several hosts. + +=item C + +The descriptive name of the type of volume object. Values are C, C, +C, C, and C. + +=item C + +The numeric volume id. + +=item C + +The vnode index table offset. + +=item C + +The volume type. Values are C, C, C. + +=item C + +The volume name. + +=item C + +The partition path. + +=item C + +The AFS partition id. + +=item C + +The AFS File Identifier (FID). + +=item C + +The directory path and filename. The path is relative to the volume root directory. + +=item C + +The symlink target. Empty if the vnode is not a symlink. + +=item C + +The mount point value. Empty if the vnode is not a mount point. See L +for the mount point value format. + +=item C + +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 + +The mount point target cell. Empty if the vnode is not a cellular mount point. + +=item C + +The mount point target volume. Empty if the vnode is not a mount point. + +=item C + +Access entry user or group id. Empty if the object is not an ACL. + +=item C + +Access entry rights. Empty if the object is not an ACL. + +=item C + +The vnode type. Values are C, C, C. + +=item C + +The vnode cloned flag. Values are C or C. + +=item C + +The vnode Unix mode bits, as an octal number. + +=item C + +The vnode link count. + +=item C + +The vnode data length. + +=item C + +The vnode uniquifier number. + +=item C + +The vnode data version number. + +=item C + +The vnode inode number. This is an internally used number on namei file servers. + +=item C + +The vnode namei path. + +=item C + +The vnode modification time. + +=item C + +The vnode author user id. + +=item C + +The vnode Unix owner id. + +=item C + +The parent directory vnode number. + +=item C + +The vnode magic number. + +=item C + +The vnode lock count and time. The format is >.>, where > is +the epoch time. + +=item C + +The vnode server modify time. + +=item C + +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) or C<02000> (C): + + # 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. + +=head1 SEE ALSO + +L, +L, +L + +=head1 COPYRIGHT + +IBM Corporation 2000. All Rights Reserved. +Sine Nomine Associates 2014. All Rights Reserved. + +This documentation is covered by the IBM Public License Version 1.0.