.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Podwrapper::Man 1.38.1 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-ip-filter 1"
.TH nbdkit-ip-filter 1 2024-04-21 nbdkit-1.38.1 NBDKIT
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
nbdkit\-ip\-filter \- filter clients by IP address, process ID, user ID
or group ID
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\& nbdkit \-\-filter=ip PLUGIN [allow=addr[,addr...]]
\&                           [deny=addr[,addr...]]
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`nbdkit\-ip\-filter\*(C'\fR 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.
.PP
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 \f(CW\*(C`AF_VSOCK\*(C'\fR sockets by peer
CID or port.
.SH EXAMPLES
.IX Header "EXAMPLES"
.SS "Filter by IP address"
.IX Subsection "Filter by IP address"
.Vb 1
\& nbdkit \-\-filter=ip [...] allow=127.0.0.1,::1 deny=all
.Ve
.PP
Allow clients to connect on the loopback IPv4 or loopback IPv6
address, deny all other clients.
.PP
.Vb 1
\& nbdkit \-\-filter=ip [...] deny=8.0.0.0/8
.Ve
.PP
Allow any client except connections from the IPv4 \f(CW\*(C`8.0.0.0/8\*(C'\fR
network.
.PP
.Vb 1
\& nbdkit \-\-filter=ip [...] allow=anyipv6 deny=all
.Ve
.PP
Allow IPv6 clients to connect from anywhere, deny all other sources.
.SS "Filter by Unix domain socket peer"
.IX Subsection "Filter by Unix domain socket peer"
.Vb 1
\& nbdkit \-U $tmpdir/sock \-\-filter=ip [...] allow=uid:\`id \-u\` deny=all
.Ve
.PP
Only allow the current user (\f(CW\*(C`id\ \-u\*(C'\fR) to connect over the socket.
.PP
Layer extra security by creating the socket inside a temporary
directory only accessible by the user.
.PP
.Vb 1
\& nbdkit \-U $tmpdir/sock \-\-filter=ip [...] allow=gid:\`id \-g\` deny=all
.Ve
.PP
Allow anyone in the same group as the current user to connect to the
Unix domain socket.
.PP
As in the previous example, layer extra security by creating the
socket inside a temporary directory only accessible by the group.
.SH RULES
.IX Header "RULES"
When a client connects, this filter checks its source address against
the allow and deny lists as follows:
.IP 1. 4
If the address matches any in the allow list, permission is granted.
.IP 2. 4
If the address matches any in the deny list, permission is denied.
.IP 3. 4
Otherwise permission is granted.
.PP
If either the \f(CW\*(C`allow\*(C'\fR or \f(CW\*(C`deny\*(C'\fR 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.
.PP
The \f(CW\*(C`allow\*(C'\fR and \f(CW\*(C`deny\*(C'\fR parameters each contain a comma-separated
list of any of the following:
.IP \fBall\fR 4
.IX Item "all"
.PD 0
.IP \fBany\fR 4
.IX Item "any"
.PD
These keywords (which both have the same meaning) match any source.
.IP \fBallipv4\fR 4
.IX Item "allipv4"
.PD 0
.IP \fBanyipv4\fR 4
.IX Item "anyipv4"
.PD
These keywords match any IPv4 address.
.IP \fBallipv6\fR 4
.IX Item "allipv6"
.PD 0
.IP \fBanyipv6\fR 4
.IX Item "anyipv6"
.PD
These keywords match any IPv6 address.
.IP \fBallunix\fR 4
.IX Item "allunix"
.PD 0
.IP \fBanyunix\fR 4
.IX Item "anyunix"
.PD
These keywords match any connection over a Unix domain socket.
.IP \fBallvsock\fR 4
.IX Item "allvsock"
.PD 0
.IP \fBanyvsock\fR 4
.IX Item "anyvsock"
.PD
These keywords match any connection over an \f(CW\*(C`AF_VSOCK\*(C'\fR socket.
.IP A\fB.\fRB\fB.\fRC\fB.\fRD 4
.IX Item "A.B.C.D"
This matches the single IPv4 address \f(CW\*(C`A.B.C.D\*(C'\fR, for example
\&\f(CW127.0.0.1\fR.
.IP A\fB.\fRB\fB.\fRC\fB.\fRD\fB/\fRNN 4
.IX Item "A.B.C.D/NN"
This matches the range of IPv4 addresses \f(CW\*(C`A.B.C.D/NN\*(C'\fR, for example
\&\f(CW\*(C`192.168.2.0/24\*(C'\fR or \f(CW\*(C`10.0.0.0/8\*(C'\fR.
.IP A\fB:\fRB\fB:\fR... 4
.IX Item "A:B:..."
This matches the single IPv6 address \f(CW\*(C`A:B:...\*(C'\fR.  The usual IPv6
address representations can be used (see RFC\ 5952).
.IP A\fB:\fRB\fB:\fR...\fB/\fRNN 4
.IX Item "A:B:.../NN"
This matches a range of IPv6 addresses \f(CW\*(C`A:B:.../NN\*(C'\fR.
.IP \fBpid:\fRPID 4
.IX Item "pid:PID"
(nbdkit ≥ 1.24, Linux only)
.Sp
This matches the process ID \f(CW\*(C`PID\*(C'\fR, if the client connects over a Unix
domain socket.
.Sp
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.
.IP \fBsecurity:\fRLABEL 4
.IX Item "security:LABEL"
(nbdkit ≥ 1.36, not Windows)
.Sp
This matches the security context (usually the SELinux label, IPSEC
label or NetLabel) of the client.
.IP \fBuid:\fRUID 4
.IX Item "uid:UID"
(nbdkit ≥ 1.24)
.Sp
This matches the numeric user ID \f(CW\*(C`UID\*(C'\fR, if the client connects over a
Unix domain socket.
.IP \fBgid:\fRGID 4
.IX Item "gid:GID"
(nbdkit ≥ 1.24)
.Sp
This matches the numeric group ID \f(CW\*(C`GID\*(C'\fR, if the client connects over
a Unix domain socket.
.IP \fBvsock-cid:\fRCID 4
.IX Item "vsock-cid:CID"
.PD 0
.IP \fBvsock-port:\fRPORT 4
.IX Item "vsock-port:PORT"
.PD
(nbdkit ≥ 1.24)
.Sp
These match the CID or port number for \f(CW\*(C`AF_VSOCK\*(C'\fR sockets.
.SS "Not filtered"
.IX Subsection "Not filtered"
If neither the \f(CW\*(C`allow\*(C'\fR nor the \f(CW\*(C`deny\*(C'\fR parameter is given the filter
does nothing.
.PP
Unix domain sockets and \f(CW\*(C`AF_VSOCK\*(C'\fR sockets were always unfiltered in
nbdkit\ ≤\ 1.22.  In nbdkit\ ≥\ 1.24 the ability to filter
them was added.
.SS "Common patterns of usage"
.IX Subsection "Common patterns of usage"
Permit known good connections and deny everything else:
.PP
.Vb 1
\& nbdkit \-\-filter=ip ... allow=good1,good2,... deny=all
.Ve
.PP
Block troublemakers but allow everything else:
.PP
.Vb 1
\& nbdkit \-\-filter=ip ... deny=bad1,bad2,...
.Ve
.SH PARAMETERS
.IX Header "PARAMETERS"
.IP \fBallow=\fRaddr[\fB,\fR...] 4
.IX Item "allow=addr[,...]"
Set list of allow rules.  This parameter is optional, if omitted the
allow list is empty.
.IP \fBdeny=\fRaddr[\fB,\fR...] 4
.IX Item "deny=addr[,...]"
Set list of deny rules.  This parameter is optional, if omitted the
deny list is empty.
.SH "DEBUG FLAGS"
.IX Header "DEBUG FLAGS"
.IP "\fB\-D ip.rules=1\fR" 4
.IX Item "-D ip.rules=1"
Debug rules and rule matching.  If clients are accepted or rejected
when they should not be, using \fI\-v\ \-D\ ip.rules=1\fR can help to
debug the problem.
.SH FILES
.IX Header "FILES"
.ie n .IP \fR\fI$filterdir\fR\fI/nbdkit\-ip\-filter.so\fR 4
.el .IP \fR\f(CI$filterdir\fR\fI/nbdkit\-ip\-filter.so\fR 4
.IX Item "$filterdir/nbdkit-ip-filter.so"
The filter.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$filterdir\fR.
.SH VERSION
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-ip\-filter\*(C'\fR first appeared in nbdkit 1.18.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-exitlast\-filter\fR\|(1),
\&\fBnbdkit\-exitwhen\-filter\fR\|(1),
\&\fBnbdkit\-limit\-filter\fR\|(1),
\&\fBnbdkit\-filter\fR\|(3).
.SH AUTHORS
.IX Header "AUTHORS"
Richard W.M. Jones
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright Red Hat
.SH LICENSE
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP \(bu 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP \(bu 4
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.
.IP \(bu 4
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.
.PP
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.