NFTLB(8)

NAME
nftlb - nftables load balancer

SYNOPSIS
nftlb [option]

DESCRIPTION
nftlb is a nftables(8) rules manager to create virtual services for load balancing at layer 2, layer 3 and layer 4, minimizing the number of rules and using structures to match efficiently the packets. It’s also provided with an easy JSON API service to have the flexibility to interact with nftlb programmatically and to meet automation. So you can use your preferred health checker to be integrated with nftlb very easily.

The philosophy of nftlb is to maintain the data path into the kernel, in order to achieve the most performance possible, but the control plane and heath checks into user space to have the flexibility to change the behavior easily but also to be compatible with the rest of the linux stack.

USAGE
These are the options you may use when running nftlb:

-h | --help
    Show the command help.

-l <LEVEL> | --log <LEVEL>
    Verbosity of the logs. They will be sent to syslog. Valid values are from 0 to 7 (default is 5).

-c <FILE> | --config <FILE>
    Initial configuration file.

-k <KEY> | --key <KEY>
    The authentication key for the web service can be set with this option. If not specified, it will be automatically generated and printed to stdout.

-e | --exit
    This option results in nftlb loading the generated ruleset into nftables(8) and then exit. The web server won't be available.

-6 | --ipv6
    Enable IPv6 support for the web server.

-H <HOST> | --host <HOST>
    Set the host for the web service (all interfaces by default).

-P <PORT> | --port <PORT>
    Set the TCP port for the web service (5555 by default).

API USAGE
Once nftlb is launched you can manage it through the API:

Virtual service listing

    curl -H "Key: <MYKEY>" http://<NFTLB IP>:5555/farms

Setup a new virtual service

    curl -H "Key: <MYKEY>" -X POST http://<NFTLB IP>:5555/farms -d "@tests/008_snat_ipv4_all_rr.json"

Delete a virtual service

    curl -H "Key: <MYKEY>" -X DELETE http://<NFTLB IP>:5555/farms/lb01

Delete a backend of a virtual service

    curl -H "Key: <MYKEY>" -X DELETE http://<NFTLB IP>:5555/farms/lb01/backends/bck1

CONFIGURATION
Configuration files have this format (JSON):

{
	"farms" : [
		{ <object farm 1> },
		{ <object farm 2> },
		{ ... }
	]
}

The farm objects have the following attributes:

{
	"name" : "<string>",				*Name of the service (required)*
	"iface"	: "<interface name>",			*Input interface (only required for DSR)*
	"oface"	: "<interface name>",			*Output interface (only required for DSR)*
	"family": "<ipv4 | ipv6 | dual>",		*Family of the virtual service (ipv4 by default)*
	"ether-addr": "<mac address>",			*Physical address of the virtual service (only required for DSR)*
	"virtual-addr": "<ip address>",			*IP address for the virtual service (required)*
	"virtual-ports": "<port list>",			*Port list separated by commas or ranges separated by a hyphen*
	"mode": "<snat | dnat | dsr>",			*Topology to be implemented (required)*
	"protocol": "<tcp | udp | sctp | all>",		*Protocol to be used by the virtual service (tcp by default)*
	"scheduler": "<weight | rr | hash | symhash>",	*Scheduler to be used (round robin by default)*
	"priority": "<number>",				*Priority availability for backends > 0 (1 by default)*
	"state": "<up | down | off>",			*Set the status of the virtual service (up by default)*
	"backends" : [					*List of backends*
		{<object backend 1>},
		{<object backend 2>},
		{...}
	]
}

The backend objects have the following attributes:

{
	"name" : "<string>",				*Name of the backend (required)*
	"ether-addr": "<mac address>",			*Physical address of the backend (only required for DSR)*
	"ip-addr": "<ip address>",			*IP address for the backend (required, except for DSR)*
	"weight": "<number>",				*Weight of the backend (1 by default)*
	"priority": "<number>",				*Priority availability for the backend > 0 (1 by default)*
	"state": "<up | down | off>",			*Set the status of the backend (up by default)*
}

CONFIG EXAMPLES
TCP IPv4 SNAT with weights:

{
    "farms" : [
        {
            "name" : "lb01",
            "family" : "ipv4",
            "virtual-addr" : "192.168.0.100",
            "virtual-ports" : "80",
            "mode" : "snat",
            "protocol" : "tcp",
            "scheduler" : "weight",
            "state" : "up",
            "backends" : [
                {
                    "name" : "bck0",
                    "ip-addr" : "192.168.0.10",
                    "weight" : "5",
                    "priority" : "1",
                    "state" : "up"
                },
                {
                    "name" : "bck1",
                    "ip-addr" : "192.168.0.11",
                    "weight" : "5",
                    "priority" : "1",
                    "state" : "up"
                }
            ]
        }
    ]
}

TCP IPv4 with DSR using symhash:

{
    "farms" : [
        {
            "name" : "lb01",
            "family" : "ipv4",
            "iface" : "enp0s3",
            "oface" : "enp0s8",
            "virtual-addr" : "192.168.0.100",
            "ether-addr" : "01:01:01:01:01:01",
            "virtual-ports" : "80-88",
            "mode" : "dsr",
            "protocol" : "tcp",
            "scheduler" : "symhash",
            "state" : "up",
            "backends" : [
                {
                    "name" : "bck0",
                    "ip-addr" : "192.168.0.10",
                    "ether-addr" : "02:02:02:02:02:02",
                    "weight" : "5",
                    "priority" : "1",
                    "state" : "up"
                },
                {
                    "name" : "bck1",
                    "ip-addr" : "192.168.0.11",
                    "ether-addr" : "03:03:03:03:03:03",
                    "weight" : "5",
                    "priority" : "1",
                    "state" : "up"
                }
            ]
        }
    ]
}

SEE ALSO
For nftlb information, please head to https://github.com/zevenet/nftlb.

To get up-to-date information about nftables(8), please head to http://wiki.nftables.org/.

AUTHORS
nftlb was written by Laura García @ Zevenet (https://www.zevenet.com).

This manual page was written by Arturo Borrero Gonzalez <arturo@debian.org> for the Debian project (but may be used by others).