Whitelisting and blacklisting by IP address

IP Access

Preliminaries

This note describes how to configure the server to restrict incoming requests from selected IP addresses.

Access to the server can be selectively enabled based on the IP address of the requestor. This is a handy feature when a single user or small team is actively working on the website before its official launch. This scenario is called whitelisting.

Access to the server can also be selectively disabled by IP address. This may be desirable when the server is being abused by a user arriving through a well-known IP address. This scenario is called blacklisting.

Both forms of IP access configuration involve IP4 addresses only; the server does not support incoming IP6 addresses. A range of addresses may be specified using CIDR notation.

Use of this feature for whitelisting, during website development, is considered to be a good practice. Use in a production environment, for blacklisting, can provide temporary relief from bad actors.

Configuration

Configuring the server for IP whitelisting is done by defining an ip-access section and adding one or more allow entries. Each entry may be either a single IP4 address, or an IP4 range specified using CIDR notation. The special value 0.0.0.0/0 can be used to allow all addresses.

Configuring the server for IP blacklisting is done by defining an ip-access section and adding one or more deny entries. Each entry may be either a single IP4 address, or an IP4 range specified using CIDR notation. The special value 0.0.0.0/0 can be used to deny all addresses.

Specifying both allow and deny entries together is not permitted.

Module

The ip-access module must be on to be effective.

Placement

The ip-access configuration section may appear in either the server section or a host section. When values occur in both the server and host sections, they are merged according to the standard rules defined for the merge attribute.

Information Headers

When an address is blocked, either because it is blacklisted, or because it is not whitelisted, an rw-ip-access information header is added, and the server responds with a status code of 403.

EBNF

SP ::= U+20
CR ::= U+0D
SOLIDUS ::= U+2F
LEFT-CURLY-BRACKET ::= U+7B
RIGHT-CURLY-BRACKET ::= U+7D
unsigned-number ::= 0..255
ip4-address ::= unsigned-number '.' unsigned-number '.' unsigned-number '.' unsigned-number
cidr-range ::= SOLIDUS 0..32
allow-entry ::= 'allow' SP ip4-address cidr-range? CR
deny-entry ::= 'deny' SP ip4-address cidr-range? CR
ip-access-section ::= 'ip-access' SP LEFT-CURLY-BRACKET CR
(allow-entry | deny-entry)*
RIGHT-CURLY-BRACKET CR

Cookbook

Example 1: ip-access ignored
server {
modules {
ip-access off
}
}
Example 2: deny everyone
server {
modules {
ip-access on
}
ip-access {
deny 0.0.0.0/0
}
}
Example 3: deny a few bad actors
server {
modules {
ip-access on
}
ip-access {
deny 100.200.30.4
deny 100.200.50.6
deny 100.200.80.9
deny 180.210.70.4
deny 180.210.70.6
deny 180.210.70.9
}
}
Example 4: allow single users
server {
modules {
ip-access on
}
ip-access {
allow 100.200.30.4
allow 180.210.70.9
}
}
Example 5: allow range of users
server {
modules {
ip-access on
}
ip-access {
allow 100.200.0.0/16
allow 180.210.70.0/24
}
}

Review

Key points to remember:

  • Using IP addresses to allow selected individuals to access the server can be useful during website development.
  • Using IP addresses to restrict access to the server can provide temporary relief from bad actors, but comprehensive IP blacklists are too wieldy to be useful, and other strategies should be pursued.

Whitelisting and blacklisting by IP address