nbdkit-ip-filter(1)

1nbdkit-ip-filter(1)                 NBDKIT                 nbdkit-ip-filter(1)
2
3
4

NAME

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

SYNOPSIS

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

DESCRIPTION

14       "nbdkit-ip-filter" can allow or deny client connections by their IP
15       address.  Usually it is better to control this outside nbdkit, for
16       example using TCP wrappers or a firewall, but this filter can be used
17       if these are not available.
18
19       nbdkit ≥ 1.24 added the ability to filter clients connecting over Unix
20       domain sockets by client process ID, user ID and group ID.  Also this
21       version added support for filtering "AF_VSOCK" sockets by peer CID or
22       port.
23

EXAMPLES

25   Filter by IP address
26        nbdkit --filter=ip [...] allow=127.0.0.1,::1 deny=all
27
28       Allow clients to connect on the loopback IPv4 or loopback IPv6 address,
29       deny all other clients.
30
31        nbdkit --filter=ip [...] deny=8.0.0.0/8
32
33       Allow any client except connections from the IPv4 "8.0.0.0/8" network.
34
35        nbdkit --filter=ip [...] allow=anyipv6 deny=all
36
37       Allow IPv6 clients to connect from anywhere, deny all other sources.
38
39   Filter by Unix domain socket peer
40        nbdkit -U $tmpdir/sock --filter=ip [...] allow=uid:`id -u` deny=all
41
42       Only allow the current user ("id -u") to connect over the socket.
43
44       Layer extra security by creating the socket inside a temporary
45       directory only accessible by the user.
46
47        nbdkit -U $tmpdir/sock --filter=ip [...] allow=gid:`id -g` deny=all
48
49       Allow anyone in the same group as the current user to connect to the
50       Unix domain socket.
51
52       As in the previous example, layer extra security by creating the socket
53       inside a temporary directory only accessible by the group.
54

RULES

56       When a client connects, this filter checks its source address against
57       the allow and deny lists as follows:
58
59       1.  If the address matches any in the allow list, permission is
60           granted.
61
62       2.  If the address matches any in the deny list, permission is denied.
63
64       3.  Otherwise permission is granted.
65
66       If either the "allow" or "deny" parameter is not present then it is
67       assumed to be an empty list.  The order in which the parameters appear
68       on the command line does not matter; the allow list is always processed
69       first and the deny list second.
70
71       The "allow" and "deny" parameters each contain a comma-separated list
72       of any of the following:
73
74       all
75       any These keywords (which both have the same meaning) match any source.
76
77       allipv4
78       anyipv4
79           These keywords match any IPv4 address.
80
81       allipv6
82       anyipv6
83           These keywords match any IPv6 address.
84
85       allunix
86       anyunix
87           These keywords match any connection over a Unix domain socket.
88
89       allvsock
90       anyvsock
91           These keywords match any connection over an "AF_VSOCK" socket.
92
93       A.B.C.D
94           This matches the single IPv4 address "A.B.C.D", for example
95           127.0.0.1.
96
97       A.B.C.D/NN
98           This matches the range of IPv4 addresses "A.B.C.D/NN", for example
99           "192.168.2.0/24" or "10.0.0.0/8".
100
101       A:B:...
102           This matches the single IPv6 address "A:B:...".  The usual IPv6
103           address representations can be used (see RFC 5952).
104
105       A:B:.../NN
106           This matches a range of IPv6 addresses "A:B:.../NN".
107
108       pid:PID
109           (nbdkit ≥ 1.24, Linux only)
110
111           This matches the process ID "PID", if the client connects over a
112           Unix domain socket.
113
114           Note that process IDs are recycled so this alone is not secure
115           enough to ensure that only a single desired process can connect.
116           However you could use it as an additional check.
117
118       security:LABEL
119           (nbdkit ≥ 1.36, not Windows)
120
121           This matches the security context (usually the SELinux label, IPSEC
122           label or NetLabel) of the client.
123
124       uid:UID
125           (nbdkit ≥ 1.24)
126
127           This matches the numeric user ID "UID", if the client connects over
128           a Unix domain socket.
129
130       gid:GID
131           (nbdkit ≥ 1.24)
132
133           This matches the numeric group ID "GID", if the client connects
134           over a Unix domain socket.
135
136       vsock-cid:CID
137       vsock-port:PORT
138           (nbdkit ≥ 1.24)
139
140           These match the CID or port number for "AF_VSOCK" sockets.
141
142   Not filtered
143       If neither the "allow" nor the "deny" parameter is given the filter
144       does nothing.
145
146       Unix domain sockets and "AF_VSOCK" sockets were always unfiltered in
147       nbdkit ≤ 1.22.  In nbdkit ≥ 1.24 the ability to filter them was added.
148
149   Common patterns of usage
150       Permit known good connections and deny everything else:
151
152        nbdkit --filter=ip ... allow=good1,good2,... deny=all
153
154       Block troublemakers but allow everything else:
155
156        nbdkit --filter=ip ... deny=bad1,bad2,...
157

PARAMETERS

159       allow=addr[,...]
160           Set list of allow rules.  This parameter is optional, if omitted
161           the allow list is empty.
162
163       deny=addr[,...]
164           Set list of deny rules.  This parameter is optional, if omitted the
165           deny list is empty.
166

DEBUG FLAGS

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

FILES

174       $filterdir/nbdkit-ip-filter.so
175           The filter.
176
177           Use "nbdkit --dump-config" to find the location of $filterdir.
178

VERSION

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

AUTHORS

187       Richard W.M. Jones
188

COPYRIGHT

190       Copyright Red Hat
191

LICENSE

193       Redistribution and use in source and binary forms, with or without
194       modification, are permitted provided that the following conditions are
195       met:
196
197       •   Redistributions of source code must retain the above copyright
198           notice, this list of conditions and the following disclaimer.
199
200       •   Redistributions in binary form must reproduce the above copyright
201           notice, this list of conditions and the following disclaimer in the
202           documentation and/or other materials provided with the
203           distribution.
204
205       •   Neither the name of Red Hat nor the names of its contributors may
206           be used to endorse or promote products derived from this software
207           without specific prior written permission.
208
209       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
210       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
211       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
212       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
213       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
214       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
215       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
216       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
217       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
218       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
219       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
220
221
222
223nbdkit-1.36.2                     2023-11-26               nbdkit-ip-filter(1)