Cobbler

Introduction

Uyuni features the Cobbler server, which allows administrators to centralize system installation and provisioning infrastructure. Cobbler is an installation server that provides various methods of performing unattended system installations. It can be used on server, workstation, or guest systems, in full or para-virtualized environments.

Cobbler offers several tools for pre-installation guidance, automated installation file management, installation environment management, and more. This section explains some of the supported features of Cobbler, including:

  • Installation environment analysis using the cobbler check command

  • Multi-site installation server configuration using the cobbler replicate command

  • Virtual machine guest installation automation with the koan client-side tool

  • Building installation ISOs with PXE-like menus using the cobbler buildiso command (for Uyuni systems with x86_64 architecture)

For more detailed Cobbler documentation, see http://cobbler.github.io/manuals/.

Supported Cobbler Functions

SUSE only support those Cobbler functions that are either listed within our formal documentation or available via the web interface and API.

Cobbler and SUSE Manager for Retail

Cobbler is not currently supported within SUSE Manager for Retail environments. If you intend to use your installation with SUSE Manager for Retail formulas, do not configure Cobbler.

Cobbler Requirements

To use Cobbler for system installation with PXE, you will require a TFTP server. Uyuni installs a TFTP server by default. To PXE boot systems, you will require a DHCP server, or have access to a network DHCP server. Edit the /etc/dhcp.conf configuration file to change next-server to the hostname or IP address of your Cobbler server.

Cobbler requires an open HTTP port to synchronize data between the Server and the Proxy. By default, Cobbler uses port 80, but you can configure it to use port 443 instead if that suits your environment.

Correct Hostname Configuration

Cobbler uses hostnames as a unique key for each system. If you are using the pxe-default-image to onboard bare metal systems, make sure every system has a unique hostname. Non-unique hostnames will cause all systems with the same hostname to have the configuration filess overwritten when a provisioning profile is assigned.

Configuring Cobbler with /etc/cobbler/settings

Cobbler configuration is primarily managed using the /etc/cobbler/settings file. Cobbler will run with the default settings unchanged. All configurable settings are explained in detail in the /etc/cobbler/settings file, including information on each setting, and recommendations.

Supported Languages

If Uyuni complains that language en was not found within the list of supported languages available at /usr/share/YaST2/data/languages, remove the lang parameter in the /etc/cobbler/settings file, or add a valid parameter such as en_US.

For more on this topic, see https://www.suse.com/support/kb/doc?id=7018334.

Cobbler and DHCP

Cobbler uses DHCP to automate bare metal installations from a PXE boot server. You must have administrative access to the network’s DHCP server, or be able to configure DHCP directly on the the Cobbler server.

Configuring an Existing DHCP Server

If you have existing DHCP server, you will need to edit the DHCP configuration file so that it points to the Cobbler server and PXE boot image.

As root on the DHCP server, edit the /etc/dhcpd.conf file and append a new class with options for performing PXE boot installation. For example:

allow booting;
allow bootp; (1)
class "PXE" (2)
{match if substring(option vendor-class-identifier, 0, 9) = "PXEClient"; (3)
next-server 192.168.2.1; (4)
filename "pxelinux.0";} (5)
1 Enable network booting with the bootp protocol.
2 Create a class called PXE.
3 A system configured to have PXE first in its boot priority identifies itself as PXEClient.
4 As a result, the DHCP server directs the system to the Cobbler server at 192.168.2.1.
5 The DHCP server retrieves the pxelinux.0bootloader file.

Setting up PXE Boot in KVM

It is possible to set up PXE booting in KVM, however we do not recommend you use this method for production systems.

Edit the network XML description with virsh:

  1. Produce an XML dump of the current description:

    virsh net-dumpxml --inactive network > network.xml
  2. Open the XML dump file at network.xml with a text editor and add a bootp parameter within the <dhcp>` element:

    <bootp file='/pxelinux.0' server='192.168.100.153'/>
  3. Install the updated description:

    virsh net-define network.xml

Alternatively, use the net-edit subcommand, which will also perform some error checking.

Example 1. Minimal Network XML Description for KVM
<network>
  <name>default</name>
  <uuid>1da84185-31b5-4c8b-9ee2-a7f5ba39a7ee</uuid>
  <forward mode='nat'>
    <nat>
      <port start='1024' end='65535'/>
    </nat>
  </forward>
  <bridge name='virbr0' stp='on' delay='0'/>
  <mac address='52:54:00:29:59:18'/>
  <domain name='default'/>
  <ip address='192.168.100.1' netmask='255.255.255.0'>
    <dhcp>
      <range start='192.168.100.128' end='192.168.100.254'/>
      <bootp file='/pxelinux.0' server='192.168.100.153'/> (1)
</dhcp>
  </ip>
</network>
1 bootp statement that directs to the PXE server.

TFTP

Uyuni uses the atftpd daemon, but it can also use TFTP. The atftpd daemon is the recommended method for PXE serviices, and is installed by default. Usually, you do not have to change its configuration, but if you have to, use the YaST Services Manager.

Before TFTP can serve the pxelinux.0 boot image, you must start the tftp service. Start YaST and use System  Services Manager to configure the tftpd daemon.

Syncing TFTP Contents to Uyuni Proxies

It is possible to synchronize Cobbler-generated TFTP contents to Uyuni proxies to perform PXE booting using proxies.

Installation

On the Uyuni Server as the root user, install the susemanager-tftpsync package:

zypper install susemanager-tftpsync

On the SUSE Manager Proxy systems as the root user , install the susemanager-tftpsync-recv package:

zypper install susemanager-tftpsync-recv

Configuring SUSE Manager Proxy

Execute configure-tftpsync.sh on the SUSE Manager Proxy systems.

This setup script asks for hostnames and IP addresses of the Uyuni server and the proxy. Additionally, it asks for the tftpboot directory on the proxy. For more information, see the output of configure-tftpsync.sh --help.

Configuring Uyuni Server

As the root user, execute configure-tftpsync.sh on Uyuni Server:

configure-tftpsync.sh proxy1.example.com proxy2.example.com

Execute cobbler sync to initially push the files to the proxy systems. This will succeed if all listed proxies are properly configured.

Changing the List of Proxy Systems

You can call configure-tftpsync.sh to change the list of proxy systems. You must always provide the full list of proxy systems.

Reinstalling a Configured Proxy

If you reinstall an already configured proxy and want to push all the files again you must remove the cache file at /var/lib/cobbler/pxe_cache.json before you can call cobbler sync again.

Requirements

The Uyuni Server must be able to access the SUSE Manager Proxy systems directly. You cannot push using a proxy.

Syncing and Starting the Cobbler Service

Before starting the Cobbler service, run a check to make sure that all the prerequisites are configured according to your requirements using the cobbler check command.

If configuration is correct, start the Uyuni server with this command:

/usr/sbin/spacewalk-service start

Do not start or stop the cobblerd service independent of the Uyuni service. Doing so may cause errors and other issues.

Always use /usr/sbin/spacewalk-service to start or stop Uyuni.

Using Cobbler Templates

The Uyuni web interface allows you to create variables for use with Kickstart distributions and profiles. For more information on creating Kickstart profile variables, refer to reference:systems/autoinst-distributions.adoc.

Kickstart variables are part of an infrastructure change in Uyuni to support templating in Kickstart files. Kickstart templates are files that describe how to build Kickstart files, rather than creating specific Kickstarts. The templates are shared by various profiles and systems that have their own variables and corresponding values. These variables modify the templates and a template engine parses the template and variable data into a usable Kickstart file. Cobbler uses an advanced template engine called Cheetah that provides support for templates, variables, and snippets.

Advantages of using templates include:

  • Robust features that allow administrators to create and manage large amounts of profiles or systems without duplication of effort or manually creating Kickstarts for every unique situation.

  • While templates can become complex and involve loops, conditionals and other enhanced features and syntax, you can also create simpler Kickstart files without such complexity.

Using Templates

Kickstart templates can have static values for certain common items such as PXE image file names, subnet addresses, and common paths such as /etc/sysconfig/network-scripts/. However, templates differ from standard Kickstart files in their use of variables.

For example, a standard Kickstart file may have a networking section similar to this:

network --device=eth0 --bootproto=static --ip=192.168.100.24 \
  --netmask=255.255.255.0 --gateway=192.168.100.1 --nameserver=192.168.100.2

In a Kickstart template file, the networking section would look like this instead:

network --device=$net_dev --bootproto=static --ip=$ip_addr \
  --netmask=255.255.255.0 --gateway=$my_gateway --nameserver=$my_nameserver

These variables are substituted with the values set in your Kickstart profile variables or in your system detail variables. If the same variable is defined in both the profile and the system detail, then the system detail variable takes precedence.

The template for the autoinstallation has syntax rules which relies on punctuation symbols. To avoid clashes, they need to be properly treated.

In case the autoinstallation scenario contains any shell script using variables like $(example), its content should be escaped by using the backslash symbol: \$(example).

If the variable named example is defined in the autoinstallation snippet, the templating engine will evaluate $example with its content. If there is no such variable, the content will be left unchanged. Escaping the $ symbol will prevent the templating engine from evaluating the symbol as an internal variable. Long scripts or strings can be escaped by wrapping them with the \#raw and \#end raw directives. For example:

#raw
#!/bin/bash
for i in {0..2}; do
 echo "$i - Hello World!"
done
#end raw

Also, pay attention to scenarios like this:

#start some section (this is a comment)
echo "Hello, world"
#end some section (this is a comment)

Any line with a # symbol followed by a whitespace is treated as a comment and is therefore not evaluated.

For more information about Kickstart templates, refer to the Cobbler project page at:

Kickstart Snippets

If you have common configurations across all Kickstart templates and profiles, you can use the Snippets feature of Cobbler to take advantage of code reuse.

Kickstart snippets are sections of Kickstart code that can be called by a $SNIPPET() function that will be parsed by Cobbler and substituted with the contents of the snippet.

For example, you might have a common hard drive partition configuration for all servers, such as:

clearpart --all
part /boot --fstype ext3 --size=150 --asprimary
part / --fstype ext3 --size=40000 --asprimary
part swap --recommended

part pv.00 --size=1 --grow

volgroup vg00 pv.00
logvol /var --name=var vgname=vg00 --fstype ext3 --size=5000

Save this snippet of the configuration to a file like my_partition and place the file in /var/lib/cobbler/snippets/, where Cobbler can access it.

Use the snippet by calling the $SNIPPET() function in your Kickstart templates. For example:

$SNIPPET('my_partition')

Wherever you invoke that function, the Cheetah parser will substitute the function with the snippet of code contained in the my_partition file.

Building ISOs with Cobbler

Some environments might lack PXE support. The Cobbler buildiso command creates a ISO boot image containing a set of distributions and kernels, and a menu similar to PXE network installations. Define the name and output location of the boot ISO using the --iso option.

ISO Build Directory

Depending on Cobbler-related systemd settings (see /usr/lib/systemd/system/cobblerd.service) writing ISO images to public tmp directories will not work.

cobbler buildiso --iso=/path/to/boot.iso

The boot ISO includes all profiles and systems by default. Limit these profiles and systems using the --profiles and --systems options.

cobbler buildiso --systems="system1,system2,system3" \
  --profiles="profile1,profile2,profile3"

Building ISOs with the cobbler buildiso command is supported for all architectures except the ibmz architecture.

Bare Metal Provisioning

Systems that have not yet been provisioned are called bare metal systems. You can provision bare metal systems using Cobbler. Once a bare metal system has been provisioned in this way, it will appear in the Systems list, where you can perform regular provisioning with autoinstallation, for a completely unattended installation.

Bare Metal Provisioning System Requirements

To successfully provision a bare metal system, you will require a fully patched Uyuni server, version 2.1 or higher.

The system to be provisioned must have x86_64 architecture, with at least 2 GB RAM, and be capable of PXE booting.

The server uses TFTP to provision the bare metal client, so the appropriate port and networks must be configured correctly in order for provisioning to be successful. In particular, ensure that you have a DHCP server, and have set the next-server parameter to the Uyuni server IP address or hostname.

Enabling Bare Metal Systems Management

Bare metal systems management can be enabled or disabled in the Web UI by clicking Admin  SUSE Manager Configuration  Bare-metal systems.

New systems are added to the organization of the administrator who enabled the bare metal systems management feature. To change the organization, log in as an Administrator of the required organization, and re-enable the feature.

Once the feature has been enabled, any bare metal system connected to the server network will be automatically added to the organization when it is powered on. The process can take a few minutes, and the system will automatically shut down once it is complete. After the reboot, the system will appear in the Systems list. Click on the name of the system to see basic information, or go to the Properties, Notes, and Hardware tabs for more details. You can migrate bare metal systems to other organizations if required, using the Migrate tab.

Provisioning Bare Metal Systems

Provisioning bare metal systems is similar to provisioning other systems, and can be done using the Provisioning tab. However, you will not be able to schedule provisioning, it will happen automatically as soon as the system is configured and powered on.

Bare Metal and System Set Manager

System Set Manager can be used with bare metal systems, although not all features will be available, because bare metal systems do not have an operating system installed. This limitation also applies to mixed sets that contain bare metal systems; all features will be re-enabled if the bare metal systems are removed from the set.

Troubleshooting Bare Metal Systems

If a bare metal system on the network is not automatically added to the Systems list, check these things first:

  • You must have the pxe-default-image package installed.

  • File paths and parameters must be configured correctly. Check that the vmlinuz0 and initrd0.img files, which are provided by pxe-default-image, are in the locations specified in the rhn.conf configuration file.

  • Ensure the networking equipment connecting the bare metal system to the Uyuni server is working correctly, and that you can reach the Uyuni server IP address from the server.

  • The bare metal system to be provisioned must have PXE booting enabled in the boot sequence, and must not be attempting to boot an operating system.

  • The DHCP server must be responding to DHCP requests during boot. Check the PXE boot messages to ensure that:

    • the DHCP server is assigning the expected IP address

    • the DHCP server is assigning the the Uyuni server IP address as next-server for booting.

  • Ensure Cobbler is running, and that the Discovery feature is enabled.

If you see a blue Cobbler menu shortly after booting, discovery has started. If it does not complete successfully, temporarily disable automatic shutdown in order to help diagnose the problem. To disable automatic shutdown:

  1. Select pxe-default-profile in the Cobbler menu with the arrow keys, and press the Tab key before the timer expires.

  2. Add the kernel boot parameter spacewalk-finally=running using the integrated editor, and press Enter to continue booting.

  3. Enter a shell with the username root and password linux to continue debugging.

Duplicate profiles

Due to a technical limitation, it is not possible to reliably distinguish a new bare metal system from a system that has previously been discovered. Therefore, we recommended that you do not power on bare metal systems multiple times, as this will result in duplicate profiles.