.\" Automatically generated by Podwrapper::Man 1.32.5 (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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 "2023-01-04" "nbdkit-1.32.5" "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 \s-1IP\s0
address.  Usually it is better to control this outside nbdkit, for
example using \s-1TCP\s0 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 \s-1ID,\s0 user \s-1ID\s0 and group \s-1ID.\s0  Also
this version added support for filtering \f(CW\*(C`AF_VSOCK\*(C'\fR sockets by peer
\&\s-1CID\s0 or port.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Filter by \s-1IP\s0 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/\fR\s-1NN\s0" 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 \s-1RFC 5952\s0).
.IP "A\fB:\fRB\fB:\fR...\fB/\fR\s-1NN\s0" 4
.IX Item "A:B:.../NN"
This matches a range of IPv6 addresses \f(CW\*(C`A:B:.../NN\*(C'\fR.
.IP "\fBpid:\fR\s-1PID\s0" 4
.IX Item "pid:PID"
(nbdkit ≥ 1.24, Linux only)
.Sp
This matches the process \s-1ID\s0 \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 "\fBuid:\fR\s-1UID\s0" 4
.IX Item "uid:UID"
(nbdkit ≥ 1.24)
.Sp
This matches the numeric user \s-1ID\s0 \f(CW\*(C`UID\*(C'\fR, if the client connects over a
Unix domain socket.
.IP "\fBgid:\fR\s-1GID\s0" 4
.IX Item "gid:GID"
(nbdkit ≥ 1.24)
.Sp
This matches the numeric group \s-1ID\s0 \f(CW\*(C`GID\*(C'\fR, if the client connects over
a Unix domain socket.
.IP "\fBvsock-cid:\fR\s-1CID\s0" 4
.IX Item "vsock-cid:CID"
.PD 0
.IP "\fBvsock-port:\fR\s-1PORT\s0" 4
.IX Item "vsock-port:PORT"
.PD
(nbdkit ≥ 1.24)
.Sp
These match the \s-1CID\s0 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 "FILES"
.IX Header "FILES"
.IP "\fI\f(CI$filterdir\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 (C) 2019\-2020 Red Hat Inc.
.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
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0