Skip to content

Frequently Asked Questions

Common questions from administrators about deploying, configuring, and managing Nullafi Shield.

What is the difference between NULLAFI_LICENSE_KEY_FILE and NULLAFI_LICENSE_KEY_VALUE?

Both variables pass your Shield license, but they do so differently and are mutually exclusive — only set one of them.

  • NULLAFI_LICENSE_KEY_VALUE — pass the raw license key string directly as an environment variable value. This is the simplest option.
  • NULLAFI_LICENSE_KEY_FILE — pass a path to a file that contains the license key. This is useful when you want to keep the key out of your .env file or compose definition (e.g., using Docker secrets or a mounted volume).

Shield will fail to start if neither variable is set. See the Deployment Option Reference for the full parameter list.

What does NULLAFI_SERVERMODE do, and which value should I use?

NULLAFI_SERVERMODE controls which services run inside a given Shield container. The available values are:

Value What runs
all Admin Console, ICAP enforcement, API enforcement, and Alert — all in one container. Default. Good for testing.
web Admin Console only. The management interface for administrators.
icap ICAP enforcement node only. Scans traffic forwarded by a proxy.
api API enforcement node only. Accepts REST calls to /scan or /scan-dynamic.
alert Alert node only. Runs scheduled queries against the Activity Database and sends notifications.

For production, it is recommended to separate concerns: run one web instance for administration, and one or more icap (or api) instances for enforcement. A single web instance can support many enforcement nodes. All nodes must share the same Redis and Elasticsearch databases.

How do I log in to the Admin Console for the first time?

When you access the Admin Console URL in your browser for the first time after deployment, Shield will prompt you to create an administrator username and password. There are no default credentials — you set them on first access.

After that initial setup, you can optionally switch to SAML-based authentication through your organization's Identity Provider under Configuration → General → Dashboard Security. This is recommended for production so that multiple administrators do not share a single password.

Note

The databases (Redis and Elasticsearch) take a minute or two to initialize on first run. If you see a "missing database" warning immediately after starting the containers, wait briefly and refresh.

How do I enable HTTPS for the Admin Console?

HTTPS is disabled by default. There are two ways to enable it:

Option A — Let's Encrypt (ACME): Set NULLAFI_HTTPS_ENABLE_ACME=true. Shield will automatically obtain a certificate for the domain set in NULLAFI_HTTP_CUSTOM_DOMAIN. This requires the host to be publicly reachable on port 80 for the ACME challenge. Store certs in a persistent location using NULLAFI_HTTPS_CERT_DIR to avoid hitting rate limits on container restarts.

Option B — Bring your own certificate: Set NULLAFI_HTTPS_ENABLED=true and point NULLAFI_HTTPS_TLS_CERT_FILE and NULLAFI_HTTPS_TLS_KEY_FILE to your certificate and key files (mounted into the container via a volume). This is the right approach for hosts not reachable from the internet or where your internal CA is used.

In both cases, the container's HTTPS port defaults to 8081, typically mapped to the host's port 443.

Elasticsearch won't start — what should I check first?

The most common cause on Linux is the kernel's virtual memory limit being too low. Elasticsearch requires a higher vm.max_map_count than the default on some distributions (Ubuntu 22.04 defaults to 65,530, for example).

Check the current value: 

cat /proc/sys/vm/max_map_count

Set it temporarily (until reboot): 

sudo sysctl -w vm.max_map_count=262144

Make it permanent by adding the following to /etc/sysctl.conf and running sudo sysctl -p: 

vm.max_map_count=262144

Also check that the host has sufficient free disk space (df -h) — Elasticsearch will refuse to start or write if the disk is too full.

Why is my Activity Log empty even though traffic is flowing?

Work through this checklist:

  1. Activity logging is disabled globally — Go to Configuration → General and confirm Enable Activity Log is turned on.
  2. Elasticsearch is unreachable — Check that all Shield nodes can reach the Elasticsearch host on TCP port 9200. Verify NULLAFI_ACTIVITY_DATABASE_URL is set correctly on all nodes.
  3. No matching rules — The Activity Log records transactions only when at least one Shield rule is active and matched. Confirm your rules are enabled under Policy → Rules.
  4. Traffic is not passing through the proxy — Shield only sees traffic routed through its ICAP or API interface. Confirm that client traffic is actually reaching the proxy, and that the proxy is forwarding to Shield.
  5. Data not yet refreshed — The Activity page is not a live view. Click the Refresh button (↺) at the top of the Activity page to load the latest records.
How does rule priority work when a transaction matches more than one rule?

Rules are evaluated in the order they appear in the Policy → Rules table. The table cannot be sorted freely — the display order is the priority order.

When a transaction matches more than one rule, the last matching rule takes precedence. This means more specific rules should be placed lower in the list so they are not overridden by more general ones above them.

You can use the Enable/Disable toggle on individual rules (via the three-dot menu) to temporarily suspend a rule without deleting it, which is useful for testing priority changes.

How do I apply policies to specific users or groups instead of everyone?

User- and group-based rules require two things to be set up:

  1. Directory integration — Connect Shield to your user directory (Google, Azure/Entra, Okta, or LDAP) under Configuration → Directory. This gives Shield a way to resolve group membership.
  2. Proxy authentication — The proxy must pass identity information to Shield via ICAP headers. Configure the Username Header and Group Header fields under Configuration → ICAP → Headers to match the headers your proxy inserts.

Once both are in place, you can add Users and Groups criteria to any Rule under Policy → Rules. Multiple criteria in the Users and Groups section are evaluated as logical OR — a user matching any one of them will have the rule applied.

If directory integration is not configured, Shield can still enforce global policy (rules that apply to all users equally).

What is the correct ICAP URL to give my proxy when configuring Shield as an ICAP server?

Use one of these formats depending on the mode your proxy uses:

Mode URL format Example
Response modification (RESPMOD) icap://<host>:<port>/respmod icap://shield.example.com:1344/respmod
Request modification (REQMOD) icap://<host>:<port>/reqmod icap://shield.example.com:1344/reqmod

The default ICAP port is 1344 (plain) or 11344 (ICAP over SSL / ICAPS). These are configurable via NULLAFI_ICAP_PORT and NULLAFI_ICAPS_PORT.

Shield is broadly compatible with any standards-compliant ICAP client. See the ICAP Integrations section for vendor-specific configuration guides.

Can I run multiple Shield instances, and how do they stay synchronized?

Yes. All Shield nodes (web, icap, alert) share state through the Redis configuration database and Elasticsearch activity database. As long as every node points to the same Redis instance (NULLAFI_REDIS_URI) and the same Elasticsearch instance (NULLAFI_ACTIVITY_DATABASE_URL), they will automatically stay in sync.

For distributed deployments, keep these points in mind:

  • Each ICAP or API enforcement node should have a unique NULLAFI_NODE_NAME so it is identifiable in the Admin Console and Activity Log.
  • A single web instance can support an arbitrary number of enforcement nodes.
  • In geographically distributed deployments, it is best practice to run enforcement nodes close to end users (to reduce latency) while centralizing the web and alert instances.
How do I update Shield to a new version?

Updating uses standard Docker container replacement. Two commands are sufficient:

docker-compose pull
docker-compose up -d

pull downloads the latest image. Running up -d a second time restarts only the containers whose images have changed, leaving unaffected services running. To clean up old images afterward:

docker image prune

Check the release notes before updating in case a version requires pre-upgrade steps.

How do I distribute the proxy certificate and PAC file to end users?

Shield can serve both assets directly from the Admin Console without requiring users to authenticate:

  • Proxy certificate — Set NULLAFI_PROXY_CERT_FILE to the path of the proxy's public certificate file (mounted into the container). A Download Certificate button will appear in Configuration → ICAP → Proxy Configuration for users to install it into their browser or OS trust store.
  • PAC file — Set NULLAFI_PROXY_URL to the proxy's hostname and port (e.g., proxy.example.com:3128). Shield generates a PAC file based on your Application definitions. Users can download it directly or configure their OS/browser to fetch it from the PAC File URL shown in the same section.
How do I send Shield activity data to my SIEM?

Shield can forward activity events via syslog. Set the following environment variables on each Shield node:

Variable Purpose
NULLAFI_SYSLOG_ACTIVITY_ENABLE Set to true to enable syslog output
NULLAFI_SYSLOG_ACTIVITY_REMOTE_ADDRESS Destination syslog server and port (e.g., syslog.example.com:514)
NULLAFI_SYSLOG_ACTIVITY_NETWORK Transport protocol: tcp or udp
NULLAFI_SYSLOG_ACTIVITY_FACILITY Syslog facility label (default: LOCAL0)

A common pattern is to run a syslog container (e.g., syslog-ng) on the same Docker host as Shield, then configure that syslog agent to route events to your SIEM. This keeps Shield's configuration simple while leveraging the full routing and filtering capabilities of dedicated syslog software.

You can also connect an OpenTelemetry-compatible tool (Splunk, Grafana, SolarWinds, FluentBit, etc.) via NULLAFI_TRACER_ENDPOINT.

How do I create a custom data type for proprietary or company-specific data?

Shield's built-in data types cover most common sensitive data formats. For proprietary data, you can define your own:

  1. Navigate to Policy → Data Types in the Admin Console.
  2. Click Add New Data Type.
  3. Fill in a Type (machine-readable identifier), a Name (human-friendly label), and an optional description.
  4. Add one or more regular expression definitions that match the pattern of your data.
  5. Click Save.

Your custom data type will then be available to select in Obfuscations, just like built-in types.

Tip

If your data has complex formatting requirements (e.g., structured JSON), the Advanced Settings option on each definition can help. Contact Nullafi Support for assistance with complicated patterns.

How do I generate and manage API keys for programmatic access to Shield?
  1. Go to Configuration → API Keys in the Admin Console.
  2. Click Generate API Keys to create a new key.
  3. Copy and store the key immediately — Shield does not store it after the page is dismissed.

You can have up to two active API keys at a time. To revoke a key, return to the same page and delete it.

The full API reference (Swagger UI) is available at https://<your-shield-hostname>/swagger/index.html and is also linked from the API Keys configuration page. Use the NULLAFI_API_KEY environment variable to set a key at container startup instead of generating one through the UI.