Docs/Drafts/Spins/RevisorDocumentation

Documentation Summary:

Purpose: Teach how to use common Fedora tools to build (spin) a custom Linux OS based on Fedora that is installable or runnable from a media source such as CD, DVD, or a USB device.

Audience: (option1) The general audience is daring or moderately experienced technical operators, such as systems administrators, programmers, or power users. (option2) General computer user. (Can we do to that level at this stage?)

kanarip: The audience for Revisor had originally been "the computer user"; no real experience with the command line, wants click-n-go GUIs to do the work. We knew however that we had the opportunity to create some additional features and really extend the feature set of the entire "spin your own" branch of applications. This is where we choose to go "Advanced Mode"; the rather experienced user can find his way through the GUI by making a few attempts, and the general administrator should not have any trouble creating exactly what he wants. Nonetheless, "Advanced Mode" will show lots of options that one may not need or may not know anything about. Some advanced users will try and fail and find their way through, others will never click any "Virtualisation Media" but need the "Advanced Configuration" for selecting specific versions of packages. Ergo, long story short, my proposal is to have a document for the non-savvy user warning him not to go "Advanced Mode" unless expecting himself to fail navigating through the GUI, and a document that has the more advanced options and features and choices and rationale behind those options, features and choices.

Approach: This document explains basic principles by explaining one principle at a time. The focus is on performing procedures, and only explaining principles where necessary.

Assumptions: The document does not assume familiarity with any Linux/UNIX-specific terminology or concepts. Readers need to be able to follow technical directions, operate their computer, and may need the root password for certain operations.

Related Documents: Docs/Drafts/AdministrationGuide?

Lead Writer: JonathanRoberts

Writers: JohnBabich

Overview
Revisor enables you to customize and compose your own Fedora based installation and live media. It can be used through a graphical interface, or through the command line for access to more advanced features and configuration files. This guide explains how to use Revisor to spin custom Fedora media.

Terminology
Live Media:: Live media (Live CD) is a runnable instance of Fedora booted from media, without the need to install it on your system first. The operating system is installed on a CD, DVD, or USB media such as a thumbdrive, and the computer boots that operating system. It is possible to install a Fedora system from live media.

Installation Media:: Installation media can only be used to install a Fedora system, or to recover a system with Fedora already installed.

Kickstart Configuration File:: A kickstart configuration file holds configuration information used by, the Fedora system installer. It can be used to configure the system beforehand, allowing  to run unattended. Kickstart files often hold a package manifest, along with other configuration options such as which services to run on the installed system, what the X Window configuration should look like, and so forth. System-config-kickstart is installed as a dependency of Revisor, allowing easy creation of kickstart files.

Installation
To install Revisor, and all the necessary dependencies, on a Fedora 7 system, execute the following command from the terminal:

su -c 'yum install revisor'

This makes Revisor available as a menu entry under Applications > System Tools > Revisor.

Using Revisor
NB: Going to need explanations of advanced options!

Recommendation: Explain anything advanced in the GUI as well as the TUI/CLI. Focus on several usage examples, as well as something that shows or points at the command list, such as pointing the way to.

Get Started
To get started, launch Revisor from the menu entry created during installation. The welcome screen appears and provides some brief information about Revisor. To proceed click Get Started.

The following screen prompts you to select the kind of media you would like. Mark the appropriate selection and click Forward.

Configuring Revisor For This Session
Revisor is configured by a master configuration file that lists different models, and in which file the information relating to that model can be found. The default configuration file is /etc/revisor/revisor.conf. Each model contains configuration options, such as which yum repositories to use for the following Revisor session.

The models listed in the configuration file are available for selection, under Configuration Section To Use, and when the Apply button is pressed all yum repositories for that model are loaded. Select which repositories to use and continue by pressing the Forward button. See appendix  Revisor Configuration Files  for more information about available options.

Kickstart
Loading a kickstart configuration file in this dialog enables you to store configuration options you've used to compose media before, and use them again in this run. Options available when loading a kickstart configuration file include:


 * Use package manifest from kickstart data


 * Use the package manifest defined in the kickstart file, providing a pre-defined set of packages for installation from the installation media, or as software to be available on the live media.


 * Customize package manifest defined in kickstart data


 * This option makes it possible to enable use package manifest from kickstart data, allowing the selection or removal of additional software from an old kickstart package manifest.


 * Customize/Review additional options loaded from kickstart data


 * While the kickstart configuration file may have specified all configuration options, enabling this option allows further customization to the configuration in the kickstart data, using the options in the kickstart data as 'defaults'. As before, this makes it possible to customize an old kickstart file without having to start from scratch.

Package Selection
If the only option selected so far was to use the package manifest from a kickstart file, Revisor will start building the media immediately. For live media, this means that options in the kickstart configuration file will be applied, and no further customization will take place.

If a kickstart configuration file was loaded, but the option to customize the package manifest, or not to use the package manifest at all was selected, Revisor will continue with the Package Selection Dialog. Revisor will also continue with the Package Selection Dialog if no kickstart configuration file was specified.

The Package Selection Dialog makes it possible to select packages for inclusion on the installation or live media. The default view has Categories on the left side, and corresponding Groups on the right side. To customize the packages within a selected group, click Optional Packages. Right clicking a group makes it possible to select, or de-select, all optional packages for that group. De-selecting all optional packages leaves mandatory packages for that group selected. It is also possible to view a list of all available packages, or to search for a specific package, using the appropriate tab at the top of the dialog.

If the option to customize additional options from kickstart was selected, or if no kickstart file was selected then the Revisor will now move on and present a series of screens to create a kickstart file. (NB: With installation media this is only true if kickstart is to be included on the installation medium.) Otherwise, Revisor will start building your media.

Advanced Configuration Options
The advanced configuration options allow you to modify a number of sections of the kickstart file:


 * Basic Configuration
 * Boot Loader Options
 * Network Configuration
 * Authentication
 * Security Configuration
 * Display Configuration
 * Account Information

All of these can also be modified in the original kickstart file, along with other options, using system-config-kickstart which is found under Applications > Accessories > Kickstart.