Chapter 2. The Control File

Contents

2.1. Introduction
2.2. Format
2.3. Structure
2.4. RELAX NG—A Schema Language for XML

2.1. Introduction

The control file is in most cases a configuration description for a single system. It consists of sets of resources with properties including support for complex structures such as lists, records, trees and large embedded or referenced objects.

2.2. Format

The XML configuration format provides a consistent file structure, which is easier to learn and remember when attempting to configure a new system.

The AutoYaST2 control file uses XML to describe the system installation and configuration. XML is a commonly used mark up and many users are familiar with the concepts of the language and the tools used to process XML files. If you edit an existing control file or create a control file using an editor from scratch, it is strongly recommended to validate the control file using a validating XML parser.

The following example shows a control file in XML format:

Example 2.1. XML Control File (Profile)

<?xml version="1.0"?>
<!DOCTYPE profile>
 <profile
 xmlns="http://www.suse.com/1.0/yast2ns"
 xmlns:config="http://www.suse.com/1.0/configns">
   <partitioning  config:type="list">
      <drive>
         <device>/dev/hda</device>
         <partitions config:type="list">
           <partition>
              <filesystem config:type="symbol">ext2</filesystem>
              <size>520Mb</size>
              <mount>/</mount>
           </partition>
           <partition>
              <filesystem config:type="symbol">reiser</filesystem>
              <size>1200Mb</size>
              <mount>/data</mount>
           </partition>
         </partitions>
      </drive>
   </partitioning>
   <scripts>
    <pre-scripts>
     <script> 
        <interpreter>shell</interpreter>
	<filename>start.sh</filename>
         <source>

            <![CDATA[
#!/bin/sh 
echo "Starting installation" 
exit 0

]]>

         </source>
     </script>  
    </pre-scripts>
   </scripts>
</profile>

2.3. Structure

Below is an example of a basic control file container, the actual content of which is explained later on in this chapter.

Example 2.2. Control file container

<?xml version="1.0"?>
<!DOCTYPE profile>
 <profile
 xmlns="http://www.suse.com/1.0/yast2ns"
 xmlns:config="http://www.suse.com/1.0/configns">
 
<!-- RESOURCES -->

</profile>

The profile element (root node) contains one or more distinct resource elements. The permissible resource elements are specified in the schema files

2.3.1. Resources and Properties

A resource element either contains multiple and distinct property and resource elements, or multiple instances of the same resource element, or it is empty. The permissible content of a resource element is specified in the schema files.

A property element is either empty or contains a literal value. The permissible property elements and values in each resource element are specified in the schema files

An element can be either a container of other elements (a resource) or it has a literal value (a property); it can never be both. This restriction is specified in the schema files. A configuration component with more than one value must either be represented as some kind of embedded list in a property value or as a nested resource.

2.3.2. Nested Resources

Nested resource elements allow a tree-like structure of configuration components to be built to any level.

Example 2.3. Nested Resources

...
<drive> 
  <device>/dev/hda</device> 
  <partitions> <!-- this is wrong, explanation below -->
     <partition>
        <size>1000mb</size> 
        <mount>/</mount> 
     </partition> 
     <partition> 
        <size>250mb</size> 
        <mount>/tmp</mount> 
     </partition> 
  </partitions> 
</drive>
....

In the example above the disk resource consists of a device property and a partitions resource. The partitions resource contains multiple instances of the partition resource. Each partition resource contains a size and mount property.

The XML schema defines the partitions element as a resource supporting one or multiple partition element children. If only one partition resource is specified it is important to use the "config:type" attribute of the partitions element to indicate that the content is a resource, in this case a list. Using the partitions element with out specifying the type in this case will result in undefined behavior as YaST2 will improperly interpret the partitions resource as a property. The example below illustrates this use case.

Example 2.4. Nested Resources with Type Attributes

...
<drive> 
  <device>/dev/hda</device> 
  <partitions config:type="list"> 
     <partition> 
        <size>1000</size> 
        <mount>/</mount> 
     </partition> 
     <partition> 
        <size>250</size> 
        <mount>/tmp</mount> 
     </partition> 
  </partitions> 
</drive>
....

2.3.3. Attributes

Global profile attributes are used to define meta-data on resources and properties. Attributes are used to define context switching. They are also used for naming and typing properties as shown in the previous sections. Profile attributes are in a separate namespace so they do not have to be treated as reserved words in the default namespace. New ones can then be added without having to potentially alter existing profiles.

Profile attributes are defined in the configuration namespace and must always be prefixed with config: . All profile attributes are optional. Most can be used with both resource and property elements but some can only be used with one type of element which is specified in the schema files.

The type of an element is defined using the config:type attribute. The type of a resource element is always RESOURCE, although this can also be made explicit with this attribute (to ensure correct identification of an empty element, for example, when there is no schema file to refer to). A resource element cannot be any other type and this restriction is specified in the schema file. The type of a property element determines the interpretation of its literal value. The type of a property element defaults to STRING, as specified in the schema file. The full set of permissible types is specified in the schema file.

2.4. RELAX NG—A Schema Language for XML

2.4.1. Introduction

A RELAX NG schema specifies a pattern for the structure and content of an XML document. A RELAX NG schema thus identifies a class of XML documents consisting of those documents that match the pattern. A RELAX NG schema is itself an XML document.

Verfify your AutoYaST XML file

xmllint --noout \
--relaxng /usr/share/YaST2/schema/autoyast/rng/profile.rng \
myAutoYaSTProfile.xml

openSUSE AutoYaST 12.2