Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
AutoYaST Guide / Understanding and creating the AutoYaST control file / The AutoYaST control file
Applies to openSUSE Leap 15.4

2 The AutoYaST control file

2.1 Introduction

A control file, also known as a profile, is 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.

Important
Important: Control files from OS releases older than SLES 12 GA and openSUSE 42.0 are incompatible

Many major changes were introduced with SLES 12 and openSUSE Leap 42.0, such as the switch to systemd and GRUB 2. These changes also required fundamental changes in AutoYaST Therefore you cannot use AutoYaST control files created on SLES 11 to install openSUSE Leap 15.4, and vice versa.

2.2 Format

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

The AutoYaST control file uses XML to describe the system installation and configuration. XML is a commonly used markup, 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 new control file, it is strongly recommended to validate the control file. This can be done using a validating XML parser such as xmllint or jing, for example (see Section 3.3, “Creating/editing a control file manually”).

The following example shows a control file in XML format:

Example 2.1: AutoYaST 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/sda</device>
      <partitions config:type="list">
        <partition>
          <filesystem config:type="symbol">btrfs</filesystem>
          <size>10G</size>
          <mount>/</mount>
        </partition>
        <partition>
          <filesystem config:type="symbol">xfs</filesystem>
          <size>120G</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 an embedded list in a property value or as a nested resource.

An empty element, such as <foo></foo> or <bar/>, will not be in the parsed data model. Usually this is interpreted as wanting a sensible default value. In cases where you need an explicitly empty string instead, use a CDATA section: <foo><![CDATA[]]></foo>.

2.3.2 Nested resources

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

There are two kinds of nested resources: maps and lists. Maps, also known as associative arrays, hashes, or dictionaries, contain mixed contents, identified by their tag names. Lists, or arrays, have all items of the same type.

Example 2.3: Nested resources
...
<drive>
  <device>/dev/sda</device>
  <partitions config:type="list">
     <partition>
        <size>10G</size>
        <mount>/</mount>
     </partition>
     <partition>
        <size>1G</size>
        <mount>/tmp</mount>
     </partition>
  </partitions>
</drive>
....

In the example above, the drive resource is a map consisting of a device property and a partitions resource. The partitions resource is a list containing multiple instances of the partition resource. Each partition resource is a map containing a size and mount property.

The default type of a nested resource is map, although you can specify it as you want. Lists must be marked as such using the config:type="list" attribute.

Tip
Tip: Using sorter type annotations

Starting with openSUSE Leap 15.3, it is possible to use the attribute t instead of config:type to specify the element type.

<mode t="boolean">true</mode>

2.3.3 Attributes

Global attributes are used to define metadata 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. Attributes are in a separate namespace so they do not need to be treated as reserved words in the default namespace.

The config:type attribute determines the type of the resource or property in the parsed data model. For resources, lists need a list type whereas a map is the default type that does not need an attribute. There is one exception. When the map is empty, it needs to be marked as a map so it does not get confused with a simple string value.

Example 2.4: An empty map
<general t="map" />

For properties, boolean, symbol, and integer can be used, the default being a string.

Except for map and string values, as explained before, attributes are not optional. It may appear that attributes are optional, because various parts of the schema are not very consistent in their usage of data types. In some places an enumeration is represented by a symbol, elsewhere a string is required. One resource needs config:type="integer", another will parse the number from a string property. Some resources use config:type="boolean", others want yes or even 1. If in doubt, consult the schema file.