Direct Transfers

File transfers between a Files.com client and an On-Premise Agent normally travel through Files.com's network, which adds a relay hop between the client and the Agent. Direct Transfers remove that hop. The Files.com CLI App and the Files.com Desktop App send file data straight to the Agent, and transfers typically run 3 to 5 times faster. Actual speeds vary with your network.

The direct connection carries only the file data. Files.com still authenticates every user and authorizes every transfer, each transfer is encrypted and uses a signed, expiring authorization issued by Files.com, and enabling the feature grants no new access to the Agent's files. When the direct connection cannot be established, the client falls back to the standard connection route automatically, so transfers keep working either way.

The tradeoff is network setup. On many networks a single configuration line is enough, because the Agent asks the local router to open a port automatically. On networks with a managed firewall, your network team opens a small port range and forwards it to the Agent host. If transfer speed to and from your Agent matters to your workflows, Direct Transfers are worth that setup.

The CLI App and the Desktop App support Direct Transfers. Once the Agent is set up, both use the direct connection automatically. Transfers from other clients and interfaces continue over the standard connection route.

Enabling Direct Transfers

On networks where the router accepts automatic port mappings, you only need to add one line to the Agent's configuration file and restart the Agent service.

direct_transfers = true

The Agent listens on the first free port between 4001 and 4010, asks your router to open a matching public port using UPnP or NAT-PMP, and registers the addresses it can be reached at. Files.com verifies that it can reach the Agent before any client is offered the direct connection, and the Agent automatically allows connections from Files.com's own addresses for those checks.

If the network blocks automatic port mappings, the direct transfer status never becomes Available, and Setting Up Direct Transfers on a Restricted Network covers opening the ports by hand.

Setting Up Direct Transfers on a Restricted Network

Corporate and government networks usually block automatic port mappings, so the network team opens the ports instead. Configure the Agent with automatic mapping turned off (direct_transfer_upnp = false).

direct_transfers = true
direct_transfer_port = "4001:4010"
direct_transfer_upnp = false

Have your network team allow inbound TCP and UDP connections on ports 4001 through 4010 to the Agent host, and forward each public port to the same port number on the Agent host. Keeping the port numbers identical is critical, because the Agent tells clients the exact port it is listening on. Opening the full range gives the Agent room to keep direct transfers available whenever it updates itself.

When your firewall must present different public port numbers than the ports the Agent listens on, list the public ports in the direct_transfer_public_ports setting. When the Agent sits behind a static public IP address or a load balancer, add that address in the direct_transfer_advertised_addrs setting so clients are offered it.

If your network inspects TLS traffic, exclude connections to *.agents.files.internal from inspection, as described in Hostnames Used by Files.com. The direct connection is verified against a certificate that only the running Agent holds, and a device that intercepts or re-signs the connection breaks that verification, leaving clients on the standard connection route.

Restricting Which Clients Can Connect

The Agent has its own allow and block lists for direct transfers, separate from your firewall.

List your users' network ranges in the direct_transfer_allowed_client_ips setting to deny every other client. The Agent allows Files.com's own addresses automatically, so you list only your client ranges. Entries can be single IP addresses or ranges in CIDR form.

direct_transfer_allowed_client_ips = ["192.0.2.0/24", "198.51.100.25"]

Add addresses to the direct_transfer_blocked_client_ips setting to deny them. Blocked addresses take precedence over allowed ones, so an address that appears on both lists is blocked.

direct_transfer_blocked_client_ips = ["203.0.113.10", "198.51.100.0/24"]

When the Agent sits behind NAT or a load balancer, use one that preserves the client's original address. The allow and block lists match against the address the connection arrives from, so a device that replaces the client address with its own would make every client look identical.

Verifying That Direct Transfers Are Being Used

The Agent's Remote Server entry shows a direct transfer status.

Available means Files.com verified that it can reach the Agent's listener and clients are being offered the direct connection.

Not Available means Direct Transfers are enabled and no address has passed verification yet. Not Enabled means the Agent does not have the feature turned on.

On the Agent host, run the following command to ask the running Agent service for its current direct transfer status.

files-agent service direct-transfer-status

The result field in the output summarizes the state.

An Available status proves that Files.com can reach the Agent, but a client on a different network can still be blocked by a firewall between it and the Agent. Every status other than Available leaves the standard connection route in use, so transfers keep working while you adjust the network configuration.

Each direct upload and download is recorded in the Agent's log as a Direct transfer served entry. On the client side, the CLI App's debug log records direct transfer attempts, successes, and fallbacks to the standard connection route, and the Desktop App's logs record the same events.