diff options
| -rw-r--r-- | MANIFEST.in | 1 | ||||
| -rw-r--r-- | cobbler.spec | 2 | ||||
| -rw-r--r-- | config/cobbler_hosts | 0 | ||||
| -rw-r--r-- | setup.py | 1 | ||||
| -rw-r--r-- | website/new/docs/cobbler.html | 359 | ||||
| -rw-r--r-- | website/new/docs/koan.html | 188 | ||||
| -rw-r--r-- | website/new/documentation.html | 4 |
7 files changed, 446 insertions, 109 deletions
diff --git a/MANIFEST.in b/MANIFEST.in index a4662aa..c2b4c87 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -5,6 +5,7 @@ include config/cobbler.conf include config/rsync.exclude include config/cobblerd include config/cobblerd_rotate +include config/cobbler_hosts recursive-include templates *.template recursive-include kickstarts *.ks include docs/cobbler.1.gz diff --git a/cobbler.spec b/cobbler.spec index 36aa113..8bd58ed 100644 --- a/cobbler.spec +++ b/cobbler.spec @@ -134,6 +134,8 @@ test "x$RPM_BUILD_ROOT" != "x" && rm -rf $RPM_BUILD_ROOT %config(noreplace) /var/lib/cobbler/snippets/partition_select /var/lib/cobbler/elilo-3.6-ia64.efi /var/lib/cobbler/menu.c32 +%defattr(2755,root,root) +%config(noreplace) /var/lib/cobbler/cobbler_hosts %defattr(-,root,root) %doc AUTHORS CHANGELOG NEWS README COPYING diff --git a/config/cobbler_hosts b/config/cobbler_hosts new file mode 100644 index 0000000..e69de29 --- /dev/null +++ b/config/cobbler_hosts @@ -55,6 +55,7 @@ if __name__ == "__main__": (wwwconf, ['config/cobbler.conf']), (cobpath, ['loaders/elilo-3.6-ia64.efi']), (cobpath, ['loaders/menu.c32']), + (cobpath, ['config/cobbler_hosts']), (etcpath, ['kickstarts/kickstart_fc5.ks']), (etcpath, ['kickstarts/kickstart_fc6.ks']), (etcpath, ['kickstarts/kickstart_fc6_domU.ks']), diff --git a/website/new/docs/cobbler.html b/website/new/docs/cobbler.html index dd87345..76ccbcf 100644 --- a/website/new/docs/cobbler.html +++ b/website/new/docs/cobbler.html @@ -1,3 +1,13 @@ +<?xml version="1.0" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>NAME</title> +<meta http-equiv="content-type" content="text/html; charset=utf-8" /> +<link rev="made" href="mailto:root@localhost" /> +</head> + +<body style="background-color: white"> <p><a name="__index__"></a></p> <!-- INDEX BEGIN --> @@ -18,6 +28,9 @@ <li><a href="#adding_a_repository_to_mirror">ADDING A REPOSITORY TO MIRROR</a></li> <li><a href="#displaying_configuration_entries">DISPLAYING CONFIGURATION ENTRIES</a></li> <li><a href="#deleting_configuration_entries">DELETING CONFIGURATION ENTRIES</a></li> + <li><a href="#editing">EDITING</a></li> + <li><a href="#copying">COPYING</a></li> + <li><a href="#renaming">RENAMING</a></li> <li><a href="#rebuilding_configurations">REBUILDING CONFIGURATIONS</a></li> </ul> @@ -35,18 +48,22 @@ <li><a href="#pxe_menus">PXE MENUS</a></li> <li><a href="#kickstart_templating">KICKSTART TEMPLATING</a></li> + <li><a href="#kickstart_snippets">KICKSTART SNIPPETS</a></li> + <li><a href="#kickstart_validation">KICKSTART VALIDATION</a></li> <li><a href="#dhcp_configuration_management">DHCP CONFIGURATION MANAGEMENT</a></li> <li><a href="#enchant">ENCHANT</a></li> <li><a href="#importing_trees">IMPORTING TREES</a></li> <li><a href="#default_pxe_boot_behavior">DEFAULT PXE BOOT BEHAVIOR</a></li> <li><a href="#repo_management">REPO MANAGEMENT</a></li> + <li><a href="#pxe_boot_loop_prevention">PXE BOOT LOOP PREVENTION</a></li> <li><a href="#kickstart_tracking">KICKSTART TRACKING</a></li> <li><a href="#tweaking">TWEAKING</a></li> + <li><a href="#triggers">TRIGGERS</a></li> <li><a href="#api">API</a></li> </ul> <li><a href="#exit_status">EXIT_STATUS</a></li> - <li><a href="#mailing_list">MAILING LIST</a></li> + <li><a href="#additional_resources">ADDITIONAL RESOURCES</a></li> <li><a href="#author">AUTHOR</a></li> </ul> <!-- INDEX END --> @@ -55,23 +72,22 @@ <p> </p> <h1><a name="name">NAME</a></h1> -<p>cobbler is a command line tool for configuring a provisioning and update server. It supports provisioning via PXE, virtualization (Xen), and remotely re-provisioning a existing Linux system when PXE booting isn't possible. The latter two features are enabled by usage of 'koan' (a client side provisioning application) on the remote system. Update server features include yum mirroring over rsync:// and integration of those mirrors with kickstart.</p> +<p>cobbler is a command line tool for configuring a provisioning and update server. It supports provisioning via PXE (network booting), virtualization (Xen or QEMU/KVM), and re-installs of existing Linux systems. The latter two features are enabled by usage of 'koan' on the remote system. Update server features include yum mirroring and integration of those mirrors with kickstart.</p> <p> </p> <hr /> <h1><a name="synopsis">SYNOPSIS</a></h1> -<p>cobbler command [subcommand] [--arg1=] [--arg2=]</p> +<p>cobbler command [subcommand] [--arg1=value1] [--arg2=value2]</p> <p> </p> <hr /> <h1><a name="description">DESCRIPTION</a></h1> <p>Cobbler manages provisioning using a tiered concept of Distributions, Profiles, Systems, and Repositories.</p> -<p>Distributions contain information about what kernel and initrd are used, along with various other information, such as required kernel parameters.</p> -<p>Profiles associate a Distribution with a kickstart file and optionally customize it further.</p> -<p>Systems associate a hostname, IP, or MAC with a distribution and optionally customize the Profile further.</p> -<p>Repositories contain yum mirror information. Using cobbler to mirror repositories is an optional/advanced -feature and is covered further down in this manpage.</p> -<p>The main advantages of cobbler is that it glues together a lot of disjoint technologies and concepts and abstracts the user from the need to understand them. It allows the systems administrator to concentrate on what he needs to do, and not how it is done.</p> +<p>Distributions contain information about what kernel and initrd are used, plus metadata (required kernel parameters, etc).</p> +<p>Profiles associate a Distribution with a kickstart file and optionally customize the metadata further.</p> +<p>Systems associate a MAC, IP, and/or hostname with a distribution and optionally customize the metadata further.</p> +<p>Repositories contain yum mirror information. Using cobbler to mirror repositories is an optional/advanced</p> +<p>The main advantage of cobbler is that it glues together a lot of disjoint technologies and concepts and abstracts the user from the need to understand them. It allows the systems administrator to concentrate on what he needs to do, and not how it is done.</p> <p> </p> <hr /> @@ -84,18 +100,18 @@ feature and is covered further down in this manpage.</p> <p> </p> <h2><a name="setup">SETUP</a></h2> -<p>Running ``cobbler check'' after installation will verify that cobbler's prerequisites are installed and configured correctly. This is a good first command to run after installing cobbler.</p> +<p>After installing, run ``cobbler check'' to verify that cobbler's ecosystem is configured correctly. This will also create +an initial settings state file that cobbler will ask you to modify using a text editor.</p> <p>Any problems detected should be corrected, with the potential exception of DHCP related warnings. Run ``cobbler sync'' after making any changes to the configuration files to ensure those changes are applied.</p> -<p>It is especially important that the server name field be accurate in /var/lib/cobbler/settings, without this field being correct, kickstart trees may not be found, and provisioning won't work.</p> -<p>For PXE, if DHCP is to be run from the cobbler server, the dhcp configuration file should be changed as suggested. If DHCP is not run locally, the ``next-server'' field on the DHCP server should point to the cobbler server's IP and the filename should be set to ``pxelinux.0''.</p> -<p>Cobbler can also manage (generate) your dhcp configuration file -- this is covered in a later section. If you don't already have a dhcp setup, allowing cobbler to manage it may prove to be useful. If you already have a setup, moving an existing setup to be managed from within cobbler is relatively painless and is entirely optional.</p> +<p>It is especially important that the server name field be accurate in /var/lib/cobbler/settings, without this field being correct, kickstart trees will not be found, and automated installtions will fail.</p> +<p>For PXE, if DHCP is to be run from the cobbler server, the dhcp configuration file should be changed as suggested by ``cobbler check''. If DHCP is not run locally, the ``next-server'' field on the DHCP server should point to the cobbler server's IP and the filename should be set to ``pxelinux.0''. Alternatively, cobbler can also generate your dhcp configuration file if you want to run dhcp locally -- this is covered in a later section. If you don't already have a dhcp setup, allowing cobbler to manage it may prove to be useful. If you already have a setup, moving an existing setup to be managed from within cobbler is relatively painless and is entirely optional. If you are not interested +in network booting via PXE and just want to use koan to install virtual systems, DHCP can be totally ignored.</p> <p> </p> <h2><a name="adding_a_distribution">ADDING A DISTRIBUTION</a></h2> <p>This first step towards configurating what you want to provision is to add a distribution to the cobbler's configuration.</p> -<p>If there is an rsync mirror or filesystem tree that you would rather import instead, skip down to the documentation about the ``import'' command. It's really a lot easier, but it requires waiting for the mirror to sync data across. Imported mirrors also save time during install since they don't have to hit external install sources.</p> -<p>The manual distro add command is:</p> -<p><strong>cobbler distro add --name=string --kernel=path --initrd=path [--kopts=string] [--ksmeta=string] [--arch=x86|x86_64|ia64] [--breed=redhat|suse]</strong></p> +<p>If there is an rsync mirror, DVD, NFS, or filesystem tree available that you would rather import instead, skip down to the documentation about the ``import'' command. It's really a lot easier, and it only requires waiting for the mirror content to be copied. Imported mirrors also save time during install since they don't have to hit external install sources. However if you have the content locally already and don't want to create another copy of it, you'll want to use the manual distro add commands.</p> +<p><strong>cobbler distro add --name=string --kernel=path --initrd=path [--kopts=string] [--ksmeta=string] [--arch=x86|x86_64|ia64] [--breed=redhat|debian|suse]</strong></p> <dl> <dt><strong><a name="item_name">name</a></strong> @@ -131,13 +147,10 @@ on it, will use.</p> <p>(optional) sets the architecture for the PXE bootloader</p> </dd> <dd> -<p>x86 and x86_64 are interchangable, both use syslinux.</p> -</dd> -<dd> -<p>ia64 uses the IA64 build of elilo.</p> +<p>The default setting ('standard') will use pxelinux. Set to 'ia64' to use elilo.</p> </dd> <dd> -<p>if you don't use IA64 systems, leaving this parameter off is fine.</p> +<p>'x86' and 'x86_64' effectively do the same thing as standard.</p> </dd> </li> <dt><strong><a name="item_ksmeta">ksmeta</a></strong> @@ -152,24 +165,29 @@ on it, will use.</p> <p>Example: --ksmeta=``foo=bar baz=3 asdf''</p> </dd> <dd> -<p>See the section below on templating.</p> +<p>See the section on ``Kickstart Templating'' for further information.</p> </dd> </li> <dt><strong><a name="item_breed">breed</a></strong> <dd> -<p>Defaults to ``redhat'', which is a suitable value for Fedora and Centos as well. Specifying ``suse'' allows the kickstart file parameters to be treated instead like AutoYaST answer files, such that the proper parameters for SuSE answer files -are put on the kernel command line. Support for other types of distributions is possible in the future. The file used for the answer file, regardless of -distro breed, is the value used for --kickstart when creating the profile. See the profile add commands for further information. This feature is still rather experimental.</p> +<p>Defaults to ``redhat'', which is a suitable value for Fedora and Centos as well. It means anything redhat based.</p> +</dd> +<dd> +<p>There is limited experimental support for specifying ``debian'' or ``suse'', which treats the kickstart file as a different format and changes the kernel +arguments appropriately. Support for other types of distributions is possible in the future.</p> +</dd> +<dd> +<p>The file used for the answer file, regardless of the breed setting, is the value used for --kickstart when creating the profile.</p> </dd> </li> </dl> <p> </p> <h2><a name="adding_a_profile">ADDING A PROFILE</a></h2> -<p>A profile associates a distribution to additional specialized options, such as a kickstart automation file. Profiles are the core unit of provisioning and at least one profile must exist for every distribution to be provisioned. A profile might represent, for instance, a web server or desktop configuration.</p> -<p><strong>cobbler profile add --name=string --distro=string [--kickstart=url] [--kopts=string] [--ksmeta=string] [--virt-file-size=gigabytes] [--virt-ram=megabytes]</strong></p> -<p>Arguments are as listed for distributions, except for the ``arch'' parameter, and with the additions listed below:</p> +<p>A profile associates a distribution to additional specialized options, such as a kickstart automation file. Profiles are the core unit of provisioning and at least one profile must exist for every distribution to be provisioned. A profile might represent, for instance, a web server or desktop configuration. In this way, profiles define a role to be performed.</p> +<p><strong>cobbler profile add --name=string --distro=string [--kickstart=url] [--kopts=string] [--ksmeta=string] [--virt-file-size=gigabytes] [--virt-ram=megabytes] [--virt-type=string] [--virt-path=string]</strong></p> +<p>Arguments are as listed for distributions, save for the removal of ``arch'' and ``breed'', and with the additions listed below:</p> <dl> <dt><strong>name</strong> @@ -189,7 +207,7 @@ distro breed, is the value used for --kickstart when creating the profile. See <p>Local filesystem path to a kickstart file.</p> </dd> <dd> -<p>If this parameter is not provided, the kickstart file will default to /etc/cobbler/default.ks (or whatever is set in /var/lib/cobbler/settings). This file is initially blank, meaning default kickstarts are not automated. Admins can change the default.ks or can leave it blank.</p> +<p>If this parameter is not provided, the kickstart file will default to /etc/cobbler/default.ks. This file is initially blank, meaning default kickstarts are not automated ``out of the box''. Admins can change the default.ks if they desire..</p> </dd> </li> <dt><strong><a name="item_virt_2dfile_2dsize">virt-file-size</a></strong> @@ -204,6 +222,22 @@ distro breed, is the value used for --kickstart when creating the profile. See <p>(optional) (Virt-only) how many megabytes of RAM to consume. The default is 512 MB.</p> </dd> </li> +<dt><strong><a name="item_virt_2dtype">virt-type</a></strong> + +<dd> +<p>(optional) (Virt-only) koan can install images using either Xen paravirt (``xenpv'') or QEMU/KVM (``qemu''). Choose one or the other strings to specify, or values will default to attempting to find a compatible installation type on the client system (``auto''). See the ``koan'' manpage for more documentation.</p> +</dd> +</li> +<dt><strong><a name="item_virt_2dpath">virt-path</a></strong> + +<dd> +<p>(optional) (Virt-only) where to store the virtual image. Except for advanced cases, this parameter can usually be omitted. For disk images, the value is an +absolute path to an existing directory with an optional file name component.</p> +</dd> +<dd> +<p>There is also some experimental support for specifying partitions ``/dev/sda4'' or volume groups ``VolGroup00'', etc.</p> +</dd> +</li> <dt><strong><a name="item_repos">repos</a></strong> <dd> @@ -211,47 +245,96 @@ distro breed, is the value used for --kickstart when creating the profile. See can make use of during kickstart installation. For example, an example might be --repos=``fc6i386updates fc6i386extras''.</p> </dd> </li> +<dt><strong><a name="item_inherit">inherit</a></strong> + +<dd> +<p>(optional) profiles may inherit from other profiles in lieu of specifing --distro. Inherited profiles will override any settings specified in their parent, with the exception of --ksmet(templating) and --kopts (kernel options), which will be blended together.</p> +</dd> +<dd> +<p>Example: If profile A has --kopts=``x=7 y=2'', B inherits from A, and B has --kopts=``x=9 z=2'', the actual kernel options that will be used for B are ``x=7 y=2 z=2''.</p> +</dd> +<dd> +<p>Example: If profile B has --virt-ram=256 and A has --virt-ram of 512, profile B will use the value 256.</p> +</dd> +<dd> +<p>Example: If profile A has a --virt-file-size of 5 and B does not specify a size, B will use the value from A.</p> +</dd> +</li> </dl> <p> </p> <h2><a name="adding_a_system">ADDING A SYSTEM</a></h2> -<p>Systems assign a piece of hardware with the cobbler profile to be assigned to it. Systems can be defined by hostname, IP, or MAC address. When available, use of the MAC address to assign systems is preferred.</p> -<p><strong>cobbler system add --name=ip|mac|hostname --profile=string [--kopts=string] [--pxe-address=string] [--ksmeta=string]</strong></p> +<p>System records map a piece of hardware with the cobbler profile to be assigned to run on it. This may be thought of as chosing +a role for a specific system.</p> +<p>Note that if provisioning via koan and PXE menus alone, it is not required to create system records, though they are useful when system specific templating is required or to establish that a specific system should always recieve a specific software install. If there is a specific role inteded for a given machine, system records should be created for it.</p> +<p><strong>cobbler system add --name=string --profile=string [--mac=macaddress] [--ip=ipaddress] [--hostname=hostname] [--kopts=string] [--ksmeta=string] [--netboot-enabled=Y/N</strong></p> <p>Adds a cobbler System to the configuration. Arguments are specified as per ``profile add'' with the following changes:</p> <dl> <dt><strong>name</strong> <dd> -<p>The system name must be either a currently-resolvable hostname, an IP address, or a MAC address.</p> +<p>The system name works like the name option for other commands.</p> +</dd> +<dd> +<p>If the name looks like a MAC address or an IP, the name will implicitly be used for either --mac or --ip, respectively.</p> +</dd> +<dd> +<p>Best practice usage would suggest use a system --name that is a MAC address, because the MAC address is globally +unique, unchanging, and very explicit.</p> +</dd> +<dd> +<p>A system created with name ``default'' has special semantics. If a default system object exists, it sets all undefined +systems to PXE to a specific profile. Without a ``default'' system name created, PXE will fall through to +local boot for unconfigured systems.</p> </dd> +</li> +<dt><strong><a name="item_mac">mac</a></strong> + <dd> -<p>When defining Virtualized systems, using a MAC address causes the Virt MAC address to be used for creation, -so that is the preferred usage. To restate this, unless you have a better reason, use the MAC -address here, as it makes things a lot easier and more powerful across the board.</p> +<p>Specifying a mac address via --mac allows the system object to boot via PXE. If the name of the cobbler system +already looks like a mac address, this is inferred from the system name and does not need to be specified.</p> </dd> <dd> -<p>There is also the magic name ``default'', which allows creation of the default PXE profile. Without -a ``default'' system name created, PXE will fall through to local boot for unconfigured systems.</p> +<p>MAC addresses have the format AA:BB:CC:DD:EE:FF.</p> </dd> </li> -<dt><strong><a name="item_pxe_2daddress">pxe-address</a></strong> +<dt><strong><a name="item_ip">ip</a></strong> <dd> -<p>Advanced feature.</p> +<p>If cobbler is configured to generate a DHCP configuratition (see advanced section), use this +setting to define a specific IP for this system in DHCP. Leaving off this parameter will result in no DHCP +management for this particular system.</p> </dd> <dd> -<p>If cobbler is configured to generate the dhcpd.conf file, use this -setting to pin a certain hostname or IP to a given MAC address. This corresponds to the ``fixed-address'' field in dhcpd.conf.</p> +<p>Example: ---ip=192.168.1.50</p> </dd> <dd> -<p>When using this setting for IA64 machines, be sure that the ``--name'' given to the ``system add'' command is a MAC address or no per-system record in dhcpd.conf can be generated.</p> +<p>Note for Itanium users: this setting is always required for IA64 regardless of whether DHCP management is enabled.</p> </dd> +</li> +<dt><strong><a name="item_hostname">hostname</a></strong> + <dd> -<p>Example: ---pxe-address=192.168.1.50</p> +<p>If using the DHCP configuration feature (see advanced section) with dnsmasq, use this to define a hostname for the system to +recieve from DNS. If not using DHCP management or not using dnsmasq, this field is treated as a descriptive comment and is +basically ignored.</p> </dd> <dd> -<p>NOTE: Due to a limitation in elilo (IA64 bootloader), this parameter must ALSO be used even if dhcpd.conf files are not being managed by cobbler AND you want to PXE provision IA64 systems using a handwritten dhcpd.conf. Also, for IA64, the value of pxe-address must be an IP, and not a hostname, even though hostnames work for X86. Thankfully, if you don't have IA64 systems, there are a lot less rules.</p> +<p>Example: --hostname=mycomputer.example.com</p> +</dd> +</li> +<dt><strong><a name="item__2d_2dkickstart">--kickstart</a></strong> + +<dd> +<p>(optional) While it is recommended that the --kickstart parameter is only used within for the ``profile add'' command, there are scenarios when an install base switching to cobbler may have kickstarts created on a per-system basis (one kickstart for each system, nothing shared) and may not want to immediately make use of the cobbler templating system. This allows specifing a kickstart for use on a per-system basis. Creation of a parent profile is still required. If the kickstart is a filesystem location, it will still be treated as a cobbler template.</p> +</dd> +</li> +<dt><strong><a name="item__2d_2dnetboot_2denabled">--netboot-enabled</a></strong> + +<dd> +<p>If set false, the system will be provisionable through koan but not through +standard PXE. This will allow the system to fall back to default PXE boot behavior without deleting the cobbler system object. The default value allows PXE.</p> </dd> </li> </dl> @@ -263,13 +346,13 @@ also optional packages, 3rd party content, and even updates. Mirroring all of on your network will result in faster, more up-to-date installations and faster updates. If you are only provisioning a home setup, this will probably be overkill, though it can be very useful for larger setups (labs, datacenters, etc).</p> -<p><strong>cobbler repo add --mirror=url --name=string [--local-filename=string]</strong></p> +<p><strong>cobbler repo add --mirror=url --name=string [--local-filename=string] [--rpmlist=list] [--creatrepo-flags=string]</strong></p> <dl> <dt><strong><a name="item_mirror">mirror</a></strong> <dd> <p>The addresss of the yum mirror. This can be an rsync:// URL, an ssh location, or -a http:// or ftp:// mirror location.</p> +a http:// or ftp:// mirror location. Filesystem paths also work.</p> </dd> <dd> <p>The mirror address should specify an exact repository to mirror -- just one architecture @@ -285,9 +368,10 @@ repo seperately.</p> <a href="mailto:user@yourmirror.example.com/fedora-linux-core/updates/6/i386">user@yourmirror.example.com/fedora-linux-core/updates/6/i386</a> (for SSH)</p> </dd> <dd> -<p>Experimental support is also provided for mirroring (RHEL5) and later RHN content when you need +<p>Experimental support is also provided for mirroring RHN content when you need a fast local mirror. The mirror syntax for this is --mirror=rhn://channel-name and you must -have entitlements for this to work.</p> +have entitlements for this to work. This requires the cobbler server to be installed on RHEL5 +or later.</p> </dd> </li> <dt><strong>name</strong> @@ -300,7 +384,7 @@ have entitlements for this to work.</p> <p>This name corresponds with values given to the --repos parameter of ``cobbler profile add''. If a profile has a --repos value that matches the name here, that repo can be automatically set up during provisioning. This means that, if supported by Anaconda, the repo can be used during kickstart install -- and -- either way, -it can be automatically configured on the clients.</p> +it can be automatically configured for use by the provisioned clients (see --local-filename).</p> </dd> <dd> <p>See the documentation on ``cobbler profile add'' for more information.</p> @@ -324,16 +408,43 @@ still be used for installation, it just won't get installed automatically in /et <p>See /etc/cobbler/kickstart_fc6.ks for an example of how to employ this within a kickstart template.</p> </dd> </li> +<dt><strong><a name="item_rpm_2dlist">rpm-list</a></strong> + +<dd> +<p>By specifying a space-delimited list of package names for --rpm-list, one can decide to mirror only a part +of a repo (the list of packages given, plus dependencies). This may be helpful in conserving time/space/bandwidth. +For instance, when mirroring FC6 Extras, it may be desired to mirror just cobbler and koan, and skip all of the +games. To do this, use --rpm-list=``cobbler koan''.</p> +</dd> +<dd> +<p>This option only works for http:// and ftp:// repositories. It will be ignored for other +mirror types, such as local paths and rsync:// mirrors.</p> +</dd> +</li> +<dt><strong><a name="item_createrepo_2dflags">createrepo-flags</a></strong> + +<dd> +<p>Specifies optional flags to feed into the createrepo tool, which is called when ``cobbler reposync'' is run for the +given repository. The defaults are '-c cache'.</p> +</dd> +</li> +<dt><strong>arch</strong> + +<dd> +<p>Specifies what architecture the repository should use. By default the current system arch (of the server) is used, which may not be desirable. Using this to override the default arch allows mirroring of source repositories (using --arch=src).</p> +</dd> +</li> </dl> <p> </p> <h2><a name="displaying_configuration_entries">DISPLAYING CONFIGURATION ENTRIES</a></h2> -<p>This is a rather simple command, usable regardless of how you are using cobbler.</p> -<p><strong>cobbler report [--settings] [--profiles] [--distros] [--systems] [--repos]</strong></p> -<p>Prints the current cobbler configuration for systems, profiles, and groups. If one of the switches is given, only information for those is printed.</p> -<p>The list command gives an abbreviated version of what ``report'' gives. -It only returns the names of each item.</p> -<p><strong>cobbler list [--settings] [--profiles] [--distros] [--systems] [--repos]</strong></p> +<p>The following commands are usable regardless of how you are using cobbler. +``report'' gives detailed configuration info. ``list'' just lists the names of items in the configuration. +Run these commands to check how you have cobbler configured.</p> +<p><strong>cobbler report</strong></p> +<p><strong>cobbler distro|profile|system|repo report [object-name]</strong></p> +<p><strong>cobbler list</strong></p> +<p><strong>cobbler distro|profile|system|repo list [object-name]</strong></p> <p>Alternatively, you could look at the configuration files in /var/lib/cobbler to see the same information.</p> <p> </p> @@ -345,6 +456,23 @@ It only returns the names of each item.</p> <p><strong>cobbler remove repo --name=string</strong></p> <p> </p> +<h2><a name="editing">EDITING</a></h2> +<p>If you want to change a particular setting without doing an ``add'' again, use the ``edit'' command, using +the same name you gave when you added the item. Anything supplied in the parameter list will overwrite +the settings in the existing object, preserving settings not mentioned.</p> +<p><strong>cobbler distro|profile|system|repo edit --name=string [parameterlist]</strong></p> +<p> +</p> +<h2><a name="copying">COPYING</a></h2> +<p>Objects can also be copied:</p> +<p><strong>cobbler distro|profile|system|repo copy --name=oldname --newname=newname</strong></p> +<p> +</p> +<h2><a name="renaming">RENAMING</a></h2> +<p>Objects can also be renamed, as long as other objects don't reference them.</p> +<p><strong>cobbler distro|profile|system|repo rename --name=oldname --newname=newname</strong></p> +<p> +</p> <h2><a name="rebuilding_configurations">REBUILDING CONFIGURATIONS</a></h2> <p><strong>cobbler sync</strong></p> <p>Cobbler sync is used to repair or rebuild the contents /tftpboot or /var/www/cobbler when something has changed behind the scenes. It brings the filesystem up to date with the configuration as understood by cobbler.</p> @@ -361,11 +489,14 @@ run after systems are added to regenerate and reload the DHCP configuration.</p> <p>This example shows how to create a provisioning infrastructure from a distribution mirror. Then a default PXE configuration is created, so that by default systems will PXE boot into a fully automated install process for that distribution.</p> -<p>You can use a network rsync mirror or a mounted DVD location.</p> +<p>You can use a network rsync mirror, a mounted DVD location, or a tree you have available +via a network filesystem.</p> <p><strong>cobbler check</strong></p> -<p><strong>cobbler import --mirror=rsync://yourfavoritemirror.com/foo --mirror-name=anyname</strong></p> +<p><strong>cobbler import --path=rsync://yourfavoritemirror.com/foo --name=anyname</strong></p> <p># OR</p> -<p><strong>cobbler import --mirror=root@localhost:/mnt/dvd --mirror-name=anyname</strong></p> +<p><strong>cobbler import --path=/mnt/dvd --name=anyname</strong></p> +<p># OR (using an eternal NAS box without mirroring)</p> +<p><strong>cobbler import --path=/path/where/filer/is/mounted --name=anyname --available-as=nfs://nfs.example.org:/where/mounted/</strong></p> <p># wait for mirror to rsync...</p> <p><strong>cobbler report</strong></p> <p><strong>cobbler system add --name=default --profile=name_of_a_profile1</strong></p> @@ -400,11 +531,13 @@ that will auto install those repository configurations on provisioned systems us </p> <h2><a name="xen">XEN</a></h2> <p>For Virt, be sure the distro uses a Virt kernel and initrd and follow similar steps as above, adding additional parameters as desired:</p> -<p><strong>cobbler distro add --name=fc5virt --kernel=/dir3/vmlinuz --initrd=/dir6/initrd.img</strong></p> -<p>Specify reasonable values for the Virt image size (in GB) and RAM requirements:</p> -<p><strong>cobbler profile add --name=virtwebservers --distro=fc5virt --kickstart=/dir7/kick.ks --virt-file-size=10 --virt-ram=512</strong></p> -<p>And define systems (if desired) using MAC addresses, not IP's or hostnames:</p> +<p><strong>cobbler distro add --name=fc7virt [options...]</strong></p> +<p>Specify reasonable values for the Virt image size (in GB) and RAM requirements (in MB):</p> +<p><strong>cobbler profile add --name=virtwebservers --distro=fc7virt --kickstart=path --virt-file-size=10 --virt-ram=512</strong></p> +<p>Define systems only if desired. koan can also provision based on the profile name.</p> <p><strong>cobbler system add --name=AA:BB:CC:DD:EE:FE --profile=virtwebservers</strong></p> +<p>If you have just installed cobbler, be sure that the ``cobblerd'' service is running and that port 25151 is unblocked.</p> +<p>See the manpage for koan for the client side steps.</p> <p> </p> <hr /> @@ -420,38 +553,51 @@ knows about.</p> <p>If the association between a system (MAC address) and a profile is already known, it may be more useful to just use ``system add'' commands and declare that relationship in cobbler; however many use cases will prefer having a PXE system, especially when provisioning is done at the same time as installing new physical machines.</p> <p>If this behavior is not desired, run ``cobbler system add --name=default --profile=plugh'' to default all PXE booting machines to get a new copy of the profile ``plugh''. To go back to the menu system, run ``cobbler system remove --name=default'' and then ``cobbler sync'' to regenerate the menus.</p> +<p>When using PXE menu deployment exclusively, it is not neccessary to make cobbler system records, although the two can easily be mixed.</p> +<p>Additionally, note that all files generated for the pxe menu configurations are templatable, so if you wish to change the color +scheme or equivalent, see the files in /etc/cobbler.</p> <p> </p> <h2><a name="kickstart_templating">KICKSTART TEMPLATING</a></h2> <p>The --ksmeta options above require more explanation.</p> <p>If and only if --kickstart options reference filesystem URLs, --ksmeta allows for templating of the kickstart files to achieve advanced functions. If the --ksmeta option for a profile read --ksmeta=``foo=7 bar=llama'', anywhere -in the kickstart file where the string ``TEMPLATE::bar'' appeared would be replaced with the string ``llama''. (Actually $bar is also replaced, if you prefer that syntax).</p> +in the kickstart file where the string ``$bar'' appeared would be replaced with the string ``llama''.</p> <p>To apply these changes, ``cobbler sync'' must be run to generate custom kickstarts for each profile/system.</p> -<p>For NFS and HTTP URLs, the ``--ksmeta'' options will have no effect. This is a good reason to let +<p>For NFS and HTTP kickstart URLs, the ``--ksmeta'' options will have no effect. This is a good reason to let cobbler manage your kickstart files, though the URL functionality is provided for integration with legacy infrastructure, possibly including web apps that already generate kickstarts.</p> <p>Templated kickstart files are processed by the templating program/package Cheetah, so anything you can do in a Cheetah template can be done to a kickstart template. Learn more at <a href="http://www.cheetahtemplate.org/learn.html">http://www.cheetahtemplate.org/learn.html</a></p> <p>When working with Cheetah, be sure to escape any shell macros that look like ``$(this)'' with something like ``\$(this)'' or errors may show up during the sync process.</p> -<p>Should you want to express larger sections of templating (more that can be decently expressed on the command line), you may want to edit /var/lib/cobbler/ files directly. Keep in mind that changes need to be valid YAML 1.0 syntax and ``cobbler sync'' should be run after making any changes to those files.</p> +<p> +</p> +<h2><a name="kickstart_snippets">KICKSTART SNIPPETS</a></h2> +<p>Anywhere a kickstart template mentions SNIPPET::snippet_name, the file named /var/lib/cobbler/snippet/snippet_name (if present) will be included automatically in the kickstart template. This serves as a way to recycle frequently used kickstart snippets without duplication. Snippets can contain templating variables, and the variables will be evaluated according to the profile and/or system as one would expect.</p> +<p> +</p> +<h2><a name="kickstart_validation">KICKSTART VALIDATION</a></h2> +<p>To check for potential errors in kickstarts, prior to installation, use ``cobbler validateks''. This function will check all profile and system kickstarts for detectable errors. Since pykickstart is not future-Anaconda-version aware, there may be some false positives. It should be noted that ``cobbler validateks'' runs on the rendered kickstart output, not kickstart templates themselves.</p> <p> </p> <h2><a name="dhcp_configuration_management">DHCP CONFIGURATION MANAGEMENT</a></h2> -<p>By default, cobbler does not write a dhcpd.conf and leaves configuration -of DHCP up to the user. If manage_dhcp is set to 1 in /var/lib/cobbler/settings, -this changes, and cobbler *will* write it's own dhcp.conf file, replacing any dhcpd.conf -that already exists.</p> -<p>The file is based on a template in /etc/cobbler/dhcpd.conf.template -- and must be user edited for -the user's particular networking environment. Read the file and understand dhcpd.conf files before proceeding. -If you already have dhcpd.conf data that you would like to preserve (say DHCP was manually configured earlier), -insert the relevant portions of it into the template file.</p> -<p>So, if this manage_dhcp bit is enabled, the following features are enabled:</p> +<p>Cobbler can optionally help you manage DHCP and (depending on how used) DNS as it relates +to systems you wish to provision/control. This allows cobbler to essentially maintain a database +of all of your installed systems, and be a central point of control for aspects related to setting +up those systems.</p> +<p>This feature is off by default and must be turned on by setting 'manage_dhcp' to 1 in +/var/lib/cobbler/settings. Choices include ISC dhcpd (default), or DNSmasq, which can be chosen +by setting manage_dhcp_mode to 'dnsmasq'. If you choose dnsmasq and want to revert to ISC, change +the setting to 'isc'.</p> +<p>Depending on your choice, cobbler will use /etc/cobbler/dhcpd.template or /etc/cobbler/dnsmasq.template as a starting point. This file must be user edited for the user's particular networking environment. Read the file and understand how the particular app (ISC dhcpd or dnsmasq) work before proceeding.</p> +<p>If you already have DHCP configuration data that you would like to preserve (say DHCP was manually configured earlier), insert the relevant portions of it into the template file, as running ``cobbler sync'' will overwrite your previous configuration.</p> +<p>In summary, if this manage_dhcp bit is enabled, the following features are enabled:</p> <p>(A) pinning dhcp hostnames to MAC addresses automatically. -(B) relatively seamless mixing of Itanium and x86/x86_64 machines in a PXE environment</p> -<p>Per-system records in DHCP will only be written if the cobbler system name is a MAC address, so it's recommended that those be used if manage_dhcp is turned on.</p> -<p>Itanium systems names also need to be specified by the MAC address, and their distribution needs to be created with the ``--arch=ia64'' parameter.</p> -<p>The dhcpd.conf file will be updated each time ``cobbler sync'' is run, and not until then, so it is important -to remember to use ``cobbler sync'' when using this feature.</p> +(B) relatively seamless mixing of Itanium and x86/x86_64 machines in a PXE environment (ISC only) +(C) assigning hostnames to MAC addresses using DNS (dnsmasq only).</p> +<p>These options are all enabled by using the --hostname and --ip options when using the ``cobbler system add'' command.</p> +<p>Itanium systems names also need to be assigned to a distro that was created with the ``--arch=ia64'' parameter. If you have Itanium systems, you must (for now) choose 'isc' for +'manage_dhcp_mode' in the /var/lib/cobbler/settings file, and are required to use --ip when creating the system object in order for those systems to PXE.</p> +<p>The dhcpd.conf file will be updated each time ``cobbler sync'' is run, and not until then, so it is important to remember to use ``cobbler sync'' when using this feature. Support for online updates to DHCP (and DNS, in this dnsmasq case) are pending.</p> <p> </p> <h2><a name="enchant">ENCHANT</a></h2> @@ -464,19 +610,24 @@ Usage: <strong>cobbler enchant --address=ip|hostname --system=string</strong></ the remote machine. The default behavior is machine (not virtual) re-provisioning.</p> <p>Example: <strong>cobbler enchant --virt=yes --address=192.168.10.10 --profile=fc6xen</strong></p> <p>Before using enchant, configure the location of the koan noarch RPM in /var/lib/cobbler/settings (a local path) and re-run ``cobbler sync''.</p> +<p>Enterprising users will notice this is not much more than a wrapper around SSH commands to koan, but it's OS version agnostic and gets koan installed even if it's not available via up2date/yum.</p> <p> </p> <h2><a name="importing_trees">IMPORTING TREES</a></h2> -<p>Cobbler can auto-add distributions and profiles from remote sources, whether this is an NFS path or an rsync mirror. This can save a lot of time when setting up a new provisioning environment.</p> -<p>When importing a rsync mirror, cobbler will try to detect the distribution type and automatically assign kickstarts. By default, it will provision the system by erasing the hard drive, setting up eth0 for dhcp, and using a default password of ``cobbler''. If this is undesirable, edit the kickstart files in /etc/cobbler to do something else or change the kickstart setting after cobbler creates the profile.</p> -<p>Note that if you use --path instead of --mirror, no files will actually be copied. Most of the time, usage of --mirror is preferred, to create a local copy of the files you are importing. These files are saved automatically in /var/www/cobbler/ks_mirror.</p> -<p>Example: <strong>cobbler import --mirror=rsync://mirrorserver.example.com/path/ --mirror-name=fedora</strong></p> -<p>Example2: <strong>cobbler import <a href="mailto:--mirror=root@192.168.1.10:/stuff">--mirror=root@192.168.1.10:/stuff</a> --mirror-name=bar</strong></p> -<p>Example3: <strong>cobbler import --mirror=root@localhost:/mnt/dvd --mirror-name=baz</strong></p> -<p>Example4: <strong>cobbler import --path=/path/to/stuff --mirror-name=glorp</strong></p> +<p>Cobbler can auto-add distributions and profiles from remote sources, whether this is a filesystem path or an rsync mirror. This can save a lot of time when setting up a new provisioning environment. Import is a feature that many users will want to take advantage of, and is very simple to use. +</p> +<pre> + +After an import is run, cobbler will try to detect the distribution type and automatically assign kickstarts. By default, it will provision the system by erasing the hard drive, setting up eth0 for dhcp, and using a default password of "cobbler". If this is undesirable, edit the kickstart files in /etc/cobbler to do something else or change the kickstart setting after cobbler creates the profile.</pre> +<p>Mirrored content is saved automatically in /var/www/cobbler/ks_mirror.</p> +<p>Example: <strong>cobbler import --mirror=rsync://mirrorserver.example.com/path/ --name=fedora</strong></p> +<p>Example2: <strong>cobbler import <a href="mailto:--mirror=root@192.168.1.10:/stuff">--mirror=root@192.168.1.10:/stuff</a> --name=bar</strong></p> +<p>Example3: <strong>cobbler import --mirror=/mnt/dvd --name=baz</strong></p> +<p>Example4: <strong>cobbler import --mirror=/path/to/stuff --name=glorp</strong></p> +<p>Example5: <strong>cobbler import --path=/path/where/filer/is/mounted --name=anyname --available-as=nfs://nfs.example.org:/where/mounted/</strong></p> <p>Once imported, run a ``cobbler list'' or ``cobbler report'' to see what you've added.</p> -<p>``Cobbler sync'' should still be run after an import to get the system ready to provision what was just imported.</p> <p>By default, the rsync operations will exclude PPC content, debug RPMs, and ISO images -- to change what is excluded during an import, see /etc/cobbler/rsync.exclude.</p> +<p>Note that all of the import commands will mirror install tree content into /var/www/cobbler unless a network accessible location is given with --available-as. --available-as will be primarily used when importing distros stored on an external NAS box, or potentially on another partition on the same machine that is already accessible via http:// or ftp://.</p> <p> </p> <h2><a name="default_pxe_boot_behavior">DEFAULT PXE BOOT BEHAVIOR</a></h2> @@ -516,12 +667,20 @@ use ``cobbler reposync'' to update cobbler mirrors, as reposync does not perform cobbler adds support for rsync and SSH locations, where as yum's reposync only supports what yum supports (http/ftp).</p> <p>Note that if a cobbler import provides enough information to use the boot server as a yum mirror for -core packages, cobbler will set up kickstarts to use the cobbler server as a mirror instead of the -outside world. If this feature is undesirable, it can be turned off by setting yum_core_mirror_from_server -to 0 in /var/lib/cobbler/settings (and rerunning ``cobbler sync''). You may want to disable this feature +core packages, cobbler can set up kickstarts to use the cobbler server as a mirror instead of the +outside world. If this feature is desirable, it can be turned on by setting yum_core_mirror_from_server +to 1 in /var/lib/cobbler/settings (and rerunning ``cobbler sync''). You should not enable this feature if machines are provisioned on a different VLAN/network than production.</p> <p> </p> +<h2><a name="pxe_boot_loop_prevention">PXE BOOT LOOP PREVENTION</a></h2> +<p>If you have your machines set to PXE first in the boot order (ahead of hard drives), change +the ``pxe_just_once'' flag in /var/lib/cobbler/settings to 1. This will set the machines +to not PXE on successive boots once they complete one install.</p> +<p>To re-enable PXE for a specific system, run the following command:</p> +<p><strong>cobbler system edit --name=name --netboot-enabled=1</strong></p> +<p> +</p> <h2><a name="kickstart_tracking">KICKSTART TRACKING</a></h2> <p>Cobbler knows how to keep track of the status of kickstarting machines.</p> <p><strong>cobbler status</strong></p> @@ -545,8 +704,14 @@ files in /etc/cobbler that can be edited.</p> <p>Running ``cobbler sync'' is required to apply any changes that are made manually.</p> <p> </p> +<h2><a name="triggers">TRIGGERS</a></h2> +<p>Triggers provide a way to integrate cobbler with arbitrary 3rd party software without modifying cobbler's code. +When adding a distro, profile, system, or repo, all scripts in /var/lib/cobbler/triggers/add are executed for the particular object type. Each particular file must be executable and it is executed with the name of the item being added as a parameter. Deletions work similarly -- delete triggers live in /var/lib/cobbler/triggers/delete. Order of execution is arbitrary, and cobbler does not ship with any triggers by default.</p> +<p> +</p> <h2><a name="api">API</a></h2> -<p>Cobbler also makes itself available as a Python API for use by higher level management software.</p> +<p>Cobbler also makes itself available as a Python API for use by higher level management software. +Learn more at <a href="http://cobbler.et.redhat.com">http://cobbler.et.redhat.com</a></p> <p> </p> <hr /> @@ -555,11 +720,17 @@ files in /etc/cobbler that can be edited.</p> <p> </p> <hr /> -<h1><a name="mailing_list">MAILING LIST</a></h1> -<p>Cobbler has a mailing list for user and development-related questions/comments at <a href="mailto:et-mgmt-tools@redhat.com.">et-mgmt-tools@redhat.com.</a></p> +<h1><a name="additional_resources">ADDITIONAL RESOURCES</a></h1> +<p>Cobbler has a mailing list for user and development-related questions/comments at <a href="mailto:et-mgmt-tools@redhat.com.">et-mgmt-tools@redhat.com.</a> +At the time of writing, there is also a IRC channel on irc.freenode.net (#cobbler).</p> <p> </p> <hr /> <h1><a name="author">AUTHOR</a></h1> -<p>Michael DeHaan <<a href="mailto:mdehaan@redhat.com">mdehaan@redhat.com</a>></p> +<p>Michael DeHaan <<a href="mailto:mdehaan@redhat.com">mdehaan@redhat.com</a>> + +</p> + +</body> +</html> diff --git a/website/new/docs/koan.html b/website/new/docs/koan.html index 807bf8d..f5b382b 100644 --- a/website/new/docs/koan.html +++ b/website/new/docs/koan.html @@ -1,3 +1,13 @@ +<?xml version="1.0" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> +<head> +<title>NAME</title> +<meta http-equiv="content-type" content="text/html; charset=utf-8" /> +<link rev="made" href="mailto:root@localhost" /> +</head> + +<body style="background-color: white"> <p><a name="__index__"></a></p> <!-- INDEX BEGIN --> @@ -7,7 +17,15 @@ <li><a href="#name">NAME</a></li> <li><a href="#synopsis">SYNOPSIS</a></li> <li><a href="#description">DESCRIPTION</a></li> + <li><a href="#the_cobbler_server">THE COBBLER SERVER</a></li> + <li><a href="#listing_available_resources">LISTING AVAILABLE RESOURCES</a></li> + <li><a href="#main_commands">MAIN COMMANDS</a></li> + <li><a href="#viewing_the_installation_data">VIEWING THE INSTALLATION DATA</a></li> + <li><a href="#virtualized_installs">VIRTUALIZED INSTALLS</a></li> + <li><a href="#reinstallation">REINSTALLATION</a></li> <li><a href="#notes_for_users_of_cobbler_templating">NOTES FOR USERS OF COBBLER TEMPLATING</a></li> + <li><a href="#new_live_cd">NEW LIVE CD</a></li> + <li><a href="#post_installation_management_of_virt_guests">POST INSTALLATION MANAGEMENT OF VIRT GUESTS</a></li> <li><a href="#additional">ADDITIONAL</a></li> <li><a href="#author">AUTHOR</a></li> </ul> @@ -17,39 +35,183 @@ <p> </p> <h1><a name="name">NAME</a></h1> -<p>koan stands for ``kickstart-over-a-network'' and allows for both network provisioning of new virtualized guests and destructive provisioning of any existing system. For use with a boot-server configured with 'cobbler'.</p> +<p>koan stands for ``kickstart-over-a-network'' and allows for both network provisioning of new virtualized guests (Xen, QEMU/KVM) and re-installation of an existing system. koan is a client side application used with a Cobbler boot server.</p> <p> </p> <hr /> <h1><a name="synopsis">SYNOPSIS</a></h1> -<p>koan --server=<host> --list-profiles</p> -<p>koan --server=<host> --list-systems</p> -<p>koan --virt --server=<host> --profile=<name> [--virtname=<name>]</p> -<p>koan --virt --server=<host> --system=<name> [--virtname=<name>]</p> -<p>koan --replace-self --server=<host> --profile=<name></p> -<p>koan --replace-self --server=<host> --system=<name></p> +<p>koan --server=<host> [--list-profiles|--list-systems]</p> +<p>koan --server=<host> [--virt|--replace-self|--display] [--profile=<name>|--system=<name>] [--virt-name=<name>] [--virt-path=<path>] [--virt-type=<type>] [--virt-graphics]</p> <p> </p> <hr /> <h1><a name="description">DESCRIPTION</a></h1> -<p>When invoked, koan requests profile information from a remote boot server that has been configured with cobbler. What koan does with the profile data depends on whether it was invoked with --virt or --replace-self.</p> -<p>For --virt, cobbler will create new virtualized guests on a machine in accordance to the orders from cobbler. You can then, once finished, use ``virsh'' and ``xm'' commands on the guest. Cobbler automatically names domains based on their mac addresses. To install using a more descriptive name, specify one with --virtname.</p> -<p>For re-kickstarting ('--replace-self'), cobbler will reprovisioning the system, blowing away any current data and replacing it with the results of a network install.</p> +<p>When invoked, koan requests install information from a remote cobbler boot server. What koan does with the profile data depends on whether it was invoked with --virt or --replace-self.</p> +<p> +</p> +<hr /> +<h1><a name="the_cobbler_server">THE COBBLER SERVER</a></h1> +<dl> +<dt><strong><a name="item__2d_2dserver">--server</a></strong> + +<dd> +<p>Indicates the hostname of the Cobbler boot server to be contacted. Successful +communication requires that no firewalls are blocking the cobbler XMLRPC port, +which is usually 25151, and that ``cobblerd'' is running on the cobbler server.</p> +</dd> +<dd> +<p>This argument must be specified for all koan commands.</p> +</dd> +</li> +</dl> +<p> +</p> +<hr /> +<h1><a name="listing_available_resources">LISTING AVAILABLE RESOURCES</a></h1> +<p>Lists of the resources that can be installed from a remote server can be obtained by using the following commands:</p> +<dl> +<dt><strong><a name="item__2d_2dlist_2dprofiles">--list-profiles</a></strong> + +<dd> +<p>Shows a list of profiles that can be remotely installed from the cobbler server.</p> +</dd> +</li> +<dt><strong><a name="item__2d_2dlist_2dsystems">--list-systems</a></strong> + +<dd> +<p>Shows a list of systems that can be remotely installed from the cobbler server. Systems contain the same information as profiles but may be further customized in terms of parameters or kickstart information. The level of customization varies depending on what has been specified on the cobbler server.</p> +</dd> +</li> +</dl> +<p>Example: koan --server=cobbler.example.org --list-systems</p> +<p> +</p> +<hr /> +<h1><a name="main_commands">MAIN COMMANDS</a></h1> +<p>The commands --virt, --replace-self, and --display all take the following arguments:</p> +<dl> +<dt><strong><a name="item__2d_2dprofile">--profile</a></strong> + +<dd> +<p>Names a profile, known to cobbler, that is to be installed.</p> +</dd> +</li> +<dt><strong><a name="item__2d_2dsystem">--system</a></strong> + +<dd> +<p>Names a system, known to cobbler, that is to be installed. --system cannot +be used at the same time as --profile; pick one or the other.</p> +</dd> +</li> +</dl> +<p> +</p> +<hr /> +<h1><a name="viewing_the_installation_data">VIEWING THE INSTALLATION DATA</a></h1> +<p>In depth data about what is being installed can be viewed prior to +kicking off an installation. Use --display instead of --virt or +--replace-self. When using this argument, specify the data to display +with --profile or --system.</p> +<p>Example: koan --server=cobbler.example.org --display --profile=fedora7-xen-i386</p> +<p> +</p> +<hr /> +<h1><a name="virtualized_installs">VIRTUALIZED INSTALLS</a></h1> +<p>When using --virt, koan will create new virtualized guests on a machine in accordance to the orders from cobbler. These can be Xen or QEMU/KVM guests depending on --virt-type. Once created, use ``virsh'' to control the guests. Virsh may need a connection string like ``virsh --connect qemu:///system''.</p> +<p>Example: koan --server=cobbler.example.org --virt --profile=fedora7-xen-i386</p> +<p>If --profile is specified, cobbler will default to naming domains based on their mac addresses; using --system will use the exact name given to the cobbler system object. To install using an alternate descriptive name, specify one with --virtname.</p> +<p>The additional parameters --virt-path, and --virt-type allow overriding certain defaults that are ordinarily defined by the remote cobbler server.</p> +<p>Optional advanced-configuration parameters for --virt:</p> +<dl> +<dt><strong><a name="item__2d_2dvirt_2dname">--virt-name</a></strong> + +<dd> +<p>(optional) Overrides the name of the virtual machine. This name must not conflict with +other virtual machines running on the same system. If not specified, cobbler +will provide reasonable defaults.</p> +</dd> +</li> +<dt><strong><a name="item__2d_2dvirt_2dpath">--virt-path</a></strong> + +<dd> +<p>(optional) Specifies the storage for the virtual image. This path must be an absolute path of an existing directory in which to store the image, with an optional filename component.</p> +</dd> +<dd> +<p>There is also experimental support for specifying partitions such as ``/dev/sda4''. Volume Groups with available free space can also be used by specifying a group name such as ``VolGroup00''. Partitions should always start with /dev and Volume Groups should be represented by their names.</p> +</dd> +</li> +<dt><strong><a name="item__2d_2dvirt_2dtype">--virt-type</a></strong> + +<dd> +<p>(optional) Koan can install virtual guests for Xen (paravirtualized), or QEMU/KVM (paravirtualized or fully virtualized based on hardware support). Use --virt-type=``qemu'' or --virt-type=``xenpv'' to override the values already defined in cobbler. Since this parameter can be set in the cobbler profile, it's best to just set it there. See the cobbler manpage for more documentation.</p> +</dd> +<dd> +<p>qemu installs will select kvm, kqemu, or qemu, based on available hardware support.</p> +</dd> +</li> +<dt><strong><a name="item__2d_2dvirt_2dgraphics">--virt-graphics</a></strong> + +<dd> +<p>(optional) This enables VNC graphics for virtual installs. Currently qemu-based installs ignore this parameter and always enable VNC. With VNC on, it is assumed a firewall is blocking remote access to the server. In the future, qemu installs may respect the presence/absense of this parameter as Xen installs currently do.</p> +</dd> +</li> +</dl> +<p>Example: koan --server=cobbler.example.org --virt --profile=rhel5-x86_64 --virt-type=``qemu'' --virt-path=``/home/username/qemu/'' --virt-name=``test_setup''</p> +<p> +</p> +<hr /> +<h1><a name="reinstallation">REINSTALLATION</a></h1> +<p>When using '--replace-self', cobbler will reprovision the system, blowing away any current data and replacing it with the results of a network install. Specify a specific item from cobbler with --system or --profile, otherwise cobbler will try to see if there is a cobbler system record that matches a MAC address on the system.</p> +<p>This is useful to reinstall systems in conditions where ordinary PXE is not possible.</p> +<p>After using this feature, run ``/sbin/reboot'' to initiate the fully automatic reinstallation.</p> +<p>Example: koan --server=cobbler.example.org --profile=fedora7-xen-i386 --replace-self</p> +<p>Example: koan --server=cobbler.example.org --replace-self</p> <p> </p> <hr /> <h1><a name="notes_for_users_of_cobbler_templating">NOTES FOR USERS OF COBBLER TEMPLATING</a></h1> -<p>Cobbler contains an advanced templating feature that allows a single kickstart file to be customized on a per-system basis. See the cobbler manpage for more details.</p> -<p>If you have system specific customizations in your kickstarts and have cobbler system definitions defined server side for those systems, use --system and not --profile.</p> +<p>Cobbler contains a templating feature that allows a single kickstart file to be customized on a per-system basis. See the cobbler manpage for more details.</p> +<p>If you have system specific customizations in your kickstarts and have cobbler system definitions defined server side for those systems, use --system and not --profile, to request the more specific per-system information from Cobbler.</p> +<p> +</p> +<hr /> +<h1><a name="new_live_cd">NEW LIVE CD</a></h1> +<p>Koan's source checkout (see <a href="http://cobbler.et.redhat.com)">http://cobbler.et.redhat.com)</a> can be used to build +a live CD for use with koan. This live CD serves the purpose of running +--replace-self with no OS present -- bare metal installation. This tool may prove useful to emulate a PXE environment with a cobbler server, when no local DHCPconfiguration is not feasible or otherwise undesired.</p> +<p>To build a CD (on Fedora 7):</p> +<p>yum install livecd-tools</p> +<p>git clone <a href="git://et.redhat.com/koan">git://et.redhat.com/koan</a></p> +<p>cd /checkout/koan</p> +<p>make</p> +<p>cd /checkout/koan/live</p> +<p>python build.py --server=cobbler.example.org --koan=``--profile=foo''</p> +<p># OR (for auto-detection)</p> +<p>python build.py --server=cobbler.example.org --koan=``''</p> +<p># burn the CD, and insert it in a bare metal machine</p> +<p>The koan live CD is in the early stages of development and may not +support all direct attached storage. NOTE: Usage of the Live CD will +erase all data on the first DASD disk during the course of provisioning.</p> +<p> +</p> +<hr /> +<h1><a name="post_installation_management_of_virt_guests">POST INSTALLATION MANAGEMENT OF VIRT GUESTS</a></h1> +<p>The best tools to use after automatically installing a virt guest with koan are SSH (once installed and running), virsh, or virt-manager. If VNC graphics are +available, virt-manager will allow access to the guest as if logged in directly +to it. For Xen guests, ``virsh console <name>'' will also allow access to the +guests. There is no QEMU console support at this time (use virt-manager with VNC or SSH).</p> +<p>Various additional commands are available through virsh. See the virsh manpage for details. Depending on virt type, start virsh with either just ``virsh'' (for Xen) or ``virsh --connect=qemu:///system'' (for QEMU).</p> <p> </p> <hr /> <h1><a name="additional">ADDITIONAL</a></h1> -<p>Consult the man page for cobbler for more information.</p> +<p>Also see the cobbler manpage. It is both entertaining and educational.</p> <p> </p> <hr /> <h1><a name="author">AUTHOR</a></h1> <p>Michael DeHaan <<a href="mailto:mdehaan@redhat.com">mdehaan@redhat.com</a>></p> +</body> +</html> diff --git a/website/new/documentation.html b/website/new/documentation.html index 65b137b..86088f1 100644 --- a/website/new/documentation.html +++ b/website/new/documentation.html @@ -8,8 +8,8 @@ <!-- <li><a href="cobbler-guide.php">Cobbler Guide</a></li> --> -<li><a href="./cobbler-manpage.php">Cobbler Manpage</a></li> -<li><a href="./koan-manpage.php">Koan Manpage</a></li> +<li><a href="./docs/cobbler.html">Cobbler Manpage</a></li> +<li><a href="./docs/koan.html">Koan Manpage</a></li> <li><a href="./cobbler-import.php">A Quickstart Guide on Using "import"</a></li> <li><a href="./cobbler-repos.php">Using Cobbler to manage yum repositories</a></li> <li><a href="./cobbler-dhcp.php">Cobbler's DHCP management features</a></li> |