Skip to content

Deployment

Technical requirements

Nullafi Shield requires minimal resources to deploy, although requirements increase according to the scale of the deployment. The following list is sufficient for a typical customer.

Server Requirements

  • Linux host with Docker or compatible container runtime
    • [OPTIONAL] Docker Compose for ease of configuration and management
  • At least 1GB RAM and 2GB storage

Other Services

  • ICAP Client
    • Any typical proxy server can be configured as an ICAP client for Response Modification
      • Secure Web Gateways are commonly already processing user traffic
  • [OPTIONAL] User/Group directory
    • Without directory integration, Nullafi Shield can be configured with global policy that applies to all users
    • Directory integration requires that the proxy be configured to authenticate users, and to modify HTTP headers in ICAP connections to include user/group information

Network Environment

  • User traffic flowing through the proxy
    • In the case of an already-in-use proxy, like Squid Proxy, do the configuration as an ICAP client
    • Also, do the client browser configuration (via PAC file or other methodology)
      • Connectivity from client devices to the Squid Proxy (on any port; default is 3128)
      • Connectivity from the Squid Proxy to any web applications to be used (typically ports 80 and/or 443)
      • [OPTIONAL] certificate signed by a trusted CA for use by the Squid Proxy, or acceptance of Squid’s self-signed certificate
  • ICAP connections from proxy to ICAP server
    • Connectivity from proxy to Nullafi Shield on at least one port (typically 1344) for plain text ICAP connections
    • [OPTIONAL] connectivity from proxy to Nullafi Shield on an additional port for SSL encrypted ICAP connections
  • Administration Console access connectivity from administrator’s PC to Nullafi Shield
    • HTTPS for SSL encrypted configuration management (typically 443)
    • HTTP for plain text configuration management (typically 80)

Software requirements

Nullafi Shield is distributed in a containerized form factor. Without getting into the complexities of the many options regarding container runtimes and host operating systems, Nullafi tests with containerd. If you’re not intimately familiar with container runtimes and the difference between OCI and CRI and a hundred other acronyms, it’s enough to know that you can use Docker and Kubernetes with Nullafi Shield. If you are familiar with those terms, then you don’t need us to tell you how to make it work.

For any configuration examples going forward in this document, we’ll assume you are using Docker (in fact, we’ll use Docker Compose yaml format because it’s fairly easy to read) and leave any translation from that to other tools to you.

Deployment

Using a simple Docker Compose file, it is easy to bring up an instance of Nullafi Shield in your environment. There are a few mandatory configuration parameters which must be included when the container is started. Other options are configurable but not required; Shield will use default values if they are not specified. These are documented below in the Container Options section.

The sample Docker Compose file below can be used to start an instance of Nullafi Shield by issuing the command docker-compose up -d “up” tells Docker Compose to start the containers referenced in the comose file, and “-d” says to run in Detached mode.

Docker-Compose

A quick tour of the Compose file: - Some of these settings need to be coordinated with anything else that might be running on your host server - The network named “default” is fairly plain but could conflict with other settings - Restart policies should be coordinated with your container orchestration - Listening ports (especially 80 and 443) should be checked to ensure that they don’t conflict with other running services - Creating a container name and hostname are not required but can make administrative tasks easier - Ports - Port 1344 is the ICAP protocol port - Port 8080 is the default port for the Web Management Console (plain text http) - Port 8081 is the default port for a secure connection to the Web Management Console (https) - The “nullafi-data'' volume will be managed by Docker and is mapped to the container’s /apps/nullafi/data path. It provides persistent storage for Shield’s configuration files and Activity log. - The “${CONTAINER_DIR}/nullafi/user-data'' volume is local storage on the Docker host and is mapped to the container’s /apps/nullafi/user-data path. It provides a way to pass the license key to Shield. - ${CONTAINER_DIR} is a reference to an environment variable. If used, the environment variable must be passed to the container. See Docker for more information - To avoid using environment variables, a path will need to be hard coded into the Compose file. For example, if the license key is in the user’s home directory (~/key-dir/license.key) then the volume line in the Docker Compose file would be - /home/user/key-dir:/apps/nullafi/user-data - The environment settings set the Web Management Console’s username and password, and the locations for Shield’s license key file and data directory.

Example

version: "3.7"

networks:
  default:
    driver: bridge

services:
# Nullafi Shield
  nullafi:
    image: nullafi/shield:latest
    container_name: nullafi
    hostname: nullafi
    restart: unless-stopped
    networks:
      - default
    ports:
      - "1344:1344"
      - "80:8080"
      - "443:8081"
    volumes:
      - nullafi-data:/apps/nullafi/data
      - ${CONTAINER_DIR}/nullafi/user-data:/apps/nullafi/user-data
    environment:
      NULLAFI_USERNAME: "admin"
      NULLAFI_PASSWORD: "123456"
      NULLAFI_LICENSE_KEY_FILE: "/apps/nullafi/user-data/license.key"
      NULLAFI_DATABASE_DIR: "/apps/nullafi/data"

volumes:
  nullafi-data:

Product Updates

Standard practices for managing containers include the concept of replacing containers rather than upgrading them. When new versions of Nullafi Shield become available, upgrading is as simple as downloading the new container image and then redeploying from your deployment script. When using Docker Compose to deploy and upgrade, an upgrade can be accomplished in two commands:

docker-compose pull
docker-compose up -d

Pull tells Docker to go get the new image. Running “up -d” a second time will only recreate changed images (so if your compose file defines many containers and services, it will only stop and restart images that have changed since the last “up -d” run.

Optionally, you might use:

docker image prune

to remove obsolete images.

Container Options

List of all available environment variables for the container:

Environment Variable Possible Values Default Description
NULLAFI_USERNAME any string of characters none Sets the username for full administrative privileges to the Web Management Console
NULLAFI_PASSWORD any string of characters none Sets the password for full administrative privileges to the Web Management Console
NULLAFI_LICENSE_KEY_FILE a path to the license key file none The license key file provided to you by the Nullafi team. You can use the ./user-data folder to map a volume with the file.
NULLAFI_API_KEY any string of characters none Sets an API Key to be used by clients on Nullafi Shield API Requests
NULLAFI_DATABASE_DIR a valid path to a folder ./data Sets the path to the database file
NULLAFI_ACTIVITY_DATABASE_DIR a valid path to a folder ./activity-data Sets the path to the activity database file
NULLAFI_SERVERMODE [icap | web | both] both Sets how services should run on that instance, just the ICAP server, just the web Web Management Console or both.
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_ICAP_PORT [0-65535] 1344 Sets the TCP port for the ICAP protocol
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
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_CERT_DIR a valid path to a folder ./certs Sets the path to the certificates folder
NULLAFI_HTTPS_ACME_SERVER_URL a valid URL none ACME directory URL for signed HTTP exchange certificates.
NULLAFI_VERBOSE_LOG [true | false] true Sets the product to print all information
NULLAFI_HTTP_CUSTOM_DOMAIN any valid domain localhost Sets the custom domain for the web Web Management Console
NULLAFI_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_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_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.
NULLAFI_HTTPS_ENABLE_ACME [true | false] false Sets if Nullafi will use a self-signed certificate from an ACME protocol service. See more in RFC8555
NULLAFI_SYSLOG_ACTIVITY_ENABLE [true | false] false Sets the log information to be sent to a SYSLOG service.
NULLAFI_SYSLOG_ACTIVITY_FACILITY [ kernel | user-level | mail | system | security/authorization | syslogd | line printer | network news | UUCP | clock | security/authorization | FTP | NTP | log audit | log alert | local0 | local1 | local2 | local3 | local4 | local5 | local6 | local7 ] local0 Labels for facility levels defined in RFC3164