softflowd/debian/README.Debian

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

Starting with version 0.9.9-4, the Debian packaging of softflowd
supports handling of multiple instances. One instance is already
shipped as `/etc/softflowd/default.conf` (which is a re-used
`/etc/default/softflowd` when upgrading from an older version).

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. 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.
    http://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.