The IP whitelist feature restricts which IP addresses can connect to the Debian Agent API.
When enabled, only requests from whitelisted IP addresses or CIDR ranges are allowed.
All other connections are rejected with a403 Forbiddenresponse.
This provides an additional layer of security beyond mTLS authentication.
¶ Manual Configuration
Basic Configuration
Add the following to /etc/debian-agent/config.json:
{ "security": { "enable_ip_whitelist": true, "ip_whitelist": [ "192.168.1.0/24", "10.0.0.50" ] }}
Configuration Options
| Field | Type | Default | Description |
|---|---|---|---|
enable_ip_whitelist |
boolean | false |
Enable or disable IP-based access control |
ip_whitelist |
array | RFC 1918 | List of allowed IP addresses and CIDR ranges |
Default Behavior When Disabled (enable_ip_whitelist: false)
All IP addresses can connect (subject to mTLS authentication for API endpoints).
When Enabled with Empty List
If enable_ip_whitelist is true but ip_whitelist is empty or not specified, the agent defaults to RFC 1918 private networks:
{ "security": { "enable_ip_whitelist": true }}
This automatically allows:
| Network | Description |
|---|---|
10.0.0.0/8 |
Class A private network (16 million addresses) |
172.16.0.0/12 |
Class B private network (1 million addresses) |
192.168.0.0/16 |
Class C private network (65,536 addresses) |
127.0.0.0/8 |
Loopback (localhost) |
::1/128 |
IPv6 loopback |
This default configuration is suitable for most internal deployments where the agent should only be accessible from private networks.
¶ Manual Configuration Examples
Example 1: Private Networks Only (Default)
Allow connections only from RFC 1918 private networks:
{ "security": { "enable_ip_whitelist": true }}
Example 2: Specific Management Server
Allow only your central management server:
{ "security": { "enable_ip_whitelist": true, "ip_whitelist": [ "192.168.1.100", "127.0.0.1" ] }}
Example 3: Management Subnet
Allow an entire management VLAN:
{ "security": { "enable_ip_whitelist": true, "ip_whitelist": [ "10.10.50.0/24", "127.0.0.1" ] }}
Example 4: Multiple Networks
Allow multiple networks and specific IPs:
{ "security": { "enable_ip_whitelist": true, "ip_whitelist": [ "192.168.1.0/24", "192.168.2.0/24", "10.0.0.0/8", "172.16.100.50", "127.0.0.1", "::1" ] }}
Example 5: IPv6 Support
Include IPv6 addresses and ranges:
{ "security": { "enable_ip_whitelist": true, "ip_whitelist": [ "192.168.1.0/24", "127.0.0.1", "::1", "fd00::/8", "2001:db8:1234::100" ] }}
Example 6: Disable Whitelist (Allow All)
To disable IP restrictions entirely:
{ "security": { "enable_ip_whitelist": false }}
¶ Integration with Reverse Proxy
When using a reverse proxy (nginx), the IP whitelist checks the real client IP extracted from proxy headers.
Configuration
{ "proxy": { "enabled": true, "trusted_proxies": ["127.0.0.1", "::1"] }, "security": { "enable_ip_whitelist": true, "ip_whitelist": [ "192.168.1.0/24", "10.0.0.0/8" ] }}
How It Works
- Client (
192.168.1.50) connects to nginx - Nginx forwards request to agent with
X-Real-IP: 192.168.1.50 - Agent's
RealIPmiddleware extracts192.168.1.50(only if nginx IP is intrusted_proxies) - IP whitelist checks
192.168.1.50againstip_whitelist - Request is allowed (IP is in
192.168.1.0/24)
Important
- The proxy's IP (
127.0.0.1) does not need to be inip_whitelist - The proxy's IP must be in
trusted_proxiesfor real IP extraction - The client's real IP is checked against
ip_whitelist
¶ Security Recommendations
1. Always Include Localhost
Include 127.0.0.1 to allow local CLI commands:
{ "ip_whitelist": ["192.168.1.0/24", "127.0.0.1"]}
2. Use Smallest Possible Range
Prefer specific IPs or small subnets over large ranges:
- Good - specific management server
"ip_whitelist": ["192.168.1.100"] - Acceptable - management subnet
"ip_whitelist": ["192.168.1.0/24"] - Avoid - too broad
"ip_whitelist": ["0.0.0.0/0"]
3. Combine with mTLS
IP whitelist is a complement to mTLS, not a replacement:
- IP Whitelist: Network-level restriction (where can connect from)
- mTLS: Identity verification (who is connecting)
Both should be enabled for production deployments.
¶ Using Artica Web console
If you manage an Artica as client.
- On the left menu, choose
Your System > Web API Service - Click on “Parameters” on the Network Agent widget
- Set the list of whitelisted addresses and networks separated by a comma inside the “Trusted Networks” field
