Overview

Welcome to the User Guide for Flock Networks Routing Suite 20.0.

At Flock Networks we believe networks should be simple, fast and secure.

  • Simplicity is achieved by having a Uniform configuration across all routers in the network.
  • Performance is achieved by handling network protocol updates in batches. This means route calculation can be performed less frequently, and keeps the CPU's instruction cache hot whilst calculating routes. In addition all the Data Structures used in the Routing Suite are CPU data cache friendly.
  • Security is achieved by the Routing Suite being exclusively written in the Rust programming language. Rust has a similar performance to C / C++, but is memory safe at compile time.

If you have any questions, suggestions or issues, please email support@flocknetworks.com.

Installation

The Flock Networks Routing Suite is shipped as a Debian package. However the Routing Suite can run on any Linux system. The executables have no dependencies other than the Linux Kernel API (Sockets, Netlink, etc). The following instructions are for installing on a Debian based Linux distribution (Debian, Ubuntu, Mint, etc). To install on other systems please see Appendix C: Manual Install.

Download the latest Debian package.

Install the application from the Debian package;

# dpkg -i flockrsd_20.0.0_amd64.deb

The Flock Routing Suite Licence is appended to;

/usr/share/doc/flockrsd/copyright

The Flock Routing Suite Client (flockrsc) is copied to;

/usr/bin/flockrsc

The Flock Routing Suite Daemon (flockrsd) is copied to;

/usr/sbin/flockrsd

flockrsd config is stored under;

/etc/flockrsd/

flockrsd is controlled by systemd;

# service flockrsd status
# service flockrsd start
# service flockrsd stop

logging can be viewed via journalctl;

# journalctl -u flockrsd --boot

Example successful installation

# dpkg -i flockrsd_20.0.0_amd64.deb
Selecting previously unselected package flockrsd.
(Reading database ... 27695 files and directories currently installed.)
Preparing to unpack flockrsd_20.0.0_amd64.deb ...
Unpacking flockrsd (20.0.0) ...
Setting up flockrsd (20.0.0) ...

# service flockrsd start

# service flockrsd status
● flockrsd.service - Flock Networks Routing Suite Daemon
Loaded: loaded (/lib/systemd/system/flockrsd.service; enabled; vendor preset: enabled)
Active: active (running) since Fri 2020-01-24 12:39:24 GMT; 6s ago
Main PID: 825 (flockrsd)
    Tasks: 1 (limit: 1150)
Memory: 908.0K
CGroup: /system.slice/flockrsd.service
        └─785 /usr/sbin/flockrsd
Jan 24 12:39:24 flocknet flockrsd[825]: [INFO  flockrsd] START: PID=825, Compile Mode=Release, Log Level="info"
Jan 24 12:39:24 flocknet flockrsd[825]: [INFO  flockrsd] OSPFv2 derived RouterId(192.168.122.171) from IPv4 Address
Jan 24 12:39:28 flocknet flockrsd[825]: [INFO  flockrsd::ospf_intf] IntfId(2) 10.0.1.168/24 state change Wait -> Backup
Jan 24 12:39:28 flocknet flockrsd[825]: [INFO  flockrsd::ospf_neigh] RouterId(10.0.100.2) V4(10.0.1.249) neigh state change Exchange -> Full

$ flockrsc system
{"version":"20.0.1","pid":825,"compile_mode":"Release","log_level":"info","uptime":{"days":0,"hours":0,"mins":0,"secs":19}}

Troubleshooting Installation

flockrsd fails to start

  • systemd PolicyKit / polkit failure

PolicyKit / polkit is the "sudo of systemd". If you have PolicyKit / polkit active on the install host, and you want to start flockrsd as an unprivileged user, you will need to add PolicyKit / polkit configuration for flockrsd. Alternatively you can just run service flockrsd start as root or under sudo.

$ service flockrsd start
==== AUTHENTICATING FOR org.freedesktop.systemd1.manage-units ===
Authentication is required to start 'flockrsd.service'.
Authenticating as: www-data
Password:
Failed to start flockrsd.service: Connection timed out
See system logs and 'systemctl status flockrsd.service' for details.
polkit-agent-helper-1: pam_authenticate failed: Authentication failure

Flock Routing Suite Daemon (flockrsd)

flockrsd Configuration

Flock Networks devices are designed to be run with a minimal uniform configuration. This is achieved by making each protocols configuration simple and generic, and allowing the device to auto configure. Specific configuration is supported so that devices can be RFC compliant, but users are encouraged to have as little device specific configuration as possible. Interface specific configuration is strongly discouraged.

OSPFv2 Uniform Configuration

This is the default OSPFv2 configuration shipped with Version 20.0. The Flock Routing Suite is designed for scale, you will not need multiple OSPF areas. (If you are adding a device to an existing multi-area OSPF AS, multiple areas are fully supported, please see Appendix A: Configuration Reference).

cat /etc/flockrsd/ospfv2.toml
[ospf_v2]
# Place all ethernet interfaces into area 0.0.0.0
[[ospf_v2.area]]
area_id = "0.0.0.0"
[[ospf_v2.area.intf]]
# Match any interfaces that have name starting with "en"
name = "^en"

You may wish to redistribute static routes from the RIB into OSPFv2.

[[ospf_v2.redistribute]]
origin = "kernel-static"
metric_type = 2
metric = 1000

By design, just configuring redistribution will not make the router an ASBR. The router will only become an ASBR if it actually has some routes to redistribute. This means the OSPF configuration can be kept the same on each router in the AS.

As a minimum we may want a default route added to the kernel of each ASBR router. This route will appear in the RIB and then be redistributed into OSPFv2. OSPFv2 will advertise this route across the AS, so all nodes learn the route to exit the network. Static routes are added using the Linux command line.

# ip route add 0.0.0.0/0 via 192.168.122.171 dev enp9s0

flockrsd logging

Logging can be viewed using journalctl

$ journalctl -u flockrsd --boot

Information

Log level info / [INFO] is used for expected events of note

[INFO  flockrsd] START: PID 385 Compile Mode Release Log Level "debug"
[INFO  flockrsd::os_intf] Update IntfId(2)] Broadcast Mtu(1500) Up [] event DownToUp
[INFO  flockrsd::ospf_intf] IntfId(2), 10.0.1.168/24 state change Wait -> DrOther
[INFO  flockrsd::ospf_neigh] RouterId(10.0.100.3), V4(10.0.1.152) neigh state change Loading -> Full

Warning

Log level warn / [WARN] is used for unexpected events signalled from outside the router. It is normal to see warnings whilst the network is converging. Warnings should never be seen after the network has converged and remains stable.

[WARN  flockrsd::ospf_neigh] RouterId(10.0.100.2), V4(10.0.3.157) neigh state change Full -> Down

Error

Log level error / [ERROR] is used for unexpected events signalled from inside the router. These are never expected to be seen and indicate a bug. Please email a bug report to: support@flocknetworks.com.

Debug

Log level debug / [DEBUG] is used for common expected events.

Trace

Log level trace / [TRACE] is used for very common expected events.

Changing the default log level

The default log level can be changed by setting the RUST_LOG environment variable in the flockrsd systemd service file. Supported log levels in descending order of importance are error, warn, info, debug and trace.

grep RUST_LOG /lib/systemd/system/flockrsd.service
    Environment=RUST_LOG="info"

When the systemd service file has changed, systemd needs to be told to reload the new flockrsd configuration.

# systemctl daemon-reload

To enable the new log level, flockrsd needs to be restarted.

# service flockrsd restart

Flock Routing Suite Client (flockrsc)

By design flockrsc can be run by a user with no special privileges. flockrsc connects to a Read-Only connection on flockrsd. flockrsd state can be viewed but cannot be changed. All output is in JSON format, making it suitable for consumption by humans or machines.

General Command Flags

General Flags can be included in any command.

-d, --detail
-h, --help           Prints help information
-J, --json           Output in JSON
-j, --json-pretty    Output in Pretty Print JSON
-u, --unsorted       Output in unsorted order

System State Commands

Help

flockrsc system -h

Overview

flockrsc system

All system interfaces

flockrsc system -i

Single interface

flockrsc system -i enp1s0

RIB State Commands

Help

flockrsc ribv4 -h

Overview

flockrsc ribv4

All prefixes

flockrsc ribv4 -p

Single prefix

flockrsc ribv4 -p 10.0.5.0/24

All prefixes by route origin

flockrsc ribv4 -p -o ospfv2

OSPFv2 State Commands

Help

flockrsc ospfv2 -h

Overview

flockrsc ospfv2

Overview of all areas

flockrsc ospfv2 -a

Overview of Area 20

flockrsc ospfv2 -a 20

or

flockrsc ospfv2 -a 0.0.0.20

All interfaces in Area 20

flockrsc ospfv2 -i -a 20

All neighbors on interface enp1s0 in Area 0

flockrsc ospfv2 -n -i enp1s0 -a 0

All neighbors on all interfaces in all areas

flockrsc ospfv2 -n -i -a

Autonomous System Link State Database

flockrsc ospfv2 -l

Area 0.0.0.0 Link State Database

flockrsc ospfv2 -a 0 -l

OSPFv2 network route table prefixes

flockrsc ospfv2 -p

OSPFv2 network route table by destination prefix

flockrsc ospfv2 -p 10.20.20.0/24

OSPFv2 router route table prefixes

flockrsc ospfv2 -P

OSPFv2 router route table by router id

flockrsc ospfv2 -P 10.20.100.22

Commonly used commands including sample output

Check status of flockrsd

flock@flocknet:~$ flockrsc system
{"version":"20.0.1","pid":371,"compile_mode":"Release","log_level":"info","uptime":{"days":0,"hours":0,"mins":8,"secs":52}}

Show all prefix's in the RIB

flock@flocknet:~$ flockrsc ribv4 -p
{"ip_net":"0.0.0.0/0","origin":"Kernel","next_hops":[{"intf_id":5,"ip_addr":"192.168.122.1"}]}
{"ip_net":"10.0.1.0/24","origin":"Kernel","next_hops":[{"intf_id":2}]}
{"ip_net":"10.0.2.0/24","origin":"Ospfv2","next_hops":[{"intf_id":2,"ip_addr":"10.0.1.249"}]}
{"ip_net":"10.0.3.0/24","origin":"Kernel","next_hops":[{"intf_id":4}]}
{"ip_net":"10.0.4.0/24","origin":"Kernel","next_hops":[{"intf_id":3}]}
{"ip_net":"42.0.0.0/16","origin":"Kernel","next_hops":[{"intf_id":5,"ip_addr":"192.168.122.1"}]}
{"ip_net":"192.168.122.0/24","origin":"Kernel","next_hops":[{"intf_id":5}]}

Show all OSPFv2 neighbors, out of all interfaces, in all areas

flock@flocknet:~$ flockrsc ospfv2 -n -i -a
{"ospf_area_id":"0.0.0.0"}
{"ospf_intf":"enp1s0"}
{"id":"10.0.100.3","ip":"10.0.5.225","state":"Full","dr":"10.0.5.204","bdr":"10.0.5.225"}
{"ospf_area_id":"0.0.0.20"}
{"ospf_intf":"enp7s0"}
{"id":"10.20.100.20","ip":"10.20.20.189","state":"Full","dr":"10.20.20.189","bdr":"10.20.20.214"}

Show OSPFv2 Area 20 Link State Database

flock@flocknet:~$ flockrsc ospfv2 -a 20 -l
{"lsa_age":279,"lsa_opts":{"bits":2},"lsa_type":"Router","lsa_id":"10.0.100.4","lsa_router_id":"10.0.100.4","lsa_seq":-2147483646,"lsa_checksum":28411,"lsa_len":36}
{"lsa_age":266,"lsa_opts":{"bits":2},"lsa_type":"Router","lsa_id":"10.0.100.5","lsa_router_id":"10.0.100.5","lsa_seq":-2147483646,"lsa_checksum":22802,"lsa_len":36}
{"lsa_age":275,"lsa_opts":{"bits":2},"lsa_type":"Router","lsa_id":"10.20.100.20","lsa_router_id":"10.20.100.20","lsa_seq":-2147483644,"lsa_checksum":58508,"lsa_len":48}
{"lsa_age":271,"lsa_opts":{"bits":2},"lsa_type":"Router","lsa_id":"10.20.100.21","lsa_router_id":"10.20.100.21","lsa_seq":-2147483644,"lsa_checksum":53018,"lsa_len":48}
{"lsa_age":270,"lsa_opts":{"bits":2},"lsa_type":"Network","lsa_id":"10.20.23.191","lsa_router_id":"10.20.100.22","lsa_seq":-2147483646,"lsa_checksum":15710,"lsa_len":32}
{"lsa_age":290,"lsa_opts":{"bits":2},"lsa_type":"Network","lsa_id":"10.20.24.165","lsa_router_id":"10.20.100.22","lsa_seq":-2147483647,"lsa_checksum":37311,"lsa_len":28}
{"lsa_age":262,"lsa_opts":{"bits":2},"lsa_type":"NetworkSummary","lsa_id":"10.0.1.0","lsa_router_id":"10.0.100.4","lsa_seq":-2147483647,"lsa_checksum":30038,"lsa_len":28}
{"lsa_age":266,"lsa_opts":{"bits":2},"lsa_type":"NetworkSummary","lsa_id":"10.0.2.0","lsa_router_id":"10.0.100.5","lsa_seq":-2147483647,"lsa_checksum":25701,"lsa_len":28}
{"lsa_age":262,"lsa_opts":{"bits":2},"lsa_type":"AsbrSummary","lsa_id":"10.0.100.1","lsa_router_id":"10.0.100.4","lsa_seq":-2147483647,"lsa_checksum":6222,"lsa_len":28}
{"lsa_age":266,"lsa_opts":{"bits":2},"lsa_type":"AsbrSummary","lsa_id":"10.0.100.1","lsa_router_id":"10.0.100.5","lsa_seq":-2147483647,"lsa_checksum":4691,"lsa_len":28}

Changing the output format

By default the output is in JSON Lines format, which is JSON with newlines added to aid reading by a human.

flock@flocknet:~$ flockrsc ospfv2 -a -i -n 10.0.100.3
{"ospf_area_id":"0.0.0.0"}
{"ospf_intf":"enp1s0"}
{"id":"10.0.100.3","ip":"10.0.5.225","state":"Full","dr":"10.0.5.225","bdr":"10.0.5.204"}

Using the -j, --json-pretty flag the output is pretty printed JSON

flock@flocknet:~$ flockrsc ospfv2 -a -i -n 10.0.100.3 -j
[
  {
    "ospf_area_id": "0.0.0.0",
    "ospf_intfs": [
      {
        "ospf_intf": "enp1s0",
        "ospf_neighs": [
          {
            "id": "10.0.100.3",
            "ip": "10.0.5.225",
            "state": "Full",
            "dr": "10.0.5.225",
            "bdr": "10.0.5.204"
          }
        ]
      }
    ]
  }
]

Using the -J, --json flag the output is JSON

flock@flocknet:~$ flockrsc ospfv2 -a -i -n 10.0.100.3 -j
[{"ospf_area_id":"0.0.0.0","ospf_intfs":[{"ospf_intf":"enp1s0","ospf_neighs":[{"id":"10.0.100.3","ip":"10.0.5.225","state":"Full","dr":"10.0.5.225","bdr":"10.0.5.204"}]}]}]

Linux Kernel Settings

IP forwarding

For a Linux host to operate as an IP Router, IP forwarding must be enabled.

View IP Forwarding state

# sysctl net.ipv4.ip_forward
net.ipv4.ip_forward = 0

Turn on IP Forwarding

# sysctl -w net.ipv4.ip_forward=1
net.ipv4.ip_forward = 1

Turn on IP forwarding permanently / on system boot

# nano /etc/sysctl.conf
net.ipv4.ip_forward = 1

Appendix A: Configuration Reference

All Flock Network configuration files are in the toml format.

OSPFv2 Configuration

/etc/flockrsd/ospfv2.toml

# OSPFv2 Instance level configuration
# -----------------------------------
# 'ospf_v2' toml table
[ospf_v2]
# RFC2328 1.2 Router ID
# Optional: If not specified highest IPv4 Address is used.
router_id = "String in dotted decimal format"

# Array of 'redistribute' toml tables
[[ospf_v2.redistribute]]
# Origin of the Routes in the RIB to be redistributed
origin = ("kernel-static" | "kernel-connected")
# RFC2328 2.3 Type 1 / Type 2 external metrics
metric_type = ( 1 | 2 )
# OSPF metric to reach redistributed routes, from this router.
# RFC2328 B. LSInfinity => 16777215
metric = ( 0..16777215 )

# OSPFv2 Area level configuration
# -------------------------------
[[ospf_v2.area]] # Array of 'area' toml tables
# RFC2328 C.2 Area ID
area_id = "String in dotted decimal format"

# OSPFv2 Interface level configuration
# ------------------------------------
[[ospf_v2.area.intf]]
# Specify the entire interface name i.e. "eno1"
# or use ^ to match the start of interface names
#   e.g. "^en" will match all interfaces that start with "en"
name = "Interface Name"
# RFC2328 C.3 Interface output cost
# Optional: Default is 10
cost = ( 1..65,535 )
# RFC2328 C.3 Router Priority
# Optional: Default is 1
priority = ( 0..255 )
# RFC2328 C.3 HelloInterval
# Optional: Default is 10s
hello_interval = ( 1..65,535 seconds)
# RFC2328 C.3 RouterDeadInterval
# Optional: Default is 40s
dead_interval = ( 1..65,535 seconds)

Example Uniform OSPFv2 Configuration (Recommended)

[ospf_v2]

# Place all ethernet interfaces into area 0.0.0.0
[[ospf_v2.area]]
area_id = "0.0.0.0"
[[ospf_v2.area.intf]]
# Match any interfaces that have name starting with "en"
name = "^en"

Example Exhaustive OSPFv2 Configuration

[ospf_v2]
router_id = "10.0.1.100"

[[ospf_v2.redistribute]]
origin = "kernel-static"
metric_type = 1
metric = 100
[[ospf_v2.redistribute]]
origin = "kernel-connected"
metric_type = 2
metric = 1000

[[ospf_v2.area]]
area_id = "0.0.0.0"
[[ospf_v2.area.intf]]
name = "enp7s0"
cost = 20
priority = 10
hello_interval = 1
dead_interval = 4
[[ospf_v2.area.intf]]
name = "enp8s0"
cost = 40
priority = 20
hello_interval = 2
dead_interval = 8

[[ospf_v2.area]]
area_id = "0.0.0.1"
[[ospf_v2.area.intf]]
name = "enp9s0"
cost = 30
priority = 30
hello_interval = 20
dead_interval = 80

Appendix B: RFC Compliance

Flock Networks Routing Suite implements the following RFC's.

OSPFv2

  • RFC2328 OSPF Version 2

    The following sections of the RFC are not yet supported;

    • Stub Areas (3.6 Supporting stub areas)
    • Virtual Links (15. Virtual Links)
    • Authentication (D. Authentication)
    • Non-broadcast networks (1.2. Definitions of commonly used terms)

Appendix C: Manual Install

Flock Networks Routing Suite can be manually installed on any Linux system. The executables have no dependencies other than the Linux Kernel API (Sockets, Netlink, etc).

Extract the contents of the Debian package

You will need the ar archive utility from binutils.

For example on Fedora;

# yum install binutils

Then extract the contents of the debian package

$ ar x flockrsd_20.0.0_amd64.deb
$ ls
control.tar.gz  data.tar.xz  debian-binary  flockrsd_20.0.0_amd64.deb
$ tar -xf data.tar.xz
$ ls
control.tar.gz  debian-binary  flockrsd_20.0.0_amd64.deb  usr data.tar.xz etc lib

Install Files

The copyright / software licence file is here;

less usr/share/doc/flockrsd/copyright

Copy the flockrsd daemon config files to /etc/flockrsd

# mkdir /etc/flockrsd
# cp etc/flockrsd/* /etc/flockrsd

Copy the flockrsd daemon to /usr/sbin

# cp usr/sbin/flockrsd /usr/sbin

Copy the flockrsc client to /usr/bin

# cp usr/bin/flockrsc /usr/bin

Start the daemon

# RUST_LOG=info /usr/sbin/flockrsd &

Check the daemon is running

$ flockrsc system
{
    "version": "20.0.0",
    "pid": 24878,
    "compile_mode": "Release",
    "log_level": "error",
    "uptime": {
        "days": 0,
        "hours": 0,
        "mins": 0,
        "secs": 15
    }
}