Foreman

{{toc}}

h1. How do I use unattended installations (Kickstart, jumpstart, preseed)?

Foreman manages the host creation process by controlling a host's DHCP, DNS, TFTP boot file and the puppet node classification. This is whole process is handled in the core foreman program and in several satellite proxies running at various locations within the organization. More details can be found on the [[Foreman_Architecture]] page. 

Foreman automates network boot processes using PXEboot, gPXE, (or native Solaris net:dhcp in the future.) It also manages the host's DHCP and DNS entries as of version 0.2.

h2. TFTP

Foreman has currently limited support for TFTP- that means it require the TFTP server to be accessible via the local file system.

future versions of Foreman would allow remote TFTP servers as well.

make sure you add into your config/settings.yml

<pre> :tftppath: /var/lib/tftpboot/pxelinux.cfg</pre>

replace the value with your actual TFTP directory and ensure that the *user which executes Foreman  have write access*.

h3. How does Foreman manages TFTP?

When clicking on the Build button (in the host list), Foreman would generate a link which will be automatically read by pxelinux,

This link would point to a predefined syslinux(pxelinux) boot file which would be based on the Operating System used.

Note:- if you require the link to point to different PXE files based on serial console variables, adding '0,19200n8' in the serial field of a host will create a different symbolic link.

after a successful OS installation, that link will be removed, and your default PXE settings will be served.

The idea behind it is to set the boot order on each host to always boot from network, and then change the settings via Foreman.

This avoids the need to press F12 on each machine just to reinstall it, Clicking on Build in Foreman will trigger a host re-installation upon the next server reboot if default boot order is PXE.

*+Examples+*:

*CentOS 5 32bit*:

<pre>default linux

label linux

kernel boot/centos-5-32.vmlinuz

append initrd=boot/centos-5-32.initrd.img ks=http://foremanhost/unattended/kickstart ksdevice=bootif network kssendmac

</pre>

PXEboot kernels for CentOS:

* "CentOS 4 32bit":http://mirror.centos.org/centos/4/os/i386/images/pxeboot/

* "CentOS 4 64bit":http://mirror.centos.org/centos/4/os/x86_64/images/pxeboot/

* "CentOS 5 32bit":http://mirror.centos.org/centos/5/os/i386/images/pxeboot/

* "CentOS 5 64bit":http://mirror.centos.org/centos/5/os/x86_64/images/pxeboot/

PXEboot kernels for Fedora:

* "Fedora 12 32bit":http://download.fedoraproject.org/pub/fedora/linux/releases/12/Fedora/i386/os/images/pxeboot/

* "Fedora 12 64bit":http://download.fedoraproject.org/pub/fedora/linux/releases/12/Fedora/x86_64/os/images/pxeboot/

*Ubuntu 10.04 64bit*:

<pre>default preseed

label preseed

kernel ubuntu/lucid/x86_64/linux

append initrd=ubuntu/lucid/x86_64/initrd.gz ramdisk_size=10800 root=/dev/rd/0 rw auto interface=auto url=http://foreman.example.net/unattended/preseed hostname=unassigned-hostname locale=en_US console-setup/ask_detect=false console-setup/layout=USA console-setup/variant=USA DEBCONF_PRIORITY=critical</pre>

Tweakable options:

* @interface@: the network interface on which the DHCP client should run. Set to @auto@ for automatic detection or the specific interface (@eth0@, @eth1@, ...) if it doesn't work for you.

* @url@: The URL to the preseed file provided by Foreman.

* @locale@: The locale used during the installation.

* @log_host=loghost.example.com@ and @log_port=1234@ (if the syslogd doesn't listen on @514/udp@) if there is a central log host in your network.

Netboot kernels for Debian and Ubuntu:

* "Debian 5.0 (Lenny) 32bit":http://ftp.debian.org/debian/dists/lenny/main/installer-i386/current/images/netboot/debian-installer/i386/

* "Debian 5.0 (Lenny) 64bit":http://ftp.debian.org/debian/dists/lenny/main/installer-amd64/current/images/netboot/debian-installer/amd64/

* "Ubuntu 8.04 LTS (Hardy Heron) 32bit":http://archive.ubuntu.com/ubuntu/dists/hardy/main/installer-i386/current/images/netboot/ubuntu-installer/i386/

* "Ubuntu 8.04 LTS (Hardy Heron) 64bit":http://archive.ubuntu.com/ubuntu/dists/hardy/main/installer-amd64/current/images/netboot/ubuntu-installer/amd64/

* "Ubuntu 9.10 (Karmic Koala) 32bit":http://archive.ubuntu.com/ubuntu/dists/karmic/main/installer-i386/current/images/netboot/ubuntu-installer/i386/

* "Ubuntu 9.10 (Karmic Koala) 64bit":http://archive.ubuntu.com/ubuntu/dists/karmic/main/installer-amd64/current/images/netboot/ubuntu-installer/amd64/

* "Ubuntu 10.04 LTS (Lucid Lynx) 32bit":http://archive.ubuntu.com/ubuntu/dists/lucid/main/installer-i386/current/images/netboot/ubuntu-installer/i386/

* "Ubuntu 10.04 LTS (Lucid Lynx) 64bit":http://archive.ubuntu.com/ubuntu/dists/lucid/main/installer-amd64/current/images/netboot/ubuntu-installer/amd64/

h2. PuppetCA

Foreman will enable host autosign during provisioning time, that means, the user which executes Foreman must have:

1. write access to /etc/puppet/autosign.conf

2. sudo access to run puppetca

Once a host (which is enabled for build) is requesting a kickstart/jumpstart etc than an entry would be created in the autosign.conf file.

Each operating system will run puppetd after the OS installation but before the first reboot, this will acquire the puppet certificate, then the host will notify Foreman that it has finished the installation, and Foreman will remove the entry from the autosign file automatically.

h2. Whats inside the Kickstart / jumpstart /preseed ?

These files are all generated dynamically based on the setting of each host in Foreman, things like partition tables and root password can be unique per server.

if you want to see the kickstart/preseed etc you may use the spoof parameter, just point your browser to:

<pre>http://foremanhost:3000/unattended/kickstart?spoof=123.321.123.321</pre>

* 123.321.123.321 is the hosts IP Address (the one you want to build).

* usually you want to see the page source, the browser might display the file in html which will result in hard to read output.

* if you are using passenger please remove the ":3000" from the URL.

h2. Modifying/Creating the template

See [[TemplateWriting]]

h3. Snippets support

as of version 0.1-2 snippets support was added, for reusable code that be shared between operating systems deployments (e.g. puppet.conf).

They are pure ERB templates (same as puppet templates) and could be modified/added from the "Provisioning Templates" page.  To mark a template a snippet, simply tick the 'snippet' box for that template.

Later you can call it from the existing templates:

<pre>

<%= snippet "vmware" -%>

</pre>

h3. Dynamic disk partition

It is possible to use a script (e.g a kickstart post script) instead of a static partition table.

see [[Dynamic disk partioning]]