NAME

upgrade — operating system upgrade instructions

DESCRIPTION

This document describes how to upgrade an existing Sortix installation to a newer release. The installation(7) manual page covers creating a new installation.

Prerequisites

You need to prepare a bootable medium with the new release as described in installation(7). Read all the instructions up to Bootloader Menu and continue with this document. It is not possible to skip releases. If you want to upgrade to a release, you must upgrade first to all releases before that one. If the existing installation is a development snapshot, you must either upgrade to a newer development snapshot of that version, or a the final release of that version.

Release .iso Modification

Optionally, you might want to modify a release .iso to meet your custom needs per the instructions in release-iso-modification(7). The release modification procedure lets you customize aspects such as the default bootloader menu option and timeout, the default hostname, the default keyboard layout, the default graphics resolution, adding files of your choice to the live environment, and so on. Warning: The live environment does not come with any random entropy and entropy gathering is not yet implemented. To keep your system secure, it is recommended to use the release modification procedure to add a /boot/random.seed file to the release .iso in order to securely seed the cryptographically secure pseudorandom number generator.

Bootloader Menu

Pick the upgrade existing installation option in the bootloader menu to begin the upgrade. This will load a live environment set to automatically run the sysupgrade(8) program.

Upgrader

This guide assumes you selected the upgrade option in the bootloader. If not, you can run the installer by running the sysupgrade(8) command. The upgrader is an interactive command line program that asks you questions and you answer them. It provides useful information you shouldn't accidentally overlook. Before answering any question, read all output since your last answer. You should have this upgrade guide ready at all times. You can view this upgrade(7) page during the installation by answering '!man' to any regular prompt (excluding password prompts). Likewise you can answer '!' to get an interactive shell. Upon completion, you will be asked the question again.

Keyboard Layout

You need to choose the applicable keyboard layout. By default, a standard US keyboard layout is used. You can view a list of keyboard layouts if you wish.

Display Resolution

If a driver exists for your graphics card, then you will be asked for your preferred display resolution by chvideomode(1).

Installation Search

The upgrader will search for existing Sortix installations by probing local filesystems for /etc/sortix-release. You will be asked which installation you wish to upgrade. Enter the name of the root filesystem device. If none are found, it asks if you want to run sysinstall(8). Filesystems will be repaired by fsck(8) as needed.

Confirmation

The upgrader will warn you if it detects you are not following proper upgrade procedure either by downgrading or by skipping a release, neither of which is supported. It will also warn you if it detects an ABI downgrade. The upgrade will load the upgrade preferences from /etc/upgrade.conf file of the target system as described in upgrade.conf(5). The new release may have a new ABI. A major ABI change means the new kernel will be unable to properly execute old programs. A minor ABI change means the new kernel has new compatible features and will be able to run older programs, but older kernels will not be able to run programs using the new ABI. A confirmation screen will tell you what actions the upgrader plan on doing. Answer yes to proceed with the upgrade. Otherwise you can escape to a shell, edit upgrade.conf(5), return and answer no and the upgrader will reload the configuration.

Upgrade

The upgrader will take the appropriate actions:

• Running any upgrade hooks needed to migrate the installation across incompatible changes.
• Updating the system.
• Updating the ports, installing any new ports, and removing any ports that don't exist anymore or weren't loaded.
• Updating the source code.
• Updating the initrd.
• Updating the bootloader.

Completion

The upgrade is now complete. The new system will run after a reboot. The upgrader will give you an overview of what it has done. If you upgraded across a major ABI change, then you will be told that you need to recompile all local programs to use the new ABI. Congratulations on your freshly upgraded Sortix system.

SEE ALSO

chkblayout(1), chvideomode(1), man(1), development(7), initrd(7), installation(7), kernel(7), user-guide(7), sysinstall(8), sysupgrade(8), update-grub(8), update-initrd(8)