BOS_SALVAGE(8)

📦
version 1.8.16.1 · 10 versions
, in ubuntu stonking

💖 BOS_SALVAGE ✨

okay bestie, gather round, because this one is bos_salvage from the AFS Command Reference, section 8, and it is literally the glow-up-your-filesystem command 🫶

It restores internal consistency to a file system or volume. That's the whole vibe. Corruption? Not on our watch. 💅

🌸 SYNOPSIS 🌸

like, here's the whole fit, both the long version and the short girlies:

bos salvage -server <machine name>
    [-partition <salvage partition>]
    [-volume <salvage volume number or volume name>]
    [-file <salvage log output file>] [-all] [-showlog]
    [-parallel <# of max parallel partition salvaging>]
    [-tmpdir <directory to place tmp files>]
    [-orphans (ignore | remove | attach)] [-cell <cell name>]
    [-forceDAFS]
    [-noauth] [-localauth] [-help]

and the abbreviated icon edition:

bos sa -se <machine name> [-part <salvage partition>]
    [-v <salvage volume number or volume name>]
    [-f <salvage log output file>] [-a] [-sh]
    [<-para> <# of max parallel partition salvaging>]
    [-t <directory to place tmp files>]
    [-o (ignore | remove | attach)] [-c <cell name>] [-n]
    [-force]
    [-l] [-h]

🦋 DESCRIPTION 🦋

So the bos salvage command salvages — aka restores internal consistency to — one or more volumes on the file server machine you named with the -server argument. When it's working through one or more partitions, it restores consistency to corrupted read/write volumes where it can. But for read-only or backup volumes, bestie, it only peeks at the volume header. That's it. Head only. 👑

Here's the tea on what happens in those two cases:

  • If the volume header is corrupted, the Salvager removes the volume completely and records that removal in its log file, /var/log/openafs/SalvageLog. To bring the read-only or backup volume back into existence, you issue the vos release or vos backup command. Boom, reborn. ✨
  • If the volume header is intact, the Salvager skips that volume entirely — like, it does not check for corruption in the contents. However (plot twist), if the File Server notices corruption while it initializes, it sometimes refuses to attach the volume or bring it online. When that happens, the simplest move is to remove the volume with the vos remove or vos zap command, then issue the vos release or vos backup command to create it again. Fresh start, no cap.

Now, how much are we salvaging? Use the arguments to pick your scope:

  • To process ALL volumes on a file server machine: give it the -server argument plus the -all flag. Heads up though — no volumes on the machine are accessible to Cache Managers during the salvage operation, because the BOS Server stops the File Server and Volume Server processes while the Salvager runs. The BOS Server automatically restarts them when the operation completes, so, slay, it handles itself. 💅
  • To process all volumes on ONE partition: give it the -server and -partition arguments. Same deal as a whole-machine salvage — no volumes on the machine are accessible to Cache Managers during the operation. The BOS Server automatically restarts the File Server and Volume Server when the operation completes.
  • To salvage only ONE read/write volume: combine -server, -partition, and -volume. Only that one volume is inaccessible to Cache Managers, because the BOS Server does not shut down the File Server and Volume Server processes during a single-volume salvage. Small and surgical, we love that. 🎀 One thing though — do not name a read-only or backup volume with the -volume argument. Instead, remove the volume using vos remove or vos zap, then create a new copy of it with vos release or vos backup.

During a salvage of an entire machine or partition, the bos status command reports the "fs" process's auxiliary status as "Salvaging file system". Cute little status update, we're obsessed. 🙈

📝 Logging, bestie

The Salvager always writes a trace to the /var/log/openafs/SalvageLog file on the file server machine where it runs. If you want that trace recorded somewhere else too — either in AFS or on the local disk of the machine where the bos salvage command is issued — name that file with the -file argument.

And if you want to watch the trace scroll by on the standard output stream as it's written to /var/log/openafs/SalvageLog, include the -showlog flag. It's giving live commentary. 📺✨

🧚 Parallelism, the dramatic part

By default, multiple Salvager subprocesses run in parallel, like a little squad: one for each partition up to four, and four subprocesses for four or more partitions. To increase or decrease how many subprocesses run in parallel, hand the -parallel argument a positive integer value.

Now here's the messy part. If there's more than one server partition on a physical disk, the Salvager by default salvages them serially — because constantly yeeting the disk head from one partition to another is inefficient, and we don't do inefficiency here. But this strategy is often not ideal if the partitions are configured as logical volumes that span multiple disks. In that case, to force the Salvager to salvage logical volumes in parallel, give the string "all" as the value for the -parallel argument. You can also give a positive integer to say how many subprocesses run in parallel — for example, -parallel 5all gives you five subprocesses — or you can omit the integer entirely to run up to four subprocesses, depending on how many logical volumes are being salvaged. 🌈

🍓 Temporary files (aka the space situation)

The Salvager creates temporary files as it runs, and by default it writes them to the partition it's salvaging. And listen — the number of files can be quite large. If the partition is too full to accommodate them, the Salvager terminates without completing the salvage operation. (It always removes the temporary files before exiting, at least. 🫠)

Meanwhile, the other Salvager subprocesses running at the same time keep going until they finish salvaging all the other partitions that have enough disk space for temporary files.

To complete that interrupted salvage, reissue the command against the appropriate partitions and add the -tmpdir argument to redirect the temporary files to a local disk directory that has enough space. Problem solved, main character energy restored. 💅

👑 Orphans

The -orphans argument controls how the Salvager handles orphaned files and directories it finds on server partitions it's salvaging.

So what's an orphaned element? It's something that's completely inaccessible because it's not referenced by the vnode of any directory that can act as its parent — like, nothing is higher in the filespace to claim it. 😭 Orphaned objects occupy space on the server partition, but they do not count against the volume's quota. Yeah. Rude of them.

⚠️ CAUTIONS ⚠️

Running this command can result in data loss if the Salvager process can repair corruption only by removing the offending data.

Not me being dramatic — that's just true. Consult the OpenAFS Administration Guide for more information before you go off, bestie. 📖

✨ OPTIONS ✨

okay bestie, here's the whole toolbelt 💅 every single flag, no skips, we're doing this properly.

  • -server <machine name> — tells it which file server machine we're salvaging volumes on. you can ID the machine by IP address or by host name (fully-qualified, or abbreviated as long as it's unambiguous). more deets in bos(8). 🖥️
  • -partition <salvage partition> — picks ONE partition and salvages every volume on it. give the complete partition name (like /vicepa) or one of these cute abbreviated forms:
   /vicepa     =     vicepa      =      a      =      0
   /vicepb     =     vicepb      =      b      =      1

after /vicepz (index 25, yes we're counting) comes:

   /vicepaa    =     vicepaa     =      aa     =      26
   /vicepab    =     vicepab     =      ab     =      27

and so on and so forth all the way through:

   /vicepiv    =     vicepiv     =      iv     =      255
  • -volume <salvage volume id or name> — names the read/write volume you wanna salvage, by name or by volume ID number. ⚠️ you MUST also pass -partition with this one, they're a package deal fr.
  • -file <salvage log output file> — full pathname of a file to dump a trace of the salvage into, on top of the /var/log/openafs/SalvageLog file on the server machine. if the pathname is local, the trace lands on the local disk of the machine where you ran bos salvage. if you also threw in -volume, the file can live in AFS — just not in the volume you're salvaging (that would be chaos 💀). do NOT combine this with the -showlog flag.
  • -all — salvages every volume on every partition on the machine you named with -server. all of them. the whole buffet 🍓
  • -showlog — prints the trace of the salvage to standard output and writes it to /var/log/openafs/SalvageLog. do NOT combine this flag with -file.
  • -parallel <# of max parallel partition salvaging> — sets the max number of Salvager subprocesses running at once. three flavors, pick one:
    • An integer from the range 1 to 32. a value of 1 means one single Salvager process salvages the partitions one after another (sequentially, no rush bestie).
    • The string "all" to run up to four Salvager subprocesses in parallel on partitions formatted as logical volumes spanning multiple physical disks. ⚠️ only use this value with those kinds of logical volumes.
    • The string all followed immediately — like, no space in between, they're holding hands — by an integer from the range 1 to 32, to run that many Salvager subprocesses in parallel on partitions formatted as logical volumes. ⚠️ again, only with those kinds of logical volumes.

also important: the BOS Server never starts more Salvager subprocesses than there are partitions, and always starts only one process to salvage a single volume. if you omit this argument entirely, up to four Salvager subprocesses run in parallel. ✨

  • -tmpdir <directory to place tmp files> — full pathname of a local disk directory where the Salvager writes temp files while it's working. if you skip this, or point it at a directory that's ineligible or doesn't exist, the Salvager just writes those files to the partition it's currently salvaging. 🗂️
  • -orphans (ignore | remove | attach) — controls how the Salvager deals with orphaned files and directories. three choices, choose wisely:
    • ignore — leaves the orphaned objects sitting on the disk, but logs a message to /var/log/openafs/SalvageLog saying how many orphans it found and roughly how many kilobytes they're eating. 👑 this is the DEFAULT when you omit -orphans.
    • remove — deletes the orphaned objects, and logs a message to /var/log/openafs/SalvageLog reporting how many orphans got removed and about how many kilobytes they were consuming. bye bye 👋
    • attach — attaches the orphaned objects by creating a reference to them in the vnode of the volume's root directory. since each object's real name is lost forever 😭 at this point, the Salvager names each one like this:
      • "__ORPHANFILE__.index" for files.
      • "__ORPHANDIR__.index" for directories.

where index is a two-digit number that uniquely IDs each object. these orphans get charged against the volume's quota and show up in the output of the ls command you run against the volume's root directory. iconic honestly.

  • -forceDAFS — if the fileserver is a Demand Attach File Server, then you MUST pass -forceDAFS or the salvager won't run. no flag, no salvage, periodt. 🚨
  • -cell <cell name> — names the cell to run the command in. don't combine this with the -localauth flag. more details in bos(8).
  • -noauth — assigns the unprivileged identity "anonymous" to whoever issued it. don't combine this flag with -localauth. more details in bos(8).
  • -localauth — builds a server ticket using a key from the local /etc/openafs/server/KeyFile or /etc/openafs/server/KeyFileExt file. the bos command interpreter hands that ticket to the BOS Server during mutual authentication. don't combine this flag with -cell or -noauth. more details in bos(8).
  • -help — prints the online help for this command. every other valid option gets ignored, sorry not sorry.

🌟 EXAMPLES 🌟

this one salvages all volumes on the /vicepd partition of the machine "db3.example.com":

   % bos salvage -server db3.example.com -partition /vicepd

this one salvages the volume with volume ID number 536870988 on partition /vicepb of the machine "fs2.example.com":

   % bos salvage -server fs2.example.com -partition /vicepb -volume 536870988

and this one salvages all volumes on the machine "fs4.example.com" — with SIX Salvager processes running in parallel instead of the default four, look at her go 🔥:

   % bos salvage -server fs4.example.com -all -parallel 6

🔐 PRIVILEGE REQUIRED 🔐

the issuer has to be listed in the /etc/openafs/server/UserList file on the machine named by -server. OR, if you passed -localauth, you have to be logged onto a server machine as the local superuser "root". that's the vibe check, no cap.

👀 SEE ALSO 👀

KeyFile(5), KeyFileExt(5), SalvageLog(5), UserList(5), bos(8), salvager(8), salvageserver(8), vos_backup(1), vos_release(1), vos_remove(1), vos_zap(1)

also the OpenAFS Administration Guide, sitting pretty at http://docs.openafs.org/AdminGuide/. 📖

IBM Corporation 2000. http://www.ibm.com/ All Rights Reserved.

this documentation is covered by the IBM Public License Version 1.0. it was converted from HTML to POD by software written by Chas Williams and Russ Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. shoutout to the legends 🫶

and that's the whole page bestie!! 💖 this beauty lives under OpenAFS, dated 2026-07-27, in section BOS_SALVAGE(8) — go forth and salvage responsibly, mwah 🎀✨🦋

📦 where this page comes from