Configure SpamFoo Client

SpamFoo Client reads some settings from environment variables, command-line options, a settings file, and a few files in its data directory when it starts. This page lists those settings and their defaults. Settings you change on System > Settings in the admin console, or with the settings API, are listed in Read and Change Settings.

If you use SmarterMail, it does most of this configuration for you, including the license, folders, and updates. See Set Up SmarterMail.

How Settings Are Applied

Environment variables, command-line options, and the settings file: read when SpamFoo Client starts. Restart SpamFoo Client after you change one.
The license key file and the proxy secret file: changes are picked up while SpamFoo Client runs in some cases. See License Key and Proxy Secret.
Settings page and settings API: changes apply right away. Saving the Settings page saves every value shown on it, not just the one you changed. See Read and Change Settings.

When the same setting is set in more than one place, SpamFoo Client uses the first one it finds in this order:

A value saved on the Settings page or with the settings API
An environment variable
A line in the settings file
A command-line option, or a file in the etc folder of the data directory
The default

There are two exceptions:

The --mode, --port, and --conf command-line options win over their environment variables and the settings file.
When the SPAMFOO_GPU environment variable is set, it overrides the GPU Acceleration switch on the Settings page.

If a setting has a value SpamFoo Client can't use, such as an unknown mode or a port that isn't a number, SpamFoo Client prints a line that starts with FATAL and stops with exit code 78. See It Stops With a Settings Error.

Mode

SpamFoo Client runs in one of two modes. The mode is set when it starts, with SPAMFOO_MODE or --mode.

Embedded (the default): the mode SmarterMail uses, and the mode of any install that doesn't set one.
Standalone: for SpamFoo Client running on its own. The Linux package uses it, and the Docker and Linux archive steps in Install SpamFoo Client turn it on.

In standalone mode, SpamFoo Client works differently in these ways:

Proxy secret: every caller needs the proxy secret, even a program on the same server. Health checks are the only exception. In embedded mode, programs on the same server can classify mail without it.
Failed sign-ins: after a certain number of wrong proxy secrets or sign-in links from one IP address within a short time, that address is blocked for several minutes. Its requests get HTTP 429.
Changing the secret: a new value in etc/sf.proxysecret takes effect within a few seconds, with no restart. See Change the Secret.
License key: SpamFoo Client starts and waits when there's no key. It picks up a key you add later without a restart.
Largest message: the default limit is 64 MB instead of 520 MB. See Largest Message.
Port and public address: Port and Public URL only apply in standalone mode. In embedded mode the port is always 16253.
Message files: messages waiting to be scanned are written to the spool folder in the data directory, instead of the system's temporary folder. See Spool Folder.
File permissions: on Linux and macOS, SpamFoo Client makes the etc folder and the database readable only by the account that runs it.
Logs: log lines are also written to the console, so they show up in journalctl or docker logs.
Address map: a mail server can send which mailboxes it has and which addresses deliver to each one. See Push an Address Map.

Settings File

SpamFoo Client can read startup settings from a file named spamfoo.conf. The Linux package creates one at /etc/spamfoo/spamfoo.conf. SpamFoo Client uses the first file it finds:

The file named by --conf or SPAMFOO_CONF. SpamFoo Client won't start if that file doesn't exist.
spamfoo.conf in the data directory (/data/spamfoo.conf in Docker).
On Linux, /etc/spamfoo/spamfoo.conf.

Each line sets one environment variable from this page:

# Lines that start with # are comments.
SPAMFOO_MODE=standalone
SPAMFOO_BIND_ADDRESS=127.0.0.1
SPAMFOO_MAX_CLASSIFICATION_CONCURRENCY=4

Only names that start with SPAMFOO_ are read. Other lines are ignored with a warning.
A line only applies when the same environment variable isn't already set.
Quotes around a value are removed. If a name appears twice, the last line wins.
Restart SpamFoo Client after you change the file.

The same file works as a systemd EnvironmentFile or a Docker --env-file. The spamfoo-client commands read it too, so they use the same data directory, port, and public address as the service.

Command-Line Options

Add command-line options after the program name when you start SpamFoo Client. Write each one with an equals sign, such as --data-dir=/var/lib/spamfoo. In paths, ~ means your home folder.

./spamfoo-client --data-dir=/var/lib/spamfoo --models-dir=/var/lib/spamfoo/models

The program also has commands for tasks such as adding a license key or making a sign-in link. See Use SpamFoo Client Commands.

Data Directory

--data-dir=<path>

The directory that holds the database, license key, proxy secret, personalization data, backups, and logs. See Data Directory.

Default: the install folder (/data in Docker)

Models Folder

--models-dir=<path>

The folder where downloaded models are stored.

You can also set it with the SPAMFOO_MODELS environment variable, which wins over the option. It is only used if the folder already exists.

Default: <data directory>/trained-models

Mode

--mode=<mode>

embedded or standalone. See Mode.

You can also set it with the SPAMFOO_MODE environment variable. The option wins if both are set.

Default: embedded

Port

--port=<number>

The port SpamFoo Client listens on. Standalone mode only.

You can also set it with the SPAMFOO_PORT environment variable. The option wins if both are set.

Default: 16253

Settings File

--conf=<path>

The settings file to read. See Settings File.

You can also set it with the SPAMFOO_CONF environment variable. The option wins if both are set.

Default: spamfoo.conf in the data directory, then /etc/spamfoo/spamfoo.conf on Linux

Environment Variables

Each setting below shows its environment variable. A few of them, such as the scan queue settings, can also be saved on the Settings page or with the settings API, and a saved value wins.

Folders

NVIDIA Libraries Folder

SPAMFOO_RUNTIME

The folder for the NVIDIA libraries that GPU acceleration downloads.

Default: <data directory>/runtime

Spool Folder

SPAMFOO_SPOOL_DIR

The folder where messages are written while they wait to be scanned. Standalone mode only. SpamFoo Client deletes leftover files in it when it starts. In embedded mode, the system's temporary folder is used.

Default: <data directory>/spool

License and Access

License Key

SPAMFOO_LICENSE_KEY

Your license key.

You can also save the key in etc/sf.key in the data directory, or with spamfoo-client activate. The environment variable wins if both are set.

SpamFoo Client watches etc/sf.key and uses a changed key within a few seconds, with no restart. In embedded mode, this works only if SpamFoo Client had a key when it started. Otherwise, restart it after you add the key.

Proxy Secret

SPAMFOO_PROXY_SECRET

The password you paste to sign in to the admin console. Mail servers and scripts send it with every request.

If you choose your own, use at least 32 characters from A-Z a-z 0-9 - _, with no spaces before or after it. Letter case matters.

You can also save it in etc/sf.proxysecret in the data directory. The environment variable wins if both are set. In standalone mode, a new value in the file takes effect within a few seconds. See Change the Secret.

Default: a random value SpamFoo Client creates and saves in etc/sf.proxysecret when it first starts

Network

Listen Address

SPAMFOO_BIND_ADDRESS

The network address SpamFoo Client listens on. Use 0.0.0.0 to accept connections from other machines. SpamFoo Client serves HTTP only.

Default: localhost (0.0.0.0 in Docker, 127.0.0.1 in the Linux package's settings file)

Port

SPAMFOO_PORT

The port SpamFoo Client listens on, from 1 to 65535. Standalone mode only. In embedded mode the port is always 16253.

You can also set it with the --port option, which wins.

Default: 16253

Public URL

SPAMFOO_PUBLIC_URL

The address people use to reach SpamFoo Client, such as http://spamfoo.example.com:16253. Sign-in links start with it. It must start with http:// or https://. Standalone mode only.

Without it, a sign-in link made by the dashboard or the API uses the address the request came to, and one made by spamfoo-client login-link uses http://localhost and the port.

Warning Do not open the SpamFoo Client port to the internet. Allow only your mail servers to reach it.

Updates

Update Check Interval

SPAMFOO_UPDATE_INTERVAL_HOURS

How often SpamFoo Client checks for new models and program updates, in hours.

Default: 6 hours

Automatic Program Updates

SPAMFOO_DISABLE_BINARY_UPDATE

Whether SpamFoo Client replaces its own program files when a new version is available. Set the variable to true to turn this off. Model updates still run. Program updates are always off in a Docker container running in standalone mode and with the Linux package, which you upgrade with its install script.

Default: false (true in Docker and with the Linux package)

Install Kind

SPAMFOO_INSTALL_KIND

How SpamFoo Client was installed: package, container, portable (an archive), or sidecar. Standalone mode only. It decides whether program updates run, and it's shown on your license in your SpamFoo account. Set it only if SpamFoo Client guesses wrong.

Default: container inside a container, package when the program is in /opt/spamfoo/client, and portable otherwise

SpamFoo API Timeout

SPAMFOO_TIMEOUT

How long SpamFoo Client waits for SpamFoo's servers to answer, in seconds.

Default: 30 seconds

Scan Queue

SpamFoo Client scans a limited number of messages at once. Other messages wait in a queue. There are two queues that share the same slots:

Spool queue: messages being delivered right now. These get first claim on the slots.
Background queue: requests that only sort mail into Email Classifications, without spam checks. See Classify Without Spam Checks.

Max Concurrency

SPAMFOO_MAX_CLASSIFICATION_CONCURRENCY

How many messages are scanned at once, shared by both queues. Each message being scanned can keep one processor core fully busy. See Concurrency.

Default: 2 (range 1 to 32)

Queue Timeout

SPAMFOO_CLASSIFICATION_QUEUE_TIMEOUT_SECONDS

How long a message can wait for a slot before SpamFoo Client returns an error (HTTP 503), in seconds. See Timeouts.

Default: 30 seconds

Spool Queue Timeout

SPAMFOO_SPOOL_TIMEOUT_SECONDS

A separate wait limit for the spool queue, in seconds.

Once you save the Settings page, the saved Queue Timeout replaces SPAMFOO_SPOOL_TIMEOUT_SECONDS. To keep a separate limit after that, set it with the settings API.

Default: same as Queue Timeout

Background Queue Slots

SPAMFOO_BACKGROUND_MAX_CONCURRENCY

The most slots the background queue can use. It can never take every slot.

Default: one less than Max Concurrency, at least 1

Background Queue Timeout

SPAMFOO_BACKGROUND_TIMEOUT_SECONDS

A separate wait limit for the background queue, in seconds.

Once you save the Settings page, the saved Queue Timeout replaces SPAMFOO_BACKGROUND_TIMEOUT_SECONDS. To keep a separate limit after that, set it with the settings API.

Default: 120 seconds, or Queue Timeout once you save the Settings page

Request Limits

These limits protect the server from very large or very many requests. The defaults are set high so that normal mail is never turned away.

Largest Message

SPAMFOO_MAX_CLASSIFY_BODY_BYTES

The largest message SpamFoo Client accepts, in bytes. Larger messages get an error (HTTP 413). To protect memory from very large messages, lower it, for example to 33554432 (32 MB).

Default: 545259520 (520 MB), or 67108864 (64 MB) in standalone mode

Messages Held at Once

SPAMFOO_MAX_CLASSIFY_INFLIGHT

The most messages SpamFoo Client holds at once, scanning or waiting. Extra requests get an error (HTTP 503).

Default: 1024

Intake Wait

SPAMFOO_CLASSIFY_INTAKE_TIMEOUT_MS

How long a request waits for room under Messages Held at Once, in milliseconds.

Default: 250 milliseconds

Model Processing

Model Threads

SPAMFOO_ONNX_THREADS

How many processor threads the models share.

Default: about half the processor cores (1 on servers with 2 cores or fewer)

GPU Acceleration

SPAMFOO_GPU

Set to true to always run the text model on an NVIDIA GPU, or false to always use the processor. When it's set, it overrides the GPU Acceleration switch on the Settings page. See Turn On GPU Acceleration, which also lists the other GPU variables.

Change Other Settings

Data retention, backups, display, and the other settings not listed here are changed on System > Settings in the admin console, or with the settings API. For each one, its place on the Settings page, its settings API key, and its default, see Read and Change Settings.

Data Directory

SpamFoo Client keeps its data in the data directory. This is the install folder unless you set --data-dir. In Docker it's /data, and with the Linux package it's /var/lib/spamfoo. The Storage card on System > Status shows the exact paths.

<data directory>/
  backups/              Nightly backups
  correction_archive/   Corrections reported from this server
  etc/                  License key, proxy secret, release channel, installation ID, and encryption keys
  logs/                 Log files
  personalization/      Each user's rules and learned preferences
  runtime/              NVIDIA libraries (only with GPU acceleration)
  spool/                Messages waiting to be scanned (standalone mode only)
  trained-models/       Downloaded models (downloaded again if missing)
  admin.db              Settings, scan history, and totals
  address-map.json      The address map a mail server pushed
  domain_age.db         Saved domain ages
  spamfoo.conf          Startup settings, if you created this file
  update-status.json    The result of the last install script upgrade (Linux package only)

To learn what to back up, see Update and Back Up.

Tune Performance

The defaults keep processor and memory use low, which suits most mail servers. Change them only if messages wait too long to be scanned or the server is dedicated to email scanning.

Concurrency

Max Concurrency sets how many messages are scanned at once. A higher value lets busy servers keep up, but uses more memory and processor time. On servers with few processor cores, a value of 1 can work better. After a change, watch the Memory and CPU tiles on System > Status.

Speedup Optimizations

Enable Speedup Optimizations lets SpamFoo Client use more processor and memory to scan each message faster. It's off by default and applies to the next message scanned, with no restart.

Warning Turn this on only if the server is dedicated to SpamFoo Client or has a lot of unused processor and memory. It can take processor time and memory that your mail server needs.

What it does: the text model gets its own set of threads that can use every processor core, and the model runtime turns on extra optimizations.
Processor: while a message is scanned, SpamFoo Client can use every core. On a busy mail server this competes with mail delivery.
Memory: the models keep memory between messages instead of releasing it, so memory use goes up and stays up.
Concurrency: each message can already use every core, so a high Max Concurrency can make scanning slower. Start at 2.
GPU servers: it also changes how GPU memory is managed. Watch memory after you turn it on.

To see the effect, compare Average Scan Time on the Mail Health page before and after. If delivery slows down or memory runs short, turn it off.

If the server has an NVIDIA GPU, GPU acceleration is usually a better choice:

The text model does the same small math many thousands of times. A GPU is built to do that kind of work all at once.
The work moves off the processor, so scanning and mail delivery stop competing for the same cores.

Timeouts

Your mail server waits a limited time for each scan. Queue Timeout only covers the time a message waits for a free slot, and the scan takes more time after that.

Set Queue Timeout a few seconds below your mail server's limit. Then, when SpamFoo Client is too busy, it returns an error (HTTP 503) that your mail server can handle, instead of the mail server cutting off the request.

Configure Docker

In Docker, pass environment variables with -e, or list them in an env file. The image already sets these:

SPAMFOO_BIND_ADDRESS=0.0.0.0, so your mail server can reach the container
SPAMFOO_DISABLE_BINARY_UPDATE=true, so you update by pulling a new image
The data directory is /data, so the models, settings, and history are all stored on the volume

The image doesn't set SPAMFOO_MODE, so a container runs in embedded mode unless you set it. Pulling a newer image never changes the mode of a container you already run. To use standalone mode, add SPAMFOO_MODE=standalone, as in Install With Docker.

docker run -d --name spamfoo-client --restart unless-stopped --stop-timeout 30 \
    -e SPAMFOO_MODE=standalone --env-file spamfoo.env \
    -e SPAMFOO_MAX_CLASSIFICATION_CONCURRENCY=4 \
    -p 127.0.0.1:16253:16253 -v spamfoo-data:/data \
    spamfoo/spamfoo-client:latest

Settings you save on the Settings page or through the settings API are kept in /data, so they survive when you replace the container. A spamfoo.conf file in /data is also read when the container starts.

Next Steps

Connect your mail server. See How Integration Works.
Learn the admin console. See Use the Admin Console.
Plan updates and backups. See Update and Back Up.