WeOS
5.29.0

# Bootstrap System Configuration with DHCP

## About

This document presents a simple use-case where DHCP is used to bootstrap the system startup configuration.

For an overview on all boot configuration options in the system refer to the following documents:

- Boot Configuration Guide.
- Bootstrap configuration over network.

## Introduction

This use-case aims to present a simple, yet effective, use-case where we obtain our startup configuration over the net using DHCP. When using DHCP for this purpose the client will request that it is provided with DHCP option 66 (TFTP Server Name) and 67 (Bootfile Name). This means that the DHCP server used must support these options.

Two different cases will be presented in this document. The major difference between these is the location of the server on the network. This is one of the strengths of using DHCP to bootstrap instead of BOOTP, is that it is possible to route the request to a server on another network from the client. This Requires a DHCP relay to be used as well.

## Case 1: Server on the Same Subnet

In the case presented here, the server managing the configuration files will be located on the same subnet as the clients.

       .--------.                 .--------.
       | DHCP-  |                 | TFTP-  | Files: h1-config.cfg
       | Server |                 | Server |        h2-config.cfg
       |        |                 |        |
       '---+----'                 '---+----'
           |.1                        |.5
           |                          |         192.168.1.0/24
       ----+----+----------------+----+-----------------------
                |                |
              .-+--.           .-+--.
              | H1 |           | H2 |
              '----'           '----'

Figure 1: Two host devices configured to bootstrap their configuration over the network using DHCP. Both the DHCP server and Tftp server are located on the same subnet.

We want host H1 to obtain its configuration based on its Client ID, while H2 should obtain it based on its mac address.

Note

This example just assumes any arbitrary TFTP server.

### Configuration

We need to configure our two hosts and DHCP server. The TFTP server configuration is assumed for this example.

#### Hosts

Configure host H1:

    H1:/#> boot
    H1:/boot/#> config-order internal:net
    H1:/boot/#> net
    H1:/boot/net/#> clientid host-h1
    H1:/boot/net/#> mode dhcp
    H1:/boot/net/#> no sync
    H1:/boot/net/#> end
    H1:/boot/#> end
    H1:/#>

Configure host H2:

    H2:/#> boot
    H2:/boot/#> config-order internal:net
    H2:/boot/#> net
    H2:/boot/net/#> no clientid
    H2:/boot/net/#> mode dhcp
    H2:/boot/net/#> no sync
    H2:/boot/net/#> end
    H2:/boot/#> end
    H2:/#>

#### DHCP Server

Configure the DHCP server to provide a specific bootfile for each of the hosts. Host H1 should match on its Client ID, host H2 should match on its MAC address:

    dhcp-server:/#> configure
    dhcp-server:/config/#> dhcp-server
    dhcp-server:/config/dhcp-server/#> tftp-server 192.168.1.5
    dhcp-server:/config/dhcp-server/#> subnet 192.168.1.0/24
    Created new DHCP server for subnet 192.168.1.0.
    dhcp-server:/config/dhcp-server/subnet-192.168.1.0/#> no pool
    Disabling dynamic IP allocation for this subnet, only static hosts allowed.
    dhcp-server:/config/dhcp-server/subnet-192.168.1.0/#>end
    dhcp-server:/config/dhcp-server/#>
    dhcp-server:/config/dhcp-server/#> host 1
    dhcp-server:/config/dhcp-server/host-1/#> address 192.168.1.10
    dhcp-server:/config/dhcp-server/host-1/#> match clientid string host-h1
    dhcp-server:/config/dhcp-server/host-1/#> bootfile h1-config.cfg
    dhcp-server:/config/dhcp-server/host-1/#> end
    dhcp-server:/config/dhcp-server/#>
    dhcp-server:/config/dhcp-server/#> host 2
    dhcp-server:/config/dhcp-server/host-2/#> address 192.168.1.20
    dhcp-server:/config/dhcp-server/host-2/#> match mac 52:54:00:12:34:56
    dhcp-server:/config/dhcp-server/host-2/#> bootfile h2-confg.cfg
    dhcp-server:/config/dhcp-server/host-2/#> end
    dhcp-server:/config/dhcp-server/#>leave
    dhcp-server:/#>

## Case 2: Server on Another Subnet

In this case the DHCP and TFTP server is located on a separate network from the hosts. In order for this particular case to work, a DHCP Relay is necessary between the hosts and the servers. This allows us to route the traffic to the correct destinations.

       .--------.                 .--------.
       | DHCP-  | GW: .2          | TFTP-  | GW: .2
       | Server |                 | Server | Files: h1-config.cfg
       |        |                 |        |        h2-config.cfg
       '---+----'                 '---+----'
           |.1                        |.5
           |                          |            10.0.0.0/24
       ----+------------+-------------+-----------------------
                        |
                        |.2
                    .---+----. vlan2
                    | DHCP-  |
                    | Relay  |
                    |        |
                    '---+----' vlan1
                        |.2
                        |                       192.168.1.0/24
       ---------+-------+--------+----------------------------
                |                |
              .-+--.           .-+--.
              | H1 |           | H2 |
              '----'           '----'

Figure 2: Two host devices configured to bootstrap their configuration over the network using DHCP. Both the DHCP server and Tftp server are located on another subnet, requiring a DHCP-Relay to be used.

The configuration of the host devices will not be any different from before, the hosts should not need to care about the setup of the rest of the network. As long as the DHCP-Relay and the servers are correctly configured everything should work as before.

For this case to work, the DHCP server must also be able to distribute a default gateway in its offer to the hosts. This is because the hosts will need a route to the relay located at 192.168.1.2. Otherwise they will not be able to fetch the their configuration files from the server, since they wont know the route to it. But this requires no additional configuration on the hosts, only the DHCP Server.

Note

Both the DHCP and TFTP server will need to have a route to the DHCP-relay at 10.0.0.2, handling the 192.168.1.0/24 net. It does not really matter if this is done using static or dynamic routes or a default gateway, as long as it has a route back. In this example we use default gateways.

### Configuration

The configuration of the Hosts and DHCP server is mostly the same, except for a few adjustments to the DHCP server. In addition for this case a DHCP relay is also needed.

#### Hosts

Both host H1 and host H2 are configured in the same manner as they were in the example in case 1.

#### DHCP Server

The DHCP Server is for the most part configured in the same manner as in case 1. There is one difference in the server configuration, and that is the location of the `tftp-server`. Since the DHCP server and TFTP server are not separate nets from the hosts, this needs to be changed. Further, we also change the DHCP `server-port` to the non standard 6767. This because we want the DHCP relay to relay the DHCP messages it receives to that port.

    dhcp-server:/#> configure
    dhcp-server:/config/#> dhcp-server
    dhcp-server:/config/dhcp-server/#> tftp-server 10.0.0.5
    dhcp-server:/config/dhcp-server/#> server-port 6767
    dhcp-server:/config/dhcp-server/#>

In addition, we also need the DHCP server to provide a gateway to the hosts towards the relay located at 192.168.1.2. This is necessary for the hosts to be able to download their configurations from the TFTP server:

    dhcp-server:/config/dhcp-server/#> host 1
    dhcp-server:/config/dhcp-server/host-1/#> gateway 192.168.1.2
    dhcp-server:/config/dhcp-server/host-1/#> end
    dhcp-server:/config/dhcp-server/#> host 2
    dhcp-server:/config/dhcp-server/host-2/#> gateway 192.168.1.2
    dhcp-server:/config/dhcp-server/host-2/#> leave
    dhcp-server:/#>

Lastly, the server is also in need of a route back to the DHCP Relay. In this example we handle this with a default gateway route:

    dhcp-server:/#> configure
    dhcp-server:/config/#> ip
    dhcp-server:/config/ip/#> route default 10.0.0.2
    dhcp-server:/config/ip/#>leave
    dhcp-server:/#>

Note

This example assumes the same is done for the TFTP server.

#### DHCP Relay

We configure the relay to forward any dhcp messages it receives on vlan1 towards the DHCP server located at 10.0.0.1:6767:

    dhcp-relay:/#> configure
    dhcp-relay:/config/#> dhcp-relay
    dhcp-relay:/config/dhcp-relay/#> server 10.0.0.1:6767
    dhcp-relay:/config/dhcp-relay/#> iface vlan1
    dhcp-relay:/config/dhcp-relay/#> leave
    dhcp-relay:/#>

« Previous Next »