Ubuntu Manpage: nbdkit-ssh-plugin - access disk images over the SSH protocol

Provided by: nbdkit_1.36.3-1ubuntu10_amd64

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

       This is an nbdkit(1) plugin which lets you access remote disk images over Secure Shell (SSH).  Any server
       which hosts disk images and runs an SSH server can be turned into an NBD source using this plugin.

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
           is opened relative to the user’s home directory on the remote server.

           The remote file can be read or written.  To force read-only access add the -r flag.

       nbdkit ssh host=ssh.example.com disk.img user=bob
           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=" is a magic config key and 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.

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

       Copyright Red Hat

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.

       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.

nbdkit-1.36.3                                      2024-03-31                               nbdkit-ssh-plugin(1)