softflowd/debian/README.Debian

Multiple softflowd instances
============================

The Debian packaging of softflowd supports handling of multiple
instances. One instance is already shipped as
`/etc/softflowd/default.conf`.

To add more instances, create a file `/etc/softflowd/<instance>.conf`
where `<instance>` should be constructed using the "Portable Filename
Character Set"[1] and must not start with a dot (i.e. must not be a
hidden file).

The file is a POSIX shell fragment and defines two variables:

* `interface`: The interface to listen on, or `all`
  Without an interface definition, the instance will be ignored.
* `options`: Additional options to pass to softflowd.

On systemd, the file is read as a key/value store, for details see
`EnvironmentFile=` systemd.exec(5).

On SysV init, the file is run as a shell script.


The pidfile will be stored at `/run/softflowd/<instance>.pid`[2], do not
attempt to override that. The control socket for softflowctl is at
`/run/softflowd/<instance>.ctl`. You still may override these using the
`-c` options in the `options=` string, last match wins.

The softflowctl program will query the "default" instance by default.


To add a new instance:

Create an according configuration file first.

On systemd, run `systemctl daemon-reload`, then
`systemctl start softflowd@<instance>.service`.

On SysV init, run `serivce softflowd start <instance>`.


[1] Upper and lower case characters, digits, dot, underscore, dash.
    For pure visual reasons, the dash should be avoided on systemd as
    it's escaped in the service name.
    https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap03.html#tag_03_282
[2] On SysV init systems: `/var/run/softflowd/<instance>.pid`, likewise
    for the control socket.