3.3 AutoYaST Control File

An AutoYaST control file is a configuration description in XML format that can contain just a few instructions or it may be comprised of hundreds of instructions that describe the details of the system to be installed.

A control file does not need to provide every configuration detail. If configuration items are omitted, AutoYaST will configure the system by using meaningful default values for the configuration items of the lacking sections. This works for most situations but can lead to unexpected results in some circumstances. Therefor we strongly recommend to include the configuration tags for every setting where the desired value differs from the default or must be protected against a change in the default.

In theory a control file can be created completely manually using your favorite editor. However, because this approach would be very error-prone it is not recommended.

The easiest way to obtain a valid control file that can be used as a template for automated installations is to use the /root/autoinst.xml file of an existing system, provided the option to create this file had been selected during installation. If this should not have been the case the file can be created easily at any time by issuing the yast clone_system command.

Another way to create a control file is to use yast autoyast. This allows you to crate a control file for the complete system or for individual components. It provides a save method to create a syntactically correct XML file. You can even clone the existing system and only modify the values that need to be different for the system that you want to install. The resulting XML files are stored in the directory /var/lib/autoinstall/repository.

Figure 3-1 YaST: Autoinstallation - Configuration Items

The packages autoyast2 and autoyast2-installation must be installed for this functionality to be available in YaST.

However, the control file of an existing system should only be used as template for a new installation with great care. You need to ensure that any value specific for the machine where the file has been generated is adjusted before you use the control file to install a new system. Whenever you modify the contents of a XML file we strongly recommend to validate the control file using a XML parser such as xmllint.

The AutoYaST control file can be located on any local or remote installation repository from where it can be retrieved at the beginning of an unattended installation.

3.3.1 Control File Structure

An AutoYaST control file must be written in valid XML syntax. It is organized in sections that define different aspects of an installation. The following sections could be part of an AutoYaST control file that drives an OES 2018 installation:

add-on
boot loader
ca_mgm (CA management)
eDirectory
general
groups
host
…
networking
partitioning
users

The following example shows a XML snippet to configure some aspects of the YaST Certificate Authority for SLES 12:

<?xml version="1.0"?> 
<!DOCTYPE profile> 
<profile xmlns="http://www.suse.com/1.0/yast2ns" 
xmlns:config="http://www.suse.com/1.0/configns">
<ca_mgm>
    <CAName>YaST_Default_CA</CAName>
    <ca_commonName>my-company.us</ca_commonName>
    <country>US</country>
    <importCertificate config:type="boolean">false</importCertificate>
    <locality>Provo</locality>
    <organisation>IT</organisation>
    <organisationUnit>Servermanagement</organisationUnit>
    <password>secret</password>
    <server_email>jdoe@novell.com</server_email>
    <state>UTAH</state>
    <takeLocalServerName config:type="boolean">true</takeLocalServerName>
</ca_mgm>
</profile>

3.3.2 Class Files

Very few instructions within a control file are specific for a particular server. Most of them can be re-used. To support this AutoYaST offers the possibility to separate sections of the control file out into external class files. This approach is also known as class-based AutoYaST installation. Classes have a few advantages over monolithic AutoYaST control files:

Code is easier to maintain since class files contain only parts of the whole.
Classes can be re-used for different installation scenarios, i. e. the NTP class can be used for the installation of different versions of SLES and OES.

When using this technique it is possible to start the installation with a minimal control file only containing class directives (see control file default in section Retrieving a Control File below). The real configuration information is then provided by the class files.

Just like a control file a class file must be in valid XML syntax and it can contain a single or multiple sections of the complete AutoYaST control file. It must be specified in a control file by a class directive. This directive has attributes that define the location of the external class file.

When a class configuration tag is encountered during control file processing the corresponding external class file is loaded from the specified location and merged into the main control file that is temporarily stored in /tmp/profile/autoinst.xml on the system being installed. Once it is complete this control file is parsed in the same manner as a monolithic control file when using the non-class based approach.

For using classes some preparations have to be made where the AutoYaST control file is stored:

All class files must be located in a directory named classes immediately subordinate to the directory specified in the AutoYaST URL. For example, if the AutoYaST URL has been specified as autoyast=http://10.10.10.101/xml/default the class files must be located in the http://10.10.10.101/xml/classes directory.

A class directive always contains a class_name tag and a configuration tag:

<class>
     <class_name>general</class_name>
     <configuration>bootloader.xml</configuration>
</class>

A class_name tag represents a directory underneath the classes directory, e. g. if general is used in the class_name tag the following directory must exist:
```
http://10.10.10.101/xml/classes/general
```
A configuration tag specifies the name of the XML file in the directory defined by the class_name tag. Using the class_name tag from the above example the class file bootloader.xml would be accessed through the following URL:
```
http://10.10.10.101/xml/classes/general/bootloader.xml
```

3.3.3 Retrieving a Control File

The URL for a control file must be specified by one of the following syntaxes:

autoyast=<protocol>://<IP Address|DNS-Name>/<path to control file or directory/>,

e.g.:

autoyast=http://10.10.10.101/xml/mycontrolfile

autoyast=http://10.10.10.101/xml/

The first example points directly to a control file at the repository server. This will locate, retrieve and process the AutoYaST control file mycontrolfile.

The second example points to a directory (note the trailing “/”) resulting in the following retrieval process:

A file whose name is equivalent to the hexadecimal value of the IP address of the system being installed is searched in the specified directory. For example:
```
192.168.2.91 -> http://10.10.10.101/xml/C0A8025B
```
If this file does not exist, the last character of the file name is removed and the system searches for the resulting file name. For example:
```
http://10.10.10.101/xml/C0A8025
```

If the file does not exist the process is repeated until the file name has been truncated to one character. For example:

http://10.10.10.101/xml/C0A802
http://10.10.10.101/xml/C0A80
http://10.10.10.101/xml/C0A8
http://10.10.10.101/xml/C0A
http://10.10.10.101/xml/C0
http://10.10.10.101/xml/C

If a file with a name matching the name derived by the above process can be located the unattended installation starts. If no file can be found the process continues.
The system tries to retrieve a file with a name matching the MAC address of the network adapter from which the connection to the web server has been initiated.

Two attempts are made: First, it looks for a file name with characters in all uppercase. If it is not found, a file name with characters in all lowercase will be searched for.

For example:
```
http://10.10.10.101/xml/0080A8F6484C
http://10.10.10.101/xml/0080a8f6484c
```
Finally, if this still does not deliver a control file, the process looks for a file named default in the directory which has been specified with the autoyast= parameter. For example:
```
http://10.10.10.101/xml/default
```
If the default file is found, it is evaluated and its instructions are executed. The resulting control file that is used to perform the installation initially is stored as /tmp/profile/autoinst.xml and moved to /var/adm/autoinstall/cache/installedSystem.xml on the installed system as the installation proceeds.

If the installation engine has not located a control file at this point, the installation process terminates and informs the administrator that the URL for the AutoYaST control file is invalid.