Added kickstart-anatomy.adoc

modules/ROOT/pages/installation/kickstart-anatomy.adoc

@@ -0,0 +1,84 @@
+= The anatomy of Fedora Server kickstart files
+Peter Boy
+:page-authors: {author}
+:revnumber: F36-F37
+:revdate: n/a
+
+
+[abstract]
+We provide basic information aboutcfreating and using Kickstart files in Fedora Server. It includes dedicated links for detailed information about various specific topics. 
+
+
+
+[IMPORTANT]
+====
+**Status:** work in progress! Text is still raw and basically unedited yet.
+====
+
+
+
+== Creating a Kickstart File
+
+The Kickstart file itself is a plain text file, containing keywords listed 
+//xref:appendixes/Kickstart_Syntax_Reference.adoc#appe-kickstart-syntax-reference
+[Kickstart Syntax Reference],
+the Kickstart Appendix of Anaconda reference guide, which serve as directions for the installation. Any text editor able to save files as ASCII text (such as [application]*Gedit* or [application]*vim* on Linux systems or [application]*Notepad* on Windows systems) can be used to create and edit Kickstart files.
+
+The recommended approach to creating Kickstart files is to perform a manual installation on one system first. After the installation completes, all choices made during the installation are saved into a file named `anaconda-ks.cfg`, located in the `/root/` directory on the installed system. You can then copy this file, make any changes you need, and use the resulting configuration file in further installations.
+
+When creating a Kickstart file, keep in mind the following:
+
+* Lines starting with a pound sign (`#`) are treated as comments and are ignored.
+
+* Sections must be specified *in order*. Items within the sections do not have to be in a specific order unless otherwise specified. The correct section order is:
++
+** The command section which contains actual Kickstart commands and options as listed in the refernce guide.
+
+// xref:appendixes/Kickstart_Syntax_Reference.adoc#appe-kickstart-syntax-reference[Kickstart Syntax Reference]. 
+Note that some commands, such as [command]#install#, are mandatory, but most commands are optional.
++
+** The [command]#%packages# section which contains a list of packages and package groups to be installed. See Reference Guide for details.
+
+// xref:appendixes/Kickstart_Syntax_Reference.adoc#sect-kickstart-packages[%packages (required) - Package Selection] 
+
++
+** The [command]#%pre# and [command]#%post# sections, containing a pre-installation and post-installation scripts. These two sections can be in any order and are not mandatory. See
+//xref:appendixes/Kickstart_Syntax_Reference.adoc#sect-kickstart-preinstall[%pre (optional) - Pre-installation Script] and
+//xref:appendixes/Kickstart_Syntax_Reference.adoc#sect-kickstart-postinstall[%post (optional) - Post-installation Script]
+Refernce Guide for details.
++
+[IMPORTANT]
+====
+The [command]#%packages#, [command]#%pre# and [command]#%post# sections must end with [command]#%end#, otherwise the installation program will refuse the Kickstart file. The main command section has no special ending statement.
+
+====
+
+* Omitting any required item results in the installation program prompting the user for an answer to the related item, just as the user would be prompted during a typical installation. Once the answer is given, the installation will continue. Note that if the system you are installing has no display, you will not be able to see the prompt, and the installation will appear to have failed.
+
+
+=== Verifying the Kickstart File
+
+When creating or customizing your kickstart file, it is useful to verify that it is valid before attempting to use it in an installation. Fedora includes the [application]*ksvalidator* command line utility which can be used to do this. This tool is a part of the [package]*pykickstart* package. To install this package, execute the following command:
+
+[subs="macros"]
+----
+# dnf install pykickstart
+----
+
+After installing the package, you can validate a Kickstart file using the following command:
+
+[subs="quotes, macros"]
+----
+$ [command]#ksvalidator _/path/to/kickstart.ks_#
+----
+
+Replace _/path/to/kickstart.ks_ with the path to the Kickstart file you want to verify.
+
+For more information about this tool, see the `ksvalidator(1)` man page.
+
+[IMPORTANT]
+====
+
+Keep in mind that the validation tool has its limitations. The Kickstart file can be very complicated; [application]*ksvalidator* can make sure the syntax is correct and that the file does not include removed options, but it cannot  guarantee the installation will be successful. It also does not attempt to validate the [command]#%pre#, [command]#%post# and [command]#%packages# sections of the Kickstart file.
+
+====