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] [identity=FILENAME]
11 [known-hosts=FILENAME] [password=PASSWORD|-|+FILENAME]
12 [port=PORT] [timeout=SECS] [user=USER]
13 [verify-remote-host=false]
14
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
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 The remote file can be read or written. To force read-only access
27 add the -r flag.
28 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
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 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 config=
44 Do not read any local SSH configuration.
45 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 host=HOST
51 Specify the name or IP address of the remote host.
52 This parameter is required.
54 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 You can give this parameter multiple times.
64 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 The default is to check ~/.ssh/known_hosts followed by
71 /etc/ssh/ssh_known_hosts.
72 password=PASSWORD
74 Set the password to use when connecting to the remote server.
75 Note that passing this on the command line is not secure on shared
77 machines.
78 password=-
80 Ask for the password (interactively) when nbdkit starts up.
81 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 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 [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 This parameter is required.
97 "path=" is a magic config key and may be omitted in most cases.
99 See "Magic parameters" in nbdkit(1).
100 port=PORT
102 Specify the SSH protocol port name or number.
103 This parameter is optional. If not given then the default ssh port
105 is used.
106 timeout=SECS
108 Set the SSH connection timeout in seconds.
109 user=USER
111 Specify the remote username.
112 This parameter is optional. If not given then the local username
114 is used.
115 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 Setting this to "false" is dangerous because it allows a Man-In-
124 The-Middle (MITM) attack to be conducted against you.
125
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 If you have never connected to the SSH server before then the
132 connection will usually fail. You can:
133 • connect to the server first using ssh(1) so you can manually accept
135 the host key, or
136 • provide the host key in an alternate file which you specify using
138 the "known-hosts" option, or
139 • 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 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 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 Path expansion
155 In the "config", "identity" and "known-hosts" options, libssh expands
156 some "%"-sequences.
157 %d The user’s SSH directory, usually ~/.ssh
159 %u The local username.
161 %l The local hostname.
163 %h The remote hostname.
165 %r The remote username.
167 %p The SSH port number.
169 "%%"
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
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 1 informational and warning messages
181 2 SSH and SFTP protocol steps
183 3 SSH and SFTP packets
185 4 libssh functions
187 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 If diagnosing SSH problems it is also useful to look at server-side
193 logs, eg. /var/log/secure or "journalctl -u sshd"
194
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 ~/.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 ~/.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 $plugindir/nbdkit-ssh-plugin.so
216 The plugin.
217 Use "nbdkit --dump-config" to find the location of $plugindir.
219
221 "nbdkit-ssh-plugin" first appeared in nbdkit 1.12.
222
224 nbdkit(1), nbdkit-curl-plugin(1), nbdkit-extentlist-filter(1),
225 nbdkit-readahead-filter(1), nbdkit-retry-filter(1), nbdkit-plugin(3),
226 ssh(1), ssh-agent(1), https://libssh.org.
227
229 Richard W.M. Jones
230 Parts derived from Pino Toscano’s qemu libssh driver.
232
234 Copyright (C) 2014-2020 Red Hat Inc.
235
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 • Redistributions of source code must retain the above copyright
242 notice, this list of conditions and the following disclaimer.
243 • 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 • 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 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.
264nbdkit-1.28.2 2021-11-09 nbdkit-ssh-plugin(1)