Creating a Kernel Module Update Installation Source

From openSUSE

The following information is subject to change. Partner feedback is requested.

Note: If your kernel module package is GPL-licensed, an option exists to host the package on a Novell update site instead of going through creating your own installation source.

Overview

A kernel module update installation source is a disk, local directory or web site used by SUSE Linux utilities to install and/or update kernel modules on users' systems. By creating a kernel module update installation source, partners can provide customers with the ability to get correct kernel module versions automatically, as part of the SUSE installation and update process. This automatic update process reduces versioning problems and greatly improves the overall customer experience.

Partners who wish to provide drivers needed during the installation process should create a Driver Update Disk. Partners who wish to provide a kernel module installation/update source via http or ftp may choose to implement a YaST source, a module update repository, an Add-on product source, or a YUM source.

Step-by-Step Instructions

The following sections list the steps to create a Driver Update Disk (Code 9 and Code 10), a YaST Installation Source (Code 9), a Module Update Repository (Code 9), an Add-on Product Source (Code 10) and a YUM Repository (Code 10).

Creating a Driver Update Disk 9 (Code 9 and Code 10)

• Prerequisites:

1. Kernel modules (*.o or *.ko files) to be installed during OS installation. (These kernel modules must be built to match the kernel used during installation).
2. gzipped tar file containing modules built for all supported kernel versions or separate rpms for different supported kernel versions.  ??? Should these be signed ???
3. Media to be used for Driver Update Disk (CD, DVD, or floppy disk).

• Create a staging directory (e.g., "/work/staging") on your local system.
• Create the following directory structure in <staging>/:

   linux/
     suse/
       <architecture>-<suse version>/  (e.g., "i386-sles9")
         install/
         modules/

• Place the following files in the "install" directory:

1. Optional installation shell scripts:
   1. Pre-installation script named "update.pre".
   2. Post-installation script named "update.post".
   3. Secondary post-installation script named "update.post2", which will run just before YaST2 unmounts the installed system.
2. Separate RPMs for different kernel versions or a gzipped tar archive named "update.tar.gz" which contains driver modules for all possible kernel versions.
   1. If using the "update.tar.gz" file (instead of RPMs), the archive should include:
      1. Full directory structure for placement of the driver modules.
      2. Driver modules compiled for all kernel versions available on the distribution in both SMP and uniprocessor configurations.
      3. (Optional) New device nodes or other files that should be installed into the system.

• Place the uncompressed updated driver modules (*.o or *.ko) for the installation kernel in the "modules" directory. These are the modules which will be loaded during the OS installation. Note: an installation kernel is usually a -default flavor, so the modules in this directory should also be built for the -default flavor.
• Create the driver update disk by burning (CD/DVD) or copying (floppy disk) the contents of <staging>/ onto the chosen media.
• Sign the add-on media as detailed in "Secure Installation Repositories" at the end of this page.
• More detailed instructions on creating a driver update disk are provided at Update Media HowTo for more information on creating a Code 9 Driver Update Disk.

Creating a Code 9 YaST Installation Source

• Prerequisites:

1. RPM which has been built in accordance with SUSE Packaging Conventions (add link) and Kernel Module Packages Manual for CODE 10
2. ftp or http site configured (permissions, etc.) in such a way as to allow the public to download from it.

• Create a staging directory (e.g., "work/staging").
• Create the following directory structure:

   <staging>/
       media.1/
       suse/
          i386/
          i486/
            .
            .
            .
          setup/
             descr/
 Note:Some of these names may be defined by the user, please refer to openSUSE Installation Sources for more information.

• Place your appropriate product RPMs in the <staging>/suse/<arch> directories.
• Create a media file containing at least the author name, creation date, and number of media in <staging>/media.1/. Example:

   SUSE Linux Products GmbH
   20060505000500
   1

• Create a directory.yast file by typing "ls -A1 -p >directory.yast" in each directory except the <staging>/suse/<arch> directories.
• Install the autoyast2-utils package.
• Rrun "create_package_descr -C" to create package description files in <staging>/suse/setup/descr/ from within <staging>/suse/.
• Create a <staging>/content file as detailed in openSuSE Installation Sources. Example:

    PRODUCT e1000 Drivers
    VERSION 1.0
    VENDOR SUSE LINUX Products GmbH, Nuernberg, Germany
    LABEL Source designation to be used in YaST
    ARCH.i586 i586 i486 i386 noarch
    ARCH.i486 i486 i386 noarch
    ARCH.i386 i386 noarch
    DEFAULTBASE i586
    DESCRDIR suse/setup/descr
    DATADIR suse

• Move the entire contents of <staging>/ to your chosen YaST repository site.
• Sign the repository as detailed in "Secure Installation Repositories" at the end of this page.
• For more information and details about creating a Code 9 YaST repository, please refer to openSUSE Installation Sources.

Creating a Code 9 Module Update Repository

• Prerequisites

1. Download site (http or ftp) which can be accessed by the installation utilities.
2. RPM which has been built in accordance with Kernel Module Packages Manual for CODE 9:
   1. Note: The specification file used to build each RPM must contain the URL for the update repository.
   2. Note: The user's system must have an initial version of the partner product installed and thus have a /var/lib/YaST2/download/<package_name> file which lists the URL for the update repository.

• Create a staging directory (e.g., "/work/staging").
• Place your RPMs in <staging>/. Note: The name of each RPM (minus version numbers) must be exactly the <package_name> in the user's /var/lib/YaST2/download directory.
• Copy the contents of <staging>/ to the URL for the update repository.

Creating a Code 10 Add-on product repository

• Prerequisites:

1. RPM(s) (preferably signed) which have been built as detailed in Kernel Module Packages Manual for CODE 10
2. Download site or separate media for the addon product.

• Create a staging directory (e.g., "work/staging").
• Create the following directory structure:

   <staging>/
       media.1/
       suse/
          i386/
          i486/
            .
            .
            .
          setup/
             descr/

Note that some of these names may be defined by the user, please refer to Creating Add-ons for more information.

• Place your appropriate product RPMs in the <staging>/suse/<arch> directories, .
• Create a media file containing at least the author name, creation date, and number of media in <staging>/media.1/. Example:

   SUSE Linux Products GmbH
   20060505000500
   1

• Create a "products" file to describe the different products and their locations on your add-on media in <staging>/media.1/. Example:

   /                       Product 1 Name
   product_2_directory     Product 2 Name
   product_4_directory     Product 3 Name
           .
           .
           .

• Create a directory.yast file by typing "ls -A1 -p >directory.yast" in each directory except the <staging>/suse/<arch> directories (where the rpms are located).
• Create an MD5SUMS file by typing "md5sum * >MD5SUMS" in each <staging>/suse/<arch>/ directory.
• Install the autoyast2-utils package.
• Run "create_package_descr -C" to create package description files in <staging>/suse/setup/descr/From within <staging>/suse/.
• Create a <staging>/content file as detailed in Creating Add-ons. Example:

    PRODUCT e1000 Drivers
    VERSION 1.0
    DISTPRODUCT SUSE-Linux-1.0-e1000
    DISTVERSION 1.0-0
    VENDOR SUSE LINUX Products GmbH, Nuernberg, Germany
    ARCH.i586 i586 i486 i386 noarch
    ARCH.i486 i486 i386 noarch
    ARCH.i386 i386 noarch
    DEFAULTBASE i586
    DESCRDIR suse/setup/descr
    DATADIR suse
    META SHA1 04ef39995b65f02d81d6e1cc22fffda5c3a2a40e MD5SUMS
    META SHA1 b8b7146ce7b1e957bec2978ecaa38078db400ce5 pacakges
    META SHA1 12ee25db081bf57beaef32b798262a18f9242216 packages.DU
       .
       .
       .
 Note: The "META SHA1 ..." lines list the sha1 message digests of each file in the
 <staging>/suse/setup/descr/ directory. To obtain these digest values, run "sha1sum <filename>" for each file.

• Sign the repository as detailed in "Secure Installation Repositories" at the end of this page. Note: If you do not sign your repository, the end-user will be asked to approve its use as an installation source.
• If you wish to make a CD/DVD/diskette add-on product, create the add-on disk by burning (CD/DVD) or copying (floppy disk) the contents of <staging>/ onto the chosen media.
• If you wish to place the repository on a download site, copy the contents of <staging>/ to the download site URL.
• For more information and details about optional items that can be placed in a Code 10 YaST repository, please refer to Creating Add-ons.

Creating a Code 10 YUM repository

Note: A Code 10 YUM Repository may also be used as an Add-on Product Installation Source.

• Prerequisites:

1. RPM(s) (preferably signed) which have been built as detailed in Kernel Module Packages Manual for CODE 10.
2. ftp or http site configured (permissions, etc.) in such a way as to allow the public to download from it. For Code 10, this download site does not have to be specified in the package's specification file.

• Determine which directory on the ftp/http site will contain the YUM structure and packages needed by the Novell installation utilities.
• Create a "staging" directory on your local system (e.g., /work/staging/yum/product_name/suse). You can make the local system's staging directory structure to mimic the ftp/http site's structure.
• Create a "SLE10" directory in the staging directory.
• Create a directory for all the architectures supported (e.g., "i586, "x86_64", etc.) in the "SLE10" directory.
• Place the appropriate RPMs in each of the specific architecture directories.

• If your kernel module is not GPL you must create a license file that will be shown (in YaST and ZEN Updater) to the user to accept or reject the downloading and installing of your kernel module. To associate a license file with an RPM the license file is placed in the same directory as the RPM and given the same name as the RPM with the extension of ".eula.<LANGUAGE> (where LANGUAGE is a two character extension representing the language of the license text with the default being english).

For example, to have an english license file associated with the "myKernelModule-1.2.3-1.i386.rpm" RPM you need a license file named "myKernelModule-1.2.3-1.i386.rpm.eula.en" in the i386 directory.

For Code 10, a special version of createrepo must be used. It can be obtained from <TBD: add link to createrepo-0.4.4-10>. This version of createrepo understands how to "embed" the license text into the repository which allows a user to accept or reject the downloading/installating of the driver when using YaST and ZEN Updater.

 If you have a license file which is the same for all RPMs you can create a symbolic link to
 a license file by running the link-eula.sh script <TBD: add link to link-eula.sh>
 To run it, type "link-eula.sh <license_file_name> <language>" the directory where the RPM is located.
 This script will create a "<package>.eula.<language>" file which is a link to the given license file.

• The createrepo script is run as follows: "createrepo ." from within the top staging directory (e.g. <staging>/suse/). This should create a "repodata" directory (containing the repository metadata files) in your staging directory.
• Sign the repository as detailed in "Secure Installation Repositories" at the end of this page. Note: If you do not sign your repository, the end-user will be asked to approve its use as an installation source.
• Place the contents of your staging directory (not including the staging directory itself) on your ftp/http site. This ftp/http site URL must match the URL supplied to Novell for inclusion in the SUSE installation utilities. After all the steps are completed, the URL should contain the SLE10 and repodata directories.

Secure Installation Repositories

Once the YaST or YUM repository has been created, the repository must be "signed" as detailed in How to Sign YaST and YUM Repositories. Basic steps:

Signing a YaST Repository

• If you do not already have an established key, create one:

   gpg -q --gen-key

• Get the value of this key (temporarily store it in the MY_KEY variable):

   MY_KEY=$( gpg --list-secret-keys | grep "^sec"|sed -e 's/.*\///;s/ .*//g;' | tail -n 1 )

• From within your staging directory, sign the content and media.1/products files and export the key:

   gpg --detach-sign -u MY_KEY -a content
   gpg --export -a -u MY_KEY > content.key
   gpg --detach-sign -u MY_KEY -a media.1/products
   gpg --export -a -u MY_KEY > media.1/products.key

• Export your key:

   gpg --export -a MY_KEY > gpg-pubkey-MY_KEY.asc

• In the <staging> directory, recreate the directory.yast file by typing "ls -A1 -p > directory.yast".
• In the <staging>/media.1 directory, recreate the directory.yast file by typing "ls -A1 -p > directory.yast".

Signing a YUM repository

• If you do not already have an established key, create one:

   gpg -q --gen-key

• Get the value of this key (termporarily store it in the MY_KEY variable):

   MY_KEY=$( gpg --list-secret-keys | grep "^sec"|sed -e 's/.*\///;s/ .*//g;' | tail -n 1 )

• From within your staging directory, sign the repodata/repomd.xml file:

   gpg -a --detach-sign repodata/repomd.xml

• Export your key:

   gpg -a --export <your key id> > repodata/repomd.xml.key