YaST Firstboot

Firstboot configuration

The YaST firstboot utility is a special kind of configuration workflow that can be run after the basic system is installed. It is started on the first boot of the system and guides a user through a series of steps that allow for easier configuration of their desktops.

YaST firstboot does not run by default and has to be configured to run by the user or the system administrator. It is useful for image deployments where the system in the image is completely configured (read: AutoYaST, SUSE Studio, KIWI). However, some final steps such as root password and user logins have to be created to personalize the system.

Typical usage is also together with OEM preloads, where vendor provides hardware with preconfigured system, and user does the rest on first boot.

Enabling Firstboot

Firstboot is disabled by default. To enable running firstboot configuration sequence on the machine, it is necessary to:

Have yast2-firstboot package installed. Depending on your installation method, this means adding the package to the list of packages to be installed (e.g. for AutoYaST) or that are part of installation image.

Create the empty file /var/lib/YaST2/reconfig_system. If this file is present on system boot, firstboot configuration sequence is started. YaST Firstboot removes the file when the configuration is done.

Additionally, if you want to have firstboot sequence translated into another languages, you have to include/install also the translation packages. These are yast2-trans-*, e.g. yast2-trans-de.rpm for German.

Customizing YaST Firstboot

There are two main files that control the behavior of Firstboot: the firstboot control file (firstboot.xml) and the sysconfig file /etc/sysconfig/firstboot. The control file defines the steps that should be part of your configuration sequence, in the sysconfig file it is possible to define custom messages and paths to various files.

In addition to those files, YaST Firstboot also honors those settings in /etc/install.inf that make sense in a firstboot scenario.

Customized Messages

The texts configurable in sysconfig file are mainly the text shown as welcome text (use FIRSTBOOT_WELCOME_DIR value) and - most importantly - the texts shown in the License Agreement screens. For license texts, there are sysconfig variables FIRSTBOOT_LICENSE_DIR and FIRSTBOOT_NOVELL_LICENSE_DIR.

The license text is read from the file 'license.txt' or from 'license_<locale>.txt'. The license texts of the Novell base product are by default installed to the directory /etc/YaST2/licenses/base/ -- you can set different value to FIRSTBOOT_NOVELL_LICENSE_DIR if they are elsewhere. Use FIRSTBOOT_LICENSE_DIR to indicate a path to directory containing vendor licence texts; it is preferred to put these license texts into another subdirectory of /etc/YaST2/licenses/.

Note that the name of the variable FIRSTBOOT_NOVELL_LICENSE_DIR does not mean that it must point explicitely to Novell license: two different license directories are used to distinguish any two license texts.

To show two license texts in one dialog (typically the one from vendor and one from Novell), use 'firstboot_license_novell' step in your firstboot.xml file. This client will use the license texts specified by both FIRSTBOOT_LICENSE_DIR and FIRSTBOOT_NOVELL_LICENSE_DIR.

Customized Workflow

The default firstboot workflow can be controled using one single file which uses the same syntax as the control.xml file used to control the complete installation. The firstboot control file consists of workflow and proposal configurations and can be used to add or remove configuration screens depending on the end configuration of the system. The file firstboot.xml is installed with the yast2-firstboot package and can be found at the following location: /etc/YaST2/firstboot.xml.

This file can be modified to match the post installation requirements of the product in question. In addition to the default and pre-installed components, custom screens can be added to enable maximal flexiblity during post installation.

In following simple example of firstboot control file, only three steps are part of the workflow: Language and Keyboard, Welcome and Root Password (Language step is disabled). Note the value of 'name' section: this points to ycp file that will be called in specific step, for example for 'firstboot_language_keyboard' it will be the file /usr/share/YaST2/clients/firstboot_language_keyboard.ycp etc.

   <workflows  config:type="list">
       <workflow>
           <defaults>
               <enable_back>yes</enable_back>
               <enable_next>yes</enable_next>
               <archs>all</archs>
           </defaults>
           <stage>firstboot</stage>
           <label>Configuration</label>
           <mode>installation</mode>
           <modules  config:type="list">
               <module>
                   <label>Language and Keyboard</label>
                   <enabled config:type="boolean">true</enabled>
                   <name>firstboot_language_keyboard</name>
               </module>
               <module>
                   <label>Language</label>
                   <enabled config:type="boolean">false</enabled>
                   <name>firstboot_language</name>
               </module>
               <module>
                   <label>Welcome</label>
                   <name>firstboot_welcome</name>
               </module>
               <module>
                   <label>Root Password</label>
                   <enabled config:type="boolean">true</enabled>
                   <name>inst_root</name>
               </module>
           </modules>
       </workflow>
   </workflows>

And this is the first dialog of the sequence described above:

Look into the example firstboot.xml file coming with your yast2-firstboot package for more available steps. Also check the control file documentation for more details about the customization (e.g., how to customize the look & feel).

Instead of modifying the default /etc/YaST2/firstboot.xml file, it is possible to put the customized one to different location and specify path to it by altering the value of FIRSTBOOT_CONTROL_FILE variable in /etc/sysconfig/firstboot.

YaST Firstboot configuration

As mentioned above, some settings of /etc/install.inf can be useful in a firstboot scenario. For example, adding "Textmode: 1" to that file will force YaST Firstboot to use the ncurses interface. See the corresponding documentation for all the available options (although not all of them will make sense for the YaST Firstboot use case).

Custom Scripts

Not everything can be achieved with already prepared steps, and it is usually not necessary to write your own ycp dialogs.

You can add schell scripts to be executed at the end of the firstboot configuration. Scripts should be placed in /usr/share/firstboot/scripts or in a custom location that can be set using the variable SCRIPT_DIR of /etc/sysconfig/firstboot configuration file. The scripts are executed in alphabetical order of their names.

AutoYaST Support

It is possible to configure the firstboot process as a part of autoinstallation, so the system can be installed with most of the default values set via AutoYaST profile, leaving the rest to the end user during the firstboot sequence.

As a part of autoinstallation configuration, you need to provide all the changes mentioned above:

Customize /etc/sysconfig/firstboot: it can be done e.g. via Sysconfig Editor in System section of AutoYaST configuration module.

Provide customized firstboot.xml file and point to its location in FIRSTBOOT_CONTROL_FILE value of /etc/sysconfig/firstboot.

Enable Firstboot: do it via GUI in Misc/Firstboot section of AutoYaST configuration module or manually by adding the section

<firstboot>
   <firstboot_enabled config:type="boolean">true</firstboot_enabled>
</firstboot>

to your AutoYaST profile.