Linux Certif

Toute la documentation sur la certification Linux LPI

cobbler

NAME

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.

SYNOPSIS

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

DESCRIPTION

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

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.

Repositories contain yum mirror information. Using cobbler to mirror repositories is an optional/advanced feature and is covered further down in this manpage.

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.

SEE ALSO

For help in building kickstarts, try using the ``system-config-kickstart'' tool, or install a new system and look at the /root/anaconda-ks.cfg file left over from the installer. General kickstart questions can also be asked at kickstart-list@redhat.com. Cobbler ships some kickstart templates in /etc/cobbler that may also prove helpful.

COBBLER USAGE

SETUP

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.

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.

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.

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

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.

ADDING A DISTRIBUTION

This first step towards configurating what you want to provision is to add a distribution to the cobbler's configuration.

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.

The manual distro add command is:

cobbler distro add --name=string --kernel=path --initrd=path [--kopts=string] [--ksmeta=string] [--arch=x86|x86_64|ia64] [--breed=redhat|suse]

name

a string identifying the distribution, this should be something like ``rhel4''.

kernel

an absolute filesystem path to a kernel image

initrd

an absolute filesystem path to a initrd image

kopts

(optional) sets kernel command-line arguments that the distro, and profiles/systems dependant on it, will use.

Example: --kopts=``foo=bar baz=3 asdf''

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.

if you don't use IA64 systems, leaving this parameter off is fine.

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.

breed

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.

ADDING A PROFILE

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.

cobbler profile add --name=string --distro=string [--kickstart=url] [--kopts=string] [--ksmeta=string] [--virt-file-size=gigabytes] [--virt-ram=megabytes]

Arguments are as listed for distributions, except for the ``arch'' parameter, and with the additions listed below:

name

a descriptive name. This could be something like ``rhel4webservers'' or ``fc6desktops''.

distro

the name of a previously defined cobbler distribution

kickstart

Local filesystem path to a kickstart file.

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.

virt-file-size

(optional) (Virt-only) how large the disk image should be in gigabytes. The default is ``5''.

virt-ram

(optional) (Virt-only) how many megabytes of RAM to consume. The default is 512 MB.

repos

(optional) a space delimited list of all the repos (created with ``cobbler repo add'' and ``cobbler reposync'') that this profile can make use of during kickstart installation. For example, an example might be --repos=``fc6i386updates fc6i386extras''.

ADDING A SYSTEM

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.

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

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

name

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

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.

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.

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.

ADDING A REPOSITORY TO MIRROR

Repository mirroring allows cobbler to mirror not only install trees (``cobbler import'' does this for you) but also optional packages, 3rd party content, and even updates. Mirroring all of this content locally 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).

cobbler repo add --mirror=url --name=string [--local-filename=string]

mirror

The addresss of the yum mirror. This can be an rsync:// URL, an ssh location, or a http:// or ftp:// mirror location.

The mirror address should specify an exact repository to mirror --- just one architecture and just one distribution. If you have a seperate repo to mirror for a different arch, add that repo seperately.

Here's an example of what looks like a good URL:

rsync://yourmirror.example.com/fedora-linux-core/updates/6/i386 (for rsync protocol) http://mirrors.kernel.org/fedora/extras/6/i386/ (for http://) user@yourmirror.example.com/fedora-linux-core/updates/6/i386 (for SSH)

Experimental support is also provided for mirroring (RHEL5) and later 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.

http://, ftp:// and rhn:// mirrors require yum-utils be installed.

name

This name is used as the save location for the mirror. If the mirror represented, say, Fedora Core 6 i386 updates, a good name would be ``fc6i386updates''. Again, be specific.

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.

See the documentation on ``cobbler profile add'' for more information.

local-filename

Local filename specifies, for kickstarts containing the template parameter ``yum_config_stanza'', what files to populate on provisioned clients in /etc/yum.repos.d.

In other words, if this value is ``foo'', the repo would be installed on provisioned clients as ``/etc/yum.repos.d/foo.repo''.

If you don't want clients to have this repo installed, don't add a name for the repo, and provisioned machines will not configure yum to know about this repo --- you can still do it manually if you choose. The repository will still be used for installation, it just won't get installed automatically in /etc/yum.repos.d on the client.

See /etc/cobbler/kickstart_fc6.ks for an example of how to employ this within a kickstart template.

rpm-list

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 intance, 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''.

This option only works for http:// and ftp:// repositories. It will be ignored for other mirror types, such as local paths and rsync:// mirrors. This option requires yum-utils be installed.

DISPLAYING CONFIGURATION ENTRIES

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.

cobbler report

cobbler distro|profile|system|repo report

cobbler list

cobbler distro|profile|system|repo list

Alternatively, you could look at the configuration files in /var/lib/cobbler to see the same information.

DELETING CONFIGURATION ENTRIES

If you want to remove a specific object, use the remove command with the name that was used to add it.

cobbler distro remove --name=string

cobbler profile remove --name=string

cobbler system remove --name=string

cobbler remove repo --name=string

EDITING

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.

cobbler distro|profile|system|repo edit --name=string [parameterlist]

COPYING

Objects can also be copied:

cobbler distro|profile|system|repo copy --name=oldname --newname=newname

RENAMING

Objects can also be renamed, as long as other objects don't reference them.

cobbler distro|profile|system|repo rename --name=oldname --newname=newname

REBUILDING CONFIGURATIONS

cobbler sync

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.

Sync should be run whenever files in /var/www/cobbler are manually edited or when making changes to kickstart files. In practice, this should not happen often, though running sync too many times does not cause any adverse effects.

If using cobbler to manage a DHCP server (see the advanced section of this manpage), sync does need to be run after systems are added to regenerate and reload the DHCP configuration.

EXAMPLES

IMPORT WORKFLOW

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.

You can use a network rsync mirror or a mounted DVD location.

cobbler check

cobbler import --mirror=rsync://yourfavoritemirror.com/foo --mirror-name=anyname

# OR

cobbler import --mirror=root@localhost:/mnt/dvd --mirror-name=anyname

# wait for mirror to rsync...

cobbler report

cobbler system add --name=default --profile=name_of_a_profile1

cobbler system add --name=AA:BB:CC:DD:EE:FF --profile=name_of_a_profile2

cobbler sync

NORMAL WORKFLOW

The following example uses a local kernel and initrd file (already downloaded), and shows how profiles would be created using two different kickstarts --- one for a web server configuration and one for a database server. Then, a machine is assigned to each profile.

cobbler check

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

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

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''

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

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

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

cobbler report

REPOSITORY MIRRORING WORKFLOW

The following example shows how to set up a repo mirror for two repositories, and create a profile that will auto install those repository configurations on provisioned systems using that profile.

cobbler check

# set up your cobbler distros here.

cobbler repo add --mirror=http://mirrors.kernel.org/fedora/core/updates/6/i386/ --name=fc6i386updates

cobbler repo add --mirror=http://mirrors.kernel.org/fedora/extras/6/i386/ --name=fc6i386extras

cobbler reposync

cobbler profile add --name=p1 --distro=existing_distro_name --kickstart=/etc/cobbler/kickstart_fc6.ks --repos=``fc6i386updates fc6i386extras''

XEN

For Virt, be sure the distro uses a Virt kernel and initrd and follow similar steps as above, adding additional parameters as desired:

cobbler distro add --name=fc5virt --kernel=/dir3/vmlinuz --initrd=/dir6/initrd.img

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

cobbler profile add --name=virtwebservers --distro=fc5virt --kickstart=/dir7/kick.ks --virt-file-size=10 --virt-ram=512

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

cobbler system add --name=AA:BB:CC:DD:EE:FE --profile=virtwebservers

ADVANCED TOPICS

PXE MENUS

Cobbler will automatically generate PXE menus for all profiles it has defined. Running ``cobbler sync'' is required to generate and update these menus.

To access the menus, type ``menu'' at the ``boot:'' prompt while a system is PXE booting. If nothing is typed, the network boot will default to a local boot. If ``menu'' is typed, the user can then choose and provision any cobbler profile the system knows about.

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.

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.

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''. (Actually $bar is also replaced, if you prefer that syntax).

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.

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 http://www.cheetahtemplate.org/learn.html

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.

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.

DHCP CONFIGURATION MANAGEMENT

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.

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.

So, if this manage_dhcp bit is enabled, the following features are enabled:

(A) pinning dhcp hostnames to MAC addresses automatically. (B) relatively seamless mixing of Itanium and x86/x86_64 machines in a PXE environment

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, and not until then, so it is important to remember to use ``cobbler sync'' when using this feature.

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 Virt), cobbler contains yet another option, called ``enchant''.

Enchant takes a configuration that has already been defined (be sure to run ``cobbler sync'' before using ``cobbler enchant'') and applies it to a remote system that might not have koan installed. Users might want to use this command to replace a server that is being repurposed, or when no PXE environment can be created.

Essentially what enchant does is allow koan to be executed remotely from the cobbler server. Running ``enchant'' in it's normal mode will replace the operating system of the target machine, so use it with caution.

Usage: cobbler enchant --address=ip|hostname --profile=string Usage: cobbler enchant --address=ip|hostname --system=string

Adding a ``--virt=yes'' to either form will provision a virtualized image rather than reprovisioning the remote machine. The default behavior is machine (not virtual) re-provisioning.

Example: cobbler enchant --virt=yes --address=192.168.10.10 --profile=fc6xen

Before using enchant, configure the location of the koan noarch RPM in /var/lib/cobbler/settings (a local path) and re-run ``cobbler sync''.

IMPORTING TREES

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.

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.

Mirrored content is saved automatically in /var/www/cobbler/ks_mirror.

Example: cobbler import --mirror=rsync://mirrorserver.example.com/path/ --name=fedora

Example2: cobbler import --mirror=root@192.168.1.10:/stuff --name=bar

Example3: cobbler import --mirror=/mnt/dvd --name=baz

Example4: cobbler import --mirror=/path/to/stuff --name=glorp

Once imported, run a ``cobbler list'' or ``cobbler report'' to see what you've added.

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.

DEFAULT PXE BOOT BEHAVIOR

What happens when PXE booting a system when cobbler has no record of the system being booted?

By default, cobbler will configure PXE to boot to the contents of /etc/cobbler/default.pxe, which (if unmodified) will just fall through to the local boot process. Administrators can modify this file if they like to change that behavior.

An easy way to specify a default cobbler profile to PXE boot is to create a system named ``default''. This will cause /etc/cobbler/default.pxe to be ignored. To restore the previous behavior do a ``cobbler system remove'' on the ``default'' system.

cobbler system add --name=default --profile=boot_this

cobbler system remove --name=default

REPO MANAGEMENT

This has already been covered a good bit in the command reference section.

Yum repository management is an optional feature, and is not required to provision through cobbler. However, if cobbler is configured to mirror certain repositories, it can then be used to associate profiles with those repositories. Systems installed under those profiles will then be autoconfigured to use these repository mirrors in /etc/yum.repos.d, and if supported (Fedora Core 6 and later) these repositories can be leveraged even within Anaconda. This can be useful if (A) you have a large install base, (B) you want fast installation and upgrades for your systems, or (C) have some extra software not in a standard repository but want provisioned systems to know about that repository.

Make sure there is plenty of space in cobbler's webdir, which defaults to /var/www/cobbler.

cobbler reposync

Cobbler reposync is the command to use to update repos as configured with ``cobbler repo add''. Mirroring can take a long time, and usage of cobbler reposync prior to cobbler sync is needed to ensure provisioned systems have the files they need to actually use the mirrored repositories. If you just add repos and never run ``cobbler reposync'', the repos will never be mirrored. This is probably a command you would want to put on a crontab, though the frequency of that crontab and where the output goes is left up to the systems administrator.

For those familiar with yum's reposync, cobbler's reposync is a wrapper around the yum command. Please use ``cobbler reposync'' to update cobbler mirrors, as reposync does not perform all required steps. Also cobbler adds support for rsync and SSH locations, where as yum's reposync only supports what yum supports (http/ftp).

Note that if a cobbler import provides enough information to use the boot server as a yum mirror for 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.

KICKSTART TRACKING

Cobbler knows how to keep track of the status of kickstarting machines.

cobbler status

Using the status command will show when cobbler thinks a machine started kickstarting and when it last requested a file. This is a good way to track machines that may have gone interactive during kickstarts. Cobbler will also make a special request in the post section of the kickstart to signal when a machine is finished kickstarting.

To use this feature, the kickstart tree files need to be served via a http://server/cblr/... URL, which happens automatically when using the ``cobbler import'' command to pull in a kickstart tree from an rsync mirror.

If kickstart trees are somewhere else, one can still benefit from the kickstart tracking feature by adding a symlink to /var/www/cobbler/localmirror/distroname will allow the kickstarts to be served through the tracking URL mentioned above. Be sure to use the http://server/cblr/ URL to point to the kickstart tree for each distro you want to track.

Note that kickstart tracking support using syslog requires an Anaconda that supports syslog forwarding. RHEL5 is good, as is FC6 and later. URL tracking currently requires python2.3 or higher on the server for the mod_python piece to work. This will likely be improved later to better support older distros acting as a cobbler server.

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 files in /etc/cobbler that can be edited.

Running ``cobbler sync'' is required to apply any changes that are made manually.

TRIGGERS

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.

API

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

EXIT_STATUS

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

MAILING LIST

Cobbler has a mailing list for user and development-related questions/comments at et-mgmt-tools@redhat.com.

AUTHOR

Michael DeHaan <mdehaan@redhat.com>