Logging

TLDR - Quick Summary

Key Logs: /opt/sftpgw/log/application-YYYY-MM-DD.log (Java), sftp-audit-YYYY-MM-DD.log (SFTP actions), license-audit-YYYY-MM-DD.log (licensing), /var/log/auth.log (SSH)

Rotation: SFTP Gateway rolls its own logs at midnight, one file per day. The operating system's logrotate is not involved.

Retention: 30 days or 1 GB of archived files per log (3 GB before 3.7.2), whichever comes first (license audit: 90 days). A single oversized day can wipe the older days.

Keep more history: download our logback-spring.xml to /opt/sftpgw, edit the SETTINGS block at the top (days kept, size caps, compression), add logging.config=/opt/sftpgw/logback-spring.xml to application.properties, restart.

Debug Mode: Add logging.level.com.sftpgateway...=DEBUG to /opt/sftpgw/application.properties

Stack Traces: journalctl -u sftpgw-admin-api

Overview

This article covers the log files SFTP Gateway writes, how they are rotated and retained, how to keep more history than the defaults allow, and where the operating system's own log rotation (logrotate) fits in.

Log file locations

These are the logs of interest when troubleshooting SFTP Gateway:

/opt/sftpgw/log/application-YYYY-MM-DD.log
/opt/sftpgw/log/sftp-audit-YYYY-MM-DD.log
/opt/sftpgw/log/license-audit-YYYY-MM-DD.log
/var/log/auth.log
/var/log/sftpgw/cloudinit.log

And this is what these logs do:

• application-YYYY-MM-DD.log: Java events and errors.
• sftp-audit-YYYY-MM-DD.log: SFTP actions and authentication.
• license-audit-YYYY-MM-DD.log: license activation and validation events (SFTP Gateway 3.8.0 and later).
• auth.log: SSH authentication events for the administrative SSH service on port 2222.
• cloudinit.log: Server related issues that happen at first launch

SFTP Gateway writes each day's entries to a file named with that date. There is no plain application.log or sftp-audit.log; today's file is the one carrying today's date. Listing the directory shows exactly what is currently retained:

sudo ls -la /opt/sftpgw/log

It's often helpful to tail a log file while troubleshooting, to get a sense of timing:

sudo tail -f /opt/sftpgw/log/application-$(date +%F).log

How log rotation and retention work

SFTP Gateway rotates these logs itself, using the logback library built into the Java application. The operating system's logrotate does not manage /opt/sftpgw/log, and there is no logrotate rule for it on the VM.

• Rollover: at midnight (server time) the application starts a new file for the new date. There is no size-based rollover by default, so a single day's file grows until midnight.
• Retention: at each rollover, two limits are enforced per log. Older archived files (every file except the current day's) are deleted, oldest first, when either limit is exceeded.

Log	Days kept (maxHistory)	Size cap for archived files (totalSizeCap)
application-*.log	30	1 GB
sftp-audit-*.log	30	1 GB
license-audit-*.log	90	1 GB

Note: SFTP Gateway 3.6.x, 3.7.0 and 3.7.1 shipped with a 3 GB cap; versions 3.7.2 and later use 1 GB. The license-audit log exists from 3.8.0. The rotation mechanism itself is the same from 3.6.0 through 3.9.0, and no version has a logrotate rule for the application logs.

Why older audit logs can disappear

The size cap is what usually catches people out. It applies to the combined size of the archived files and is enforced when the day rolls over. On a busy server, or after a day of DEBUG logging, one day's sftp-audit file can exceed 1 GB on its own. When that day rolls over, it is deleted along with everything older to get back under the cap, and only the new day's file is left. The application log is usually much smaller, so it can still show a week or more of history while the audit log shows only today. The "30 days" is a ceiling, not a guarantee.

For example, with archived audit files of 700 MB and 1.1 GB in place, the midnight rollover removes both, while 10 MB application archives are left alone.

To see which limit you are hitting:

sudo du -ch /opt/sftpgw/log/sftp-audit-*.log | tail -1
sudo ls -la /opt/sftpgw/log

If yesterday's file is close to or above 1 GB, the size cap is deleting your history.

Keeping more log history

The rotation settings live in a logback.xml file packaged inside the application jar, so they cannot be edited in place. Instead, point SFTP Gateway at a configuration file of its own with the logging.config property. A ready-made one is available for download. It writes the same three logs in the same format, works on SFTP Gateway 3.6.0 and later, and gathers every retention setting into a short SETTINGS block at the top. It also compresses rolled files (roughly ten times smaller) and caps the size of a single day's file, which the built-in configuration does not do. The file lives outside the jar, so it survives restarts and in-place upgrades.

1. Download the file to /opt/sftpgw:

   cd /opt/sftpgw
   sudo wget https://thorntech-products.s3.amazonaws.com/sftpgateway/logging-config/logback-spring.xml
   sudo chown sftpgw:sftpgw /opt/sftpgw/logback-spring.xml
   sudo chmod 644 /opt/sftpgw/logback-spring.xml
   

2. Edit the SETTINGS block near the top of the file. Nothing below it needs to change.

   <!-- ===================== SETTINGS: edit these ===================== -->
   <!-- Where the logs live -->
   <property name="LOG_DIR" value="/opt/sftpgw/log"/>
   <!-- Largest size one log file may reach before rolling to a new file within the same day -->
   <property name="MAX_FILE_SIZE" value="200MB"/>
   <!-- Rolled files: ".log.gz" compresses them (about 10x less disk); ".log" keeps them plain -->
   <property name="ARCHIVE_EXT" value=".log.gz"/>
   <!-- Days of history to keep, per log -->
   <property name="APP_DAYS" value="30"/>
   <property name="AUDIT_DAYS" value="90"/>
   <property name="LICENSE_DAYS" value="365"/>
   <!-- Total disk the rolled files of each log may use; oldest are deleted first -->
   <property name="APP_CAP" value="2GB"/>
   <property name="AUDIT_CAP" value="8GB"/>
   <property name="LICENSE_CAP" value="1GB"/>
   <!-- ================================================================= -->
   

   Both limits always apply to each log, so set the cap high enough to hold the number of days you want, and check the disk has room for it (df -h /opt). Sizes accept KB, MB and GB.

3. Tell SFTP Gateway to use the file. Add this line to /opt/sftpgw/application.properties:

   logging.config=/opt/sftpgw/logback-spring.xml
   

4. Restart the service and verify:

   sudo service sftpgw-admin-api restart
   sudo ls -la /opt/sftpgw/log
   sudo journalctl -u sftpgw-admin-api --since "-2 min" | grep -E '\|-ERROR'
   

   The new configuration is in effect when today's files carry a counter: application-YYYY-MM-DD.0.log, sftp-audit-YYYY-MM-DD.0.log and license-audit-YYYY-MM-DD.0.log. Rolled files gain .gz, so after a few days the directory looks like this:

   sftp-audit-2026-09-21.0.log.gz
   sftp-audit-2026-09-22.0.log.gz
   sftp-audit-2026-09-22.1.log.gz
   sftp-audit-2026-09-23.0.log
   

   The journalctl command should print nothing. Warnings mentioning springProperty or an appender that is not referenced are normal: they come from the built-in configuration, which the Java runtime still reads briefly at startup before switching to yours.

To change a setting later, edit the SETTINGS block and restart the service. Retention is applied at startup and at every rollover.

Note: Files written before the switch keep their old names (sftp-audit-YYYY-MM-DD.log) and are no longer managed, so delete them once you no longer need them. Some versions also leave an empty file with the old name after each restart; it is harmless. Log shippers that match application*.log or sftp-audit*.log pick up the new names unchanged. The file is for VM deployments; it leaves out the JSON console and CloudWatch appenders that SFTP Gateway 3.9 uses only in containers.

For example, with 5 GB audit archives from two earlier days in place and AUDIT_CAP at 8 GB, the midnight rollover compresses the day's file, keeps the newer archive and removes the older one, while a 10 MB application archive is left alone. Lowering MAX_FILE_SIZE produces sftp-audit-YYYY-MM-DD.0.log.gz, .1.log.gz and so on within the day.

System logs and logrotate

logrotate manages the operating system's logs, not SFTP Gateway's. Its global defaults are in /etc/logrotate.conf, the per-log rules are the files in /etc/logrotate.d/, and it runs once a day from a systemd timer (systemctl list-timers logrotate.timer).

On the Ubuntu-based Azure image, /var/log/auth.log (SSH) and /var/log/syslog are rotated by the rule in /etc/logrotate.d/rsyslog. As shipped on SFTP Gateway 3.9.0 it keeps four weekly rotations, compresses them, and rotates early once a file reaches 100 MB:

/var/log/syslog
/var/log/mail.log
/var/log/kern.log
/var/log/auth.log
/var/log/user.log
/var/log/cron.log
{
    rotate 4
    weekly
    missingok
    notifempty
    compress
    delaycompress
    sharedscripts
    postrotate
        /usr/lib/rsyslog/rsyslog-rotate
    endscript
    create 0640 syslog adm
    su root syslog
    size 100M
}

To keep more SSH history, raise rotate (for example rotate 12 keeps roughly three months). Preview what logrotate would do with sudo logrotate -d /etc/logrotate.d/rsyslog, and force a rotation with sudo logrotate -f /etc/logrotate.d/rsyslog.

Note for instances launched before 3.7.4: on those images /var/log was group-writable and the rsyslog rule had no su line, so logrotate refused to touch these files at all (sudo logrotate -d /etc/logrotate.d/rsyslog reports skipping "/var/log/syslog" because parent directory has insecure permissions) and syslog grew without limit. To fix an older instance without redeploying, run sudo chmod 0755 /var/log and add the create 0640 syslog adm, su root syslog, and size 100M lines shown above to the block in /etc/logrotate.d/rsyslog. Images from 3.7.4 onward ship with these already applied.

The admin web interface's nginx logs under /var/log/nginx/ are rotated by /etc/logrotate.d/nginx (daily, 14 rotations kept, with a 100 MB size cap on 3.7.4 and later).

⚠️ WARNING: Do not add a logrotate rule for /opt/sftpgw/log. SFTP Gateway keeps its own file handles and names its files by date, so an outside rename or truncate loses entries or leaves duplicate files behind. Use the logback settings above instead.

Advanced Logging

If you want more verbose logging, insert this property into the /opt/sftpgw/application.properties file.

logging.level.com.sftpgateway.backend.sftp.logging.MaverickLogService=DEBUG

Note: You can also use TRACE instead of DEBUG, but this generates large amounts of output and can fill your disk up in a short period of time.

⚠️ WARNING: DEBUG and TRACE output can push a single day's file past the 1 GB retention cap, which deletes the older archived days at the next midnight. If you need verbose logging for more than a short troubleshooting session, raise the caps as described above first, and turn it off when you are done.

To apply your change, restart the Java service:

sudo su
service sftpgw-admin-api restart

Journalctl

If you want to get the full Java stack trace you can run this command:

journalctl -u sftpgw-admin-api