plugins/ssh/nbdkit-ssh-plugin.pod

   1 =head1 NAME
   2
   3 nbdkit-ssh-plugin - access disk images over the SSH protocol
   4
   5 =head1 SYNOPSIS
   6
   7  nbdkit ssh host=HOST [path=]PATH
   8             [config=CONFIG_FILE] [identity=FILENAME]
   9             [known-hosts=FILENAME] [password=PASSWORD|-|+FILENAME]
  10             [port=PORT] [timeout=SECS] [user=USER]
  11             [verify-remote-host=false]
  12
  13 =head1 DESCRIPTION
  14
  15 This is an L<nbdkit(1)> plugin which lets you access remote disk
  16 images over Secure Shell (SSH).  Any server which hosts disk images
  17 and runs an SSH server can be turned into an NBD source using this
  18 plugin.
  19
  20 =head1 EXAMPLES
  21
  22 =over 4
  23
  24 =item nbdkit ssh host=ssh.example.com disk.img
  25
  26 Open a file called F<disk.img> on remote host C<ssh.example.com>.
  27 Because the pathname is relative, it is opened relative to the user’s
  28 home directory on the remote server.
  29
  30 The remote file can be read or written.  To force read-only access add
  31 the I<-r> flag.
  32
  33 =item nbdkit ssh host=ssh.example.com disk.img user=bob
  34
  35 As above but log in using username C<bob> (instead of trying the local
  36 username).
  37
  38 =back
  39
  40 =head1 PARAMETERS
  41
  42 =over 4
  43
  44 =item B<config=>CONFIG_FILE
  45
  46 Read local SSH configuration from an alternate configuration file.
  47 Libssh expands some C<%>-sequences in C<CONFIG_FILE>, see
  48 L</Path expansion> below.  C<CONFIG_FILE> must expand to an absolute
  49 path.
  50
  51 =item B<config=>
  52
  53 Do not read any local SSH configuration.
  54
  55 The C<config> parameter is optional.  If it is I<not> specified at all
  56 then F<~/.ssh/config> and F</etc/ssh/ssh_config> are both read.
  57 Missing or unreadable files are ignored.
  58
  59 =item B<host=>HOST
  60
  61 Specify the name or IP address of the remote host.
  62
  63 This parameter is required.
  64
  65 =item B<identity=>FILENAME
  66
  67 Prepend the private key (identity) C<FILENAME> to the list of identity
  68 files used.  Libssh examines several identity files by default such as
  69 F<~/.ssh/id_ed25519>, F<~/.ssh/id_ecdsa>, F<~/.ssh/id_rsa> and
  70 F<~/.ssh/id_dsa>.  Libssh expands some C<%>-sequences in C<FILENAME>,
  71 see L</Path expansion> below.  C<FILENAME> must expand to an absolute
  72 path.
  73
  74 You can give this parameter multiple times.
  75
  76 =item B<known-hosts=>FILENAME
  77
  78 Set name of the file which records the identity of previously seen
  79 hosts.  Libssh expands some C<%>-sequences in C<FILENAME>, see
  80 L</Path expansion> below.  C<FILENAME> must expand to an absolute
  81 path.
  82
  83 The default is to check F<~/.ssh/known_hosts> followed by
  84 F</etc/ssh/ssh_known_hosts>.
  85
  86 =item B<password=>PASSWORD
  87
  88 Set the password to use when connecting to the remote server.
  89
  90 Note that passing this on the command line is not secure on shared
  91 machines.
  92
  93 =item B<password=->
  94
  95 Ask for the password (interactively) when nbdkit starts up.
  96
  97 =item B<password=+>FILENAME
  98
  99 Read the password from the named file.  This is the most secure method
 100 to supply a password, as long as you set the permissions on the file
 101 appropriately.
 102
 103 =item [B<path=>]PATH
 104
 105 Specify the path to the remote file.  This can be a relative path in
 106 which case it is relative to the remote home directory.
 107
 108 This parameter is required.
 109
 110 C<path=> is a magic config key and may be omitted in most cases.
 111 See L<nbdkit(1)/Magic parameters>.
 112
 113 =item B<port=>PORT
 114
 115 Specify the SSH protocol port name or number.
 116
 117 This parameter is optional.  If not given then the default ssh port is
 118 used.
 119
 120 =item B<timeout=>SECS
 121
 122 Set the SSH connection timeout in seconds.
 123
 124 =item B<user=>USER
 125
 126 Specify the remote username.
 127
 128 This parameter is optional.  If not given then the local username is
 129 used.
 130
 131 =item B<verify-remote-host=true>
 132
 133 =item B<verify-remote-host=false>
 134
 135 Set whether or not we verify the remote host is one we have previously
 136 seen, using a local file such as F<~/.ssh/known_hosts>.  The default
 137 is C<true>, meaning that we verify the remote host’s identity has not
 138 changed.
 139
 140 Setting this to C<false> is dangerous because it allows a
 141 Man-In-The-Middle (MITM) attack to be conducted against you.
 142
 143 =back
 144
 145 =head1 NOTES
 146
 147 =head2 Known hosts
 148
 149 The SSH server’s host key is checked at connection time, and must be
 150 present and correct in the local "known hosts" file.
 151
 152 If you have never connected to the SSH server before then the
 153 connection will usually fail.  You can:
 154
 155 =over 4
 156
 157 =item *
 158
 159 connect to the server first using L<ssh(1)> so you can manually accept
 160 the host key, or
 161
 162 =item *
 163
 164 provide the host key in an alternate file which you specify using the
 165 C<known-hosts> option, or
 166
 167 =item *
 168
 169 set I<verify-remote-host=false> on the command line.  This latter
 170 option is dangerous because it allows a MITM attack to be conducted
 171 against you.
 172
 173 =back
 174
 175 =head2 Supported authentication methods
 176
 177 This plugin supports only the following authentication methods:
 178 C<none>, C<publickey> or C<password>.  In particular note that
 179 C<keyboard-interactive> is I<not> supported.
 180
 181 =head2 SSH agent
 182
 183 There is no means for nbdkit to ask for the public key passphrase when
 184 it is running as a server.  Therefore C<publickey> authentication must
 185 be done in conjunction with L<ssh-agent(1)>.
 186
 187 =head2 Path expansion
 188
 189 In the C<config>, C<identity> and C<known-hosts> options, libssh
 190 expands some C<%>-sequences.  Unfortunately there is no escape
 191 character for C<%> itself, so there is no way to specify that
 192 character in the path.
 193
 194 =over 4
 195
 196 =item C<%d>
 197
 198 The user’s SSH directory, usually F<~/.ssh>
 199
 200 =item C<%u>
 201
 202 The local username.
 203
 204 =item C<%l>
 205
 206 The local hostname.
 207
 208 =item C<%h>
 209
 210 The remote hostname.
 211
 212 =item C<%r>
 213
 214 The remote username.
 215
 216 =item C<%p>
 217
 218 The SSH port number.
 219
 220 =back
 221
 222 =head1 FILES
 223
 224 =over 4
 225
 226 =item F<~/.ssh/config>
 227
 228 =item F</etc/ssh/ssh_config>
 229
 230 These are the default SSH config files which are read to get other
 231 options.  You can change this using the C<config> option.
 232
 233 =item F<~/.ssh/id_dsa>
 234
 235 =item F<~/.ssh/id_ecdsa>
 236
 237 =item F<~/.ssh/id_ed25519>
 238
 239 =item F<~/.ssh/id_rsa>
 240
 241 These are some of the default private key (identify) files used by
 242 libssh.  You can prepend more to the list using the C<identity>
 243 option.
 244
 245 =item F<~/.ssh/known_hosts>
 246
 247 =item F</etc/ssh/ssh_known_hosts>
 248
 249 These are the default SSH files recording the identity of previously
 250 seen hosts.  You can change this using the C<known-hosts> option.
 251
 252 =back
 253
 254 =head1 DEBUG FLAGS
 255
 256 =head2 -D ssh.log=[1..4]
 257
 258 Set the libssh log level to increasing levels of verbosity.  Each
 259 level includes messages from the previous levels.  Currently
 260 the levels are:
 261
 262 =over 4
 263
 264 =item B<1>
 265
 266 informational and warning messages
 267
 268 =item B<2>
 269
 270 SSH and SFTP protocol steps
 271
 272 =item B<3>
 273
 274 SSH and SFTP packets
 275
 276 =item B<4>
 277
 278 libssh functions
 279
 280 =back
 281
 282 Use level 2 to diagnose SSH protocol or server problems.  Levels 3 and
 283 4 are extremely verbose and probably only useful if you are debugging
 284 libssh itself.
 285
 286 =head1 SEE ALSO
 287
 288 L<nbdkit(1)>,
 289 L<nbdkit-curl-plugin(1)>,
 290 L<nbdkit-readahead-filter(1)>,
 291 L<nbdkit-retry-filter(1)>,
 292 L<nbdkit-plugin(3)>,
 293 L<ssh(1)>,
 294 L<ssh-agent(1)>,
 295 L<https://libssh.org>.
 296
 297 =head1 AUTHORS
 298
 299 Richard W.M. Jones
 300
 301 Parts derived from Pino Toscano’s qemu libssh driver.
 302
 303 =head1 COPYRIGHT
 304
 305 Copyright (C) 2014-2019 Red Hat Inc.