SYSUPGRADE(8)

NAME
sysupgrade - upgrades a NetBSD system to a newer version

SYNOPSIS
common_flags ::= [-c config_name] [-d destdir] [-o variable=value]

Major commands:

sysupgrade [common_flags] auto [releasedir]
sysupgrade [common_flags] config [-a]

Standalone upgrade steps:

sysupgrade [common_flags] clean
sysupgrade [common_flags] fetch [releasedir]
sysupgrade [common_flags] etcupdate
sysupgrade [common_flags] kernel [kernel_name] (reboot for major version upgrade)
sysupgrade [common_flags] modules
sysupgrade [common_flags] sets [set1 .. setN]
sysupgrade [common_flags] postinstall [arg1 .. argN]

DESCRIPTION
sysupgrade is a utility that automates the process of upgrading a possibly-running NetBSD system to a newer release.

sysupgrade works by first fetching the release sets from a remote site or from a local directory, then by upgrading the system using such release sets and finally by taking care of bringing the system configuration up to date. In other words, sysupgrade does nothing special on its own: it is just a utility that automates a highly manual process and relies on other tools within the system to perform its job.

sysupgrade has a subcommand-based interface: every command performs a single step of the upgrade procedure, and the ‘auto’ command orchestrates a complete upgrade by invoking the rest of the commands in a specific order. There are a set of options that apply to all commands (those stated before the command name), and every particular command may accept its own options and arguments as shown in the synopsis.

The behavior of sysupgrade is defined by a configuration file that specifies how to apply an update to the system (see sysupgrade.conf(5)). For example, the configuration states which distribution sets ought to be installed, where they need to be downloaded from, and whether the system configuration files should be upgraded.

The following options apply to all commands:

-c config_file
    Specifies the configuration file to use.

    Default: /usr/pkg/etc/sysupgrade.conf

-d destdir
    Path to the NetBSD system to upgrade.

    This optional flag can be used to upgrade a non-live system or for testing/development purposes. Note that some steps (particularly ‘etcupdate’) do not support this feature and thus will never be run if set.

    Default: not set (which means / is affected).

-o variable=value
    Applies an override to the loaded configuration.

    The variable part of the argument must be any of the recognized configuration variables described in sysupgrade.conf(5). The value, if not empty, specifies the value to set the configuration variable to. If value is empty, then the configuration variable is unset.

  The auto command
The auto command is the most important command in sysupgrade, and is probably the one you will find yourself using most frequently. This is the command that takes care of upgrading a full NetBSD installation, and it does so by invoking the other commands in the tool in the specific order in which they are needed.

The optional argument releasedir points to the release directory or URL to use, overriding the value of RELEASEDIR in the configuration file (if any). If you are tracking daily builds from an FTP site, for example, you will probably want to avoid setting RELEASEDIR in the configuration file and instead pass an URL each time you run this command.

The standard upgrade procedure performed by this command is as follows:

1.  ‘fetch’: Retrieve distribution sets into the local cache directory.

2.  ‘modules’: Unpack new kernel modules.

3.  ‘kernel’: Upgrade kernel.

4.  ‘sets’: Upgrade system sets, except configuration files.

5.  ‘etcupdate’: Merge new changes to configuration files. This is the only interactive step in the process and can be disabled for this reason by setting ETCUPDATE to false.

6.  ‘postinstall’: Perform sanity checks and optionally apply unconditional fixes to the upgraded system.

7.  ‘clean’: Remove contents of the cache directory. This can be disabled by setting AUTOCLEAN to false in case you want to keep the downloaded distribution files around.

  The clean command
The clean command removes any distribution sets from the local cache directory.

  The config command
The config command dumps the loaded configuration to the standard output. The format of the output is not a script, so it cannot be fed back into sysupgrade. The purpose of this command is to aid in debugging the configuration of the tool before performing any builds, particularly when the configuration files use shell logic to determine the value of any variables.

The following options are accepted:

-a  Process automatic variables such as KERNEL and SETS and display their deduced values instead of only showing the literal ‘AUTO’.

  The etcupdate command
The etcupdate command invokes etcupdate(8) to perform an interactive upgrade of the system configuration files in /etc. This is the only interactive process in a full system upgrade.

In order for this command to do anything useful, the list of sets to install as specified by the SETS configuration variable must include ‘etc’, and may optionally include ‘xetc’.

Note that, due to defficiencies in the etcupdate(8) utility, this command does not work when DESTDIR is set.

  The fetch command
The fetch command gets a copy of the release sets as pointed to by the RELEASEDIR variable into a local cache directory, or from the directory indicated by the optional argument releasedir.

If RELEASEDIR points to a local directory, the utility just creates symlinks within the cache directory pointing to the original files. Otherwise, if RELEASEDIR points to a remote FTP, HTTP or SSH site, the fetch command will retrieve the contents of the release directory into the local cache directory.

Please note that all the commands that access distribution sets do so by looking for such files in the cache directory even when the release directory is in a local path. This means that, for such commands to work, you must run fetch beforehand.

  The kernel command
The kernel command upgrades the kernel to a newer version. The kernel to install is determined by the optional argument kernel_name if present, or otherwise from the KERNEL variable. The kernel is expected to be found in a ‘netbsd-<NAME>.gz’ file in the release directory.

The previous kernel is backed up as <destdir>/onetbsd.

  The modules command
The modules command upgrades the kernel modules to a newer version. This operation only takes place if the sets to be installed, as specified by the SETS variable, contains the ‘modules’ set.

  The sets command
The sets command upgrades all non-kernel, non-modules and non-configuration sets of the system to a newer version. In other words, this command installs sets like ‘base’ or ‘tests’ but explicitly skips sets of the forms ‘*etc’ and ‘modules’. The presence of any ‘kern-*’ sets in the list will cause this command to fail.

The list of sets to be installed is determined by the optional arguments passed to the command or, if none, from the value of the SETS configuration variable.

  The postinstall command
The postinstall command invokes the postinstall(8) utility to perform checks and fixes on the system after all new files have been put in place.

The POSTINSTALL_AUTOFIX variable can optionally include a list of postinstall(8) fixes to be applied to a system unconditionally. For example, listing ‘obsolete’ in this variable is usually useful as this check fails often during upgrades and is safe to auto-fix.

Any arguments supplied to the command are passed directly to postinstall(8), which comes handy in those cases where you have to manually fix a broken test.

FILES

/usr/pkg/etc/sysupgrade.conf
    Default configuration file.

/var/cache/sysupgrade
    Location where distribution sets are temporarily stored. The ‘fetch’ command writes files into this directory and the ‘clean’ command clears its contents.

/home/sysbuild/release/<machine>
    Standard location of the releases built by the sysbuild(1) utility.

EXAMPLES AND TROUBLESHOOTING
The most common way of executing sysupgrade is by using the ‘auto’ command and relying in the default configuration file:

    $ sysupgrade auto

If you wish to track minor stable releases, you may want to do something like this every time a new release is published:

    $ sysupgrade auto \
        ftp://ftp.NetBSD.org/pub/NetBSD/NetBSD-6.<minor>/$(uname -m)

If the upgrade process fails due to an aborted FTP or HTTP connection, simply rerun sysupgrade in ‘auto’ mode and it will resume the download where it left off.

If the ‘postinstall’ step fails due to broken checks, you can manually resume that stage and complete the upgrade by doing:

    $ sysupgrade postinstall fix <names of the failed checks>
    $ sysupgrade clean

If you have decided to run etcupdate(8) by hand separately from sysupgrade, you could do:

    $ sysupgrade -o AUTOCLEAN=no -o ETCUPDATE=no auto
    ... and later, at your earliest convenience ...
    $ sysupgrade etcupdate
    $ sysupgrade clean

SEE ALSO
sysbuild(1), sysupgrade.conf(5), etcupdate(8), postinstall(8) https://www.netbsd.org/docs/guide/en/chap-updating.html#updating-sysbuild-sysupgrade

AUTHORS
The sysupgrade utility was developed by Julio Merino <jmmv@google.com>.