# Outgoing SFTP connections

Server address, username and password, private key authentication and host key checking.

An outgoing SFTP connection is how a Zato service reaches an SFTP server. Services look connections up by the name given here.

In Dashboard, go to `Connections → Outgoing → SFTP` and click Create.

The fields:

| Name | Notes |
| --- | --- |
| Name | The name of the connection, as used in your services |
| Address | The remote server's address, optionally including a port, e.g. `example.com` or `example.com:22022`, with a default port of 22 |
| Username | The username to log in with |
| Password | Optional - if the private key below is encrypted, the password is its passphrase |
| Private key | Optional - the path to a private key file on the Zato server's filesystem, see below |
| Strict host key checking | Whether the remote server's host key must already be known, see below |
| Ignore host key changes | Whether to accept the remote server's key even when it has changed, see below |
| Store transferred content | Whether the [audit log](https://zato.io/docs/admin/audit-log/) keeps the bytes of each transferred file, in addition to the always-recorded metadata |

Both the password and the private key are optional, because the connection may also rely on system-level keys, meaning the keys that already exist in the `~/.ssh` directory of the user account the Zato server runs as.

## Private keys {#private-keys}

The private key field holds a path to a key file on the filesystem of the machine the Zato server runs on. In a container, mount the directory holding the key and point the field at the in-container path:

```bash
docker run \
    -v /path/on/host/keys:/keys:ro \
    ...
```

.. with the field set to `/keys/id_ed25519`.

Details worth knowing:

- When a private key is set, it is the only identity offered to the server - the SSH agent and the default keys in `~/.ssh` are excluded
- An encrypted key uses the Password field as its passphrase
- Key files must not be group- or world-readable, or the underlying SSH client refuses to use them - `chmod 600` the file if in doubt
- The path is checked when a command runs, not when the connection is created, so a connection pointing to a missing file saves fine and fails on first use, with an error naming the path

## Host key checking {#host-key-checking}

Three behaviors are available, in order of precedence:

- With **Ignore host key changes** turned on, any host key is accepted, known or changed. This is meant for containers and test servers that regenerate their keys on every start - do not use it against production systems, because it removes the protection against connecting to an impostor
- Otherwise, with **Strict host key checking** turned on, which is the default, the remote server's host key must already exist in the `known_hosts` file of the user account the server runs as, and connections to servers with unknown or changed keys are rejected
- Otherwise, keys of previously unknown hosts are accepted and recorded automatically on first connection, while connections to hosts whose keys have changed are still rejected

## Paths {#paths}

SFTP paths are ordinary remote file system paths, absolute or relative to the login directory:

```text
/home/partner/incoming/invoice.pdf
```

## What you can do with the connection {#what-you-can-do-with-the-connection}

Once the connection exists, a service reaches it through `self.sftp`:

```python
from zato.server.service import Service

class MyService(Service):

    def handle(self):

        conn = self.sftp['My SFTP Connection']
        conn.ping()
```

See [the connection API](https://zato.io/docs/dev/file-transfer/connection-api.html) for everything the connection object offers, and [file transfer schedules](https://zato.io/docs/dev/file-transfer/schedules.html) for having Zato watch a directory on this server for you.

## Connections as YAML {#connections-as-yaml}

The same connection in [enmasse](https://zato.io/docs/admin/enmasse.html) YAML, with key-based authentication:

```yaml
sftp:
  - name: My SFTP Connection
    address: example.com:22022
    username: zato-transfer
    private_key: /keys/id_ed25519
    strict_host_key_checking: true
```

The [enmasse reference](https://zato.io/docs/admin/enmasse-reference.html) lists all the fields.

## Learn more {#learn-more}

- [File transfer](https://zato.io/docs/dev/file-transfer/) - SFTP, FTP and SMB behind one API, driven by your code or by a schedule
- [The connection API](https://zato.io/docs/dev/file-transfer/connection-api.html) - Upload, download, read, write, list and manage remote entries
- [Schedules](https://zato.io/docs/dev/file-transfer/schedules.html) - Have Zato watch a remote directory and invoke a service per file
- [Receiving files](https://zato.io/docs/dev/file-transfer/receiving-files.html) - What the service receives, and the two ways to refuse a file
- [Real-world feeds](https://zato.io/docs/dev/file-transfer/feeds.html) - Marker files, archiving, bad files and pausing a feed
- [File transfer in enmasse](https://zato.io/docs/dev/file-transfer/enmasse.html) - Connections and schedules as YAML, ready for version control