DIRVISH(8)

💖 DIRVISH(8) 💖

okay bestie, sit down, hydrate, because we're talking about dirvish — the Disk based virtual image network backup system, and she's from the System Manager's Manual section 8, so you already know she's a whole server-side queen 👑

---

✨ NAME ✨

dirvish — Disk based virtual image network backup system 🦋

---

✨ SYNOPSIS ✨

dirvish --vault vault [ OPTIONS ]

that's it. that's the whole vibe. --vault is required, everything else is seasoning 💅

---

✨ DESCRIPTION ✨

okay so the whole thing: you're creating a backup image of a client directory tree. that's the job. that's the assignment. 🎀

Every single image is a directory, and inside it lives a transfer log, a summary, a tree, and — if the transfer gods said no and errors got detected — an rsync_error file. Let's break those down because they matter:

• the transfer log keeps the output of any pre and post processing commands, PLUS the rsync log listing every file that was changed or added, with some statistical info sprinkled on top 📊
• the summary file has all the tea about how the image was created, plus meta-data for managing the image, and it's all in config file format
• tree is literally just the copy of the client tree 🌳

Here's the iconic part: the client directory tree gets compared against an existing image to build the new one. Unchanged files are shared between images (no cap, they're roommates). For changed files, only the parts that actually changed get transferred over the network — everything else gets copied from the reference image. Efficiency? She ate. 🔥

And the resulting images? Complete copies of the original trees, preserving ownership and file permissions. So even though the backups are made incrementally, every single image can be used independently for restores, or to make removable-media off-site copies, or archives. Every image is its own main character 💜

also, removing an image will have no effect on other images. she minds her business. periodt.

---

✨ OPTIONS ✨

okay bestie, ground rules first, and these are important so don't skip:

• Each option on the command line may be specified any number of times. Those options that support lists in the config files will accumulate all of their arguments — otherwise, each specification will override the ones before. 💀
• As configuration files are loaded they may override options on the command line. yes fr fr, the config files got seniority.
• Each option may be unambiguously abbreviated. you can be lazy, it's fine 🫶

now the menu:

• --branch [vault:]branch_name — Specify a branch to use.

A branch is a sequence of images. 📚

If a vault has been specified — either here or with --vault — the first time this option is used it will attempt to load the config file branch_name or branch_name.conf from the vault.

• --config config-file — Load options from the specified file.

If this precedes --vault, the --vault option will not load its own config file. 👀

If vault has been set and config-file is a bare filename, the presence of one in the vault will take precedence over one in the current directory. To specify one in the current directory after --vault, use ./ to precede the name.

The master configuration file will be read prior to processing options.

• --expire expire_date — Specify a time for the image to expire.

See Time::ParseDate(3pm) for details.

⚠️ this does not actually expire anything. What it does do is add an Expire: field to the image summary file containing an absolute time, so that a dirvish-expire or another tool outside of dirvish can decide when to remove old images. it's giving "leaving it on read for the expire tool" 💅

• --image image_name — Specify a name for the image.

image_name is passed through POSIX::strftime.

See strftime(3) for details.

• --image-time parsedate_expression — Time to use when creating the image name. ⏰

If an absolute time without a date is provided, it will be forced into the past. If this isn't set, the current time will be used.

See Time::ParseDate(3pm) for details.

• --init — Create an initial image.

Create the image entirely from the source tree without the use of a reference image. no ex, no situationship, just vibes and source 🌱

• --no-run
• --dry-run — Don't actually do anything.

Process all configuration files, options and tests, then produce a summary/configuration file on standard output and exit. it's a dress rehearsal 🎭

• --reference branch_name|image_name — Specify an existing image or a branch from which to create the new image.

If a branch_name is specified, the last existing image from its history file will be used. A branch will take precedence over an image of the same name. 👑

• --reset option — Reset the values in an accumulating option. 🧹
• --summary short|long — Specify summary format.

A short summary will only include final used values. A long summary will include all configuration values.

Default value: short

• --vault vault[:branch_name] — Specify the vault to store the image in.

If not preceded by --config, this will attempt to load the config file default or default.conf within the vault.

If branch_name is specified here, this will behave exactly like the --branch option, and branch_name or branch_name.conf will be attempted instead of default.conf.

• --version — Print version string and exit. 🎉

---

✨ EXIT CODES ✨

so dirvish is a thoughtful queen and provides rationalised exit codes to make automation and integration with other tools easier. The exit codes are range based — and this is the important bit:

⚠️ the code for a specific error may change from one version to another, but it will remain within the specified range. So don't test for specific exit codes — test for a range of values instead. To the degree possible, higher value ranges indicate more severe errors. 📈

here's the whole spectrum:

• 0 — success 🥳
• 1-19 — The backup job reported warnings.
• 20-39 — An error occurred during index generation and cleanup.
• 40-49 — A post-client or post-server command could not be run.
• 50-59 — The post-client command reported an error. Its exit code modulo 10 is added to 50
• 60-69 — The post-server command reported an error. Its exit code modulo 10 is added to 60
• 70-79 — A post-client or post-server command could not be run.
• 80-89 — The pre-server command reported an error. Its exit code modulo 10 is added to 80
• 90-99 — The pre-server command reported an error. Its exit code modulo 10 is added to 90
• 100-149 — Rsync encountered a non-fatal error.
• 150-199 — Rsync encountered a fatal error. 💀
• 200-219 — An error was encountered in loading a configuration file.
• 220-254 — An error was detected in the configuration.
• 255 — Incorrect usage.

---

✨ FILES ✨

the sacred texts, the locations, the map to the treasure 🗺️

• /etc/dirvish/master.conf — alternate master configuration file.
• /etc/dirvish.conf — master configuration file.
• /etc/dirvish/client[.conf] — client configuration file.
• bank/vault/dirvish/default[.conf] — default vault configuration file.
• bank/vault/dirvish/branch[.conf] — branch configuration file.
• bank/vault/dirvish/branch.hist — branch history file.
• bank/vault/image/summary — image creation summary.
• bank/vault/image/log — image creation log.
• bank/vault/image/tree — actual image of source directory tree.
• bank/vault/image/rsync_error — Error output from rsync if errors or warnings were detected.

---

✨ SEE ALSO ✨

go read these too, they're all part of the friend group 🫶

• dirvish.conf(5)
• dirvish-runall(8)
• dirvish-expire(8)
• dirvish-locate(8)
• ssh(1)
• rsync(1)
• Time::ParseDate(3pm)
• strftime(3)

---

✨ AUTHOR ✨

Dirvish was created by J.W. Schultz of Pegasystems Technologies. legend behaviour, honestly 👑✨

---

✨ BUGS AND ISSUES ✨

okay bestie, here's where we get real, because I love you and I want you to not get confused:

• Fields set in configuration files will override command line options that have been set before the file is read. This behaviour, while consistent, may occasionally confuse. 😵‍💫 For this reason, most command line options should be specified after any options that may cause a configuration file to be loaded. order matters, babe.
• In order to preserve permissions, it is necessary for dirvish to run as root on the backup server. no getting around it. 💅
• The root user must have non-interactive ssh access to the client systems. It is not necessary that this access be as the root user on the client.
• File ownership is preserved using numeric values, so it is not necessary to have user accounts on the backup server. Making the vaults network accessible using protocols that map UIDs based on names instead of number could allow access controls on files to be violated. 🚨
• Making the vaults writable by users will compromise the integrity of the backups. Therefore, any access to the vaults by users should be done through a read-only mount. 🔒

---

and that's the whole page, babe 💜 this is DIRVISH(8) from the System Manager's Manual — go forth and back things up responsibly, protect your vaults, test for ranges not specific codes, and remember: incremental backups but independent images. she's everything, honestly. mwah 🎀✨🦋

DIRVISH(8) 💖