The Agent can be configured to automatically update itself or it can be manually upgraded.

Automatic updates are enabled by default. Set the update policy in the Agent configuration file to match your organization's deployment requirements.

Files.com releases regular updates to the Agent, but upgrading to every new version is not required if the Agent is functioning correctly. Files.com will notify you when an upgrade is required, when a version reaches end of support, or when updates are needed to support new encryption or security requirements.

Automatic Updates

The Agent provides a configuration option for automatic unattended updates.

Configure the auto_update_policy value to the desired option.

Valid options are manual_trigger, critical_only, always and never.

When set to always, the Agent will update itself whenever there is a new version available. This is the default value.

When set to critical_only, the Agent will only update itself with versions that solve reliability, performance, or security issues.

When set to never, the Agent never automatically updates. This prevents updates from being pushed to host systems, providing flexibility for meeting change management policy requirements.

When set to manual_trigger, the Agent will only update itself when manually triggered from Files.com.

The updates are cryptographically verified prior to installation to make sure that they have not been tampered with.

If the Agent cannot start after an update, the Agent will restart with the previously installed version.

Automatic updates will only occur when the Agent is running as a system service.

Blocking Updates During Busy Periods

If your Agent has busy periods when an update must not start, such as an overnight batch run or a month-end close, list those periods in the push_update_block_windows setting in the configuration file. Updates to the Agent will not happen during these time periods.

In the following example, updates are blocked for 1 hour after 9:00 AM in Austin, Texas every day, and from December 24 through December 26 in Scottsdale, Arizona.

push_update_block_windows = [
  "America/Chicago 0 9 * * * | 1h",
  "America/Phoenix 0 0 24-26 12 * | 24h"
]

The IANA list also includes legacy time zone names, kept only for compatibility. They work, but we recommend the modern names, such as America/Phoenix.

Each entry has three parts. The first is an IANA time zone name, such as America/Chicago. The second is a five-field cron schedule for when each block starts, in the order minute, hour, day of month, month, and day of week. The third, after the |, is how long the block lasts.

Ranges, lists, and intervals work in all five cron fields, and a range includes both ends. MON-FRI means Monday through Friday, MON,WED,FRI means those three days, and */15 in the minute field means every 15 minutes.

America/Chicago 0 18 * * MON-FRI | 12h starts a 12-hour block at 6:00 PM Central every weekday.
America/New_York 30 22 * * MON,WED,FRI | 2h starts a 2-hour block at 10:30 PM Eastern on Mondays, Wednesdays, and Fridays.
Europe/London 0 */6 * * * | 30m starts a 30-minute block every 6 hours, at midnight, 6:00 AM, noon, and 6:00 PM London time.

The duration must be between 1m and 168h, and only minutes (m) and hours (h) are accepted. To specify days, use increments of 24 hours.

30 minutes is 30m
1 day is 24h
3 days is 72h
7 days is 168h

You can combine the two, such as 1h30m. You can list up to 32 entries. Restart the Agent service after changing the setting.

While a block is active, an update you request is refused with an error that says the update is blocked and when the block ends. An automatic update is tried again later.

A block stops only new updates from starting. An update that already began finishes, and the block does not stop Agent restarts or host restarts.

For a Remote Server with Agent High Availability, Files.com checks every node before it starts an update, and a block on any one node blocks the update for all of them. The schedules on different nodes do not have to match.

Upgrading the Agent Manually

The Files.com Agent supports two upgrade methods: Remote Upgrade and Local Upgrade. A remote upgrade is initiated from the Files.com web interface while a local upgrade is performed directly on the Agent host system. Both approaches update the Agent to a newer version without requiring changes to the configuration file.

Remote Upgrade

A remote upgrade is initiated from the Files.com web interface by using the Update to <version> option for the Agent. This method allows you to upgrade the Agent without manually accessing the host system. The Agent downloads and installs the new version automatically and restarts the service as needed.

Local Upgrade

A local upgrade is manually performed directly on the host where the Agent is installed. To complete a local upgrade, download the latest version of the Agent and replace the existing files-agent executable binary with the newly downloaded version. Stop and restart the Agent service to complete the upgrade. No configuration changes are required.

Recovering From an Unsuccessful Update

An Agent warning names the update step that did not complete. Follow the matching section below and start with its first recovery action. Use the later repair steps only if the same failure returns. After the update completes, confirm that the Agent Remote Server shows Connected and reports the intended Agent version.

The recovery commands below select the latest approved Agent release for your operating system.

The Agent Installed the Update but Did Not Restart

Restart Files Agent on the Agent host. For a service installation, restart the Agent service. If you run Files Agent directly, stop the old process and start it again using your normal launch method. Confirm that the Agent Remote Server shows Connected and reports the intended Agent version before starting another update.

The Agent Could Not Download the Update

Confirm that the Agent host can make outbound HTTPS connections, then retry the update. If the same download failure returns, review the Agent firewall requirements and the exact error in the Agent log. Correct the firewall, outbound proxy, or security software restriction identified by the error before retrying again.

The Installed Executable Could Not Be Replaced or Backed Up

Check the available space on the volume that contains the Agent executable. Confirm that the account running the Agent service can create, replace, and delete files in the same folder.

Retry the update after correcting the space or permission problem. If the same failure returns and you installed the Agent with the Windows MSI, run the current MSI again to repair the existing installation.

For other installations, run the standalone recovery command on the Agent host. On Windows, use PowerShell or Command Prompt with permission to replace the executable. On Linux or macOS, prefix the command with sudo when the executable is owned by root and omit sudo for a user-owned installation.

files-agent upgrade

This command updates the executable on disk but does not restart a running service. If it reports that it saved the update at a different path, the installed executable is unchanged; complete the local upgrade before restarting. Otherwise, start or restart the Agent service after the replacement completes.

A Rolling Update Did Not Complete

If the Agent remains connected as a managed service, request another rolling update from the Agent host. On Windows, use PowerShell or Command Prompt opened as an administrator. On Linux or macOS, prefix the command with sudo for a root-owned system service and omit sudo for a user-owned service.

files-agent service upgrade

An accepted request starts the update in the background. Allow it to finish, then confirm that the Agent Remote Server shows Connected and reports the intended version. If the command or update fails, follow the standalone recovery steps above. If standalone recovery also fails, include the command's error output when contacting Files.com Support.

Upgrading The Agent