revisor-devel December 2009

revisor-devel@lists.stg.fedorahosted.org

1 participants
2 discussions

4 commits - doc/Reference_Manual revisor/__init__.py.in revisor/misc.py
by Jeroen van Meeuwen 26 Dec '09

26 Dec '09

Environment).png |binary doc/Reference_Manual/en-US/Appendix.xml | 51 - doc/Reference_Manual/en-US/Book_Info.xml | 9 doc/Reference_Manual/en-US/Preface.xml | 10 doc/Reference_Manual/en-US/Reference-Compose_Process_Details.xml | 431 ++++++++++ doc/Reference_Manual/en-US/Reference-Configuration.xml | 317 +++++++ doc/Reference_Manual/en-US/Reference-Development.xml | 220 +++++ doc/Reference_Manual/en-US/Reference-Features.xml | 182 ++++ doc/Reference_Manual/en-US/Reference-Frequently_Asked_Questions.xml | 54 + doc/Reference_Manual/en-US/Reference-HOWTO.xml | 65 + doc/Reference_Manual/en-US/Reference-Installation.xml | 104 ++ doc/Reference_Manual/en-US/Reference-Introduction.xml | 77 + doc/Reference_Manual/en-US/Reference-Plugins.xml | 131 +++ doc/Reference_Manual/en-US/Reference-Quick_Start.xml | 60 + doc/Reference_Manual/en-US/Reference-Testing.xml | 173 ++++ doc/Reference_Manual/en-US/Reference-Tips_and_Tricks.xml | 47 + doc/Reference_Manual/en-US/Reference-Tweaking_The_Build_Process.xml | 40 doc/Reference_Manual/en-US/Reference-Using_Kickstart.xml | 118 ++ doc/Reference_Manual/en-US/Reference.ent | 5 doc/Reference_Manual/en-US/Reference.xml | 41 doc/Reference_Manual/en-US/Reference_Manual.ent | 5 doc/Reference_Manual/en-US/Reference_Manual.xml | 27 doc/Reference_Manual/en-US/Revisor_Reference_Manual-Compose_Process_Details.xml | 431 ---------- doc/Reference_Manual/en-US/Revisor_Reference_Manual-Configuration.xml | 280 ------ doc/Reference_Manual/en-US/Revisor_Reference_Manual-Development.xml | 220 ----- doc/Reference_Manual/en-US/Revisor_Reference_Manual-Features.xml | 175 ---- doc/Reference_Manual/en-US/Revisor_Reference_Manual-Frequently_Asked_Questions.xml | 54 - doc/Reference_Manual/en-US/Revisor_Reference_Manual-Installation.xml | 104 -- doc/Reference_Manual/en-US/Revisor_Reference_Manual-Introduction.xml | 77 - doc/Reference_Manual/en-US/Revisor_Reference_Manual-Plugins.xml | 131 --- doc/Reference_Manual/en-US/Revisor_Reference_Manual-Testing.xml | 173 ---- doc/Reference_Manual/en-US/Revisor_Reference_Manual-Tips_and_Tricks.xml | 47 - doc/Reference_Manual/en-US/Revisor_Reference_Manual-Tweaking_The_Build_Process.xml | 40 doc/Reference_Manual/en-US/Revisor_Reference_Manual-Using_Kickstart.xml | 118 -- doc/Reference_Manual/en-US/images/Screenshot-1.png |binary doc/Reference_Manual/en-US/images/Screenshot-2.png |binary doc/Reference_Manual/en-US/images/Screenshot-Revisor-1.png |binary doc/Reference_Manual/en-US/images/Screenshot-Revisor-2.png |binary doc/Reference_Manual/en-US/images/Screenshot-Revisor-3.png |binary doc/Reference_Manual/en-US/images/Screenshot-Revisor-4.png |binary doc/Reference_Manual/en-US/images/Screenshot-Revisor-5.png |binary doc/Reference_Manual/en-US/images/Screenshot-Revisor-6.png |binary doc/Reference_Manual/en-US/images/Screenshot-Revisor-7.png |binary doc/Reference_Manual/en-US/images/Screenshot-Revisor-8.png |binary doc/Reference_Manual/en-US/images/Screenshot-Revisor-9.png |binary doc/Reference_Manual/en-US/images/Screenshot-Revisor.png |binary doc/Reference_Manual/en-US/images/Screenshot-Warning-1.png |binary doc/Reference_Manual/en-US/images/Screenshot-Warning.png |binary doc/Reference_Manual/en-US/images/Screenshot.png |binary doc/Reference_Manual/publican.cfg | 7 folder.png |binary revisor/__init__.py.in | 2 revisor/misc.py | 15 53 files changed, 2116 insertions(+), 1925 deletions(-) New commits: commit 8f0605fdd1864f2b2175173b8d8e12248559382b Author: Jeroen van Meeuwen (Fedora Unity) <kanarip(a)fedoraunity.org> Date: Fri Dec 25 14:57:57 2009 +0100 Update documentation, include some screenshots for the Quick Start guide as well diff --git a/doc/Reference_Manual/en-US/Appendix.xml b/doc/Reference_Manual/en-US/Appendix.xml index dad871e..cee1f35 100644 --- a/doc/Reference_Manual/en-US/Appendix.xml +++ b/doc/Reference_Manual/en-US/Appendix.xml @@ -122,7 +122,7 @@ <entry>global, model</entry> </row> <row> - <entry namest="column25" nameend="column89">Answer <emphasis>yes</emphasis> to all questions.</entry> + <entry namest="column25" nameend="column89">Answer <emphasis>yes</emphasis> to all questions. This enables you to run an automated, unattended compose.</entry> </row> <row> @@ -135,7 +135,7 @@ <entry>global, model</entry> </row> <row> - <entry namest="column25" nameend="column89">Should Revisor not clean up at all (0), clean up it's temporary build data (1), or everything -this includes the yum cache (2).</entry> + <entry namest="column25" nameend="column89">Should Revisor not clean up at all (0), clean up it's temporary build data (1), or everything (2). Note that <emphasis>everything</emphasis> includes the yum cache.</entry> </row> <row> @@ -148,7 +148,9 @@ <entry>global, model</entry> </row> <row> - <entry namest="column25" nameend="column89">A directory tree to copy onto the media created. In the case of installation media, the contents of the directory specified are copied onto <code>cdrom:/files/</code>. In the case of live media, the contents of the directory specified are copied onto the root filesystem of the live system.</entry> + <entry namest="column25" nameend="column89"> + A directory tree to copy onto the media created. In the case of installation media, the contents of the directory specified are copied onto <code>cdrom:/files/</code>. In the case of live media, the contents of the directory specified are copied onto the root filesystem of the live system. See also <xref linkend="Reference-HOWTO-Include_folders_and_files_on_the_Media" />. + </entry> </row> <row> @@ -282,6 +284,19 @@ </row> <row> + <entry namest="column1" nameend="column25"><literal>kickstart_repos</literal></entry> + <entry namest="column67" nameend="column89"><literal>--kickstart-repos</literal></entry> + </row> + <row> + <entry namest="column25">0, 1</entry> + <entry>0</entry> + <entry>global, model</entry> + </row> + <row> + <entry namest="column25" nameend="column89">Whether to use the <code>repo</code> directives in the kickstart provided to Revisor. Useful in cases where the <code>repo</code> directive in the kickstart file provided points to an arbitrary repository such as a repository mirrored by Cobbler, since there is no default URI location for those repositories -and Cobbler refers to them in the kickstart (template) using <code>$yum_repo_stanza</code></entry> + </row> + + <row> <entry namest="column1" nameend="column25"><literal>kickstart_save</literal></entry> <entry namest="column67" nameend="column89"><literal>--kickstart-save</literal></entry> </row> @@ -416,8 +431,8 @@ <entry namest="column67" nameend="column89"><literal>--model</literal></entry> </row> <row> - <entry namest="column25"> </entry> - <entry><code>[model]</code></entry> + <entry namest="column25"><code>[model]</code></entry> + <entry> </entry> <entry>global</entry> </row> <row> diff --git a/doc/Reference_Manual/en-US/Preface.xml b/doc/Reference_Manual/en-US/Preface.xml index c736cd3..c0439f4 100644 --- a/doc/Reference_Manual/en-US/Preface.xml +++ b/doc/Reference_Manual/en-US/Preface.xml @@ -23,7 +23,7 @@ <formalpara> <title>Contributors</title> <para> - <emphasis>Jonathan Steffan</emphasis> is a community volunteer based in Colorado, USA, and has a long standing record within Fedora for packaging Zope (Web Application Server), Plone (Open Source Content Management System), providing compat-python2.4 packages for Fedora 7 and 8, and voluntarily administering the Fedora Unity servers, Zope and Plone instances, creating and further developing Revisor and pyJigdo. + <emphasis>Jonathan Steffan</emphasis> is a community volunteer based in Colorado, USA, and has a long standing record within Fedora for packaging Zope (Web Application Server), Plone (Open Source Content Management System), providing compat-python2.4 packages through Livna<footnote><para>Livna (<ulink url="http://livna.org" />) merged into RPMFusion after having offered numerous free and non-free packages through a third-party repository</para></footnote> and RPMFusion<footnote><para>RPMFusion (<ulink url="http://rpmfusion.org" />) is the best & largest third-party addon repository to Fedora and Enterprise Linux, with free and nonfree packages</para></footnote> ever since Fedora 7, and voluntarily administering the Fedora Unity servers, Zope and Plone instances, creating and further developing Revisor and pyJigdo, amongst many other things. </para> </formalpara> </section> diff --git a/doc/Reference_Manual/en-US/Reference-Configuration.xml b/doc/Reference_Manual/en-US/Reference-Configuration.xml index 49c6f6a..0a94819 100644 --- a/doc/Reference_Manual/en-US/Reference-Configuration.xml +++ b/doc/Reference_Manual/en-US/Reference-Configuration.xml @@ -7,11 +7,14 @@ <para> Revisor configuration can be performed using <xref linkend="Reference-Configuration-Files" />, or through <xref linkend="Reference-Configuration-Command-line_Options" />. </para> + <para> + We seriously recommend you consider configuration files for products you are going to have to build more then once, or for seriously complex products that make use of Revisor functions beyond what is a simple click-and-go exercise, such as rebranding and other advanced customization. On the other hand, if you are just to try one or two simple things just for this once, command-line options might be more suitable. + </para> <section id="Reference-Configuration-Files"> <title>Configuration Files</title> <para> - Revisor uses configuration files for a large part of it's operations. These files mostly reside in <filename>/etc/revisor/</filename>. There is two types of files Revisor uses: + Revisor uses configuration files for a large part of it's operations. These files mostly reside in <filename>/etc/revisor/</filename>. There is two types of configuration files Revisor uses: </para> <para> <orderedlist> @@ -56,7 +59,7 @@ <formalpara> <title><literal>[<replaceable>model</replaceable>]</literal></title> <para> - Model configuration. One section per <xref linkend="Reference-Appendix-Terminology-model" />. + Model configuration. You use one section per <xref linkend="Reference-Appendix-Terminology-model" />, and each section represents a <emphasis>product</emphasis>. </para> </formalpara> <para> @@ -75,21 +78,24 @@ To see what models are available with the Revisor standard package, use: </para> <para> - <screen>$ <userinput>revisor --list-models</userinput></screen> + <screen># <userinput>revisor --list-models</userinput></screen> </para> </section> <section id="Reference-Configuration-Files-_etc_revisor_conf.d_"> <title><filename>/etc/revisor/conf.d/</filename></title> <para> - The default YUM configuration files used by Revisor. In a model configuration section, the <literal>main =</literal> setting points to one of the YUM configuration files in <filename>/etc/revisor/conf.d/</filename> + The default YUM configuration files used by Revisor. In a model configuration section, the <code>main =</code> setting points to one of the YUM configuration files in <filename>/etc/revisor/conf.d/</filename>. + </para> + <para> + The YUM configuration files configure the repositories available during a product compose, as well as the available architectures. </para> </section> <section id="Reference-Configuration-Files-Updates"> <title>Updates to Configuration Files</title> <para> - The Revisor packages are not allowed to overwrite files in <filename>/etc/</filename>, and they should thus not do so. If an update to Revisor is installed on your system, files with the extension <literal>.rpmnew</literal> may be created --if you had changed anything in the file before applying the update. Since this world isn't perfect, configuration errors may exist in the configuration files shipped with Revisor. Please pay close attention to updates to these configuration files by examining the <literal>.rpmnew</literal> files. + The Revisor packages (or any packages in Fedora for that matter) are not allowed to overwrite existing configuration files in <filename>/etc/</filename>, and they should thus not do so. Users anticipate that if they change a file in <filename>/etc/</filename> these changes are persistent in that they are not destroyed when a package is updated. If an update to Revisor is installed on your system, files with the extension <literal>.rpmnew</literal> may be created --if you had changed anything in the file before applying the update. Since this world isn't perfect, configuration errors may exist in the configuration files shipped with Revisor. Please pay close attention to updates to these configuration files by searching for and examining the <literal>.rpmnew</literal> files. </para> <para> You can use any file location (not just <filename>/etc/revisor/</filename>) for your own custom configuration. @@ -131,7 +137,9 @@ For example, if you know all the models in a configuration file are optical live media products, the configuration sections could look like the following: </para> <para> - <screen>[revisor] + <example> + <title>Example revisor.conf global vs. model configuration</title> + <screen>[revisor] # Optical live media for all models media_live_optical = 1 @@ -141,7 +149,9 @@ description = The model1 product architecture = i386 # This is already configured in the global section of # this configuration file and can thus be removed. -#media_live_optical = 1</screen> +#media_live_optical = 1 + </screen> + </example> </para> <note> <title>When Running the GUI</title> @@ -154,7 +164,7 @@ architecture = i386 <section id="Reference-Configuration-Yum_Repositories"> <title>YUM Repository Configuration</title> <para> - The files in <filename>/etc/revisor/conf.d/</filename> are YUM configuration files. Revisor directs YUM to use these files during the compose process, and does not handle these files itself. This chapter lists a few tips and tricks. + The files in <filename>/etc/revisor/conf.d/</filename> are YUM configuration files. Revisor directs YUM through its API to use these files during the compose process, and does not handle these files itself. This chapter explains how these files are used, how you can change them and lists a few tips and tricks. </para> <para> Because these files are YUM Configuration files, you can configure anything that YUM supports. See <application>man yum.conf</application> for more details. @@ -163,7 +173,7 @@ architecture = i386 <section id="Reference-Configuration-Yum_Repositories-releasever_and_basearch"> <title>$releasever and $basearch</title> <para> - When configuring a repository URL, make sure you do not use <replaceable>$releasever</replaceable> or <replaceable>$basearch</replaceable> variables. Since Revisor allows cross-composing distributions between different versions of the operating system, as well as different architectures, these variables need to be expanded to the value intended. + When configuring a repository URL, make sure you do not use <replaceable>$releasever</replaceable> or <replaceable>$basearch</replaceable> variables. Since Revisor allows cross-composing distributions between different versions of the operating system, as well as different architectures, these variables need to be expanded to the value intended. Ergo, if a repository configuration has <ulink url="http://server/repo/$releasever/$basearch/" />, for a Fedora 12 i386 YUM configuration file you would need to change such in <ulink url="http://server/repo/12/i386/" />. </para> <para> See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> @@ -188,7 +198,7 @@ architecture = i386 </para> </note> <para> - Set each <literal>baseurl</literal> to the location of the repository on the local mirror. + Alternatively, you can set each <literal>baseurl</literal> directive to the location of the repository on the local mirror. </para> <para> See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> @@ -217,7 +227,10 @@ architecture = i386 A DVD does not contain enough packages to rebuild the installer images. If you are using a DVD and you want to rebuild the installer images, you will need to have a network connection and a mirror you can reach. </para> <para> - There is a list of required packages, but since the packages change per release and may change in the middle of the release cycle as well, we cannot hand you a list that just works. + If you have no need for rebuilding the installer images, make sure you configure Revisor to not rebuild the installer. There's a HOWTO on the subject in <xref linkend="Reference-HOWTO-Reuse_Installer_Images" />. + </para> + <para> + There is a list of required packages, but since the packages change per release and may change in the middle of the release cycle as well, we cannot hand you a list that just works. If you really want to know though, the list of packages are in Revisor's <filename>cfg.py</filename>. Maybe you can write a plugin with a command-line option that spits out the required packages per model, and optionally download all of them, and create a repository out of the downloaded packages. If you do so, please let us know at the Revisor Development mailing-list at <ulink url="https://fedorahosted.org/mailman/listinfo/revisor-devel" />, and we'll be glad to help you out or maintain the plugin upstream. </para> <para> See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> @@ -230,6 +243,9 @@ architecture = i386 When adding a third party repository, make sure you add the correct release version as well as architecture to the Revisor YUM configuration file. Verify the location for the <literal>baseurl</literal> and/or <literal>mirrorlist</literal> you configure manually or through YUM. Make sure you expand any <literal>$releasever</literal>, <literal>$basearch</literal> and <literal>$arch</literal> variables. </para> <para> + There's a HOWTO on adding third party repositories included in this document at <xref linkend="Reference-HOWTO-Add_a_Third_Party_Repository" />. + </para> + <para> See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> </para> </section> @@ -243,7 +259,7 @@ architecture = i386 People often wonder how Revisor handles comps.xml group files. </para> <para> - When you create your own repository, follow the directions in <xref linkend="Reference-Configuration-Yum_Repositories-Adding_Third_Party_Repositories" /> to add the repository configuration to Revisor's YUM configuration, since your own repository is a third party repository as well. + When you create your own repository, essentially a third party repository, follow the directions in <xref linkend="Reference-HOWTO-Add_a_Third_Party_Repository" /> to add the repository configuration to Revisor's YUM configuration, since your own repository is a third party repository as well. </para> <para> See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> @@ -253,7 +269,25 @@ architecture = i386 <section id="Reference-Configuration-Yum_Repositories-Troubleshooting"> <title>Testing & Troubleshooting the YUM Configuration</title> <para> - Before you use the (modified) configuration file, take it for a test run. + Before you use the (modified) configuration file, take it for a test run to see if you have configured YUM properly. + </para> + <procedure> + <title>Testing a YUM configuration file</title> + <step> + <para> + <screen># <userinput>yum -c <filename><replaceable>/path/to/configuration/file</replaceable></filename> \</userinput> + <userinput>clean all</userinput></screen> + </para> + </step> + <step> + <para> + <screen># <userinput>yum -c <filename><replaceable>/path/to/configuration/file</replaceable></filename> \</userinput> + <userinput>list kernel</userinput></screen> + </para> + </step> + </procedure> + <para> + Should this show errors, or fail otherwise, add <literal>-d 9</literal> to the command line in order to have YUM spit out more detailed debugging output. This detailed output should leave you a clue or two about what might be wrong with the configuration. </para> </section> @@ -262,18 +296,21 @@ architecture = i386 <section id="Reference-Configuration-Configuring_A_Proxy"> <title>Configuring A Proxy Server</title> <para> - para + Configuring a Proxy server to be used can be done through YUM, using the <code>proxy=</code> configuration directive. </para> </section> <section id="Reference-Configuration-Command-line_Options"> <title>Command-line Options</title> <para> - With the command-line options available, you can configure options that either override what is in the configuration file or have simply not been configured using the configuration file. With the default configuration files that come with the <application>revisor-cli</application> package for example, no media products have been pre-configured in the default section. In the <application>revisor-unity</application> package however, some default configuration has been applied so that Fedora Unity Re-Spins actually create CD, DVD and Rescue ISO images as well as the Installation Tree and include the sources. + With the command-line options available, you can configure options that either override what is in the configuration file or have simply not been configured using the configuration file. With the default configuration files that come with the <application>revisor-cli</application> package for example, no media products have been pre-configured in the global configuration section. In the <application>revisor-unity</application> package however, some default configuration has been applied so that Fedora Unity Re-Spins actually create CD, DVD and Rescue ISO images as well as the Installation Tree, and include the sources. </para> <para> Only some configuration options have CLI parameters. Use <application>revisor --help</application> to see a complete list of configuration options you can supply on the command line. </para> + <para> + Note that command-line options always override the configuration settings supplied in the configuration files. Additionally, when using the graphical user interface, command-line options can be overriden by GUI interaction. + </para> </section> </chapter> diff --git a/doc/Reference_Manual/en-US/Reference-Features.xml b/doc/Reference_Manual/en-US/Reference-Features.xml index 193bb7a..8b31cc0 100644 --- a/doc/Reference_Manual/en-US/Reference-Features.xml +++ b/doc/Reference_Manual/en-US/Reference-Features.xml @@ -8,13 +8,13 @@ Revisor allows you to build and customize your own Remix, Re-Spin, Spin or even your own distribution, based on Fedora and derivative distributions such as Red Hat Enterprise Linux and CentOS. </para> <para> - Revisor builds installation media, live media, installation trees, cobbler distro's and profiles, virtualization images and more. + Revisor builds installation media, live media, installation trees, cobbler distro's and profiles, virtualization images and more. We'll now briefly explain what each of these terms mean and what Revisor can (or cannot) do for you. </para> <section id="Reference-Features-Installation_Media"> <title>Installation Media</title> <para> - Installation media is what you use to install a system with. The installation media composed will allow you to go through the installation process, answering a number of questions (either manually or through kickstart), and ends up in a system running the distribution you install. + Installation media is what you normally use to install a system with. The installation media composed will allow you to go through the installation process, answering a number of questions (either manually or through kickstart), and ends up in a system running the distribution you install. </para> <para> Composing installation media using the Revisor GUI allows you to choose the media (CD, or DVD), the packages to be included on the media (also called <emphasis>RPM payload</emphasis>). @@ -114,7 +114,14 @@ <section id="Reference-Features-Extraneous_Debugging"> <title>Extraneous Debugging</title> <para> - Revisor has extraneous debugging, which enables you, as well as the supporters and Revisor's developers, to trace down what happens exactly, and where anything might go wrong. + Revisor has extraneous debugging, which enables you, as well as the supporters and Revisor's developers, to trace down what happens exactly, and where anything might have gone wrong. + </para> + </section> + + <section id="Reference-Features-Smart_Caching"> + <title>Smart Caching</title> + <para> + Revisor is one of the utilities that uses the same cache over and over again, across multiple product composes. If you have downloaded something once, chances are you're going to need to download it again and again especially if you are a frequent user of the compose tools. Revisor caches all the downloaded packages in <filename>/var/tmp/revisor-yumcache/</filename> (by default), enabling you to download just once and never again. </para> </section> diff --git a/doc/Reference_Manual/en-US/Reference-HOWTO.xml b/doc/Reference_Manual/en-US/Reference-HOWTO.xml new file mode 100644 index 0000000..a7ce19b --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-HOWTO.xml @@ -0,0 +1,65 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-HOWTO"> + <title>HOWTO</title> + <para> + This chapter includes a couple of HOWTOs on use-cases that Revisor serves. + </para> + + <section id="Reference-HOWTO-Add_a_Third_Party_Repository"> + <title>HOWTO: Add a Third Party Repository</title> + <para> + para + </para> + </section> + + <section id="Reference-HOWTO-Create-a-Re-Spin"> + <title>HOWTO: Create a Re-Spin</title> + <para> + Fedora Unity is famous for creating Re-Spins, amongst other things. This, however, does not mean you need to be some kind of guru or spins master to create your own Re-Spin ;-) + </para> + <para> + This is a HOWTO on composing a Re-Spin, but does not include testing the Re-Spin. Maybe it will include testing the Re-Spin as soon as we get someone on board willing to write about it ;-) + </para> + <procedure> + <step> + <para> + First, install the <application>revisor-unity</application> package: + </para> + <para> + <screen># <userinput>yum -y install revisor-unity</userinput></screen> + </para> + <para> + The <application>revisor-unity</application> package includes the configuration files Fedora Unity uses to execute automatic and unattended composes for Re-Spins. + </para> + </step> + <step> + <para> + Execute the following for a x86_64 version of a Fedora 12 Re-Spin: + </para> + <para> + <screen># <userinput>revisor --cli --config /etc/revisor-unity/f12-install-respin.conf \</userinput> + <userinput>--model f12-x86_64-respin</userinput></screen> + </para> + </step> + </procedure> + </section> + + <section id="Reference-HOWTO-Include_folders_and_files_on_the_Media"> + <title>HOWTO: Include folders and files on the Media</title> + <para> + para + </para> + </section> + + <section id="Reference-HOWTO-Reuse_Installer_Images"> + <title>HOWTO: Re-use Installer Images</title> + <para> + para + </para> + </section> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Installation.xml b/doc/Reference_Manual/en-US/Reference-Installation.xml index 5f1f89a..b9833b8 100644 --- a/doc/Reference_Manual/en-US/Reference-Installation.xml +++ b/doc/Reference_Manual/en-US/Reference-Installation.xml @@ -38,7 +38,7 @@ <section id="Reference-Installation-Packages-YUM-RHEL"> <title>Red Hat Enterprise Linux 5 or higher</title> <para> - On Red Hat Enterprise Linux 5 or higher, and derivatives, install the Extra Packages for Enterprise Linux (EPEL) repository. + On Red Hat Enterprise Linux 5 or higher, and derivatives, install the Extra Packages for Enterprise Linux<footnote><para>Extra Packages for Enterprise Linux: <ulink url="http://fedoraproject.org/wiki/EPEL" /></para></footnote> (EPEL) repository. </para> <para> Then, give the following command: diff --git a/doc/Reference_Manual/en-US/Reference-Introduction.xml b/doc/Reference_Manual/en-US/Reference-Introduction.xml index a6bd7a7..d59fc7a 100644 --- a/doc/Reference_Manual/en-US/Reference-Introduction.xml +++ b/doc/Reference_Manual/en-US/Reference-Introduction.xml @@ -32,7 +32,7 @@ </para> </formalpara> <para> - Fedora Unity decided Revisor could accomplish more then just being a front-end to existing compose tools and enable someone to tweak a lot of settings as well. In March 2007, Revisor was rebuild from the ground up in March 2007 to allow a more flexible process, more dependent on the configuration directives it was given and less so on the processes of the existing tools. When in San Diego at the Red Hat Summit (early May 2007), Robert 'Bob' Jensen and Jonathan Steffan gave a presentation on “Customizing Fedora”, the responses were amazing. Since then Revisor has evolved from a front-end to existing tools to the complete compose tool it is today, with lots of configuration options for specific use-cases. + Fedora Unity decided Revisor could accomplish more then just being a front-end to existing compose tools and enable someone to tweak a lot of settings as well. In March 2007, Revisor was rebuilt from the ground up in order to allow a more flexible process, neing more dependent on the configuration directives it was given from configuration files, command-line parameters and the graphical user interface, and less so on the processes of the existing tools. When in San Diego at the Red Hat Summit (early May 2007), Robert 'Bob' Jensen and Jonathan Steffan gave a presentation on “Customizing Fedora”, the responses were amazing. Since then Revisor has evolved from a front-end to existing tools to the complete compose tool it is today, with lots of configuration options for specific use-cases. </para> <para> For users, Revisor is particularly useful because it has a GUI front-end wizard, which, with the defaults settings, will just succeed in getting a user the media he/she wants. If a user decides he needs little adjustment of the media, the GUI allows for selecting the most common options. If a user decides he needs some less common adjustments, the configuration options gives him very granular control -and as long as the documentation on all the options is sufficient, users will be able to make those less common adjustments. @@ -54,10 +54,10 @@ <emphasis>When a user downloads a Fedora release and installs the distribution, the user will need to download and install a number of updates. The “older” the release becomes, the more updates will be available, and the greater the total download size of these updates the user will need to download on top of the download size of the original release media.</emphasis> </para> <para> - “older” is in quotes on purpose, because really for an operating system -or “distribution” if you will- being released every 6 months, “old” is quite a relative concept. The number of updates available however, at any given time during the release cycle, may range from 0 right after the release (which has never happened before), to the total amount of packages installed on the user's system (often over 2000). You can imagine the size of these updates ranging from 0 MB to an astonishing 2GB(!), only 6 months after the initial release. + “older” is in quotes on purpose, because really for an operating system -or “distribution” if you will- being released every 6 months, “old” is quite a relative concept. The number of updates available however, at any given time during the release cycle, may range from 0 right after the release (which has never happened before), to the total amount of packages installed on the user's system (often over 2000). You can imagine the size of these updates ranging from 0 MB to an astonishing 2GB(!), only 6 months after the initial release. A single Fedora release has a support cycle of 13 months. </para> <para> - Some of us do not have the bandwidth capacity or enough data transfer quota to download this many extra, rather useless bits. In addition, some of us do not have an Internet connection at all, and thus benefit getting the updates from Re-Spins directly. + Some of us do not have the bandwidth capacity or enough data transfer quota to download this many extra, rather useless bits. In addition, some of us do not have an Internet connection at all, and those benefit from getting the updates through Re-Spins as well. </para> <para> The use of updates in Re-Spins has several more beneficial side-effects, which we'll explain in more detail later on in this document. Long story short; If for some reason the software used to compose the media (the release) with does not work for your hardware or your specific needs, updated software incorporated in the composed installer images might resolve that problem. @@ -70,7 +70,7 @@ <section id="Reference-Introduction-The_Live_Media_Challenge"> <title>The Live Media Challenge</title> <para> - Back in the day Fedora Core 5 was the most recent release, Fedora Unity created so-called live media using Kadischi. In that time, live media could only have a read-only root file system and was not as feature-rich as live media is today. However, just before Revisor came to life, two applications were developed; pungi for creating installation media, and livecd-tools for creating live media. These two applications did their work well; The media composed for a release, including many different custom live media spins were, and still are, created with these tools. Immediately, the Revisor developers set themselves a target to provide a single interface to both of those tools. + Back in the day Fedora Core 5 was the most recent release, Fedora Unity created so-called live media using Kadischi, then actively developed by Jasper Hartline, another valued Fedora Unity member. In those days, live media could only have a read-only root file system and was not as feature-rich as live media is today. However, just before Revisor came to life, two applications were developed; pungi for creating installation media, and livecd-tools for creating live media. These two applications did their work well; The media composed for a genuine Fedora release, including many different custom live media spins were, and still are, created with these tools, not to mention the many downstream consumers that use these tools to do the exact same thing. Immediately, the Revisor developers set themselves a target to provide a single interface to both of those tools, and give the user more flexibility so that the user could bend the rules without breaking them. </para> </section> diff --git a/doc/Reference_Manual/en-US/Reference-Quick_Start.xml b/doc/Reference_Manual/en-US/Reference-Quick_Start.xml new file mode 100644 index 0000000..43df0cb --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Quick_Start.xml @@ -0,0 +1,60 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Quick_Start"> + <title>Quick Start</title> + <para> + This is a quick start guide to get you on your feet using Revisor really quickly, without any modifications, advanced options, whatsoever. + </para> + <para> + When you execute Revisor for the first time, the following screen appears: + </para> + <figure> + <title>Revisor Welcome Screen</title> + <screenshot> + <mediaobject> + <objectinfo id="revisor_welcome_screen"> + <title>Revisor Welcome Screen</title> + </objectinfo> + <imageobject> + <imagedata fileref="images/Screenshot-Revisor.png" format="PNG" /> + </imageobject> + </mediaobject> + </screenshot> + </figure> + <para> + The first thing you'll notice, is that the Advanced Options are disabled. Don't worry, as the advanced options are very limited at this point and do not get you anywhere right now. Press <guibutton>Get Started</guibutton> to get started. + </para> + <figure> + <title>Select Media Type(s)</title> + <screenshot> + <mediaobject> + <objectinfo id="select_media_types"> + <title>Select Media Types</title> + </objectinfo> + <imageobject> + <imagedata fileref="images/Screenshot-Revisor-1.png" format="PNG" /> + </imageobject> + </mediaobject> + </screenshot> + </figure> + <para> + Select the DVD Set to compose installation media with the maximum size of a DVD per disc. + </para> + <figure> + <title>Select DVD Set</title> + <screenshot> + <mediaobject> + <objectinfo id="select_dvd_set"> + <title>Select DVD Set</title> + </objectinfo> + <imageobject> + <imagedata fileref="images/Screenshot-Revisor-2.png" format="PNG" /> + </imageobject> + </mediaobject> + </screenshot> + </figure> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference.xml b/doc/Reference_Manual/en-US/Reference.xml index 0e7af68..6fbfd05 100644 --- a/doc/Reference_Manual/en-US/Reference.xml +++ b/doc/Reference_Manual/en-US/Reference.xml @@ -8,16 +8,30 @@ <xi:include href="Reference-Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <xi:include href="Reference-Features.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Reference-Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Reference-Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Reference-Using_Kickstart.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Reference-Compose_Process_Details.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Reference-Plugins.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Reference-Tweaking_The_Build_Process.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Reference-Tips_and_Tricks.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Reference-Frequently_Asked_Questions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Reference-Testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Reference-Development.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <part id="Reference-Getting_Started"> + <title>Getting Started</title> + <xi:include href="Reference-Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Quick_Start.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </part> + + <part id="Reference-Manual"> + <title>Manual</title> + <xi:include href="Reference-HOWTO.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Using_Kickstart.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </part> + + <part id="Reference-Reference"> + <title>Reference</title> + <xi:include href="Reference-Compose_Process_Details.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Plugins.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Tweaking_The_Build_Process.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Tips_and_Tricks.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Frequently_Asked_Questions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Development.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </part> <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> <index /> diff --git a/doc/Reference_Manual/en-US/images/Screenshot-1.png b/doc/Reference_Manual/en-US/images/Screenshot-1.png new file mode 100644 index 0000000..200b06b Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-1.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-2.png b/doc/Reference_Manual/en-US/images/Screenshot-2.png new file mode 100644 index 0000000..a34937f Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-2.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Choose a file or folder.png b/doc/Reference_Manual/en-US/images/Screenshot-Choose a file or folder.png new file mode 100644 index 0000000..44d15d0 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Choose a file or folder.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Packages in KDE (K Desktop Environment).png b/doc/Reference_Manual/en-US/images/Screenshot-Packages in KDE (K Desktop Environment).png new file mode 100644 index 0000000..c6412a8 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Packages in KDE (K Desktop Environment).png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Revisor-1.png b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-1.png new file mode 100644 index 0000000..ea634c7 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-1.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Revisor-2.png b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-2.png new file mode 100644 index 0000000..b1d9bc6 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-2.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Revisor-3.png b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-3.png new file mode 100644 index 0000000..94cd4e8 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-3.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Revisor-4.png b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-4.png new file mode 100644 index 0000000..4261c9e Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-4.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Revisor-5.png b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-5.png new file mode 100644 index 0000000..d5e3c2c Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-5.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Revisor-6.png b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-6.png new file mode 100644 index 0000000..7d76db1 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-6.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Revisor-7.png b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-7.png new file mode 100644 index 0000000..462b780 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-7.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Revisor-8.png b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-8.png new file mode 100644 index 0000000..139a088 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-8.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Revisor-9.png b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-9.png new file mode 100644 index 0000000..d47e545 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Revisor-9.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Revisor.png b/doc/Reference_Manual/en-US/images/Screenshot-Revisor.png new file mode 100644 index 0000000..32a0d32 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Revisor.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Warning-1.png b/doc/Reference_Manual/en-US/images/Screenshot-Warning-1.png new file mode 100644 index 0000000..29edf31 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Warning-1.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot-Warning.png b/doc/Reference_Manual/en-US/images/Screenshot-Warning.png new file mode 100644 index 0000000..d099e99 Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot-Warning.png differ diff --git a/doc/Reference_Manual/en-US/images/Screenshot.png b/doc/Reference_Manual/en-US/images/Screenshot.png new file mode 100644 index 0000000..419c20d Binary files /dev/null and b/doc/Reference_Manual/en-US/images/Screenshot.png differ commit 7e34e4f80fde6e75f0eadd784278ad1c2b2a05a7 Author: Jeroen van Meeuwen (Fedora Unity) <kanarip(a)fedoraunity.org> Date: Fri Dec 25 02:59:35 2009 +0100 Update documentation for new publican diff --git a/doc/Reference_Manual/en-US/Appendix.xml b/doc/Reference_Manual/en-US/Appendix.xml index f08fc79..dad871e 100644 --- a/doc/Reference_Manual/en-US/Appendix.xml +++ b/doc/Reference_Manual/en-US/Appendix.xml @@ -2,12 +2,12 @@ <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> -<part id="Revisor_Reference_Manual-Appendices"> +<part id="Reference-Appendices"> <title>Appendices</title> - <appendix id="Revisor_Reference_Manual-Appendix-Terminology" label="A"> + <appendix id="Reference-Appendix-Terminology" label="A"> <title>Terminology</title> - <formalpara id="Revisor_Reference_Manual-Appendix-Terminology-model"> + <formalpara id="Reference-Appendix-Terminology-model"> <title>Model</title> <indexterm> <primary>model</primary> @@ -17,7 +17,7 @@ </para> </formalpara> - <formalpara id="Revisor_Reference_Manual-Appendix-Terminology-package_manifest"> + <formalpara id="Reference-Appendix-Terminology-package_manifest"> <title>Package Manifest</title> <indexterm> <primary>Package Manifest</primary> @@ -27,7 +27,7 @@ </para> </formalpara> - <formalpara id="Revisor_Reference_Manual-Appendix-Terminology-Remix"> + <formalpara id="Reference-Appendix-Terminology-Remix"> <title>Remix</title> <indexterm> <primary>Remix</primary> @@ -37,7 +37,7 @@ </para> </formalpara> - <formalpara id="Revisor_Reference_Manual-Appendix-Terminology-Re-Spin"> + <formalpara id="Reference-Appendix-Terminology-Re-Spin"> <title>Re-Spin</title> <indexterm> <primary>Re-Spin</primary> @@ -51,7 +51,7 @@ Fedora Unity releases Fedora Re-Spins every so often, twice or trice per release. </para> - <formalpara id="Revisor_Reference_Manual-Appendix-Terminology-Spin"> + <formalpara id="Reference-Appendix-Terminology-Spin"> <title>Spin</title> <indexterm> <primary>Spin</primary> @@ -64,7 +64,7 @@ Fedora Spins have gone through the Spins Process (<ulink url="http://fedoraproject.org/wiki/Spins_Process" />), and have been approved trademark usage by the Fedora Project Board. </para> - <formalpara id="Revisor_Reference_Manual-Appendix-Terminology-Package_Sack"> + <formalpara id="Reference-Appendix-Terminology-Package_Sack"> <title>Package Sack</title> <indexterm> <primary>Package Sack</primary> @@ -75,13 +75,13 @@ </formalpara> </appendix> - <appendix id="Revisor_Reference_Manual-Appendix-Configuration_Reference" label="B"> + <appendix id="Reference-Appendix-Configuration_Reference" label="B"> <title>Configuration Reference</title> <para> This is the configuration reference for Revisor. Options are listed in alphabetical order. </para> - <section id="Revisor_Reference_Manual-Appendix-Configuration_Reference-Media_Options"> + <section id="Reference-Appendix-Configuration_Reference-Media_Options"> <title>Configuration Options</title> <para> <table> @@ -213,7 +213,7 @@ <entry>global, model</entry> </row> <row> - <entry namest="column25" nameend="column89">Whether to include the relatively large boot.iso on the optical installation media created. Setting this to 0 will still include boot.iso in the installation tree created (if configured with <code>media_installation_tree</code><footnote><para>Note that the installation tree is always created. See <xref linkend="Revisor_Reference_Manual-Compose_Process_Details" /> for more details.</para></footnote>)</entry> + <entry namest="column25" nameend="column89">Whether to include the relatively large boot.iso on the optical installation media created. Setting this to 0 will still include boot.iso in the installation tree created (if configured with <code>media_installation_tree</code><footnote><para>Note that the installation tree is always created. See <xref linkend="Reference-Compose_Process_Details" /> for more details.</para></footnote>)</entry> </row> <row> @@ -382,7 +382,7 @@ <entry>global, model</entry> </row> <row> - <entry namest="column25" nameend="column89">Whether to create a an installation tree<footnote><para>Note that the installation tree is always created. See <xref linkend="Revisor_Reference_Manual-Compose_Process_Details" /> for more details.</para></footnote> (for publication over HTTP or FTP, or through Cobbler). No size limit.</entry> + <entry namest="column25" nameend="column89">Whether to create a an installation tree<footnote><para>Note that the installation tree is always created. See <xref linkend="Reference-Compose_Process_Details" /> for more details.</para></footnote> (for publication over HTTP or FTP, or through Cobbler). No size limit.</entry> </row> <row> @@ -447,7 +447,7 @@ <entry>global, model</entry> </row> <row> - <entry namest="column25" nameend="column89">Whether Revisor should operate in <emphasis>respin</emphasis> mode. See also <xref linkend="Revisor_Reference_Manual-Compose_Process_Details-Respin_Mode" /></entry> + <entry namest="column25" nameend="column89">Whether Revisor should operate in <emphasis>respin</emphasis> mode. See also <xref linkend="Reference-Compose_Process_Details-Respin_Mode" /></entry> </row> <row> diff --git a/doc/Reference_Manual/en-US/Book_Info.xml b/doc/Reference_Manual/en-US/Book_Info.xml index 31d0e76..9c5be09 100644 --- a/doc/Reference_Manual/en-US/Book_Info.xml +++ b/doc/Reference_Manual/en-US/Book_Info.xml @@ -2,16 +2,13 @@ <!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> -<bookinfo id="Revisor_Reference_Manual-Documentation"> - <title>Reference Manual</title> +<bookinfo id="Reference-Documentation"> + <title>Reference</title> <subtitle>Revisor Complete Installation, Configuration and Tweaking Reference</subtitle> <productname>Revisor</productname> - <productnumber>2.1.5</productnumber> - - <abstract> <para> This is Revisors upstream documentation. diff --git a/doc/Reference_Manual/en-US/Preface.xml b/doc/Reference_Manual/en-US/Preface.xml index 529b5be..c736cd3 100644 --- a/doc/Reference_Manual/en-US/Preface.xml +++ b/doc/Reference_Manual/en-US/Preface.xml @@ -2,13 +2,13 @@ <!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> -<preface id="Revisor_Reference_Manual-Preface"> +<preface id="Reference-Preface"> <title>Preface</title> <para> This is the documentation for Revisor, a utility to create and customize your own Linux distribution based on Fedora, Red Hat Enterprise Linux or CentOS. This is also known as a Remix, or Re-Spin, or Re-Master. You may create anything you want with Revisor no matter what it's called though. </para> - <section id="Revisor_Reference_Manual-Preface-About_The_Contributors"> + <section id="Reference-Preface-About_The_Contributors"> <title>About the Contributors</title> <formalpara> <title>Author</title> @@ -28,7 +28,7 @@ </formalpara> </section> - <section id="Revisor_Reference_Manual-Preface-About_Fedora_Unity"> + <section id="Reference-Preface-About_Fedora_Unity"> <title>About Fedora Unity</title> <para> The Fedora Unity Project consists of a group of concerned peers from within the Fedora community that strive to bring the best possible solutions to the community, in a consistent manner. This, amongst other things, resulted in extensive documentation on various topics often referred to on the Web, published under the Open Documentation License v1.0. @@ -38,7 +38,7 @@ </para> </section> - <section id="Revisor_Reference_Manual-Preface-About_This_Document"> + <section id="Reference-Preface-About_This_Document"> <title>About this Document</title> <para> This document is licensed under the Open Publication License version 1.0, which is available at <ulink url="http://www.opencontent.org/openpub/" />. You can get the latest version from <ulink url="http://kanarip.fedorapeople.org/Revisor_Reference_Manual/en-US/pdf/Revisor_…" /> (PDF), and it's sources live at <ulink url="http://git.fedorahosted.org/git/?p=revisor;a=tree;f=doc" />. diff --git a/doc/Reference_Manual/en-US/Reference-Compose_Process_Details.xml b/doc/Reference_Manual/en-US/Reference-Compose_Process_Details.xml new file mode 100644 index 0000000..2085682 --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Compose_Process_Details.xml @@ -0,0 +1,431 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Compose_Process_Details"> + <title>Compose Process Details</title> + <para> + This chapter lists the details of the compose process as well as dives deep into the features of Revisor. + </para> + + <section id="Reference-Compose_Process_Details-Overview"> + <title>Overview</title> + <titleabbrev id="Compose_Process_Details-Overview">Overview</titleabbrev> + <para> + Of course, the compose process for installation media is a little different then the compose process for live media. + </para> + <para> + When composing, Revisor starts out doing the following: + </para> + <para> + <itemizedlist> + <listitem> + <para> + Revisor initiates and loads plugins, options, and defaults. At this point, Revisor has a so-called <emphasis>ConfigStore</emphasis> that holds all options Revisor knows about. + </para> + </listitem> + <listitem> + <para> + Revisor reads the options from the command-line. + </para> + </listitem> + <listitem> + <para> + Revisor reads the configuration file specified with the <code>--config</code> command-line parameter, or uses it's builtin default, <filename>/etc/revisor/revisor.conf</filename>. + </para> + </listitem> + <listitem> + <para> + Revisor reads the global <code>[revisor]</code> section for all settings available in it's <emphasis>ConfigStore</emphasis> and sets those configured in the global section. Remember that if an option is not available in the <emphasis>ConfigStore</emphasis> but is configured in the global configuration section, it is ignored. + </para> + </listitem> + <listitem> + <para> + If a model is specified in the configuration file's global section <code>[revisor]</code>, Revisor will set that model to be used and loads it. + </para> + </listitem> + <listitem> + <para> + If a model has been specified on the command-line, with option <code>--model</code>, Revisor loads that model. + </para> + </listitem> + <listitem> + <para> + When loading the model, Revisor again iterates over all the settings that are in the <emphasis>ConfigStore</emphasis>, checks if the setting has been configured in the model section, and adjusts the setting in the <emphasis>ConfigStore</emphasis> if necessary. Again remember that if the <emphasis>ConfigStore</emphasis> does not know about one or the other option already, that setting is ignored. + </para> + </listitem> + <listitem> + <para> + Now that the defaults and configuration file settings have been applied to the <emphasis>ConfigStore</emphasis>, it is time for Revisor to look at the options specified on the command-line to see if you wanted to override anything. + </para> + </listitem> + <listitem> + <para> + While loading each configuration setting available in the global <code>[revisor]</code>, model-specific sections and/or command-line, Revisor checks every settings against a function that is specifically written to check such setting. For example, the label of an ISO cannot be longer then 32 characters. + </para> + </listitem> + <listitem> + <para> + Especially in CLI mode, these settings build up the task list for Revisor. If there's nothing to do, Revisor will throw an error explaining what's missing. If there's things to do that cannot be done in one run, Revisor will throw an error explaining that. + </para> + </listitem> + <listitem> + <para> + In Graphical User Interface mode however, if the settings loaded so far are all OK, the GUI will start. Since you can still adjust a few settings from within the GUI, the settings loaded so far will be the defaults for configuration settings that have a dialog for you to adjust them with, throughout the rest of the process. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="Reference-Compose_Process_Details-Installation_Media"> + <title>Installation Media</title> + <para> + As we've explained before, composing installation media is a little different then composing live media. That's not just because installation media should start an installation procedure and live media should show you a nice, shiny, fully-functional Desktop. + </para> + <para> + For one, installation media allows split media. This means that Revisor can span the payload of the product over multiple ISO images or multiple discs, if you will. When composing installation media, Revisor basically does the following: + </para> + <para> + <itemizedlist> + <listitem> + <para> + Of course, Revisor goes through the loading of configuration options mentioned in the <xref linkend="Reference-Compose_Process_Details-Overview" endterm="Compose_Process_Details-Overview" />. + </para> + </listitem> + <listitem> + <para> + When you're done specifying options in the GUI, or when Revisor thinks it can go ahead using the options specified in CLI mode, it takes the list of packages selected from either the GUI or the kickstart <code>%packages</code> manifest. + </para> + <para> + Not getting too deep into details here, yet, because some of these things are routines shared with other composing modes, but here's a few additional considerations Revisor makes when doing the package selection. + </para> + <para> + <itemizedlist> + <listitem> + <para> + Normally, a kickstart <code>%packages</code> manifest only allows you to select package <emphasis>names</emphasis>. With Revisor though, you can select exact package <emphasis>NEVRA</emphasis> to select a certain version or architecture for the package that you want. Additionally, if a package is not available, Revisor searches the <emphasis>Provides</emphasis> of the available packages. + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="Reference-Compose_Process_Details-Live_Media"> + <title>Live Media</title> + <para> + para + </para> + </section> + + <section id="Reference-Compose_Process_Details-Respin_Mode"> + <title>Respin Mode</title> + <para> + Revisor has a respin mode that in some aspects differs from the regular routines. It is intended to reflect behaviour of tools in use by the Fedora Project Release Engineering team as closely as possible. + </para> + <para> + Re-Spin mode only affects installation media products. + </para> + <para> + In Re-Spin mode, the way the RPM payload is determined from kickstart differs from Revisor's normal procedures. See <xref linkend="Reference-Using_Kickstart" /> for more details on using a kickstart package manifest. + </para> + <para> + A kickstart file's so-called <xref linkend="Reference-Appendix-Terminology-package_manifest" /> usually looks like: + </para> + <para> + <screen>%packages +@group1 +@group2 --nodefaults +@group3 --optional +package1 +package2 +-package3 +%end</screen> + </para> + <para> + Which tells us the following: + </para> + <para> + <itemizedlist> + <listitem> + <para> + Include all mandatory and default packages from group1 + </para> + </listitem> + <listitem> + <para> + Include all mandatory packages from group2 + </para> + </listitem> + <listitem> + <para> + Include all mandatory, default and optional packages from group3 + </para> + </listitem> + <listitem> + <para> + Include package1, and package2 + </para> + </listitem> + <listitem> + <para> + Exclude package3 + </para> + </listitem> + </itemizedlist> + </para> + <para> + Depending on how you use this instructions or information, there is a slight difference in the package set that ends up on the media you compose. + </para> + + <section id="Reference-Compose_Process_Details-Respin_Mode-Selecting_Groups"> + <title>Selecting Groups</title> + <para> + Selecting groups has the following logic: When you load a repository you may also load the groups file (often referred to as 'comps' or 'comps.xml'). This comps file is an XML file with categories, groups (per category), and per group: + </para> + <para> + <itemizedlist> + <listitem> + <para> + a list of mandatory packages. If you select or include the group, these packages come with it. + </para> + </listitem> + <listitem> + <para> + a list of default packages. If you select or include the group, these packages will come with it as a default. If you only want the mandatory, minimum set of packages for this group, in a kickstart package manifest append <code>--nodefaults</code> to the group line or in the Revisor GUI, right-click on the group and choose <emphasis>Deselect all packages</emphasis>. + </para> + </listitem> + <listitem> + <para> + a list of optional packages. If you select a group you have not yet selected these packages. To select the optional packages of a group, in a kickstart package manifest append <code>--optional</code> to the group line or in the Revisor GUI, right-click on the group and choose <emphasis>Select all optional packages</emphasis>. + </para> + </listitem> + <listitem> + <para> + a list of conditionals. If you select this group, these conditionals are thrown into the package sack and transaction information and include or exclude other packages. Suppose you select the '@nl-support' or “Dutch Support” group from the Languages or Localization category, you would end up with support for the Dutch language in all applications that have that kind of support. + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="Reference-Compose_Process_Details-Respin_Mode-Select_Matching_Packages"> + <title>Select Matching Packages</title> + <para> + This is the logic Revisor applies when running in Re-Spin mode (on the CLI, specify <code>--respin</code>). It imitates the behavior pungi has, and thus enables you to copy that behavior. Note that <code>--respin</code> has other implications as well. + </para> + <para> + First of all, it iterates the groups in the kickstart package manifest. For each group, it appends the names of the mandatory packages to a list, and depending on the additional parameters specified with that group (<code>--nodefaults</code> or <code>--optional</code>), appends the names of the other packages in that group as well. + </para> + <para> + Then it iterates over the package names in the package manifest. These package names are appended to the same list of package names too. This includes package 'names' with some sort of wildcard (?, or *). + </para> + <para> + Then it iterates over all the excluded packages, appending each of those to the YUM configuration exclude list. + </para> + <para> + Now that Revisor has a very simple, flat list of package names, it uses YUM's internal matching logic 5 to get what packages in the repositories matched exactly (by name), matched (by wildcard) and did not match at all. Revisor then selects the exact matches and matches, adding them to the transaction. + </para> + </section> + </section> + + <section id="Reference-Compose_Process_Details-Dependency_Resolving"> + <title>Dependency Resolving</title> + <indexterm> + <primary>Dependency Resolving</primary> + </indexterm> + <para> + Dependency resolving is the area where some of the efficiency Revisor can gain for you comes from. While of course there is specific reasons to do things one way, or the other, most people I speak to about Revisor, it is not very clear why, or what Revisor does in this area. First of all, there's two ways of resolving dependencies: + </para> + <para> + <orderedlist> + <listitem> + <formalpara> + <title>Inclusive Dependency Resolving</title> + <indexterm> + <primary>Dependency Resolving</primary> + <secondary>Inclusive</secondary> + </indexterm> + <para> + Iterate all packages in the transaction and list their requirements, then for each of those requirements, find all packages that provide a matching capability, add those packages to the transaction, and don't forget to add the requirements those packages have themselves, back into the pile of (unmet) requirements. + </para> + </formalpara> + </listitem> + <listitem> + <formalpara> + <title>Exclusive Dependency Resolving</title> + <indexterm> + <primary>Dependency Resolving</primary> + <secondary>Inclusive</secondary> + </indexterm> + <para> + Iterate all the packages and for each of the requirements found, find the best package that meets the requirement. This is also YUMs default behavior. Anaconda uses YUM during the installation, and this is the behaviour of YUM used during the installation. + </para> + </formalpara> + </listitem> + </orderedlist> + </para> + + <section id="Reference-Compose_Process_Details-Dependency_Resolving-Inclusive"> + <title>Inclusive Dependency Resolving</title> + <para> + Hypothetically, you could describe inclusive dependency as follows: + </para> + <para> + <screen>final_packages = [] +more_to_do = True +while more_to_do: +more_to_do = False +for package in packages: + if package in final_packages: + continue + + dependencies = find_package_dependencies() + for dependency in dependencies: + pulled_in_package = pull_in_dependency() + if pulled_in_package not in final_packages: + packages.append(pulled_in_package) + more_to_do = True</screen> + </para> + <para> + So, what does this mean? Basically, it means that if there is a requirement for a capability, all packages providing that capability are being pulled in. Now imagine package 'foo' requires capability 'web-client'. There's a number of packages providing that capability, right? So you get Firefox, lynx, elinks, konqueror, safari, Netscape, Internet Explorer, emacs, for free! All of those pull in their own dependencies also, of course. + </para> + <note> + <para> + If you catch this before it catches you, you can prevent the packages from being pulled in during dependency resolving by not making the package available in the <xref linkend="Reference-Appendix-Terminology-Package_Sack" /> in the first place, using the <literal>-firefox</literal> syntax in the kickstart package manifest, and setting <literal>kickstart_uses_pkgsack_excludes</literal> to 1. + </para> + </note> + <note> + <para> + You may have thought of it; pulling in packages this way may give you a package set (or <emphasis>RPM payload</emphasis>) that has conflicting packages. Imagine package <application>foo</application> requiring capability <application>bar</application>, which is provided by two packages that conflict with one another (either on explicit <literal>Conflicts:</literal> RPM header or file level). Both will be pulled in, hence disabling you to install everything (<literal>'*'</literal> or -previously- <literal>@Everything</literal> in the kickstart package manifest). + </para> + </note> + + <section id="Reference-Compose_Process_Details-Dependency_Resolving-Inclusive-When_This_Makes_Sense"> + <title>When This Makes Sense</title> + <para> + If you are composing a large distribution of which 3 million users in even so many different situations having so many different expectations and desires, you will want this behaviour, since you won't be able to determine which one of the packages for each capability someone in that group wants, and which one may not want. Or, in case of upgrades, what the system needs. Shipping them all on the same media is the best solution in these cases. + </para> + </section> + + <section id="Reference-Compose_Process_Details-Dependency_Resolving-Inclusive-When_This_Does_Not_Make_Sense"> + <title>When This Does Not Make Sense</title> + <para> + <itemizedlist> + <listitem> + <para> + When creating installation media to be installed unattended, or to be used in conjunction with deployment strategies + </para> + </listitem> + <listitem> + <para> + When creating installation media to be upgrading PCs you have controlled from the beginning, such as in a company + </para> + </listitem> + <listitem> + <para> + Installation for a small group of users or systems + </para> + </listitem> + <listitem> + <para> + When creating minimal installation media, or media with a minimal RPM payload. + </para> + </listitem> + <listitem> + <para> + When creating installation media that is to be used with installing "Everything" in the RPM payload. + </para> + </listitem> + </itemizedlist> + </para> + </section> + </section> + + <section id="Reference-Compose_Process_Details-Dependency_Resolving-Exclusive"> + <title>Exclusive Dependency Resolving</title> + <para> + Exclusive dependency resolving is what YUM does when you execute a <application>yum install</application>. Unless you've specified one of the packages satisfying any of the dependencies in the transaction, YUM is going to look up the best match for you. This results in the installation of only one package providing the requirement(s) of other packages, rather then all packages providing said requirement being installed. + </para> + <para> + As an example, imagine you install a package foo which requires capability web-client. Using exclusive dependency resolving, YUM would select one package providing the web-client capability whereas inclusive dependency resolving would include all packages providing the web-client capability. + </para> + <para> + During the installation procedure, one of the major features of installation media, anaconda is going to use YUM dependency resolving to satisfy all the dependencies. + </para> + <note> + <title>Installation Procedure !== Upgrade Procedure</title> + <para> + Note that an installation procedure is not the same as an upgrade procedure. With an installation procedure for example, you have control over the partitioning layout whereas with an upgrade procedure, you have none. More importantly, during an upgrade procedure, the (already installed) system has an existing package set which needs to be updated/upgraded and thus could possibly introduce dependency resolving problems, because of third party packages installed on the system, or because the media used to upgrade the system with does not contain the software packages needed to complete the upgrade RPM transaction. + </para> + </note> + </section> + + </section> + + <section id="Reference-Compose_Process_Details-Copying_Arbitrary_Files_Onto_The_Media"> + <title>Copying Arbitrary Files Onto the Media</title> + <para> + With <literal>--copy-dir</literal>, you can specify a path Revisor should copy onto the media. + </para> + <formalpara> + <title>Installation Media</title> + <para> + In the case of installation media, the path specified with <literal>--copy-dir</literal> will be copied recursively to the <filename>files/</filename> sub-directory at the root of the ISO image (or the first ISO image if you compose split media). + </para> + </formalpara> + <para> + A few use-case examples: + </para> + <para> + <itemizedlist> + <listitem> + <para> + If one kickstart profile is not enough for you to deploy the product onto your systems, create a directory that holds multiple kickstart files and specify the path to that directory using <literal>--copy-dir</literal>. The kickstart files now end up available to the installation procedures as <filename>cdrom:/files/*.ks</filename>, and can thus be used by specifying them on the kernel cmdline (<code>ks=cdrom:/files/profile1.ks</code>), or, when used in combination with <literal>--isolinux-cfg</literal> from the <xref linkend="Reference-Plugins-Upstream-Isolinux_Plugin" endterm="Isolinux_Plugin" />, can be added as an option in the isolinux menu. + </para> + </listitem> + <listitem> + <para> + If you have files or scripts that need to be copied onto, or run on, the installed system before it attempts to reboot and operate normally, you can use <literal>--copy-dir</literal> to make these files and scripts available during the installation and copy or execute them from either <code>%pre</code> or <code>%post</code> scripts. + </para> + </listitem> + </itemizedlist> + </para> + <formalpara> + <title>Live Media</title> + <para> + In the case of live media, the path specified with <literal>--copy-dir</literal> will be copied recursively onto the root directory (<filename>/</filename>) of the live media filesystem (which is probably loop-mounted onto <filename>/var/tmp/revisor/</filename>). + </para> + </formalpara> + <para> + If, for example, you want to copy a home directory onto the live media, and the home directory you want to copy is at <filename>/home/user1/</filename> on the composing system, you copy this directory so that the root of that new directory has a sub-directory <filename>home/</filename> which in turn contains a sub-directory <filename>user1/</filename>: + </para> + <para> + <screen>$ <userinput>mkdir -p /tmp/something/home/</userinput> +$ <userinput>cp -a /home/user1 /tmp/something/home/.</userinput> +$ <userinput>revisor [options] --copy-dir /tmp/something/</userinput></screen> + </para> + </section> + + <section id="Reference-Compose_Process_Details-Cleaning_Up"> + <title>Cleaning Up</title> + <para> + Revisor tends to clean up after itself by default. If a product compose succeeds, you (probably) don't need to change this default behaviour. However, by default, Revisor tends to leave the YUM cache directories untouched. This is to prevent you from having to download all the packages a second, third or more times when you run another compose. + </para> + <para> + To change this default behaviour, Revisor has an option <literal>--clean-up</literal>. The default value for this option is <literal>1</literal>, meaning Revisor will clean up it's temporary, compose-specific files, but no files that could be re-used. Specifying <literal>--clean-up=0</literal> will cause Revisor to leave everything behind and not clean anything up at all. This is most ideal for troubleshooting purposes, where one needs to examine the temporary, compose-specific files and see what went wrong. To clean up everything however, because for example you might be low on disk-space, use <literal>--clean-up=2</literal>. Revisor will then also clean up the files that could be re-used. + </para> + + <section id="Reference-Compose_Process_Details-Cleaning_Up-Exception-to-the-Rule"> + <title>Exception to the Rule</title> + <para> + There's one exception to the rule of cleaning up. <filename>/var/tmp/revisor/</filename>, or put more accurately, the path specified as the <code>installroot</code> in the YUM configuration file configured with the model used to compose the product, will not be cleaned up afterwards. When composing live media, this directory may still be in use as a mount-point for the live media filesystem. Removing this directory recursively in these cases would not make sense. + </para> + </section> + </section> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Configuration.xml b/doc/Reference_Manual/en-US/Reference-Configuration.xml new file mode 100644 index 0000000..49c6f6a --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Configuration.xml @@ -0,0 +1,280 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Configuration"> + <title>Configuration</title> + <para> + Revisor configuration can be performed using <xref linkend="Reference-Configuration-Files" />, or through <xref linkend="Reference-Configuration-Command-line_Options" />. + </para> + + <section id="Reference-Configuration-Files"> + <title>Configuration Files</title> + <para> + Revisor uses configuration files for a large part of it's operations. These files mostly reside in <filename>/etc/revisor/</filename>. There is two types of files Revisor uses: + </para> + <para> + <orderedlist> + <listitem> + <formalpara> + <title>Revisor Configuration Files</title> + <para> + Revisor configuration files, such as <filename>/etc/revisor/revisor.conf</filename>, contain information and settings unique to Revisor. A Revisor configuration file is where you specify default options, and include information on different products you want to compose. + </para> + </formalpara> + </listitem> + <listitem> + <formalpara> + <title>YUM Configuration Files</title> + <para> + YUM configuration files, such as the files in <filename>/etc/revisor/conf.d/</filename>, contain configuration for YUM. To be more precise, Revisor doesn't even handle the files (it let's YUM do so). The files in <filename>/etc/revisor/conf.d/</filename> practically contain the same information as <filename>/etc/yum.conf</filename> combined with the files in <filename>/etc/yum.repos.d/</filename> (but not exactly the same content!). + </para> + </formalpara> + </listitem> + </orderedlist> + </para> + + <section id="Reference-Configuration-Files-_etc_revisor_revisor.conf"> + <title><filename>/etc/revisor/revisor.conf</filename></title> + <para> + The default Revisor configuration file is <filename>/etc/revisor/revisor.conf</filename>. This configuration file contains two sections: + </para> + <para> + <orderedlist> + <listitem> + <formalpara> + <title><literal>[revisor]</literal></title> + <para> + The global section. Options specified in this section apply to all the models defined in this configuration file. + </para> + </formalpara> + <para> + See also: <xref linkend="Reference-Configuration-Global_and_Model_Configuration" /> + </para> + </listitem> + <listitem> + <formalpara> + <title><literal>[<replaceable>model</replaceable>]</literal></title> + <para> + Model configuration. One section per <xref linkend="Reference-Appendix-Terminology-model" />. + </para> + </formalpara> + <para> + See also: <xref linkend="Reference-Configuration-Global_and_Model_Configuration" /> + </para> + </listitem> + </orderedlist> + </para> + <para> + Model sections basically define a single product. Amongst other things, the distribution name, release version, architecture for the product to be composed and what YUM configuration file to use, are (often) defined on a per-model basis. There is a large number of settings available for models, and they are all related to how the product is going to look like. The product name, the location of the RPM payload for installation media, the ISO label, the YUM configuration file to use, are all model settings. + </para> + <para> + Using models, you can reproduce the outcome of the compose process, a <emphasis>product</emphasis>, simply by not changing the model configuration anymore. If you want something different, you can just add another model section, and name it differently. + </para> + <para> + To see what models are available with the Revisor standard package, use: + </para> + <para> + <screen>$ <userinput>revisor --list-models</userinput></screen> + </para> + </section> + + <section id="Reference-Configuration-Files-_etc_revisor_conf.d_"> + <title><filename>/etc/revisor/conf.d/</filename></title> + <para> + The default YUM configuration files used by Revisor. In a model configuration section, the <literal>main =</literal> setting points to one of the YUM configuration files in <filename>/etc/revisor/conf.d/</filename> + </para> + </section> + + <section id="Reference-Configuration-Files-Updates"> + <title>Updates to Configuration Files</title> + <para> + The Revisor packages are not allowed to overwrite files in <filename>/etc/</filename>, and they should thus not do so. If an update to Revisor is installed on your system, files with the extension <literal>.rpmnew</literal> may be created --if you had changed anything in the file before applying the update. Since this world isn't perfect, configuration errors may exist in the configuration files shipped with Revisor. Please pay close attention to updates to these configuration files by examining the <literal>.rpmnew</literal> files. + </para> + <para> + You can use any file location (not just <filename>/etc/revisor/</filename>) for your own custom configuration. + </para> + </section> + + <section id="Reference-Configuration-Files-Changing_Configuration_Files"> + <title>Changing Configuration Files</title> + <para> + If you are creating your own models off of the ones that ship with Revisor itself, please consider using an alternative configuration file (a file other then <filename>/etc/revisor/revisor.conf</filename>, or copy the original file for safekeeping. This way, you can always return to a working, sample configuration file and test whether it is Revisor causing errors, or configuration mistakes. + </para> + </section> + + </section> + + <section id="Reference-Configuration-Global_and_Model_Configuration"> + <title>Global and Model Configuration</title> + <para> + The default Revisor configuration file, <filename>/etc/revisor/revisor.conf</filename> consists of multiple sections (the file is in .INI format). One is the <literal>[revisor]</literal> global section, where you specify configuration options that apply to each other section or <xref linkend="Reference-Appendix-Terminology-model" />. + </para> + <para> + The options specified in the global and model configuration sections apply to the Revisor compose in the following order: + </para> + <para> + <orderedlist> + <listitem> + <para> + The options from the global section are read, tested and set. + </para> + </listitem> + <listitem> + <para> + The options from a model section are read, tested and set, regardless of whether the global section had caused the setting to be set to a certain value already. + </para> + </listitem> + </orderedlist> + </para> + <para> + For example, if you know all the models in a configuration file are optical live media products, the configuration sections could look like the following: + </para> + <para> + <screen>[revisor] +# Optical live media for all models +media_live_optical = 1 + +[model1] +main = /etc/revisor/conf.d/revisor-model1.conf +description = The model1 product +architecture = i386 +# This is already configured in the global section of +# this configuration file and can thus be removed. +#media_live_optical = 1</screen> + </para> + <note> + <title>When Running the GUI</title> + <para> + Note that when running Revisor in Graphical User Interface mode, you can still change a lot of the settings supplied by Revisor through the configuration files loaded. When you are running Revisor in GUI mode, the configuration files supply the defaults. + </para> + </note> + </section> + + <section id="Reference-Configuration-Yum_Repositories"> + <title>YUM Repository Configuration</title> + <para> + The files in <filename>/etc/revisor/conf.d/</filename> are YUM configuration files. Revisor directs YUM to use these files during the compose process, and does not handle these files itself. This chapter lists a few tips and tricks. + </para> + <para> + Because these files are YUM Configuration files, you can configure anything that YUM supports. See <application>man yum.conf</application> for more details. + </para> + + <section id="Reference-Configuration-Yum_Repositories-releasever_and_basearch"> + <title>$releasever and $basearch</title> + <para> + When configuring a repository URL, make sure you do not use <replaceable>$releasever</replaceable> or <replaceable>$basearch</replaceable> variables. Since Revisor allows cross-composing distributions between different versions of the operating system, as well as different architectures, these variables need to be expanded to the value intended. + </para> + <para> + See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> + </para> + </section> + + <section id="Reference-Configuration-Yum_Repositories-Using_a_Local_Mirror"> + <title>Using a Local Mirror</title> + <para> + If you have a local mirror of Fedora, you can use the <literal>baseurl</literal> configuration directive in each repository configuration section to tell YUM to use the local mirror. + </para> + <para> + Optionally, you can also disable the <literal>mirrorlist</literal>, preferably by outcommenting it, so that YUM will only use the local mirror. + </para> + <para> + The default <literal>baseurl</literal> uses <literal>http://download.fedoraproject.org/</literal>. This location may or may not be suitable for you. If you have a local mirror, you might want to change this setting here, or add your mirror to Fedora Project's Mirrorlist. + </para> + <note> + <title>Adding your local mirror to the Mirrorlist</title> + <para> + You can add your local mirror to the Mirrorlist, so that the Fedora Project mirrorlist redirects you to your local mirror. Additionally, systems in your local network(s) will be redirected to the local mirror. The local mirror does not have to be a public mirror in order to do so. See <ulink url="http://admin.fedoraproject.org/mirrormanager/" /> for more details. + </para> + </note> + <para> + Set each <literal>baseurl</literal> to the location of the repository on the local mirror. + </para> + <para> + See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> + </para> + </section> + + <section id="Reference-Configuration-Yum_Repositories-Using_Local_Files"> + <title>Using Local Files</title> + <para> + If you have the repositories on your local filesystem, configure a <literal>baseurl</literal> of <filename>file://<replaceable>/path/to/repository/</replaceable></filename>. + </para> + <note> + <title>Make sure to supply the correct path</title> + <para> + Make sure to supply the correct path to the repository. <filename>file://</filename> is the "<emphasis>protocol</emphasis>" for the location, and the location is <filename><replaceable>/path/to/repository/</replaceable></filename>. Put together, you have <emphasis>three</emphasis> slashes. + </para> + </note> + <para> + See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> + </para> + </section> + + <section id="Reference-Configuration-Yum_Repositories-Using_a_DVD"> + <title>Using a DVD</title> + <para> + A DVD does not contain enough packages to rebuild the installer images. If you are using a DVD and you want to rebuild the installer images, you will need to have a network connection and a mirror you can reach. + </para> + <para> + There is a list of required packages, but since the packages change per release and may change in the middle of the release cycle as well, we cannot hand you a list that just works. + </para> + <para> + See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> + </para> + </section> + + <section id="Reference-Configuration-Yum_Repositories-Adding_Third_Party_Repositories"> + <title>Adding Third Party Repositories</title> + <para> + When adding a third party repository, make sure you add the correct release version as well as architecture to the Revisor YUM configuration file. Verify the location for the <literal>baseurl</literal> and/or <literal>mirrorlist</literal> you configure manually or through YUM. Make sure you expand any <literal>$releasever</literal>, <literal>$basearch</literal> and <literal>$arch</literal> variables. + </para> + <para> + See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> + </para> + </section> + + <section id="Reference-Configuration-Yum_Repositories-Creating_Your_Own_Repository"> + <title>Creating Your Own Repository</title> + <para> + Creating your own repository is relatively simple. You take a directory, dump some RPM packages in it, and run <application>createrepo</application>. See <literal>man createrepo</literal> for more information. + </para> + <para> + People often wonder how Revisor handles comps.xml group files. + </para> + <para> + When you create your own repository, follow the directions in <xref linkend="Reference-Configuration-Yum_Repositories-Adding_Third_Party_Repositories" /> to add the repository configuration to Revisor's YUM configuration, since your own repository is a third party repository as well. + </para> + <para> + See also <xref linkend="Reference-Configuration-Yum_Repositories-Troubleshooting" /> + </para> + </section> + + <section id="Reference-Configuration-Yum_Repositories-Troubleshooting"> + <title>Testing & Troubleshooting the YUM Configuration</title> + <para> + Before you use the (modified) configuration file, take it for a test run. + </para> + </section> + + </section> + + <section id="Reference-Configuration-Configuring_A_Proxy"> + <title>Configuring A Proxy Server</title> + <para> + para + </para> + </section> + + <section id="Reference-Configuration-Command-line_Options"> + <title>Command-line Options</title> + <para> + With the command-line options available, you can configure options that either override what is in the configuration file or have simply not been configured using the configuration file. With the default configuration files that come with the <application>revisor-cli</application> package for example, no media products have been pre-configured in the default section. In the <application>revisor-unity</application> package however, some default configuration has been applied so that Fedora Unity Re-Spins actually create CD, DVD and Rescue ISO images as well as the Installation Tree and include the sources. + </para> + <para> + Only some configuration options have CLI parameters. Use <application>revisor --help</application> to see a complete list of configuration options you can supply on the command line. + </para> + </section> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Development.xml b/doc/Reference_Manual/en-US/Reference-Development.xml new file mode 100644 index 0000000..f28128e --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Development.xml @@ -0,0 +1,220 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Development"> + <title>Development</title> + <para> + This chapter sheds some light on development of Revisor, such as different branches and maintenance policies, versioning schemas, etcetera. + </para> + <para> + This part of the documentation relies on whether you have <application>sudo</application> set up properly. If you have not, you're on your own. + </para> + + <section id="Reference-Development-Running_Revisor_from_Source"> + <title>Running Revisor from Source</title> + <para> + The latest code in GIT can be built into a RPM you can install but one of the advantages of having the complete source tree is that you can run it directly from that source tree so that when you pull in the next updates you do not have to rebuild the RPM. Note that we do not bump the version number for every little change we make, and as such the RPM built does not allow you to use <literal>rpm -Uvh</literal> or <literal>rpm -Uvh --oldpackage</literal>. Of course, Revisor's Makefiles also allow <application>make install</application>, but that leaves a number of unmanaged files on your computer you would have to track down manually in order to remove Revisor completely. + </para> + <warning> + <title>Cannot have Revisor RPMs installed</title> + <para> + When running revisor from within the source tree, you cannot have any of the Revisor packages installed. Having Revisor RPM packages installed regardless will mess up the GIT repository or source tree. + </para> + </warning> + <para> + To run Revisor from within the source tree, checkout the master branch, and run the <filename>./switchhere</filename> script: + </para> + <para> + <screen>$ <userinput>./switchhere</userinput></screen> + </para> + <para> + The <filename>./switchhere</filename> script does the following: + </para> + <para> + <itemizedlist> + <listitem> + <para> + Symlink <filename>/etc/revisor/</filename> to <filename><replaceable>$PWD</replaceable>/conf/</filename> so that <filename>/etc/revisor/revisor.conf</filename>, the primary configuration file, and <filename>/etc/revisor/conf.d/</filename>, the configuration directory, are valid (the symlink causes the actual file and directory to be found in <filename><replaceable>$PWD</replaceable>/conf/</filename>) + </para> + </listitem> + <listitem> + <para> + Create the <filename>/usr/share/revisor/</filename> directory so that a couple of symlinks can be created from within that directory: + </para> + </listitem> + <listitem> + <para> + In Revisor 2.1.0 (development version in branch master), this includes: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <filename>/usr/share/revisor/ui => <replaceable>$PWD</replaceable>/revisor/modgui/glade/</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/usr/share/revisor/pixmaps => <replaceable>$PWD</replaceable>/revisor/modgui/glade/pixmaps/</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/usr/share/revisor/comps => <replaceable>$PWD</replaceable>/conf/</filename> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + In Revisor 2.0.5 (branch F-7, F-8 or EL-5), this includes: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <filename>/usr/share/revisor/ui => <replaceable>$PWD</replaceable>/glade/</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/usr/share/revisor/pixmaps => <replaceable>$PWD</replaceable>/glade/pixmaps/</filename> + </para> + </listitem> + <listitem> + <para> + <filename>/usr/share/revisor/comps => <replaceable>$PWD</replaceable>/conf/</filename> + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para> + In Revisor 2.1.0, also create symlinks from within the appropriate <filename>/usr/share/man/man<replaceable>$x</replaceable>/</filename> directories to the source for these man pages in <filename><replaceable>$PWD</replaceable>/doc/</filename>. + </para> + </listitem> + </itemizedlist> + </para> + <para> + From this moment on, you should be able to run: + </para> + <para> + <screen>$ <userinput>./revisor.py</userinput></screen> + </para> + <note> + <title>Root privileges required</title> + <para> + Note that revisor needs root privileges to run, and that you'll need to sudo or su-c to gain those. Use here whatever you find the most convenient; Revisor though should have a nice error message when run without those privileges. + </para> + </note> + + <section id="Reference-Development-Running_Revisor_from_Source-Required_Packages"> + <title>Installing the Required Packages</title> + <para> + To be able to run Revisor from within the source tree, you'll need to install the required packages for each component, of course. + </para> + <para> + To get a current list of those packages, use: + </para> + <para> + <screen>$ <userinput>rpmquery --specfile --qf="%{REQUIRES}\n" revisor.spec | sort | uniq | xargs -n 1 repoquery --requires --alldeps --resolve</userinput></screen> + </para> + </section> + + </section> + + <section id="Reference-Development-Building_Revisor_Packages"> + <title>Building Revisor Packages</title> + <para> + para + </para> + </section> + + <section id="Reference-Development-Tickets"> + <title>Tickets</title> + <para> + bugzilla, trac + </para> + </section> + + <section id="Reference-Development-Adding_A_New_Spin"> + <title>Adding a new spin or remix</title> + <para> + <orderedlist> + <listitem> + <para> + Add the appropriate models in the appropriate configuration file for Revisor. + </para> + </listitem> + <listitem> + <para> + Add the appropriate configuration file to the appropriate automake Makefile + </para> + </listitem> + <listitem> + <para> + Run autoreconf && ./configure && make rpm to verify the rpm building + </para> + </listitem> + <listitem> + <para> + Create the model's YUM configuration files with the following repositories: + </para> + <para> + <itemizedlist> + <listitem> + <para> + fedora, enabled, pointing to Everything + </para> + </listitem> + <listitem> + <para> + fedora-source, disabled, pointing to Everything + </para> + </listitem> + <listitem> + <para> + fedora-updates, enabled, pointing to the updates repository + </para> + </listitem> + <listitem> + <para> + fedora-updates-source, disabled, pointing to the updates repository + </para> + </listitem> + <listitem> + <para> + anaconda-updates, enabled, pointing to the anaconda updates repository + </para> + </listitem> + <listitem> + <para> + anaconda-updates-source, disabled, pointing to the ananconda updates repository + </para> + </listitem> + </itemizedlist> + </para> + </listitem> + </orderedlist> + </para> + </section> + + <section id="Reference-Development-Versioning_Schema"> + <title>Versioning Schema</title> + <para> + para + </para> + </section> + + <section id="Reference-Development-Release_Procedure"> + <title>Release Procedure</title> + <para> + para + </para> + </section> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Features.xml b/doc/Reference_Manual/en-US/Reference-Features.xml new file mode 100644 index 0000000..193bb7a --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Features.xml @@ -0,0 +1,175 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Features"> + <title>Features</title> + <para> + Revisor allows you to build and customize your own Remix, Re-Spin, Spin or even your own distribution, based on Fedora and derivative distributions such as Red Hat Enterprise Linux and CentOS. + </para> + <para> + Revisor builds installation media, live media, installation trees, cobbler distro's and profiles, virtualization images and more. + </para> + + <section id="Reference-Features-Installation_Media"> + <title>Installation Media</title> + <para> + Installation media is what you use to install a system with. The installation media composed will allow you to go through the installation process, answering a number of questions (either manually or through kickstart), and ends up in a system running the distribution you install. + </para> + <para> + Composing installation media using the Revisor GUI allows you to choose the media (CD, or DVD), the packages to be included on the media (also called <emphasis>RPM payload</emphasis>). + </para> + <para> + Using the command-line interface, Revisor also allows you to choose DVD Duallayer and single- or dual-layer Bluray. + </para> + </section> + + <section id="Reference-Features-Installation_Trees"> + <title>Installation Trees</title> + <para> + Installation trees are typically used in environments where a distribution needs to be deployed over multiple systems, or is very volatile. Installation trees are often made accessible through HTTP or FTP protocols, in one place, and do not have as much overhead (in creating .iso files, and burning those to optical media to distribute them). + </para> + </section> + + <section id="Reference-Features-Live_Media"> + <title>Live Media</title> + <para> + Live media often is a perfect showcase for an Operating system, Desktop Environment or any other thing you want to show. Also, since Live media is read-only, live media perfectly allows for a kiosk system, a system that may change while it's running, but restores all original settings when rebooted. + </para> + <para> + Live media is also installable. You start out with a system and boot it from live media, then choose to install the live media. This however is inferior to real installation media, but is convenient if you happen to like what you see when running from live media. + </para> + </section> + + <section id="Reference-Features-Reproducibility"> + <title>Reproducibility</title> + <para> + Media composed with Revisor is extremely reproducible. Using <literal>kickstart_exact_nevra</literal>, you can even select specific versions of packages to be included on the product. + </para> + </section> + + <section id="Reference-Features-Consistency"> + <title>Consistency</title> + <para> + When composing different types of media, such as CDs and DVDs, Revisor composes these discs in one run, making the different media completely consistent. <application>pungi</application> would require you to run twice, once for CDs, and once for DVDs. This is because <application>pungi</application> uses the <literal>part / <replaceable><size></replaceable></literal> kickstart configuration directive to set the maximum size of the media, and has no option to override the size on the command-line, nor to compose a certain set of media (it all depends on the size). + </para> + </section> + + <section id="Reference-Features-Flexibility"> + <title>Flexibility</title> + <para> + Over the years, Revisor has been adopted to serve a large number of use-cases, where use-cases stretch from media being composed as efficient as possible, as robust as possible, specific deployment needs and expectations, and to match the Fedora Project Release Engineering tools' behaviour. All this allows you to configure a lot, and thus customize a lot, making Revisor more of a flexible framework. + </para> + </section> + + <section id="Reference-Features-Graphical_User_Interface"> + <title>Graphical User Interface</title> + <para> + Revisor has a Graphical User Interface or GUI, in addition to the Command Line Interface or CLI, which makes Revisor more accessible to users then the other tools, which are CLI only. Most people only know of Revisor through the GUI, and may think there is no CLI to Revisor. Only when it comes down to many of the additional features that Revisor has, and that do not fit in a simplified GUI, one gets down with it using the CLI. + </para> + </section> + + <section id="Reference-Features-Open_Development_Community"> + <title>Open Development Community</title> + <para> + Revisor has one of those old-fashioned Free and Open Source Software development communities, allowing anyone to make a contribution to Revisor. In fact, Revisor has not bounced a single patch since the project started. Therefor, it improves faster then any of the other compose tools, and is better adaptible to your needs and expectations, because unlike the other utilities, Revisor is not limited to use-cases that apply to Fedora Project Release Engineering. + </para> + </section> + + <section id="Reference-Features-Plugin_System"> + <title>Plugin System</title> + <para> + Revisor has a plugin system so that you can easily extend Revisor. This plugin system gives you full control over the Revisor procedures, and hands you off anything Revisor knows about the compose process. There's are multiple plugins available from upstream as well. To give you an example, the ability to replace <filename>isolinux.cfg</filename> after the compose is done, is a plugin. See <xref linkend="Reference-Plugins" /> for more information. + </para> + + <para> + Current plugins included with Revisor include: + </para> + <para> + <itemizedlist> + <listitem> + <para> + <xref linkend="Reference-Plugins-Upstream-Cobbler_Plugin" /> + </para> + </listitem> + <listitem> + <para> + <xref linkend="Reference-Plugins-Upstream-Isolinux_Plugin" /> + </para> + </listitem> + <listitem> + <para> + <xref linkend="Reference-Plugins-Upstream-Rebrand_Plugin" /> + </para> + </listitem> + <listitem> + <para> + <xref linkend="Reference-Plugins-Upstream-Reuse_Installer_Images_Plugin" /> + </para> + </listitem> + </itemizedlist> + </para> + </section> + + <section id="Reference-Features-Extraneous_Debugging"> + <title>Extraneous Debugging</title> + <para> + Revisor has extraneous debugging, which enables you, as well as the supporters and Revisor's developers, to trace down what happens exactly, and where anything might go wrong. + </para> + </section> + + <section id="Reference-Features-Using_YUM_Configuration_Files"> + <title>Using YUM Configuration Files</title> + <para> + Revisor uses YUM configuration files, where everyone else is not. With using YUM configuration files however, the control you have is nearly limitless. With all the features in YUM already, using it's configuration file format and letting YUM itself work with those allows Revisor to do a lot of cool things without doing anything itself: + </para> + <para> + <orderedlist> + <listitem> + <formalpara> + <title>Excluding packages from repositories</title> + <para> + Excluding packages from repositories means a great deal. Not having them exist in the <xref linkend="Reference-Appendix-Terminology-Package_Sack" /> ensures the package will not end up in the product. This may be what you want for maybe just a few, or maybe an awful lot of packages. + </para> + </formalpara> + <para> + Using the alternative configuration file format, kickstart, in use by every other compose tool, and the <literal>repo</literal> configuration directive that is available with kickstart, you can exclude packages using the <literal>--exclude=</literal> parameter to the <literal>repo</literal> configuration directive. However, that parameter does not allow wildcard matches. + </para> + </listitem> + <listitem> + <formalpara> + <title>Including only a certain (set of) package(s)</title> + <para> + Including only a certain package, or certain set of packages is valuable when a lot of packages exist in the repository configured, but you only need one or two. + </para> + </formalpara> + </listitem> + <listitem> + <formalpara> + <title>Concurrent use of baseurl(s) and the mirrorlist</title> + <para> + Like during normal YUM operations, the baseurl(s) and the mirrorlist configured for a repository are used concurrently. This is not possible with the kickstart configuration directive <literal>repo</literal>, which takes either <literal>--baseurl</literal> or <literal>--mirrorlist</literal>, but not both. + </para> + </formalpara> + </listitem> + <listitem> + <formalpara> + <title>Repository priorities</title> + <para> + Settings available with YUM are available within Revisor as well, like repository priorities. Using repository priorities, you can have YUM decide to pull a package from the repository with a higher priority (a lower priority number) rather then a repository with a lower priority. + </para> + </formalpara> + </listitem> + <listitem> + <formalpara> + <title>YUM Plugins</title> + <para> + YUM plugins, such as <application>yum-fastestmirror</application>, <application>yum-fedorakmod</application>, are available, giving you even more control over the behaviour of YUM. + </para> + </formalpara> + </listitem> + </orderedlist> + </para> + </section> +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Frequently_Asked_Questions.xml b/doc/Reference_Manual/en-US/Reference-Frequently_Asked_Questions.xml new file mode 100644 index 0000000..b2d8128 --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Frequently_Asked_Questions.xml @@ -0,0 +1,54 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Frequently_Asked_Questions"> + <title>Frequently Asked Questions</title> + <para> + para + </para> + + <formalpara id="Reference-Frequently_Asked_Questions-How_Does_Revisor_Handle_Comps"> + <title>How Does Revisor Handle Comps?</title> + <para> + para + </para> + </formalpara> + + <formalpara id="Reference-Frequently_Asked_Questions-What_Are_Installer_Images"> + <title>What Are Installer Images?</title> + <para> + para + </para> + </formalpara> + + <formalpara id="Reference-Frequently_Asked_Questions-Relationship_Between_Revisor_and_Pungi"> + <title>What is the relationship between Revisor and Pungi?</title> + <para> + Where pungi builds a bunch of RPMs into ISO images and installation trees through one single procedure, perfect for Release Engineering on something like the Fedora Project, Revisor does it different entirely. + </para> + </formalpara> + + <formalpara id="Reference-Frequently_Asked_Questions-Relationship_Between_Revisor_and_Livecd-tools"> + <title>What is the relationship between Revisor and livecd-tools?</title> + <para> + Revisor depends on livecd-tools for the composing of live media. Creating the filesystem to install the packages to, turning that image file into a SquashFS file, and applying the settings inside the chroot. + </para> + </formalpara> + + <formalpara id="Reference-Frequently_Asked_Questions-Why_Rebuild_Installer_Images"> + <title>Why Rebuild Installer Images?</title> + <para> + para + </para> + </formalpara> + + <formalpara id="Reference-Frequently_Asked_Questions-How_do_I_create_an_updates.img"> + <title>How do I create an updates.img?</title> + <para> + para + </para> + </formalpara> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Installation.xml b/doc/Reference_Manual/en-US/Reference-Installation.xml new file mode 100644 index 0000000..5f1f89a --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Installation.xml @@ -0,0 +1,104 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Installation"> + <title>Installation</title> + <para> + This chapter contains the installation instructions for Revisor. + </para> + + <section id="Reference-Installation-Packages"> + <title>Packages</title> + <para> + You can install Revisor using RPM packages from the repositories already configured on your system. + </para> + + <formalpara id="Reference-Installation-Packages-revisor"> + <title><application>revisor</application></title> + <para> + Shorthand package for the Revisor GUI. + </para> + </formalpara> + + <formalpara id="Reference-Installation-Packages-revisor-cli"> + <title><application>revisor-cli</application></title> + <para> + The CLI version of Revisor. This package is always installed, as it contains the Python code for Revisor's core. Installing just this package will give you the command-line version of Revisor, and prevents the graphical dependencies from the <xref linkend="Reference-Installation-Packages-revisor-gui" /> package to be installed as well. + </para> + </formalpara> + + <formalpara id="Reference-Installation-Packages-revisor-gui"> + <title><application>revisor-gui</application></title> + <para> + The GUI version of Revisor. This is the actual package containing the Graphical User Interface, as opposed to <xref linkend="Reference-Installation-Packages-revisor" />. Depends on <xref linkend="Reference-Installation-Packages-revisor-cli" />, and thus also installs the command-line version of Revisor. + </para> + </formalpara> + + <section id="Reference-Installation-Packages-YUM-RHEL"> + <title>Red Hat Enterprise Linux 5 or higher</title> + <para> + On Red Hat Enterprise Linux 5 or higher, and derivatives, install the Extra Packages for Enterprise Linux (EPEL) repository. + </para> + <para> + Then, give the following command: + </para> + <para> + <screen># <userinput>yum install revisor</userinput></screen> + </para> + </section> + + <section id="Reference-Installation-Packages-YUM-Fedora"> + <title>Fedora 7 or higher</title> + <para> + On Fedora 7 or higher, and derivatives, no additional repository configuration is required. + </para> + <para> + Give the following command: + </para> + <para> + <screen># <userinput>yum install revisor</userinput></screen> + </para> + <note> + <title>About EOL Releases</title> + <para> + Please bear in mind that Fedora releases that are past the point of End-Of-Life, approximatly 13 months after the initial release, are not supported anymore for use with Revisor. Also, the version of Revisor running on these EOL versions of Fedora are not supported anymore. + </para> + </note> + </section> + + </section> + + <section id="Reference-Installation-The_Latest_And_Greatest"> + <title>The Latest and Greatest</title> + <para> + The latest and greatest is available from GIT, at <ulink url="git://git.fedorahosted.org/revisor" />. To clone this repository, use: + </para> + <para> + <screen>$ <userinput>git clone git://git.fedorahosted.org/revisor/</userinput></screen> + </para> + <para> + Using the GIT clone, you have the several options to start using the latest and greatest: + </para> + <formalpara> + <title>Running directly from the source</title> + <para> + You can run directly from within the source tree. See <xref linkend="Reference-Development-Running_Revisor_from_Source" /> for more information on how to do so. + </para> + </formalpara> + <warning> + <title>Installed packages and running from source</title> + <para> + Do not run Revisor from source while RPM packages have been installed. Files managed by a package will get created, moved and removed when using Revisor's source tree, and updates to the installed RPM packages will destroy these changes. + </para> + </warning> + <formalpara> + <title>Building your own packages</title> + <para> + You can create your own packages, so that you have all the benefits of RPM. See <xref linkend="Reference-Development-Building_Revisor_Packages" /> for more information on how to do so. + </para> + </formalpara> + </section> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Introduction.xml b/doc/Reference_Manual/en-US/Reference-Introduction.xml new file mode 100644 index 0000000..a6bd7a7 --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Introduction.xml @@ -0,0 +1,77 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Introduction"> + <title>Introduction</title> + <para> + Revisor is a community product by Fedora Unity. Amongst other features, it allows the creation of installation media and live media in the easiest possible manner, through a click-and-go GUI. This chapter gives some insight on how and why Revisor was born, and how the product evolved since. + </para> + + <section id="Reference-Introduction-History_Of_Revisor"> + <title>History of Revisor</title> + <para> + Revisor development started in December 2006, during the Fedora 7 development cycle, in which -as you might recall- the Fedora Core repository, maintained by Red Hat, and Fedora Extras repository, mostly maintained by the community, were merged into one large repository being maintained by both community members as well as Red Hat employees -which are mostly community members who just so happen to be hired by Red Hat, so community altogether. Before then Red Hat employees maintained Fedora Core -as the set of packages upstream for Red Hat's Enterprise product- and the community maintained a repository with additional software; Fedora Extras. Red Hat composed the Fedora distribution every once in a while, but the merge introduced the possibility for packages that were in Fedora Extras to be included in the main distribution, and for the community to also (co-)maintain the (former) Fedora Core packages that originally made up the distribution. + </para> + <para> + In addition to this huge merge of packages, Red Hat employees were also able to release the entire build process to the community, meaning that from the moment the source is committed up and until the release is announced, the entire process is open. Not that is was all behind closed doors or proprietary or anything, the community just couldn't really play with it as much. We now have koji (build system), mash (repository compose from build system products), bodhi (updates release system), livecd-tools (compose tool for live media) and pungi (compose tool for installation media). + </para> + <formalpara> + <title>Composing the distribution's media</title> + <para> + Composing media was an obscure process up and until the moment these tools exposed the best way to compose (a set of) installation media. Fedora Unity had been building and releasing so-called Re-Spins1 regularly, but they were built using a not-so-very intelligent bash script. Like hundreds if not thousands of other parties that needed to build their own media one way or the other, the entire process was based on the best educated guess of what should happen. Luckily, in the FOSS world an educated guess is often a very good guess, despite the fact that one keeps learning even years after the original engagement. + </para> + </formalpara> + <para> + When in December 2006 the compose tools hit a stage in which they were released to the public, Fedora Unity was eager to get these tools and study them and use them for composing their Re-Spins. Up and until then, Re-Spins were composed with the aforementioned bash script that didn't do much but trigger the appropriate commands in a sequence; There wasn't any dependency resolving between the packages included nor did we know exactly how a release was supposed to be composed -it was our educated guess of how it could happen. Although it often led to success, we've had many, many failed Re-Spins as well. With a handful of volunteers, you can imagine the amount of frustration that might give. Fedora Unity was eager to improve their Re-Spin process. + </para> + <formalpara> + <title>Fedora Unity's engagement</title> + <para> + So, early February 2007, a number of Fedora Unity members attended “FUDCon 2007” in Boston, and presented a working GUI front-end to both livecd-tools and pungi enabling regular users to also re-compose or re-spin the installation media and live media they had been getting from the Fedora Project. Revisor at this point just made it “as easy as possible”. Besides the possibilities of pungi and livecd-tools themselves, the wizard Revisor had apparently was very, very useful to mere mortals. From that point on, things took off. + </para> + </formalpara> + <para> + Fedora Unity decided Revisor could accomplish more then just being a front-end to existing compose tools and enable someone to tweak a lot of settings as well. In March 2007, Revisor was rebuild from the ground up in March 2007 to allow a more flexible process, more dependent on the configuration directives it was given and less so on the processes of the existing tools. When in San Diego at the Red Hat Summit (early May 2007), Robert 'Bob' Jensen and Jonathan Steffan gave a presentation on “Customizing Fedora”, the responses were amazing. Since then Revisor has evolved from a front-end to existing tools to the complete compose tool it is today, with lots of configuration options for specific use-cases. + </para> + <para> + For users, Revisor is particularly useful because it has a GUI front-end wizard, which, with the defaults settings, will just succeed in getting a user the media he/she wants. If a user decides he needs little adjustment of the media, the GUI allows for selecting the most common options. If a user decides he needs some less common adjustments, the configuration options gives him very granular control -and as long as the documentation on all the options is sufficient, users will be able to make those less common adjustments. + </para> + <para> + For administrators on the other hand, Revisor is the tool that gives so much granular control over what happens, that it can serve almost every specific use-case. In this aspect, Revisor could potentially replace the compose tools administrators have been developing themselves with a consistent and flexible program flow. + </para> + <para> + This document should enable you to study the process of composing installation and live media, and comprehend the logic Revisor adds to that process. + </para> + </section> + + <section id="Reference-Introduction-The_Installation_Media_Challenge"> + <title>The Installation Media Challenge</title> + <para> + When Fedora Unity first started doing these so-called Re-Spins, the challenge ahead could maybe be explained like this: + </para> + <para> + <emphasis>When a user downloads a Fedora release and installs the distribution, the user will need to download and install a number of updates. The “older” the release becomes, the more updates will be available, and the greater the total download size of these updates the user will need to download on top of the download size of the original release media.</emphasis> + </para> + <para> + “older” is in quotes on purpose, because really for an operating system -or “distribution” if you will- being released every 6 months, “old” is quite a relative concept. The number of updates available however, at any given time during the release cycle, may range from 0 right after the release (which has never happened before), to the total amount of packages installed on the user's system (often over 2000). You can imagine the size of these updates ranging from 0 MB to an astonishing 2GB(!), only 6 months after the initial release. + </para> + <para> + Some of us do not have the bandwidth capacity or enough data transfer quota to download this many extra, rather useless bits. In addition, some of us do not have an Internet connection at all, and thus benefit getting the updates from Re-Spins directly. + </para> + <para> + The use of updates in Re-Spins has several more beneficial side-effects, which we'll explain in more detail later on in this document. Long story short; If for some reason the software used to compose the media (the release) with does not work for your hardware or your specific needs, updated software incorporated in the composed installer images might resolve that problem. + </para> + <para> + This is the original challenge the Fedora Unity team resolved a long time ago, and is at the base of what Revisor does nowadays. + </para> + </section> + + <section id="Reference-Introduction-The_Live_Media_Challenge"> + <title>The Live Media Challenge</title> + <para> + Back in the day Fedora Core 5 was the most recent release, Fedora Unity created so-called live media using Kadischi. In that time, live media could only have a read-only root file system and was not as feature-rich as live media is today. However, just before Revisor came to life, two applications were developed; pungi for creating installation media, and livecd-tools for creating live media. These two applications did their work well; The media composed for a release, including many different custom live media spins were, and still are, created with these tools. Immediately, the Revisor developers set themselves a target to provide a single interface to both of those tools. + </para> + </section> + +</chapter> diff --git a/doc/Reference_Manual/en-US/Reference-Plugins.xml b/doc/Reference_Manual/en-US/Reference-Plugins.xml new file mode 100644 index 0000000..56bf3c3 --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Plugins.xml @@ -0,0 +1,131 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Plugins"> + <title>Plugins</title> + <para> + para + </para> + + <section id="Reference-Plugins-Upstream"> + <title>Upstream Plugins</title> + <para> + Plugins available from upstream, maintained by upstream + </para> + + <section id="Reference-Plugins-Upstream-Cobbler_Plugin"> + <title>Cobbler Plugin</title> + <para> + The Cobbler plugin is able to put the product composed into a Cobbler environment, by handing off the built product to the existing Cobbler infrastructure as a <emphasis>distro</emphasis>, and creating a <emphasis>profile</emphasis>. + </para> + <para> + Using this module, one can automatically import the Revisor product into a Cobbler environment, and immediately use the new Cobbler <emphasis>profile</emphasis> to start deploying or automated testing, maybe. + </para> + </section> + + <section id="Reference-Plugins-Upstream-Composer_Plugin"> + <title>Composer Plugin</title> + <para> + para + </para> + </section> + + <section id="Reference-Plugins-Upstream-Delta_Plugin"> + <title>Delta Plugin</title> + <para> + A small change to a ISO image does not require you to download the complete ISO image if you have a copy of the old ISO image. + </para> + <note> + <title>Only applicable to (...)</title> + <para> + The generation of Delta ISO images is only applicable to situations in which the ISO image does not contain SquashFS images. SquashFS images are smaller, but all SquashFS images are unique. Since the Delta principle is based on similarities, and no two SquashFS images are alike, creating a Delta on two ISO images containing SquashFS images will lead to a Delta pratically the same size as the SquashFS image. For Live Media that compresses the ext3 filesystem image into a SquashFS image, since that SquashFS image is probably over 97% of the size of the ISO image, creating Delta images for compressed Live Media does not make sense. For installation media however, most RPMs would be similar as well as (potentially) the installer images. + </para> + </note> + </section> + + <section id="Reference-Plugins-Upstream-GUI_Plugin"> + <title>GUI (Graphical User Interface) Plugin</title> + <para> + Yes, the Graphical User Interface for Revisor is actually a plugin. + </para> + </section> + + <section id="Reference-Plugins-Upstream-HUB_Plugin"> + <title>HUB Plugin</title> + <para> + para + </para> + </section> + + <section id="Reference-Plugins-Upstream-Isolinux_Plugin"> + <title>Isolinux Plugin</title> + <titleabbrev id="Isolinux_Plugin">Isolinux Plugin</titleabbrev> + <para> + The isolinux plugin adds the <literal>--isolinux-cfg</literal> command-line option to Revisor. Specify a file here, and the original <filename>isolinux.cfg</filename> that is built as part of the compose process is replaced by the <filename>isolinux.cfg</filename> specified. + </para> + </section> + + <section id="Reference-Plugins-Upstream-Jigdo_Plugin"> + <title>Jigdo Plugin</title> + <para> + para + </para> + </section> + + <section id="Reference-Plugins-Upstream-Mock_Plugin"> + <title>Mock Plugin</title> + <para> + para + </para> + </section> + + <section id="Reference-Plugins-Upstream-Rebrand_Plugin"> + <title>Rebrand Plugin</title> + <para> + The rebrand plugin hooks in to Revisor at several different stages. The goal of this plugin is to ensure no trademarked packages end up on the media. Trademarked packages may include <application>fedora-logos</application>, <application>redhat-logos</application>, and so forth. + </para> + <para> + The plugin adds a <literal>--rebrand</literal> option, to which you can specify the name of your new product. When rebranding Fedora to Omega for example, specifying <literal>--rebrand Omega</literal> would be sufficient to make sure the product does not have any Fedora trademarks. + </para> + </section> + + <section id="Reference-Plugins-Upstream-Reuse_Installer_Images_Plugin"> + <title>Reuse Installer Images Plugin</title> + <para> + para + </para> + </section> + + <section id="Reference-Plugins-Upstream-Server_Plugin"> + <title>Server Plugin</title> + <para> + para + </para> + </section> + + <section id="Reference-Plugins-Upstream-Virtualization_Plugin"> + <title>Virtualization Plugin</title> + <para> + para + </para> + </section> + + <section id="Reference-Plugins-Upstream-WUI_Plugin"> + <title>WUI (Web-based User Interface) Plugin</title> + <para> + para + </para> + </section> + + </section> + + <section id="Reference-Plugins-Writing_Your_Own"> + <title>Writing Your Own Plugins</title> + <para> + para + </para> + </section> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Testing.xml b/doc/Reference_Manual/en-US/Reference-Testing.xml new file mode 100644 index 0000000..689f1d5 --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Testing.xml @@ -0,0 +1,173 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Testing"> + <title>Testing</title> + <para> + The following test cases describe different types of testing a new Revisor release. + </para> + + <section id="Reference-Testing-Simple_Test_Cases"> + <title>Simple Test Cases</title> + <para> + This section has a few simple test cases ensuring configuration shipped with Revisor works as anticipated. + </para> + + <section id="Reference-Testing-Simple_Test_cases-Packages"> + <title>Packages</title> + <para> + Install the <application>revisor-cli</application>: + </para> + <para> + <screen># <userinput>yum --enablerepo=updates-testing install revisor</userinput></screen> + </para> + <para> + Installed are all dependencies for the Revisor CLI interface. Make sure <application>spin-kickstarts</application> is installed, a package for sample kickstarts. + </para> + <para> + Starting Revisor as follows should not show any error messages related to Revisor attempting to start up it's GUI interface: + </para> + <para> + <screen># <userinput>revisor</userinput></screen> + </para> + + <formalpara> + <title>Configuration Files</title> + <para> + The following configuration files should exist: + </para> + </formalpara> + <para> + <itemizedlist> + <listitem> + <para> + <filename>/etc/revisor/revisor.conf</filename> + </para> + </listitem> + </itemizedlist> + </para> + <para> + Each section should have a configuration file listed as <literal>main</literal>. + </para> + <para> + And, of course, every configuration file listed in each section. In this case, the following snippet is easy enough: + </para> + <para> + <screen>$ <userinput>i=0; \ +configfiles="`grep ^main /etc/revisor/revisor.conf | \ + sed -r -e 's/^main.*=\s*(.*)/\1/g'`" + +for configfile in $configfiles; do \ + [ ! -f $file ] && i=1; \ +done; \ +echo $i</userinput></screen> + </para> + <para> + Another way to test the configuration file is to execute: + </para> + <para> + <screen>$ <userinput>revisor --list-models >/dev/null</userinput></screen> + </para> + <para> + If everything is well, since <literal>STDOUT</literal> is redirected to <filename>/dev/null</filename>, you should see no messages at all. + </para> + + </section> + + <section id="Reference-Testing-Simple_Test_Cases-Configuration_Files"> + <title>Configuration Files</title> + <para> + The main Revisor configuration file is <filename>/etc/revisor/revisor.conf</filename>. The file lists a series of models, each having their own YUM configuration file in <filename>/etc/revisor/conf.d/</filename>. + </para> + <formalpara> + <title>Testing</title> + <para> + <itemizedlist> + <listitem> + <para> + For each model in <filename>/etc/revisor/revisor.conf</filename>, the <code>main</code> setting for that model should point to a valid file. + </para> + </listitem> + <listitem> + <para> + Each YUM configuration file should work. To verify, run the following command for each configuration file: + </para> + <para> + <screen>$ yum -c <replaceable>$file</replaceable> list kernel</screen> + </para> + </listitem> + </itemizedlist> + </para> + </formalpara> + <formalpara> + <title>Known Errors</title> + <para> + <itemizedlist> + <listitem> + <para> + Revisor has baseurls in YUM repositories set to <ulink url="http://localrepo" />. This URL will not be retrievable for many people, but allows the developers to quickly change mirrors. + </para> + </listitem> + <listitem> + <para> + Repositories that are unavailable at the moment of testing will throw errors Revisor can't do anything about. + </para> + </listitem> + <listitem> + <para> + If the directories <filename>revisor-yumcache/</filename> and <filename>revisor/</filename> in <filename>/var/tmp/</filename>, the default working directory, are not writeable for the user then YUM will throw permission denied errors. + </para> + <para> + Remove <filename>/var/tmp/revisor/</filename> and <filename>/var/tmp/revisor-yumcache/</filename> or run the command with root permissions. + </para> + </listitem> + </itemizedlist> + </para> + </formalpara> + </section> + + <section id="Reference-Testing-Simple_Test_Cases-Compose_Results"> + <title>Requirements for Compose Results</title> + <para> + Although heavily dependent on Anaconda for this part, these are still requirements + </para> + + <formalpara> + <title>ld-linux.so.2</title> + <para> + In the <filename>initrd.img</filename> of the composed product, if 32-bit, <filename>/lib/ld-linux.so.2</filename> (or any other version) should link to <filename>/lib/ld-2.9.so</filename> (or any other version). If <filename>/lib/ld-linux.so.2</filename> links to itself, the media will fail to install. + </para> + </formalpara> + <formalpara> + <title>How to test</title> + <para> + In a terminal, type the following command: + </para> + </formalpara> + <para> + <screen>$ <userinput>lsinitrd /path/to/initrd | grep ld-linux</userinput></screen> + </para> + <para> + See also: <ulink url="https://www.redhat.com/archives/anaconda-devel-list/2009-February/msg00115.…" /> + </para> + + </section> + </section> + + <section id="Reference-Testing-Complex_Test_Cases"> + <title>Complex Test Cases</title> + <para> + para + </para> + </section> + + <section id="Reference-Testing-Specific_Test_Cases"> + <title>Specific Test Cases</title> + <para> + para + </para> + </section> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Tips_and_Tricks.xml b/doc/Reference_Manual/en-US/Reference-Tips_and_Tricks.xml new file mode 100644 index 0000000..22a558d --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Tips_and_Tricks.xml @@ -0,0 +1,47 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Tips_and_Tricks"> + <title>Tips and Tricks</title> + <para> + para + </para> + + <section id="Reference-Tips_and_Tricks-The_spin-kickstarts_Package"> + <title>The spin-kickstarts Package</title> + <para> + para + </para> + </section> + + <section id="Reference-Tips_and_Tricks-Even_More_Debugging"> + <title>Even More Debugging</title> + <para> + something about using -x to buildinstall scripts + </para> + </section> + + <section id="Reference-Tips_and_Tricks-ksvalidator"> + <title>Kickstart Validator</title> + <para> + something about using -x to buildinstall scripts + </para> + </section> + + <section id="Reference-Tips_and_Tricks-Using_Mirrormanager_For_Mirror_Redirection"> + <title>Using Mirrormanager for Mirror Redirection</title> + <para> + Something about using Mirrormanager to redirect you to the local mirror (so you do not have to edit YUM configuration files). + </para> + </section> + + <section id="Reference-Tips_and_Tricks-The_localrepo_DNS_Alias"> + <title>Using The localrepo DNS Alias</title> + <para> + Something about using the localrepo DNS alias to point to your local mirror (either through real DNS or through /etc/hosts), so you do not have to edit the YUM configuration files. + </para> + </section> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Tweaking_The_Build_Process.xml b/doc/Reference_Manual/en-US/Reference-Tweaking_The_Build_Process.xml new file mode 100644 index 0000000..b64d3a3 --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Tweaking_The_Build_Process.xml @@ -0,0 +1,40 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Tweaking_The_Build_Process"> + <title>Tweaking the build process</title> + <para> + para + </para> + + <section id="Reference-Tweaking_The_Build_Process-Reusing_Existing_Installer_Images"> + <title>Reusing Existing Installer Images</title> + <para> + para + </para> + </section> + + <section id="Reference-Tweaking_The_Build_Process-Building_The_Installer_Images_In_Mock"> + <title>Building The Installer Images in Mock</title> + <para> + para + </para> + </section> + + <section id="Reference-Tweaking_The_Build_Process-Omitting-isomd5sum"> + <title>Omitting isomd5sums</title> + <para> + para + </para> + </section> + + <section id="Reference-Tweaking_The_Build_Process-Omitting-sha1sums"> + <title>Omitting SHA1SUMS</title> + <para> + para + </para> + </section> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference-Using_Kickstart.xml b/doc/Reference_Manual/en-US/Reference-Using_Kickstart.xml new file mode 100644 index 0000000..6145b95 --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference-Using_Kickstart.xml @@ -0,0 +1,118 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<chapter id="Reference-Using_Kickstart"> + <title>Using Kickstart</title> + <para> + Kickstart is a configuration file format for automating installation procedures. Or at least, it was, originally. Nowadays, kickstart files are used as input to the compose tools, including Revisor. + </para> + <para> + Revisor again is unique in that it does not require a kickstart file for input. The other tools only take kickstart configuration files. Revisor though allows most of what is in a kickstart file to be configured interactively in Graphical User Interface mode. + </para> + + <section id="Reference-Using_Kickstart-How_Kickstart_Is_Used"> + <title>How Kickstart Is Used</title> + <para> + There's two cases in which a kickstart file is used differently. One is during the compose of installation media, and the other of course is during the compose of live media, or virtualization media. + </para> + + <section id="Reference-Using_Kickstart-How_Kickstart_Is_Used-Installation_Media"> + <title>Installation Media</title> + <para> + In the case of installation media, the following settings are used: + </para> + <para> + <itemizedlist> + <listitem> + <formalpara> + <title><literal>repo</literal></title> + <para> + The <literal>repo</literal> command in kickstart is used when Revisor is configured to use the repositories configured in the kickstart file only. Use <literal>kickstart_repos = 1</literal> to enable this feature, or set the appropriate checkbox in the Revisor GUI. + </para> + </formalpara> + </listitem> + <listitem> + <formalpara> + <title><literal>%packages</literal></title> + <para> + The <literal>%packages</literal> section in kickstart is used to determine the RPM payload on the installation media. It can include groups and packages, and exclude packages. It accepts wildcards, both in includes and excludes of packages (but not groups). + </para> + </formalpara> + </listitem> + </itemizedlist> + </para> + <note> + <title>@core and @base</title> + <para> + By default, groups @core and @base are included in the package manifest. You can specify @base to not be included, by using <literal>%packages --nobase</literal>, but @core cannot be excluded using a kickstart package manifest. + </para> + </note> + <para> + Using <literal>kickstart_exact</literal>, you can exclude @core and @base so that you need to explicitly select them in the kickstart package manifest. + </para> + <para> + Using <literal>kickstart_exact_nevra</literal> ... + </para> + </section> + </section> + + <section id="Reference-Using_Kickstart-The_Kickstart_Package_Manifest"> + <title>The Kickstart Package Manifest</title> + <para> + para + </para> + + <formalpara> + <title>Group @core</title> + <para> + para + </para> + </formalpara> + + <formalpara> + <title>Group @base</title> + <para> + para + </para> + </formalpara> + + <formalpara> + <title>Including groups of packages</title> + <para> + para + </para> + </formalpara> + + <formalpara> + <title>Including a single package</title> + <para> + para + </para> + </formalpara> + + <formalpara> + <title>Excluding a single package</title> + <para> + para + </para> + </formalpara> + + <formalpara> + <title>Using wildcard matches</title> + <para> + para + </para> + </formalpara> + + <section id="Reference-Using_Kickstart-Using_Kickstart_With_Package_NEVRA"> + <title>Using Kickstart with Package NEVRA</title> + <para> + para + </para> + </section> + + </section> + +</chapter> + diff --git a/doc/Reference_Manual/en-US/Reference.ent b/doc/Reference_Manual/en-US/Reference.ent new file mode 100644 index 0000000..9edfaea --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference.ent @@ -0,0 +1,5 @@ +<!ENTITY PRODUCT "Revisor"> +<!ENTITY BOOKID "Reference Manual"> +<!ENTITY YEAR "2007 - 2009"> +<!ENTITY HOLDER "Jeroen van Meeuwen"> + diff --git a/doc/Reference_Manual/en-US/Reference.xml b/doc/Reference_Manual/en-US/Reference.xml new file mode 100644 index 0000000..0e7af68 --- /dev/null +++ b/doc/Reference_Manual/en-US/Reference.xml @@ -0,0 +1,27 @@ +<?xml version='1.0'?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<book status="draft"> + <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="Reference-Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Features.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Using_Kickstart.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Compose_Process_Details.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Plugins.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Tweaking_The_Build_Process.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Tips_and_Tricks.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Frequently_Asked_Questions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <xi:include href="Reference-Development.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <index /> + <xi:include href="Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + +</book> + diff --git a/doc/Reference_Manual/en-US/Reference_Manual.ent b/doc/Reference_Manual/en-US/Reference_Manual.ent deleted file mode 100644 index 9edfaea..0000000 --- a/doc/Reference_Manual/en-US/Reference_Manual.ent +++ /dev/null @@ -1,5 +0,0 @@ -<!ENTITY PRODUCT "Revisor"> -<!ENTITY BOOKID "Reference Manual"> -<!ENTITY YEAR "2007 - 2009"> -<!ENTITY HOLDER "Jeroen van Meeuwen"> - diff --git a/doc/Reference_Manual/en-US/Reference_Manual.xml b/doc/Reference_Manual/en-US/Reference_Manual.xml deleted file mode 100644 index 4f7ee5f..0000000 --- a/doc/Reference_Manual/en-US/Reference_Manual.xml +++ /dev/null @@ -1,27 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<book status="draft"> - <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="Revisor_Reference_Manual-Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Features.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Installation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Using_Kickstart.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Compose_Process_Details.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Plugins.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Tweaking_The_Build_Process.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Tips_and_Tricks.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Frequently_Asked_Questions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="Revisor_Reference_Manual-Development.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="Revision_History.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <index /> - <xi:include href="Appendix.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - -</book> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Compose_Process_Details.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Compose_Process_Details.xml deleted file mode 100644 index 6b12e6c..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Compose_Process_Details.xml +++ /dev/null @@ -1,431 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Compose_Process_Details"> - <title>Compose Process Details</title> - <para> - This chapter lists the details of the compose process as well as dives deep into the features of Revisor. - </para> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Overview"> - <title>Overview</title> - <titleabbrev id="Compose_Process_Details-Overview">Overview</titleabbrev> - <para> - Of course, the compose process for installation media is a little different then the compose process for live media. - </para> - <para> - When composing, Revisor starts out doing the following: - </para> - <para> - <itemizedlist> - <listitem> - <para> - Revisor initiates and loads plugins, options, and defaults. At this point, Revisor has a so-called <emphasis>ConfigStore</emphasis> that holds all options Revisor knows about. - </para> - </listitem> - <listitem> - <para> - Revisor reads the options from the command-line. - </para> - </listitem> - <listitem> - <para> - Revisor reads the configuration file specified with the <code>--config</code> command-line parameter, or uses it's builtin default, <filename>/etc/revisor/revisor.conf</filename>. - </para> - </listitem> - <listitem> - <para> - Revisor reads the global <code>[revisor]</code> section for all settings available in it's <emphasis>ConfigStore</emphasis> and sets those configured in the global section. Remember that if an option is not available in the <emphasis>ConfigStore</emphasis> but is configured in the global configuration section, it is ignored. - </para> - </listitem> - <listitem> - <para> - If a model is specified in the configuration file's global section <code>[revisor]</code>, Revisor will set that model to be used and loads it. - </para> - </listitem> - <listitem> - <para> - If a model has been specified on the command-line, with option <code>--model</code>, Revisor loads that model. - </para> - </listitem> - <listitem> - <para> - When loading the model, Revisor again iterates over all the settings that are in the <emphasis>ConfigStore</emphasis>, checks if the setting has been configured in the model section, and adjusts the setting in the <emphasis>ConfigStore</emphasis> if necessary. Again remember that if the <emphasis>ConfigStore</emphasis> does not know about one or the other option already, that setting is ignored. - </para> - </listitem> - <listitem> - <para> - Now that the defaults and configuration file settings have been applied to the <emphasis>ConfigStore</emphasis>, it is time for Revisor to look at the options specified on the command-line to see if you wanted to override anything. - </para> - </listitem> - <listitem> - <para> - While loading each configuration setting available in the global <code>[revisor]</code>, model-specific sections and/or command-line, Revisor checks every settings against a function that is specifically written to check such setting. For example, the label of an ISO cannot be longer then 32 characters. - </para> - </listitem> - <listitem> - <para> - Especially in CLI mode, these settings build up the task list for Revisor. If there's nothing to do, Revisor will throw an error explaining what's missing. If there's things to do that cannot be done in one run, Revisor will throw an error explaining that. - </para> - </listitem> - <listitem> - <para> - In Graphical User Interface mode however, if the settings loaded so far are all OK, the GUI will start. Since you can still adjust a few settings from within the GUI, the settings loaded so far will be the defaults for configuration settings that have a dialog for you to adjust them with, throughout the rest of the process. - </para> - </listitem> - </itemizedlist> - </para> - </section> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Installation_Media"> - <title>Installation Media</title> - <para> - As we've explained before, composing installation media is a little different then composing live media. That's not just because installation media should start an installation procedure and live media should show you a nice, shiny, fully-functional Desktop. - </para> - <para> - For one, installation media allows split media. This means that Revisor can span the payload of the product over multiple ISO images or multiple discs, if you will. When composing installation media, Revisor basically does the following: - </para> - <para> - <itemizedlist> - <listitem> - <para> - Of course, Revisor goes through the loading of configuration options mentioned in the <xref linkend="Revisor_Reference_Manual-Compose_Process_Details-Overview" endterm="Compose_Process_Details-Overview" />. - </para> - </listitem> - <listitem> - <para> - When you're done specifying options in the GUI, or when Revisor thinks it can go ahead using the options specified in CLI mode, it takes the list of packages selected from either the GUI or the kickstart <code>%packages</code> manifest. - </para> - <para> - Not getting too deep into details here, yet, because some of these things are routines shared with other composing modes, but here's a few additional considerations Revisor makes when doing the package selection. - </para> - <para> - <itemizedlist> - <listitem> - <para> - Normally, a kickstart <code>%packages</code> manifest only allows you to select package <emphasis>names</emphasis>. With Revisor though, you can select exact package <emphasis>NEVRA</emphasis> to select a certain version or architecture for the package that you want. Additionally, if a package is not available, Revisor searches the <emphasis>Provides</emphasis> of the available packages. - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </itemizedlist> - </para> - </section> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Live_Media"> - <title>Live Media</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Respin_Mode"> - <title>Respin Mode</title> - <para> - Revisor has a respin mode that in some aspects differs from the regular routines. It is intended to reflect behaviour of tools in use by the Fedora Project Release Engineering team as closely as possible. - </para> - <para> - Re-Spin mode only affects installation media products. - </para> - <para> - In Re-Spin mode, the way the RPM payload is determined from kickstart differs from Revisor's normal procedures. See <xref linkend="Revisor_Reference_Manual-Using_Kickstart" /> for more details on using a kickstart package manifest. - </para> - <para> - A kickstart file's so-called <xref linkend="Revisor_Reference_Manual-Appendix-Terminology-package_manifest" /> usually looks like: - </para> - <para> - <screen>%packages -@group1 -@group2 --nodefaults -@group3 --optional -package1 -package2 --package3 -%end</screen> - </para> - <para> - Which tells us the following: - </para> - <para> - <itemizedlist> - <listitem> - <para> - Include all mandatory and default packages from group1 - </para> - </listitem> - <listitem> - <para> - Include all mandatory packages from group2 - </para> - </listitem> - <listitem> - <para> - Include all mandatory, default and optional packages from group3 - </para> - </listitem> - <listitem> - <para> - Include package1, and package2 - </para> - </listitem> - <listitem> - <para> - Exclude package3 - </para> - </listitem> - </itemizedlist> - </para> - <para> - Depending on how you use this instructions or information, there is a slight difference in the package set that ends up on the media you compose. - </para> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Respin_Mode-Selecting_Groups"> - <title>Selecting Groups</title> - <para> - Selecting groups has the following logic: When you load a repository you may also load the groups file (often referred to as 'comps' or 'comps.xml'). This comps file is an XML file with categories, groups (per category), and per group: - </para> - <para> - <itemizedlist> - <listitem> - <para> - a list of mandatory packages. If you select or include the group, these packages come with it. - </para> - </listitem> - <listitem> - <para> - a list of default packages. If you select or include the group, these packages will come with it as a default. If you only want the mandatory, minimum set of packages for this group, in a kickstart package manifest append <code>--nodefaults</code> to the group line or in the Revisor GUI, right-click on the group and choose <emphasis>Deselect all packages</emphasis>. - </para> - </listitem> - <listitem> - <para> - a list of optional packages. If you select a group you have not yet selected these packages. To select the optional packages of a group, in a kickstart package manifest append <code>--optional</code> to the group line or in the Revisor GUI, right-click on the group and choose <emphasis>Select all optional packages</emphasis>. - </para> - </listitem> - <listitem> - <para> - a list of conditionals. If you select this group, these conditionals are thrown into the package sack and transaction information and include or exclude other packages. Suppose you select the '@nl-support' or “Dutch Support” group from the Languages or Localization category, you would end up with support for the Dutch language in all applications that have that kind of support. - </para> - </listitem> - </itemizedlist> - </para> - </section> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Respin_Mode-Select_Matching_Packages"> - <title>Select Matching Packages</title> - <para> - This is the logic Revisor applies when running in Re-Spin mode (on the CLI, specify <code>--respin</code>). It imitates the behavior pungi has, and thus enables you to copy that behavior. Note that <code>--respin</code> has other implications as well. - </para> - <para> - First of all, it iterates the groups in the kickstart package manifest. For each group, it appends the names of the mandatory packages to a list, and depending on the additional parameters specified with that group (<code>--nodefaults</code> or <code>--optional</code>), appends the names of the other packages in that group as well. - </para> - <para> - Then it iterates over the package names in the package manifest. These package names are appended to the same list of package names too. This includes package 'names' with some sort of wildcard (?, or *). - </para> - <para> - Then it iterates over all the excluded packages, appending each of those to the YUM configuration exclude list. - </para> - <para> - Now that Revisor has a very simple, flat list of package names, it uses YUM's internal matching logic 5 to get what packages in the repositories matched exactly (by name), matched (by wildcard) and did not match at all. Revisor then selects the exact matches and matches, adding them to the transaction. - </para> - </section> - </section> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Dependency_Resolving"> - <title>Dependency Resolving</title> - <indexterm> - <primary>Dependency Resolving</primary> - </indexterm> - <para> - Dependency resolving is the area where some of the efficiency Revisor can gain for you comes from. While of course there is specific reasons to do things one way, or the other, most people I speak to about Revisor, it is not very clear why, or what Revisor does in this area. First of all, there's two ways of resolving dependencies: - </para> - <para> - <orderedlist> - <listitem> - <formalpara> - <title>Inclusive Dependency Resolving</title> - <indexterm> - <primary>Dependency Resolving</primary> - <secondary>Inclusive</secondary> - </indexterm> - <para> - Iterate all packages in the transaction and list their requirements, then for each of those requirements, find all packages that provide a matching capability, add those packages to the transaction, and don't forget to add the requirements those packages have themselves, back into the pile of (unmet) requirements. - </para> - </formalpara> - </listitem> - <listitem> - <formalpara> - <title>Exclusive Dependency Resolving</title> - <indexterm> - <primary>Dependency Resolving</primary> - <secondary>Inclusive</secondary> - </indexterm> - <para> - Iterate all the packages and for each of the requirements found, find the best package that meets the requirement. This is also YUMs default behavior. Anaconda uses YUM during the installation, and this is the behaviour of YUM used during the installation. - </para> - </formalpara> - </listitem> - </orderedlist> - </para> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Dependency_Resolving-Inclusive"> - <title>Inclusive Dependency Resolving</title> - <para> - Hypothetically, you could describe inclusive dependency as follows: - </para> - <para> - <screen>final_packages = [] -more_to_do = True -while more_to_do: -more_to_do = False -for package in packages: - if package in final_packages: - continue - - dependencies = find_package_dependencies() - for dependency in dependencies: - pulled_in_package = pull_in_dependency() - if pulled_in_package not in final_packages: - packages.append(pulled_in_package) - more_to_do = True</screen> - </para> - <para> - So, what does this mean? Basically, it means that if there is a requirement for a capability, all packages providing that capability are being pulled in. Now imagine package 'foo' requires capability 'web-client'. There's a number of packages providing that capability, right? So you get Firefox, lynx, elinks, konqueror, safari, Netscape, Internet Explorer, emacs, for free! All of those pull in their own dependencies also, of course. - </para> - <note> - <para> - If you catch this before it catches you, you can prevent the packages from being pulled in during dependency resolving by not making the package available in the <xref linkend="Revisor_Reference_Manual-Appendix-Terminology-Package_Sack" /> in the first place, using the <literal>-firefox</literal> syntax in the kickstart package manifest, and setting <literal>kickstart_uses_pkgsack_excludes</literal> to 1. - </para> - </note> - <note> - <para> - You may have thought of it; pulling in packages this way may give you a package set (or <emphasis>RPM payload</emphasis>) that has conflicting packages. Imagine package <application>foo</application> requiring capability <application>bar</application>, which is provided by two packages that conflict with one another (either on explicit <literal>Conflicts:</literal> RPM header or file level). Both will be pulled in, hence disabling you to install everything (<literal>'*'</literal> or -previously- <literal>@Everything</literal> in the kickstart package manifest). - </para> - </note> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Dependency_Resolving-Inclusive-When_This_Makes_Sense"> - <title>When This Makes Sense</title> - <para> - If you are composing a large distribution of which 3 million users in even so many different situations having so many different expectations and desires, you will want this behaviour, since you won't be able to determine which one of the packages for each capability someone in that group wants, and which one may not want. Or, in case of upgrades, what the system needs. Shipping them all on the same media is the best solution in these cases. - </para> - </section> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Dependency_Resolving-Inclusive-When_This_Does_Not_Make_Sense"> - <title>When This Does Not Make Sense</title> - <para> - <itemizedlist> - <listitem> - <para> - When creating installation media to be installed unattended, or to be used in conjunction with deployment strategies - </para> - </listitem> - <listitem> - <para> - When creating installation media to be upgrading PCs you have controlled from the beginning, such as in a company - </para> - </listitem> - <listitem> - <para> - Installation for a small group of users or systems - </para> - </listitem> - <listitem> - <para> - When creating minimal installation media, or media with a minimal RPM payload. - </para> - </listitem> - <listitem> - <para> - When creating installation media that is to be used with installing "Everything" in the RPM payload. - </para> - </listitem> - </itemizedlist> - </para> - </section> - </section> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Dependency_Resolving-Exclusive"> - <title>Exclusive Dependency Resolving</title> - <para> - Exclusive dependency resolving is what YUM does when you execute a <application>yum install</application>. Unless you've specified one of the packages satisfying any of the dependencies in the transaction, YUM is going to look up the best match for you. This results in the installation of only one package providing the requirement(s) of other packages, rather then all packages providing said requirement being installed. - </para> - <para> - As an example, imagine you install a package foo which requires capability web-client. Using exclusive dependency resolving, YUM would select one package providing the web-client capability whereas inclusive dependency resolving would include all packages providing the web-client capability. - </para> - <para> - During the installation procedure, one of the major features of installation media, anaconda is going to use YUM dependency resolving to satisfy all the dependencies. - </para> - <note> - <title>Installation Procedure !== Upgrade Procedure</title> - <para> - Note that an installation procedure is not the same as an upgrade procedure. With an installation procedure for example, you have control over the partitioning layout whereas with an upgrade procedure, you have none. More importantly, during an upgrade procedure, the (already installed) system has an existing package set which needs to be updated/upgraded and thus could possibly introduce dependency resolving problems, because of third party packages installed on the system, or because the media used to upgrade the system with does not contain the software packages needed to complete the upgrade RPM transaction. - </para> - </note> - </section> - - </section> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Copying_Arbitrary_Files_Onto_The_Media"> - <title>Copying Arbitrary Files Onto the Media</title> - <para> - With <literal>--copy-dir</literal>, you can specify a path Revisor should copy onto the media. - </para> - <formalpara> - <title>Installation Media</title> - <para> - In the case of installation media, the path specified with <literal>--copy-dir</literal> will be copied recursively to the <filename>files/</filename> sub-directory at the root of the ISO image (or the first ISO image if you compose split media). - </para> - </formalpara> - <para> - A few use-case examples: - </para> - <para> - <itemizedlist> - <listitem> - <para> - If one kickstart profile is not enough for you to deploy the product onto your systems, create a directory that holds multiple kickstart files and specify the path to that directory using <literal>--copy-dir</literal>. The kickstart files now end up available to the installation procedures as <filename>cdrom:/files/*.ks</filename>, and can thus be used by specifying them on the kernel cmdline (<code>ks=cdrom:/files/profile1.ks</code>), or, when used in combination with <literal>--isolinux-cfg</literal> from the <xref linkend="Revisor_Reference_Manual-Plugins-Upstream-Isolinux_Plugin" endterm="Isolinux_Plugin" />, can be added as an option in the isolinux menu. - </para> - </listitem> - <listitem> - <para> - If you have files or scripts that need to be copied onto, or run on, the installed system before it attempts to reboot and operate normally, you can use <literal>--copy-dir</literal> to make these files and scripts available during the installation and copy or execute them from either <code>%pre</code> or <code>%post</code> scripts. - </para> - </listitem> - </itemizedlist> - </para> - <formalpara> - <title>Live Media</title> - <para> - In the case of live media, the path specified with <literal>--copy-dir</literal> will be copied recursively onto the root directory (<filename>/</filename>) of the live media filesystem (which is probably loop-mounted onto <filename>/var/tmp/revisor/</filename>). - </para> - </formalpara> - <para> - If, for example, you want to copy a home directory onto the live media, and the home directory you want to copy is at <filename>/home/user1/</filename> on the composing system, you copy this directory so that the root of that new directory has a sub-directory <filename>home/</filename> which in turn contains a sub-directory <filename>user1/</filename>: - </para> - <para> - <screen>$ <userinput>mkdir -p /tmp/something/home/</userinput> -$ <userinput>cp -a /home/user1 /tmp/something/home/.</userinput> -$ <userinput>revisor [options] --copy-dir /tmp/something/</userinput></screen> - </para> - </section> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Cleaning_Up"> - <title>Cleaning Up</title> - <para> - Revisor tends to clean up after itself by default. If a product compose succeeds, you (probably) don't need to change this default behaviour. However, by default, Revisor tends to leave the YUM cache directories untouched. This is to prevent you from having to download all the packages a second, third or more times when you run another compose. - </para> - <para> - To change this default behaviour, Revisor has an option <literal>--clean-up</literal>. The default value for this option is <literal>1</literal>, meaning Revisor will clean up it's temporary, compose-specific files, but no files that could be re-used. Specifying <literal>--clean-up=0</literal> will cause Revisor to leave everything behind and not clean anything up at all. This is most ideal for troubleshooting purposes, where one needs to examine the temporary, compose-specific files and see what went wrong. To clean up everything however, because for example you might be low on disk-space, use <literal>--clean-up=2</literal>. Revisor will then also clean up the files that could be re-used. - </para> - - <section id="Revisor_Reference_Manual-Compose_Process_Details-Cleaning_Up-Exception-to-the-Rule"> - <title>Exception to the Rule</title> - <para> - There's one exception to the rule of cleaning up. <filename>/var/tmp/revisor/</filename>, or put more accurately, the path specified as the <code>installroot</code> in the YUM configuration file configured with the model used to compose the product, will not be cleaned up afterwards. When composing live media, this directory may still be in use as a mount-point for the live media filesystem. Removing this directory recursively in these cases would not make sense. - </para> - </section> - </section> - -</chapter> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Configuration.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Configuration.xml deleted file mode 100644 index 647706f..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Configuration.xml +++ /dev/null @@ -1,280 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Configuration"> - <title>Configuration</title> - <para> - Revisor configuration can be performed using <xref linkend="Revisor_Reference_Manual-Configuration-Files" />, or through <xref linkend="Revisor_Reference_Manual-Configuration-Command-line_Options" />. - </para> - - <section id="Revisor_Reference_Manual-Configuration-Files"> - <title>Configuration Files</title> - <para> - Revisor uses configuration files for a large part of it's operations. These files mostly reside in <filename>/etc/revisor/</filename>. There is two types of files Revisor uses: - </para> - <para> - <orderedlist> - <listitem> - <formalpara> - <title>Revisor Configuration Files</title> - <para> - Revisor configuration files, such as <filename>/etc/revisor/revisor.conf</filename>, contain information and settings unique to Revisor. A Revisor configuration file is where you specify default options, and include information on different products you want to compose. - </para> - </formalpara> - </listitem> - <listitem> - <formalpara> - <title>YUM Configuration Files</title> - <para> - YUM configuration files, such as the files in <filename>/etc/revisor/conf.d/</filename>, contain configuration for YUM. To be more precise, Revisor doesn't even handle the files (it let's YUM do so). The files in <filename>/etc/revisor/conf.d/</filename> practically contain the same information as <filename>/etc/yum.conf</filename> combined with the files in <filename>/etc/yum.repos.d/</filename> (but not exactly the same content!). - </para> - </formalpara> - </listitem> - </orderedlist> - </para> - - <section id="Revisor_Reference_Manual-Configuration-Files-_etc_revisor_revisor.conf"> - <title><filename>/etc/revisor/revisor.conf</filename></title> - <para> - The default Revisor configuration file is <filename>/etc/revisor/revisor.conf</filename>. This configuration file contains two sections: - </para> - <para> - <orderedlist> - <listitem> - <formalpara> - <title><literal>[revisor]</literal></title> - <para> - The global section. Options specified in this section apply to all the models defined in this configuration file. - </para> - </formalpara> - <para> - See also: <xref linkend="Revisor_Reference_Manual-Configuration-Global_and_Model_Configuration" /> - </para> - </listitem> - <listitem> - <formalpara> - <title><literal>[<replaceable>model</replaceable>]</literal></title> - <para> - Model configuration. One section per <xref linkend="Revisor_Reference_Manual-Appendix-Terminology-model" />. - </para> - </formalpara> - <para> - See also: <xref linkend="Revisor_Reference_Manual-Configuration-Global_and_Model_Configuration" /> - </para> - </listitem> - </orderedlist> - </para> - <para> - Model sections basically define a single product. Amongst other things, the distribution name, release version, architecture for the product to be composed and what YUM configuration file to use, are (often) defined on a per-model basis. There is a large number of settings available for models, and they are all related to how the product is going to look like. The product name, the location of the RPM payload for installation media, the ISO label, the YUM configuration file to use, are all model settings. - </para> - <para> - Using models, you can reproduce the outcome of the compose process, a <emphasis>product</emphasis>, simply by not changing the model configuration anymore. If you want something different, you can just add another model section, and name it differently. - </para> - <para> - To see what models are available with the Revisor standard package, use: - </para> - <para> - <screen>$ <userinput>revisor --list-models</userinput></screen> - </para> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Files-_etc_revisor_conf.d_"> - <title><filename>/etc/revisor/conf.d/</filename></title> - <para> - The default YUM configuration files used by Revisor. In a model configuration section, the <literal>main =</literal> setting points to one of the YUM configuration files in <filename>/etc/revisor/conf.d/</filename> - </para> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Files-Updates"> - <title>Updates to Configuration Files</title> - <para> - The Revisor packages are not allowed to overwrite files in <filename>/etc/</filename>, and they should thus not do so. If an update to Revisor is installed on your system, files with the extension <literal>.rpmnew</literal> may be created --if you had changed anything in the file before applying the update. Since this world isn't perfect, configuration errors may exist in the configuration files shipped with Revisor. Please pay close attention to updates to these configuration files by examining the <literal>.rpmnew</literal> files. - </para> - <para> - You can use any file location (not just <filename>/etc/revisor/</filename>) for your own custom configuration. - </para> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Files-Changing_Configuration_Files"> - <title>Changing Configuration Files</title> - <para> - If you are creating your own models off of the ones that ship with Revisor itself, please consider using an alternative configuration file (a file other then <filename>/etc/revisor/revisor.conf</filename>, or copy the original file for safekeeping. This way, you can always return to a working, sample configuration file and test whether it is Revisor causing errors, or configuration mistakes. - </para> - </section> - - </section> - - <section id="Revisor_Reference_Manual-Configuration-Global_and_Model_Configuration"> - <title>Global and Model Configuration</title> - <para> - The default Revisor configuration file, <filename>/etc/revisor/revisor.conf</filename> consists of multiple sections (the file is in .INI format). One is the <literal>[revisor]</literal> global section, where you specify configuration options that apply to each other section or <xref linkend="Revisor_Reference_Manual-Appendix-Terminology-model" />. - </para> - <para> - The options specified in the global and model configuration sections apply to the Revisor compose in the following order: - </para> - <para> - <orderedlist> - <listitem> - <para> - The options from the global section are read, tested and set. - </para> - </listitem> - <listitem> - <para> - The options from a model section are read, tested and set, regardless of whether the global section had caused the setting to be set to a certain value already. - </para> - </listitem> - </orderedlist> - </para> - <para> - For example, if you know all the models in a configuration file are optical live media products, the configuration sections could look like the following: - </para> - <para> - <screen>[revisor] -# Optical live media for all models -media_live_optical = 1 - -[model1] -main = /etc/revisor/conf.d/revisor-model1.conf -description = The model1 product -architecture = i386 -# This is already configured in the global section of -# this configuration file and can thus be removed. -#media_live_optical = 1</screen> - </para> - <note> - <title>When Running the GUI</title> - <para> - Note that when running Revisor in Graphical User Interface mode, you can still change a lot of the settings supplied by Revisor through the configuration files loaded. When you are running Revisor in GUI mode, the configuration files supply the defaults. - </para> - </note> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Yum_Repositories"> - <title>YUM Repository Configuration</title> - <para> - The files in <filename>/etc/revisor/conf.d/</filename> are YUM configuration files. Revisor directs YUM to use these files during the compose process, and does not handle these files itself. This chapter lists a few tips and tricks. - </para> - <para> - Because these files are YUM Configuration files, you can configure anything that YUM supports. See <application>man yum.conf</application> for more details. - </para> - - <section id="Revisor_Reference_Manual-Configuration-Yum_Repositories-releasever_and_basearch"> - <title>$releasever and $basearch</title> - <para> - When configuring a repository URL, make sure you do not use <replaceable>$releasever</replaceable> or <replaceable>$basearch</replaceable> variables. Since Revisor allows cross-composing distributions between different versions of the operating system, as well as different architectures, these variables need to be expanded to the value intended. - </para> - <para> - See also <xref linkend="Revisor_Reference_Manual-Configuration-Yum_Repositories-Troubleshooting" /> - </para> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Yum_Repositories-Using_a_Local_Mirror"> - <title>Using a Local Mirror</title> - <para> - If you have a local mirror of Fedora, you can use the <literal>baseurl</literal> configuration directive in each repository configuration section to tell YUM to use the local mirror. - </para> - <para> - Optionally, you can also disable the <literal>mirrorlist</literal>, preferably by outcommenting it, so that YUM will only use the local mirror. - </para> - <para> - The default <literal>baseurl</literal> uses <literal>http://download.fedoraproject.org/</literal>. This location may or may not be suitable for you. If you have a local mirror, you might want to change this setting here, or add your mirror to Fedora Project's Mirrorlist. - </para> - <note> - <title>Adding your local mirror to the Mirrorlist</title> - <para> - You can add your local mirror to the Mirrorlist, so that the Fedora Project mirrorlist redirects you to your local mirror. Additionally, systems in your local network(s) will be redirected to the local mirror. The local mirror does not have to be a public mirror in order to do so. See <ulink url="http://admin.fedoraproject.org/mirrormanager/" /> for more details. - </para> - </note> - <para> - Set each <literal>baseurl</literal> to the location of the repository on the local mirror. - </para> - <para> - See also <xref linkend="Revisor_Reference_Manual-Configuration-Yum_Repositories-Troubleshooting" /> - </para> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Yum_Repositories-Using_Local_Files"> - <title>Using Local Files</title> - <para> - If you have the repositories on your local filesystem, configure a <literal>baseurl</literal> of <filename>file://<replaceable>/path/to/repository/</replaceable></filename>. - </para> - <note> - <title>Make sure to supply the correct path</title> - <para> - Make sure to supply the correct path to the repository. <filename>file://</filename> is the "<emphasis>protocol</emphasis>" for the location, and the location is <filename><replaceable>/path/to/repository/</replaceable></filename>. Put together, you have <emphasis>three</emphasis> slashes. - </para> - </note> - <para> - See also <xref linkend="Revisor_Reference_Manual-Configuration-Yum_Repositories-Troubleshooting" /> - </para> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Yum_Repositories-Using_a_DVD"> - <title>Using a DVD</title> - <para> - A DVD does not contain enough packages to rebuild the installer images. If you are using a DVD and you want to rebuild the installer images, you will need to have a network connection and a mirror you can reach. - </para> - <para> - There is a list of required packages, but since the packages change per release and may change in the middle of the release cycle as well, we cannot hand you a list that just works. - </para> - <para> - See also <xref linkend="Revisor_Reference_Manual-Configuration-Yum_Repositories-Troubleshooting" /> - </para> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Yum_Repositories-Adding_Third_Party_Repositories"> - <title>Adding Third Party Repositories</title> - <para> - When adding a third party repository, make sure you add the correct release version as well as architecture to the Revisor YUM configuration file. Verify the location for the <literal>baseurl</literal> and/or <literal>mirrorlist</literal> you configure manually or through YUM. Make sure you expand any <literal>$releasever</literal>, <literal>$basearch</literal> and <literal>$arch</literal> variables. - </para> - <para> - See also <xref linkend="Revisor_Reference_Manual-Configuration-Yum_Repositories-Troubleshooting" /> - </para> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Yum_Repositories-Creating_Your_Own_Repository"> - <title>Creating Your Own Repository</title> - <para> - Creating your own repository is relatively simple. You take a directory, dump some RPM packages in it, and run <application>createrepo</application>. See <literal>man createrepo</literal> for more information. - </para> - <para> - People often wonder how Revisor handles comps.xml group files. - </para> - <para> - When you create your own repository, follow the directions in <xref linkend="Revisor_Reference_Manual-Configuration-Yum_Repositories-Adding_Third_Party_Repositories" /> to add the repository configuration to Revisor's YUM configuration, since your own repository is a third party repository as well. - </para> - <para> - See also <xref linkend="Revisor_Reference_Manual-Configuration-Yum_Repositories-Troubleshooting" /> - </para> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Yum_Repositories-Troubleshooting"> - <title>Testing & Troubleshooting the YUM Configuration</title> - <para> - Before you use the (modified) configuration file, take it for a test run. - </para> - </section> - - </section> - - <section id="Revisor_Reference_Manual-Configuration-Configuring_A_Proxy"> - <title>Configuring A Proxy Server</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Configuration-Command-line_Options"> - <title>Command-line Options</title> - <para> - With the command-line options available, you can configure options that either override what is in the configuration file or have simply not been configured using the configuration file. With the default configuration files that come with the <application>revisor-cli</application> package for example, no media products have been pre-configured in the default section. In the <application>revisor-unity</application> package however, some default configuration has been applied so that Fedora Unity Re-Spins actually create CD, DVD and Rescue ISO images as well as the Installation Tree and include the sources. - </para> - <para> - Only some configuration options have CLI parameters. Use <application>revisor --help</application> to see a complete list of configuration options you can supply on the command line. - </para> - </section> - -</chapter> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Development.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Development.xml deleted file mode 100644 index 9df83c1..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Development.xml +++ /dev/null @@ -1,220 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Development"> - <title>Development</title> - <para> - This chapter sheds some light on development of Revisor, such as different branches and maintenance policies, versioning schemas, etcetera. - </para> - <para> - This part of the documentation relies on whether you have <application>sudo</application> set up properly. If you have not, you're on your own. - </para> - - <section id="Revisor_Reference_Manual-Development-Running_Revisor_from_Source"> - <title>Running Revisor from Source</title> - <para> - The latest code in GIT can be built into a RPM you can install but one of the advantages of having the complete source tree is that you can run it directly from that source tree so that when you pull in the next updates you do not have to rebuild the RPM. Note that we do not bump the version number for every little change we make, and as such the RPM built does not allow you to use <literal>rpm -Uvh</literal> or <literal>rpm -Uvh --oldpackage</literal>. Of course, Revisor's Makefiles also allow <application>make install</application>, but that leaves a number of unmanaged files on your computer you would have to track down manually in order to remove Revisor completely. - </para> - <warning> - <title>Cannot have Revisor RPMs installed</title> - <para> - When running revisor from within the source tree, you cannot have any of the Revisor packages installed. Having Revisor RPM packages installed regardless will mess up the GIT repository or source tree. - </para> - </warning> - <para> - To run Revisor from within the source tree, checkout the master branch, and run the <filename>./switchhere</filename> script: - </para> - <para> - <screen>$ <userinput>./switchhere</userinput></screen> - </para> - <para> - The <filename>./switchhere</filename> script does the following: - </para> - <para> - <itemizedlist> - <listitem> - <para> - Symlink <filename>/etc/revisor/</filename> to <filename><replaceable>$PWD</replaceable>/conf/</filename> so that <filename>/etc/revisor/revisor.conf</filename>, the primary configuration file, and <filename>/etc/revisor/conf.d/</filename>, the configuration directory, are valid (the symlink causes the actual file and directory to be found in <filename><replaceable>$PWD</replaceable>/conf/</filename>) - </para> - </listitem> - <listitem> - <para> - Create the <filename>/usr/share/revisor/</filename> directory so that a couple of symlinks can be created from within that directory: - </para> - </listitem> - <listitem> - <para> - In Revisor 2.1.0 (development version in branch master), this includes: - </para> - <para> - <itemizedlist> - <listitem> - <para> - <filename>/usr/share/revisor/ui => <replaceable>$PWD</replaceable>/revisor/modgui/glade/</filename> - </para> - </listitem> - <listitem> - <para> - <filename>/usr/share/revisor/pixmaps => <replaceable>$PWD</replaceable>/revisor/modgui/glade/pixmaps/</filename> - </para> - </listitem> - <listitem> - <para> - <filename>/usr/share/revisor/comps => <replaceable>$PWD</replaceable>/conf/</filename> - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - <listitem> - <para> - In Revisor 2.0.5 (branch F-7, F-8 or EL-5), this includes: - </para> - <para> - <itemizedlist> - <listitem> - <para> - <filename>/usr/share/revisor/ui => <replaceable>$PWD</replaceable>/glade/</filename> - </para> - </listitem> - <listitem> - <para> - <filename>/usr/share/revisor/pixmaps => <replaceable>$PWD</replaceable>/glade/pixmaps/</filename> - </para> - </listitem> - <listitem> - <para> - <filename>/usr/share/revisor/comps => <replaceable>$PWD</replaceable>/conf/</filename> - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - <listitem> - <para> - In Revisor 2.1.0, also create symlinks from within the appropriate <filename>/usr/share/man/man<replaceable>$x</replaceable>/</filename> directories to the source for these man pages in <filename><replaceable>$PWD</replaceable>/doc/</filename>. - </para> - </listitem> - </itemizedlist> - </para> - <para> - From this moment on, you should be able to run: - </para> - <para> - <screen>$ <userinput>./revisor.py</userinput></screen> - </para> - <note> - <title>Root privileges required</title> - <para> - Note that revisor needs root privileges to run, and that you'll need to sudo or su-c to gain those. Use here whatever you find the most convenient; Revisor though should have a nice error message when run without those privileges. - </para> - </note> - - <section id="Revisor_Reference_Manual-Development-Running_Revisor_from_Source-Required_Packages"> - <title>Installing the Required Packages</title> - <para> - To be able to run Revisor from within the source tree, you'll need to install the required packages for each component, of course. - </para> - <para> - To get a current list of those packages, use: - </para> - <para> - <screen>$ <userinput>rpmquery --specfile --qf="%{REQUIRES}\n" revisor.spec | sort | uniq | xargs -n 1 repoquery --requires --alldeps --resolve</userinput></screen> - </para> - </section> - - </section> - - <section id="Revisor_Reference_Manual-Development-Building_Revisor_Packages"> - <title>Building Revisor Packages</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Development-Tickets"> - <title>Tickets</title> - <para> - bugzilla, trac - </para> - </section> - - <section id="Revisor_Reference_Manual-Development-Adding_A_New_Spin"> - <title>Adding a new spin or remix</title> - <para> - <orderedlist> - <listitem> - <para> - Add the appropriate models in the appropriate configuration file for Revisor. - </para> - </listitem> - <listitem> - <para> - Add the appropriate configuration file to the appropriate automake Makefile - </para> - </listitem> - <listitem> - <para> - Run autoreconf && ./configure && make rpm to verify the rpm building - </para> - </listitem> - <listitem> - <para> - Create the model's YUM configuration files with the following repositories: - </para> - <para> - <itemizedlist> - <listitem> - <para> - fedora, enabled, pointing to Everything - </para> - </listitem> - <listitem> - <para> - fedora-source, disabled, pointing to Everything - </para> - </listitem> - <listitem> - <para> - fedora-updates, enabled, pointing to the updates repository - </para> - </listitem> - <listitem> - <para> - fedora-updates-source, disabled, pointing to the updates repository - </para> - </listitem> - <listitem> - <para> - anaconda-updates, enabled, pointing to the anaconda updates repository - </para> - </listitem> - <listitem> - <para> - anaconda-updates-source, disabled, pointing to the ananconda updates repository - </para> - </listitem> - </itemizedlist> - </para> - </listitem> - </orderedlist> - </para> - </section> - - <section id="Revisor_Reference_Manual-Development-Versioning_Schema"> - <title>Versioning Schema</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Development-Release_Procedure"> - <title>Release Procedure</title> - <para> - para - </para> - </section> - -</chapter> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Features.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Features.xml deleted file mode 100644 index 6321641..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Features.xml +++ /dev/null @@ -1,175 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Features"> - <title>Features</title> - <para> - Revisor allows you to build and customize your own Remix, Re-Spin, Spin or even your own distribution, based on Fedora and derivative distributions such as Red Hat Enterprise Linux and CentOS. - </para> - <para> - Revisor builds installation media, live media, installation trees, cobbler distro's and profiles, virtualization images and more. - </para> - - <section id="Revisor_Reference_Manual-Features-Installation_Media"> - <title>Installation Media</title> - <para> - Installation media is what you use to install a system with. The installation media composed will allow you to go through the installation process, answering a number of questions (either manually or through kickstart), and ends up in a system running the distribution you install. - </para> - <para> - Composing installation media using the Revisor GUI allows you to choose the media (CD, or DVD), the packages to be included on the media (also called <emphasis>RPM payload</emphasis>). - </para> - <para> - Using the command-line interface, Revisor also allows you to choose DVD Duallayer and single- or dual-layer Bluray. - </para> - </section> - - <section id="Revisor_Reference_Manual-Features-Installation_Trees"> - <title>Installation Trees</title> - <para> - Installation trees are typically used in environments where a distribution needs to be deployed over multiple systems, or is very volatile. Installation trees are often made accessible through HTTP or FTP protocols, in one place, and do not have as much overhead (in creating .iso files, and burning those to optical media to distribute them). - </para> - </section> - - <section id="Revisor_Reference_Manual-Features-Live_Media"> - <title>Live Media</title> - <para> - Live media often is a perfect showcase for an Operating system, Desktop Environment or any other thing you want to show. Also, since Live media is read-only, live media perfectly allows for a kiosk system, a system that may change while it's running, but restores all original settings when rebooted. - </para> - <para> - Live media is also installable. You start out with a system and boot it from live media, then choose to install the live media. This however is inferior to real installation media, but is convenient if you happen to like what you see when running from live media. - </para> - </section> - - <section id="Revisor_Reference_Manual-Features-Reproducibility"> - <title>Reproducibility</title> - <para> - Media composed with Revisor is extremely reproducible. Using <literal>kickstart_exact_nevra</literal>, you can even select specific versions of packages to be included on the product. - </para> - </section> - - <section id="Revisor_Reference_Manual-Features-Consistency"> - <title>Consistency</title> - <para> - When composing different types of media, such as CDs and DVDs, Revisor composes these discs in one run, making the different media completely consistent. <application>pungi</application> would require you to run twice, once for CDs, and once for DVDs. This is because <application>pungi</application> uses the <literal>part / <replaceable><size></replaceable></literal> kickstart configuration directive to set the maximum size of the media, and has no option to override the size on the command-line, nor to compose a certain set of media (it all depends on the size). - </para> - </section> - - <section id="Revisor_Reference_Manual-Features-Flexibility"> - <title>Flexibility</title> - <para> - Over the years, Revisor has been adopted to serve a large number of use-cases, where use-cases stretch from media being composed as efficient as possible, as robust as possible, specific deployment needs and expectations, and to match the Fedora Project Release Engineering tools' behaviour. All this allows you to configure a lot, and thus customize a lot, making Revisor more of a flexible framework. - </para> - </section> - - <section id="Revisor_Reference_Manual-Features-Graphical_User_Interface"> - <title>Graphical User Interface</title> - <para> - Revisor has a Graphical User Interface or GUI, in addition to the Command Line Interface or CLI, which makes Revisor more accessible to users then the other tools, which are CLI only. Most people only know of Revisor through the GUI, and may think there is no CLI to Revisor. Only when it comes down to many of the additional features that Revisor has, and that do not fit in a simplified GUI, one gets down with it using the CLI. - </para> - </section> - - <section id="Revisor_Reference_Manual-Features-Open_Development_Community"> - <title>Open Development Community</title> - <para> - Revisor has one of those old-fashioned Free and Open Source Software development communities, allowing anyone to make a contribution to Revisor. In fact, Revisor has not bounced a single patch since the project started. Therefor, it improves faster then any of the other compose tools, and is better adaptible to your needs and expectations, because unlike the other utilities, Revisor is not limited to use-cases that apply to Fedora Project Release Engineering. - </para> - </section> - - <section id="Revisor_Reference_Manual-Features-Plugin_System"> - <title>Plugin System</title> - <para> - Revisor has a plugin system so that you can easily extend Revisor. This plugin system gives you full control over the Revisor procedures, and hands you off anything Revisor knows about the compose process. There's are multiple plugins available from upstream as well. To give you an example, the ability to replace <filename>isolinux.cfg</filename> after the compose is done, is a plugin. See <xref linkend="Revisor_Reference_Manual-Plugins" /> for more information. - </para> - - <para> - Current plugins included with Revisor include: - </para> - <para> - <itemizedlist> - <listitem> - <para> - <xref linkend="Revisor_Reference_Manual-Plugins-Upstream-Cobbler_Plugin" /> - </para> - </listitem> - <listitem> - <para> - <xref linkend="Revisor_Reference_Manual-Plugins-Upstream-Isolinux_Plugin" /> - </para> - </listitem> - <listitem> - <para> - <xref linkend="Revisor_Reference_Manual-Plugins-Upstream-Rebrand_Plugin" /> - </para> - </listitem> - <listitem> - <para> - <xref linkend="Revisor_Reference_Manual-Plugins-Upstream-Reuse_Installer_Images_Plugin" /> - </para> - </listitem> - </itemizedlist> - </para> - </section> - - <section id="Revisor_Reference_Manual-Features-Extraneous_Debugging"> - <title>Extraneous Debugging</title> - <para> - Revisor has extraneous debugging, which enables you, as well as the supporters and Revisor's developers, to trace down what happens exactly, and where anything might go wrong. - </para> - </section> - - <section id="Revisor_Reference_Manual-Features-Using_YUM_Configuration_Files"> - <title>Using YUM Configuration Files</title> - <para> - Revisor uses YUM configuration files, where everyone else is not. With using YUM configuration files however, the control you have is nearly limitless. With all the features in YUM already, using it's configuration file format and letting YUM itself work with those allows Revisor to do a lot of cool things without doing anything itself: - </para> - <para> - <orderedlist> - <listitem> - <formalpara> - <title>Excluding packages from repositories</title> - <para> - Excluding packages from repositories means a great deal. Not having them exist in the <xref linkend="Revisor_Reference_Manual-Appendix-Terminology-Package_Sack" /> ensures the package will not end up in the product. This may be what you want for maybe just a few, or maybe an awful lot of packages. - </para> - </formalpara> - <para> - Using the alternative configuration file format, kickstart, in use by every other compose tool, and the <literal>repo</literal> configuration directive that is available with kickstart, you can exclude packages using the <literal>--exclude=</literal> parameter to the <literal>repo</literal> configuration directive. However, that parameter does not allow wildcard matches. - </para> - </listitem> - <listitem> - <formalpara> - <title>Including only a certain (set of) package(s)</title> - <para> - Including only a certain package, or certain set of packages is valuable when a lot of packages exist in the repository configured, but you only need one or two. - </para> - </formalpara> - </listitem> - <listitem> - <formalpara> - <title>Concurrent use of baseurl(s) and the mirrorlist</title> - <para> - Like during normal YUM operations, the baseurl(s) and the mirrorlist configured for a repository are used concurrently. This is not possible with the kickstart configuration directive <literal>repo</literal>, which takes either <literal>--baseurl</literal> or <literal>--mirrorlist</literal>, but not both. - </para> - </formalpara> - </listitem> - <listitem> - <formalpara> - <title>Repository priorities</title> - <para> - Settings available with YUM are available within Revisor as well, like repository priorities. Using repository priorities, you can have YUM decide to pull a package from the repository with a higher priority (a lower priority number) rather then a repository with a lower priority. - </para> - </formalpara> - </listitem> - <listitem> - <formalpara> - <title>YUM Plugins</title> - <para> - YUM plugins, such as <application>yum-fastestmirror</application>, <application>yum-fedorakmod</application>, are available, giving you even more control over the behaviour of YUM. - </para> - </formalpara> - </listitem> - </orderedlist> - </para> - </section> -</chapter> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Frequently_Asked_Questions.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Frequently_Asked_Questions.xml deleted file mode 100644 index 7e97e0e..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Frequently_Asked_Questions.xml +++ /dev/null @@ -1,54 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Frequently_Asked_Questions"> - <title>Frequently Asked Questions</title> - <para> - para - </para> - - <formalpara id="Revisor_Reference_Manual-Frequently_Asked_Questions-How_Does_Revisor_Handle_Comps"> - <title>How Does Revisor Handle Comps?</title> - <para> - para - </para> - </formalpara> - - <formalpara id="Revisor_Reference_Manual-Frequently_Asked_Questions-What_Are_Installer_Images"> - <title>What Are Installer Images?</title> - <para> - para - </para> - </formalpara> - - <formalpara id="Revisor_Reference_Manual-Frequently_Asked_Questions-Relationship_Between_Revisor_and_Pungi"> - <title>What is the relationship between Revisor and Pungi?</title> - <para> - Where pungi builds a bunch of RPMs into ISO images and installation trees through one single procedure, perfect for Release Engineering on something like the Fedora Project, Revisor does it different entirely. - </para> - </formalpara> - - <formalpara id="Revisor_Reference_Manual-Frequently_Asked_Questions-Relationship_Between_Revisor_and_Livecd-tools"> - <title>What is the relationship between Revisor and livecd-tools?</title> - <para> - Revisor depends on livecd-tools for the composing of live media. Creating the filesystem to install the packages to, turning that image file into a SquashFS file, and applying the settings inside the chroot. - </para> - </formalpara> - - <formalpara id="Revisor_Reference_Manual-Frequently_Asked_Questions-Why_Rebuild_Installer_Images"> - <title>Why Rebuild Installer Images?</title> - <para> - para - </para> - </formalpara> - - <formalpara id="Revisor_Reference_Manual-Frequently_Asked_Questions-How_do_I_create_an_updates.img"> - <title>How do I create an updates.img?</title> - <para> - para - </para> - </formalpara> - -</chapter> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Installation.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Installation.xml deleted file mode 100644 index f56855f..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Installation.xml +++ /dev/null @@ -1,104 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Installation"> - <title>Installation</title> - <para> - This chapter contains the installation instructions for Revisor. - </para> - - <section id="Revisor_Reference_Manual-Installation-Packages"> - <title>Packages</title> - <para> - You can install Revisor using RPM packages from the repositories already configured on your system. - </para> - - <formalpara id="Revisor_Reference_Manual-Installation-Packages-revisor"> - <title><application>revisor</application></title> - <para> - Shorthand package for the Revisor GUI. - </para> - </formalpara> - - <formalpara id="Revisor_Reference_Manual-Installation-Packages-revisor-cli"> - <title><application>revisor-cli</application></title> - <para> - The CLI version of Revisor. This package is always installed, as it contains the Python code for Revisor's core. Installing just this package will give you the command-line version of Revisor, and prevents the graphical dependencies from the <xref linkend="Revisor_Reference_Manual-Installation-Packages-revisor-gui" /> package to be installed as well. - </para> - </formalpara> - - <formalpara id="Revisor_Reference_Manual-Installation-Packages-revisor-gui"> - <title><application>revisor-gui</application></title> - <para> - The GUI version of Revisor. This is the actual package containing the Graphical User Interface, as opposed to <xref linkend="Revisor_Reference_Manual-Installation-Packages-revisor" />. Depends on <xref linkend="Revisor_Reference_Manual-Installation-Packages-revisor-cli" />, and thus also installs the command-line version of Revisor. - </para> - </formalpara> - - <section id="Revisor_Reference_Manual-Installation-Packages-YUM-RHEL"> - <title>Red Hat Enterprise Linux 5 or higher</title> - <para> - On Red Hat Enterprise Linux 5 or higher, and derivatives, install the Extra Packages for Enterprise Linux (EPEL) repository. - </para> - <para> - Then, give the following command: - </para> - <para> - <screen># <userinput>yum install revisor</userinput></screen> - </para> - </section> - - <section id="Revisor_Reference_Manual-Installation-Packages-YUM-Fedora"> - <title>Fedora 7 or higher</title> - <para> - On Fedora 7 or higher, and derivatives, no additional repository configuration is required. - </para> - <para> - Give the following command: - </para> - <para> - <screen># <userinput>yum install revisor</userinput></screen> - </para> - <note> - <title>About EOL Releases</title> - <para> - Please bear in mind that Fedora releases that are past the point of End-Of-Life, approximatly 13 months after the initial release, are not supported anymore for use with Revisor. Also, the version of Revisor running on these EOL versions of Fedora are not supported anymore. - </para> - </note> - </section> - - </section> - - <section id="Revisor_Reference_Manual-Installation-The_Latest_And_Greatest"> - <title>The Latest and Greatest</title> - <para> - The latest and greatest is available from GIT, at <ulink url="git://git.fedorahosted.org/revisor" />. To clone this repository, use: - </para> - <para> - <screen>$ <userinput>git clone git://git.fedorahosted.org/revisor/</userinput></screen> - </para> - <para> - Using the GIT clone, you have the several options to start using the latest and greatest: - </para> - <formalpara> - <title>Running directly from the source</title> - <para> - You can run directly from within the source tree. See <xref linkend="Revisor_Reference_Manual-Development-Running_Revisor_from_Source" /> for more information on how to do so. - </para> - </formalpara> - <warning> - <title>Installed packages and running from source</title> - <para> - Do not run Revisor from source while RPM packages have been installed. Files managed by a package will get created, moved and removed when using Revisor's source tree, and updates to the installed RPM packages will destroy these changes. - </para> - </warning> - <formalpara> - <title>Building your own packages</title> - <para> - You can create your own packages, so that you have all the benefits of RPM. See <xref linkend="Revisor_Reference_Manual-Development-Building_Revisor_Packages" /> for more information on how to do so. - </para> - </formalpara> - </section> - -</chapter> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Introduction.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Introduction.xml deleted file mode 100644 index a1b4e52..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Introduction.xml +++ /dev/null @@ -1,77 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Introduction"> - <title>Introduction</title> - <para> - Revisor is a community product by Fedora Unity. Amongst other features, it allows the creation of installation media and live media in the easiest possible manner, through a click-and-go GUI. This chapter gives some insight on how and why Revisor was born, and how the product evolved since. - </para> - - <section id="Revisor_Reference_Manual-Introduction-History_Of_Revisor"> - <title>History of Revisor</title> - <para> - Revisor development started in December 2006, during the Fedora 7 development cycle, in which -as you might recall- the Fedora Core repository, maintained by Red Hat, and Fedora Extras repository, mostly maintained by the community, were merged into one large repository being maintained by both community members as well as Red Hat employees -which are mostly community members who just so happen to be hired by Red Hat, so community altogether. Before then Red Hat employees maintained Fedora Core -as the set of packages upstream for Red Hat's Enterprise product- and the community maintained a repository with additional software; Fedora Extras. Red Hat composed the Fedora distribution every once in a while, but the merge introduced the possibility for packages that were in Fedora Extras to be included in the main distribution, and for the community to also (co-)maintain the (former) Fedora Core packages that originally made up the distribution. - </para> - <para> - In addition to this huge merge of packages, Red Hat employees were also able to release the entire build process to the community, meaning that from the moment the source is committed up and until the release is announced, the entire process is open. Not that is was all behind closed doors or proprietary or anything, the community just couldn't really play with it as much. We now have koji (build system), mash (repository compose from build system products), bodhi (updates release system), livecd-tools (compose tool for live media) and pungi (compose tool for installation media). - </para> - <formalpara> - <title>Composing the distribution's media</title> - <para> - Composing media was an obscure process up and until the moment these tools exposed the best way to compose (a set of) installation media. Fedora Unity had been building and releasing so-called Re-Spins1 regularly, but they were built using a not-so-very intelligent bash script. Like hundreds if not thousands of other parties that needed to build their own media one way or the other, the entire process was based on the best educated guess of what should happen. Luckily, in the FOSS world an educated guess is often a very good guess, despite the fact that one keeps learning even years after the original engagement. - </para> - </formalpara> - <para> - When in December 2006 the compose tools hit a stage in which they were released to the public, Fedora Unity was eager to get these tools and study them and use them for composing their Re-Spins. Up and until then, Re-Spins were composed with the aforementioned bash script that didn't do much but trigger the appropriate commands in a sequence; There wasn't any dependency resolving between the packages included nor did we know exactly how a release was supposed to be composed -it was our educated guess of how it could happen. Although it often led to success, we've had many, many failed Re-Spins as well. With a handful of volunteers, you can imagine the amount of frustration that might give. Fedora Unity was eager to improve their Re-Spin process. - </para> - <formalpara> - <title>Fedora Unity's engagement</title> - <para> - So, early February 2007, a number of Fedora Unity members attended “FUDCon 2007” in Boston, and presented a working GUI front-end to both livecd-tools and pungi enabling regular users to also re-compose or re-spin the installation media and live media they had been getting from the Fedora Project. Revisor at this point just made it “as easy as possible”. Besides the possibilities of pungi and livecd-tools themselves, the wizard Revisor had apparently was very, very useful to mere mortals. From that point on, things took off. - </para> - </formalpara> - <para> - Fedora Unity decided Revisor could accomplish more then just being a front-end to existing compose tools and enable someone to tweak a lot of settings as well. In March 2007, Revisor was rebuild from the ground up in March 2007 to allow a more flexible process, more dependent on the configuration directives it was given and less so on the processes of the existing tools. When in San Diego at the Red Hat Summit (early May 2007), Robert 'Bob' Jensen and Jonathan Steffan gave a presentation on “Customizing Fedora”, the responses were amazing. Since then Revisor has evolved from a front-end to existing tools to the complete compose tool it is today, with lots of configuration options for specific use-cases. - </para> - <para> - For users, Revisor is particularly useful because it has a GUI front-end wizard, which, with the defaults settings, will just succeed in getting a user the media he/she wants. If a user decides he needs little adjustment of the media, the GUI allows for selecting the most common options. If a user decides he needs some less common adjustments, the configuration options gives him very granular control -and as long as the documentation on all the options is sufficient, users will be able to make those less common adjustments. - </para> - <para> - For administrators on the other hand, Revisor is the tool that gives so much granular control over what happens, that it can serve almost every specific use-case. In this aspect, Revisor could potentially replace the compose tools administrators have been developing themselves with a consistent and flexible program flow. - </para> - <para> - This document should enable you to study the process of composing installation and live media, and comprehend the logic Revisor adds to that process. - </para> - </section> - - <section id="Revisor_Reference_Manual-Introduction-The_Installation_Media_Challenge"> - <title>The Installation Media Challenge</title> - <para> - When Fedora Unity first started doing these so-called Re-Spins, the challenge ahead could maybe be explained like this: - </para> - <para> - <emphasis>When a user downloads a Fedora release and installs the distribution, the user will need to download and install a number of updates. The “older” the release becomes, the more updates will be available, and the greater the total download size of these updates the user will need to download on top of the download size of the original release media.</emphasis> - </para> - <para> - “older” is in quotes on purpose, because really for an operating system -or “distribution” if you will- being released every 6 months, “old” is quite a relative concept. The number of updates available however, at any given time during the release cycle, may range from 0 right after the release (which has never happened before), to the total amount of packages installed on the user's system (often over 2000). You can imagine the size of these updates ranging from 0 MB to an astonishing 2GB(!), only 6 months after the initial release. - </para> - <para> - Some of us do not have the bandwidth capacity or enough data transfer quota to download this many extra, rather useless bits. In addition, some of us do not have an Internet connection at all, and thus benefit getting the updates from Re-Spins directly. - </para> - <para> - The use of updates in Re-Spins has several more beneficial side-effects, which we'll explain in more detail later on in this document. Long story short; If for some reason the software used to compose the media (the release) with does not work for your hardware or your specific needs, updated software incorporated in the composed installer images might resolve that problem. - </para> - <para> - This is the original challenge the Fedora Unity team resolved a long time ago, and is at the base of what Revisor does nowadays. - </para> - </section> - - <section id="Revisor_Reference_Manual-Introduction-The_Live_Media_Challenge"> - <title>The Live Media Challenge</title> - <para> - Back in the day Fedora Core 5 was the most recent release, Fedora Unity created so-called live media using Kadischi. In that time, live media could only have a read-only root file system and was not as feature-rich as live media is today. However, just before Revisor came to life, two applications were developed; pungi for creating installation media, and livecd-tools for creating live media. These two applications did their work well; The media composed for a release, including many different custom live media spins were, and still are, created with these tools. Immediately, the Revisor developers set themselves a target to provide a single interface to both of those tools. - </para> - </section> - -</chapter> diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Plugins.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Plugins.xml deleted file mode 100644 index 122f25e..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Plugins.xml +++ /dev/null @@ -1,131 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Plugins"> - <title>Plugins</title> - <para> - para - </para> - - <section id="Revisor_Reference_Manual-Plugins-Upstream"> - <title>Upstream Plugins</title> - <para> - Plugins available from upstream, maintained by upstream - </para> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-Cobbler_Plugin"> - <title>Cobbler Plugin</title> - <para> - The Cobbler plugin is able to put the product composed into a Cobbler environment, by handing off the built product to the existing Cobbler infrastructure as a <emphasis>distro</emphasis>, and creating a <emphasis>profile</emphasis>. - </para> - <para> - Using this module, one can automatically import the Revisor product into a Cobbler environment, and immediately use the new Cobbler <emphasis>profile</emphasis> to start deploying or automated testing, maybe. - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-Composer_Plugin"> - <title>Composer Plugin</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-Delta_Plugin"> - <title>Delta Plugin</title> - <para> - A small change to a ISO image does not require you to download the complete ISO image if you have a copy of the old ISO image. - </para> - <note> - <title>Only applicable to (...)</title> - <para> - The generation of Delta ISO images is only applicable to situations in which the ISO image does not contain SquashFS images. SquashFS images are smaller, but all SquashFS images are unique. Since the Delta principle is based on similarities, and no two SquashFS images are alike, creating a Delta on two ISO images containing SquashFS images will lead to a Delta pratically the same size as the SquashFS image. For Live Media that compresses the ext3 filesystem image into a SquashFS image, since that SquashFS image is probably over 97% of the size of the ISO image, creating Delta images for compressed Live Media does not make sense. For installation media however, most RPMs would be similar as well as (potentially) the installer images. - </para> - </note> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-GUI_Plugin"> - <title>GUI (Graphical User Interface) Plugin</title> - <para> - Yes, the Graphical User Interface for Revisor is actually a plugin. - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-HUB_Plugin"> - <title>HUB Plugin</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-Isolinux_Plugin"> - <title>Isolinux Plugin</title> - <titleabbrev id="Isolinux_Plugin">Isolinux Plugin</titleabbrev> - <para> - The isolinux plugin adds the <literal>--isolinux-cfg</literal> command-line option to Revisor. Specify a file here, and the original <filename>isolinux.cfg</filename> that is built as part of the compose process is replaced by the <filename>isolinux.cfg</filename> specified. - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-Jigdo_Plugin"> - <title>Jigdo Plugin</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-Mock_Plugin"> - <title>Mock Plugin</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-Rebrand_Plugin"> - <title>Rebrand Plugin</title> - <para> - The rebrand plugin hooks in to Revisor at several different stages. The goal of this plugin is to ensure no trademarked packages end up on the media. Trademarked packages may include <application>fedora-logos</application>, <application>redhat-logos</application>, and so forth. - </para> - <para> - The plugin adds a <literal>--rebrand</literal> option, to which you can specify the name of your new product. When rebranding Fedora to Omega for example, specifying <literal>--rebrand Omega</literal> would be sufficient to make sure the product does not have any Fedora trademarks. - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-Reuse_Installer_Images_Plugin"> - <title>Reuse Installer Images Plugin</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-Server_Plugin"> - <title>Server Plugin</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-Virtualization_Plugin"> - <title>Virtualization Plugin</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Plugins-Upstream-WUI_Plugin"> - <title>WUI (Web-based User Interface) Plugin</title> - <para> - para - </para> - </section> - - </section> - - <section id="Revisor_Reference_Manual-Plugins-Writing_Your_Own"> - <title>Writing Your Own Plugins</title> - <para> - para - </para> - </section> - -</chapter> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Testing.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Testing.xml deleted file mode 100644 index ea4ff00..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Testing.xml +++ /dev/null @@ -1,173 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Testing"> - <title>Testing</title> - <para> - The following test cases describe different types of testing a new Revisor release. - </para> - - <section id="Revisor_Reference_Manual-Testing-Simple_Test_Cases"> - <title>Simple Test Cases</title> - <para> - This section has a few simple test cases ensuring configuration shipped with Revisor works as anticipated. - </para> - - <section id="Revisor_Reference_Manual-Testing-Simple_Test_cases-Packages"> - <title>Packages</title> - <para> - Install the <application>revisor-cli</application>: - </para> - <para> - <screen># <userinput>yum --enablerepo=updates-testing install revisor</userinput></screen> - </para> - <para> - Installed are all dependencies for the Revisor CLI interface. Make sure <application>spin-kickstarts</application> is installed, a package for sample kickstarts. - </para> - <para> - Starting Revisor as follows should not show any error messages related to Revisor attempting to start up it's GUI interface: - </para> - <para> - <screen># <userinput>revisor</userinput></screen> - </para> - - <formalpara> - <title>Configuration Files</title> - <para> - The following configuration files should exist: - </para> - </formalpara> - <para> - <itemizedlist> - <listitem> - <para> - <filename>/etc/revisor/revisor.conf</filename> - </para> - </listitem> - </itemizedlist> - </para> - <para> - Each section should have a configuration file listed as <literal>main</literal>. - </para> - <para> - And, of course, every configuration file listed in each section. In this case, the following snippet is easy enough: - </para> - <para> - <screen>$ <userinput>i=0; \ -configfiles="`grep ^main /etc/revisor/revisor.conf | \ - sed -r -e 's/^main.*=\s*(.*)/\1/g'`" - -for configfile in $configfiles; do \ - [ ! -f $file ] && i=1; \ -done; \ -echo $i</userinput></screen> - </para> - <para> - Another way to test the configuration file is to execute: - </para> - <para> - <screen>$ <userinput>revisor --list-models >/dev/null</userinput></screen> - </para> - <para> - If everything is well, since <literal>STDOUT</literal> is redirected to <filename>/dev/null</filename>, you should see no messages at all. - </para> - - </section> - - <section id="Revisor_Reference_Manual-Testing-Simple_Test_Cases-Configuration_Files"> - <title>Configuration Files</title> - <para> - The main Revisor configuration file is <filename>/etc/revisor/revisor.conf</filename>. The file lists a series of models, each having their own YUM configuration file in <filename>/etc/revisor/conf.d/</filename>. - </para> - <formalpara> - <title>Testing</title> - <para> - <itemizedlist> - <listitem> - <para> - For each model in <filename>/etc/revisor/revisor.conf</filename>, the <code>main</code> setting for that model should point to a valid file. - </para> - </listitem> - <listitem> - <para> - Each YUM configuration file should work. To verify, run the following command for each configuration file: - </para> - <para> - <screen>$ yum -c <replaceable>$file</replaceable> list kernel</screen> - </para> - </listitem> - </itemizedlist> - </para> - </formalpara> - <formalpara> - <title>Known Errors</title> - <para> - <itemizedlist> - <listitem> - <para> - Revisor has baseurls in YUM repositories set to <ulink url="http://localrepo" />. This URL will not be retrievable for many people, but allows the developers to quickly change mirrors. - </para> - </listitem> - <listitem> - <para> - Repositories that are unavailable at the moment of testing will throw errors Revisor can't do anything about. - </para> - </listitem> - <listitem> - <para> - If the directories <filename>revisor-yumcache/</filename> and <filename>revisor/</filename> in <filename>/var/tmp/</filename>, the default working directory, are not writeable for the user then YUM will throw permission denied errors. - </para> - <para> - Remove <filename>/var/tmp/revisor/</filename> and <filename>/var/tmp/revisor-yumcache/</filename> or run the command with root permissions. - </para> - </listitem> - </itemizedlist> - </para> - </formalpara> - </section> - - <section id="Revisor_Reference_Manual-Testing-Simple_Test_Cases-Compose_Results"> - <title>Requirements for Compose Results</title> - <para> - Although heavily dependent on Anaconda for this part, these are still requirements - </para> - - <formalpara> - <title>ld-linux.so.2</title> - <para> - In the <filename>initrd.img</filename> of the composed product, if 32-bit, <filename>/lib/ld-linux.so.2</filename> (or any other version) should link to <filename>/lib/ld-2.9.so</filename> (or any other version). If <filename>/lib/ld-linux.so.2</filename> links to itself, the media will fail to install. - </para> - </formalpara> - <formalpara> - <title>How to test</title> - <para> - In a terminal, type the following command: - </para> - </formalpara> - <para> - <screen>$ <userinput>lsinitrd /path/to/initrd | grep ld-linux</userinput></screen> - </para> - <para> - See also: <ulink url="https://www.redhat.com/archives/anaconda-devel-list/2009-February/msg00115.…" /> - </para> - - </section> - </section> - - <section id="Revisor_Reference_Manual-Testing-Complex_Test_Cases"> - <title>Complex Test Cases</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Testing-Specific_Test_Cases"> - <title>Specific Test Cases</title> - <para> - para - </para> - </section> - -</chapter> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Tips_and_Tricks.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Tips_and_Tricks.xml deleted file mode 100644 index 8b785ee..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Tips_and_Tricks.xml +++ /dev/null @@ -1,47 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Tips_and_Tricks"> - <title>Tips and Tricks</title> - <para> - para - </para> - - <section id="Revisor_Reference_Manual-Tips_and_Tricks-The_spin-kickstarts_Package"> - <title>The spin-kickstarts Package</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Tips_and_Tricks-Even_More_Debugging"> - <title>Even More Debugging</title> - <para> - something about using -x to buildinstall scripts - </para> - </section> - - <section id="Revisor_Reference_Manual-Tips_and_Tricks-ksvalidator"> - <title>Kickstart Validator</title> - <para> - something about using -x to buildinstall scripts - </para> - </section> - - <section id="Revisor_Reference_Manual-Tips_and_Tricks-Using_Mirrormanager_For_Mirror_Redirection"> - <title>Using Mirrormanager for Mirror Redirection</title> - <para> - Something about using Mirrormanager to redirect you to the local mirror (so you do not have to edit YUM configuration files). - </para> - </section> - - <section id="Revisor_Reference_Manual-Tips_and_Tricks-The_localrepo_DNS_Alias"> - <title>Using The localrepo DNS Alias</title> - <para> - Something about using the localrepo DNS alias to point to your local mirror (either through real DNS or through /etc/hosts), so you do not have to edit the YUM configuration files. - </para> - </section> - -</chapter> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Tweaking_The_Build_Process.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Tweaking_The_Build_Process.xml deleted file mode 100644 index 4979285..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Tweaking_The_Build_Process.xml +++ /dev/null @@ -1,40 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Tweaking_The_Build_Process"> - <title>Tweaking the build process</title> - <para> - para - </para> - - <section id="Revisor_Reference_Manual-Tweaking_The_Build_Process-Reusing_Existing_Installer_Images"> - <title>Reusing Existing Installer Images</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Tweaking_The_Build_Process-Building_The_Installer_Images_In_Mock"> - <title>Building The Installer Images in Mock</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Tweaking_The_Build_Process-Omitting-isomd5sum"> - <title>Omitting isomd5sums</title> - <para> - para - </para> - </section> - - <section id="Revisor_Reference_Manual-Tweaking_The_Build_Process-Omitting-sha1sums"> - <title>Omitting SHA1SUMS</title> - <para> - para - </para> - </section> - -</chapter> - diff --git a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Using_Kickstart.xml b/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Using_Kickstart.xml deleted file mode 100644 index f3e6ab2..0000000 --- a/doc/Reference_Manual/en-US/Revisor_Reference_Manual-Using_Kickstart.xml +++ /dev/null @@ -1,118 +0,0 @@ -<?xml version='1.0'?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ -]> - -<chapter id="Revisor_Reference_Manual-Using_Kickstart"> - <title>Using Kickstart</title> - <para> - Kickstart is a configuration file format for automating installation procedures. Or at least, it was, originally. Nowadays, kickstart files are used as input to the compose tools, including Revisor. - </para> - <para> - Revisor again is unique in that it does not require a kickstart file for input. The other tools only take kickstart configuration files. Revisor though allows most of what is in a kickstart file to be configured interactively in Graphical User Interface mode. - </para> - - <section id="Revisor_Reference_Manual-Using_Kickstart-How_Kickstart_Is_Used"> - <title>How Kickstart Is Used</title> - <para> - There's two cases in which a kickstart file is used differently. One is during the compose of installation media, and the other of course is during the compose of live media, or virtualization media. - </para> - - <section id="Revisor_Reference_Manual-Using_Kickstart-How_Kickstart_Is_Used-Installation_Media"> - <title>Installation Media</title> - <para> - In the case of installation media, the following settings are used: - </para> - <para> - <itemizedlist> - <listitem> - <formalpara> - <title><literal>repo</literal></title> - <para> - The <literal>repo</literal> command in kickstart is used when Revisor is configured to use the repositories configured in the kickstart file only. Use <literal>kickstart_repos = 1</literal> to enable this feature, or set the appropriate checkbox in the Revisor GUI. - </para> - </formalpara> - </listitem> - <listitem> - <formalpara> - <title><literal>%packages</literal></title> - <para> - The <literal>%packages</literal> section in kickstart is used to determine the RPM payload on the installation media. It can include groups and packages, and exclude packages. It accepts wildcards, both in includes and excludes of packages (but not groups). - </para> - </formalpara> - </listitem> - </itemizedlist> - </para> - <note> - <title>@core and @base</title> - <para> - By default, groups @core and @base are included in the package manifest. You can specify @base to not be included, by using <literal>%packages --nobase</literal>, but @core cannot be excluded using a kickstart package manifest. - </para> - </note> - <para> - Using <literal>kickstart_exact</literal>, you can exclude @core and @base so that you need to explicitly select them in the kickstart package manifest. - </para> - <para> - Using <literal>kickstart_exact_nevra</literal> ... - </para> - </section> - </section> - - <section id="Revisor_Reference_Manual-Using_Kickstart-The_Kickstart_Package_Manifest"> - <title>The Kickstart Package Manifest</title> - <para> - para - </para> - - <formalpara> - <title>Group @core</title> - <para> - para - </para> - </formalpara> - - <formalpara> - <title>Group @base</title> - <para> - para - </para> - </formalpara> - - <formalpara> - <title>Including groups of packages</title> - <para> - para - </para> - </formalpara> - - <formalpara> - <title>Including a single package</title> - <para> - para - </para> - </formalpara> - - <formalpara> - <title>Excluding a single package</title> - <para> - para - </para> - </formalpara> - - <formalpara> - <title>Using wildcard matches</title> - <para> - para - </para> - </formalpara> - - <section id="Revisor_Reference_Manual-Using_Kickstart-Using_Kickstart_With_Package_NEVRA"> - <title>Using Kickstart with Package NEVRA</title> - <para> - para - </para> - </section> - - </section> - -</chapter> - diff --git a/doc/Reference_Manual/publican.cfg b/doc/Reference_Manual/publican.cfg new file mode 100644 index 0000000..1cd36ee --- /dev/null +++ b/doc/Reference_Manual/publican.cfg @@ -0,0 +1,7 @@ +# Config::Simple 4.59 +# Fri Dec 25 02:54:02 2009 + +xml_lang: en-US +type: Book +brand: common + commit d4dbfc2b3b694b3da1c7216c28d8c763172c46cc Author: Jeroen van Meeuwen (Fedora Unity) <kanarip(a)fedoraunity.org> Date: Fri Dec 25 02:28:56 2009 +0100 Permanently disable the SELinux == enforcing check, but also leave the SELinux is disabled check / warning enabled. diff --git a/revisor/misc.py b/revisor/misc.py index 5e2d706..7298df7 100644 --- a/revisor/misc.py +++ b/revisor/misc.py @@ -44,19 +44,8 @@ def check_uid(): def check_selinux(log=None): """Check if the composing host has SELinux in enforcing (which will cause the build to fail)""" - return - - if os.path.exists("/selinux/enforce"): - f = open("/selinux/enforce") - buf = f.read().strip() - f.close() - if buf == "1": - # SELinux in enforcing mode - log.error(_("SELinux is in enforcing mode on this host. Composing media will fail. Please set SELinux to permissive mode."), recoverable=False) - else: - # SELinux in permissive mode - pass - else: + + if not os.path.exists("/selinux/enforce"): log.warning(_("SELinux on this host is disabled. Composed media will not have SELinux, and as a result the system you install from the composed media will not have SELinux either.")) def get_file(url, working_directory="/var/tmp"): commit ae6b251169946f7ea066d32e0ffeb8355d050469 Author: Jeroen van Meeuwen (Fedora Unity) <kanarip(a)fedoraunity.org> Date: Sun Dec 13 16:18:18 2009 +0100 I always seem to forget whether it was --cleanup or --clean-up... Problem solved! diff --git a/revisor/__init__.py.in b/revisor/__init__.py.in index 5b46f0c..e225a80 100644 --- a/revisor/__init__.py.in +++ b/revisor/__init__.py.in @@ -132,7 +132,7 @@ class Revisor: default = False, help = _("Tells Revisor to ignore @core and @base (or %packages --nobase) and only add what is in the package manifest")) - runtime_group.add_option( "--clean-up", + runtime_group.add_option( "--clean-up", "--cleanup", dest = "clean_up", action = "store", type = 'int',

1 0

2 commits - revisor/modgui revisor/progress.py
by Jeroen van Meeuwen 05 Dec '09

05 Dec '09

revisor/modgui/__init__.py | 3 ++- revisor/progress.py | 5 +++++ 2 files changed, 7 insertions(+), 1 deletion(-) New commits: commit 4f6d1b47f3d89796625e0d692343d067162bff9d Author: Jeroen van Meeuwen (Fedora Unity) <kanarip(a)fedoraunity.org> Date: Sat Dec 5 14:32:15 2009 -0500 Prevent division by zero diff --git a/revisor/progress.py b/revisor/progress.py index da57893..78e81ad 100644 --- a/revisor/progress.py +++ b/revisor/progress.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- # # Copyright 2007-2009 Fedora Unity Project (http://fedoraunity.org) # @@ -465,6 +466,10 @@ class dlcb(urlgrabber.progress.BaseMeter): def _do_update(self, amount_read, now=None): if self.size is None: return + + if self.size == 0: + return + pct = float(amount_read) / self.size curval = self.pbar.get_fraction() newval = (pct * 1/self.total) + (self.current / self.total) commit e79026ce02b6e225bc7986cfa76a6af7a1532bbb Author: Jeroen van Meeuwen (Fedora Unity) <kanarip(a)fedoraunity.org> Date: Sat Dec 5 14:31:45 2009 -0500 Force "user" to be a string (#532908) diff --git a/revisor/modgui/__init__.py b/revisor/modgui/__init__.py index 2e1c1fb..9d08d9e 100644 --- a/revisor/modgui/__init__.py +++ b/revisor/modgui/__init__.py @@ -1,3 +1,4 @@ +# -*- coding: utf-8 -*- # # Copyright 2007-2009 Fedora Unity Project (http://fedoraunity.org) # @@ -188,7 +189,7 @@ class RevisorGui: pid = os.fork() if not pid: self.log.info(_("Opening up /usr/bin/sudo -u %s /usr/bin/xdg-open %s") % (user,url)) - os.execv("/usr/bin/sudo", ["/usr/bin/sudo", "-u", user, "/usr/bin/xdg-open", "%s" % (url)]) + os.execv("/usr/bin/sudo", ["/usr/bin/sudo", "-u", "%s" % user, "/usr/bin/xdg-open", "%s" % (url)]) def on_button_revisor_link_clicked(self, *args): self.open_url(REVISOR_HOMEPAGE)

1 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

revisor-devel December 2009