filters/ip/nbdkit-ip-filter.pod

   1 =head1 NAME
   2
   3 nbdkit-ip-filter - filter clients by IP address, process ID, user ID
   4 or group ID
   5
   6 =head1 SYNOPSIS
   7
   8  nbdkit --filter=ip PLUGIN [allow=addr[,addr...]]
   9                            [deny=addr[,addr...]]
  10
  11 =head1 DESCRIPTION
  12
  13 C<nbdkit-ip-filter> can allow or deny client connections by their IP
  14 address.  Usually it is better to control this outside nbdkit, for
  15 example using TCP wrappers or a firewall, but this filter can be used
  16 if these are not available.
  17
  18 nbdkit E<ge> 1.24 added the ability to filter clients connecting over
  19 Unix domain sockets by client process ID, user ID and group ID.  Also
  20 this version added support for filtering C<AF_VSOCK> sockets by peer
  21 CID or port.
  22
  23 =head1 EXAMPLES
  24
  25 =head2 Filter by IP address
  26
  27  nbdkit --filter=ip [...] allow=127.0.0.1,::1 deny=all
  28
  29 Allow clients to connect on the loopback IPv4 or loopback IPv6
  30 address, deny all other clients.
  31
  32  nbdkit --filter=ip [...] deny=8.0.0.0/8
  33
  34 Allow any client except connections from the IPv4 C<8.0.0.0/8>
  35 network.
  36
  37  nbdkit --filter=ip [...] allow=anyipv6 deny=all
  38
  39 Allow IPv6 clients to connect from anywhere, deny all other sources.
  40
  41 =head2 Filter by Unix domain socket peer
  42
  43  nbdkit -U $tmpdir/sock --filter=ip [...] allow=uid:`id -u` deny=all
  44
  45 Only allow the current user (S<C<id -u>>) to connect over the socket.
  46
  47 Layer extra security by creating the socket inside a temporary
  48 directory only accessible by the user.
  49
  50  nbdkit -U $tmpdir/sock --filter=ip [...] allow=gid:`id -g` deny=all
  51
  52 Allow anyone in the same group as the current user to connect to the
  53 Unix domain socket.
  54
  55 As in the previous example, layer extra security by creating the
  56 socket inside a temporary directory only accessible by the group.
  57
  58 =head1 RULES
  59
  60 When a client connects, this filter checks its source address against
  61 the allow and deny lists as follows:
  62
  63 =over 4
  64
  65 =item 1
  66
  67 If the address matches any in the allow list, permission is granted.
  68
  69 =item 2
  70
  71 If the address matches any in the deny list, permission is denied.
  72
  73 =item 3
  74
  75 Otherwise permission is granted.
  76
  77 =back
  78
  79 If either the C<allow> or C<deny> parameter is not present then it is
  80 assumed to be an empty list.  The order in which the parameters appear
  81 on the command line does not matter; the allow list is always
  82 processed first and the deny list second.
  83
  84 The C<allow> and C<deny> parameters each contain a comma-separated
  85 list of any of the following:
  86
  87 =over 4
  88
  89 =item B<all>
  90
  91 =item B<any>
  92
  93 These keywords (which both have the same meaning) match any source.
  94
  95 =item B<allipv4>
  96
  97 =item B<anyipv4>
  98
  99 These keywords match any IPv4 address.
 100
 101 =item B<allipv6>
 102
 103 =item B<anyipv6>
 104
 105 These keywords match any IPv6 address.
 106
 107 =item B<allunix>
 108
 109 =item B<anyunix>
 110
 111 These keywords match any connection over a Unix domain socket.
 112
 113 =item B<allvsock>
 114
 115 =item B<anyvsock>
 116
 117 These keywords match any connection over an C<AF_VSOCK> socket.
 118
 119 =item AB<.>BB<.>CB<.>D
 120
 121 This matches the single IPv4 address C<A.B.C.D>, for example
 122 C<127.0.0.1>.
 123
 124 =item AB<.>BB<.>CB<.>DB</>NN
 125
 126 This matches the range of IPv4 addresses C<A.B.C.D/NN>, for example
 127 C<192.168.2.0/24> or C<10.0.0.0/8>.
 128
 129 =item AB<:>BB<:>...
 130
 131 This matches the single IPv6 address C<A:B:...>.  The usual IPv6
 132 address representations can be used (see S<RFC 5952>).
 133
 134 =item AB<:>BB<:>...B</>NN
 135
 136 This matches a range of IPv6 addresses C<A:B:.../NN>.
 137
 138 =item B<pid:>PID
 139
 140 (nbdkit E<ge> 1.24, Linux only)
 141
 142 This matches the process ID C<PID>, if the client connects over a Unix
 143 domain socket.
 144
 145 Note that process IDs are recycled so this alone is not secure enough
 146 to ensure that only a single desired process can connect.  However you
 147 could use it as an additional check.
 148
 149 =item B<uid:>UID
 150
 151 (nbdkit E<ge> 1.24)
 152
 153 This matches the numeric user ID C<UID>, if the client connects over a
 154 Unix domain socket.
 155
 156 =item B<gid:>GID
 157
 158 (nbdkit E<ge> 1.24)
 159
 160 This matches the numeric group ID C<GID>, if the client connects over
 161 a Unix domain socket.
 162
 163 =item B<vsock-cid:>CID
 164
 165 =item B<vsock-port:>PORT
 166
 167 (nbdkit E<ge> 1.24)
 168
 169 These match the CID or port number for C<AF_VSOCK> sockets.
 170
 171 =back
 172
 173 =head2 Not filtered
 174
 175 If neither the C<allow> nor the C<deny> parameter is given the filter
 176 does nothing.
 177
 178 Unix domain sockets and C<AF_VSOCK> sockets were always unfiltered in
 179 S<nbdkit E<le> 1.22>.  In S<nbdkit E<ge> 1.24> the ability to filter
 180 them was added.
 181
 182 =head2 Common patterns of usage
 183
 184 Permit known good connections and deny everything else:
 185
 186  nbdkit --filter=ip ... allow=good1,good2,... deny=all
 187
 188 Block troublemakers but allow everything else:
 189
 190  nbdkit --filter=ip ... deny=bad1,bad2,...
 191
 192 =head1 PARAMETERS
 193
 194 =over 4
 195
 196 =item B<allow=>addr[B<,>...]
 197
 198 Set list of allow rules.  This parameter is optional, if omitted the
 199 allow list is empty.
 200
 201 =item B<deny=>addr[B<,>...]
 202
 203 Set list of deny rules.  This parameter is optional, if omitted the
 204 deny list is empty.
 205
 206 =back
 207
 208 =head1 FILES
 209
 210 =over 4
 211
 212 =item F<$filterdir/nbdkit-ip-filter.so>
 213
 214 The filter.
 215
 216 Use C<nbdkit --dump-config> to find the location of C<$filterdir>.
 217
 218 =back
 219
 220 =head1 VERSION
 221
 222 C<nbdkit-ip-filter> first appeared in nbdkit 1.18.
 223
 224 =head1 SEE ALSO
 225
 226 L<nbdkit(1)>,
 227 L<nbdkit-exitlast-filter(1)>,
 228 L<nbdkit-exitwhen-filter(1)>,
 229 L<nbdkit-limit-filter(1)>,
 230 L<nbdkit-filter(3)>.
 231
 232 =head1 AUTHORS
 233
 234 Richard W.M. Jones
 235
 236 =head1 COPYRIGHT
 237
 238 Copyright Red Hat