=head1 NAME

cobbler is a command line tool for configuring a provisioning server.  It supports provisioning via PXE, Xen, and re-provisioning an existing Linux system ("auto-kickstarting").  The latter two features are enabled by usage of 'koan' (a client side provisioning application) on the remote system.

=head1 SYNOPSIS

cobbler command [subcommand] [--arg1=] [--arg2=]

=head1 DESCRIPTION

Cobbler manages provisioning using a tiered concept of Distributions, Profiles, and Systems.

Distributions contain information about what kernel and initrd are used, along with various other information, such as required kernel parameters.  

Profiles associate a Distribution with a kickstart file and optionally customize it further.  

Systems associate a hostname, IP, or MAC with a distribution and optionally customize the Profile further.

=head1 ACTIONS

=head2 SETUP

Running "cobbler check" after installation will verify that the prerequisites are installed and configured correctly.

Any problems detected should be corrected, with the potential exception of DHCP related warnings.  

It is especially important that the server name be accurate in cobbler.conf

For PXE, if DHCP is 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".   

=head2 ADDING A DISTRIBUTION

B<cobbler distro add --name=<string> --kernel=<path> --initrd=<path> [--kopts=<string>] [--ksmeta=<string>] [--arch=<x86|x86_64|ia64>]

=over

=over

=item name

a string identifying the distribution

=item kernel

an absolute filesystem path to a kernel image

=item initrd

an absolute filesystem path to a initrd image

=item kopts

(optional) sets kernel arguments.

Example: --ksmeta="foo=bar baz=3 asdf"

=item arch

(optional) sets the architecture for the PXE bootloader

x86 and x86_64 are interchangable, both use syslinux.

ia64 uses the IA64 build of elilo.

=item ksmeta

(optional)

This is an advanced feature that sets kickstart variables to substitute, thus enabling kickstart files to be treated as templates.  

Example: --ksmeta="foo=bar baz=3 asdf"

See the section below on templating.

=back

=back

=head2 ADDING A PROFILE

B<cobbler profile add --name=<string> --distro=<string> [--kickstart=<url>] [--kopts=<string>] [--ksmeta=<string>] [--xen-name=<string>] [--xen-file-size=<gigabytes>] [--xen-ram=<megabytes>]

=over

=over

Arguments are as listed for distributions, with the follwing additions...

=item distro

the name of a previously defined cobbler distribution

=item kickstart

(optional) an HTTP URL, NFS URL, or local filesystem path to a kickstart file

=item xen-name

(optional) (Xen-only) what the Xen domU name should start with

=item xen-file-size

(optional) (Xen-only) how large the disk image should be in gigabytes

=item xen-ram

(optional) (Xen-only) how many megabytes of RAM to consume

=back

=back


=head2 ADDING A SYSTEM

B<cobbler system add --name=<ip|mac|hostname> --profile=<string> [--kopts=<string>] [--pxe-address=<string>] [--ksmeta=<string>]
=over

=over

Adds a cobbler System to the configuration.  Arguments are specified as per "profile add" with
the following changes:

=item name

The system name must be either a currently-resolvable hostname, an IP address, or a MAC address.

When defining Xen systems, using a MAC address causes the Xen MAC address to be used for creation,
so that is the preferred usage.

=item pxe-address

Advanced feature.

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.

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. 

Example: ---pxe-address=192.168.1.50

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.

=back

=head2 DISPLAYING CONFIGURATION ENTRIES

B<cobbler list>

Prints the current cobbler configuration for systems, profiles, and groups.  

=head2 DELETING CONFIGURATION ENTRIES

B<cobbler distro remove --name=<string>>

B<cobbler profile remove --name=<string>>

B<cobbler system remove --name=<string>>

=head2 APPLYING CONFIGURATIONS

B<cobbler sync [--dryrun]>

Configurations are saved in /var/lib/cobbler.  Changes made with any commands are not
applied until 'cobbler sync' is run.   Any errors in the configuration will be reported 
during the sync process.

=head1 EXAMPLES

=head2 BASIC WORKFLOW

B<cobbler check>

B<cobbler distro add --name=rhel4u3 --kernel=/dir1/vmlinuz --initrd=/dir1/initrd.img>

B<cobbler distro add --name=fc5 --kernel=/dir2/vmlinuz --initrd=/dir2/initrd.img>

B<cobbler profile add --name=fc5webservers --distro=fc5-i386 --kickstart=/dir4/kick.ks --kopts="something_to_make_my_gfx_card_work=42,some_other_parameter=foo">

B<cobbler profile add --name=rhel4u3dbservers --distro=rhel4u3 --kickstart=/dir5/kick.ks>

B<cobbler system add --name=AA:BB:CC:DD:EE:FF --profile=fc5-webservers>

B<cobbler system add --name=AA:BB:CC:DD:EE:FE --profile=rhel4u3-dbservers>

B<cobbler list>

B<cobbler sync>

=head2 XEN

For Xen, be sure the distro uses a Xen kernel and initrd:

B<cobbler distro add --name=fc5xen --kernel=/dir3/vmlinuz --initrd=/dir6/initrd.img>

Specify reasonable values for the Xen image size (in GB) and RAM requirements:

B<cobbler profile add --name=xenwebservers --distro=fc5xen --kickstart=/dir7/kick.ks --xen-file-size=10 --xen-ram=512>

And define systems (if desired) using MAC addresses, not IP's or hostnames:

B<cobbler system add --name=AA:BB:CC:DD:EE:FE --profile=xenwebservers>

=head1 ADVANCED TOPICS

=head2 KICKSTART TEMPLATING

The --ksmeta options above require more explanation.

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".

To apply these changes, "cobbler sync" must be run to generate custom kickstarts for each profile/system.

For NFS and HTTP 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. 

=head2 DHCP CONFIGURATION MANAGEMENT

By default, cobbler does not touch dhcpd.conf and leaves configuration
of it up to the user.  If manage_dhcp is set to 1 in /var/lib/cobbler/settings,
this changes, and cobbler *will* write a dhcp.conf file.  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 this flag is set, it enables two things:
(A) relatively seamless mixing of Itanium and x86/x86_64 machines in a PXE environment
(B) pinning dhcp hostnames to MAC addresses automatically.

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.

Itanium systems names also need to be specified by the MAC address, and their distribution needs to be created with the "--arch=ia64" parameter.

The dhcpd.conf file will be updated each time "cobbler sync" is run.

=head2 ENCHANT

While the normal provisioning procedure is either to PXE bare-metal, or use koan to do something else (kickstart an existing system or deploy Xen), cobbler contains yet another option, called "enchant".  

Enchant takes a system configuration that has already been defined (be sure to run "cobbler sync" before using "cobbler enchant") and applies it to a remote system that may not have koan installed.  This is all done from the cobbler server using SSH.  The remote system will reboot prior to configuring the bootloader to kickstart.

Running "enchant" will replace the operating system of the target machine, so use it with caution.

Usage:  B<cobbler system enchant --name=<ip|hostname> [--password=<string>]>

=head2 IMPORTING TREES

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.

NOTE: The mirror or directory tree must have the basic directory tree layout as a Fedora or Centos mirror normally looks, including directories named things like "pxeboot" or "xen", "i386" or "x86_64", and so forth.  

When importing a rsync mirror, cobbler can try to detect the distribution type and automatically assign kickstarts.  This autodetection is rather primative but can improve as community users contribute kickstarts.  If cobbler is able to guess the architecture, 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.

If a mirror updated with rsync changes, running the "update.sh" script created in /var/www/cobbler/localmirror/<mirrorname> will update the files and the cobbler metadata appropriately.  

Usage: B<cobbler import --path=<path>>

Usage; B<cobbler import --mirror=<rsync_url> --mirror-name=<string>>

Example:  B<cobbler import --mirror=rsync://mirror.linux.duke.edu/fedora-linux-core/ --mirror-name=fedora>

Once imported, run a "cobbler list" to see what you've added.

"Cobbler sync" must still be run after an import to get the system ready to provision what was just imported.

=head2 TWEAKING

Enterprising users can edit the files in /var/lib/cobbler directly versus using the command line.  The repair
mechanism for user error here is to delete the files in /var/lib/cobbler.  There are also a few configuration
variables in /etc/cobbler.conf

=head2 API

Cobbler also makes itself available as a Python API for use by higher level management software.

=head1 EXIT_STATUS

cobbler's command line returns a zero for success and non-zero for failure.

=head1 AUTHOR

Michael DeHaan <mdehaan@redhat.com>