1nbdkit-ssh-plugin(1)                NBDKIT                nbdkit-ssh-plugin(1)
2
3
4

NAME

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

SYNOPSIS

9        nbdkit ssh host=HOST [path=]PATH
10                   [compression=true] [config=CONFIG_FILE] [identity=FILENAME]
11                   [known-hosts=FILENAME] [password=PASSWORD|-|+FILENAME]
12                   [port=PORT] [timeout=SECS] [user=USER]
13                   [verify-remote-host=false]
14

DESCRIPTION

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

EXAMPLES

21       nbdkit ssh host=ssh.example.com disk.img
22           Open a file called disk.img on remote host "ssh.example.com".
23           Because the pathname is relative, it is opened relative to the
24           user’s home directory on the remote server.
25
26           The remote file can be read or written.  To force read-only access
27           add the -r flag.
28
29       nbdkit ssh host=ssh.example.com disk.img user=bob
30           As above but log in using username "bob" (instead of trying the
31           local username).
32

PARAMETERS

34       compression=true
35           Enable compression.  You should only use this on slow or bandwidth-
36           limited connections.  On fast connections it will slow things down.
37
38       config=CONFIG_FILE
39           Read local SSH configuration from an alternate configuration file.
40           Libssh expands some "%"-sequences in "CONFIG_FILE", see "Path
41           expansion" below.  "CONFIG_FILE" must expand to an absolute path.
42
43       config=
44           Do not read any local SSH configuration.
45
46           The "config" parameter is optional.  If it is not specified at all
47           then ~/.ssh/config and /etc/ssh/ssh_config are both read.  Missing
48           or unreadable files are ignored.
49
50       host=HOST
51           Specify the name or IP address of the remote host.
52
53           This parameter is required.
54
55       identity=FILENAME
56           Prepend the private key (identity) "FILENAME" to the list of
57           identity files used.  Libssh examines several identity files by
58           default such as ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa, ~/.ssh/id_rsa
59           and ~/.ssh/id_dsa.  Libssh expands some "%"-sequences in
60           "FILENAME", see "Path expansion" below.  "FILENAME" must expand to
61           an absolute path.
62
63           You can give this parameter multiple times.
64
65       known-hosts=FILENAME
66           Set name of the file which records the identity of previously seen
67           hosts.  Libssh expands some "%"-sequences in "FILENAME", see "Path
68           expansion" below.  "FILENAME" must expand to an absolute path.
69
70           The default is to check ~/.ssh/known_hosts followed by
71           /etc/ssh/ssh_known_hosts.
72
73       password=PASSWORD
74           Set the password to use when connecting to the remote server.
75
76           Note that passing this on the command line is not secure on shared
77           machines.
78
79       password=-
80           Ask for the password (interactively) when nbdkit starts up.
81
82       password=+FILENAME
83           Read the password from the named file.  This is a secure method to
84           supply a password, as long as you set the permissions on the file
85           appropriately.
86
87       password=-FD
88           Read the password from file descriptor number "FD", inherited from
89           the parent process when nbdkit starts up.  This is also a secure
90           method to supply a password.
91
92       [path=]PATH
93           Specify the path to the remote file.  This can be a relative path
94           in which case it is relative to the remote home directory.
95
96           This parameter is required.
97
98           "path=" is a magic config key and may be omitted in most cases.
99           See "Magic parameters" in nbdkit(1).
100
101       port=PORT
102           Specify the SSH protocol port name or number.
103
104           This parameter is optional.  If not given then the default ssh port
105           is used.
106
107       timeout=SECS
108           Set the SSH connection timeout in seconds.
109
110       user=USER
111           Specify the remote username.
112
113           This parameter is optional.  If not given then the local username
114           is used.
115
116       verify-remote-host=true
117       verify-remote-host=false
118           Set whether or not we verify the remote host is one we have
119           previously seen, using a local file such as ~/.ssh/known_hosts.
120           The default is "true", meaning that we verify the remote host’s
121           identity has not changed.
122
123           Setting this to "false" is dangerous because it allows a Man-In-
124           The-Middle (MITM) attack to be conducted against you.
125

NOTES

127   Known hosts
128       The SSH server’s host key is checked at connection time, and must be
129       present and correct in the local "known hosts" file.
130
131       If you have never connected to the SSH server before then the
132       connection will usually fail.  You can:
133
134       ·   connect to the server first using ssh(1) so you can manually accept
135           the host key, or
136
137       ·   provide the host key in an alternate file which you specify using
138           the "known-hosts" option, or
139
140       ·   set verify-remote-host=false on the command line.  This latter
141           option is dangerous because it allows a MITM attack to be conducted
142           against you.
143
144   Supported authentication methods
145       This plugin supports only the following authentication methods: "none",
146       "publickey" or "password".  In particular note that
147       "keyboard-interactive" is not supported.
148
149   SSH agent
150       There is no means for nbdkit to ask for the public key passphrase when
151       it is running as a server.  Therefore "publickey" authentication must
152       be done in conjunction with ssh-agent(1).
153
154   Path expansion
155       In the "config", "identity" and "known-hosts" options, libssh expands
156       some "%"-sequences.
157
158       %d  The user’s SSH directory, usually ~/.ssh
159
160       %u  The local username.
161
162       %l  The local hostname.
163
164       %h  The remote hostname.
165
166       %r  The remote username.
167
168       %p  The SSH port number.
169
170       "%%"
171           In libssh > 0.9.0 this expands to a single "%" character.  In
172           earlier versions of libssh there was no way to escape a "%"
173           character.
174

DEBUG FLAGS

176   -D ssh.log=[1..4]
177       Set the libssh log level to increasing levels of verbosity.  Each level
178       includes messages from the previous levels.  Currently the levels are:
179
180       1   informational and warning messages
181
182       2   SSH and SFTP protocol steps
183
184       3   SSH and SFTP packets
185
186       4   libssh functions
187
188       Use level 2 to diagnose SSH protocol or server problems.  Levels 3 and
189       4 are extremely verbose and probably only useful if you are debugging
190       libssh itself.
191
192       If diagnosing SSH problems it is also useful to look at server-side
193       logs, eg. /var/log/secure or "journalctl -u sshd"
194

FILES

196       ~/.ssh/config
197       /etc/ssh/ssh_config
198           These are the default SSH config files which are read to get other
199           options.  You can change this using the "config" option.
200
201       ~/.ssh/id_dsa
202       ~/.ssh/id_ecdsa
203       ~/.ssh/id_ed25519
204       ~/.ssh/id_rsa
205           These are some of the default private key (identify) files used by
206           libssh.  You can prepend more to the list using the "identity"
207           option.
208
209       ~/.ssh/known_hosts
210       /etc/ssh/ssh_known_hosts
211           These are the default SSH files recording the identity of
212           previously seen hosts.  You can change this using the "known-hosts"
213           option.
214
215       $plugindir/nbdkit-ssh-plugin.so
216           The plugin.
217
218           Use "nbdkit --dump-config" to find the location of $plugindir.
219

VERSION

221       "nbdkit-ssh-plugin" first appeared in nbdkit 1.12.
222

SEE ALSO

224       nbdkit(1), nbdkit-curl-plugin(1), nbdkit-readahead-filter(1),
225       nbdkit-retry-filter(1), nbdkit-plugin(3), ssh(1), ssh-agent(1),
226       https://libssh.org.
227

AUTHORS

229       Richard W.M. Jones
230
231       Parts derived from Pino Toscano’s qemu libssh driver.
232
234       Copyright (C) 2014-2019 Red Hat Inc.
235

LICENSE

237       Redistribution and use in source and binary forms, with or without
238       modification, are permitted provided that the following conditions are
239       met:
240
241       ·   Redistributions of source code must retain the above copyright
242           notice, this list of conditions and the following disclaimer.
243
244       ·   Redistributions in binary form must reproduce the above copyright
245           notice, this list of conditions and the following disclaimer in the
246           documentation and/or other materials provided with the
247           distribution.
248
249       ·   Neither the name of Red Hat nor the names of its contributors may
250           be used to endorse or promote products derived from this software
251           without specific prior written permission.
252
253       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
254       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
255       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
256       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
257       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
258       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
259       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
260       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
261       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
262       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
263       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
264
265
266
267nbdkit-1.16.1                     2019-12-03              nbdkit-ssh-plugin(1)
Impressum