ay_create_control_file.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter
[
  <!ENTITY % entities SYSTEM "generic-entities.ent">
    %entities;
]>
<chapter version="5.0" role="General" 
  xml:id="cha-autoyast-create-control-file"
  xmlns="http://docbook.org/ns/docbook"
  xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink">
 <title>Creating an &ay; control file</title>
 <info>
  <dm:docmanager xmlns:dm="urn:x-suse:ns:docmanager">
   <dm:bugtracker></dm:bugtracker>
   <dm:translation>yes</dm:translation>
  </dm:docmanager>
 </info>
 <sect1 xml:id="Autoinstallation-collectInfo">
  <title>Collecting information</title>

  <para>
   To create the control file, you need to collect information about the
   systems you are going to install. This includes hardware data and network
   information among other things. Make sure you have the following information
   about the machines you want to install:
  </para>

  <itemizedlist mark="bullet" spacing="normal">
   <listitem>
    <para>
     Hard disk types and sizes
    </para>
   </listitem>
   <listitem os="sles;sled;osuse">
    <para>
     Graphical interface and attached monitor, if any
    </para>
   </listitem>
   <listitem>
    <para>
     Network interface and MAC address if known (for example, when using DHCP)
    </para>
   </listitem>
  </itemizedlist>

  <para os="sles;sled;osuse">
   Also verify that both <package>autoyast2-installation</package> and
   <package>autoyast2</package> are installed.
  </para>
 </sect1>
 <sect1 os="sles;sled;osuse" xml:id="CreateProfile-CMS">
  <title>Using the configuration management system (CMS)</title>

  <para>
   To create the control file for one or more computers, a configuration
   interface based on &yast; is provided. This system depends on existing
   modules which are usually used to configure a computer in regular operation
   mode, for example, after &productname; is installed.
  </para>

  <para>
   The configuration management system lets you easily create control files and
   manage a repository of configurations for use in a networked environment
   with multiple clients.
  </para>

  <figure os="sles;sled">
   <title>Configuration system</title>
   <mediaobject>
    <imageobject role="html">
     <imagedata fileref="autoyast2-maindialog.png"/>
    </imageobject>
    <imageobject role="fo">
     <imagedata fileref="autoyast2-maindialog.png" width="75%"/>
    </imageobject>
   </mediaobject>
  </figure>

  <figure os="osuse">
   <title>Configuration system</title>
   <mediaobject>
    <imageobject role="html">
     <imagedata fileref="autoyast2-maindialog_kde.png"/>
    </imageobject>
    <imageobject role="fo">
     <imagedata fileref="autoyast2-maindialog_kde.png" width="75%"/>
    </imageobject>
   </mediaobject>
  </figure>

  <sect2 xml:id="CreateProfile-CMS-new">
   <title>Creating a new control file</title>
   <para>
    The easiest way to create an &ay; profile is to use an existing
    &productname; system as a template. On an already installed system, launch
    <menuchoice><guimenu>&yast;</guimenu> <guimenu>Miscellaneous</guimenu>
    <guimenu>Autoinstallation Configuration</guimenu></menuchoice>. Then select
    <menuchoice><guimenu>Tools</guimenu> <guimenu>Create Reference
    Profile</guimenu></menuchoice> from the menu. Choose the system components
    you want to include in the profile. Alternatively, create a profile
    containing the complete system configuration by launching
    <menuchoice><guimenu>&yast;</guimenu> <guimenu>Miscellaneous</guimenu>
    <guimenu>Autoinstallation Cloning System</guimenu></menuchoice> or running
    <command>sudo yast clone_system</command> from the command line.
   </para>
   <para>
    Both methods will create the file <filename>/root/autoinst.xml</filename>.
    The cloned profile can be used to set up an identical clone of the system
    it was created from. However, you will usually want to adjust the file to
    allow for installing multiple machines that are very similar, but not
    identical. This can be done by adjusting the profile with your favorite
    text/XML editor.
   </para>
   <warning>
    <title>Sensitive data in profiles</title>
    <para>
     Be aware that the profile might contain sensitive information such as
     password hashes and registration keys.
    </para>
    <para>
     Carefully review the exported profiles and make sure to keep file
     permissions restrictive.
    </para>
   </warning>
   <para>
    With some exceptions, almost all resources of the control file can be
    configured using the configuration management system. The system offers
    flexibility and the configuration of some resources is identical to the one
    available in the &yast; control center. In addition to the existing and
    familiar modules new interfaces were created for special and complex
    configurations, for example for partitioning, general options and software.
   </para>
   <para>
    Furthermore, using a CMS guarantees the validity of the resulting control
    file and its direct use for starting automated installation.
   </para>
   <para>
    Make sure the configuration system is installed (package
    <systemitem class="resource">autoyast2</systemitem>) and call it using the
    &yast; control center or as root with the following command (make sure the
    <envar>DISPLAY</envar> variable is set correctly to start the graphical
    user interface instead of the text-based one):
   </para>
<screen>/sbin/yast2 autoyast</screen>
  </sect2>
 </sect1>
 <sect1 xml:id="CreateProfile-Manual">
  <title>Creating/editing a control file manually</title>

  <para os="slemicro">
   You need to create the control file manually and ensure that it has a valid
   syntax. To verify if the file has a valid XML structure, you can use the
   utility <command>xmllint</command> available with the
   <systemitem>libxml2</systemitem> package:
  </para>

  <para os="sles;sled;osuse">
   If editing the control file manually, make sure it has a valid syntax. To
   check the syntax, use the tools already available on the distribution. For
   example, to verify that the file is well-formed (has a valid XML structure),
   use the utility <command>xmllint</command> available with the
   <systemitem>libxml2</systemitem> package:
  </para>

<screen>xmllint &lt;control file&gt;</screen>

  <para>
   If the control file is not well formed, for example, if a tag is not closed,
   <command>xmllint</command> will report the errors.
  </para>

  <para>
   To validate the control file, use the tool <command>jing</command> from the
   package with the same name. During validation, misplaced or missing tags and
   attributes and wrong attribute values are detected. <phrase os="sles">The
   <package>jing</package> package is provided with the &sdk;.</phrase>
  </para>

<screen>jing /usr/share/YaST2/schema/autoyast/rng/profile.rng &lt;control file&gt;</screen>

  <para>
   <literal>/usr/share/YaST2/schema/autoyast/rng/profile.rng</literal> is
   provided by the package <literal>yast2-schema</literal>. This file describes
   the syntax and classes of an &ay; profile.
  </para>

  <note os="osuse;sles;sled">
   <title>Schema extensions</title>
   <para>
    &ay; can be extended by other products and modules, but the schema does not
    contain the specification for those extensions. As a consequence, when &ay;
    is given a profile that uses one of those extensions, it might report the
    profile as invalid.
   </para>
   <para>
    Thus, starting in &productname;
    <phrase os="osuse">15.3</phrase><phrase
     os="sles;sled">SP3</phrase>,
    &ay; does not validate top-level unknown sections, and ignores them. For
    example, in the example below, <literal>&lt;sap-inst&gt;</literal> is not
    validated. The rest is validated as usual.
   </para>
<screen>&lt;general&gt;
  &lt;mode&gt;
    &lt;confirm config:type="boolean"&gt;true&lt;/confirm&gt;
  &lt;/mode&gt;
&lt;/general&gt;

&lt;sap-inst&gt;
  &lt;!-- this section is not validated -->&gt;
&lt;/sap-inst&gt;
</screen>
  </note>

  <para>
   Before going on with the autoinstallation, fix any errors resulting from
   such checks. The autoinstallation process cannot be started with an invalid
   and not well-formed control file.
  </para>

  <para>
   You can use any XML editor available on your system or any text editor with
   XML support (for example, Emacs, Vim). <phrase os="osuse;sles;sled">However,
   it is not optimal to create the control file manually for many machines and
   it should only be seen as an interface between the autoinstallation engine
   and the Configuration Management System (CMS)</phrase>.
  </para>

  <tip>
   <title>Using Emacs as an XML editor</title>
   <para>
    The built-in nxml-mode turns Emacs into a fully-fledged XML editor with
    automatic tag completion and validation. Refer to the Emacs help for
    instructions on how to set up nxml-mode.
   </para>
  </tip>
 </sect1>
 <sect1 xml:id="CreateProfile-XSLT">
  <title>Creating a control file via script with XSLT</title>

  <para>
   If you have a template and want to change a few things via script or command
   line, use an XSLT processor like <literal>xsltproc</literal>. For example,
   if you have an &ay; control file and want to fill out the host name via
   script for any reason. (If doing this often, you should consider scripting
   it.)
  </para>

  <para>
   First, create an XSL file:
  </para>

  <example>
   <title>Example file for replacing the host name/domain by script</title>
<screen>&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
  xmlns:y2="http://www.suse.com/1.0/yast2ns"
  xmlns:config="http://www.suse.com/1.0/configns"
  xmlns="http://www.suse.com/1.0/yast2ns"
  version="1.0"&gt;
  &lt;xsl:output method="xml" encoding="UTF-8" indent="yes" omit-xml-declaration="no" cdata-section-elements="source"/&gt;

  &lt;!-- the parameter names --&gt;
  &lt;xsl:param name="hostname"/&gt;
  &lt;xsl:param name="domain"/&gt;

  &lt;xsl:template match="/"&gt;
    &lt;xsl:apply-templates select="@*|node()"/&gt;
  &lt;/xsl:template&gt;

  &lt;xsl:template match="y2:dns"&gt;
    &lt;xsl:copy&gt;
      &lt;!-- where to copy the parameters --&gt;
      &lt;domain&gt;&lt;xsl:value-of select="string($domain)"/&gt;&lt;/domain&gt;
      &lt;hostname&gt;&lt;xsl:value-of select="string($hostname)"/&gt;&lt;/hostname&gt;
      &lt;xsl:apply-templates select="@*|node()"/&gt;
    &lt;/xsl:copy&gt;
  &lt;/xsl:template&gt;


  &lt;xsl:template match="@*|node()" &gt;
    &lt;xsl:copy&gt;
      &lt;xsl:apply-templates select="@*|node()"/&gt;
    &lt;/xsl:copy&gt;
  &lt;/xsl:template&gt;

&lt;/xsl:stylesheet&gt;
</screen>
  </example>

  <para>
   This file expects the host name and the domain name as parameters from the
   user.
  </para>

<screen>&lt;xsl:param name="hostname"/&gt;
&lt;xsl:param name="domain"/&gt;</screen>

  <para>
   There will be a copy of those parameters in the DNS section of the control
   file. This means that if there already is a domain element in the DNS
   section, you will get a second one, which will cause conflicts.
  </para>

  <!-- FIXME: rewrite these sections using xsltproc
   <para>
   To create a new &ay; control file now from the template plus
   the XSL file, run the following command:
   </para>
   <screen>sabcmd add_hostname.xsl \$hostname=myHost \$domain=my.domain  template.xml</screen>
   <para>
   You will then get a filled out &ay; control file on STDOUT.
   </para>
   <para>
   If you have multiple XSL files you want to apply to a template, do the
   following:
   </para>
   <screen>sabcmd add_hd_vg.xsl \$device=/dev/sda \$partition=p2 \$vg=system \
   | sabcmd add_harddisk.xsl \$device=/dev/system \$lvm=true \
   | sabcmd ....
   | sabcmd add_hostname.xsl \$hostname=myHost \$domain=my.domain</screen>
   <para>
   Pipe the output of each sabcmd to the next sabcmd.
   </para>
   -->

  <para>
   For more information about XSLT, go to the official Web page
   <link xlink:href="http://www.w3.org/TR/xslt">www.w3.org/TR/xslt</link>
  </para>
 </sect1>
 <sect1 xml:id="check-profile">
  <title>Checking a control file</title>

  <para>
   Depending on the use case, creating an &ay; profile can be difficult,
   especially if you build a dynamic profile using rules/classes, ERB templates
   or pre-scripts. For more information, see
   <xref linkend="part-dynamic-profiles"/>.
  </para>

  <para>
   Starting with &productname;
   <phrase os="osuse">15.3</phrase><phrase
    os="sles;sled">15
   SP3</phrase><phrase os="slemicro">5.1</phrase>, &ay; validates the profile
   during the installation, reporting any problem found to the user. Although
   it is recommended to check whether the profile is correct or not, you can
   disable this behavior by setting the
   <literal>YAST_SKIP_XML_VALIDATION</literal> boot parameter to
   <literal>1</literal>.
  </para>

  <para>
   Moreover, to simplify the testing and debugging process, &ay; offers the
   <literal>check-profile</literal> command, which takes care of fetching,
   building and, optionally, importing the profile to detect any potential
   problem.
  </para>

  <note>
   <title>Results may vary</title>
   <para>
    Although this command uses the same approach as the installation, the
    results may vary depending on the differences between the current system
    and installation media: &yast; package versions, architecture, etc.
   </para>
  </note>

  <warning>
   <title>Use only trusted profiles</title>
   <para>
    You must be careful when running this command because pre-installation
    scripts and ERB code would run as the <literal>root</literal> user. Use
    only profiles that you trust.
   </para>
  </warning>

  <sect2 xml:id="sec-basic-checks">
   <title>Basic checks</title>
   <para>
    The simplest way to use this command is just to read and validate the
    profile:
   </para>
<screen>&prompt.sudo; yast2 autoyast check-profile filename=autoinst.xml output=result.xml</screen>
   <para>
    The <filename>result.xml</filename> file contains the result of evaluating
    the profile. Bear in mind that, even if you do not use any advanced
    feature, the content of <filename>autoinst.xml</filename> and
    <filename>result.xml</filename> may differ. The reason is that &ay; does
    some cleaning up when it processes the profile.
   </para>
   <para>
    <literal>check-profile</literal> can deal with remote files too:
   </para>
<screen>&prompt.sudo; yast2 autoyast check-profile filename=http://192.168.1.100/autoinst.xml output=result.xml</screen>
  </sect2>

  <sect2 xml:id="sec-running-pre-scripts">
   <title>Running pre-scripts</title>
   <para>
    Optionally, &ay; can run the scripts that are included in the profile,
    reporting any error found during the execution. This is especially relevant
    if you are using a pre-installation script to modify the profile. To enable
    this feature, you need to set the <literal>run-scripts</literal> option to
    <literal>true</literal>.
   </para>
<screen>&prompt.sudo; yast2 autoyast check-profile filename=http://192.168.1.100/autoinst.xml output=result.xml run-scripts=true</screen>
   <warning>
    <title>Scripts run as root</title>
    <para>
     You must be careful when enabling the <literal>run-scripts</literal>
     option, because the scripts will run as root and they may affect the
     current system.
    </para>
   </warning>
  </sect2>

  <sect2 xml:id="sec-importing-profile">
   <title>Importing the profile</title>
   <para>
    It is possible to face some problems when importing a valid profile, even
    if it is correct. The reason is that &ay; does not perform any logic check
    when fetching, building and validating the profile.
   </para>
   <para>
    To anticipate such problems, the <literal>check-profile</literal> command
    imports the profile and reports problems that it has detected. As it may
    take a while, you can disable this behavior by setting the
    <literal>import-all</literal> option to <literal>false</literal>.
   </para>
<screen>&prompt.sudo; yast2 autoyast check-profile filename=http://192.168.1.100/autoinst.xml output=result.xml import-all=false</screen>
   <para>
    Importing the profile is a safe operation and does not alter the underlying
    system in any way.
   </para>
  </sect2>
 </sect1>
</chapter>