=head1 NAME

cobbler is a command line tool for simplified configuration of a provisioning server.  It supports provisioning via PXE, Xen, and re-provisioning an existing Linux system via a method called "auto-kickstarting".  The last two modes require usage of a program called 'koan' on the remote system.

=head1 SYNOPSIS

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

=head1 DESCRIPTION

Manual configuration of a PXE boot server usually involves setting up a tftpd server, a dhcpd server, syslinux, and creating semi-complex configuration file trees.

Cobbler makes these things faster, simpler, and more flexible.  It also enables a tool named 'koan', which can quickly provision new Xen instances, as well as amorph an existing machine into a new system (destructively), using a feature known as "auto-kickstarting" -- replacing the kernel/initrd pair of a current system, and rebooting so that it turns into something else.

=head1 INSTRUCTIONS FOR PXE

B<before starting...>

An admin should first install dhcpd, tftpd, and httpd.  Kickstarts files can also be downloaded over NFS and FTP (meaning installs of an FTP or NFS server may be warranted), but these modes of delivery are optional.  NFS is a common way of serving kickstart trees, however.

   yum install dhcp tftp-server syslinux
   ...
   vi /etc/dhcpd.conf

B<cobbler check>

This verifies that prerequisites are properly installed and configured.
Any problems should be corrected, with the potential exception of DHCP related warnings.

In the case of the DHCP server being on another machine, the "next-server" field in dhcpd.conf on that machine should be set to the IP of the boot server and "filename" field set to "pxelinux.0".  In this case, DHCP errors coming from "cobbler check" should be ignored.

B<cobbler distro add --name=<string> --kernel=<path> --initrd=<path> [--kopts=<string>]>

Cobbler works in terms of distros, profiles, and systems.  All three must define to get a working PXE configuration.  "cobbler distro add" defines a distribution.  Minimally, this is a named set (for instance, 'fc5-i386') of an initrd and a kernel.  Kernel options from /var/lib/cobbler/settings can be overriden here by specifying a comma seperated list of key=value pairs.

The kernel/initrd pairs used for "distro add" probably should be those that are used to boot Anaconda, but there are plenty of other uses.  If Xen provisioning is desired, a Xen dom0 kernel and the matching Anaconda initrd is required.

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

"cobbler profile add" defines a named provisioning profile, which must reference an already created distribution.  Optional parameters can specify kickstart information or Xen parameters.  Kickstarts are almost always desired, and can be nfs://, http://, or ftp:// -- or an absolute path.  For file paths, cobbler will copy the kickstarts and serve them up as http -- so having servable kickstart paths as parameters to "cobbler profile add" is not required.  In fact, it's probably a good idea to leave the kickstarts as absolute paths to avoid having yet another resource to manage.

For Xen parameters, koan may interpret some parameters as hints, not absolutes, if it has to resolve conflicts.  All of these Xen parameters are optional, though as many as possible should be specified to avoid the risk koan making it's own decisions when run on the target dom0.  See the documentation for koan for more details.

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

Correlates a system name (an IP, hostname, or MAC address of a bare-metal system or a Xen dom0) with an already created profile.  For koan (the tool used for Xen and auto-kickstart deployment), system configurations are *not* used -- system information is only used for PXE.

=head1 DISPLAYING THE CONFIGURATION

B<cobbler list>

Prints the current cobbler configuration for systems, profiles, and groups.  This can be used to review any data that has been added to the configuration.  To correct information, use add (to overwrite an existing entry) or remove subcommands.

=head1 DELETING ENTRIES

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

=head1 APPLYING CONFIGURATIONS

B<cobbler sync [--dryrun]>

Configurations are saved in /var/cobbler/cobbler.conf and are not applied until 'cobbler sync' is run.  A '--dryrun' option is available for the paranoid.

=head1 PXE EXAMPLE

It is easier to understand cobbler once having gone through some examples.

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=http://192.168.1.10/blah/fc5-webservers.ks --kopts="something_to_make_my_gfx_card_work=42,some_other_parameter=foo">

B<cobbler profile add --name=rhel4u3dbservers --distro=rhel4u3 --kickstart=http://192.168.1.10/blah/rhel4u3-dbservers.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>

=head1 XEN EXAMPLE

TBA

=head1 CONFIGURATION FILES

The current cobbler configuration files are kept under /var/lib/cobbler.  The files are reasonably-human editable YAML and will regenerate themselves if they don't exist.  If one is broken during hand-editing, it should be manually deleted.

No changes are ever applied to the provisioning state unless 'cobbler sync' is run, as cobbler contains no daemon process.  It exists to build out information under the /tftpboot directory.

=head1 EXIT_STATUS

cobbler returns a zero for success and non-zero for failure.

=head1 AUTHOR

Michael DeHaan <mdehaan@redhat.com>