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]
11                   [create=true] [create-mode=MODE] [create-size=SIZE]
12                   [identity=FILENAME] [known-hosts=FILENAME]
13                   [password=PASSWORD|-|+FILENAME]
14                   [port=PORT] [timeout=SECS] [user=USER]
15                   [verify-remote-host=false]
16

DESCRIPTION

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

EXAMPLES

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

PARAMETERS

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

NOTES

154   Known hosts
155       The SSH server’s host key is checked at connection time, and must be
156       present and correct in the local "known hosts" file.
157
158       If you have never connected to the SSH server before then the
159       connection will usually fail.  You can:
160
161       •   connect to the server first using ssh(1) so you can manually accept
162           the host key, or
163
164       •   provide the host key in an alternate file which you specify using
165           the "known-hosts" option, or
166
167       •   set verify-remote-host=false on the command line.  This latter
168           option is dangerous because it allows a MITM attack to be conducted
169           against you.
170
171   Supported authentication methods
172       This plugin supports only the following authentication methods: "none",
173       "publickey" or "password".  In particular note that
174       "keyboard-interactive" is not supported.
175
176   SSH agent
177       There is no means for nbdkit to ask for the public key passphrase when
178       it is running as a server.  Therefore "publickey" authentication must
179       be done in conjunction with ssh-agent(1).
180
181   Path expansion
182       In the "config", "identity" and "known-hosts" options, libssh expands
183       some "%"-sequences.
184
185       %d  The user’s SSH directory, usually ~/.ssh
186
187       %u  The local username.
188
189       %l  The local hostname.
190
191       %h  The remote hostname.
192
193       %r  The remote username.
194
195       %p  The SSH port number.
196
197       "%%"
198           In libssh > 0.9.0 this expands to a single "%" character.  In
199           earlier versions of libssh there was no way to escape a "%"
200           character.
201

DEBUG FLAGS

203   -D ssh.log=[1..4]
204       Set the libssh log level to increasing levels of verbosity.  Each level
205       includes messages from the previous levels.  Currently the levels are:
206
207       1   informational and warning messages
208
209       2   SSH and SFTP protocol steps
210
211       3   SSH and SFTP packets
212
213       4   libssh functions
214
215       Use level 2 to diagnose SSH protocol or server problems.  Levels 3 and
216       4 are extremely verbose and probably only useful if you are debugging
217       libssh itself.
218
219       If diagnosing SSH problems it is also useful to look at server-side
220       logs, eg. /var/log/secure or "journalctl -u sshd"
221

FILES

223       ~/.ssh/config
224       /etc/ssh/ssh_config
225           These are the default SSH config files which are read to get other
226           options.  You can change this using the "config" option.
227
228       ~/.ssh/id_dsa
229       ~/.ssh/id_ecdsa
230       ~/.ssh/id_ed25519
231       ~/.ssh/id_rsa
232           These are some of the default private key (identify) files used by
233           libssh.  You can prepend more to the list using the "identity"
234           option.
235
236       ~/.ssh/known_hosts
237       /etc/ssh/ssh_known_hosts
238           These are the default SSH files recording the identity of
239           previously seen hosts.  You can change this using the "known-hosts"
240           option.
241
242       $plugindir/nbdkit-ssh-plugin.so
243           The plugin.
244
245           Use "nbdkit --dump-config" to find the location of $plugindir.
246

VERSION

248       "nbdkit-ssh-plugin" first appeared in nbdkit 1.12.
249

SEE ALSO

251       nbdkit(1), nbdkit-curl-plugin(1), nbdkit-extentlist-filter(1),
252       nbdkit-retry-filter(1), nbdkit-plugin(3), ssh(1), ssh-agent(1),
253       https://libssh.org.
254

AUTHORS

256       Richard W.M. Jones
257
258       Parts derived from Pino Toscano’s qemu libssh driver.
259
261       Copyright Red Hat
262

LICENSE

264       Redistribution and use in source and binary forms, with or without
265       modification, are permitted provided that the following conditions are
266       met:
267
268       •   Redistributions of source code must retain the above copyright
269           notice, this list of conditions and the following disclaimer.
270
271       •   Redistributions in binary form must reproduce the above copyright
272           notice, this list of conditions and the following disclaimer in the
273           documentation and/or other materials provided with the
274           distribution.
275
276       •   Neither the name of Red Hat nor the names of its contributors may
277           be used to endorse or promote products derived from this software
278           without specific prior written permission.
279
280       THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
281       EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
282       IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
283       PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
284       LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
285       CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
286       SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
287       BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
288       WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
289       OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
290       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
291
292
293
294nbdkit-1.36.2                     2023-11-26              nbdkit-ssh-plugin(1)
Impressum