VOLSCAN(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💅 VOLSCAN(8) — aka the AFS Command Reference glow-up ✨

okay bestie, listen up, this is volscan from the AFS Command Reference and she is THAT girl — she spills all the tea about what's actually inside your AFS volumes. 🫖💖

🌸 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 🦋

so basically, volscan shows you the volume meta-data stored over on your AFS file servers. it's giving debugging tool energy — the output is meant for someone who already knows the internal structure of AFS volumes, iykyk. 💀

bestie this is IMPORTANT: you gotta run volscan directly on a file server machine, and as the root superuser. no cap.

the good news? volscan does not modify volume information. she's just looking. respectful. 🫶

by default, she produces output for all the volumes on the file server. wanna narrow it down to one partition? include the -partition argument. wanna narrow it to just ONE volume? include both -partition AND -volumeid. 💅

she'll produce output for read-write, read-only, and backup volumes by default. to limit it to particular types, pass -type with one or more volume types ("rw", "ro", "bk").

she also produces output for each type of vnode object found in the volumes scanned. by default that means files, directories, AFS mount points, and symbolic links. she can also output access control lists (ACLs) for directory vnode objects scanned. to limit output to particular types of vnode objects, or to get those ACLs, pass -find with one or more object types ("file", "dir", "mount", "symlink", "acl"). ✨

now the output — it's tabular, okay? it's an optional heading line, followed by zero or more lines of delimiter-separated values. the default output values are:

  • the file server hostname ("host")
  • the object type ("desc")
  • the vnode FID ("fid")
  • the vnode data version ("dv")
  • the directory path ("path")

that directory path is relative to the root directory of the volume, fyi. and 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"). wanna pick different output values? pass -output with one or more column names — see the OUTPUT section below for the names, bestie. 👑

values are space delimited by default. want a different delimiter character? that's what -delim is for. and if you wanna suppress that output heading line entirely, hit -noheading. periodt. 💅

✨ OPTIONS ✨

  • -checkout — checks out the specified volume from the running file server. why do you care? because this makes sure the file server (or other processes) won't be messing with volume meta-data at the same time you're trying to read it — which would otherwise give you invalid or incorrect results. no cap, that's the whole point. 😤
  • -partition <partition name or id>+ — specifies the partition that houses each volume you wanna produce output for. use the format /vicepxx or xx, where xx is one or two lowercase letters.

you can skip this argument entirely if your current working directory happens to be the mount location for an AFS server partition. 🏠 but if your cwd 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 you want output for. unless your current working directory is the mount location for the AFS server partition that houses the volume, you must provide -partition along with this one. 🔑
  • -type <Volume types: rw, ro, bk>+ — limits the volumes to be scanned to read/write, read-only, or backup volumes. specify one or more of "rw", "ro", "bk". by default volscan scans all types of volumes. 🌈
  • -find <Objects to find: file, dir, mount, symlink, acl>+ — outputs the specified volume objects within the scanned volumes. specify one or more of "file", "dir", "mount", "symlink", "acl". by default volscan finds "file", "dir", "mount", "symlink" objects. 🔍
  • -output <Column>+ — specifies the output columns produced by volscan. see the OUTPUT section below for the <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, those default output values also include the user/group id ("aid") and the access rights ("arights"). 💖

  • -delim <Output field delimiter> — specifies the record delimiter character. the default value is the space (' ') character. 🌸
  • -noheading — prevents volscan from printing the heading line. simple as that. 🙈
  • -ignore-magic — displays vnodes even when they have incorrect vnode magic numbers. ⚠️ by default, volscan will not process vnode objects with incorrect vnode magic numbers. so this flag is you saying "yeah yeah I know, show me anyway."
  • -help — prints the online help for this command. and just so you know: all other valid options are ignored when you use this one. 💅

👑 OUTPUT 👑

these are the valid column names for the -output argument, bestie:

  • "host" — the hostname of the current machine. this field may be useful when you're combining 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. this 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. check out 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. (iykyk 🫣)
  • "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 🔥

bestie, we're doing SHOW AND TELL. 💖

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

2. this command displays the AFS mount points in all the read-write volumes on the file server. for each mount point you get: the volume containing the mount point, the type of mount point — regular ("#") or read-write ("%") — the target cell (or "-" if it's not a cellular mount point), the name of the target volume, and the path of the mount point within the volume (relative to the volume root directory). obsessed. 😍

# 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

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

4. and these 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 🔐

whoever runs this must be logged in as the local superuser root. that's the whole vibe check right there. 👑

🌈 SEE ALSO 🌈

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

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.

okay that's the whole page bestie, you're welcome 🫶 and just so you have the receipts: this is OpenAFS, dated 2026-07-27, and the page is VOLSCAN(8). go forth and scan some volumes, you absolute icon 💅✨🎀

📦 where this page comes from