README: Document rule matching behaviour

[aszlig]

Rendered version

I wasn't sure whether I'd want to change the behaviour of blackholing subsequent sockets leading to the same socket path, so I searched for public code on GitHub where I'm using ip2unix in practice:

https://github.com/aszlig/avonc/blob/8c025c2d283a11/modules/redis.nix#L33

$ ip2unix -r port=10,systemd ...

https://github.com/aszlig/avonc/blob/01dead4e3de2cb/osrm/default.nix#L140

$ ip2unix -r in,systemd -r reject ...

https://github.com/aszlig/avonc/blob/26bb761105c8ba/talk/external-signaling/default.nix#L420

$ ip2unix -r in,port=8188,systemd ...

https://github.com/headcounter/shabitica/blob/fb917c6a6c8539/tests/e2e/default.nix#L98

$ ip2unix -r addr=127.0.0.1,port=8100,path=shabitica.sock

https://github.com/aszlig/avonc/blob/ec07c35d744de2/libreoffice-online/default.nix#L212-L214

$ ip2unix -r out,port=9981,ignore \
>         -r out,path=/run/libreoffice-online/internal.socket \
>         ...

https://github.com/nixcloud/nixcloud-webservices/blob/e324a8aa9e1bc89/modules/web/messaging/rabbitmq/default.nix#L166-L183

$ ip2unix -r in,tcp,port=5671-5672,path=.../rabbitmq.socket \
>         -r in,tcp,port=25672,path=.../rabbitmqctl.socket \
>         -r out,port=35672-35682,path=.../rabbitmqctl-%p.socket \
>         -r out,tcp,port=4369,path=.../epmd.socket \
>         -r in,tcp,port=4369,reject=EADDRINUSE \
>         -r port=0,path=.../.epmd-rabbitmq-%p.socket \
>         -r path=/tmp/xxx-%a-%t-%p.socket \
>         ...

https://github.com/aszlig/avonc/blob/34d9794487e36ba/xmpp/default.nix#L33-L70

$ ip2unix -r in,port=4369,reject=EADDRINUSE \
>         -r in,port=0,path=/run/mongooseim-epmd/port-%p.socket \
>         -r out,addr=127.0.0.100,port=5432,path=/run/postgresql/.s.PGSQL.5432 \
>         -r out,tcp,port=4369,path=/run/mongooseim-epmd.socket \
>         -r out,addr=127.0.0.1,path=/run/mongooseim-epmd/port-%p.socket \
>         -r in,port=5280,systemd \
>         -r out,addr=127.0.0.200,port=7,path=/run/mongooseim-internal/auth.socket \
>         ...

The last three are pretty complicated and also could be simplified in todays version of ip2unix, but the all the other examples benefit from the "lazy" approach (blackholing subsequent sockets) to be much more concise.

Even when looking closer at the more complicated examples, some of them still benefit from that behaviour, since for example epmd (port 4369) could possibly bind to multiple addresses. The same is true for RabbitMQ (Default: an empty string, meaning "bind to all network interfaces".).

Of course, apart from just my own examples, I also looked on how others are using it:

https://github.com/grahamc/nixos-config/blob/91ce27f375500ff/packages/aenea/service.nix#L6

$ ip2unix -r in,path=.../aenea.sock ...

I don't know a whole lot about Aenea but from its source it seems that it only binds to one address, but @grahamc still seems to use the "lazy" approach here, which I think is perfectly fine.

https://github.com/openlab-aux/vuizvui/blob/bfee3147aaf5216/machines/profpatsch/legosi.nix#L74-L76

$ ip2unix -r addr=1.2.3.4,port=6667,path=/run/bitlbee.socket ...

The example from @Profpatsch however is a little more specific, so in this case, blackholing of the socket would only take ploce if BitlBee would bind to the same address and port, but using UDP instead.

https://github.com/nixcloud/ip2unix/pull/13#issuecomment-635423354

$ ip2unix -r path=rsession.sock ...

An example from @riedel, which is in another "lazy" (or let's say "concise") usage.

Given that one can always be more specific and so prevent anything from being blackholed, I opted to not change the behaviour and just document the current behaviour so that it's more clear to people what's happening in such a situation and why.

[aszlig]

@Profpatsch, @grahamc, @riedel: Please give a thumbs up :+1: if this behaviour is fine or a thumbs down :-1: if you think this behaviour is weird and should be changed.

[riedel]

Like you mentioned, I am rather lazy ( :) ). To me it was rather obvious that the first socket wins the bind.

[Profpatsch]

I think you need to expand the description of what the term “to be blackholed” means a little more, I don’t quite follow the examples, even after reading the description at the beginning of the readme.