]> Lenz Grimmer Klaus Kaempf Steffen Winterfeldt Hendrik Vogelsang 2006 SUSE LINUX Products GmbH The different Update Media. Version 4.03 - Jan 2006 This Document describes the various Update Media you can create for SuSE/UnitedLinux. They make it possibile to change nearly everything before, during and after the installation process. These Update Media are especially designed for independent hardware and software vendors to provide their customers with software updates/fixes for the SuSE/UnitedLinux distributions.

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 ) to learn how SuSE Linux 9.0 / UnitedLinux SP3 makes that possible )

If you use a Floppy, CD or a DVD the media has to be formated in a Linux readable filesystem because the installer mounts it. For floppys ext2, minix or dosfs and for cdroms iso9660 filesystems are good choices.

If the installation source is on a Harddisk or somewhere on the Network you can create the Update Media layout in the root directory of the installation source.

For HTTP/FTP installations you can put a file 'driverupdate' into the root of your installation source. This file is a (possibly compressed) filesystem image that contains the Update Media.

There are 3 different Types of Update Media 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. 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. The YaST Update makes it possible to update parts of the YaST Installer before installation commences.

With SuSE Linux 9.0 / UnitedLinux Service Pack 3 the Layout of the Update Media has slightly changed. The new features are: The new Layout allows more than one Driver Update ( see ) on a single medium. The meaning of the ALT Key in the bootloader has changed. You can now choose between several update media in linuxrc. Driver updates work with ftp/http installations. USB storage device handling works even if you apply driver updates using the usb floppy drive. There's a menu entry in linuxrc ('Kernel modules' --> 'Add Driver Update') allowing you to apply driver updates in 'manual' mode An optional driver update config file 'dud.config' (see ). The new code is backward compatible. Means you can use your old Update Media also with SuSE Linux 9.0 and UnitedLinux SP3. However the new layout has several improvements and you should use them. The changes in this Document are marked with >= SL 9.0.

SUSE LINUX 9.1 / SLES9 adds one new feature: You can use rpms (instead of update.tar.gz) to add files to the installed system. Just add them to the 'install' directory (see ).

SLES9 SP1 adds two new features: You can add an 'inst-sys' directory. All files in this directory will be updated in the installation environment (see ). Driver updates can have a priority determining the order in which they are applied (see ).

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

The three different types of Update Media share some settings and 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

Since SuSE Linux 9.0 / UnitedLinux SP3 you can use a decimal number in front of the Operating System string. The [number] part is optional and can be used to easily combine several driver updates into one. Updates from one medium are applied ordered by [number]. If a directory without [number] exists, it is applied first. 01/ `-- linux/ | `-- suse | `-- i386-8.1 02/ `-- linux/ `-- suse `-- i386-8.1 This is extremely helpfull if you have Driver Updates where the kernel modules depend on each other.

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 ). 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.

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.

There are two ways of applying updates from an Update Media. From a changeable media (see ) or from the installation source (see ). Applying updates from a changeable media might require user interaction. Thats the case when: 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. 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 ) 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'.

The Driver Update is providing a possibility 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. Even though linuxrc (the first stage of the installation process) has the ability to load driver modules from a separate modules floppy, these modules are not used for the installed system afterwards, because the YaST Installer installs a kernel RPM during the package installation. This driver update feature will use a provided kernel driver module during the installation process and will also place it into the installed system in order to be able to boot up the installed system later.

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

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!

Instead of unpacking a tar archive, you might prefer to use rpm packages. Starting with SUSE LINUX 9.1 all rpms that are in the 'install' directory will be installed.

update.pre is a shell script, that contains commands that should be executed within the running installation system right after the YaST installer is started, e.g. creating device entries using mknod or echoing parameters into /proc. If you need the driver module to acces the root filesystem you can use this update.pre script to add the driver module to the initial ramdisk (initrd).

update.post is an shell script that is executed by the YaST installer after the basic installation has finished and the update.tar.gz archive has been extracted into the installed system. This script is executed in the root directory of the installed system. It can be used for adding or changing entries in modules.conf, creating device nodes in the installed system etc.

There are situations for which update.post is run too early (say you want to apply changes to the boot loader config). A new script 'update.post2' is introduced that will be run just before YaST2 unmounts the installed system.

Sometimes it is necessary to update files in the installation environment itself. All files below the 'inst-sys' directory will be updated. The directory structure is preserved. If you want to replace the hardware detection library, for example, add it as 'inst-sys/usr/lib/libhd.so.X.Y'.

The driver update config file consists of lines with the format 'key: value'. Valid keys are UpdateName A short description, shown in linuxrc when the driver update is applied. This key may appear more than once. UpdateID An unique string identifying the update. There's no meaning attached to the value. It is only used to avoid applying the same update accidentally twice. UpdatePriority (>= SLES9 SP1) A number less than 900. Updates with higher numbers are applied after updates with lesser numbers. Normally, updates are assigned increasing priorities starting with 0 in the order they are found. Note that this does not work for module updates as modules are always loaded immediately.

To test if your Driver Update Medium works you can use this dummy driver module. You can compile it with the command below. gcc -Wall -DMODULE -D__KERNEL__ -DLINUX -c duddm.c -I/lib/modules/`uname -r`/build/include

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 ) 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 ) 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).

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 ) 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 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.

The Vendor Update is a more general Update Medium. It is not limited to the installation of kernel modules and its not limited to only being used during the installation. The YaST Vendor CD module makes it possible for the user to install this Update Medium into a running System.

All the files for the Vendor Update sit in the base directory ( see ) 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.

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.

A YaST Update is a Update Medium that contains a directory with the name of y2update. The directory contains a file hierarchy identical to that under /usr/share/YaST2. It can be used to replace config files or YaST2 components from the CD with new versions.

For a YaST Update only it is sufficient to have a directory y2update in the base directory ( see ) 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

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 ) 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