On-Premise Agent

---

The Files.com Agent is an installable piece of software that allows you to integrate any supported on-premise or cloud system with Files.com.

It provides a convenient method for securely connecting remote file systems with Files.com, allowing you to push and pull files between Files.com and local file systems. Local file systems can include locally attached storage, such as local disks and drives, and network attached storage, such as network drives that use CIFS, SMB, and NFS.

The Agent can be used to integrate your business processes that use on-premise file storage locations with Files.com. It can allow you to use your on-premise folders as sources or destinations for FTP(S), SFTP, AS2, and WebDAV connections. You can make your on-premise folders become sources or destinations for automations and workflows. On-premise folders can become destinations for inboxes, allowing you to easily collect data. Your on-premise folders can become sources for outboxes, share links, and public hosting, allowing for data distribution to any audience. You can also push, pull, or synchronize data between your on-premise folders and other storage providers such as Amazon S3, Microsoft Azure, Google Cloud Storage, Google Drive, BackBlaze B2, Box, Dropbox, Microsoft Sharepoint, Microsoft OneDrive, Rackspace Cloud Files, Wasabi Hot Cloud Storage, and more.

Any attached or mounted storage that the operating system has permission to access can be used with the Agent.

The Agent will connect to your Files.com site using a secure encrypted connection.

The Files.com Agent is supported on Windows (64bit), Linux (64bit), and MacOS (64bit).

First, create a Remote Server for the Agent in your Files.com site. Download and install the Agent to the system that you want the Agent to run on.

Download, review, and update the Agent configuration file to meet your needs. The Agent configuration file must be updated prior to attempting to run the Agent.

After you've installed the Agent and updated the Agent configuration file then you can run the Agent using the configuration file.

Once the Agent is running, you can use its Remote Server on Files.com to access local folders and integrate them with other Files.com features and capabilities. Use a Remote Mount to access local folders interactively through Files.com or use a Remote Sync to push files to, and pull files from, folders on the system that is hosting the Agent.

Create a new Remote Server and select Files.com Agent from the list of available remote server types.

Enter a name for this connection. This internal name is only used to reference this connection to this Agent.

Select the permissions for the Agent. These permissions will restrict Files.com to only be able to perform those actions.

Save the configuration.

A link will be provided to the download site for the Agent. Download the Agent that corresponds to your host operating system.

Download the configuration file to the system that will be hosting the Agent.

The Agent executable and the configuration file should be placed together into the same folder location.

Once saved, the Remote Server can be re-opened for further configuration.

The Remote Server configuration page for the Agent provides a link to the download site for the Agent.

On the download page, choose the version that matches your operating system.

The Agent should be downloaded into the same folder as its configuration file.

The Agent can be run manually from the command line. If you regularly intend to run the Agent manually then we recommend placing it in a directory that is contained in the PATH environment variable of your Operating System.

The Agent can also be installed as a system service.

The Files.com Agent uses a single outbound network port, port 8801.

The Agent will connect to Files.com using the general pool of Files.com IP addresses. Make sure that outbound connections to these IP addresses using port 8801 are allowed through your firewall.

If your Files.com site uses a custom domain, then the Agent will connect using your dedicated IP addresses instead.

The Files.com Agent is run from the command line. You can use a command line terminal, start it from a script, or configure your system to run it as a system service.

You should first run the Agent manually to test connectivity and functionality. Only after successfully running the Agent manually should you attempt to install it as a system service or start it from a script.

The Agent will only run on the system that it has been installed on. However, it can access network attached folders that have been mounted on the local system.

If you are using a Windows based system then you will need to use the Agent app EXE to run the Agent manually, The Agent MSI is only used when installing Agent as a system service.

Once the Agent app is installed, and the configuration file is saved onto your system, use the following command to start the Agent:

files-agent start --config files_agent_config.json

If the Agent app is not installed on your PATH then you can optionally run it by providing absolute paths to the Agent and its configuration file. For example:

C:\Users\me\files-agent start --config C:\Users\me\files_agent_config.json

The Agent will connect back to Files.com to register its current status. To confirm the status of the Agent, open the Remote Server configuration page for the Agent. The following fields will show the Agent status information:

Remote Server Mounts are created by mounting them onto an empty folder in Files.com. This folder should ideally not be the Root of your site, although that is supported if you need it.

Create a new folder. Within the newly created folder, select its Storage Location.

Select Remote Server Mount from the list and select the Agent remote server.

Choose the Remote folder, which is the portion of the remote file system that will be mounted into this folder on Files.com. You can either by leave the default "/" (i.e., the remote server's root directory) or click on Choose a different folder link and navigate to the remote folder you want to this folder to connect to.

Click the Save button. The folder will reload and immediately list the remote folders/files from the selected remote path.

If you instead wish to perform a Sync with the remote, follow these directions.

Go to the folder where you would like to add the remote server sync and use its Folder settings to enable a remote sync (Sync to/from remote server).

Add a new remote server sync and specify the details for the sync, including the remote server that you want to sync with.

There are three options for Sync direction:

You have the option to delete files on the source server after a push or pull. Use the After copying menu to select whether you would like files that are successfully transferred to be deleted from or kept on the source server.

Enter the remote path to or from which you would like files and folders transferred, starting after the folder/directory your remote user lands in upon authentication.

For example: if the remote server has a folder structure folderA/folderB/folderC, and the user credentials that you have configured your sync server to log in with automatically land that user inside folderA, then to properly configure your sync folder behavior to transfer files to or from folderC, you would enter the path as folderB/folderC.

A single Agent can be used to securely access multiple folders of a system.

The root option in the Agent configuration file specifies the top-most folder that the Agent itself is allowed to access.

However, each Remote Mount and Remote Sync can target specific lower-level folders. You can configure as many Remote Mounts and Remotes Syncs as you want using only a single Agent.

For example, let's say you want to provide secure access to 3 specific folders on your local Windows Server. In this example we'll say there are 2 folders for trading partners and 1 folder for an internal team: C:\Partners\Acme, C:\Partners\BinaryBros, C:\Internal\Teams\VendorRelations

All of the above folders share the common top-level folder of C:\ so that is what we'll specify in the Agent configuration file for the root setting.

Now we can set up 3 different Remote Mounts, each targeting one of the above lower-level folders. A Remote Mount for Acme will be configured to point to the C:\Partners\Acme folder via the Agent. Another Remote Mount, for BinaryBros, will be configured to point to the C:\Partners\BinaryBros folder. A final Remote Mount, for the internal Vendor Relations team, will be configured to point to the C:\Internal\Teams\VendorRelations folder.

Each Remote Mount is limited to accessing only its corresponding lower-level folder. The Acme users will only be able to access the C:\Partners\Acme folder, the BinaryBros users will only be able to access the C:\Partners\BinaryBros folder, and the internal Vendor Relations users will only be able to access the C:\Internal\Teams\VendorRelations folder.

You can configure the Agent to follow links, allowing it to access folders that are outside of its configured root folder.

To enable this option, update the configuration file to include "follow_links": true and then restart the Agent.

Within the Agent root folder, or subfolder, you can create symlinks that point to folders outside of the root folder, including any network attached or mounted folders. Symlinks can point to any valid and accessible NFS, CIFS, or UNC path.

To create a symlink on a Windows based system, run the following commands from a Command/DOS (CMD) terminal window:

cd C:\PATH\TO\AGENT\ROOT_FOLDER
mklink /D LINK_NAME M:\PATH\TO\TARGET_FOLDER

To create a symlink on a Linux or Mac based system, run the following commands from a terminal window:

cd /path/to/agent/root_folder
ln -s /path/to/target_folder link_name

Installing the Files.com Agent as a system service allows the Agent to automatically start when the system is started or rebooted.

System services allow programs and applications, such as the Agent, to automatically start without requiring a user login. When the Agent is installed as a system service, it will automatically start when the system is powered on and online.

For Windows x86 64bit based systems, we provide an Agent Installer MSI executable which can be found on the download site for the Agent.

The MSI should only be used for installing the Agent as a system service. To run the Agent manually, prior to installing as a service, download and use the EXE instead.

The Agent Installer MSI should be downloaded into the same folder as the Agent configuration file. After updating the configuration file, double-click the Agent Installer MSI executable to install the Agent as a service.

Once installed as a service, the configuration file for the Agent will be located at C:\Program Files\Files.com-Agent\config.json.

To uninstall the service, use the Windows "Add or remove programs" app to remove the Agent.

You can also install the Agent as a Windows service, for both x86 64bit and ARM 64bit based Windows systems, by using the command:

files-agent service install --config C:\path\to\files_agent_config.json

When installed this way, the executable and configuration file remain in their current locations.

To start the service, open the Windows Services app, select the Files.com Agent v2 entry, right-click on it, and select Start. The service can also be started from the command line using the command:

files-agent service start

If any modifications to the configuration file are needed then stop the service first, modify the configuration file, and restart the service.

To stop the service, open the Windows Services app, select the Files.com Agent v2 entry, right-click on it, and select Stop. The service can also be stopped from the command line using the command:

files-agent service stop

To uninstall the service, use the command:

files-agent service uninstall

You can install the Agent as a Linux service by using the command:

files-agent service install --config /path/to/files_agent_config.json

When installed this way, the executable and configuration file remain in their current locations.

To start the service, use the command:

files-agent service start

If any modifications to the configuration file are needed then stop the service first, modify the configuration file, and restart the service.

To stop the service, use the command:

files-agent service stop

To uninstall the service, use the command:

files-agent service uninstall

You can install the Agent as a Mac service by using the command:

files-agent service install --config /path/to/files_agent_config.json

When installed this way, the executable and configuration file remain in their current locations.

To start the service, use the command:

files-agent service start

If any modifications to the configuration file are needed then stop the service first, modify the configuration file, and restart the service.

To stop the service, use the command:

files-agent service stop

To uninstall the service, use the command:

files-agent service uninstall

All actions performed within Agent Remote Server folders are stored in the corresponding logs in exactly the same way as all other types of Remote Server and History actions are logged.

The Agent also produces a local log file on the host system.

When the Agent is run manually, the log file is named files-agent.log and will be located in the same folder that Agent resides in.

When the Agent is run as a Windows service, the log file is named logs.log and will be located in the C:\Program Files\Files.com-Agent folder.

You can customize the location of the log file by using the --log_file flag when running the Agent:

files-agent start --config files_agent_config.json --log_file C:\path\to\outputfile.log

To upgrade the Agent, download the latest version of the Agent and replace the previous files-agent executable with the newer downloaded version.

Stop and restart the Agent. No changes to the configuration file are required for an upgrade.

If the Agent has been installed as a system service, stop and restart the system service.

The first version of the Agent was built into the Files.com CLI App and has now been deprecated. It used a different connection direction and method, requiring you to open firewall ports to allow Files.com to connect inbound to your on-premise system that hosts the Agent.

Both versions of the Agent can run simultaneously on the same host system.

To migrate from Agent v1 to the latest version, follow these steps:

1. Install the latest version of the Agent.
2. Reconfigure any Remote Mounts and Remote Syncs that use your old Agent's Remote Server to instead use the new Agent's Remote Server.
3. Uninstall the old Agent.