www.nico.schottelius.org/blog/sexy-network-bootstrap.mdwn

[[!meta title="Bootstrapping a network with sexy"]]

## Introduction

This article explains how to begin to manage a network
with [[sexy|software/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|software/sexy]]. 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|software/cdist]]), sexy supports
**backends** to do the change.

For my home network, I am going to use 
[dnsmasq](http://www.thekelleys.org.uk/dnsmasq/doc.html), because the
router is a small [Soekris net5501](http://soekris.com/net5501.htm).

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|software/cdist]] to configure
the router with dnsmasq.

You can browse 
[the real sexy database](http://git.schottelius.org/?p=sexy-database;a=summary)
created during this tutorial, as well as
the [cdist configuration](http://git.schottelius.org/?p=cdist-nico;a=summary)
that is used to configure the router.

[[!tag cdist net sexy unix]]