nbdkit-ssh-plugin(1)

📦

version 1.48.1 · 14 versions

✨ nbdkit-ssh-plugin(1) — NBDKIT ✨

okay bestie, gather round 💖 this is nbdkit-ssh-plugin, a page from the NBDKIT manual, and it's literally the whole vibe of "your remote disk image, but over SSH". It's long so it comes in parts — this is part 1. No sign-off, we're just getting started 🫶

🌸 NAME 🌸

nbdkit-ssh-plugin — access disk images over the SSH protocol

🦋 SYNOPSIS 🦋

nbdkit ssh host=HOST [path=]PATH
           [compression=true] [config=CONFIG_FILE]
           [create=true] [create-mode=MODE] [create-size=SIZE]
           [identity=FILENAME] [known-hosts=FILENAME]
           [password=PASSWORD|-|+FILENAME]
           [port=PORT] [timeout=SECS] [user=USER]
           [verify-remote-host=false]

💜 DESCRIPTION 💜

So this is an nbdkit(1) plugin that lets you reach remote disk images over Secure Shell (SSH). Like, any server that's hosting disk images and also running an SSH server? Boom, that's an NBD source now. No cap. 👑

🎀 EXAMPLES 🎀

nbdkit ssh host=ssh.example.com disk.img

Open a file called disk.img on remote host "ssh.example.com". Because the pathname is relative, it gets opened relative to the user's home directory on the remote server.

The remote file can be read or written. If you want to force read-only access, add the -r flag. 🙈

nbdkit ssh host=ssh.example.com disk.img user=bob

Same as above, but log in using username "bob" (instead of trying the local username).

✨ PARAMETERS ✨

compression=true — Enable compression. You should only use this on slow or bandwidth-limited connections. On fast connections it will slow things down. 🐌
config=CONFIG_FILE — Read local SSH configuration from an alternate configuration file. Libssh expands some "%"-sequences in "CONFIG_FILE", see "Path expansion" below. "CONFIG_FILE" must expand to an absolute path.
config= — Do not read any local SSH configuration.

The "config" parameter is optional. If it is not specified at all then ~/.ssh/config and /etc/ssh/ssh_config are both read. Missing or unreadable files are ignored. 💅

create=true — (nbdkit ≥ 1.32)

If set, the remote file will be created. The remote file is created on the first NBD connection to nbdkit, not when nbdkit starts up. If the file already exists, it will be replaced and any existing content lost. 😭

If using this option, you must use "create-size". "create-mode" can be used to control the permissions of the new file.

create-mode=MODE — (nbdkit ≥ 1.32)

If using "create=true" specify the default permissions of the new remote file. You can use octal modes like create-mode=0777 or create-mode=0644. The default is 0600, ie. only readable and writable by the remote user. 🔒

create-size=SIZE — (nbdkit ≥ 1.32)

If using "create=true", specify the virtual size of the new disk. "SIZE" can use modifiers like 100M etc.

host=HOST — Specify the name or IP address of the remote host.

This parameter is required. ⭐

identity=FILENAME — Prepend the private key (identity) "FILENAME" to the list of identity files used. Libssh examines several identity files by default such as ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa, ~/.ssh/id_rsa and ~/.ssh/id_dsa. Libssh expands some "%"-sequences in "FILENAME", see "Path expansion" below. "FILENAME" must expand to an absolute path.

You can give this parameter multiple times. 🔁

known-hosts=FILENAME — Set name of the file which records the identity of previously seen hosts. Libssh expands some "%"-sequences in "FILENAME", see "Path expansion" below. "FILENAME" must expand to an absolute path.

The default is to check ~/.ssh/known_hosts followed by /etc/ssh/ssh_known_hosts.

password=PASSWORD — Set the password to use when connecting to the remote server.

Note that passing this on the command line is not secure on shared machines. 💀

password=- — Ask for the password (interactively) when nbdkit starts up.
password=+FILENAME — Read the password from the named file. This is a secure method to supply a password, as long as you set the permissions on the file appropriately. 🫶
password=-FD — Read the password from file descriptor number "FD", inherited from the parent process when nbdkit starts up. This is also a secure method to supply a password.
[path=]PATH — Specify the path to the remote file. This can be a relative path in which case it is relative to the remote home directory.

This parameter is required.

"path=" prefix may be omitted in most cases. See "Magic parameters" in nbdkit(1).

port=PORT — Specify the SSH protocol port name or number.

This parameter is optional. If not given then the default ssh port is used.

timeout=SECS — Set the SSH connection timeout in seconds.
user=USER — Specify the remote username.

This parameter is optional. If not given then the local username is used.

verify-remote-host=true
verify-remote-host=false

Set whether or not we verify the remote host is one we have previously seen, using a local file such as ~/.ssh/known_hosts. The default is "true", meaning that we verify the remote host's identity has not changed.

Setting this to "false" is dangerous because it allows a Man-In-The-Middle (MITM) attack to be conducted against you. 🚨

🌈 NOTES 🌈

🔑 Known hosts

The SSH server's host key is checked at connection time, and must be present and correct in the local "known hosts" file.

If you have never connected to the SSH server before then the connection will usually fail. You can:

connect to the server first using ssh(1) so you can manually accept the host key, or
provide the host key in an alternate file which you specify using the "known-hosts" option, or
set verify-remote-host=false on the command line. This latter option is dangerous because it allows a MITM attack to be conducted against you. 💀

🪪 Supported authentication methods

This plugin supports only the following authentication methods: "none", "publickey" or "password". In particular note that "keyboard-interactive" is not supported. ✋

🧚 SSH agent

There is no means for nbdkit to ask for the public key passphrase when it is running as a server. Therefore "publickey" authentication must be done in conjunction with ssh-agent(1).

🧭 Path expansion

In the "config", "identity" and "known-hosts" options, libssh expands some "%"-sequences.

%d — The user's SSH directory, usually ~/.ssh
%u — The local username.
%l — The local hostname.
%h — The remote hostname.
%r — The remote username.
%p — The SSH port number.
"%%" — In libssh > 0.9.0 this expands to a single "%" character. In earlier versions of libssh there was no way to escape a "%" character.

🛰️ Versus nbd+ssh:// URIs

Libnbd ≥ 1.22 supports a non-standard extension to NBD URIs allowing the NBD protocol to be forwarded over SSH (see nbd_connect_uri(3)). This is different from what this plugin does.

For "nbdkit ssh disk.img host=remote":

                                  local  ╵  remote
                                  ─────  ╵  ──────
   ┌─────────────┐      ┌─────────────┐    ╵         ┌─────────────┐
   │ NBD         │ nbd  │ nbdkit      │    ╵ ssh     │ SFTP        │
   │ client      ├─────▶│ ssh plugin  ├─────────────▶│ server      │
   └─────────────┘      └─────────────┘    ╵         └─────────────┘
                                           ╵              ┆ opens as a
                                           ╵              ┆ local file
                                           ╵           disk.img

For "nbd+ssh://remote/" URI:

                    local  ╵  remote
                    ─────  ╵  ──────
   ┌─────────────┐         ╵    ┌─────────────┐      ┌─────────────┐
   │ NBD         │  nbd in ssh  │ SSH         │ nbd  │ nbdkit      │
   │ client      ╞═════════════▶│ server      ├─────▶│ file plugin │
   └─────────────┘         ╵    └─────────────┘      └─────────────┘
                           ╵                              ┆ opens as a
                           ╵                              ┆ local file
                           ╵                           disk.img

🐛 DEBUG FLAGS 🐛

`-D ssh.log=[1..4]`

Set the libssh log level to increasing levels of verbosity. Each level includes messages from the previous levels. Currently the levels are:

1 — informational and warning messages
2 — SSH and SFTP protocol steps
3 — SSH and SFTP packets
4 — libssh functions

Use level 2 to diagnose SSH protocol or server problems. Levels 3 and 4 are extremely verbose and probably only useful if you are debugging libssh itself. 😭

If diagnosing SSH problems it is also useful to look at server-side logs, eg. /var/log/secure or "journalctl -u sshd". 🔥

🍓 FILES 🍓

~/.ssh/config
/etc/ssh/ssh_config

These are the default SSH config files which are read to get other options. You can change this using the "config" option.

~/.ssh/id_dsa
~/.ssh/id_ecdsa
~/.ssh/id_ed25519
~/.ssh/id_rsa

These are some of the default private key (identify) files used by libssh. You can prepend more to the list using the "identity" option.

~/.ssh/known_hosts
/etc/ssh/ssh_known_hosts

These are the default SSH files recording the identity of previously seen hosts. You can change this using the "known-hosts" option.

$plugindir/nbdkit-ssh-plugin.so

The plugin.

Use "nbdkit --dump-config" to find the location of $plugindir.

⭐ VERSION ⭐

"nbdkit-ssh-plugin" first appeared in nbdkit 1.12. 🎉

💖 AUTHORS 💖

Richard W.M. Jones

Parts derived from Pino Toscano's qemu libssh driver.

📜 COPYRIGHT 📜

📜 LICENSE 📜

okay bestie, final section, and it's the legal one 😭 don't scroll past it, it's literally the rules of the road for using this software. here's the whole thing, verbatim, no edits, because you do not paraphrase a license 💅

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of Red Hat nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

and now the part in ALL CAPS, which in legal-speak means pay attention bestie this is the important one 👀

THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
THE POSSIBILITY OF SUCH DAMAGE.

not me translating the caps lock: it's as-is, no promises, no warranties, and if it breaks something that's on you, not on Red Hat or the contributors. that's the whole vibe of that paragraph 🫶

and that's the page, bestie!! 🎀 you made it all the way to the bottom, which honestly is giving dedicated reader energy ✨ this was nbdkit-ssh-plugin(1) from nbdkit-1.48.1, dated 2026-08-29 — go forth and ssh responsibly, mwah 💖🦋🌸

📦 where this page comes from

fedora 44: nbdkit-ssh-plugin 1.48.1-1.fc44 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms

nbdkit-ssh-plugin(1)