Product SiteDocumentation Site

Fedora 24

Anaconda Addon Development Guide

Things one needs to know when writing an Anaconda installer Addon

Vratislav Podzimek

Edited by

Petr Bokoč

Legal Notice

Copyright © 2016 Fedora Project Contributors.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. The original authors of this document, and Red Hat, designate the Fedora Project as the "Attribution Party" for purposes of CC-BY-SA. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
For guidelines on the permitted uses of the Fedora trademarks, refer to https://fedoraproject.org/wiki/Legal:Trademark_guidelines.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
All other trademarks are the property of their respective owners.

Abstract

The Anaconda installer is a piece of software used to install Fedora, Red Hat Enterprise Linux and their derivatives. Since the installation is internally a complicated process and there are many aspects of the resulting system that need to be configured during installation it has been decided that the Anaconda installer needs to support dynamically loaded plugins (addons) that will be developed and maintained by other teams and people specialized in certain areas. This guide should help those people writting an Anaconda addon to get an insight to the architecture and basic principles used by the Anaconda installer as well as an overview of the API and helper functions provided.
1. Introduction to Anaconda and Add-ons
1.1. Introduction to Anaconda
1.2. Firstboot and Initial Setup
1.3. Anaconda and Initial Setup Add-ons
1.4. Additional Information
2. Architecture of Anaconda
3. The Hub & Spoke model
4. Threads and Communication
5. Anaconda Add-on Structure
6. Writing an Anaconda add-on
6.1. Kickstart Support
6.2. Graphical user interface
6.3. Text User Interface
7. Deploying and Testing an Anaconda Add-on
8. Add-ons Welcome
A. Revision History
Index

1. Introduction to Anaconda and Add-ons

1.1. Introduction to Anaconda

Anaconda is the operating system installer used in Fedora, Red Hat Enterprise Linux, and their derivatives. It is a set of Python modules and scripts together with some additional files like Gtk widgets (written in C), systemd units, and dracut libraries. Together, they form a tool that allows users to set parameters of the resulting (target) system and then set such a system up on a machine. The installation process has four major steps:
  • installation destination preparation (usually disk partitioning)
  • package and data installation
  • boot loader installation and configuration
  • configuration of the newly installed system
There are three ways you can control the installer and specify installation options. The most common approach is to use the graphical user interface (GUI). This interface is meant to allow users to install the system interactively with little or no configuration required before beginning the installation, and it should cover all common use cases, including setting up complicated partitioning layouts.
The graphical interface also supports remote access over VNC, which allows you to use the GUI even on systems with no graphics cards or even attached monitor. However, there are still cases where this is not desired, but at the same time, you may want to perform an interactive installation. For these cases, a text mode (TUI) is available. The TUI works in a way similar to a monochrome line printer, which allows it to work even on serial consoles which do not support cursor movement, colors and other advanced features. The text mode is limited in that it only allows you to customize most common options, such as network settings, language options or installation (package) source; advanced features such as manual partitioning are not available in this interface.
The third way to install a system using Anaconda is by using a Kickstart file - a plain text file with shell-like syntax which can contain data to drive the installation process. A Kickstart file allows you to partially or completely automate the installation. A certain set of commands which configures all required areas is necessary to completely automate the installation; if one or more of the required commands is missing, the installation will require interaction. If all required commands are present, the installation will be performed in a completely automatic way, without any need for interaction.
Kickstart provides the highest amount of options, covering use cases where neither the TUI nor the GUI is sufficient. Every feature in Anaconda must always be supported in Kickstart; other interfaces follow only subsets of all available options, which allows them to remain clear.

1.2. Firstboot and Initial Setup

The first boot of the newly installed system is traditionally considered a part of the installation process as well, because some parts of configuration such as user creation are often performed at this point. In older releases of Red Hat Enterprise Linux, the Firstboot tool has been used for this purpose, allowing you to register your newly installed system or configure Kdump. However, Firstboot relies on no longer maintained tools such as Gtk2 and the pygtk2 module. [1] For this reason, a new tool called Initial Setup was developed, which reuses code from Anaconda. This allows add-ons developed for Anaconda to be easily reused in Initial Setup. This topic is further discussed in Section 6, “Writing an Anaconda add-on”.

1.3. Anaconda and Initial Setup Add-ons

Installing a new operating system is a vastly complicated use case - each user may want to do something slightly different. Designing an installer for every corner case would cause it to be cluttered with rarely-used functionality. For this reason, when the installer was being rewritten into its current form, it gained support for add-ons.
Anaconda add-ons can be used to add your own Kickstart commands and options as well as new configuration screens in the graphical and text-based user interface, depending on your specific use case. Each add-on must have Kickstart support; the GUI and TUI are optional, but can be very helpful.
In current releases of Fedora [2] (21 and later) and Red Hat Enterprise Linux (7.1 and later), one add-on is included by default: The Kdump add-on, which adds support for configuring kernel crash dumping during the installation. This add-on has full support in Kickstart (using the %addon com_redhat_kdump command and its options) and is fully integrated as an additional screen in the text-based and graphical interfaces. You can develop other add-ons in the same way and add them to the default installer using procedures described further in this guide.

1.4. Additional Information

Following links contain additional information about Anaconda and Initial Setup:


[1] While Firstboot is a legacy tool, it is still supported because of third-party modules written for it.
[2] In Fedora, the add-on is disabled by default. You can enable it using the inst.kdump_addon=on option in the boot menu.