Use Diagnostic Tools

Use these tools to check that SpamFoo Client is running and to find out why it handled a message the way it did. For fixes to known problems, see Fix Common Problems.

Some steps below mention the data directory. This is the directory where SpamFoo Client keeps its database, logs, and keys. It is the install folder unless you start SpamFoo Client with --data-dir=. It is /data in Docker and /var/lib/spamfoo with the Linux package. The Storage card on System > Status in the admin console lists the exact folders.

Check That SpamFoo Client Is Running

The health check is the quickest test. Run it on the server where SpamFoo Client is installed.

curl.exe http://localhost:16253/health
curl http://localhost:16253/health
curl http://localhost:16253/health
docker ps --filter name=spamfoo-client

The image also runs this check on its own, so docker ps shows the container as healthy or unhealthy.

If the command can't connect, SpamFoo Client isn't running. See Read Startup Messages to find out why. A working service answers with "status": "healthy". See Check Queue Load for what the other fields mean.

Check That It Can Classify Mail

A healthy answer means SpamFoo Client is running, not that it can classify mail. To check that, use the readiness check:

curl http://localhost:16253/health/ready

A 200 means it's ready, and a 503 lists the reasons. See Check That It Is Ready.

With the Linux package or Docker, spamfoo-client status shows the same answer and also whether a license key is set up. See Check Readiness.

Read Startup Messages

When SpamFoo Client starts, it prints messages that don't go into the log files. They show which folders it uses, whether it found a license key, and why it stopped if it fails to start.

Stop SpamFoo Client if it is running. Then start it in a Command Prompt from the install folder and read the output. Add the same options the service uses, such as --data-dir=.

cd <install-folder>
spamfoo-client.exe

Press Ctrl+C to stop it when you are done.

sudo journalctl -u spamfoo-client -n 100

In standalone mode, which the Linux package uses, the journal also has every log line.

docker logs spamfoo-client

Use your container's name in place of spamfoo-client. In standalone mode, the container's output also has every log line.

Lines worth looking for:

  • FATAL:: a setting is wrong, and SpamFoo Client stopped. The line names the setting. See It Stops With a Settings Error.
  • Configuration file:: the settings file SpamFoo Client read, and how many settings it applied.
  • LicenseKey: Not Configured: SpamFoo Client found no license key.
  • ALERT: SpamFoo API not configured. Update checking disabled.: models and the client won't update.
  • Models directory:: the folder where SpamFoo Client looks for its models.
  • SpamFoo Dashboard static files not found: the admin console files are missing.

Check the Status Page

In the admin console, go to System > Status. Check that the status line says API connected, the License card shows Active, and the Versions card lists a version for each model. An empty or old model version points to an update problem. For everything on the page, see Check System Status.

The Mail Health page also shows alerts at the top when SpamFoo Client can't reach the SpamFoo API or the license needs attention.

Look Up a Message

The Messages page shows how SpamFoo Client handled each scanned message. Use it when someone asks why a message was or wasn't marked as spam.

  1. In the admin console, go to Messages.
  2. Fill in one or more filters: Sender Domain, Sender IP, Recipient, Detection Type, or Detection Path.
  3. Click Search.
  4. Click a message to open its details.

What to look at:

  • Tag next to the result: appears when something other than the machine learning model decided, such as Admin block, Reputation block, Learned (spam), or Phishing Model.
  • Verified: whether the sender passed email authentication checks (SPF, DKIM, and DMARC, which confirm a message really came from the domain it claims). A message from a verified sender that was marked as spam deserves a closer look.
  • Processing Steps: in the message details, each step SpamFoo Client took, marked Pass or Fail where it applies.
  • Message Content: the stored subject and body, if Store Message Content is on.

Right-click a message to create a rule for its sender or IP address, or to report a wrong result to SpamFoo. Messages are kept for the Retention Period set on System > Settings, which is 7 days by default.

Read the Logs

Start with the Errors log. It has every warning and error from all the other logs in one place. Read it on System > Logs in the admin console, or open the files in the logs folder of the data directory. See Monitor Logs and Health for each log and how to read it.

To see the last 100 lines of today's Errors log:

In PowerShell:

Get-Content "<data-dir>\logs\errors-$(Get-Date -Format yyyyMMdd).txt" -Tail 100
tail -n 100 <data-dir>/logs/errors-$(date +%Y%m%d).txt
docker exec spamfoo-client sh -c 'tail -n 100 /data/logs/errors-$(date +%Y%m%d).txt'

To log more while you look into a problem, set Log Level to Detailed, or turn on debug codes if support asks. See Change How Much Is Logged.