File Delivery

NetXMS can deliver files from the server to managed agents using file delivery policies. This is useful for distributing configuration files, scripts, certificates, or any other files to monitored hosts through the management infrastructure.

Overview

File delivery uses a policy-based approach:

  1. Files are uploaded to the NetXMS server and attached to a file delivery policy on a template

  2. The policy defines the target path on the agent (where the file should be placed)

  3. When nodes are bound to the template, the server pushes files to agents during configuration polls

  4. If files change on the server, the updated version is automatically re-deployed

The filemgr subagent must be loaded on the agent (SubAgent = filemgr.nsm). All file delivery operations are executed as file manager commands, and delivery fails if the subagent is not loaded. See Subagents.

Creating a File Delivery Policy

  1. Open the management client

  2. Navigate to the template where you want to add the policy

  3. Open Properties > Policies

  4. Click Add and select File Delivery

  5. Configure the policy:

    • Policy name — descriptive name for the policy

    • Add one or more files to deliver

Adding Files

For each file in the policy, specify:

Field Description

Source file

Upload the file content to the server

Remote path

Full path where the file should be placed on the agent (e.g., /etc/myapp/config.yml)

Permissions

File permissions on the target system (Linux/Unix, e.g., 0644)

Owner

File owner on the target system (Linux/Unix, e.g., root:root)

On Windows agents, permissions and owner are applied as well, with platform-specific adjustments: execute permission bits are ignored, the file group is not compared, and the owner is compared only when specified in domain-qualified form (e.g., DOMAIN\user).

How File Delivery Works

  1. During a configuration poll, the server checks if the node has pending file delivery policies

  2. File deletion entries in the policy are processed first, before any uploads

  3. For each file in the policy, the server compares the file hash with the version on the agent

  4. If the file is new or has been modified, the server transfers the file to the agent

  5. The agent writes the file to the specified path, sets the permissions and ownership

  6. The agent reports deployment status back to the server

Files are transferred over the same secure channel used for agent communication (direct connection or tunnel).

Upload bandwidth can be limited per node with the SysConfig:Agent.UploadBandwidthLimit custom attribute; when the attribute is not set, the Agent.UploadBandwidthLimit server configuration variable applies.

Remote Path Expansion

Macro expansion applies to remote file and folder names only:

  • ${ENV_VAR_NAME} — value of the specified environment variable on the agent host

  • strftime(3C) date/time codes such as %Y, %m, %d, %H, %M, %S

  • Backtick-enclosed commands — executed on the agent, with the command output substituted into the path

See File Delivery Macros for the full macro table.

File content is never modified: files are delivered byte-for-byte exactly as uploaded to the server. There is no macro substitution inside delivered files.

Monitoring Delivery Status

To check file delivery status, right-click the node and open Properties > Policies — the list shows deployed policies and their deployment status. For details on failed file transfers, check the server and agent logs.

File Delivery vs. Agent FileStore

File delivery policies are different from the agent’s FileStore mechanism:

Feature File Delivery Policy FileStore

Direction

Server → Agent

Agent (local) or Server → Agent

Management

Centralized via templates

Per-agent configuration

Target path

Any path on the agent

Limited to FileStore directory

Version control

Automatic hash comparison

Manual

Use case

Config files, scripts, certificates

Temporary file transfers

Best Practices

  • Use file delivery for configuration files that need to be consistent across a group of hosts

  • Combine with agent configuration policies — deliver a script file, then add an ExternalMetric in a configuration policy that references that script

  • Keep delivered files small — file delivery is not designed for large binary distributions; use the Package Manager for software deployment