Novell Documentation: Novell Linux Point of Service

9.2 xscr Image Building Components

xscr builds images using the Image Description Tree, an Image Specification Document (ImageSpecification.xml), and a Distribution Source Document (Distribution.xml). The Image Specification and Distribution Source Documents contain XML elements that define the structure, configuration files, and other components required to build client images for Point of Service systems.

The XML-based Image Specification and Distribution Source Documents provide significant advantages in image design and manageability:

You can manage image subcomponents as discrete elements. Image drivers, RPMs, and even features can be separately managed within the Image Specification Document. This allows you to easily add features, RPMs, and drivers to an image.
You can define global settings in the parent Image Specification Document to customize the implementation of image subcomponents. For example, in the parent document, you can choose to include or exclude specific drivers or RPMs.

This granular level of control is made possible by the structure of the Novell Linux Point of Service XML schema. The Novell Linux Point of Service XML schema organizes the template components in discrete elements so they can be individually managed.

The following sections review the image components required to build images with xscr:

9.2.1 Image Description Tree

xscr builds images using a specific file system directory structure known as the Image Description Tree. The Image Description Tree provides the XML documents, scripts, configuration files, and other components required to build client images for Point of Service systems.

NOTE:xscr uses the Image Specification (ImageSpecification.xml) and Distribution Source (Distribution.xml) documents in place of the IMAGE, VERSION, config, setup, and setup.user files used by scr to generate a client image.

Table 9-2 summarizes the Image Description Tree components required to build images with xscr.

Table 9-2 Image Description Tree components for xscr

Component	Description
/opt/SLES/POS/system/image_name-version/files/	A subdirectory that contains special files, directories, and scripts, This function of this directory is to ensure that the RPM is used as the package manager before any packages are installed in the image. The entire directory is copied to the root of the image tree using `cp -a`. This directory cannot contain any libraries or binary files. Any binaries and libraries required before the first RPM call must be extracted from the corresponding packages in advance.
/opt/SLES/POS/system/image_name-version/files-user/	A subdirectory that contains special files, directories, and scripts for adapting the image environment after the installation of all the image packages.
/opt/SLES/POS/system/image_name-version/package/	A subdirectory where ImageBuilder searches for RPM packages. The directory is automatically initialized depending on the entries in the Distribution Source file, Distribution.xml. For more information, see Section 9.2.3, Distribution Source Document (Distribution.xml). If there is no package directory, ImageBuilder creates a link to the global package directory (/opt/SLES/POS/pac/) and the links designated in the AdminServer.conf file.
/opt/SLES/POS/system/image_name-version/script/	A subdirectory that contains Bash scripts that are called after a package is installed, primarily to remove the parts of a package that are not needed for the Point of Service system. IMPORTANT:For these scripts to run, the script name must match the name of the RPM (without the version).
/opt/SLES/POS/system.image_name-version/config.cleanup	An optional configuration script for the image. This script is called at the end of the installation and after all the installation scripts have run. It is designed to clean up the image system. The target programs and files are those needed only while the installation scripts are running.
/opt/SLES/POS/system.image_name-version/config.system	An optional configuration script for the image. This script is called at the end of the installation but before the installation scripts have run. It is designed to configure the image system, such as the activation or deactivation of certain services (insserv). The call is not made until after the switch to the image has been made with chroot. IMPORTANT:This file is pre-defined to provide the scripts required to install the image. Do not modify this file.
/opt/SLES/POS/system/image_name-version/setup.txt	An optional information file for the LDAP system. This file contains information regarding which configuration files are required by the image and whether they are hardware or system-dependent. The structure of the file is as follows: flag : configuration_file_name The following values can be set for the flag value: SYS specifies that the configuration file is hardware-independent, such as /etc/ntp.conf. HWD specifies that the configuration file is hardware-dependent, such as /etc/X11/XF86Config. The configuration_file_name includes the full file path.

9.2.2 Image Specification Documents

Image Specification Documents contain XML elements that define the structure, configuration, and other components required to build client images for Point of Service systems. In general, a master Image Specification Document (or parent document) defines general image parameters and individual image subcomponents such as add-on features, custom applications, and so forth are defined in sub-documents referred to as child documents.

Novell Linux Point of Services allows you to nest multiple child documents within a parent Image Specification Document. These child documents can be located anywhere and can be given any filename. The parent Image Specification Document must be named ImageSpecification.xml and must be located at the root of the Image Description Tree (/opt/SLES/POS/system/image_name-version).

NOTE:Client Image Specification Documents can be defined in an XML editor or in a standard text editor. XML editors provide the advantage of a graphical user interface. Typically, XML elements are presented as graphical objects and are visually organized in the schema hierarchy. Element attributes are defined as fields within the element objects. After the XML template is defined, the template can be saved as a standard XML document. The graphics in the following sections were taken in an XML editor. They show XML schema in a graphical format.

Novell Linux client Image Specification Documents can also be defined in a standard text editor. Text-based XML documents are more complicated because the schema hierarchy and element attributes are defined through the document syntax and organization. The sample XML documents in Section C.0, Sample Files are presented in text format.

Figure 9-1 represents the root elements in the Novell Linux Point of Service XML schema.

Figure 9-1 Novell Linux Point of Service XML root elements

Table 9-3 summarizes the root elements in the XML Image Specification schema.

Table 9-3 Image Specification root elements

Root Element	Description
ImageSpecification	Defines general image settings such as image name, version, time zone, and so forth. The ImageSpecification settings in parent documents take precedence over settings in child documents.
IncludeSpecificationList	Identifies the child Image Specification Documents to include when generating the parent document in ImageBuilder.
Required List	Identifies the Image Specification Documents required to build the image.
DriverSpecifications	Identifies the USB, network, and general drivers to include or exclude from the image. DriverSpecifications settings in parent documents take precedence over child documents. That means the parent document can exclude any item that is in the include list of a child document or conversely, the parent document can include any item that is in the exclude list of a child document.
ConfigSpecifications	This element is not currently implemented. These configuration specifications must be defined through the config.system, and setup.txt files in the Image Description Tree. For more information, see Section 9.2.1, Image Description Tree.
RPMSpecifications	Identifies the RPMs to include or exclude from the image. RPMSpecifications settings in parent documents take precedence over child documents. That means the parent document can exclude any item that is in the include list of a child document or conversely, the parent document can include any item that is in the exclude list of a child document.
UserGroupSpecifications	Defines the users and groups to create within the image. The UserGroupSpecifications settings in the parent document take precedence over settings in child documents.
Description	Provides a general description of the client image. This element is only read in the root Image Specification Document (ImageSpecification.xml); it is ignored in all child documents.

The following sections provide detailed information on the Novell Linux Point of Service XML root elements and their sub-elements.

ImageSpecification

The ImageSpecification element defines general image settings such as image name, version and time zone. The ImageSpecification settings in parent documents take precedence over settings in child documents.

Table 9-4 summarizes the attributes in the ImageSpecification element.

Table 9-4 ImageSpecification element attributes

	Attribute	Description
	ImageName=”image_name”	Image_name indicates the name of the image. When the image is generated, the image_name is automatically expanded to include the version number and the date. The version number is extracted from the ImageVersion attribute. xscr replaces the image_name with the name specified on the command line when you clone the Image Description Tree. IMPORTANT:You cannot use the word “boot” in any image name other than the cdboot and disknetboot images. This attribute is required in the parent ImageSpecification.xml document; it is optional in a child ImageSpecification.xml document.
	SchemaVersion=”version”	The XML schema version for the current Image Specification Document. The current version is “1.” This attribute is required.
	SchemaRevision=”revision”	The XML schema revision number for the current Image Specification Document.The current revision is “1.” This attribute is required.
	ImageType=”diskful\|diskless”	The value for this parameter is either diskful or diskless. If diskful is set, all the packages required to handle the image on a hard disk are included in the setup description. If diskless is set, all unnecessary packages are removed from the setup description. This attribute is optional for the DiskNetboot image. However, for all other images, you must define the ImageType as diskful or diskless.
	ImageVersion=”version”	The version number of the image generated from the current Image Specification Document. xscr replaces the version with the version specified on the command line when you clone the Image Description Tree. This attribute is required in the parent ImageSpecification.xml document; it is optional in a child ImageSpecification.xml document.
	AddOnSize=”Image_size “	The size that is added to the final image size. Image_size is defined as a number followed by M (megabyte) or G (gigabyte). If you specify a value of “1 M,” xscr adds 1 MB to the final image size. This attribute is optional.
	Type=”ext2\|ext3”	The image type is currently restricted to ext2 or ext3, although, if necessary, different formats are possible. NOTE:If you have an existing ext2 image, you can change the file system by setting a flag in the scCashRegister or the scWorkstation objects rather than recreate the image. If ext3 is specified in either LDAP object, the Point of Service terminal extends the file system to ext3 when the image is deployed. This attribute is required in the parent ImageSpecification.xml document; it is optional in a child ImageSpecification.xml document.
	Timezone=”time_zone”	All time zone definitions are located in the /usr/share/zoneinfo directory. To specify which time zone you want to use in the image, enter the relative path to a specific time zone definition. For example, timezone-”US/Mountain.” The ImageBuilder uses this information to extract the corresponding time zone from the timezone package. The time zone value is then stored as /etc/localtime in the image. This attribute is optional for the DiskNetboot image. However, we recommend that you define the Timezone attribute for all other images.
	Locale=”locale_names”	Contains a comma-separated list of valid locale names. Novell Linux Point of Service provides support for the following locales: de_DE (German) es_ES (Spanish) fr_FR (French) it_IT (Italian) ja_JP (Japanese) ko_KR (Korean) pt_PT (Portuguese) zh_CN (Simplified Chinese) zh_TW (Traditional Chinese) IMPORTANT:In addition to designating the image locale, you must add the child Image Specification Documents required to provide the language files for each image feature. For more information, see Changing the Image Language. This attribute is optional for the DiskNetboot image. However, it is recommended that you define the Locale attribute for all other images.
	Keytable=”console_keymap”	Contains the name of the console keymap to use. The name corresponds to a map file stored below the path /usr/share/kbd/keymaps; for example, keytable=”us.map.gz”. Additionally, the KEYTABLE variable within the /etc/sysconfig/keyboard file is set according to the keyboard mapping. This attribute is optional for the DiskNetboot image. However, we recommend that you define the Keytable attribute for all other images.

IncludeSpecificationList

Novell Linux Point of Services allows you to nest multiple child Image Specification Documents within a parent document. These child documents can be located anywhere and can be given any filename.

The ImageSpecificationList element identifies the child Image Specification Documents to include when generating the parent document in ImageBuilder.

Figure 9-2 represents the IncludeSpecificationList elements.

Figure 9-2 IncludeSpecificationList elements

Table 9-5 summarizes the sub-elements and attributes in the IncludeSpecificationList element.

Table 9-5 IncludeSpecificationList element attributes

Sub-Element	Attribute	Description
IncludeSpecification	URI	The URI of a child document to include with the current Image Specification Document. NOTE:Currently, xscr only supports local URIs (FILE:///). When ImageBuilder generates ImageSpecification.xml, it also processes the child Image Specification Documents and includes them as part of the image. This attribute is required.

Sub-Element

Attribute

Description

IncludeSpecification

URI

The URI of a child document to include with the current Image Specification Document.

NOTE:Currently, xscr only supports local URIs (FILE:///).

When ImageBuilder generates ImageSpecification.xml, it also processes the child Image Specification Documents and includes them as part of the image.

This attribute is required.

For information on using the IncludeSpecificationList element to add features to a client image, see Adding Features to Client Images.

RequiredList

The RequiredList element identifies image dependencies for client add-on features. If an add-on image requires a specific parent document, the dependency is expressed in the RequiredList element. For example, the Firefox add-on feature requires the browser.xml Image Specification document; therefore, this feature can be added only to the Browser or Desktop client images.

Figure 9-3 represents the sub-elements and attributes in the RequiredList element:

Figure 9-3 RequiredList elements

Table 9-6 summarizes the sub-elements and attributes in the RequiredList element.

Table 9-6 RequiredList sub-elements and attributes

Sub-Element					Attribute	Description
	Require				URI	A URI that identifies where the required Image Specification Documents are located. NOTE:Currently, xscr only supports FILE:///. IMPORTANT:All Image Specification Documents listed in each child document's RequiredList element must exist in the parent Image Specification Document for xscr to build the image. If one of the required documents is not present, xscr returns the following error: `Dependency check failed on image_name.xml.`

DriverSpecifications

The DriverSpecifications element identifies the USB, network, and general drivers to include or exclude from the image. DriverSpecifications settings in parent documents take precedence over child documents. That means the parent document can exclude any item that is in the include list of a child document or conversely, the parent document can include any item that is in the exclude list of a child document.

NOTE:Include settings in parent documents take precedence over child documents; that is, the parent document can include any item that is in the exclude list of a child document.

Similarly, exclude settings in parent documents take precedence over child documents; that is, the parent document can exclude any item that is in the include list of a child document.

Figure 9-4 represents the sub-elements and attributes in the DriverSpecifications element:

Figure 9-4 DriverSpecifications elements

Table 9-7 summarizes the sub-elements and attributes in the DriverSpecifications element.

Table 9-7 DriverSpecifications element attributes

Sub-Element				Attribute	Description
DriverIncludeList					The list of USB, network, and general drivers to include in the image.
	DriverSet				A set of drivers that are located in a single path. Ideally, you should define separate DriverSets for your USB, network, and general drivers. These must be in the kernel RPM.
		ExplicitPath		URI	A URI that identifies where the drivers in the DriverList element are located. NOTE:Currently, xscr only supports FILE:///. This attribute is required.
		DriverList			The list of drivers to include in the image.
			Driver	Name	A text string that identifies the driver filename to include in the image. The driver name is indicated relative to the ExplicitPath. For example, input/mousedev.ko This attribute is required.
DriverExcludeList					The list of USB, network, and general drivers to exclude from the image. This element allows you to exclude drivers included in child documents.
	Driver			Name	A text string that identifies the driver filename to exclude from the image. If the name includes a full path, ImageBuilder excludes only that particular driver. If the name is just a filename, ImageBuilder excludes all drivers with that filename from the image. This attribute is required.

For information on adding or excluding drivers from a client image, see Adding Drivers.

RPMSpecifications

The RPMSpecifications element identifies the RPMs to include or exclude from the image.RPMSpecifications settings in parent documents take precedence over child documents. That means the parent document can exclude any item that is in the include list of a child document or conversely, the parent document can include any item that is in the exclude list of a child document.

NOTE:Include settings in parent documents take precedence over child documents; that is, the parent document can include any item that is in the exclude list of a child document.

Similarly, exclude settings in parent documents take precedence over child documents; that is, the parent document can exclude any item that is in the include list of a child document.

Figure 9-5 represents the sub-elements and attributes in the RPMSpecifications element.

Figure 9-5 RPMSpecifications elements

Table 9-8 summarizes the sub-elements and attributes in the RPMSpecifications element.

Table 9-8 RPMSpecifications element attributes

Sub-Element					Attribute	Description
RPMIncludeList						The list of the RPMs to include in the image.
	RPMSet					A set of RPMs that are located in a single path. A separate RPMSet element must be defined for each ExplicitPath.
		ExplicitPath			URI	A URI that identifies where the RPMs in the RPMList element are located. If the value is “x,” ImageBuilder searches all the paths specified in the Distribution.xml file. This attribute is required.
		RPM List				The list of RPMs to include in the image.
			RPM		Name	A text string that identifies the RPM filename to include in the image. The RPM name is indicated relative to the ExplicitPath. The Name attribute should specify the RPM name as defined by the following command: `rpm -qp --qf “%{name}” filename.rpm` This attribute is required.
					Version	The version of the RPM to include in the image. If the value is “x,” ImageBuilder includes the latest RPM in the image. This attribute is optional.
				InstallOption	Option	A command option that defines installation parameters for RPMs in the current RPM list. The available install options are as follows: `--excludedocs` Do not install documentation. `--includedocs` Install documentation. `--replacepkgs` Replace a package with a new copy of itself. `--replacefiles` Replace files owned by another package. `--force` : Ignore package and file conflicts. `--noscripts` Do not execute pre- and postinstall scripts. `--ignorearch` Do not verify package architecture. `--ignoreos` : Do not verify package operating system. `--nodeps` Do not check dependencies. `--nosignature` Do not verify package or header signature. This attribute is required.
RPMExcludeList						The list of RPMs to exclude from the image. This element allows you to exclude RPMs included in child documents.
	RPM				Name	A text string that identifies the RPM filename to exclude from the image. If the name includes a full path, ImageBuilder excludes only that particular RPM. If the name is just a filename, ImageBuilder excludes all RPMs with that filename from the image. This attribute is required.
					Version	The version of the RPM to exclude from the image. If the value is “all,” ImageBuilder excludes all versions of the RPM from the image. This attribute is optional.
DistributionSource					URI	A URI that identifies where the Distribution.xml file is located. The Distribution.xml template is located in /opt/SLES/POS/system/templates/. For more information, see Section 9.2.3, Distribution Source Document (Distribution.xml). This attribute is required.
					ImageClass	The type of image generated from the current Image Specification Document. The available image classes are NLD and SLES. In general, most Point of Service images are created using the NLD image class. The only images that require the SLES image class are POSBranch images. IMPORTANT:The ImageClass element must match the ImageClass definition in the Distribution Source Document.

For information on adding or excluding RPMs from a client image, see Adding RPMs.

UserGroupSpecifications

The UserGroupSpecifications element defines the users and groups that are created within the image. (For more information on standard templates setup.user files, see Section 8.2.1, Image Description Tree.) All users and groups that will be logging into the Point of Service terminals configured by the current image can be pre-defined within the image.

The UserGroupSpecifications settings in the parent document take precedence over settings in child documents.

Figure 9-6 represents the sub-elements and attributes in the UserGroupSpecifications element.

Figure 9-6 UserGroupSpecifications elements

Table 9-9 summarizes the sub-elements and attributes in the UserGroupSpecifications element.

Table 9-9 UserGroupSpecifications element attributes

Element		Attribute	Description
UserList			The user accounts created on Point of Service terminals configured by images generated from the current Image Specification Document.
	User	Name	A text string that specifies the user account to create in the image. This attribute is required.
		EncryptedPassword	A text string that specifies the encrypted password for the user account. IMPORTANT:This value must be the encrypted password. You must use an encryption utility to encrypt the user account password before it can be entered as the value for this attribute. This attribute is optional.
		HasPassword	A Boolean value (true/false) that indicates if the user has a password. This attribute is required.
		UserID	A text string that specifies a unique user ID. This value must be unique within the root Image Specification Document and its children. This attribute is required.
		HomeDirectory	A text string that identifies the user's home directory. This attribute is optional.
		Main Group	A text string that identifies the main group the user belongs to. This attribute is optional.
		Disable	A Boolean value (true/false) that disables access to the user account. The default value is false.
	GroupAssociation	Name	A text string that specifies the names of groups this user belongs to. This attribute is required.
GroupList			The Linux user groups created on Point of Service terminals configured by images generated from the current Image Specification Document.
	Group	Name	A text string that specifies the user account to create in the image. This attribute is required.
		GroupID	A text string that specifies a unique group ID. This value must be unique within the root Image Specification Document and its children. This attribute is required.
RootSettings		DisableRootAccess	A Boolean value (true/false) that disables the Root account. This attribute is optional.
		EncryptedRootPassword	A text string that specifies the encrypted password for the Root account. IMPORTANT:This value must be the encrypted password. You must use an encryption utility to encrypt the Root account password before it can be entered as the value for this attribute. This attribute is only valid if the Root account is enabled. This attribute is optional.

For information on using the UserGroupSpecifications element to manage users, groups, and the Root account in a client image, see Managing Users and Groups within an Image.

Sample ImageSpecification.xml Documents

To view examples of Image Specification Documents, see the following:

9.2.3 Distribution Source Document (Distribution.xml)

When xscr generates an image, it searches the paths listed in the Distribution Source Document to find the RPM packages required to create the image. The Distribution Source Document, Distribution.xml, defines the paths to the distribution directories where you have copied the Novell Linux Point of Service CDs.

The Distribution.xml document also references the maintenance directory. The maintenance directory is essentially an “override” directory. RPMs located in this directory take precedence over RPMs located in the distribution directories. You can add any RPM to this directory that you want xscr to use in lieu of the default RPMs in the distribution directories. By default, the maintenance directory contains the glibc and devs RPMs. For a detailed breakdown of the maintenance directory structure, see Section B.2, Branch Server Directory Structure.

By default, the Distribution.xml document is located in /opt/SLES/POS/system/templates/ . The location of the Distribution.xml document must be defined in the DistributionSource attribute in the Image Specification Document.

The posCDTool is used to generate the Distribution Source Document. For more information, see Section 7.3.4, Generating AdminServer.conf or Distribution.xml.

The Distribution Source Document defined in the parent document takes precedence over Distribution Source Documents referenced in child documents.

NOTE:Novell Linux Point of Service Distribution Source Documents can be defined in an XML editor or in a standard text editor. XML editors provide the advantage of a graphical user interface. Typically, XML elements are presented as graphical objects and are visually organized in the schema hierarchy. Element attributes are defined as fields within the element objects. After the XML template is defined, the template can be saved as a standard XML document. The graphics in this section were taken in an XML editor. They show XML schema in a graphical format.

Distribution Source Documents can also be defined as XML documents in standard text format. These documents are more complicated because the schema hierarchy and element attributes are defined through the document syntax and organization. The XML documents in Section C.0, Sample Files are presented in text format.

Figure 9-7 represents the sub-elements and attributes in the Distribution.xml document.

Figure 9-7 Distribution.xml document elements and attributes

Table 9-10 summarizes the sub-elements and attributes in the Distribution.xml document.

Table 9-10 Distribution.xml element attributes

Element				Attribute	Description
Distribution				SchemaVersion=”version”	The XML schema version for the current Image Specification Document. The current version is “1.” This attribute is required.
				SchemaRevision=”revision”	The XML schema revision number for the current Image Specification Document. The current revision is “1.” This attribute is required.
	ImageClass			Name	The type of image generated from Image Specification Documents that reference this Distribution Source Document. The default image classes are NLD and SLES. The NLD ImageClass generates client images. The SLES ImageClass generates POSBranch images. IMPORTANT:This ImageClass element must match the ImageClass definition in the RPMSpecifications element in all associated Image Specification Documents.
		Kernel		Name	The name of the kernel required for the image. The kernel name for Novell Linux Point of Service 9 images is kernel-SLRS.
				Version	The version of the kernel required for the image.
				Path	The absolute path to the kernel required for the image.
		SourceList			A list of URIs to the media where RPMs required to generate the image are located. This element enables multiple images to share a single Distribution Source Document.
			Source	URI	A URI to the media where RPMs required to generate the image are located.
				Order	Any positive number, zero or higher. This value indicates the search order for the current URI. When ImageBuilder generates the image, it searches each URI in their designated order for RPMs listed in the RPMIncludeList element.

Sample Distribution.xml Documents

To view examples of Distribution Source Documents, see the following: