Creating a Virtual Machine

We provide a virtual machine image of FileMage Gateway for Microsoft Azure. No installation is required. You just need to create a virtual machine from the Microsoft Azure Virtual Machines Marketplace. This virtual machine image is fully functional upon launch and requires no additional configuration to use. However, you may need to make certain changes depending on your specific use case.


To create a virtual machine, you must have permissions to access and manage a subscription or resource group in Azure.

First Time Login

After deploying the virtual machine make note of its IP address. The browser portal will be available at https://<server-ip>/. A self-signed certificate is used, which you will have to accept to bypass the browser warning. See Encryption for instructions on how to install a signed certificate.


The first time the portal is used you will be asked to register an administrator account.

Default Ports

By default the following ports are used. See Configuration Reference for information on how to change these ports.

Port Description
2222 SFTP
21 FTP
6000-6005 FTP Passive


When HTTPS is enabled traffic on the HTTP port will be redirected to the HTTPS port.


To use SFTP on port 22 sshd must be reconfigured to use a different port.

Increase Passive Mode FTP Port Range

By default, FileMage Gateway deployed on Azure Marketplace is configured to use ports 6000-6005 for passive mode FTP data connections. This port range may be to small in situations where multiple clients attempt to establish data connections at the same time, and may cause connecting clients to experience delays or be completely unable to connect when they request passive data transfers. The following explains how to enable a larger port range for passive mode FTP in FileMage Gateway installed on a Microsoft Azure.

Add inboud security rules

  1. Log in to Microsoft Azure portal.

  2. Go to Virtual machines

    • Click the name of the virtual machine you want to configure.
    • Under Settings, click on Networking.
  3. Click the Add inbound port rule button.

  4. In the “Add inbound security rule” panel, specify the following settings:

    • “Service”. Keep the “Custom” value in the drop-down list.
    • “Port ranges”. Specify the following port range: 32768-60999.
    • “Priority”. This value determines the order in which firewall rules are applied. Rules with low priority are applied before rules with high priority. We recommend keeping the automatically assigned Priority value.
    • “Name”. Give the rule a recognizable name so you can tell it apart from others.
    • (Optional) “Description”. If desired, you can add the description to the rule.
  5. Click OK.

Configure passive mode FTP port range on the server

  1. Log in to your server via SSH as the user you specified when launching the instance.

  2. Open the file /etc/filemage/config.yml (you may need to use sudo), add the following lines to it, and then save the changes:

ftp_data_port_start: 32768
ftp_data_port_end: 60999
  1. Restart the server:
sudo systemctl restart filemage

FileMage Gatway is now configured to use a large range of ports for passive mode FTP data connections.

FTP Public Address Configuration

Public IP auto-detection for Passive Mode FTP

FileMage Gateway will use the Azure instance metadata service to detect the virtual machine's public IP address for passive FTP connections. You may override this address by specifying a FTP public address in the server configuration.

Passive mode FTP behind a NAT

In passive mode FTP, when a client requests a passive data connection, the server responds with the IP address the client should connect to. If the server is behind a load balancer or NAT gateway you must set the FTP public address to the IP address or hostname of the forwarding appliance for passive connections to work properly.

Specifying a custom FTP public address

To specify a different FTP public address IP address or hostname:

  1. Open the file /etc/filemage/config.yml (you may need to use sudo), add the following lines to it, and then save the changes:
ftp_public_address: <PUBLIC_IP_ADDRESS_OR_HOSTNAME>


If you specify a hostname it will be resolved at server startup.

  1. Restart the server:
sudo systemctl restart filemage


By default a self-signed certificate is used. You may upload your own signed certificates or automatically provision them through Lets Encrypt. This configuration applies to both FTPS and HTTPS.

Adding custom certificates

  1. Upload the certificate files to the server.

  2. Open the file /etc/filemage/config.yml (you may need to use sudo), add the following lines to it, and then save the changes:

tls_certificate_key: <PATH_TO_CERTIFICATE_FILE>
tls_certificate_key: <PATH_TO_CERTIFICATE_KEY_FILE>
  1. Restart the server:
sudo systemctl restart filemage

Your certificate is now active and used by the server.

Enabling Lets Encrypt Automatic Certificates

  1. Create a public DNS records that resolves to the servers public IP address.

  2. Open the file /etc/filemage/config.yml (you may need to use sudo), add the following lines to it, and then save the changes:

acme_use_auto_tls: true
acme_hostname: <PUBLIC_DNS_NAME>
  1. Restart the server:
sudo systemctl restart filemage

Let's Encrypt is now enabled and signed certificates will automatically be issued and renewed for free.


Running SFTP on port 22

To make SFTP available on port 22 the OpenSSH server must to be reconfigured to use a different port.

  1. Stop FileMage Gateway.
sudo systemctl stop filemage
  1. Open the OpenSSH server configuration file.
sudo vi /etc/ssh/sshd_config
  1. Uncomment and set the Port directive to the desired SSH port number.
Port 2222
  1. Restart the OpenSSH server.
sudo systemctl restart sshd
  1. Verify that OpenSSH was able to start correctly.
sudo systemctl status sshd
  1. Open the FileMage Gateway configuration file.
sudo vi /etc/filemage/config.yaml
  1. Set the sftp_port configuration to the desired SFTP port number.
sftp_port: 22
  1. Start FileMage Gateway.
sudo systemctl start filemage


Make sure OpenSSH is running properly and can accept new SSH connections before disconnecting your current SSH session to avoid becoming locked out of the system.

Compatibility with older SFTP clients

The default SFTP configuration provides a balance between security and comparability with older clients. If you encounter errors when connecting to the SFTP port of FileMage Gateway you may need to adjust certain SFTP encryption configurations. See the sections for SSH encryption and key exchange algorithms in the configuration reference.

Extended Logging

Detailed protocol and connection logged can be enabled using the configuration parameters ftp_log and connection_log