Outgoing SFTP connections

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:

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

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:

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

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

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

/home/partner/incoming/invoice.pdf

What you can do with the connection

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

from zato.server.service import Service

class MyService(Service):

    def handle(self):

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

See the connection API for everything the connection object offers, and file transfer schedules for having Zato watch a directory on this server for you.

Connections as YAML

The same connection in enmasse YAML, with key-based authentication:

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 lists all the fields.

Learn more