doc/man-pages/pod8/volscan.pod

   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.