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 |
| Active | An inactive connection keeps its definition and cannot be used by services |
| Store file contents | Whether the audit log keeps the bytes of each transferred file, in addition to the always-recorded metadata |
| Verify stores by | How an upload is confirmed - Size compares the size of the remote file with what was sent, Read back reads the file back from the server and compares its checksum with that of the file sent |
| Address | The remote server's address, optionally including a port, e.g. example.com, example.com:22022 or [2001:db8::1]: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 file | 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 |
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:
.. 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
~/.sshare 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 600the 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_hostsfile 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:
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.