Nico Schottelius/ blog/ Bootstrapping a network with sexy

Introduction

This article explains how to begin to manage a network with sexy. Because I just moved house, I take my home network as an example.

Prerequisites

First of all, you need to have sexy installed, as described on the sexy homepage. Secondly, if you already played around with sexy, you should empty the sexy database, which is located at ~/.sexy:

% rm -rf ~/.sexy

Or, if you are using git to manage your ~/.sexy directory, create a fresh branch, which does not contain any files:

% cd ~/.sexy 
% git checkout -b network_bootstrap

# Ensure all (committed and non-committed) files are gone
% rm -rf db/ backend/
% git rm -r db/ backend/
% git commit -m "Empty sexy database"

Add the first host

First of all, let us add a host. Sexy wants to know its type (virtual machine or hardware). Sexy expects all names as fully qualified domain names (FQDNs):

% sexy host add -t hw katze.intern.schottelius.org

Hint: You can use the -h flag to get help for any command. Using host list, we can verify the host has been added:

% sexy host list
katze.intern.schottelius.org

Now we can network cards to this host:

% sexy host nic-add -m 00:00:24:c8:da:bc -n eth0 katze.intern.schottelius.org 
% sexy host nic-add -m 00:00:24:c8:da:bd -n eth1 katze.intern.schottelius.org

Add the network

Currently, sexy only allows you to manage IPv4 based networks - IPv6 may be added in future releases. So the command to remember for now, is net-ipv4:

% sexy net-ipv4 add --mask 22 192.168.24.0
% sexy net-ipv4 list
192.168.24.0

Now we created the network 192.168.24.0/22.

Add a host to a network

In sexy, the host and net-ipv4 areas are disconnected: You can use sexy to manage only hosts, to manage only networks or to manage both. To allow this flexibility, the network part does not know about any information from the host part. Luckily enough, you don't need to re-enter the information, but you can retrieve them from the database.

The previously added host, katze.intern.schottelius.org, is the router of my home network and it should use the first IPv4 address in the network. The net-ipv4 host-add command can be used to add a host:

% sexy net-ipv4 host-add
usage: sexy net-ipv4 host-add [-h] [-d] [-v] -m MAC_ADDRESS -f FQDN
                          [-i IPV4_ADDRESS]
                          network

So adding the host to a network requires giving in at least the mac address, which we entered before. So we can use the following line to add the host to our new network:

% host=katze.intern.schottelius.org
% mac=$(sexy host nic-addr-get -n eth0 $host)
% sexy net-ipv4 host-add -m $mac -f $host 192.168.24.0

Sexy will be default use the next free address and as this is the first host in the network, it used .1:

% sexy net-ipv4 host-ipv4-address-get 192.168.24.0 -f katze.intern.schottelius.org
192.168.24.1

Making use of the entered information

Sexy does not know which DNS or DHCP server you may be using. To implement changes to your architecture (probably using a software like cdist), sexy supports backends to do the change.

For my home network, I am going to use dnsmasq, because the router is a small Soekris net5501.

The backends are stored in ~/.sexy/backend and for this example tutorial, I will create ~/.sexy/backend/net-ipv4/apply:

% cat ~/.sexy/backend/net-ipv4/apply 
#!/bin/sh -e

cdist_base="/home/users/nico/p/cdist/nico"
cdist_bin="$cdist_base/bin/cdist"
dst_dir="$cdist_base/conf/type/__nico_router/files/dnsmasq.d"
tmp=$(mktemp /tmp/foooooo.XXXXXXXXXXXXXXXX)

for network in "$@"; do
    dstfile="${dst_dir}/${network}-dhcp.conf"

    cat << eof > "$tmp"
# WARNING: sexy generated file, do *not* edit directly.
eof

    for fqdn in $(sexy net-ipv4 host-list $network); do
        mac=$(sexy net-ipv4 host-mac-address-get -f "$fqdn" "$network")
        ipv4a=$(sexy net-ipv4 host-ipv4-address-get -f "$fqdn" "$network")
        hostname=$(echo $fqdn | sed 's/\..*//')

        line="dhcp-host=${mac},$ipv4a,$hostname"
        echo "${line}" >> "${tmp}"
    done

    mv "${tmp}" "${dstfile}"
done

cd "${dst_dir}"
git add .
git commit -m "Update Sexy generated network configuration" -o -- . 2>/dev/null || true
echo "Transferring changes to git remote"
git pull --quiet
git push --quiet

"$cdist_bin" config -v zuhause.schottelius.org

In essence this backend creates the dnsmasq configuration and executes cdist afterwards to apply the changes. I personally prefer a backend to be shell script, but it can be any kind of executable.

Adding more hosts

To make this tutorial useful and my router actually provide a dhcp server, I'll add my notebook and the fileserver to sexy:

% sexy host add -t hw loch.intern.schottelius.org                                 
% sexy host nic-add -m f4:6d:04:71:c5:ce loch.intern.schottelius.org
% sexy net-ipv4 host-add -m $(sexy host  nic-addr-get -n nic0 loch.intern.schottelius.org) -f loch.intern.schottelius.org 192.168.24.0     
% sexy host add -t hw brief.intern.schottelius.org                                                                  
% sexy host nic-add -m b8:8d:12:15:fd:fa brief.intern.schottelius.org                                                                  
% sexy net-ipv4 host-add -m $(sexy host  nic-addr-get -n nic0 brief.intern.schottelius.org) -f brief.intern.schottelius.org 192.168.24.0

As you can see, if I do not specify the name of the nic, sexy automatically uses nic0 for the first nic. This decision was made, as network device names vary between operating systems and even operating system versions.

Applying the configuration

The previously created backend will get executed with all existing networks, if you run the apply command with the --all parameter:

% sexy net-ipv4 apply --all

The result

Using only the steps above, I've created a sexy maintained network, 192.168.24.0/22, which calls cdist to configure the router with dnsmasq.

You can browse the real sexy database created during this tutorial, as well as the cdist configuration that is used to configure the router.