.Dd January 4, 2016
.Dt UPGRADE.CONF 5
.Os
.Sh NAME
.Nm upgrade.conf
.Nd upgrade configuration
.Sh SYNOPSIS
.Nm /etc/upgrade.conf
.Sh DESCRIPTION
.Nm upgrade.conf
controls the actions taken by
.Xr sysupgrade 8
during a system upgrade as described in
.Xr upgrade 7 .
The file allows customizing whether the system itself is replaced, whether new
ports are installed, whether the new source code is installed and what happens
to the old source code.
It also records information about the system such as how the system is booted.
The file is created automatically by
.Xr sysinstall 8
as part of
.Xr installation 7
to match what was installed.
.Pp
The file also controls the actions of
.Xr tix 8
when upgrading releases and installing ports.
.Pp
Developers may wish to customize what happens to
.Pa /src
on a system upgrade.
The new source code can be installed or not.
If it is installed, it can be installed in
.Pa /newsrc
or by default in
.Pa /src .
Any existing source code will be safely moved inside a subdirectory of
.Pa /oldsrc .
.Pp
It is possible to disable any upgrading whatsoever.
If you do this, except the new source code is installed, then you can upgrade to
the new system manually as described in
.Xr development 7 .
Upgrading to the next release from source is not supported.
.Sh FORMAT
The file is read line by line.
The # character starts a comment and the rest of the line is ignored.
Lines are supposed to contain assignments to variables.
An assignment is the name of the variable, whitespace, an equal character,
whitespace, the value, whitespace, and then the end of the line.
.Bl -tag -width "12345678"
.It Sy channel Ns "=" Ns Ar channel
If the current release has an upgrade path named
.Ar channel
to a new release,
then system upgrades will upgrade to that new release.
If no such release path exists or if this variable is not set, upgrades will
continue to upgrade to the current release series.
Depending on the current release, the offically supported values are
.Sy stable
for stable releases and
.Sy nightly
for development releases.
Downgrading releases is not supported. For instance, if the current system is
a development release, specifying
.Sy stable
will not downgrade the system to the previous stable release, as no such upgrade
path exists.
Instead upgrades will upgrade to the next stable release when it becomes
available.
.It Sy force_mirror Ns "=" Ns Oo Sy no "|" yes Oc (default Sy no )
Use the preferred mirror set with
.Sy mirror
even if the file specified by
.Sy release_sig_url
does not list it.
.It Sy grub Ns "=" Ns Oo Sy no "|" yes Oc (default Sy no )
States GRUB is used as the bootloader.
If either the
.Sy system
or
.Sy ports
are set to
.Sy yes ,
then the bootloader is reinstalled
.Xr ( grub-install 8 )
and updated
.Xr ( update-grub 8 ) .
.It Sy mirror Ns "=" Ns Ar mirror
Download releases and ports from this preferred
.Ar mirror ,
a URL to the top level directory of a mirror.
The mirror is only used if the file specified by
.Sy release_sig_url
lists this mirror, unless
.Sy force_mirror
is set to
.Sy yes .
If no mirror is set, a default mirror is used.
.It Sy newsrc Ns "=" Ns Oo Sy no "|" yes Oc (default Sy no )
Place the new source code in
.Pa /newsrc
and move any existing
.Pa /newsrc
into
.Pa /oldsrc .
This preserves the current
.Pa /src
directory.
This takes precedence over and disables the behavior described under
.Sy src .
.It Sy ports Ns "=" Ns Oo Sy no "|" yes Oc (default Sy yes )
Install the new ports.
Ports that don't exist anymore will be removed.
.It Sy release_key Ns "=" Ns Ar release_key
Verify the file specified by
.Sy release_sig_url
with the
.Xr signify 1
public key file at the path
.Ar release_key .
This variable is updated during system upgrades and there is no need to change
this variable manually.
.It Sy release_sig_url Ns "=" Ns Ar release_sig_url
Download the meta-information about the current release from the URL
.Ar release_sig_url .
This file is verified with the
.Xr signify 1
public key in the
.Sy release_key
variable.
The file describes the current release, provides checksums of all the published
files, lists all the supported mirrors, provides instructions on how to upgrade
to this release, and lists all the supported upgrade paths to new releases.
This variable is updated during system upgrades and there is no need to change
this variable manually.
.It Sy src Ns "=" Ns Oo Sy no "|" yes Oc (default Sy no )
Place the new source code in
.Pa /src
and move any existing
.Pa /src
into
.Pa /oldsrc .
.It Sy system Ns "=" Ns Oo Sy no "|" yes Oc (default Sy yes )
Install the new system.
The upgrade hooks are run if needed as described in
.Xr following-development 7 .
This will run
.Xr update-initrd 8
and if
.Sy grub
is set to
.Sy no ,
then regenerate
.Pa /etc/grub.d/10_sortix.cache .
.El
.Pp
The defaults will be used if
.Pa /etc/upgrade.conf
is missing.
If
.Sy release_key
or
.Sy release_sig_url
are absent,
.Xr tix 8
will not be able to upgrade the current system nor install ports.
If
.Sy channel
is absent,
.Xr tix 8
will not upgrade to new releases.
.Sh FILES
.Bl -tag -width "/etc/upgrade.conf" -compact
.It Pa /etc/upgrade.conf
Upgrade configuration.
.El
.Sh EXAMPLES
.Bd -literal
grub = yes
ports = yes
src = no
system = yes
.Ed
.Sh SEE ALSO
.Xr upgrade 7 ,
.Xr sysupgrade 8 ,
.Xr tix 8