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 [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 config=CONFIG_FILE
35 Read local SSH configuration from an alternate configuration file.
36 Libssh expands some "%"-sequences in "CONFIG_FILE", see "Path
37 expansion" below. "CONFIG_FILE" must expand to an absolute path.
38 config=
40 Do not read any local SSH configuration.
41 The "config" parameter is optional. If it is not specified at all
43 then ~/.ssh/config and /etc/ssh/ssh_config are both read. Missing
44 or unreadable files are ignored.
45 host=HOST
47 Specify the name or IP address of the remote host.
48 This parameter is required.
50 identity=FILENAME
52 Prepend the private key (identity) "FILENAME" to the list of
53 identity files used. Libssh examines several identity files by
54 default such as ~/.ssh/id_ed25519, ~/.ssh/id_ecdsa, ~/.ssh/id_rsa
55 and ~/.ssh/id_dsa. Libssh expands some "%"-sequences in
56 "FILENAME", see "Path expansion" below. "FILENAME" must expand to
57 an absolute path.
58 You can give this parameter multiple times.
60 known-hosts=FILENAME
62 Set name of the file which records the identity of previously seen
63 hosts. Libssh expands some "%"-sequences in "FILENAME", see "Path
64 expansion" below. "FILENAME" must expand to an absolute path.
65 The default is to check ~/.ssh/known_hosts followed by
67 /etc/ssh/ssh_known_hosts.
68 password=PASSWORD
70 Set the password to use when connecting to the remote server.
71 Note that passing this on the command line is not secure on shared
73 machines.
74 password=-
76 Ask for the password (interactively) when nbdkit starts up.
77 password=+FILENAME
79 Read the password from the named file. This is the most secure
80 method to supply a password, as long as you set the permissions on
81 the file appropriately.
82 [path=]PATH
84 Specify the path to the remote file. This can be a relative path
85 in which case it is relative to the remote home directory.
86 This parameter is required.
88 "path=" is a magic config key and may be omitted in most cases.
90 See "Magic parameters" in nbdkit(1).
91 port=PORT
93 Specify the SSH protocol port name or number.
94 This parameter is optional. If not given then the default ssh port
96 is used.
97 timeout=SECS
99 Set the SSH connection timeout in seconds.
100 user=USER
102 Specify the remote username.
103 This parameter is optional. If not given then the local username
105 is used.
106 verify-remote-host=true
108 verify-remote-host=false
109 Set whether or not we verify the remote host is one we have
110 previously seen, using a local file such as ~/.ssh/known_hosts.
111 The default is "true", meaning that we verify the remote host’s
112 identity has not changed.
113 Setting this to "false" is dangerous because it allows a Man-In-
115 The-Middle (MITM) attack to be conducted against you.
116
118 Known hosts
119 The SSH server’s host key is checked at connection time, and must be
120 present and correct in the local "known hosts" file.
121 If you have never connected to the SSH server before then the
123 connection will usually fail. You can:
124 · connect to the server first using ssh(1) so you can manually accept
126 the host key, or
127 · provide the host key in an alternate file which you specify using
129 the "known-hosts" option, or
130 · set verify-remote-host=false on the command line. This latter
132 option is dangerous because it allows a MITM attack to be conducted
133 against you.
134 Supported authentication methods
136 This plugin supports only the following authentication methods: "none",
137 "publickey" or "password". In particular note that
138 "keyboard-interactive" is not supported.
139 SSH agent
141 There is no means for nbdkit to ask for the public key passphrase when
142 it is running as a server. Therefore "publickey" authentication must
143 be done in conjunction with ssh-agent(1).
144 Path expansion
146 In the "config", "identity" and "known-hosts" options, libssh expands
147 some "%"-sequences. Unfortunately there is no escape character for "%"
148 itself, so there is no way to specify that character in the path.
149 %d The user’s SSH directory, usually ~/.ssh
151 %u The local username.
153 %l The local hostname.
155 %h The remote hostname.
157 %r The remote username.
159 %p The SSH port number.
161
163 ~/.ssh/config
164 /etc/ssh/ssh_config
165 These are the default SSH config files which are read to get other
166 options. You can change this using the "config" option.
167 ~/.ssh/id_dsa
169 ~/.ssh/id_ecdsa
170 ~/.ssh/id_ed25519
171 ~/.ssh/id_rsa
172 These are some of the default private key (identify) files used by
173 libssh. You can prepend more to the list using the "identity"
174 option.
175 ~/.ssh/known_hosts
177 /etc/ssh/ssh_known_hosts
178 These are the default SSH files recording the identity of
179 previously seen hosts. You can change this using the "known-hosts"
180 option.
181
183 -D ssh.log=[1..4]
184 Set the libssh log level to increasing levels of verbosity. Each level
185 includes messages from the previous levels. Currently the levels are:
186 1 informational and warning messages
188 2 SSH and SFTP protocol steps
190 3 SSH and SFTP packets
192 4 libssh functions
194 Use level 2 to diagnose SSH protocol or server problems. Levels 3 and
196 4 are extremely verbose and probably only useful if you are debugging
197 libssh itself.
198
200 nbdkit(1), nbdkit-curl-plugin(1), nbdkit-readahead-filter(1),
201 nbdkit-plugin(3), ssh(1), ssh-agent(1), https://libssh.org.
202
204 Richard W.M. Jones
205 Parts derived from Pino Toscano’s qemu libssh driver.
207
209 Copyright (C) 2014-2019 Red Hat Inc.
210
212 Redistribution and use in source and binary forms, with or without
213 modification, are permitted provided that the following conditions are
214 met:
215 · Redistributions of source code must retain the above copyright
217 notice, this list of conditions and the following disclaimer.
218 · Redistributions in binary form must reproduce the above copyright
220 notice, this list of conditions and the following disclaimer in the
221 documentation and/or other materials provided with the
222 distribution.
223 · Neither the name of Red Hat nor the names of its contributors may
225 be used to endorse or promote products derived from this software
226 without specific prior written permission.
227 THIS SOFTWARE IS PROVIDED BY RED HAT AND CONTRIBUTORS ''AS IS'' AND ANY
229 EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
230 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
231 PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL RED HAT OR CONTRIBUTORS BE
232 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
233 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
234 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
235 BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
236 WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
237 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
238 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
239nbdkit-1.12.3 2019-05-21 nbdkit-ssh-plugin(1)