SFTP / SSH

The SFTP integration backs up and restores directories on remote servers over SFTP, the file transfer protocol that runs over SSH. It can also host a Kloset store on an SFTP server.

The integration includes three connectors:

The connectors can be combined with each other and with other Plakar connectors.

Requirements

• An SFTP server reachable over SSH.
• Read access to the directories being backed up, and write access to the directories being restored to.
• To write to a Kloset store, write access to the store directory and support for the posix-rename@openssh.com extension. See Store requirements.

Installation

The SFTP integration is distributed as a Plakar package.

$ plakar pkg add sftp

$ plakar pkg show

$ plakar pkg build sftp

$ plakar pkg add -allow-unsigned ./sftp_v1.0.0_darwin_arm64.ptar

$ plakar pkg show

To list, upgrade, or remove the package, see managing packages guide.

SSH access

Plakar connects to the server over SSH. The username, port and identity file are best set in the SSH configuration (~/.ssh/config) under a host alias, which Plakar then references in its URLs.

Host aliases

A host alias in ~/.ssh/config keeps Plakar commands short and independent of the actual host details:

Host sftp-prod
  HostName host.example.com
  User sftpuser
  Port 22
  IdentityFile ~/.ssh/id_ed25519_plakar

Test the alias:

$ sftp sftp-prod

Then reference it in Plakar URLs:

$ plakar store add sftp_store sftp://sftp-prod/backups
$ plakar source add sftp_src sftp://sftp-prod/srv/data
$ plakar destination add sftp_dst sftp://sftp-prod/srv/restore

Key-based authentication

Unattended jobs must not prompt for passwords, so SSH authentication must be key-based and passwordless:

$ ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_plakar -C plakar@backup
$ ssh-copy-id -i ~/.ssh/id_ed25519_plakar.pub sftpuser@host.example.com
$ sftp -i ~/.ssh/id_ed25519_plakar sftpuser@host.example.com

If the private key is encrypted, load it into an SSH agent:

$ eval "$(ssh-agent -s)"
$ ssh-add ~/.ssh/id_ed25519_plakar

The key can also be set on the connector itself. identity points to a private key file. ssh_private_key passes the key material directly, and Plakar loads it into the SSH agent for the duration set by ssh_private_key_ttl. ssh_auth_sock selects the agent socket to use.

Host keys

The server’s host key is verified before connecting, against ~/.ssh/known_hosts or against the entry given in host_key. In production, keep verification enabled and manage ~/.ssh/known_hosts normally. insecure_ignore_host_key=true disables verification and should only be used in isolated test environments.

Configuration

The SFTP connectors read from and write to a directory on the server, addressed by an sftp:// URL. The same URL format is used whether the directory is backed up, restored to, or used to host a Kloset store.

Backup flow

flowchart LR

subgraph Source["SFTP Server"]
  FS["/srv/data"]
end

Plakar["Plakar"]

Via["Retrieve data via
SFTP source connector"]

Transform["Encrypt & deduplicate"]

Store["Kloset Store"]

FS --> Via --> Plakar --> Transform --> Store

Restore flow

flowchart LR

Store["Kloset Store"]

Transform["Decrypt & reconstruct"]

Plakar["Plakar"]

Via["Push data via
SFTP destination connector"]

subgraph Destination["SFTP Server"]
  FS["/srv/restore"]
end

Store --> Transform --> Plakar --> Via --> FS

Store flow

flowchart LR

Source["Source data"]

Plakar["Plakar"]

Transform["Encrypt & deduplicate"]

Via["Store snapshot via
SFTP store connector"]

subgraph Store["SFTP Server"]
  Kloset["Kloset Store"]
end

Source --> Plakar --> Transform --> Via --> Kloset

Shared configuration

The following options apply to the source, destination and store connectors.

ssh_private_key, ssh_private_key_ttl and ssh_auth_sock are not supported on Windows.

Destination configuration

The following options are available to the destination connector, in addition to those in Shared configuration.

Restore behaviour

Restored files and directories receive their final permissions when they are created, so restored content is never readable by more users than the snapshot allows, even while the restore is running. Directories keep owner read, write and execute permissions until the restore finishes, so that a read-only directory can still be populated, and then receive their final mode.

Symbolic links are restored only if their target resolves inside the destination directory. Relative targets are resolved from the link’s location, and absolute targets are compared as paths on the server. A link whose target falls outside the destination, such as ../../etc/passwd or /usr/bin/python3 restored under /srv/restore, is reported as failed and is not created.

Store requirements

Writing to a Kloset store requires the server to support the posix-rename@openssh.com SFTP extension, which OpenSSH provides. Plakar checks for it on the first write to the store and fails with an error if it is missing.

Reading from a store does not need the extension. A store on an OpenSSH server running in read-only mode (sftp-server -R), which does not advertise it, can be used as the source of a sync or browsed in the UI.

Example

Create a Kloset store on an SFTP server and use it:

# Configure the Kloset store
$ plakar store add sftp_store sftp://sftp-prod/backups

# Initialize the Kloset store
$ plakar at "@sftp_store" create

# List snapshots in the Kloset store
$ plakar at "@sftp_store" ls

# Verify integrity of the Kloset store
$ plakar at "@sftp_store" check

# Back up a local folder to the Kloset store
$ plakar at "@sftp_store" backup /etc

Back up a remote directory:

# Configure a source pointing to the remote SFTP directory
$ plakar source add sftp_src sftp://sftp-prod/srv/data

# Back up the remote directory to a Kloset store on the filesystem
$ plakar at /var/backups backup "@sftp_src"

# Or back up the remote directory to the Kloset store on SFTP created above
$ plakar at "@sftp_store" backup "@sftp_src"

Restore a snapshot to a remote directory:

# Configure a destination pointing to the remote SFTP directory
$ plakar destination add sftp_dst sftp://sftp-prod/srv/restore

# Restore a snapshot from a filesystem-hosted Kloset store to the remote SFTP directory
$ plakar at /var/backups restore -to "@sftp_dst" <snapshot_id>

# Or restore a snapshot from the Kloset store on SFTP created above to the remote SFTP directory
$ plakar at "@sftp_store" restore -to "@sftp_dst" <snapshot_id>

Snapshots can be moved between two SFTP-hosted stores by defining both stores and synchronizing them with plakar at "@store1" sync to "@store2".

Limitations and scope

Files that change during a backup can leave the snapshot reflecting different points in time for different files. For highly dynamic paths, quiesce the workload or back up from a read-only replica.

Troubleshooting

• SSH works but SFTP fails: the SFTP subsystem must be enabled on the server.
• Path not found on a chrooted account: the path in location is relative to the chroot, not to the server’s filesystem root.

See also

• Plakar Architecture (Kloset Engine)
• OpenSSH / SFTP Documentation