Ctrlk
Login to UbiQuity
linkedin
For the complete documentation index, see llms.txt. This page is also available as Markdown.

SFTP Connection

Configure your SFTP server and SSH key authentication so UbiQuity can securely connect to your files.

CONNECTORS ARE COMING AUGUST 2026

This guide walks you through configuring your SFTP server so that UbiQuity can securely connect to it. The setup involves creating a dedicated user account, generating an SSH key pair, and installing the public key on your server.

How it works

UbiQuity connects to your SFTP server over SSH using private key authentication. When the connector runs, it establishes a connection using the credentials you provide, then reads from or writes to your configured directory path.

  • Each connection is opened for the duration of the run and closed immediately after processing completes

  • Files are never permanently deleted — after processing, they are moved to an archive/ subfolder, or an error/ subfolder if processing fails

  • The archive/ and error/ directories are created automatically if they do not exist

Before you begin

You'll need the following before starting:

What you need
Description
Example

Hostname

DNS name of your SFTP server

sftp.example.com

Port

SFTP port (default is 22)

22

Username

A dedicated user account for UbiQuity

ubiquity-connector

Private Key

SSH private key in PEM format

See below

Base Path

Root directory for connector files

/data/ubiquity

Important: The hostname must be a DNS name, not an IP address. This is required for connection uniqueness tracking within the platform.

Step 1: Generate an SSH key pair

Generate a dedicated SSH key pair for the UbiQuity connector. Either RSA or Ed25519 keys are supported.

bash

This produces two files:

  • ubiquity-connector-key — the private key (provided to UbiQuity)

  • ubiquity-connector-key.pub — the public key (installed on your server)

Important: Do not use a passphrase when generating the key. The connector cannot prompt for a passphrase during an automated run.

The private key must be in PEM format. Accepted formats:

Step 2: Configure your SFTP server

Create a dedicated user account

Create a user specifically for the UbiQuity connector. Do not reuse an existing account.

bash

The user should:

  • Be restricted to SFTP only — disable shell access where possible

  • Have a home directory or chroot set to the appropriate location

  • Have read and write permissions on the connector directory

Install the public key

Append the public key to the user's authorized_keys file on the server:

bash

Required permissions

The SFTP user requires the following permissions on the base path and its subdirectories:

Permission
Purpose

Read

List and download files for import

Write

Create archive/error directories and upload files

Delete

Remove files from source after moving to archive/error

Rename

Move files between directories

Stat

Check file existence and determine file types

Mkdir

Create archive and error subdirectories

Important: The base path cannot be the root directory (/ or .). You must specify a subdirectory.

Step 3: Add the connector in UbiQuity

Once your server is configured:

  1. In UbiQuity, go to Database > Connectors > Add Connector

  2. Select SFTP

  3. Enter the following details:

    • Hostname — the DNS name of your SFTP server

    • Port — the SFTP port (default: 22)

    • Username — the dedicated user account created for the connector

    • Private Key — paste the contents of your private key file in PEM format

    • Base Path — the root directory for connector files (e.g. /data/ubiquity)

  4. Click Test Connection

A successful test confirms the server is reachable and that the user has the required read, write, and move permissions.

Troubleshooting

"Unable to authenticate" or connection timeout

The connector cannot authenticate with your server. Check:

  • The private key is in valid PEM format with the correct begin/end tags

  • The public key is present in the user's ~/.ssh/authorized_keys on the server

  • The server's sshd_config has PubkeyAuthentication enabled

"Connection refused" or cannot reach the server

The connector cannot establish a connection. Check:

  • The SFTP server is running and listening on the configured port

  • UbiQuity's IP ranges are allowlisted in your firewall — contact support for the current ranges

  • The hostname resolves correctly via DNS (IP addresses are not supported)

  • The port configured in UbiQuity matches the server

"Permission denied" on file operations

Authentication succeeded but the connector cannot read or write files. Check:

  • The user has read and write access to the base path directory

  • Directory ownership and permissions are correct (ls -la /path/to/directory)

  • If SELinux or AppArmor is in use, review its logs for blocked operations

  • If a chroot is configured, confirm it includes the target directory

No files found for processing

  • Confirm files exist in the configured base path

  • Verify the file pattern in UbiQuity matches your file naming convention (e.g. *.csv)

  • Check the archive/ directory — previously processed files will have been moved there

  • Confirm the base path is not set to the root directory

Intermittent connection failures

The connector retries automatically once on a failed connection. If failures persist:

  • Check server connection limits and timeout settings

  • Review server logs for connection rejection reasons

  • Verify network stability between UbiQuity and your server

Additional configuration

Credential rotation

To rotate the SSH key pair, generate a new key pair, install the new public key on the server, update the private key in UbiQuity, then remove the old public key from the server's authorized_keys.

Data retention

Processed files are retained in the archive/ subdirectory and failed files in the error/ subdirectory. Use cron jobs or similar mechanisms to clean up old files. A minimum of 30 days for archive files is recommended for audit purposes.

Hosting options

Your SFTP server can be hosted on-premises, in the cloud (including Azure Blob Storage with SFTP enabled, AWS Transfer Family, or any cloud VM running an SFTP server), or via a managed SFTP provider. The connector works with any standard SFTP server.

Need help?

If you run into issues during setup, contact our support team at support@ubiquity.co.nz with the following details:

  • Your SFTP hostname and port

  • The username configured for the connector (do not send private keys)

  • Any error messages shown in UbiQuity or your server logs

PreviousAzure Blob Storage ConnectionNextSecurity and Data Handling

Last updated

Was this helpful?