FileMage Gateway - Documentation Reference

# Configuration Reference

# Properties

# acme_use_auto_tls

  • type: bool
  • default: no

Enable automatic certificates from https://letsencrypt.org. acme_hostname must also be set.

# acme_hostname

  • type: list(string)

The hostnames for which you want a certificate issued. Each hostname must resolve to the servers public IP address.

# acme_cache_dir

  • type: string

Path to the directory where requested Let's Encrypt TLS certificates will be stored.

# acme_contact_email

  • type: string

An email address used by Let's Encrypt to send notifications about events such as certification revocations and expirations.

# audit_retention_days

  • type: int
  • default: 7

Number of days to retain entries in the management portal audit log.

# audit_disable

  • type: bool

Disable all audit logging in the management portal.

# audit_log

Enables audit logs to be written to the a file on disk in addition to the audit log available in the management portal.

Sample Configuration:

audit_log:
  enabled: yes
  path: /var/log/filemage/audit.log
  format: logfmt
  max_size_mb: 10
  max_backups: 3
  max_age_days: 28
  compress: yes

# authentication_log

Generate detailed logs of all authentication events.

Events:

LOGIN_SUCCESS: user provided valid credentials
LOGIN_FAILED: user provided invalid credentials
LOGIN_BLOCKED: login attempt from blocked IP address
IP_BANNED: IP address banned after too many failed login attempts
BAN_EXPIRED: IP address ban expired

Sample Configuration:

authentication_log:
  enabled: yes
  path: /var/log/filemage/auth.log
  format: logfmt
  max_size_mb: 10
  max_backups: 3
  max_age_days: 28
  compress: yes

Sample Output:

time=2020-04-04T01:12:03.8093335Z remote=172.18.0.1 user=bob event=LOGIN_FAILED
time=2020-04-04T01:12:08.7606184Z remote=172.18.0.1 user=bob event=LOGIN_SUCCESS
time=2020-04-04T01:12:12.5485004Z remote=172.18.0.1 event=IP_BANNED
time=2020-04-04T01:12:12.5485566Z remote=172.18.0.1 user=bob event=LOGIN_FAILED
time=2020-04-04T01:12:30.9450762Z remote=172.18.0.1 user=bob event=LOGIN_BLOCKED

# google_identity_service

  • type: map

    • # client_id

      • type: string

      OAuth client ID from Google Cloud Platform Web application credentials.

    • # service_account_key

      • type: string

      The local path of a the service account json key file used to retrieve groups from Google Workspace.

    • # allowed_groups

      • type: list(string)

      A list of groups in your Google Workspace domain. Users must be members of one of these groups to be authenticated.

    • # gsuite_admin_email

      • type: string

      The email address of the Google Workspace admin user which will be used to retrieve group information.

Configure Google Workspace as a login provider.

# azure_active_directory

  • type: map

    • # client_id

      • type: string

      Azure Active Directory Application (client) ID.

    • # tenant_id

      • type: string

      Azure Active Directory Directory (tenant) ID.

Configure Azure Active Directory as a login provider.

# azure_upload_buffer_size

  • type: int
  • default: 10485760

Size in bytes of Azure blob block size.

# azure_put_md5

  • type: bool
  • default: false

Enable to calculate and store the ContentMD5 value of blobs.

# tls_certificate

  • type: string
  • default: "/opt/filemage/cert.pem"

Path to a file containing a TLS certificate in PEM format.

# tls_certificate_key

  • type: string
  • default: "/opt/filemage/key.pem"

Path to a file containing the secret key for the TLS certificate.

# tls_min_version

  • type: string
  • default: "1.0"

Lowest available TLS version.

# tls_max_version

  • type: string
  • default: "1.2"

Highest available TLS version.

# tls_ciphers

  • type: list
  • default:
tls_ciphers:
   - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
   - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
   - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
   - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
   - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
   - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
   - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
   - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
   - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
   - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
   - TLS_RSA_WITH_AES_128_GCM_SHA256
   - TLS_RSA_WITH_AES_256_GCM_SHA384
   - TLS_RSA_WITH_AES_128_CBC_SHA
   - TLS_RSA_WITH_AES_256_CBC_SHA
   - TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
  • supported:
tls_ciphers:
   - TLS_RSA_WITH_RC4_128_SHA
   - TLS_RSA_WITH_3DES_EDE_CBC_SHA
   - TLS_RSA_WITH_AES_128_CBC_SHA
   - TLS_RSA_WITH_AES_256_CBC_SHA
   - TLS_RSA_WITH_AES_128_CBC_SHA256.
   - TLS_RSA_WITH_AES_128_GCM_SHA256
   - TLS_RSA_WITH_AES_256_GCM_SHA384
   - TLS_ECDHE_ECDSA_WITH_RC4_128_SHA.
   - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
   - TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
   - TLS_ECDHE_RSA_WITH_RC4_128_SHA.
   - TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
   - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
   - TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
   - TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
   - TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
   - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
   - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
   - TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
   - TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256
   - TLS_AES_128_GCM_SHA256
   - TLS_AES_256_GCM_SHA384
   - TLS_CHACHA20_POLY1305_SHA256
   - TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
   - TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

# tls_prefer_server_ciphers

  • type: bool
  • default: no

Prefer server ciphers over client ciphers.

# http_address

  • type: string
  • default: 0.0.0.0

The bind address of the HTTP and HTTPS listener.

# http_cors_origins

  • type: list

List of CORS whitelisted hostnames.

# http_session_age

  • type: int
  • default: 604800

Max age in seconds of browser session cookie.

  • type: bool
  • default: no

Set the secure flag on the session cookie.

# http_healthcheck_path

  • type: string
  • default: "/healthz"

Path of health check endpoint.

# http_port

  • type: int
  • default: 80

The port used by the HTTP listener.

# https_port

  • type: int
  • default: 443

The port used by the HTTPS listener. Set to -1 to disable.

# http_redirect_hostname

  • type: string

Redirect to the specified hostname.

# http_csp_header

  • type: string

Optionally specify a value for the Content Security Policy header.

# pg_host

  • type: string
  • default: "/var/run/postgresql/"

Database hostname or unix socket.

# pg_port

  • type: int
  • default: 5432

Database port.

# pg_user

  • type: string
  • default: "filemage"

Database user.

# pg_password

  • type: string

Database user password.

# pg_database

  • type: string
  • default: "filemage"

Database name.

# pg_ssl_mode

  • type: string

Database SSL connection mode.

# pg_ssl_root_cert

  • type: string

The file path of the root certificate file. Note file permission must be 600.

# pg_ssl_cert

  • type: string

The file path of the certificate file. Note file permission must be 600.

# pg_ssl_key

  • type: string

The file path of the certificate key file. Note file permission must be 600.

# pg_max_open_connections

  • type: int

The maximum number of open connections to the database from each application process. Set to 0 for unlimited connections.

# ftp_address

  • type: string
  • default: "0.0.0.0"

Bind address of the FTP listener.

# ftp_port

  • type: int
  • default: 21

The port used by the FTP listener.

# ftp_public_address

  • type: string

The IP address presented to clients for passive connections. You may provide a hostname which will be resolved at startup.

# ftp_data_port_start

  • type: int
  • default: 32768

Start value of passive mode FTP port range.

# ftp_data_port_end

  • type: int
  • default: 65535

End value of passive mode FTP port range.

Note

When deploying from Azure Marketplace, this range is set to 6000-6005.

# ftp_idle_timeout

  • type: int
  • default: 900

Seconds to wait before terminating idle FTP command connections. Set to 0 to disable.

# ftp_require_tls

  • type: bool
  • default: no

Require TLS protection for both control and data connections. In explicit mode TLS must be negotiated before authenticating.

# ftp_tls_mode

  • type: string
  • default: "explicit"

Specify implicit or explicit to configure the FTPS behavior. Having separate listeners for explicit and implicit mode is not supported. A TLS certificate must be configured when using implicit mode.

# ftp_proxy_protocol

  • type: bool
  • default: no

Enable compatibility with Proxy Protocol v1 and v2 on the FTP listener.

# ftp_pasv_promiscuous

  • type: bool
  • default: no

Don't compare remote IP of command connection and data connection in passive mode.

# ftp_log

  • type: log_config

    • # path

      • type: string
      • default: "/var/log/filemage/ftp.log"

Generate detailed logs of all received FTP commands.

Sample Configuration:

ftp_log:
  enabled: yes
  path: /var/log/filemage/ftp.log
  format: logfmt
  max_size_mb: 10
  max_backups: 3
  max_age_days: 28
  compress: yes

Sample Output:

time=2019-07-04T02:53:37.9396798Z client=172.20.0.3:21 remote=172.20.0.1:38556 command=AUTH param=TLS session=5e70633e15067daf007031a8151ac249
time=2019-07-04T02:53:37.9611056Z client=172.20.0.3:21 remote=172.20.0.1:38556 command=USER param=filemage session=5e70633e15067daf007031a8151ac249
time=2019-07-04T02:53:37.9620737Z client=172.20.0.3:21 remote=172.20.0.1:38556 command=PASS username=filemage session=5e70633e15067daf007031a8151ac249
time=2019-07-04T02:53:38.0968158Z client=172.20.0.3:21 remote=172.20.0.1:38556 command=OPTS param="UTF8 ON" username=filemage session=5e70633e15067daf007031a8151ac249

# sftp_address

  • type: string
  • default: "0.0.0.0"

The bind address of SFTP listener.

# sftp_port

  • type: int
  • default: 2222

Port used by SFTP listener.

# sftp_host_keys

  • type: string
  • default:
sftp_host_keys:
   - /etc/ssh/ssh_host_dsa_key
   - /etc/ssh/ssh_host_ecdsa_key
   - /etc/ssh/ssh_host_ed25519_key
   - /etc/ssh/ssh_host_rsa_key

The paths to the host key files to use.

# sftp_ciphers

  • type: list
  • default:
sftp_ciphers:
   - aes128-gcm@openssh.com
   - chacha20-poly1305@openssh.com
   - aes128-ctr
   - aes192-ctr
   - aes256-ctr
  • supported:
sftp_ciphers:
   - 3des-cbc
   - aes128-cbc
   - aes128-ctr
   - aes128-gcm@openssh.com
   - aes192-ctr
   - aes256-ctr
   - arcfour
   - arcfour128
   - arcfour256
   - chacha20-poly1305@openssh.com

The list of cipher algorithms that are presented to the client, in the specified order, during the SSH key exchange.

# sftp_key_exchanges

  • type: list
  • default:
sftp_key_exchanges:
  - curve25519-sha256@libssh.org
  - ecdh-sha2-nistp256
  - ecdh-sha2-nistp384
  - ecdh-sha2-nistp521
  - diffie-hellman-group14-sha1
  - diffie-hellman-group14-sha256
  - diffie-hellman-group1-sha1
  • supported:
sftp_key_exchanges:
   - curve25519-sha256@libssh.org
   - ecdh-sha2-nistp256
   - ecdh-sha2-nistp384
   - ecdh-sha2-nistp521
   - diffie-hellman-group14-sha1
   - diffie-hellman-group14-sha256
   - diffie-hellman-group1-sha1
   - diffie-hellman-group-exchange-sha256

The list of key exchange algorithms to use.

# sftp_digests

  • type: list
  • default:
sftp_digests:
   - hmac-sha2-256-etm@openssh.com
   - hmac-sha2-256
   - hmac-sha1
   - hmac-sha1-96

The list of MAC digest algorithms to use. All supported algorithms are enabled by default.

# sftp_log

  • type: log_config

    • # path

      • type: string
      • default: "/var/log/filemage/sftp.log"

Generate detailed logs of all received SFTP commands.

Sample Configuration:

sftp_log:
  enabled: yes
  path: /var/log/filemage/sftp.log
  format: logfmt
  max_size_mb: 10
  max_backups: 3
  max_age_days: 28
  compress: yes

# sftp_connections_log

  • type: log_config

    • # path

      • type: string
      • default: "/var/log/filemage/sftp-connections.log"

Generate detailed logs of all key exchange algorithms, MACs, and ciphers used for each SFTP connection attempt.

Sample Configuration:

sftp_connections_log:
  enabled: yes
  path: /var/log/filemage/sftp-connections.log
  format: logfmt
  max_size_mb: 10
  max_backups: 3
  max_age_days: 28
  compress: yes

Sample Output:

time=2023-08-15T20:18:37.488154096Z result=success remote=172.18.0.1:61500 local=172.18.0.5:2222 kex=ecdh-sha2-nistp256,ecdh-sha2-nistp384 macs=hmac-sha2-256,hmac-sha2-512 ciphers=aes128-ctr,aes192-ctr

# sftp_disable_passwords

  • type: bool
  • default: no

Disable password authentication for all users when connecting with SFTP.

# sftp_trusted_user_ca_keys

  • type: list

List of file paths of trusted certificate authority public keys for SSH certificate authentication.

# sftp_idle_timeout

  • type: int
  • default: 0

Seconds to wait before terminating idle SFTP command connections. Set to 0 to disable.

# sftp_server_identity

  • type: string
  • default: "FileMageGateway"

The SSH server identity string sent. Will be prefixed with SSH-2.0-.

# sftp_proxy_protocol

  • type: bool
  • default: no

Enable compatibility with Proxy Protocol v1 and v2 on the SFTP listener.

# smtp_host

  • type: string

The hostname of the SMTP server to be used for sending mail.

# smtp_port

  • type: int
  • default: 587

The port number of SMTP server to be used for sending mail.

# smtp_username

  • type: string

The username used to authenticate with the SMTP server.

# smtp_password

  • type: string

The password used to authenticate with the SMTP server.

# smtp_sender

  • type: string
  • default: "no-reply@sender"

The Sender address to use when sending mail.

# smtp_extra_headers

  • type: map(string) string

A key value map of extra headers to add to out going emails.

Example:

smtp_extra_headers:
  x-smtpapi: '{"asm_group_id": 000000}'

# smtp_insecure_tls

  • type: bool

Skip TLS certificate validation when sending emails.

# ldap_url

  • type: string

The LDAP server URL to connect to. Must include protocol ldap or ldaps. Port is optional.

# ldap_username

  • type: string

Distinguished name of object to bind when performing user search. Example: "uid=admin,ou=system".

# ldap_password

  • type: string

Password to use when performing user search.

# ldap_search_filter

  • type: string

An optional LDAP user search filter. Example: "(objectClass=user)".

# ldap_base_dn

  • type: string

Base DN under which to perform user search. Example: "ou=users,dc=mycompany,dc=com"

# ldap_username_attribute

  • type: string
  • default: "sAMAccountName"

Attribute on the user attribute object to use as the username.

# ldap_insecure_tls

  • type: bool
  • default: no

Skip LDAP server TLS certificate verification.

# ldap_start_tls

  • type: bool
  • default: no

Issue a StartTLS command after establishing an unencrypted connection.

# ldap_request_timeout

  • type: int
  • default: 90

Timeout, in seconds, for the connection when making requests to the server.

# ldap_tls_min_version

  • type: string

Minimum TLS version to use. Accepted values are "1.0", "1.1", "1.2", "1.3".

# ldap_tls_max_version

  • type: string

Maximum TLS version to use. Accepted values are "1.0", "1.1", "1.2", "1.3".

# ldap_certificate

  • type: string

CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded.

# ldap_client_cert

  • type: string

Client certificate to provide to the LDAP server, must be x509 PEM encoded.

# ldap_client_key

  • type: string

Client certificate key to provide to the LDAP server, must be x509 PEM.

# ldap_sync_interval

  • type: int

Interval in minutes to perform user synchronization search.

# ldap_case_sensitive

  • type: bool
  • default: no

By default all usernames will be lowercased before importing. Enable this to preserve case in usernames when importing.

# management_port

  • type: int

Alias for https_port.

# workspace_port

  • type: int
  • default: -1

The port to use for the user workspace portal. The default setting of -1 disables access to the workspace portal.

# workspace_public_url

  • type: string

The publicly accessible base URL, including protocol and hostname, of the workspace portal to be used in password reset emails for links pointing to the workspace portal.

  • type: string

Path to a file containing the custom logo for the workspace portal.

Note

When specifying filepaths in Windows it is recommended to wrap the value in single quotes.

# workspace_favicon

  • type: string

Path to a file containing the custom logo for the workspace portal.

# workspace_css

  • type: map

    • # button_color

      • type: string

      CSS color value to apply to workspace buttons.

    • # button_text_color

      • type: string

      CSS color value to apply to workspace button texts.

      • type: string

      CSS color value to apply to the workspace navigation bar.

    • # login_text

      • type: string

      Custom text to display in login box.

The customizable styling properties available for the workspace portal.

# workspace_disable_share

  • type: bool

Disables the share link functionality.

# otp_issuer

  • type: string

The name that will appear in the issuer field for this application in the OTP authenticator application. When this setting is blank OTP MFA is disabled.

# rename_allow_overwrite

  • type: bool
  • default: no

Allow files to be overwritten when issuing rename commands.

# password_min_length

  • type: int

Minimum length of user passwords.

# password_requirements

  • type: map

Require password contains at least one of the indicated character types.

Sample Configuration:

password_requirements:
  upper_case: yes
  lower_case: yes
  digits: yes
  special_character: yes

# password_expire_days

  • type: int
  • default: 0

The number of days that may elapse before a user password must be reset. Set to 0 to disable. This option is ignored if workspace_port is not set.

# connection_log

  • type: log_config

    • # path

      • type: string
      • default: "/var/log/filemage/connections.log"

Generate detailed logs of all FTP and SFTP connections established to the server.

Sample Configuration:

connection_log:
  enabled: yes
  path: /var/log/filemage/connections.log
  format: json
  max_size_mb: 10
  max_backups: 3
  max_age_days: 28
  compress: yes

Sample Output:

time=2019-07-04T02:53:32.4361712Z client=172.20.0.3:2222 remote=172.20.0.1:57768 msg="open sftp connection"
time=2019-07-04T02:53:37.9370762Z client=172.20.0.3:21 remote=172.20.0.1:38556 msg="open ftp control connection"
time=2019-07-04T02:53:42.2099408Z client=172.20.0.3:6001 remote=172.20.0.1:38624 msg="open ftp passive data connection"

# lockout

  • type: map

    • # enabled

      • type: bool
      • default: no

    • # max_attempts

      • type: int
      • default: 10

      Number of allowed failed login attempts before blocking further login attempts.

    • # interval

      • type: int
      • default: 60
      • unit: seconds

      Interval in seconds during which failed login attempts are evaluated.

    • # ban_duration

      • type: int
      • default: 60
      • unit: seconds

      Duration in seconds during which further login attempts will be blocked.

Block repeated failed login attempts from the same remote IP. Applies to both SFTP and FTP listeners.

Sample Configuration:

lockout:
  enabled: true
  max_attempts: 5
  interval: 15
  ban_duration: 120

# metrics

Custom application metrics can emitted to various metric sink services.

Available metrics:

BytesUploaded
BytesDownloaded
HeapUsed
LoginsSucceeded
UploadsInProgress
DownloadsInProgress
  • type: map

    • # service

      • type: string

      The metrics service to send metrics data to. Currently only azure and google_cloud is supported.

    • # azure_insights_instrumentation_key

      • type: string

      The instrumentation key for the Azure Insights workspace to use.

# welcome_email_subject

  • type: string
  • default: "Account Setup Instructions"

The subject line for account welcome emails.

# welcome_email_template

  • type: string
  • default: "/opt/filemage/templates/welcome_default.html"

File path of the HTML template to use for account welcome emails.

# password_reset_subject

  • type: string
  • default: "Password Reset Instructions"

The subject line for password reset emails.

# password_reset_template

  • type: string
  • default: "/opt/filemage/templates/reset_default.html"

File path of the HTML template to use for password reset emails.

# content_type_detection

  • type: string
  • default: "extension"
  • supported:
    • "none"
    • "extension"
    • "force-binary"

Determines how to content types are detected on created files. The default value extension uses the extension of the filename. Set to none to fallback to the default behavior of the cloud provider. Set to force-binary to make all content types application/octet-steam. This is useful for forcing all files to be downloaded when opening them in the workspace portal.

# client_ip_strategy

  • type: string
  • default: "remote-address"
  • supported:
    • "remote-address"
    • "rightmost-trusted-count"
    • "single-ip-header"

Specifies how the client IP address is determined. Use single-ip-header for custom headers such as True-Client-IP or X-Real-IP. Use rightmost-trusted-count for X-Forwarded-For or Forwarded headers. The default value remote-address disables header checking and uses the remote address of connection.

Warning

Client IP headers are easily spoofed and can be used to bypass lockout rate limiting. This setting should only be enabled if the specified header is being set by a trusted proxy.

# client_ip_trusted_count

  • type: int
  • default: 1

When using rightmost-trusted-count, this setting can be used when multiple proxies are appending client IPs.

# client_ip_header

  • type: string
  • default: X-Forwarded-For

The header name to use when determining client IPs.

# home_directory_required

  • type: bool
  • default: no

When enabled users will be required to have a home directory path specified.

# workspace_proxy_transfers

  • type: bool
  • default: no

When enabled workspace file transfers will be proxied through the application server instead of going directly to the cloud providers storage API.

# Complex Types

# log_config

  • type: map

    • # enabled

      • type: bool
      • default: no

    • # path

      • type: string

    • # format

      • type: string
      • default: "logfmt"

      Can be either "json" or "logfmt".

    • # max_size_mb

      • type: int
      • default: 100

      Max file size before rotating.

    • # max_backups

      • type: int
      • default: 5

      Max number of rotated files to keep. Set to 0 to retain all files.

    • # max_age_days

      • type: int
      • default: 0

      Number of days to keep rotated log files. Set to 0 to disable deletion based on age.

    • # compress

      • type: bool
      • default: no

      Compress rotated log files.

← FTP Public Address →