Usage

This is a summary of the various freebsd-rustdate commands and their options. This includes a lot of discussion about how using them will differ from using freebsd-update .

There’s a fair amount of online --help available too, on the various commands.

Help

freebsd-rustdate can tell you a lot about itself, just ask. Running freebsd-rustdate help will show a summary of the overall args, and the individual commands. freebsd-rustdate help <cmd> will tell you more about the command and its arguments.

That’s often going to be more thorough than the quick notes we have here, and will be more certainly in sync with the version you’re running.

Shared Storage

freebsd-rustdate uses similar local storage to freebsd-update , so a lot of that is shared. Particularly, the files/ dir, which both use to cache the downloaded data and stashed up info from the current system. So either of them will be able to use files the other downloaded, and not download them again. Assuming both are using the same WorkDir of course.

However, the metadata for updates is not shared. That means that you can’t do a fetch with one and then install with the other, or vice versa. Neither will know anything about any pending stuff the other has queued up.

Overall Differences

In general, there’re a few overall differences in structure and behavior.

• A big one: freebsd-rustdate has first-class support for running as non-root. Naturally, it’s probably not so useful if your BaseDir is /. But it means a user can own a subtree (maybe run as a chroot or jail), and use freebsd-rustdate themselves on it.

  It also makes life way easier when developing. Things like boot enviroments and schg flags that won’t work when you’re non-root. And you better own all the important files. But within those sorta contraints, it works great.

• More effort is made to show progress of long-running operations in context, so you’ll see more progress bars etc.

• Interactive use is avoided outside of commands specially built for it. This is most apparent in upgrade and somewhat in fetch; see below. In general, detailed status information is left for targetted commands, not show in the middle of other actions.

• Arguments to freebsd-rustdate as a whole are separate from arguments to individual commands. freebsd-update doesn’t do this, probably mostly because implementing that on a shell script would be a PITA.

  In day-to-day use, you’ll notice this mostly with upgrade below. The helpfile also shows them, in help vs help <cmd>.

• Explicit parallelism is used in several places. And maybe could be more in the future. But, this means you can make use of more cores when there’s work for them to do.

Global Arguments

freebsd-rustdate takes some global args; see help for details. A few quick tidbits:

• --config, --basedir, --workdir, --server, etc, are pretty much like you’d expect, and do the same sorta thing as their counterparts in freebsd-update . They override the values in the config file as necessary.

• --jobs-cpu and --jobs-net control parallelism.

  In this context, “CPU” also mostly covers “disk IO”, because they’re often intertwined. e.g., when scanning the current system, there’s disk IO in the form of stat()’s and walking directory trees, but also CPU work in the form of hashing the files.

  Network mostly means doing the HTTP fetches. freebsd-update uses HTTP/1 pipelining on a single connection, which basically nobody else in the world supports. freebsd-rustdate uses multiple parallel fetchers. The default is probably reasonable. Maybe if you have a personal mirror that’s a huge bandwidth/delay product away, it’s worth cranking that number, but generally, I’d leave it be…

Commands

Upgrading Actions

First, the major do-my-upgrades actions you use in freebsd-rustdate . which are basically the same as those in freebsd-update .

fetch

fetch will grab updates to take you up to newer patchlevels, the same in freebsd-rustdate as in freebsd-update .

This is largely going to act the same as freebsd-update . In fact, I can’t think of much to say, other than,

• It’ll probably be a lot faster,
• There are more progress bars, and
• The summary of the files to touch isn’t shown here, but in show-install

cron

cron will sleep a random amount to offset within an hour, attempt a fetch, and send an email to the owner of the MailTo email address if there are updates to install. This should be pretty much the same as freebsd-update ’s cron command.

See also the check-fetch command; that can serve much the same purpose, but is quicker and lighter-weight, both on your system and on the server.

upgrade

upgrade will set you up for upgrading from one release to another, the same as the similar command in freebsd-update . One difference is that the -r argument for specifying the release is an argument to the upgrade command itself, not a global argument to freebsd-rustdate . It doesn’t mean anything to any other command, so we don’t need to even have it available to them.

The other major difference is that freebsd-update ’s upgrade has a lot of interactive elements. One is the file listings (like in fetch), which are now reviewable in show-install. Another is merging changed files. The separate show-merges command will show the results of the merges, and resolving any conflicts is left to resolve-merges.

install

install will go ahead and… well, install, whatever pending fetch or upgrade you have waiting. Note that it won’t proceed if you’re doing an upgrade and haven’t resolved any merge conflicts.

If you have the proper freebsd-update and system layout config, freebsd-rustdate will setup ZFS boot environments on each invocation, like freebsd-update .

Like freebsd-update , this will just do all the things on a fetch, but will multi-step an upgrade. upgrade will first install a new kernel, and expect you to reboot before coming back and running upgrade a second time to install the world. Then expect you to rebuild or reinstall any necessary packages, and run upgrade a third time to remove obsolete shared libraries.

If you’re upgrading your working system, that’s what you want. But if you’re updating a jail or subdirectory, you may want to just go ahead and do it all at once. For that, there’s the --all (-a) argument, to just go ahead and do all the steps in one go.

install accepts a --dry-run (-n) argument to not do any of the steps, but just give a summary of what will happen. This imply the behavior of the --all flag, telling you about all the steps that would be taken, not just the next one.

As a further possible optimization, upgrade has a --no-sync (-s) argument to not do a fsync() on the files as they’re installed. This can provide a pretty significant speedup to the process (especially if you have things like the src/ tree installed, which adds up to a ton of tiny files). Of course, it’s also potentially dangerous; if you get a crash partway through the upgrade, you might end up with empty files that you really wish were present (libc.so, say).

If you’re upgrading a jail or subdir, that’s probably perfectly fine. If it blows up partway, you can just try again. On the system you’re trying to boot, it’s rather more dangerous. On the other hand, even with syncing, a crash in the middle could leave you with half-upgraded stuff that won’t work well, so it’s not “completely safe” vs “totally dangerous” either. Boot environments probably give you more safety. Choosing to take off your seatbelt is your business :)

As of 0.7.0, install also accepts as -j argument to enable multi-threaded parallel install. Without -s this usually gives a speedup similar to what -s would give, since it can hide the fsync() delays. With both combined, there’s further gains since you’re using multiple cores and not waiting on hardware. It’s potentially dangerous if problems are encountered, since it won’t stop right away like non-parallel install would.

Depending on how you look at it, using -j alone could be thought of as less safe than -s (since you’d install the rest of the files anyway if one failed), or more safe (since each file is still getting fsync()’d, so you don’t have the worry about empty files).

New Actions

There’s also a couple new actions, one split out from a separate command, and one completely new.

resolve-merges

Where freebsd-update has all this merge conflict resolution done interactively as part of the upgrade command, freebsd-rustdate has split it out to a separate command. If upgrade winds up with conflicts, it’ll tell you to run this command. show-install and show-merges will also tell you if there are any, and install won’t proceed until you fix them.

Like freebsd-update , a 3-way merge is attempted, then this command will drop your in your $EDITOR to fix the conflicts. Various commands along the way will let you accept, redo, or skip out to come back later.

In principle, enough information is stored that alternate resolution strategies could be added.

extract

This allows you use to freebsd-rustdate to extract pristine upstream versions of various files into place. This would be useful if you ran check-sys and it shows up differences you don’t want to exist. Or, say, you accidentally run rm /bin/ls; you can use this to re-download and re-extract that file.

n.b.: This is a very powerful and dangerous command, and it very much Does What You Say, with very few guardrails. Be extremely careful, and make liberal use of --dry-run!

In principle, you could even use this to install components you don’t have. e.g., you could freebsd-rustdate extract -x '^/usr/lib32' to install the 32-bit compat libs wholesale. This is probably not something you often want to do though, and is also probably a very inefficient way of doing things. But it’s an escape hatch if you don’t have a better way of doing something.

Pay attention to the help for this command. It’s very powerful, and also very dangerous. Worth noting:

• It does not by default try to filter down to the components you have installed; see the -c option. That’s because if you’re using this, you’re probably trying to do something tricky and manual, so it trusts you.

• By default it does compare against existing matching files, so should only do things that actually differ. Using -f will override that and make it touch everything that matches the given paths (or regexes), which can very quickly become very wide-reaching.

• Use --dry-run (-n) a lot to be sure this will do what you want before actually doing it.

• Did you use --dry-run? Use --dry-run!

Information

And some commands for showing information about pending installs.

show-install

This shows information about what a pending install includes. That’s things like what version it will be, what files/dirs/etc it will be adding, updating, or deleting, etc. See the -v argument to show full lists of a given type.

show-merges

This shows summary information and potentially details about and merges files in your pending upgrade. By default it shows the diffs vs. your current version, but can also show the diff between the new upstream version and your merged result.

check-sys

This shows difference on your running system vs. the clean upstream state. If you’re not up to date with the latest patch version, it can’t tell the difference between “my files are oudated” and “my files have been changed”, so you presumably want to be up to date. It also doesn’t know anything about merged files, etc. So it shouldn’t be treated as “any output means a problem” and more of a “does this output look like what I expect”.

This fills a similar role to freebsd-update ’s IDS command. It’s useful to give you ideas for what you might want to run extract on.

check-fetch

This does a quick check of the patchlevel the server has available, and compares it to your system. This can give you a quick check of whether the server has something new. It doesn’t do checks as thorough as fetch, but that also means it puts far less load on your system and on the freebsd-update servers.

With the -q arg, it doesn’t output anything unless it thinks you’re out of date. That’s useful when combined with the --cron argument to add a random delay to spread out load. Adding a cron job with --cron -q should cause it to quietly sit there until it sees an update, then it’ll output about it, and cron will send you that output.

complete

Generates shell completions for several common shells. This uses the clap_complete crate, so supports the shells it does (bash, zsh, and maybe fish probably being most likely to be in used in places freebsd-rustdate might be run). Specify the appropriate shell, and it’ll dump to stdout; putting that output in a place where it’s useful to your shell is left as an exercise for the reader.

Help

There’s a help command. Did you check the help command? Did you check help <command>?