1nbdkit-ssh-plugin(1) NBDKIT nbdkit-ssh-plugin(1)
2
6 nbdkit-ssh-plugin - access disk images over the SSH protocol
7
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
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
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 The remote file can be read or written. To force read-only access
29 add the -r flag.
30 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
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 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 config=
46 Do not read any local SSH configuration.
47 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 create=true
53 (nbdkit ≥ 1.32)
54 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 If using this option, you must use "create-size". "create-mode"
61 can be used to control the permissions of the new file.
62 create-mode=MODE
64 (nbdkit ≥ 1.32)
65 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 create-size=SIZE
72 (nbdkit ≥ 1.32)
73 If using "create=true", specify the virtual size of the new disk.
75 "SIZE" can use modifiers like "100M" etc.
76 host=HOST
78 Specify the name or IP address of the remote host.
79 This parameter is required.
81 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 You can give this parameter multiple times.
91 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 The default is to check ~/.ssh/known_hosts followed by
98 /etc/ssh/ssh_known_hosts.
99 password=PASSWORD
101 Set the password to use when connecting to the remote server.
102 Note that passing this on the command line is not secure on shared
104 machines.
105 password=-
107 Ask for the password (interactively) when nbdkit starts up.
108 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 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 [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 This parameter is required.
124 "path=" is a magic config key and may be omitted in most cases.
126 See "Magic parameters" in nbdkit(1).
127 port=PORT
129 Specify the SSH protocol port name or number.
130 This parameter is optional. If not given then the default ssh port
132 is used.
133 timeout=SECS
135 Set the SSH connection timeout in seconds.
136 user=USER
138 Specify the remote username.
139 This parameter is optional. If not given then the local username
141 is used.
142 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 Setting this to "false" is dangerous because it allows a Man-In-
151 The-Middle (MITM) attack to be conducted against you.
152
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 If you have never connected to the SSH server before then the
159 connection will usually fail. You can:
160 • connect to the server first using ssh(1) so you can manually accept
162 the host key, or
163 • provide the host key in an alternate file which you specify using
165 the "known-hosts" option, or
166 • 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 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 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 Path expansion
182 In the "config", "identity" and "known-hosts" options, libssh expands
183 some "%"-sequences.
184 %d The user’s SSH directory, usually ~/.ssh
186 %u The local username.
188 %l The local hostname.
190 %h The remote hostname.
192 %r The remote username.
194 %p The SSH port number.
196 "%%"
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
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 1 informational and warning messages
208 2 SSH and SFTP protocol steps
210 3 SSH and SFTP packets
212 4 libssh functions
214 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 If diagnosing SSH problems it is also useful to look at server-side
220 logs, eg. /var/log/secure or "journalctl -u sshd"
221
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 ~/.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 ~/.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 $plugindir/nbdkit-ssh-plugin.so
243 The plugin.
244 Use "nbdkit --dump-config" to find the location of $plugindir.
246
248 "nbdkit-ssh-plugin" first appeared in nbdkit 1.12.
249
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
256 Richard W.M. Jones
257 Parts derived from Pino Toscano’s qemu libssh driver.
259
261 Copyright (C) 2014-2020 Red Hat Inc.
262
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 • Redistributions of source code must retain the above copyright
269 notice, this list of conditions and the following disclaimer.
270 • 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 • 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 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.
291nbdkit-1.32.5 2023-01-03 nbdkit-ssh-plugin(1)