Controlling Access by IP Address

Supported starting with ManualWorks 6.0.18.

User IP access control allows or blocks the client IP addresses that can access ManualWorks. Use it when a server exposed to the internet should accept connections only from specific offices, VPNs, or operations networks.

Turn this feature on with a Setting Startup Script Options, and then configure it with Console commands. The default mode is allow mode. IP addresses can be single IPs, CIDR, wildcards, or ranges.

It works only when the startup script option 3rabbitz.enable_ip_filter is true. To use this feature, add -D3rabbitz.enable_ip_filter=true to the server startup options and restart ManualWorks.

Checking the Settings

Run the following command in the Console.

list-ip-filter

It shows whether IP access control is on, the access control mode, the registered IP addresses, whether proxy headers are trusted, and the proxy count. The proxy count is shown only when it is set.

Using Allow Mode

In allow mode, only requests from registered IP addresses can access ManualWorks. Requests from other IP addresses are blocked.

Run the following commands in the Console.

set-ip-filter-mode -mode allow
add-ip-filter -address 203.0.113.10
add-ip-filter -address 192.168.0.0/24

In this example, only requests from the single IP 203.0.113.10 and the range 192.168.0.0/24 are allowed.

When you use allow mode, register the IP address the administrator is currently using first. You can check your current IP address at /r/api/client_ip. If you do not register it, even the administrator might be unable to connect right after the change. /r/api/client_ip picks the IP in the same way as access control(the proxy header trust setting and the proxy count), so it shows the IP that access control uses. If proxy headers are not trusted, access control uses the IP connected directly to the server (the proxy server's IP if ManualWorks is behind a proxy). If you changed the proxy settings, check the IP again at /r/api/client_ip before you turn on allow mode.

Using Deny Mode

In deny mode, only requests from registered IP addresses are blocked. Requests from other IP addresses are allowed.

Run the following commands in the Console.

set-ip-filter-mode -mode deny
add-ip-filter -address 198.51.100.20
add-ip-filter -address 10.0.0.0/8

In this example, requests from the single IP 198.51.100.20 and the range 10.0.0.0/8 are blocked.

Removing IP Addresses

To remove a registered IP address, run the following command in the Console.

remove-ip-filter -address 203.0.113.10

To remove all registered IP addresses, run the following command.

clear-ip-filter

If the IP address list is empty, all requests are allowed regardless of the mode.

Using IP Access Control Behind a Proxy

If ManualWorks runs behind a load balancer or reverse proxy, the proxy server's IP might be treated as the client IP instead of the user's actual IP. If a trusted proxy passes the user's IP in a header such as X-Forwarded-For, run the following command.

trust-ip-filter-proxy

When proxy headers are trusted, ManualWorks checks headers such as X-Forwarded-For, Proxy-Client-IP, and WL-Proxy-Client-IP in order. If a header contains several IPs, the first one is used.

For requests that come through proxies, it is safer to also set the number of proxies in front of ManualWorks. Supported starting with ManualWorks 6.0.26.

set-ip-filter-proxy-count -count 1

The value that is the specified number of positions from the end of the X-Forwarded-For header is used as the client IP. Use 1 for a single proxy, or 2 for a load balancer followed by a reverse proxy. Only values of 1 or more are allowed.

To clear the proxy count, specify 0. The first value in the header is then used, as before.

set-ip-filter-proxy-count -count 0

If you do not set the proxy count, the first value in the header is used, as before. Clients can set the first value freely, so in allow mode an unregistered IP can pass by putting an allowed IP in the header. If you use IP access control behind a proxy, set the proxy count.

To stop trusting proxy headers, run the following command.

untrust-ip-filter-proxy

On a server that can be reached directly from the internet, it is safer not to trust proxy headers. Use the proxy header trust option only when a trusted load balancer or reverse proxy is in front.

The proxy header trust and proxy count settings apply to the allowed IP check set for each API and to /r/api/client_ip, even if 3rabbitz.enable_ip_filter is not turned on. If you use allowed IPs for APIs behind a proxy, run trust-ip-filter-proxy and set-ip-filter-proxy-count. If proxy headers are not trusted, the IP that called the API is taken to be the proxy server's IP.

Supported IP Formats

The following formats are supported.

The add-ip-filter command registers the value as entered without checking its format. Invalid IP addresses or CIDR formats never match.