1.1. What is an Update Medium?

An Update Medium is a changeable Media (CD/DVD or a floppy disk) or a directory in the installation source. In theory it is possible to use any changeable media (like USB sticks) but this is not yet implemented in the YaST installer. ( see Section 2.4) to learn how SuSE Linux 9.0 / UnitedLinux SP3 makes that possible )

1.2. The different types of Update Media

There are 3 different Types of Update Media

1. The Driver Update makes it possible to install SuSE/UnitedLinux on devices that were not supported at the time the distribution was created and be able to boot the installed system afterwards without having to manually install the new device drivers after the installation.

2. The Vendor Update provides an easy way to install software, or even device drivers, that are not included in the distribution, with YaST. This can be done either at the end of the installation or anytime in a running system with the YaST Vendor CD module.

3. The YaST Update makes it possible to update parts of the YaST Installer before installation commences.

1.3. Changes since SuSE Linux 9.0 / UnitedLinux Service Pack 3

With SuSE Linux 9.0 / UnitedLinux Service Pack 3 the Layout of the Update Media has slightly changed. The new features are:

1. The new Layout allows more than one Driver Update ( see Chapter 3) on a single medium.

2. The meaning of the ALT Key in the bootloader has changed. You can now choose between several update media in linuxrc.

3. Driver updates work with ftp/http installations.

4. USB storage device handling works even if you apply driver updates using the usb floppy drive.

5. There's a menu entry in linuxrc ('Kernel modules' --> 'Add Driver Update') allowing you to apply driver updates in 'manual' mode

6. An optional driver update config file 'dud.config' (see Section 3.1.7).

1.4. Changes in SUSE LINUX 9.1 / SLES9

SUSE LINUX 9.1 / SLES9 adds one new feature:

1. You can use rpms (instead of update.tar.gz) to add files to the installed system. Just add them to the 'install' directory (see Section 3.1.2).

1.5. Changes in SLES9 Service Pack 1

SLES9 SP1 adds two new features:

1. You can add an 'inst-sys' directory. All files in this directory will be updated in the installation environment (see Section 3.1.6).

2. Driver updates can have a priority determining the order in which they are applied (see Section 3.1.7).

1.6. Resources

The latest version of this Document is always at ftp://ftp.suse.com/pub/people/hvogel/Update-Media-HOWTO/

2.1. Directory structure

The base directory structure for all the Update Media is

		 /linux/[distribution]/[architechture]-[version]/
		

This way you can have one Update Medium for multiple distributions, architectures and versions. In theory the Operating System string (linux) is also changeable but the YaST Installer works only under Linux yet.

The [distribution] string is the name of the distributor. For now the only strings that are valid here are suse and UnitedLinux. The range of architectures is rather wide. Up to now the [architechture] string is i386, ia64, ppc, ppc64, s390, s390x sparc or x86_64. The [version] string is either the product version of the distribution, i.e 8.1 or sles7, sles8, slec1, ul1.

		linux/
		`-- suse
		 |   `-- i386-8.1
		 |   |   
		 |   `-- ppc-7.3
		 |       
		 --UnitedLinux
		     `-- x86_64-ul1
		     | 
		     `-- ia64-sles8
		

		01/
		`-- linux/
                |	`-- suse
	        |            `-- i386-8.1
                02/
		`-- linux/
                        `-- suse
                             `-- i386-8.1
                

2.2. Update Media name and id (>= SL 9.0)

linuxrc keeps track of updates it applies ('Show Driver Updates'). For this you can assign a name and an id to an update using the file dud.config below the base directory ( see Section 2.1).

		UpdateName: Sample Update
		UpdateID:   some random stuff
		

UpdateName may appear more than once. If UpdateName is missing, the names of the updated modules are used. UpdateID serves only to prevent updates from getting applied more than once accidentally.

2.3. Combinations of different Update Media

Because the Update Media use the same base structure and the same functionality to "detect" the [distribution], [architecture] and [version] they can easily be combined. You can have one cdrom that provides the possibility to install SuSE/UnitedLinux with a fixed device driver, add extra documentation for it and install your newest application all at once.

2.4. Applying Updates

There are two ways of applying updates from an Update Media. From a changeable media (see Section 1.1.1) or from the installation source (see Section 1.1.2). Applying updates from a changeable media might require user interaction. Thats the case when:

1. The Update Media is on the same media type as the installation kernel. For example a media change will be required if you boot the installation from a floppy and the Update Medium is also a floppy.

2. You have multiple Update Media on different changeable media. For example a Driver Update on a floppy and a YaST Update on a CD. (>= SL 9.0)

If thats the case you can press the 'driver update' key at the boot screen or use the parameter 'driverupdate=1'. linuxrc will apply any driver updates it finds on floppy disk and then ask the user for further driver updates (>= SL 9.0). If you start in manual mode, use the 'Kernel modules' --> 'Add Driver Update' menu entry to load driver updates.

SLES10 for i386 and x86-64 offers to load driver updates from CD-ROM via BIOS functions which is helpful if you cannot access the CD drive from linux in any way. For this, pack the complete driver update data (with number prefix to avoid problems when applying several updates - see Section 2.1.1) into a (optionally gzipped) cpio archive (use 'cpio -H newc') and put the archive on a CD. At the boot prompt add, e.g., 'driverupdate=/update1,/update2' to load updates '/update1' and '/update2'. If '/update2' is on a different CD than '/update1', add a '+' in front of it ('driverupdate=/update1,+/update2') indicating you want a prompt for changing the CD before '/update2'.

3.1. Included files on the update medium

For this type of Update Medium you need two subdirectorys below the base directory structure described above. One is the install directory: install/. This directory contains an optional pre-installation script named update.pre, the driver modules for all possible kernel versions either as a gzipped tar archive named update.tar.gz or as separate rpms (*.rpm, since SL 9.1) and two optional post-installation scripts named update.post and update.post2 (>= SL 9.0). The other directory is the modules directory: modules/. It contains the uncompressed updated driver modules (*.o or *.ko) for the installation kernel that are loaded during the initial installation. If you need to ensure a specific module loading order you can add a file 'module.order' (>= SLES9 SP1) which has one module name (without '.ko') per line. Modules are loaded in the order they are listed in that file.

		linux/ 
		`-- suse/ 
		     `-- i386-9.1/
		         `-- dud.config         # >= SL 9.0
			 |-- install/
		         |    `-- update.pre
			 |     -- update.tar.gz
			 |     -- update.post
			 |     -- update.post2  # >= SL 9.0
			 |     -- foo.rpm       # >= SL 9.1
			 |     -- bar.rpm       # >= SL 9.1
			 |-- modules/
			 |    `-- module.order	# >= SLES9 SP1
			 |    `-- module1.ko
			 |    `-- module2.ko
			 |    `...
			 `-- inst-sys/          # >= SLES9 SP1
			      `-- foo
		

---

3.1.1. update.tar.gz

The file update.tar.gz is a gzipped tar archive that includes the directory structure and the updated driver modules. The archive should contain the driver modules compiled for all kernel versions available on the distribution in both SMP and uniprocessor configuration. In addition, the tarball may include new device nodes in /dev/ or other files that should be installed into the system (e.g. additional documentation) - it will simply be extracted in the root directory of the installed system.

The files contained in this archive will not be listed in the RPM database and will overwrite files that are already installed on the system!

		gcc -Wall -DMODULE -D__KERNEL__ -DLINUX -c duddm.c -I/lib/modules/`uname -r`/build/include
		

3.2. Creating the driver modules

Documentation on how to build kernel modules for SuSE Linux / UnitedLinux is available at http://www.suse.de/~agruen/kernel-doc/

Lets assume you have updated the module e100 for the default kernel of SuSE Linux 9.0. Then you need the following structure in the update.tar.gz ( See Section 3.1.1 ) file.

		lib/modules/2.4.21-override-default/kernel/drivers/net/e100/e100.o
                

You can create the update.tar.gz file using the following commands:

		cd /tmp
		mkdir -p lib/modules/2.4.21-override-default/kernel/drivers/net/e100/
		cp /path/to/your/updated/e100.o lib/modules/2.4.21-override-default/kernel/drivers/net/e100/
		tar cvzf update.tar.gz lib/
		

This will create a compressed tar archive update.tar.gz in the /tmp directory, which can now be copied to the install directory ( See Section 3.1 ) on the Driver Update medium.

The directory names in the tar archive must not include the leading slash! Make sure all files belong to user "root" and have the correct permissions (modules should have -rw-r--r--, directories should have -rwxr-xr-x).

3.3. Workflow for the Driver Update

The Driver Update workflow consists of the following steps:

• The system boots from the installation CD or floppy disk syslinux/isolinux starts up

• The user adds 'driverupdate=1' to the kernel command line (or activates driver updates using the graphical boot loader interface). (optional. see Section 2.4)

• syslinux prompts the user for an "Update Medium" if a media change has been requested.

• The user inserts the new media and presses the Enter key, syslinux boots into the update mode of linuxrc

• linuxrc mounts the media

• linuxrc copies all files from the install directory into a directory in a RAM disk mounted below /update.

• linuxrc loads all driver modules below the modules directory by first unloading all modules with the same name and loading the new modules from this directory. This happens in the order the modules have been installed on the media! This is important if some driver modules depend on other.

  See Section 2.1.1 how the new layout since SuSE Linux 9.0 / UnitedLinux SP3 handles this.

• linuxrc unmounts the update media

• now linuxrc kicks back and starts the Installer to continue the installation

• before starting the installation of packages, the Installer first execute the update.pre script.

• after the initial installation, the Installer extracts update.tar.gz in the root directory of the installed system and then runs update.post.

4.1. Included files on the update medium

All the files for the Vendor Update sit in the base directory ( see Section 2.1) of the Update Media.

Each Vendor Update must be accompanied by at least two files.

• One installation script with the suffix .ins

• and one description file with the suffix .des

YaST first looks at all files with a .ins extension. These are the installation script files, one per Vendor Update. The file name (without the .ins extension) serves as a key to identify the Vendor Update and the accompanying description files. This makes it possible to put multiple Vendor Updates into one directory.

The installation script is free to do what it wants. Usually, the script should first check if it's applicable. Probing the hardware and checking the kernel version are minimum requirements to be checked by the script. The YaST Vendor CD module executes this script with the full path to the base directory as parameter. Based on this parameter, the script can easily extract further data from the CD.

Keep in mind that only standard linux tools will be available. For example, perl is considered a standard tool, tcl is not. And the script together with any data on the CD should be self-contained.. It should not have any package dependencies which exceed a minimal installation.

There should be multiple description files for each Vendor Update, one per supported language. At least a default (in English) should be provided. The description files have .desc as the extension start with the name (key) of the corresponding .ins file. In order to support multiple language description files, YaST appends the ISO language code to the Vendor update name before loading the default description file. For example, the ISO language code for British English is en_GB. The english description file for a Vendor Update called modem would be modem-en_GB.desc. If the full (5-char) ISO code cannot be found, YaST falls back to the two char language code. With this mechanism, several languages (i.e. de_AT for Austrian, de_CH for Swiss, and de_DE for German) can be supported by a single description file called modem-de.desc In order to support non ISO-1 (non western europe / us) languages, like Japanese, the description file must be coded in UTF8. UTF8 is the standard coding used in Linux.

		linux/
		`-- suse/
		    `-- i386-8.1/
			`-- modem.ins
			`-- modem.desc
			`-- modem-zh_CN.desc
			`-- modem-ja_JP.desc
			`-- speedblazer.ins
			`-- speedblazer.desc
			`-- speedblazer-de.desc
			`-- speedblazer-fr.desc
			`-- speedblazer-pt_BR.desc
		

The .desc files without a language code should contain the default description in English.

4.2. Workflow for the Vendor Update

The Vendor Update workflow consists of the following steps

• The User clicks on the Vendor CD Button in YaST

• When started, the Vendor Update CD module of YaST tries to mount /dev/cdrom on /var/adm/mount. If it fails YaST tries to mount /dev/fd0 on /var/adm/mount. If this also fails the user is asked to insert the vendor driver CD.

• After a successful mount, YaST tries to find the correct directory as described above. For a SuSE Linux 8.1 (i386) distribution, YaST would look for the linux/suse/ on the CD. If this fails, the CD is rejected with the message "Couldn't find driver data on the CD-ROM". Then the directory linux/suse/i386-8.1/ is searched. YaST will fail with "CD-ROM data doesn't match running SuSE Linux" if this directory doesn't exist. This and all further error messages will be presented in the correct language the user has choosen at the start of the installation.

• Next, YaST scans the directory for installation script files (files ending with .ins). If no files with extension .ins can be found, YaST rejects the CD with "Couldn't find driver data on the CD-ROM".

• For each installation script file, a matching description file is searched. The match algorithm is described above. If no matching description file can be found, the driver is silently skipped.

• For each driver, the first matching description file is read in and presented to the user in a pop-up window. The window has two buttons, one labled "Yes" the other one labled "No". The button labels will be properly translated by YaST to the correct language.

• If the user clicks on the "No" button, the driver is skipped.

• If the user clicks on the "Yes" button, the installtion script file is copied to the /tmp directory of the running system. This copying is done to prevent errors when executing files from mounted media, which is not normally allowed by default. YaST does a chmod 2774 to the file in order to force read, write, and execute permissions for root. Then the working directory is set to /tmp and the installation script is executed with the full directory path as the argument. There is no automatic mode, the user is asked separately for each Vendor Update.

• YaST evaluates the exit code of the script. If it is non-zero, a popup with the message "Installation failed" is presented to the user.

• After execution, the installation script is removed from /tmp. The script should remove any temporary files that it creates during execution.

• After all .ins files have been processed, YaST present a summary with the number of successfully installed Vendor Updates. If no Vendor Updates could be successfully installed, YaST pops up a message reading "Couldn't find driver data on the CD-ROM".

• As the final step, /var/adm/mount will be unmounted.

5.1. Included files on the update medium

For a YaST Update only it is sufficient to have a directory y2update in the base directory ( see Section 2.1) of the Update Medium. Everything present in this directory before YaST starts will be used by the installer.

                linux/
                `-- suse/
                    `-- i386-8.1/
                	`-- y2update/
			    `-- clients/
			    |  `-- inst_software.ycp
			    `--	config/
				`-- groups.y2cc
                

5.2. Workflow of the YasT Update

The YaST Update workflow consists of the following steps

• The system boots from the installation CD or floppy disk syslinux/isolinux starts.

• The user adds 'driverupdate=1' to the kernel command line (or activates driver updates using the graphical boot loader interface). (optional. see Section 2.4)

• syslinux prompts the user for an "Update Medium" if a media has been requested.

• The user inserts the media and presses the Enter key, syslinux boots into the update mode of linuxrc

• linuxrc mounts the media

• linuxrc copies linux/[distribution]/[architechture]-[version]/y2update/* to /update/y2update

• linuxrc umounts the media

• The YaST Installer starts