Deployment Option Reference

List of all available environment variables for the Shield container:

Core Configuration

Environment Variable	Possible Values	Default	Description
NULLAFI_SERVERMODE	[icap | api | web | alert | all]	all	Sets which services will run on the Shield container. ICAP server, API server, Web Management Console (which includes API), Alert server, or all at once (all is convenient for testing but not recommended for production).
NULLAFI_LICENSE_KEY_FILE	a valid path to a file	none	Passes the Nullafi Shield license information by reference to a file on the filesystem. Mutually exclusive with NULLAFI_LICENSE_KEY_VALUE. Nullafi Shield requires one of NULLAFI_LICENSE_KEY_FILE or NULLAFI_LICENSE_KEY_VALUE to exist but will only use one at a time.
NULLAFI_LICENSE_KEY_VALUE	any string of characters	none	Passes the Nullafi Shield license information by directly invoking the license key string. Mutually exclusive with NULLAFI_LICENSE_KEY_FILE. Nullafi Shield requires one of NULLAFI_LICENSE_KEY_FILE or NULLAFI_LICENSE_KEY_VALUE to exist but will only use one at a time.
NULLAFI_NODE_NAME	any string of characters	nullafi shield	When the Shield instance is configured as an enforcement node (NULLAFI_SERVERMODE is set to icap, api, or all), sets the name of the Shield instance to appear in the Web Management Console and Activity Log.
NULLAFI_LOG_LEVEL	[debug | info | warn | error ]	warn	Log level for the Shield container: debug, info, warn, error
NULLAFI_LOG_FILE_DIR	a valid path to a folder	./log	Sets the path to the log file
NULLAFI_LOG_TO_FILE	[true | false]	FALSE	By default sends the log information to the stdout.
NULLAFI_SHOWBUILD	[true | false]	TRUE	Determines whether the software build number is displayed in the Web Management Console
NULLAFI_SHOWDATE	[true | false]	FALSE	Determines whether the software build date is displayed in the Web Management Console

Database & Cache

Environment Variable	Possible Values	Default	Description
NULLAFI_REDIS_URI	a valid Redis URI	none	Sets the Web Management Console's configuration database location, including the protocol, credentials, hostname, and path for a Redis database accessible by the Web Management Console and all ICAP enforcement nodes.
NULLAFI_ACTIVITY_DATABASE_URL	a valid Elasticsearch or OpenSearch URL	none	Sets the Activity Database location, including the protocol, credentials, hostname, and path. When the driver in use is opensearch, then the NULLAFI_OPENSEARCH_* variables below apply.
NULLAFI_ACTIVITY_DATABASE_DRIVER	[elasticsearch | opensearch]	auto-detected	Forces the activity database driver. When omitted, Shield auto-detects: URLs ending in .es.amazonaws.com or .aoss.amazonaws.com resolve to opensearch; all other URLs resolve to elasticsearch. Explicitly setting this variable overrides auto-detection. (Available since 3.8.1)
NULLAFI_ACTIVITY_RING_BUFFER_SIZE	any number of records	1500	Size of the activity record ring buffer (~5 KB per record, 1500 records ≈ 8 MB)
NULLAFI_ELASTIC_CERTIFICATE_FINGERPRINT	a valid SHA256 hex fingerprint given by Elasticsearch on first launch	none	see https://www.elastic.co/guide/en/elasticsearch/reference/current/configuring-stack-security.html
NULLAFI_OPENSEARCH_AUTH_MODE	[none | basic | aws_iam]	none	Sets the authentication mode for the OpenSearch driver. Use basic for username/password authentication, or aws_iam to sign requests with AWS SigV4 (required for Amazon OpenSearch Service and OpenSearch Serverless). URLs matching the .es.amazonaws.com or .aoss.amazonaws.com pattern automatically default to aws_iam. (Available since 3.8.1)
NULLAFI_OPENSEARCH_REGION	a valid AWS region (e.g. us-east-1)	none	AWS region used for SigV4 request signing. Required when NULLAFI_OPENSEARCH_AUTH_MODE is aws_iam. When using an Amazon OpenSearch Service URL, the region is inferred from the hostname if this variable is not set. (Available since 3.8.1)
NULLAFI_OPENSEARCH_USERNAME	any string	none	OpenSearch username. Required when NULLAFI_OPENSEARCH_AUTH_MODE is basic. (Available since 3.8.1)
NULLAFI_OPENSEARCH_PASSWORD	any string	none	OpenSearch password. Required when NULLAFI_OPENSEARCH_AUTH_MODE is basic. (Available since 3.8.1)
NULLAFI_OPENSEARCH_SERVICE_NAME	es | aoss	es	AWS service name used for SigV4 signing. Set to aoss when connecting to Amazon OpenSearch Serverless (URLs ending in .aoss.amazonaws.com). This is set automatically when the URL pattern is detected and NULLAFI_OPENSEARCH_AUTH_MODE is aws_iam. (Available since 3.8.1)
NULLAFI_OPENSEARCH_INSECURE_SKIP_VERIFY	[true | false]	FALSE	Disables TLS certificate verification when connecting to OpenSearch. Intended for development and self-signed certificate environments only; do not use in production. (Available since 3.8.1)

Web Server Configuration

Environment Variable	Possible Values	Default	Description
NULLAFI_HTTP_PORT	[0-65535]	8080	Sets the listening port for plain text (HTTP) access to the Web Management Console. This is the container's listening port, and might be mapped through the host's network stack in several ways. By default, browsers use port 80 for HTTP and so it is common to map the host's port 80 to the container's 8080
NULLAFI_HTTPS_ENABLED	[true | false]	FALSE	Controls whether the Web Management Console will be offered with SSL encryption (via HTTPS).
NULLAFI_HTTPS_PORT	[0-65535]	8081	Sets the listening port for SSL encrypted (HTTPS) access to the Web Management Console. This is the container's listening port, and might be mapped through the host's network stack in several ways. By default, browsers use port 443 for HTTPS and so it is common to map the host's port 443 to the container's 8081
NULLAFI_HTTPS_ACME_CHALLENGE	[tls | dns | http | TLS-ALPN-01 | DNS-01 | HTTP-01 | false]	FALSE	Sets if Nullafi Shield will obtain a certificate for the Web Management Console using the ACME protocol service. See more in RFC8555
NULLAFI_HTTPS_ACME_SERVER_URL	a valid URL (should be a valid ACME v2 API endpoint)	https://acme-v02.api.letsencrypt.org/directory	ACME v2 API endpoint URL for signing HTTP certificates. The default value is the production directory URL for Let's Encrypt. For testing, you may use the Let's Encrypt staging server: https://acme-staging-v02.api.letsencrypt.org/directory
NULLAFI_HTTPS_ACME_DNS01_PROVIDER	a valid DNS provider name	none	The DNS Provider used by the Acme DNS-01 challenge automation process, see the options: https://go-acme.github.io/lego/dns/
NULLAFI_HTTPS_ACME_CERT_DIR	a valid path to a folder	./certs	Sets the path where ACME SSL certificates will be stored. This should be mounted to persistent storage to avoid excessive certificate generation attempts from container restarts.
NULLAFI_HTTPS_TLS_CERT_FILE	a path to the TLS certificate file (.crt)	none	Sets the certificate to be used for secure HTTPS connections to the Web Management Console. If not using the ACME protocol, Nullafi Shield can be configured to use specific certificates manually managed by the administrator. Ordinarily, these would be signed by the organization's private Certificate Authority.
NULLAFI_HTTPS_TLS_KEY_FILE	a path to the TLS key file (.pem)	none	Sets the private key to be used for secure HTTPS connections to the Web Management Console. If not using the ACME protocol, Nullafi Shield can be configured to use specific certificates manually managed by the administrator. Ordinarily, these would be signed by the organization's private Certificate Authority.
NULLAFI_HTTP_CUSTOM_DOMAIN	any valid hostname	localhost	Sets the custom domain for the web Web Management Console
~~NULLAFI_HTTPS_ENABLE_ACME~~			DEPRECATED - Use NULLAFI_HTTPS_ACME_CHALLENGE instead
~~NULLAFI_HTTPS_CERT_DIR~~			DEPRECATED - Use NULLAFI_HTTPS_ACME_CERT_DIR instead

ICAP Server Configuration

Environment Variable	Possible Values	Default	Description
NULLAFI_ICAP_PORT	[0-65535]	1344	Sets the TCP port for the ICAP protocol. This is the container's listening port, and might be mapped through the host's network stack in several ways.
NULLAFI_ICAP_READ_TIMEOUT	any number of seconds	120	ICAP read timeout in seconds
NULLAFI_ICAP_WRITE_TIMEOUT	any number of seconds	120	ICAP write timeout in seconds
NULLAFI_ICAP_MAX_CONNECTIONS	any number of connections	25 * CPU cores	Maximum concurrent ICAP connections
NULLAFI_ICAP_CONNECTION_QUEUE_MULTIPLIER	any number	3	Connection queue size multiplier
NULLAFI_ICAP_SHUTDOWN_TIMEOUT	any number of seconds	20	ICAP graceful shutdown timeout in seconds
NULLAFI_ICAP_BUFFER_SIZE_KB	any number	32	ICAP buffer size in KB
NULLAFI_ICAP_DISABLE_PREVIEW	[true | false]	FALSE	ICAP Preview Mode is an optimization feature that can yield significant performance improvements. Disable if your ICAP client does not support the feature.
NULLAFI_ICAP_PREVIEW_SIZE	any number of bytes	0	ICAP preview body size (measured in bytes) advertised in OPTIONS responses to ICAP clients
NULLAFI_ICAPS_ENABLED	[true | false]	FALSE	Sets the ICAP protocol to run on TLS
NULLAFI_ICAPS_PORT	[0-65535]	11344	Sets the TCP port for the ICAP protocol with TLS. This is the container's listening port, and might be mapped through the host's network stack in several ways.
NULLAFI_ICAP_TLS_CERT_FILE	a path to the TLS certificate file (.crt)	none	Sets the path to the certificate file for ICAPS protocol (ICAP with SSL).
NULLAFI_ICAP_TLS_KEY_FILE	a path to the TLS key file (.pem)	none	Sets the path to the key file for ICAPS protocol (ICAP with SSL).
NULLAFI_ICAP_MUTUAL_TLS_CLIENT_FILE	a path to the TLS certificate file	none	Sets client and server ICAP to use signed certificate to authenticate each other.

Proxy & API Configuration

Environment Variable	Possible Values	Default	Description
NULLAFI_PROXY_URL	a valid hostname or IP address and port combination, separated by a colon	none	Allows the Web Management Console to distribute a custom PAC file. End user devices can download the PAC file or point their automatic proxy settings to the PAC file download URL inside the Web Management Console. Valid examples: 192.168.0.254:8080, proxy.example.com:3128
NULLAFI_PROXY_CERT_FILE	a valid path to a file	none	Allows the Web Management Console to distribute the public key used by the Proxy to sign SSL certificates. End user devices can download the certificate for importing into their own trust store from the Web Management Console without authentication.
NULLAFI_API_KEY	any string of characters	none	Sets an API Key to be used by clients on Nullafi Shield API Requests

Logging & Monitoring

Environment Variable	Possible Values	Default	Description
NULLAFI_TRACER_ENDPOINT	a valid URL	none	A compatible OpenTelemetry tool URL (vendors: Splunk, Grafana, SolarWind, FluentBit, etc)
NULLAFI_SYSLOG_ACTIVITY_ENABLE	[true | false]	FALSE	Sets the log information to be sent to a SYSLOG service.
NULLAFI_SYSLOG_ACTIVITY_FACILITY	[ KERN | USER | MAIL | DAEMON | AUTH | SYSLOG | LPR | NEWS | UUCP | CRON | AUTHPRIV | FTP | LOCAL0 | LOCAL1 | LOCAL2 | LOCAL3 | LOCAL4 | LOCAL5 | LOCAL6 | LOCAL7 ]	LOCAL0	Labels for facility levels defined in RFC5424
NULLAFI_SYSLOG_ACTIVITY_NETWORK	[tcp | udp]	none	Sets the network protocol to be used by syslog
NULLAFI_SYSLOG_ACTIVITY_REMOTE_ADDRESS	a valid hostname or IP address and port combination, separated by a colon (e.g. 192.168.1.1:514, syslog.example.com:601)	none	Sets the syslog destination server and port

Authentication Cache Configuration

Environment Variable	Possible Values	Default	Description
NULLAFI_SAML_IDLE_SYNC_INTERVAL_SEC	any number of seconds	60	Interval in seconds for syncing idle times to Redis
NULLAFI_PROXY_USER_GROUP_CACHE_TTL_SEC	any number of seconds	300	TTL in seconds for cached user-to-group mappings in proxy mode

SAML Configuration

SAML is configured via the dashboard. Two independent SAML integrations are supported:

• Admin SAML — authenticates dashboard admin users (Configuration page)
• ICAP SAML — identifies users for ICAP traffic scanning (ICAP page)

Each SAML integration has a configurable Username Attribute that determines which SAML field is used as the username. The default is username. Set to NameID to use the SAML Subject (NameID) instead of an attribute from the AttributeStatement.