Agent (On-premise Storage Integration)

The Files.com Agent allows you to integrate any supported remote 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, including:

• locally attached storage, such as local disks and drives.
• network attached storage, such as network drives using CIFS, SMB, and NFS.

The Agent can be used to integrate your business processes that use on-premise file storage locations with Files.com, allowing you to:

• Use your on-premise folders, as sources or destinations, for FTP(S), SFTP, AS2, WebDAV connections.
• Use your on-premise folders, as sources or destinations, for automations and workflows.
• Use your on-premise folders as destinations for inboxes.
• Use your on-premise folders as sources for outboxes, share links, and public hosting.
• 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.

Pre-requisites for the Agent

Operating System

The Files.com Agent is supported on Windows (64bit), Linux, and MacOS (64bit). Verify that your Operating System is listed on the releases page.

Inbound Connection

The Files.com platform will connect to the Agent using a secure encrypted connection. You will need to open an inbound port from the Internet to the server that is hosting the Agent.

Permissions

The Agent will open a network port to listen for a secure encrypted connection from Files.com. The system account running the Agent should have privileges to open a network port. On locked down systems, this may require Administrator privileges.

Agent setup

Setting up a Files.com Agent consists of the following steps:

1. Create a Remote Server for the Agent
2. Download and install the Agent (Files.com CLI App)
3. Download, review, and update the Agent configuration file
4. Open an inbound port from the Internet to the server that is hosting the Agent
5. 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.

Creating a Remote Server

Navigate to Settings > Integrations > Remote servers, click the Add new remote server button and select Files.com Agent.

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

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

• Read and write - Two way file transmission. Files can be sent to, and retrieved from, the Agent. Files.com will be able to create files and folders, read files and folders, update files and folders, and delete files and folders using the Agent.
• Read only - One way file transmission. Files can only be retrieved from the Agent. Files.com will be able to read files and folders using the Agent.
• Write only - One way file transmission. Files can only be sent to the Agent. Files.com will be able to create files and folders, read folders, update files and folders, and delete files and folders using the Agent.

Click the Save button.

Once saved, the new Remote Server will be re-opened for further configuration. You can also use the Edit button to re-open the Remote Server for further configuration.

In addition to the instructions for downloading, configuring, and running the Agent, there will be configuration options for selecting your preferences for the Dedicated IPs and Data Regional Routing settings for this Agent.

Downloading and Installing

The Files.com Agent is built into version 2.1, and later, of the cross-platform Files.com Command Line Interface (CLI) App.

Download the CLI App.

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

No installation is necessary. The CLI app is a self contained app which can be stored anywhere on your computer.

Configuration file

The configuration file is generated when the Remote Server for the Agent is created. Use the Download configuration file button to download the configuration file.

You can download the configuration file for any Agent Remote Server by navigating to Settings > Integrations > Remote servers, selecting the Edit button for the Agent Remote Server, and using the Download configuration file button.

The configuration file is JSON formatted and should be reviewed by the system administrator prior to use.

Prior to use, the following field should be updated in the JSON configuration file:

• root - This specifies the top-level directory that the Agent has access to. Set this value to a directory location on the system that you wish the Agent to access. Use only Linux style slashes, as used in web URLs. For example, /path/to/agent/folder, C:/windows/folder, /mnt/otherserverfolder, or M:/mounted/networkfolder.

The system administrator should also review the following fields:

• permission_set - This shows the permissions that your Files.com administrator specified for the Agent. If the system administrator disagrees, they can change this value. Valid options are read_write, read_only, and write_only.
• port - This shows the network port that will be used for inbound connections from Files.com. The default value is 58550 but can be changed to a custom value.
• hostname - The agent will attempt to automatically determine the public hostname, or IP address, for this server. You can use this field to specify your Fully Qualified Domain Name (FQDN) for inbound connections from Files.com.

Do not edit or change any other fields in the configuration file.

Firewall information

The Files.com Agent uses a single network port, by default port 58550.

Files.com will establish an encrypted and authenticated connection, across the Internet, to the Agent.

Configure your firewall and router to forward incoming connections to the Agent using the port specified in the configuration file. The Agent will only accept connections from Files.com. If required, you can configure your firewall for a list of allowed IP addresses from Files.com.

Running the Agent

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.

Once the Files.com CLI App is installed, and the configuration file is saved onto your system, use the following command to start the Agent:

files-cli agent --config files_agent_config.json

The Agent will connect back to Files.com to register its current status. Navigating to Settings > Integrations > Remote servers, and selecting the Edit button for the Agent Remote Server, will allow you to confirm the status of the Agent. The following fields will show the Agent status information:

• Agent host - The IP address or Fully Qualified Domain Name (FQDN) of the Agent. This is the address that Files.com will use to connect to the Agent.
• Agent port - The network port of the Agent. This is the network port that Files.com will use to connect to the Agent.
• Agent root folder - The top-level folder that the Agent has access to on the server.
• Agent permissions - The permissions that the Agent has ben configured with by the system administrator.
• Agent status - The status of the Agent. When the Agent sends a heartbeat back to Files.com then this status will change from "Waiting for connection..." to "Connected." The "Connected" status confirms that the Agent has been able to "call home" but does not confirm that Files.com will be able to connect back to the Agent through your firewall.

Installing the Agent as a system service

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

Windows:

For Windows based systems, the Files.com Agent can be installed as a Windows Service using this command:

files-cli agent install --config files_agent_config.json

To start the service, use this command:

files-cli agent start

You can also open the Windows Services app, select the files-cli entry, right-click on it, and select Start.

To check the status of the service, use this command:

files-cli agent status

To stop the service, use this command:

files-cli agent stop

You can also open the Windows Services app, select the files-cli entry, right-click on it, and select Stop.

To uninstall the service, use this command:

files-cli agent uninstall

Linux:

Refer to the Systemd documentation of your Linux system for instructions on how to configure the Files.com Agent to start automatically at system startup.

• Systemd documentation for Red Hat based Linux systems.
• Systemd documentation for Debian based Linux systems.

Mac:

Refer to the Launchd documentation for instructions on how to configure the Files.com Agent to start automatically at system startup.

Add Remote Server Mount

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.

From the Files icon on the left, navigate to the location where you want the mounted folder to be and create a new folder. Navigate into the newly created folder and click the Folder Settings button on the top right.

Select Remote Server Mount from the list and click Add new remote server mount button. Select the 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.

Add Remote Server Sync

If you instead prefer to do a Sync with the remote, follow these directions.

1. From Files, navigate into the folder where you would like to add the remote server sync and click Folder settings > Sync to/from remote server.
2. Click the Add new remote server sync button to reveal the form.
3. Select the server you would like to transfer to or from by clicking on the Remote server menu.

Sync direction

Next choose your Sync direction. You have three choices:

1. Push to the remote server: This option uploads files and folders from your designated folder in your Files.com site to the remote server.
2. Pull from the remote server: This option downloads files from the remote server and saves them in your designated folder in your Files.com site.
3. Two-way sync: This option will push files from either server to the other so that both servers have the complete collection of all files. If the same file name exists on both servers with different file contents (as determined by file size), the last modification date is used to determine which version to keep. The file with the most recent modification date is then pushed to the other server. This option does not ever delete files from either server.

Delete or Keep after copying

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.

Remote path

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.

Agent Logs

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

If you need to enable local logging by the Agent, such as for troubleshooting purposes, then you can specify a log file to save logs to using the --log-file-path flag:

files-cli agent --config files_agent_config.json --log-file-path outputfile.log

Upgrading the Agent

To upgrade the Agent, download the latest version of the Files.com Command Line Interface (CLI) App. and replace the previous files-cli executable with the newer downloaded version.

Download the CLI App.

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.

Troubleshooting Agent Connections

Most of the time, Files.com Agent connection issues are caused by one of the following things:

• Most common: Firewalls or other restrictions on the remote server that require a connection from Files.com to be allowed
• Incorrect configuration of the Agent

Check the network firewall configuration at the site hosting the Agent and that all configuration steps described in this article have been followed correctly.