Troubleshooting Guide

This guide covers common issues and solutions for FOG Docker.

Container Issues

Container Won’t Start

  1. Check container logs: 
    docker compose logs fog-server
docker compose logs fog-db
  2. Verify environment variables: 
    cat .env
  3. Check port conflicts: 
    netstat -tulpn | grep -E ':(80|443|69|21|2049)'
  4. Verify Docker resources: 
    docker system df
docker system prune  # Clean up if needed

Database Connection Issues

  1. Check database container status: 
    docker compose ps fog-db
  2. Test database connectivity: 
    docker exec fog-server mysql -h fog-db -u root -p$FOG_DB_ROOT_PASSWORD
  3. Check database logs: 
    docker compose logs fog-db
  4. Verify database environment variables: 
    grep FOG_DB_ .env

Default Admin Login (fog/password) Not Working

If the default credentials fog / password don’t work, follow these steps to diagnose and fix the issue.

Step 1: Verify the Admin User Exists

Check if the admin user was created in the database:

docker exec fog-server mysql -h fog-db -u fogmaster -pfogmaster123 -e "SELECT uName, uId FROM fog.users WHERE uName='fog';"

Expected output: Should show a row with uName='fog' and a uId number.

If empty: The admin user wasn’t created during schema initialization.

Step 2: Check Schema Initialization Logs

Review the container logs for schema initialization:

docker compose logs fog-server | grep -i "schema\|admin\|user" | tail -20

Look for:

  • “Database schema is up to date” or “Database schema check/update completed successfully”
  • “FATAL: FOG database schema install/update failed” (container exits on purpose)

On FOG 1.5.10.18xx+, schema deploy requires FOG_SCHEMA_INSTALL_TOKEN. The entrypoint writes this into config.class.php and posts it unattended. Success is judged by the schemaVersion row in the database (not by scraping FOG’s HTML/JSON response). FOG still has no CLI schema installer — if upstream renames the web form fields, the POST may be ignored and the DB check will fail loudly.

If migration fails, the container exits instead of starting workers against an outdated schema.

Step 3: Manually Trigger Schema Initialization

If the admin user doesn’t exist and the container is not auto-migrating, complete installation manually:

  1. Open your browser and go to: 
    http://your-server-ip/fog/management/index.php?node=schema

    If you set a stable FOG_SCHEMA_INSTALL_TOKEN in .env, append &fogtoken=<your-token>.

  2. You should see a page titled “Database Schema Installer / Updater”

  3. Click the “Install/Update Now” button

  4. Wait for the success message

  5. Try logging in again with fog / password

Step 4: Verify After Manual Installation

After completing Step 3, verify the user exists:

docker exec fog-server mysql -h fog-db -u fogmaster -pfogmaster123 -e "SELECT uName, uId FROM fog.users WHERE uName='fog';"

Step 5: Check Database Connection

If schema initialization fails, verify the database connection:

# Check if database container is running
docker compose ps fog-db

# Check database logs
docker compose logs fog-db --tail 50

# Test database connection from fog-server
docker exec fog-server mysql -h fog-db -u fogmaster -pfogmaster123 -e "SELECT 1;"

Note: Future versions will automatically verify and report admin user creation status in the logs to make this easier to diagnose.

Login Loops Back to Empty Form (No Error)

If submitting fog / password returns you to blank login fields with no error message, the admin user may exist and credentials may be correct — the session cookie is not sticking.

Cause: The URL in your browser does not match your FOG_TLS_MODE. See TLS Modes.

You browse Set
https://host/... direct (self-signed) FOG_TLS_MODE=standard
https://fqdn/... via Traefik only FOG_TLS_MODE=reverse-proxy
http://host:port/... FOG_TLS_MODE=http-only

Using reverse-proxy but opening plain http://container-ip:80/... makes FOG set Secure cookies while the browser connection is not HTTPS — login loops.

Fix for HTTP access (e.g. custom port 89):

FOG_TLS_MODE=http-only
FOG_APACHE_EXPOSED_PORT=89

Fix for direct HTTPS (default):

FOG_TLS_MODE=standard

Recreate the container, then use https://your-host/fog/management/ and accept the self-signed certificate.

Verify: Browser devtools → Network → login POST → Set-Cookie: PHPSESSID with Secure on an http:// URL confirms the mismatch.

Also ensure FOG_STORAGE_HOST matches FOG_WEB_HOST for single-server setups (do not leave a placeholder FQDN from the example).

iPXE Fails Chaining to boot.php (HTTPS / certificate errors)

Symptom: PXE loads iPXE, then fails on https://…/fog/service/ipxe/boot.php (e.g. iPXE error 0216eb8f, or “permission denied”).

Cause: Netboot was using HTTPS while the certificate is not trusted by stock iPXE (typical with self-signed Apache certs).

Fix: Use the default mode (matches upstream FOG 1.6 standard):

FOG_TLS_MODE=standard

Recreate the container and confirm /tftpboot/default.ipxe chains to http:// your host. Open the UI at https://. See TLS Modes.

For HTTPS netboot, use FOG_TLS_MODE=reverse-proxy or public-cert with an FQDN and a publicly trusted certificate.

Network Issues

Storage Node Connectivity Issues

  1. Verify FOG_STORAGE_HOST is reachable from client machines
  2. Check that the FQDN resolves correctly from client machines
  3. Verify firewall rules allow access to ports 80, 443, 69, 2049, 21
  4. Test connectivity: 
    ping fog.example.com
telnet fog.example.com 80
telnet fog.example.com 443

PXE Boot Issues

  1. Ensure FOG_TFTP_HOST is reachable from client machines
  2. Check that port 69/UDP is open and accessible
  3. Verify DHCP is configured to point to the correct TFTP server
  4. Check that DHCP option 66 (next-server) points to FOG_TFTP_HOST
  5. Verify DHCP option 67 (filename) is set to the correct boot file
  6. For UEFI clients, ensure the boot file is configured:
    • UEFI 32-bit: FOG_DHCP_BOOTFILE_UEFI32 (default: i386-efi/snponly.efi)
    • UEFI 64-bit: FOG_DHCP_BOOTFILE_UEFI64 (default: snponly.efi)
    • UEFI ARM64: FOG_DHCP_BOOTFILE_ARM64 (default: arm64-efi/snponly.efi)
    • Legacy variable: FOG_DHCP_BOOTFILE_UEFI (maps to UEFI64 for backward compatibility)
  7. For HTTPBoot clients, verify that the iPXE files are accessible via HTTP (automatically available)

TFTP Boot Files Missing (only default.ipxe in /tftpboot)

Symptom: Host bind mount or browsed /tftpboot directory contains only default.ipxe, not undionly.kkpxe, ipxe.efi, etc. TFTP may connect but clients fail with “file not found”.

Cause: A host bind mount replaces the image’s baked-in /tftpboot at container start. On older images, the entrypoint copied boot files into a nested /tftpboot/tftp/ subdirectory; if flattening failed (permissions on NFS/host mounts), only default.ipxe (written separately) remains visible at the top level.

Fix:

  1. Ensure the host tftpboot directory is writable by the container (e.g. chmod 775 or matching UID).
  2. Empty the host tftpboot directory (keep a backup if needed) and restart the container — the entrypoint repopulates all boot files on start.
  3. Verify inside the container: 
    docker exec fog-server ls -la /tftpboot/ | head -20
tftp -m binary YOUR_HOST -c get undionly.kkpxe /tmp/test.kpxe
  4. Check for a legacy nested directory: docker exec fog-server ls /tftpboot/tftp/ — if files are there, upgrade to the latest image and restart.

Atheros / Legacy NIC: “No configuration method succeeded”

Symptom: iPXE loads but DHCP fails with err:040ee1 on certain Atheros or older NICs. Other .kpxe files may fail earlier with TFTP “file not found” if boot files are missing (see above).

Upstream fix: FOG upstream recommends updating to dev-branch for this class of hardware (forum thread). Stable images update when upstream cuts a stable release.

Options without breaking a working deployment:

  1. Wait for stable — pre-built images rebuild when upstream stable is updated (ghcr.io/88fingerslukee/fog-docker:latest).
  2. Dev / custom FOG ref — use a published tag, or build locally from any FOG git ref (including working-1.6 or an RC): 
    # In .env
FOG_VERSION=working-1.6
docker compose -f docker-compose-dev.yml up -d --build
  3. Try vendor-specific boot files (if TFTP files are present) — set in .env: 
    FOG_DHCP_BOOTFILE_BIOS=realtek.kkpxe   # some Atheros/Realtek legacy NICs

    Restart the container so DHCP config is regenerated.

  4. Spanning tree — enable PortFast/edge on the switch port if DHCP timeouts occur (forum reference).

Capture finishes but task fails on “Updating Database” (Post_Stage2 HTTP 500)

FOG 1.6 Post_Stage2.php moves the capture from /images/dev/<mac>/ into the image directory over SSH/SFTP. If that step fails, the upload data may still be on disk under dev/ while the task shows Failed.

Check Apache/PHP error log:

docker exec fog-server grep Post_Stage2 /opt/fog/log/apache2_error.log | tail -5
Log message Fix
Call to undefined function ... ssh2_connect() Image missing PHP ssh2 — rebuild/pull current fog-docker (Debian php8.4-ssh2 package).
Unable to connect to ssh during move upload openssh-server not running in the container, or storage node hostname wrong.
SSH auth failure Storage node IP/Hostname in FOG must match a host where FOG_USER/FOG_PASS work over SSH.

Docker (single container):

FOG_STORAGE_HOST=<IP or FQDN clients use for NFS/FTP>   # often same as FOG_WEB_HOST
FOG_STORAGE_NODE_SSH_HOST=127.0.0.1                    # Post_Stage2 SFTP only (not on clients)

Restart the container after upgrading fog-docker so ngmHostname is synced from FOG_STORAGE_HOST and TaskQueue.php uses FOG_STORAGE_NODE_SSH_HOST for SSH without overwriting the client storage IP.

NFS mount fails: storageip=127.0.0.1 / Connection refused

FOG builds ftp=, storage=, and storageip= from the master storage node nfsGroupMembers.ngmHostname. If that value is 127.0.0.1, each imaging client tries to NFS-mount its own loopback and fails before upload.

Fix: set FOG_STORAGE_HOST (and FOG_WEB_HOST) to the server IP or FQDN clients can route to, pull a current fog-docker image (Post_Stage2 SSH override), restart, then re-PXE or refresh boot.php so kernel args update. One-off SQL:

UPDATE nfsGroupMembers SET ngmHostname='your.imaging.host' WHERE ngmIsMasterNode=1;

Manual finalize (if capture data remains under dev/ and task failed): fix ssh2/sshd/hostname, set the task back to In-Progress in the DB if needed, then retry from the client or POST Post_Stage2.php with mac= and type=up. Success body is ##.

HTTPBoot Issues

  1. Verify iPXE files are accessible via HTTP/HTTPS
  2. Check protocol matches your TLS mode (FOG_TLS_MODE)
  3. Test URLs directly in a browser
  4. Verify reverse proxy configuration (if using)

FTP Issues

Passive Mode Problems

  1. Ensure FTP passive port range (21100-21110) is open in firewall
  2. Check FOG_FTP_PASV_MIN_PORT and FOG_FTP_PASV_MAX_PORT configuration
  3. Verify FOG_WEB_HOST resolves correctly from client machines
  4. Test FTP connectivity: 
    ftp fog.example.com
# Try passive mode

Connection Issues

  1. Verify FOG_WEB_HOST resolves correctly from client machines
  2. Check FTP server is running: 
    docker exec fog-server systemctl status vsftpd
  3. Check FTP logs: 
    docker exec fog-server tail -f /var/log/vsftpd.log

Permission Errors

  1. Check that FOG user has proper permissions on image directories
  2. Verify file ownership: 
    docker exec fog-server ls -la /images/
  3. Check FOG user configuration: 
    grep FOG_USER .env
grep FOG_PASS .env

“Cannot Create File” Errors

Usually indicates passive mode configuration issues:

  1. Check passive mode configuration in vsftpd
  2. Verify passive port range is open in firewall
  3. Check FOG_WEB_HOST setting for FQDN resolution

NFS Issues

Permission Problems

  1. NFS exports use root_squash with anonuid=999,anongid=33 mapping
  2. Check NFS export configuration: 
    docker exec fog-server cat /etc/exports
  3. Verify NFS server is running: 
    docker exec fog-server supervisorctl status nfs-kernel-server unfsd

    Kernel mode runs nfs-kernel-server. FOG_NFS_MODE=unfs3 runs unfsd instead and does not use port 32765.

Image Capture Issues

  1. If captured images create files instead of directories, check NFS export configuration
  2. Verify proper ownership mapping in NFS exports
  3. Check FOG user permissions on image directories

Mount Failures

  1. Verify NFS server is running and exports are properly configured
  2. Check NFS port accessibility (2049)
  3. Test NFS mount: 
    mount -t nfs fog.example.com:/images /mnt/test

DHCP Configuration Issues

  1. Verify all DHCP network variables match your actual network configuration
  2. Ensure FOG_DHCP_SUBNET and FOG_DHCP_NETMASK are correct for your network
  3. Check that FOG_DHCP_ROUTER points to your actual gateway
  4. Verify IP address range (FOG_DHCP_START_RANGE to FOG_DHCP_END_RANGE) doesn’t conflict with existing devices
  5. Ensure FOG_DHCP_DNS contains valid DNS servers
  6. Check that all required boot files are present in /tftpboot/ (BIOS, UEFI)

SSL/HTTPS Issues

Certificate Issues

  1. Check certificate file paths in FOG_APACHE_SSL_CERT_FILE and FOG_APACHE_SSL_KEY_FILE
  2. Verify volume mounts are correct
  3. Check file permissions on certificate files
  4. Verify certificate and key match

SSL Handshake Failed

  1. Check certificate validity dates
  2. Ensure proper certificate chain
  3. Verify SSL configuration in Apache

Edge/Chrome: ERR_SSL_KEY_USAGE_INCOMPATIBLE (standard TLS / self-signed)

The browser reached HTTPS but rejected the Apache server.crt Key Usage (common on WSL and FOG_TLS_MODE=standard). Pull a current fog-docker image and recreate the container so managed server.crt is regenerated with digitalSignature. See SSL/HTTPS — self-signed and Windows (WSL2).

WSL2 on Windows

See Windows (WSL2) for ports, FOG_WEB_HOST, HTTPS vs HTTP, and PXE limitations.

Mixed Content Warnings

  1. Use a TLS mode with HTTPS for the UI (FOG_TLS_MODE=standard, mounted-certs, public-cert, or reverse-proxy) and open the matching URL — see TLS Modes
  2. Check for hardcoded HTTP URLs in configuration

Image Management Issues

Image Capture/Deploy Failures

  1. Check that FOG_STORAGE_HOST is accessible from client machines
  2. Verify NFS exports are working (port 2049)
  3. Check FTP connectivity (port 21)
  4. Verify FTP passive mode is working (ports 21100-21110)
  5. Check NFS permissions - captured images should create directories, not files

Client Download Issues

  1. Verify FOG client files are accessible at /fog/client/
  2. Check CA certificate is accessible at /fog/management/other/ca.cert.der
  3. Verify server public certificate at /fog/management/other/ssl/srvpublic.crt

FOG Agent enrollment / certificate name errors

FOG Agent checks that srvpublic.crt matches the server name you use to enroll (stricter than the legacy FOG Client).

  1. Set FOG_WEB_HOST to the primary FQDN or IP clients/agents use.
  2. Add any other names (short hostname, extra DNS zone, LAN IP) to FOG_CERT_SAN as a comma-separated list — see SSL/HTTPS — FOG Client Certificates.
  3. Enroll using a name that appears on the cert (same string as in the URL).
  4. Change FOG_WEB_HOST or FOG_CERT_SAN and restart/recreate the container — fog-docker compares a saved fingerprint on /opt/fog/config and regenerates srvpublic.crt when the values changed (see SSL/HTTPS).

Common Error Messages

“Cannot create file line 709”

  • Cause: FTP passive mode configuration issues
  • Solution: Check passive mode configuration and port range

“Undefined array key 8” in fogftp.class.php

  • Cause: FTP directory listing issues
  • Solution: Check FTP server configuration and passive mode

“Chainloading permission denied”

  • Cause: iPXE file permission issues
  • Solution: Check file permissions and accessibility

“Failed to download nbp file”

  • Cause: HTTPBoot URL accessibility issues
  • Solution: Check HTTPBoot URL and file accessibility

Debug Commands

Container Debugging 

# Check container status
docker compose ps

# View container logs
docker compose logs -f fog-server

# Execute shell in container
docker exec -it fog-server bash

# Check service status
docker exec fog-server supervisorctl status

Network Debugging 

# Test connectivity
ping fog.example.com
telnet fog.example.com 80
telnet fog.example.com 443
telnet fog.example.com 69

# Check DNS resolution
nslookup fog.example.com
dig fog.example.com

File System Debugging 

# Check file permissions
docker exec fog-server ls -la /images/
docker exec fog-server ls -la /tftpboot/

# Check NFS exports
docker exec fog-server cat /etc/exports

# Check FTP configuration
docker exec fog-server cat /etc/vsftpd.conf

Getting Help

If you’re still experiencing issues:

  1. Check the logs for specific error messages
  2. Search existing issues on GitHub
  3. Create a new issue with detailed information:
    • FOG Docker version
    • Docker version
    • Operating system
    • Error messages and logs
    • Configuration details (sanitized)

Next Steps

After resolving issues:

  1. Configuration Guide - Review and optimize configuration
  2. Network Boot Setup - Verify network boot configuration
  3. SSL/HTTPS Setup - Check SSL configuration if using HTTPS