.\" Automatically generated by Podwrapper::Man 1.32.5 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "nbdkit-ssh-plugin 1"
.TH nbdkit-ssh-plugin 1 "2023-01-04" "nbdkit-1.32.5" "NBDKIT"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
nbdkit\-ssh\-plugin \- access disk images over the SSH protocol
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 7
\& 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]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is an \fBnbdkit\fR\|(1) plugin which lets you access remote disk
images over Secure Shell (\s-1SSH\s0).  Any server which hosts disk images
and runs an \s-1SSH\s0 server can be turned into an \s-1NBD\s0 source using this
plugin.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.IP "nbdkit ssh host=ssh.example.com disk.img" 4
.IX Item "nbdkit ssh host=ssh.example.com disk.img"
Open a file called \fIdisk.img\fR on remote host \f(CW\*(C`ssh.example.com\*(C'\fR.
Because the pathname is relative, it is opened relative to the user’s
home directory on the remote server.
.Sp
The remote file can be read or written.  To force read-only access add
the \fI\-r\fR flag.
.IP "nbdkit ssh host=ssh.example.com disk.img user=bob" 4
.IX Item "nbdkit ssh host=ssh.example.com disk.img user=bob"
As above but log in using username \f(CW\*(C`bob\*(C'\fR (instead of trying the local
username).
.SH "PARAMETERS"
.IX Header "PARAMETERS"
.IP "\fBcompression=true\fR" 4
.IX Item "compression=true"
Enable compression.  You should only use this on slow or
bandwidth-limited connections.  On fast connections it will slow
things down.
.IP "\fBconfig=\fR\s-1CONFIG_FILE\s0" 4
.IX Item "config=CONFIG_FILE"
Read local \s-1SSH\s0 configuration from an alternate configuration file.
Libssh expands some \f(CW\*(C`%\*(C'\fR\-sequences in \f(CW\*(C`CONFIG_FILE\*(C'\fR, see
\&\*(L"Path expansion\*(R" below.  \f(CW\*(C`CONFIG_FILE\*(C'\fR must expand to an absolute
path.
.IP "\fBconfig=\fR" 4
.IX Item "config="
Do not read any local \s-1SSH\s0 configuration.
.Sp
The \f(CW\*(C`config\*(C'\fR parameter is optional.  If it is \fInot\fR specified at all
then \fI~/.ssh/config\fR and \fI/etc/ssh/ssh_config\fR are both read.
Missing or unreadable files are ignored.
.IP "\fBcreate=true\fR" 4
.IX Item "create=true"
(nbdkit ≥ 1.32)
.Sp
If set, the remote file will be created.  The remote file is created
on the first \s-1NBD\s0 connection to nbdkit, not when nbdkit starts up.  If
the file already exists, it will be replaced and any existing content
lost.
.Sp
If using this option, you must use \f(CW\*(C`create\-size\*(C'\fR.  \f(CW\*(C`create\-mode\*(C'\fR can
be used to control the permissions of the new file.
.IP "\fBcreate\-mode=\fR\s-1MODE\s0" 4
.IX Item "create-mode=MODE"
(nbdkit ≥ 1.32)
.Sp
If using \f(CW\*(C`create=true\*(C'\fR specify the default permissions of the new
remote file.  You can use octal modes like \f(CW\*(C`create\-mode=0777\*(C'\fR or
\&\f(CW\*(C`create\-mode=0644\*(C'\fR.  The default is \f(CW0600\fR, ie. only readable and
writable by the remote user.
.IP "\fBcreate\-size=\fR\s-1SIZE\s0" 4
.IX Item "create-size=SIZE"
(nbdkit ≥ 1.32)
.Sp
If using \f(CW\*(C`create=true\*(C'\fR, specify the virtual size of the new disk.
\&\f(CW\*(C`SIZE\*(C'\fR can use modifiers like \f(CW\*(C`100M\*(C'\fR etc.
.IP "\fBhost=\fR\s-1HOST\s0" 4
.IX Item "host=HOST"
Specify the name or \s-1IP\s0 address of the remote host.
.Sp
This parameter is required.
.IP "\fBidentity=\fR\s-1FILENAME\s0" 4
.IX Item "identity=FILENAME"
Prepend the private key (identity) \f(CW\*(C`FILENAME\*(C'\fR to the list of identity
files used.  Libssh examines several identity files by default such as
\&\fI~/.ssh/id_ed25519\fR, \fI~/.ssh/id_ecdsa\fR, \fI~/.ssh/id_rsa\fR and
\&\fI~/.ssh/id_dsa\fR.  Libssh expands some \f(CW\*(C`%\*(C'\fR\-sequences in \f(CW\*(C`FILENAME\*(C'\fR,
see \*(L"Path expansion\*(R" below.  \f(CW\*(C`FILENAME\*(C'\fR must expand to an absolute
path.
.Sp
You can give this parameter multiple times.
.IP "\fBknown\-hosts=\fR\s-1FILENAME\s0" 4
.IX Item "known-hosts=FILENAME"
Set name of the file which records the identity of previously seen
hosts.  Libssh expands some \f(CW\*(C`%\*(C'\fR\-sequences in \f(CW\*(C`FILENAME\*(C'\fR, see
\&\*(L"Path expansion\*(R" below.  \f(CW\*(C`FILENAME\*(C'\fR must expand to an absolute
path.
.Sp
The default is to check \fI~/.ssh/known_hosts\fR followed by
\&\fI/etc/ssh/ssh_known_hosts\fR.
.IP "\fBpassword=\fR\s-1PASSWORD\s0" 4
.IX Item "password=PASSWORD"
Set the password to use when connecting to the remote server.
.Sp
Note that passing this on the command line is not secure on shared
machines.
.IP "\fBpassword=\-\fR" 4
.IX Item "password=-"
Ask for the password (interactively) when nbdkit starts up.
.IP "\fBpassword=+\fR\s-1FILENAME\s0" 4
.IX Item "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.
.IP "\fBpassword=\-\fR\s-1FD\s0" 4
.IX Item "password=-FD"
Read the password from file descriptor number \f(CW\*(C`FD\*(C'\fR, inherited from
the parent process when nbdkit starts up.  This is also a secure
method to supply a password.
.IP "[\fBpath=\fR]PATH" 4
.IX Item "[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.
.Sp
This parameter is required.
.Sp
\&\f(CW\*(C`path=\*(C'\fR is a magic config key and may be omitted in most cases.
See \*(L"Magic parameters\*(R" in \fBnbdkit\fR\|(1).
.IP "\fBport=\fR\s-1PORT\s0" 4
.IX Item "port=PORT"
Specify the \s-1SSH\s0 protocol port name or number.
.Sp
This parameter is optional.  If not given then the default ssh port is
used.
.IP "\fBtimeout=\fR\s-1SECS\s0" 4
.IX Item "timeout=SECS"
Set the \s-1SSH\s0 connection timeout in seconds.
.IP "\fBuser=\fR\s-1USER\s0" 4
.IX Item "user=USER"
Specify the remote username.
.Sp
This parameter is optional.  If not given then the local username is
used.
.IP "\fBverify\-remote\-host=true\fR" 4
.IX Item "verify-remote-host=true"
.PD 0
.IP "\fBverify\-remote\-host=false\fR" 4
.IX Item "verify-remote-host=false"
.PD
Set whether or not we verify the remote host is one we have previously
seen, using a local file such as \fI~/.ssh/known_hosts\fR.  The default
is \f(CW\*(C`true\*(C'\fR, meaning that we verify the remote host’s identity has not
changed.
.Sp
Setting this to \f(CW\*(C`false\*(C'\fR is dangerous because it allows a
Man-In-The-Middle (\s-1MITM\s0) attack to be conducted against you.
.SH "NOTES"
.IX Header "NOTES"
.SS "Known hosts"
.IX Subsection "Known hosts"
The \s-1SSH\s0 server’s host key is checked at connection time, and must be
present and correct in the local \*(L"known hosts\*(R" file.
.PP
If you have never connected to the \s-1SSH\s0 server before then the
connection will usually fail.  You can:
.IP "\(bu" 4
connect to the server first using \fBssh\fR\|(1) so you can manually accept
the host key, or
.IP "\(bu" 4
provide the host key in an alternate file which you specify using the
\&\f(CW\*(C`known\-hosts\*(C'\fR option, or
.IP "\(bu" 4
set \fIverify\-remote\-host=false\fR on the command line.  This latter
option is dangerous because it allows a \s-1MITM\s0 attack to be conducted
against you.
.SS "Supported authentication methods"
.IX Subsection "Supported authentication methods"
This plugin supports only the following authentication methods:
\&\f(CW\*(C`none\*(C'\fR, \f(CW\*(C`publickey\*(C'\fR or \f(CW\*(C`password\*(C'\fR.  In particular note that
\&\f(CW\*(C`keyboard\-interactive\*(C'\fR is \fInot\fR supported.
.SS "\s-1SSH\s0 agent"
.IX Subsection "SSH agent"
There is no means for nbdkit to ask for the public key passphrase when
it is running as a server.  Therefore \f(CW\*(C`publickey\*(C'\fR authentication must
be done in conjunction with \fBssh\-agent\fR\|(1).
.SS "Path expansion"
.IX Subsection "Path expansion"
In the \f(CW\*(C`config\*(C'\fR, \f(CW\*(C`identity\*(C'\fR and \f(CW\*(C`known\-hosts\*(C'\fR options, libssh
expands some \f(CW\*(C`%\*(C'\fR\-sequences.
.ie n .IP "%d" 4
.el .IP "\f(CW%d\fR" 4
.IX Item "%d"
The user’s \s-1SSH\s0 directory, usually \fI~/.ssh\fR
.ie n .IP "%u" 4
.el .IP "\f(CW%u\fR" 4
.IX Item "%u"
The local username.
.ie n .IP "%l" 4
.el .IP "\f(CW%l\fR" 4
.IX Item "%l"
The local hostname.
.ie n .IP "%h" 4
.el .IP "\f(CW%h\fR" 4
.IX Item "%h"
The remote hostname.
.ie n .IP "%r" 4
.el .IP "\f(CW%r\fR" 4
.IX Item "%r"
The remote username.
.ie n .IP "%p" 4
.el .IP "\f(CW%p\fR" 4
.IX Item "%p"
The \s-1SSH\s0 port number.
.ie n .IP """%%""" 4
.el .IP "\f(CW%%\fR" 4
.IX Item "%%"
In libssh > 0.9.0 this expands to a single \f(CW\*(C`%\*(C'\fR character.  In
earlier versions of libssh there was no way to escape a \f(CW\*(C`%\*(C'\fR
character.
.SH "DEBUG FLAGS"
.IX Header "DEBUG FLAGS"
.SS "\-D ssh.log=[1..4]"
.IX Subsection "-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:
.IP "\fB1\fR" 4
.IX Item "1"
informational and warning messages
.IP "\fB2\fR" 4
.IX Item "2"
\&\s-1SSH\s0 and \s-1SFTP\s0 protocol steps
.IP "\fB3\fR" 4
.IX Item "3"
\&\s-1SSH\s0 and \s-1SFTP\s0 packets
.IP "\fB4\fR" 4
.IX Item "4"
libssh functions
.PP
Use level 2 to diagnose \s-1SSH\s0 protocol or server problems.  Levels 3 and
4 are extremely verbose and probably only useful if you are debugging
libssh itself.
.PP
If diagnosing \s-1SSH\s0 problems it is also useful to look at server-side
logs, eg. \fI/var/log/secure\fR or \f(CW\*(C`journalctl \-u sshd\*(C'\fR
.SH "FILES"
.IX Header "FILES"
.IP "\fI~/.ssh/config\fR" 4
.IX Item "~/.ssh/config"
.PD 0
.IP "\fI/etc/ssh/ssh_config\fR" 4
.IX Item "/etc/ssh/ssh_config"
.PD
These are the default \s-1SSH\s0 config files which are read to get other
options.  You can change this using the \f(CW\*(C`config\*(C'\fR option.
.IP "\fI~/.ssh/id_dsa\fR" 4
.IX Item "~/.ssh/id_dsa"
.PD 0
.IP "\fI~/.ssh/id_ecdsa\fR" 4
.IX Item "~/.ssh/id_ecdsa"
.IP "\fI~/.ssh/id_ed25519\fR" 4
.IX Item "~/.ssh/id_ed25519"
.IP "\fI~/.ssh/id_rsa\fR" 4
.IX Item "~/.ssh/id_rsa"
.PD
These are some of the default private key (identify) files used by
libssh.  You can prepend more to the list using the \f(CW\*(C`identity\*(C'\fR
option.
.IP "\fI~/.ssh/known_hosts\fR" 4
.IX Item "~/.ssh/known_hosts"
.PD 0
.IP "\fI/etc/ssh/ssh_known_hosts\fR" 4
.IX Item "/etc/ssh/ssh_known_hosts"
.PD
These are the default \s-1SSH\s0 files recording the identity of previously
seen hosts.  You can change this using the \f(CW\*(C`known\-hosts\*(C'\fR option.
.IP "\fI\f(CI$plugindir\fI/nbdkit\-ssh\-plugin.so\fR" 4
.IX Item "$plugindir/nbdkit-ssh-plugin.so"
The plugin.
.Sp
Use \f(CW\*(C`nbdkit \-\-dump\-config\*(C'\fR to find the location of \f(CW$plugindir\fR.
.SH "VERSION"
.IX Header "VERSION"
\&\f(CW\*(C`nbdkit\-ssh\-plugin\*(C'\fR first appeared in nbdkit 1.12.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBnbdkit\fR\|(1),
\&\fBnbdkit\-curl\-plugin\fR\|(1),
\&\fBnbdkit\-extentlist\-filter\fR\|(1),
\&\fBnbdkit\-retry\-filter\fR\|(1),
\&\fBnbdkit\-plugin\fR\|(3),
\&\fBssh\fR\|(1),
\&\fBssh\-agent\fR\|(1),
https://libssh.org.
.SH "AUTHORS"
.IX Header "AUTHORS"
Richard W.M. Jones
.PP
Parts derived from Pino Toscano’s qemu libssh driver.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (C) 2014\-2020 Red Hat Inc.
.SH "LICENSE"
.IX Header "LICENSE"
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
.IP "\(bu" 4
Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
.IP "\(bu" 4
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.
.IP "\(bu" 4
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.
.PP
\&\s-1THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS\s0 ''\s-1AS IS\s0'' \s-1AND
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\s0 (\s-1INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES\s0; \s-1LOSS OF
USE, DATA, OR PROFITS\s0; \s-1OR BUSINESS INTERRUPTION\s0) \s-1HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT\s0 (\s-1INCLUDING NEGLIGENCE OR OTHERWISE\s0) \s-1ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.\s0