Chapter 6. Rules and Classes

Contents

6.1. Rules-based Automatic Installation
6.2. Classes
6.3. Mixing Rules and Classes
6.4. The Merging of Rules and Classes

6.1. Rules-based Automatic Installation

Rules offer the possibility to configure a system depending on system attributes by merging multiple control files during installation. The rules-based installation is controlled by a rules file.

The rules file is an XML file containing rules for each group of systems (or single systems) that you want to automatically install. A set of rules distinguish a group of systems based on one or more system attributes. After passing all rules, each group of systems is linked to a profile. Both the rules file and the profiles must be located in a pre-defined and accessible location.

The rules file is retrieved only if no specific control file is supplied using the autoyast keyword. For example, if the following is used, the rules file will not be evaluated:

autoyast=http://10.10.0.1/profile/myprofile.xml
autoyast=http://10.10.0.1/profile/rules/rules.xml

Instead use:

autoyast=http://10.10.0.1/profile/

which will load http://10.10.0.1/profile/rules/rules.xml (the slash at the end of the directory name is important).

Figure 6.1. Rules

Rules

If more than one rule applies, the final profile for each group is generated on the fly using a merge script. The merging process is based on the order of the rules and later rules override configuration data in earlier rules. Note that the names of the top sections in the merged xml files need to be in alphabetical order for the merge to succeed.

The use of a rules file is optional. If the rules file is not found, system installation proceeds in the classic way by only using the supplied profile or by searching for the profile depending on the MAC or the IP address of the system.

6.1.1. Rules File Explained

Example 6.1. Simple Rules File

The following simple example illustrates how the rules file is used to retrieve the configuration for a client with known hardware.

<?xml version="1.0"?>
<!DOCTYPE autoinstall>
<autoinstall xmlns="http://www.suse.com/1.0/yast2ns" xmlns:config="http://www.suse.com/1.0/configns">
  <rules config:type="list">
    <rule>
       <disksize>
            <match>/dev/hdc 1000</match>
            <match_type>greater</match_type>
       </disksize>
       <result>
            <profile>machine1.xml</profile>
            <continue config:type="boolean">false</continue>
        </result>
    </rule>
    <rule>
       <disksize>
            <match>/dev/hda 1000</match>
            <match_type>greater</match_type>
       </disksize>
       <result>
            <profile>machine2.xml</profile>
            <continue config:type="boolean">false</continue>
        </result>
    </rule>
  </rules>
</autoinstall>

The last example defines two rules and provides a different profile for every rule. The rule used in this case is disksize. After parsing the rules file, YaST attempts to match the target system with the rules in the rules.xml file. A rule match occurs when the target system matches all system attributes defined in the rule. As soon as the system matches a rule, the respective resource is added to the stack of profiles AutoYaST will use to create the final profile. The continue property tells AutoYaST whether it should continue with other rules after a match has been found.

If the first rule does not match, the next rule in the list is examined until a match is found.

Using the disksize attribute, you can provide different configurations for systems with hard drives of different sizes. The first rule checks if the device /dev/hdc is available and if it is greater than 1 GB in size using the match property.

A rule must have at least one attribute to be matched. If you need to check more attributes, i.e. memory or architectures, you can add more attributes in the rule resource as shown in the next example.

Example 6.2. Simple Rules File

The following example illustrates how the rules file is used to retrieve the configuration for a client with known hardware.

<?xml version="1.0"?>
<!DOCTYPE autoinstall> 
<autoinstall xmlns="http://www.suse.com/1.0/yast2ns" xmlns:config="http://www.suse.com/1.0/configns">
  <rules config:type="list">
    <rule>
       <disksize>
            <match>/dev/hdc 1000</match>
            <match_type>greater</match_type>
       </disksize>
       <memsize>	    
            <match>1000</match>
            <match_type>greater</match_type>
       </memsize>
       <result>
            <profile>machine1.xml</profile>
            <continue config:type="boolean">false</continue>
        </result>
    </rule>
    <rule>
       <disksize>
            <match>/dev/hda 1000</match>
            <match_type>greater</match_type>
       </disksize>
       <memsize>	    
            <match>256</match>
            <match_type>greater</match_type>
       </memsize>
       <result>
            <profile>machine2.xml</profile>
            <continue config:type="boolean">false</continue>
        </result>
    </rule>
  </rules>
</autoinstall>

The rules directory must be located in the same directory specified via the autoyast keyword at boot time. If the client was booted using autoyast=http://10.10.0.1/profiles/, AutoYaST will search for the rules file in http://10.10.0.1/profiles/rules/rules.xml.

6.1.2. Custom Rules

If the attributes AutoYaST provides for rules are not enough for your purposes, use custom rules. Custom rules are more or less a shell script you have to write. Its output to STDOUT specifies which AutoYaST profile should be used. STDERR will be ignored.

Here is an example for the use of custom rules:

<rule>
    <custom1>
        <script>
if grep -i intel /proc/cpuinfo > /dev/null; then
echo -n "intel"
else
echo -n "non_intel"
fi;
        </script>
        <match>*</match>
        <match_type>exact</match_type>
    </custom1>
    <result>
         <profile>@custom1@.xml</profile>
         <continue config:type="boolean">true</continue>
    </result>
</rule>

The script in this rule can echo either "intel" or "non_intel" to STDOUT (the output of the grep command must be directed to /dev/null in this case). The output of the rule script will be filled between the two '@' characters, to determine the filename of the profile to fetch. AutoYaST will read the output and fetch a file with the name "intel.xml" or "non_intel.xml". This file can contain the AutoYaST profile part for the software selection, for example, in case you want a different software selection on intel hardware than on others.

The number of custom rules is limited to five. So you can use custom1 to custom5.

6.1.3. Match Types for Rules

You can use five different match_types:

  • exact (default),

  • greater,

  • lower,

  • range,

  • regex (available since 10.1 and SLES10), a simple "=~" operator like in bash.

"greater" and "lower" can be used for memsize or totaldisk for example. They can match only with rules that return an integer value. A range is only possible for integer values too and has the form of "value1-value2", for example "512-1024". "regex" can be used to match substrings like "ntel" will match "Intel", "intel" and "intelligent".

6.1.4. Combine Attributes

Multiple attributes can be combined via a logical operator. It is possible to let a rule match if disksize is greater than 1GB or memsize is exactly 512MB.

You can do this with the "operator" element in the rules.xml file. Here is an example:

<rule>
   <disksize>
        <match>/dev/hda 1000</match>
        <match_type>greater</match_type>
   </disksize>
   <memsize>	    
        <match>256</match>
        <match_type>greater</match_type>
   </memsize>
   <result>
        <profile>machine2.xml</profile>
        <continue config:type="boolean">false</continue>
   </result>
   <operator>or</operator>
</rule>

Just "and" and "or" are possible operators and the default operator is "and".

6.1.5. Rules File Structure

The rules.xml file must:

  • have at least one rule,

  • have the name rules.xml,

  • be located in the directory rules in the profile repository,

  • and have at least one attribute to match in the rule.

6.1.6. Predefined System Attributes

The following table lists the predefined system attributes you can match in the rules file.

If you are unsure about a value on your system, start an auto-installation with "confirm" set to "true". When the proposal shows up, switch to the console via CTRL+ALT+F2 and run /usr/lib/YaST2/bin/y2base ayast_probe ncurses. The text box displaying the detected values can be scrolled.

Table 6.1. System Attributes

Attribute

Values

Description

hostaddress

IP address of the host

This attribute must always match exactly.

hostname

The name of the host

This attribute must always match exactly.

domain

Domain name of host

This attribute must always match exactly.

installed_product

The name of the product to be installed.

This attribute must always match exactly.

installed_product_version

The version of the product to be installed.

This attribute must always match exactly.

network

network address of host

This attribute must always match exactly.

mac

MAC address of host

This attribute must always match exactly. (MAC addresses should have the form 0080c8f6484c

linux

Number of installed Linux partitions on the system

This attribute can be 0 or more.

others

Number of installed non-Linux partitions on the system

This attribute can be 0 or more.

xserver

X Server needed for graphic adapter

This attribute must always match exactly.

memsize

Memory available on host in MByes

All match types are available.

totaldisk

Total disk space available on host in MBytes

All match types are available.

haspcmica

System has PCMCIA (i.e Laptops)

Exact match required, 1 for available PCMCIA or 0 for none.

hostid

Hex representation of IP address

Exact match required

arch

Architecture of host

Exact match required

karch

Kernel Architecture of host (i.e. SMP kernel, Athlon Kernel)

Exact match required

disksize

Drive device and size

All match types are available.

product

The hardware product name as specified in SMBIOS

Exact match required

product_vendor

The hardware vendor as specified in SMBIOS

Exact match required

board

The system board name as specified in SMBIOS

Exact match required

board_vendor

The system board vendor as specified in SMBIOS

Exact match required

custom1-5

Custom rules using shell scripts

All match types are available.


6.1.7. Rules with Dialogs

Since openSUSE 11.3 (not SLES11 SP1) you can use dialog popups with checkboxes to select rules you want matched.

The following elements must be between the <rules config:type="list"><rule><dialog> ... </dialog></rule></rules> tags in the rules.xml file.

Attribute

Values

Description

dialog_nr

All rules with the same dialog_nr are presented in the same popup dialog. The same dialog_nr can appear in multiple rules.

<dialog_nr config:type="integer">3</dialog_nr>

This element is optional and the default for a missing dialog_nr is always "0". If want to use one popup for all rules, you don't need to specify the dialog_nr.

element

Each element needs a unique id. Even if you have more than one dialog, you must not use the same id twice like an id "1" on dialog 1 and and id "1" on dialog 2. That's different than with <ask> dialogs, where you can have the same <element> id on multiple dialogs.

<element config:type="integer">3</element>

Optional. If left out, AutoYaST adds his own ids internally. Then you cannot specify conflicting rules (see below).

title

Caption of the popup dialog

<title>Desktop Selection</title>

Optional

question

Question shown in the popup behind the checkbox.

<question>KDE Desktop</question>

Optional. If you don't configure a text here, the name of the XML file that is triggered by this rule will be shown instead.

timeout

Timeout in seconds after which the dialog will automatically "press" the okay button. Useful for a non-blocking installation in combination with rules dialogs.

<timeout config:type="integer">30</timeout>

Optional. A missing timeout will stop the installation process until the dialog is confirmed by the user.

conflicts

A list of element ids (rules) that conflict with this rule. If this rule matches or is selected by the user, all conflicting rules are deselected and disabled in the popup. Take care that you do not create deadlocks.

<conflicts config:type="list">
  <element config:type="integer">1</element>
  <element config:type="integer">5</element>
  ...
</conflicts>

optional

Here is an example of how to use dialogs with rules:

<rules config:type="list">
    <rule>
        <custom1>
            <script>
echo -n 100
            </script>
           <match>100</match>
           <match_type>exact</match_type>
        </custom1>
        <result>
            <profile>rules/kde.xml</profile>
            <continue config:type="boolean">true</continue>
        </result>
        <dialog>
            <element config:type="integer">0</element>
            <question>KDE Desktop</question>
            <title>Desktop Selection</title>
            <conflicts config:type="list">
                <element config:type="integer">1</element>
            </conflicts>
            <dialog_nr config:type="integer">0</dialog_nr>
        </dialog>
    </rule>
    <rule>
        <custom1>
            <script>
echo -n 100
            </script>
           <match>101</match>
           <match_type>exact</match_type>
        </custom1>
        <result>
            <profile>rules/gnome.xml</profile>
            <continue config:type="boolean">true</continue>
        </result>
        <dialog>
            <element config:type="integer">1</element>
            <dialog_nr config:type="integer">0</dialog_nr>
            <question>Gnome Desktop</question>
            <conflicts config:type="list">
                <element config:type="integer">0</element>
            </conflicts>
        </dialog>
    </rule>
    <rule>
        <custom1>
            <script>
echo -n 100
            </script>
           <match>100</match>
           <match_type>exact</match_type>
        </custom1>
        <result>
            <profile>rules/all_the_rest.xml</profile>
            <continue config:type="boolean">false</continue>
        </result>
    </rule>
  </rules>

6.2. Classes

Classes represent configurations for groups of target systems. Unlike rules, classes have to be configured in the control file. Then classes can be assigned to target systems.

Here is an example of a class definition:

<classes config:type="list">
    <class>
        <class_name>TrainingRoom</class_name>
        <configuration>Software.xml</configuration>
    </class>
</classes>

The file Software.xml must be in the directory "classes/TrainingRoom/" then. It will get fetched from the same place the AutoYaST profile and rules were fetched from.

If you have multiple profiles and those profiles share parts, better use classes for common parts. You can also use XIncludes.

Using the configuration management system, you can define a set of classes. A class definition consists of the following variables:

  • Name: class name

  • Descriptions: class description

  • Order: order (or priority) of the class in the stack of migration

Figure 6.2. Defining Classes

Defining Classes

You can create as many classes as you need, however it is recommended to keep the set of classes as small as possible to keep the configuration system concise. For example, the following sets of classes can be used:

  • site: classes describing a physical location or site,

  • machine: classes describing a type of machine,

  • role: classes describing the function of the machine,

  • group: classes describing a department or a group within a site or a location.

A file saved in a class directory can have the same syntax and format as a regular control file but represents a subset of the configuration. For example, to create a new control file for a special computer with a specific network interface, only the control file resource which controls the configuration of the network is needed. Having multiple network types, you can merge the one needed for a special type of hardware with other class files and create a new control file which suits the system being installed.

6.3. Mixing Rules and Classes

It is possible to mix rules and classes during an auto-installation session. For example you can identify a system using rules which contain class definitions in them. The process is described in the figure Figure A.1, “Rules Retrieval Process”.

After retrieving the rules and merging them, the generated control file is parsed and checked for class definitions. If classes are defined, then the class files are retrieved from the original repository and a new merge process is initiated.

6.4. The Merging of Rules and Classes

With classes and with rules, multiple XML files get merged into one resulting XML file. This process of merging is often confusing for people, because it behaves different than one would expect. First of all it is important to note that the names of the top sections in the merged xml files need to be in alphabetical order for the merge to succeed.

For example, the following two XML parts should be merged:

<partitioning config:type="list">
    <drive>
        <partitions config:type="list">
            <partition>
                <filesystem config:type="symbol">swap</filesystem>
                <format config:type="boolean">true</format>
                <mount>swap</mount>
                <partition_id config:type="integer">130</partition_id>
                <size>2000mb</size>
            </partition>
            <partition>
                <filesystem config:type="symbol">xfs</filesystem>
                <partition_type>primary</partition_type>
                <size>4Gb</size>
                <mount>/data</mount>
            </partition>
        </partitions>
    </drive>
</partitioning>
<partitioning config:type="list">
  <drive>
    <initialize config:type="boolean">false</initialize>
    <partitions config:type="list">
         <partition>
           <format config:type="boolean">true</format>
           <filesystem config:type="symbol">xfs</filesystem>
           <mount>/</mount>
           <partition_id config:type="integer">131</partition_id>
           <partition_type>primary</partition_type>
           <size>max</size>
         </partition>
    </partitions>
    <use>all</use>
  </drive>
</partitioning>

You might expect the profile to contain 3 partitions. This is not the case. You'll end up with two partitions and the first partition is a mixup of the swap and the root partition. Settings configured in both partitions, like mount or size, will be used from the second file. Settings that only exist in the first or second partition, will be copied to the merged partition too.

In this example, you do not want a second drive. The two drives should be merged into one. With regard to partitions, three separate ones should be defined.

[Note]Workaround for SLES9/SL 10.0 and earlier

The following workaround only works for SLES9/SL 10.0 and earlier versions.

The following method is not officially supported by AutoYaST. For each partition in one file, add an attribute to the partition:

<partition dontmerge="1">
...
</partitions>

Because of the new attribute, the merge script will not detect the partitions as the same element type. If you have more files, you may need to add more attributes like dontmerge="2", etc.

[Note]Solution for SLES 10/SL 10.1 and later

The following method solves the merging problem for SLES10, SUSE Linux 10.1 and later versions.

Use the dont_merge element in the rules or class file:

<classes config:type="list">
    <class>
        <class_name>swap</class_name>
        <configuration>largeswap.xml</configuration>
        <dont_merge config:type="list">
            <element>partition</element>
        </dont_merge>
    </class>
</classes>
<rule>
    <board_vendor>
        <match>ntel</match>
        <match_type>regex</match_type>
    </board_vendor>
    <result>
        <profile>classes/largeswap.xml</profile>
        <continue config:type="boolean">true</continue>
        <dont_merge config:type="list">
          <element>partition</element>
        </dont_merge>
    </result>
    <board_vendor>
        <match>PowerEdge [12]850</match>
        <match_type>regex</match_type>
    </board_vendor>
    <result>
        <profile>classes/smallswap.xml</profile>
        <continue config:type="boolean">true</continue>
        <dont_merge config:type="list">
          <element>partition</element>
        </dont_merge>
    </result>
</rule>

openSUSE AutoYaST 12.2