# SFTP Connection

{% hint style="info" %}
CONNECTORS ARE COMING AUGUST 2026
{% endhint %}

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

```bash
# RSA (4096-bit)
ssh-keygen -t rsa -b 4096 -f ubiquity-connector-key -C "ubiquity-connector"

# Ed25519 (modern, shorter)
ssh-keygen -t ed25519 -f ubiquity-connector-key -C "ubiquity-connector"
```

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:

```
-----BEGIN OPENSSH PRIVATE KEY-----
[key content]
-----END OPENSSH PRIVATE KEY-----
```

```
-----BEGIN RSA PRIVATE KEY-----
[key content]
-----END RSA PRIVATE KEY-----
```

***

### **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

```bash
# Create user with no shell access
useradd -m -s /usr/sbin/nologin ubiquity-connector

# Create the directory structure
mkdir -p /home/ubiquity-connector/data/ubiquity
chown ubiquity-connector:ubiquity-connector /home/ubiquity-connector/data/ubiquity
```

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

```bash
cat ubiquity-connector-key.pub >> ~/.ssh/authorized_keys
```

**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**](mailto: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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ubiquity.co.nz/documentation/data-and-integrations/connectors/connection-setup/sftp-connection.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.