2.2.3. Install on bare metal using PXE boot and Ansible

This chapter explains how to deploy Turbo Router on a set of physical machines via PXE boot and make them available for later customization with Ansible.

You need to use the iso file with a deployment infrastructure enabling PXE boot by providing DHCP, TFTP, DNS and HTTP services.

If you don’t have such an infrastructure already, you can Install a PXE server. When you’re done, you can Configure the PXE server and Deploy Turbo Router on servers.

Install a PXE server

The following chapter describes the installation and the configuration of required packages on an Ubuntu 16.04 server to provide DHCP, DNS, TFTP and HTTP services for PXE boot.

First install required packages as root:

# apt-get update
# apt-get install -y apache2 apache2-bin apache2-data apache2-utils dnsmasq \
   dnsmasq-base grub-common grub-pc grub-pc-bin grub2-common

Configure the network interface that will answer DHCP requests in /etc/network/interfaces (adapt address and netmask to your environment):

auto eth1
iface eth1 inet static

And bring this interface up:

# ifup eth1

Then configure dnsmasq to provide DHCP, DNS and TFTP services for your network. Edit /etc/dnsmasq.conf with the following content:

# vi /etc/dnsmasq.conf
# Listening interfaces
# DNS configuration
# DHCP configuration
# TFTP configuration

In this configuration file, adapt the following options according to your environment:

  • interface: listen only to given interface. Repeat this line for each listening interface.
  • domain: the DNS domain that the target servers will belong to. This option makes dnsmasq return this domain to DHCP clients which request it and make it provide DNS resolution for this name.
  • dhcp-range: specify the IP address range that will be offered to DHCP clients. It lists the start and the end addresses and the default lease time
  • dhcp-host: specific configuration for given hosts. The server with the given MAC address will be offered the listed hostname and IP address. The fourth part is the optional lease time that overrides the default one. The hostname will be known from the DNS service. Repeat this line for each server that needs a specific configuration
  • tftp-root: the directory on the PXE server from which to server TFTP requests.

Create the root directory of TFTP server:

# grub-mknetdir --net-directory=/var/lib/tftpboot

Then restart dnsmasq service:

# systemctl restart dnsmasq

Finally configure the apache2 HTTP server. Enable the URL rewriting module:

# a2enmod rewrite

Then edit the default configuration file in /etc/apache2/sites-available/000-default.conf:

<VirtualHost *:80>
        ServerAdmin webmaster@localhost
        DocumentRoot /var/www/html
        ErrorLog ${APACHE_LOG_DIR}/error.log
        CustomLog ${APACHE_LOG_DIR}/access.log combined
        RewriteEngine On
        RewriteRule ^/cloud-init/(.*) /%{REMOTE_ADDR}/$1

Adapt the following configuration directives to your environment:

  • ServerAdmin: email of the administrator of this HTTP server.
  • DocumentRoot: the directory on this server from which to server HTTP requests

Then restart apache2 server:

# systemctl restart apache2

You can then Configure the PXE server with the delivered content.

Configure the PXE server

This chapter describes how to use the delivered Turbo Router content and the PXE server together to finalize the PXE infrastructure.

In the following document, we will use $HTTP_DIR and $TFTP_DIR to refer to the directory from which HTTP and TFTP requests are served.

First modify the /var/lib/tftpboot/boot/grub/grub.cfg that will be retrieved by servers performing a PXE boot:

# vi /var/lib/tftpboot/boot/grub/grub.cfg
set timeout=5
menuentry 'Turbo Router network installer' {
        set root='(pxe)'
        set kernel_image="/vmlinuz"
        set ramdisk="/initrd.img"
        set boot_opts="ro rd.debug console=tty1 fsck.mode=skip"
        set boot_opts="$boot_opts BOOTIF=01-$net_default_mac boot=live nonetworking console=ttyS0,115200n8 splash"
        set boot_opts="$boot_opts live-media-path=/iso/"
        set boot_opts="$boot_opts persistence persistence-storage=directory,filesystem persistence-path=/iso/ persistence-label=ramdisk_Data"
        set boot_opts="$boot_opts fetch=http://$pxe_default_server/turbo.iso ds=nocloud-net;s=http://$pxe_default_server/cloud-init/"
        echo "Boot options: $boot_opts"
        echo "Loading kernel image $kernel_image ..."
        linux $kernel_image $boot_opts
        initrd $ramdisk

In this file the important parts are:

  • kernel_image: the path relative to the root of the TFTP server where the client will find its kernel file
  • ramdisk: the path relative to the root of the TFTP server where the client will find its initrd file
  • console: where to display boot logs. Repeat for each serial access either physical of virtual
  • fetch: the URL where the Turbo Router iso will be downloaded. $pxe_default_server is automatically replaced by the IP address of the PXE server
  • ds=nocloud-net;s: the URL where the Turbo Router will find its cloud-init configuration. $pxe_default_server is automatically replaced by the IP address of the PXE server

Deploy delivered files according to this configuration file:

# cp vmlinuz initrd.img $TFTP_DIR/
# cp 6wind-turbo-*-<arch>-<version>.iso $HTTP_DIR/turbo.iso

Then prepare per-server cloud-init configurations. The previous configuration will make deployed servers retrieve their respective cloud-init meta-data and user-data configurations from $HTTP_DIR/<client_IP>/.

As an example, for a server host1 that will get IP address <client_IP> from the DHCP server, we prepare its cloud-init configuration as the following:

# mkdir $HTTP_DIR/<client_IP>/

# cat > $HTTP_DIR/<client_IP>/meta-data <<EOF
instance-id: host1
local-hostname: host1

# cat > $HTTP_DIR/<client_IP>/user-data <<EOF

 - ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBI6YcZ4KhPAFIV2C9S/6g9P7e7pemCfZRUl3Mo0xwMkTay5OTD5uS9IKaoOgUNJvMnu7yM380mxHDWPnqatYFEo= root@pxeserver

 - '/usr/bin/wget "" -O /etc/sysrepo/data/vrouter.startup'
 - '/usr/bin/install.sh -r -d /dev/sda'
 - '/sbin/reboot'

# cat > $HTTP_DIR/<client_IP>/vrouter.startup <<EOF
  "vrouter:config": {
    "vrouter-system:system": {
      "hostname": "host1"
    "vrf": [
        "name": "main",
        "vrouter-interface:interface": {
          "physical": [
              "name": "mgmt0",
              "port": "pci-b0s3",
              "enabled": true,
              "ipv4": {
                "enabled": true,
                "dhcp": {
                  "enabled": true,
                  "timeout": 60,
                  "retry": 300,
                  "select-timeout": 0,
                  "reboot": 10,
                  "initial-interval": 10,
                  "dhcp-lease-time": 7200,
                  "request": [
              "ipv6": {
                "enabled": true
              "ethernet": {
                "auto-negotiate": true

The user-data aims at setting an authorized public ssh key for root user, retrieving a startup Turbo Router configuration (optional) from the HTTP server, and then performing the installation on the given /dev/sda disk. After installation the server automatically reboots. It can then be reached with the matching private SSH key.

You can now Deploy Turbo Router on servers.

Deploy Turbo Router on servers

Make sure to configure DHCP, TFTP and HTTP servers to offer respectively an IP address and turbo installation files to the target servers.

You servers must be configured to boot in BIOS mode, first on the hard drive selected for installation and then with a PXE boot on the network interface.

With an IPMI request, configure your server to perform a PXE installation on next boot only then reboot:

# ipmitool -I lanplus -H <BMC_IP> -U <user> chassis bootdev pxe
# ipmitool -I lanplus -H <BMC_IP> -U <user> chassis power reset

The target server will perform the following tasks:

  • issue a DHCP request to retrieve an IP address, a hostname and the TFTP server address
  • fetch the grub bootloader and its configuration file from TFTP server
  • boot the default grub entry, that means:
    • fetch the kernel and intird images and boot them
    • fetch the Turbo Router iso and use it as root filesystem
  • retrieve cloud-init configuration and apply it, that means:
    • set an authorized SSH key for root account
    • fetch and apply the startup configuration of Turbo Router
    • perform the installation to the target disk device
    • reboot

On reboot, the normal boot sequence of the server will boot on the freshly installed hard drive.

The server will use its startup configuration to configure its first interface with DHCP. It can then be reached with the SSH key to perform Ansible deployment tasks.

The next step is the license file installation.