Ubuntu Manpage: nbdkit-ip-filter - filter clients by IP address, process ID, user ID, group ID and more

Provided by: nbdkit_1.42.2-1ubuntu1_amd64

NAME

       nbdkit-ip-filter - filter clients by IP address, process ID, user ID, group ID and more

SYNOPSIS

        nbdkit --filter=ip PLUGIN [allow=addr[,addr...]]
                                  [deny=addr[,addr...]]

DESCRIPTION

       "nbdkit-ip-filter" can allow or deny client connections by their IP address.

       Usually it is better to control this outside nbdkit, for example using TCP wrappers or a firewall, but
       this filter can be used if these are not available.

EXAMPLES

   Filter by IP address
        nbdkit --filter=ip [...] allow=127.0.0.1,::1 deny=all

       Allow clients to connect on the loopback IPv4 or loopback IPv6 address, deny all other clients.

        nbdkit --filter=ip [...] deny=8.0.0.0/8

       Allow any client except connections from the IPv4 "8.0.0.0/8" network.

        nbdkit --filter=ip [...] allow=anyipv6 deny=all

       Allow IPv6 clients to connect from anywhere, deny all other sources.

   Filter by Unix domain socket peer
        nbdkit -U $tmpdir/sock --filter=ip [...] allow=uid:`id -u` deny=all

       Only allow the current user ("id -u") to connect over the socket.

       Layer extra security by creating the socket inside a temporary directory only accessible by the user.

        nbdkit -U $tmpdir/sock --filter=ip [...] allow=gid:`id -g` deny=all

       Allow anyone in the same group as the current user to connect to the Unix domain socket.

       As in the previous example, layer extra security by creating the socket inside a temporary directory only
       accessible by the group.

RULES

When a client connects, this filter checks its source address against the allow and deny lists as
follows:

1. If the address matches any in the allow list, permission is granted.

2. If the address matches any in the deny list, permission is denied.

3. Otherwise permission is granted.

If either the "allow" or "deny" parameter is not present then it is assumed to be an empty list. The
order in which the parameters appear on the command line does not matter; the allow list is always
processed first and the deny list second.

The "allow" and "deny" parameters each contain a comma-separated list of any of the following:

all
any These keywords (which both have the same meaning) match any source.

allipv4
anyipv4
These keywords match any IPv4 address.

allipv6
anyipv6
These keywords match any IPv6 address.

allunix
anyunix
These keywords match any connection over a Unix domain socket.

allvsock
anyvsock
These keywords match any connection over an "AF_VSOCK" socket.

A.B.C.D
This matches the single IPv4 address "A.B.C.D", for example 127.0.0.1.

A.B.C.D/NN
This matches the range of IPv4 addresses "A.B.C.D/NN", for example "192.168.2.0/24" or "10.0.0.0/8".

A:B:...
This matches the single IPv6 address "A:B:...". The usual IPv6 address representations can be used
(see RFC 5952).

A:B:.../NN
This matches a range of IPv6 addresses "A:B:.../NN".

dn:WILDCARD
issuer-dn:WILDCARD
(nbdkit ≥ 1.40, not Windows)

This matches the TLS Distinguished Name (DN) of the client certificate or client certificate's issuer
against the "WILDCARD". In the example below quotes are used to protect the wildcard from the shell,
they are not part of the matching:

nbdkit --filter=ip allow=dn:"*,O=BigCo,*" [...]

nbdkit --filter=ip allow=issuer-dn:"CN=BigCo" [...]

See nbdkit_peer_tls_dn(3), nbdkit_peer_tls_issuer_dn(3) and nbdkit-tls(1) for further information
about DNs.

Using this rule has important performance implications, see "Late filtering" below.

Comma splitting is not done inside parameters that start with "dn:" or "issuer-dn:". See "Comma
splitting" below.

pid:PID
(nbdkit ≥ 1.24, Linux only)

This matches the process ID "PID", if the client connects over a Unix domain socket.

Note that process IDs are recycled so this alone is not secure enough to ensure that only a single
desired process can connect. However you could use it as an additional check.

security:LABEL
(nbdkit ≥ 1.36, not Windows)

This matches the security context (usually the SELinux label, IPSEC label or NetLabel) of the client.

uid:UID
(nbdkit ≥ 1.24)

This matches the numeric user ID "UID", if the client connects over a Unix domain socket.

gid:GID
(nbdkit ≥ 1.24)

This matches the numeric group ID "GID", if the client connects over a Unix domain socket.

vsock-cid:CID
vsock-port:PORT
(nbdkit ≥ 1.24)

These match the CID or port number for "AF_VSOCK" sockets.

PARAMETERS

       allow=addr[,...]
           Set list of allow rules.  This parameter is optional, if omitted the allow list is empty.

       deny=addr[,...]
           Set list of deny rules.  This parameter is optional, if omitted the deny list is empty.

NOTES

Not filtered
If neither the "allow" nor the "deny" parameter is given the filter does nothing.

Unix domain sockets and "AF_VSOCK" sockets were always unfiltered in nbdkit ≤ 1.22. In nbdkit ≥ 1.24 the
ability to filter them was added.

In nbdkit ≤ 1.38, connections from non-IP, non-Unix, non-vsock sockets (whatever that would be) were
allowed unfiltered. In nbdkit ≥ 1.40 unknown socket families are denied.

Common patterns of usage
Permit known good connections and deny everything else:

nbdkit --filter=ip ... allow=good1,good2,... deny=all

Block troublemakers but allow everything else:

nbdkit --filter=ip ... deny=bad1,bad2,...

Comma splitting
You can supply each "allow" and "deny" parameter multiple times. The rules are concatenated.

Also each "allow" or "deny" parameter can contain multiple rules, split at commas (",").

These sets of rules are equivalent:

nbdkit --filter=ip allow=good1 allow=good2,good3 deny=all

nbdkit --filter=ip allow=good1,good2 allow=good3 deny=all

Because TLS Distinguished Names (DNs) contain commas, the filter has a special exception where if the
first characters of the allow or deny parameter match "dn:" or "issuer-dn:" then the whole parameter is
not split. This lets you match on multiple DNs naturally:

nbdkit --filter=ip \
allow=dn:"*,O=BigCo,*" \
allow=issuer-dn:"CN=BigCo" [...]

Late filtering
This filter normally runs the filtering rules very early in the connection, just after nbdkit has
received an open socket from the client. Filtering happens in the ".preconnect" callback.

"Callback lifecycle" in nbdkit-plugin(3) explains the connection lifecycle in more detail.

However if your allow or deny patterns contain any "dn:" or "issuer-dn:" rules then all filtering has to
be done later in the connection lifecycle, since we must wait until TLS negotiation has been completed.
Filtering happens in the ".open" or ".list_exports" callback instead.

In practice this makes filtering more expensive and potentially makes it easier to cause Denial of
Service (DoS) attacks. You should try to combine "dn:" and "issuer-dn:" rules with extra filtering
outside nbdkit, such as using a firewall or VPN.

DEBUG FLAGS

       -D ip.rules=1
           Debug  rules  and  rule matching.  If clients are accepted or rejected when they should not be, using
           -v -D ip.rules=1 can help to debug the problem.

FILES

       $filterdir/nbdkit-ip-filter.so
           The filter.

           Use "nbdkit --dump-config" to find the location of $filterdir.

VERSION

       "nbdkit-ip-filter" first appeared in nbdkit 1.18.

AUTHORS

       Richard W.M. Jones

COPYRIGHT

       Copyright Red Hat

LICENSE

       Redistribution  and  use in source and binary forms, with or without modification, are permitted provided
       that the following conditions are met:

       •   Redistributions of source code must retain the above copyright notice, this list  of  conditions  and
           the following disclaimer.

       •   Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
           the following disclaimer in the documentation and/or other materials provided with the distribution.

       •   Neither  the  name  of  Red  Hat  nor the names of its contributors may be used to endorse or promote
           products derived from this software without specific prior written permission.

       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY EXPRESS  OR  IMPLIED  WARRANTIES,
       INCLUDING,  BUT  NOT  LIMITED  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE LIABLE  FOR  ANY  DIRECT,  INDIRECT,
       INCIDENTAL,  SPECIAL,  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
       ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT  LIABILITY,  OR  TORT  (INCLUDING  NEGLIGENCE  OR
       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
       DAMAGE.

nbdkit-1.42.2                                      2025-04-02                                nbdkit-ip-filter(1)