Annotation of wikisrc/guide/upgrading.mdwn, revision 1.4

1.4     ! jdf         1: **Contents**
        !             2: 
        !             3: [[!toc levels=3]]
        !             4: 
1.1       jdf         5: # Upgrading NetBSD
                      6: 
                      7: This chapter describes the binary upgrade of a NetBSD system. There are a
                      8: variety of alternatives to perform this procedure, and the following sections
                      9: will guide you through them.
                     10: 
                     11: ## Using sysinst
                     12: 
                     13: ### Overview
                     14: 
                     15: To do the upgrade, you must have some form of bootable media (CD-ROM, USB
                     16: drive, network, etc.) available and at least the base and kern distribution
                     17: sets. Since files already installed on the system are overwritten in place,
                     18: you only need additional free space for files which weren't previously
                     19: installed or to account for growth of the sets between releases. Usually this
                     20: is not more than a few megabytes.
                     21: 
                     22: ### Note
                     23: 
                     24: Since upgrading involves replacing the kernel, boot blocks, and most of the
                     25: system binaries, it has the potential to cause data loss. Before beginning,
                     26: you are strongly advised to back up any important data on the NetBSD partition
                     27: or on any other partitions on your disk, most importantly `/etc`.
                     28: 
                     29: The upgrade procedure is similar to an installation, but without the hard disk
                     30: partitioning. sysinst will attempt to merge the settings stored in your `/etc`
                     31: directory with the new version of NetBSD. Also, file systems are checked
                     32: before unpacking the sets. Fetching the binary sets is done in the same manner
                     33: as in the installation procedure.
                     34: 
                     35: ### The INSTALL document
                     36: 
                     37: Before doing an upgrade it is essential to read the release information and
                     38: upgrading notes in one of the `INSTALL` files: this is the official
                     39: description of the upgrade procedure, with platform specific information and
                     40: important details. It can be found in the root directory of the NetBSD release
                     41: (on the install CD or on the FTP server).
                     42: 
                     43: It is advisable to print the INSTALL document out. It is available in four
                     44: formats: `.txt`, `.ps`, `.more`, and `.html`.
                     45: 
                     46: ### Performing the upgrade
                     47: 
                     48: The following section provides an overview of the binary upgrade process. Most
                     49: of the following sysinst dialogs are similar to those of the installation
                     50: process. More verbose descriptions and explanations of the dialogs are
                     51: available in [[Example installation|guide/exinst]].
                     52: 
                     53: After selecting the installation language and the keyboard type, the main menu
                     54: appears. Choosing option `b: Upgrade NetBSD on a hard disk` will start the the
                     55: upgrade process.
                     56: 
1.3       jdf        57: ![Starting the upgrade](/guide/images/upgrading_main.png)  
                     58: **Starting the upgrade**
1.1       jdf        59: 
                     60: This dialog will request permission to continue with the upgrade. At this point
                     61: nothing has been changed yet and the upgrade can still be cancelled. This is a
                     62: good time to ask yourself whether you have made a backup, and if you know for
                     63: certain that you will be able to restore from it.
                     64: 
1.3       jdf        65: ![Continuing the upgrade](/guide/images/upgrading_confirm.png)  
1.2       jdf        66: **Continuing the upgrade**
1.1       jdf        67: 
                     68: After choosing to continue with `Yes`, the next dialog will ask you to specify
                     69: the hard disk with the NetBSD system that shall be upgraded. If more than one
                     70: disk is available a list of the disks will be displayed.
                     71: 
1.3       jdf        72: ![Choosing the hard drive](/guide/images/upgrading_select-disc.png)  
1.2       jdf        73: **Choosing the hard drive**
1.1       jdf        74: 
                     75: The system used for the example has only one hard disk available: `wd0`.
                     76: 
                     77: The following dialog provides a menu to choose the installation type. The
                     78: choices are `Full installation`, `Minimal installation`, or `Custom
                     79: installation`.
                     80: 
1.3       jdf        81: ![Choosing the distribution filesets](/guide/images/install_install-type.png)  
1.2       jdf        82: **Choosing the distribution filesets**
1.1       jdf        83: 
                     84: At this point, sysinst will perform a check of the file system to ensure its
                     85: integrity.
                     86: 
1.3       jdf        87: ![File system check](/guide/images/upgrading_fsck.png)  
1.2       jdf        88: **File system check**
1.1       jdf        89: 
                     90: The next step is to choose which type of bootblocks to install.
                     91: 
1.3       jdf        92: ![Choosing bootblocks](/guide/images/install_bootblocks.png)  
1.2       jdf        93: **Choosing bootblicks**
1.1       jdf        94: 
                     95: The next dialog will ask how much information should be displayed during the
                     96: extraction of the distribution sets.
                     97: 
1.3       jdf        98: ![Upgrade process - verbosity level](/guide/images/install_verbosity.png)  
1.2       jdf        99: **Upgrade process - verbosity level**
1.1       jdf       100: 
                    101: The following dialog asks for the install method of choice and provides a list
                    102: of possible options. The install medium contains the new NetBSD distribution
                    103: sets. You will be prompted for different information depending on which option
                    104: you choose. For example, a CD-ROM or DVD install requires you to specify which
                    105: device to use and which directory the sets are in, while an FTP install
                    106: requires you to configure your network and specify the hostname of an FTP
                    107: server. More details can be found in
                    108: [[Choosing the installation media|guide/exinst#choosing_the_installation_media]].
                    109: 
1.3       jdf       110: ![Install medium](/guide/images/install_medium.png)  
1.2       jdf       111: **Install medium**
1.1       jdf       112: 
                    113: sysinst will now unpack the distribution sets, replacing your old binaries.
                    114: After unpacking these sets, it runs the postinstall script to clean up various
                    115: things. If no problems occur, you are done. If postinstall produces errors, you
                    116: will have to manually resolve the issues it brings up. See postinstall's man
                    117: page for more information. You should also read the remarks in `INSTALL` about
                    118: upgrading, as specific compatibility issues are documented there.
                    119: 
1.3       jdf       120: ![Upgrade complete](/guide/images/upgrading_complete.png)  
1.2       jdf       121: **Upgrade complete**
1.1       jdf       122: 
                    123: When you are back at the main menu, remove the boot medium (if applicable) and
                    124: reboot. Have fun with your new version of NetBSD!
                    125: 
                    126: ## Using sysupgrade
                    127: 
                    128: The sysupgrade utility (currently found in `pkgsrc/sysutils/sysupgrade`) allows
                    129: you to upgrade a running system to a newer binary release.
                    130: 
                    131: ### Note
                    132: 
                    133: Please be aware that, as of August 2012, sysupgrade is a farily new tool and is
                    134: still undergoing field testing. Use with care. In particular, upgrades across
                    135: major binary releases might not work properly yet because of the lack of a
                    136: reboot between the kernel installation and the unpacking of the sets. That said,
                    137: you may find this tool very convenient to track NetBSD-current or stable NetBSD
                    138: branches.
                    139: 
                    140: One of the benefits of sysupgrade is that it is an integrated and
                    141: almost-unattended solution: the tool fetches the new kernel and distribution
                    142: sets from remote sites if you desire and performs the upgrade without user
                    143: intervention until new changes to the configuration files need to be merged.
                    144: 
                    145: Let's assume you are running NetBSD/amd64 6.0 and you wish to upgrade to NetBSD
                    146: 6.1. The procedure to do so would be to run the following command:
                    147: 
                    148:     # sysupgrade auto ftp://ftp.NetBSD.org/pub/NetBSD/NetBSD-6.1/amd64
                    149:       
                    150: 
                    151: And that's all that it takes. This will proceed to download the kernel and
                    152: sets appropriate for your machine, unpack them and assist you in merging new
                    153: configuration changes. Do not forget to reboot afterwards.
                    154: 
                    155: For more details, please see the included sysupgrade(8) manual page and the
                    156: `/usr/pkg/etc/sysupgrade.conf` configuration file.
                    157: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb