NAME

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

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.

       nbdkit ≥ 1.24 added the ability to filter clients connecting over Unix domain sockets by
       client process ID, user ID and group ID.  Also this version added support for filtering
       "AF_VSOCK" sockets by peer CID or port.

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".

       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.

       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.

   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.

   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,...

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.

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.

SEE ALSO

       nbdkit(1), nbdkit-exitlast-filter(1), nbdkit-exitwhen-filter(1), nbdkit-limit-filter(1),
       nbdkit-filter(3).

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.