SYSUPGRADE(8) BSD System Manager's Manual SYSUPGRADE(8)NAMEsysupgrade — 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] etcupdate
sysupgrade [common_flags] fetch [releasedir]
sysupgrade [common_flags] kernel [kernel_name]
sysupgrade [common_flags] modules
sysupgrade [common_flags] sets [set1 .. setN]
sysupgrade [common_flags] postinstall [arg1 .. argN]
DESCRIPTIONsysupgrade is a utility that automates the process of upgrading a possi‐
bly-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 speci‐
fies 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, speci‐
fies 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 uncondi‐
tional fixes to the upgraded system.
7. ‘clean’: Remove contents of the cache directory. This can be dis‐
abled 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 con‐
figuration 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 sym‐
links within the cache directory pointing to the original files. Other‐
wise, 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-configura‐
tion 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 configura‐
tion 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 manu‐
ally 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’ com‐
mand 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 ALSOsysbuild(1), sysupgrade.conf(5), etcupdate(8), postinstall(8)AUTHORS
The sysupgrade utility was developed by Julio Merino ⟨jmmv@google.com⟩.
BSD October 10, 2012 BSD
