=head1 NAME

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

=head1 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]

=head1 DESCRIPTION

This is an L<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.

=head1 EXAMPLES

=over 4

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

Open a file called F<disk.img> on remote host C<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 I<-r> flag.

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

As above but log in using username C<bob> (instead of trying the local
username).

=back

=head1 PARAMETERS

=over 4

=item B<compression=true>

Enable compression.  You should only use this on slow or
bandwidth-limited connections.  On fast connections it will slow
things down.

=item B<config=>CONFIG_FILE

Read local SSH configuration from an alternate configuration file.
Libssh expands some C<%>-sequences in C<CONFIG_FILE>, see
L</Path expansion> below.  C<CONFIG_FILE> must expand to an absolute
path.

=item B<config=>

Do not read any local SSH configuration.

The C<config> parameter is optional.  If it is I<not> specified at all
then F<~/.ssh/config> and F</etc/ssh/ssh_config> are both read.
Missing or unreadable files are ignored.

=item B<create=true>

(nbdkit E<ge> 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 C<create-size>.  C<create-mode> can
be used to control the permissions of the new file.

=item B<create-mode=>MODE

(nbdkit E<ge> 1.32)

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

=item B<create-size=>SIZE

(nbdkit E<ge> 1.32)

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

=item B<host=>HOST

Specify the name or IP address of the remote host.

This parameter is required.

=item B<identity=>FILENAME

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

You can give this parameter multiple times.

=item B<known-hosts=>FILENAME

Set name of the file which records the identity of previously seen
hosts.  Libssh expands some C<%>-sequences in C<FILENAME>, see
L</Path expansion> below.  C<FILENAME> must expand to an absolute
path.

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

=item B<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.

=item B<password=->

Ask for the password (interactively) when nbdkit starts up.

=item B<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.

=item B<password=->FD

Read the password from file descriptor number C<FD>, inherited from
the parent process when nbdkit starts up.  This is also a secure
method to supply a password.

=item [B<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.

C<path=> __IS_MAGIC__

=item B<port=>PORT

Specify the SSH protocol port name or number.

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

=item B<timeout=>SECS

Set the SSH connection timeout in seconds.

=item B<user=>USER

Specify the remote username.

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

=item B<verify-remote-host=true>

=item B<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 F<~/.ssh/known_hosts>.  The default
is C<true>, meaning that we verify the remote host’s identity has not
changed.

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

=back

=head1 NOTES

=head2 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:

=over 4

=item *

connect to the server first using L<ssh(1)> so you can manually accept
the host key, or

=item *

provide the host key in an alternate file which you specify using the
C<known-hosts> option, or

=item *

set I<verify-remote-host=false> on the command line.  This latter
option is dangerous because it allows a MITM attack to be conducted
against you.

=back

=head2 Supported authentication methods

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

=head2 SSH agent

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

=head2 Path expansion

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

=over 4

=item C<%d>

The user’s SSH directory, usually F<~/.ssh>

=item C<%u>

The local username.

=item C<%l>

The local hostname.

=item C<%h>

The remote hostname.

=item C<%r>

The remote username.

=item C<%p>

The SSH port number.

=item C<%%>

In libssh E<gt> 0.9.0 this expands to a single C<%> character.  In
earlier versions of libssh there was no way to escape a C<%>
character.

=back

=head1 DEBUG FLAGS

=head2 -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:

=over 4

=item B<1>

informational and warning messages

=item B<2>

SSH and SFTP protocol steps

=item B<3>

SSH and SFTP packets

=item B<4>

libssh functions

=back

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. F</var/log/secure> or C<journalctl -u sshd>

=head1 FILES

=over 4

=item F<~/.ssh/config>

=item F</etc/ssh/ssh_config>

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

=item F<~/.ssh/id_dsa>

=item F<~/.ssh/id_ecdsa>

=item F<~/.ssh/id_ed25519>

=item F<~/.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 C<identity>
option.

=item F<~/.ssh/known_hosts>

=item F</etc/ssh/ssh_known_hosts>

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

=item F<$plugindir/nbdkit-ssh-plugin.so>

The plugin.

Use C<nbdkit --dump-config> to find the location of C<$plugindir>.

=back

=head1 VERSION

C<nbdkit-ssh-plugin> first appeared in nbdkit 1.12.

=head1 SEE ALSO

L<nbdkit(1)>,
L<nbdkit-curl-plugin(1)>,
L<nbdkit-extentlist-filter(1)>,
L<nbdkit-retry-filter(1)>,
L<nbdkit-plugin(3)>,
L<ssh(1)>,
L<ssh-agent(1)>,
L<https://libssh.org>.

=head1 AUTHORS

Richard W.M. Jones

Parts derived from Pino Toscano’s qemu libssh driver.

=head1 COPYRIGHT

Copyright Red Hat