Standards/YaST2 Repository Metadata/media

From openSUSE

YaST/Zypp media description

Requirements

• Multiple products per media
  A media may contain several products, i.e. a combined patch media.
• Multiple architectures per product
  A media may contain products for multiple architectures.
• Bi-Arch support
  An architecture may be bi-arch, where mixing of compatible architectures is allowed.
• Multiple languages per product
  A media may contain products for multiple languages.
• Media sets
  a) The content may be splitted onto multiple media - which form a media set.
  b) It must be able to merge a media set into a single directory.
  c) Media might be double-sided (e.g. DVD-ROM).
  
• A media must be easily recognizable by the system
  This is needed when re-inserting a cd-rom media for further package installation. The system must verify that the correct media is inserted and can be used for package installation.
• product name
• product version
• base distribution
  specify the distribution the product is based on.
• base distribution version
• product vendor
• user-readable content description
  This is needed to present media information to the user prior to installing packages. The user must be able to decide on this information to proceed or cancel the installation process.
• package path
  toplevel path to packages (i.e "suse/" on SuSE media, "unitedlinux/" on UL media, etc.)
• default language
  default language if no language is determinable.
• inital server for online update
• no wildcard search for files
  doing a wildcard search is cheap on a local media but almost impossible via HTTP. So it should be avoided if possible.

Implementation

The media and product description is splitted into a set of files, separating the media preparation data from the contents (product) and making it possible to combine several products on a single media.
At toplevel of a media, a directory

       /media.1/

should exist.

The numeric extension depends on the media number in case of a media set. The first media has .1, the second .2, and so on.
This allows merging all medias of set into a single directory. YaST always knows which media to expect and can therefore directly access the correct media directory.

Files inside media.N/

Inside the media.N/ directory the files media and products must exist.
Optionally, a file named patches may exist to denote a media with patches (e.g. for YaST online update).

The media file contains the media identifier needed to determine correctness when using removable media.
In case of splitted media, it must be present on every media of the set.

The products file contains directory specifications for each product.
In case of splitted media, it must be present of the first media of the set.

The patches file contains a single directory specification for the root of the patches directory tree and an optional list of exclusive products the patches apply to.
In case of splitted media, it must be present of the first media of the set.

The /media.N/media file

This should contain an identifier to quickly verify the media set the media belongs to. This identifier is not shown to the user but should contain human-readable data for debugging purposes.

Usually a timestamp, e.g. 20061129031301, is used as media set identifier.

The identification data is stored inside the file on purpose. It could also be encoded in the file name (older SuSE media did it). But this requires a directory scan for file access and should be avoided.

By storing the vendor name in the file, the timestamp can be kept vendor specific. (It's the name of the vendor who created the media which might be different from a product vendor! It's just used as an additional key for media identification.)

All media of a set must provide identical vendor and identification information in the media file.

The /media.1/media file

The /media.1/media file may contain additional information.
The remaining media files of a media-set may repeat this information, but it is not evaluated again.

The <media count> is needed if the installation data is split up on multiple (identical) medias.
The media count is a numerical value (all characters are digits), and defaults to 1.

<media flags> may further describe the media.
In order to distinguish the flags from the count line, the flags values start with a letter.

Currently defined flags:

<media names> may define alternate strings to use when asking to insert a certain media.
They are defined as <key><whitespace><value> pairs, separated by \n.

Example

linux# mount /dev/cdrom /mnt
linux# ls /mnt/media.1
media
products
linux# cat /mnt/media.1/media
SuSE Linux AG
20020921153042
3
MEDIA1 SUSE Linux 9.1 DVD 1
MEDIA2 SUSE Linux 9.1 DVD 2
MEDIA3 SUSE Linux 9.1 DVD 3
linux#

The products file

This file contains the directory name for each product contained on the media.

If this file is not present, a single product on the media's root directory is assumed.

It is an ASCII file with one line per product.

Each line starts with the directory name (relative to the media's root dir !), followed by whitespace (space or tab) followed by the product name and version.
A leading slash in the directory name is only needed to specify the root directory of the media.

Example

linux# mount /dev/cdrom /mnt
linux# cat /mnt/media.1/products
/      SuSE Linux Personal 8.1-0
sles-8 SuSE Linux Enterprise Server 8-0
openlinux      Caldera OpenLinux 4.0-0
linux# ls -a /mnt
...
media.1/
...
sles-8/
openlinux/
...

In the above example, "SuSE Linux Personal" uses the toplevel directory, whereas the other products have their own sub-directories.

The content file

This file resides inside the product directory as specified by the products file on the media. It contains all product-specfic data to describe and identify the contents of the product.

If there was no products file, the product directory defaults to the root directory on the media.

The content file might be missing if the media does not contain a product (but just a set of packages).
In this case, the user has to 'blindly accept' the media.

Proposal:

Mandatory key strings

prio 'M' == mandatory, 'O' == optional
Either LABEL or LABEL<lang> must be present.

The ARCH.<base> line needs a bit more explanation:
Supporting bi-arch architectures and optimized packages requires multiple (architecture optimized) occurances of a package (under the same name and version).
In order to determine which the 'right' occurance is, YaST needs a fallback strategy (a search order).

The <base> tag is used as a starting point and determines 'the' architecture of the system. This is determined by running uname -m (and looking at /proc/cpuinfo).
For this <base>, a matching ARCH.<base> must exist. If it isn't found, <base> gets the value of DEFAULTBASE for which a matching ARCH.<base> is guaranteed.

The value of the ARCH.<base> line is the search order for packages. The first package matching the architecture is taken as the preferred candidate.
Packages with architectures not in this list are discarded and do not appear for selection. Packages with 'lower' architectures are still available for selection, so the user can manually choose such a package.

The RELNOTESURL line is used to define the location of the release notes rpm. Currently only http is supported. The rpm is installed with rpm -U --replacepkgs 'basename of url'.

The FLAGS line is used to describe the (installation) capabilities of the product. It's value is a list of space separated keywords.
The following keywords are currently defined:

The location of the rpm file for a package on the installation media is determined by the =Loc: line in the [package-descr.html packages] file.

Example

linux# mount /dev/cdrom /mnt
linux# cat /mnt/sles/content
PRODUCT SuSE Linux Enterprise Sever
VERSION 8.0-0
BASEPRODUCT UnitedLinux
BASEVERSION 1.0-0
VENDOR SuSE Linux AG
ARCH.x86_64 x86-64 i686 i586 i486 i386 noarch
ARCH.i686 i686 i586 i486 i386 noarch
ARCH.i586 i586 i486 i386 noarch
DEFAULTBASE i386
LINGUAS en de_DE
LABEL.en SuSE Linux Enterprise Sever based on UnitedLinux
LABEL.de_DE SuSE Linux Enterprise Sever basierend auf UnitedLinux
DESCRDIR suse/setup/descr
DATADIR suse
REQUIRES foo pattern:bar
LANGUAGE de_DE
TIMEZONE Europe/Berlin
RELNOTESURL http://www.suse.com/relnotes/sl_82/release-notes.rpm
FLAGS update
YOUURL http://www.suse.de/cgi-bin/suseservers.cgi
YOUTYPE business
YOUPATH i386/update/SuSE-SLES/8
linux#

The patches file

This file contains a single directory name for the root of the patches directory contained on the media and an optional list of exclusive products the patches apply to.
If this file is not present, the media's root directory is assumed and no restrictions about the products are made.

The first line of the file starts with the directory name (relative to the media's root dir!), followed by whitespace (space or tab) followed by an optional comment with the description/patchlevel of the Patch CD.
A leading slash in the directory name is only needed to specify the root directory of the media.

Additional lines are used to specify exclusive products. If no additional lines are present, no exclusive products are assumed. If there are exclusive products the online or patch CD update ignores all products on the installed system which are not contained in the list of exclusive products. If there are no exclusive products all products on the installed system are used for the update.

The exclusive products are listed as one product per line in the form of the product name and the product version separated by a dash.

Proposal:

Example

linux# cat /mnt/media.1/patches
/ Patch-CD SuSE-SLES 7 (i386) Patchlevel 4
linux# cat /mnt2/media.1/patches
patches Patch-CD SuSE-SLOX 4 (i386) Patchlevel 1
SUSE CORE-9

The package description directory

Each such directory contains a file listing the selections (selections) and a file listing the packages (packages).

Example

linux# grep Enterprise /mnt/media.1/products
sles   SuSE Linux Enterprise Server
linux# grep DESCRDIR /mnt/sles/content
DESCRDIR suse/setup/descr
linux# ls -R /mnt/sles/suse/setup/descr
...
packages
selections
...
linux#

The packages file

This is basically a cache file for package data needed for package selection and dependency resolution.
See current [package-descr.html here] for the syntax.

The packages file must exist in order to enable a media.

The package file contains pure package / rpm data and no user readable string (i.e. translations).

The packages.LANG file

For each language defined in content:LINGUAS a packages.LANG file exists in the content:DESCRDIR directory.
This file contains translated strings (i.e. package summary, description, etc.) to be viewed by the user.

The packages.LANG file might be ommitted. The package summary defaults to name-version-release.architecture in this case.

See [lang-descr.html here] for a format definition of such a file.

The packages.DU file

This file contains disk usage information for each package and directory used by the package.
It it used to approximate file system requirements esp. when multiple partitions (i.e. for /usr, /var, /opt, ...) are used.
Exact usage information can't be computed by YaST since it heavily depends on hard or symbolic links (either in the package or in the file system) and the filesystem in use (i.e. ext2 vs. reiserfs).

See [du-descr.html here] for a format definition of this file.

(N.B. The .DU suffix does not interfere with the .LANG suffix since the language suffix starts with lower case letters.)

The packages.DU file might be ommitted. No size estimations can be given in this case.

Example

linux# grep Enterprise /mnt/media.1/products
sles   SuSE Linux Enterprise Server
linux# grep DATADIR /mnt/sles/content
DATADIR suse
linux# grep ^ARCH /mnt/sles/content
ARCH.x86_64 x86-64 i686 i586 i486 noarch
ARCH.i586 i586 i486 noarch
linux# ls -R /mnt/sles/suse
...
x86-64/
i686/
i586/
i486/
noarch/
...
linux#

The selections file

This file contains a list of selections file names (one per line, possibly with directory pathes, relative to the DESCRDIR directory).
See current *.sel for the syntax. (To be defined).

The selections file might be ommitted. YaST tries to access *.sel files in the DESCRDIR directory in this case.

Example

linux# cat /mnt/suse/setup/descr/selections
Games.sel
Gnome.sel
Kde-Desktop.sel
Kde.sel
LAMP.sel
Linux-Devel.sel
Minimal.sel
Multimedia.sel
Network.sel
Office.sel
Standard.sel
SuSE-Documentation.sel
X11.sel
default.sel
linux#

Reading directories

When YaST reads a directory by first listing its content, it looks for a file directory.yast and takes its content as directory listing, if it exists. If it doesn't exist, it tries to list the directory by using the media backend. Listing directories isn't supported by all backends, e.g. the HTTP backend doesn't support directory listings. So directories which are required to be listable by YaST for all media have to include the directory.yast file.

The file can be created by ls >directory.yast. YaST ignores the directory.yast entry itself and the . and .. entries.