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.


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 

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

Now we can network cards to this host:

% sexy host nic-add -m 00:00:24:c8:da:bc -n eth0 
% sexy host nic-add -m 00:00:24:c8:da:bd -n eth1 

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
% sexy net-ipv4 list

Now we created the network

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,, 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]

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:

% mac=$(sexy host nic-addr-get -n eth0 $host)
% sexy net-ipv4 host-add -m $mac -f $host

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 -f

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

tmp=$(mktemp /tmp/foooooo.XXXXXXXXXXXXXXXX)

for network in "$@"; do

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

    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/\..*//')

        echo "${line}" >> "${tmp}"

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

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

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                                 
% sexy host nic-add -m f4:6d:04:71:c5:ce
% sexy net-ipv4 host-add -m $(sexy host  nic-addr-get -n nic0 -f     
% sexy host add -t hw                                                                  
% sexy host nic-add -m b8:8d:12:15:fd:fa                                                                  
% sexy net-ipv4 host-add -m $(sexy host  nic-addr-get -n nic0 -f    

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,, 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.