DBCLIENT(1)

📦
version 2026.94 · 5 versions
, in arch rolling, nixpkgs unstable, ubuntu stonking

💖 DBCLIENT 💖

welcome to DBCLIENT(1), bestie — straight outta the General Commands Manual, and yeah it's the manual page but make it make sense. this is PART ONE of two, so don't go anywhere 👑

✨ NAME ✨

dbclient — lightweight SSH client. that's it, that's the whole vibe. 🦋

🎀 SYNOPSIS 🎀

dbclient [flag arguments] [-p port] [-i id] [-L l:h:p] [-R l:h:p]
         [-l user] host [more flags] [command]

dbclient [args] [user1]@host1[^port1],[user2]@host2[^port2],...

🌈 DESCRIPTION 🌈

so dbclient is literally just the client half of Dropbear SSH. the client part. that's the whole description babes, no notes. 💅

👑 OPTIONS 👑

okay this is the main character section. buckle up. every single one, no skips, no cap.

  • command — a command you wanna run on the remote host. normally the remote host runs it through their shell. it starts at the first hyphen argument that comes after the host argument. if you don't give a command, you get a whole interactive terminal opened for you instead (peep -t and -T for the deets).
  • -p port — connect to port on the remote host. you can also do hostname^port instead. default is 22, classic.
  • -i idfile — identity file, iykyk. read the identity key out of the file idfile (and yes, multiple are allowed, go off). you make this file with dropbearkey(1) or convert it from OpenSSH using dropbearconvert(1). the default path is ~/.ssh/id_dropbear. 🗝️
  • -L [listenaddress]:listenport:host:port — local port forwarding. forward listenport on the local host, through the SSH connection, over to port on host. tunnel szn 🔥
  • -R [listenaddress]:listenport:host:port — remote port forwarding. forward listenport on the remote host, through the SSH connection, to port on host. mirror tunnel, same energy, different direction.
  • -l user — username. log in as user on the remote host. the alternative is to just specify user@host, which honestly slaps too.
  • -t — allocate a PTY. this is the default when you don't pass a command, and it gives you a full interactive remote session. the big flex here is that your keystrokes get sent remotely immediately, instead of local line-based editing. instant. ⚡
  • -T — don't allocate a PTY. this is the default when you do give a command. see -t for the drama.
  • -N — don't request a remote shell and don't run any commands. any command arguments you passed just get ignored entirely. 🙈
  • -f — fork into the background after authentication. a command argument (or -N) is required, so don't try it. this one's useful when you're using password authentication.
  • -g — allow non-local hosts to connect to forwarded ports. applies to -L and -R forwarded ports, though remote connections to -R forwarded ports may still be limited by the ssh server. sorry bestie, the server has opinions.
  • -y — always accept hostkeys if they're unknown. if a hostkey mismatch happens, the connection aborts as normal. and if you specify it a second time, no host key checking is performed at all — which is, and I quote the manual, "usually undesirable." so like. be so serious. 💀
  • -A — forward agent connections to the remote host. dbclient will use any OpenSSH-style agent program if one is available (SSH_AUTH_SOCK will be set) for public key authentication. forwarding is only enabled if -A is specified.
⚠️ beware, bestie: a forwarded agent connection lets the remote server have the same authentication credentials as you used locally. a compromised remote server could use that to log into other servers. not cute. in many situations Dropbear's multi-hop mode is a better and more secure alternative to agent forwarding, since it avoids having to trust the intermediate server. 🫶

if the SSH agent program is set to prompt when a key is used, the -o DisableTrivialAuth option can prevent UI confusion.

  • -W windowsize — specify the per-channel receive window buffer size. cranking this may improve network performance at the expense of memory use. use -h to see the default buffer size. 💾
  • -K timeout_seconds — make sure traffic is transmitted at a certain interval in seconds. useful for working around firewalls or routers that drop connections after a certain period of inactivity. the trade-off? a session may be closed if there's a temporary lapse of network connectivity. a setting of 0 disables keepalives. if no response is received for 3 consecutive keepalives, the connection gets closed. 👋
  • -I idle_timeout — disconnect the session if no traffic is transmitted or received for idle_timeout seconds. ghosting, but make it protocol.
  • -z — by default Dropbear sends network traffic with the AF21 setting for QoS, letting network devices give it higher priority. some devices may have problems with that, and -z can be used to disable it.
  • -J proxy_command | -J &fd — use the standard input/output of the program proxy_command rather than using a normal TCP connection. a hostname should still be provided, since it's used for comparing saved hostkeys. this command will be executed as exec proxy_command ... with the default shell.

the second form, &fd, makes dbclient use the numeric file descriptor as a socket. this is for more complex tunnelling scenarios. example usage with socat is:

socat EXEC:'dbclient -J &38 ev',fdin=38,fdout=38 TCP4:host.example.com:22
  • -B endhost:endport — "netcat-alike" mode, where Dropbear connects to the given host, then creates a forwarded connection to endhost. this then gets presented as dbclient's standard input/output. 🐈
  • -c cipherlist — specify a comma separated list of ciphers to enable. use -c help to list possibilities.
  • -m MAClist — specify a comma separated list of authentication MACs to enable. use -m help to list possibilities.
  • -o option — lets you give options in the format used by the OpenSSH config file. super handy for specifying options that have no separate command-line flag. for full details of the options listed below and their possible values, see ssh_config(5). yes/no arguments also accept y/n.

the following options have currently been implemented:

  • BatchMode — disable interactive prompts, e.g. password prompts and host key confirmation. the argument must be yes or no (the default).
  • BindAddress — specify address and port on the local machine as the source address of the connection.
  • Compression — can be set to yes or no. default is no compression (with default build options). enabling compression can be a security weakness in some circumstances, because the size of network traffic may leak information about the encrypted data. 😭 compression will only be used when the server also supports it.
  • DisableTrivialAuth — disallow a server immediately giving successful authentication (without presenting any password/pubkey prompt). this avoids a UI confusion issue where it may appear that the user is accepting a SSH agent prompt from their local machine, but they're actually accepting a prompt sent immediately by the remote server. sneaky!!
  • ExitOnForwardFailure — specifies whether dbclient should terminate the connection if it cannot set up all requested local and remote port forwardings. the argument must be yes or no (the default).
  • ForwardAgent — forward the authentication agent to the remote machine. the argument must be yes or no (the default).
  • GatewayPorts — allow the remote host to connect to local forwarded ports. the argument must be yes or no (the default).
  • IdentityFile — specify an authentication identity file path.
  • PasswordAuthentication — allow prompting a user for a password. if the DROPBEAR_PASSWORD env is specified then it still will be used. the argument must be yes (the default) or no.
  • Port — specify a listening port, like the -p argument.
  • ProxyCommand — specify the proxy command to use to connect to the server.
  • ServerAliveInterval — sets a timeout interval in seconds between keep-alive messages through the encrypted channel. the default is 0, e.g. disabled.
  • StrictHostKeyChecking — use yes to refuse connection to hosts where the host key is not already correct in known_hosts. entries must be added to known_hosts manually.

use no to skip the known_hosts key checking.

use accept-new to add new host keys to the known_hosts and refuse to connect if the host key has changed.

ask is the default. 🤔

  • UseSyslog — send dbclient log messages to syslog in addition to stderr.
  • -s — the specified command will be requested as a subsystem, used for sftp. Dropbear doesn't implement sftp itself, but the OpenSSH sftp client can be used, e.g.
sftp -S dbclient user@host
  • -b [address][:port] — bind to a specific local address when connecting to the remote host. this lets you choose from multiple outgoing interfaces. either address or port (or both) can be given. 🧚
  • -Q algo — query supported algorithms. options are kex, sig, cipher, mac, compress.
  • -V — print the version. that's it. that's the flag. ⭐

🚀 MULTI-HOP 🚀

okay this part is so fun. Dropbear also lets you specify multiple "hops", separated by commas. in that case a connection gets made to the first host, then a TCP forwarded connection is made through that one to the second host, and so on and so on. the hosts other than the final destination won't see anything other than the encrypted SSH stream. secretive. mysterious. iconic. 🔥

a port for a host can be specified with a caret, e.g. matt@martello^44. this syntax also works with scp or rsync (just specify dbclient as the ssh/rsh command). a file can be "bounced" through multiple SSH hops, e.g.

scp -S dbclient matt@martello,root@wrt,canyons:/tmp/dump .

note that hostnames are resolved by the prior hop (so canyons would be resolved by the host wrt in the example above), the same way as other -L TCP forwarded hosts are. host keys are checked locally based on the given hostname. 🌸

✨ ESCAPE CHARACTERS ✨

okay so bestie, when you're in a connection and you hit a newline and then the key sequence ~. (tilde, dot), the connection is terminated. yep, it just ends, periodt. and the sequence ~^Z (tilde, ctrl-z) will background the connection — like, it sends it to the background. this whole behavior only applies when a PTY is used, just so you know 👑

then ~R will perform a key re-exchange of ephemeral session keys. iconic little refresh moment 🔐✨

🌸 ENVIRONMENT 🌸

DROPBEAR_PASSWORD

a password to use for remote authentication can be specified in the environment variable DROPBEAR_PASSWORD. but bestie, care should be taken that the password is not exposed to other users on a multi-user system, or stored in accessible files. do not be messy with this one 🙈

SSH_ASKPASS

dbclient can use an external program to request a password from a user. SSH_ASKPASS should be set to the path of a program that will return a password on standard output. this program will only be used if either DISPLAY is set and standard input is not a TTY, or the environment variable SSH_ASKPASS_ALWAYS is set. very specific vibes, iykyk 💅

🎀 FILES 🎀

~/.ssh/dropbear_config

this is the per user configuration file. a very limited subset of the keywords for ssh_config(5) is supported, and none of the advanced features. the file contains key value pairs on a single line separated with space or =. empty lines are ignored. text starting with # is a comment, and also ignored. we love a low-maintenance config 🫶

the file is not considered if multi-hop connection is used. values on the command line override the respective values in the file. no cap.

the recognized keywords are as follows. keywords are case insensitive and values are case insensitive.

Host

defines the options that would be applied if this value matches the host specified on the command line. the next Host entry or EOF determine the list of applicable options. it's giving matchmaker energy 💖

HostName

specifies the actual host name to connect to. can be DNS name or IP address. yes, either one, flexible queen ✨

Port

specifies the port number to use to connect to the remote host. pick your lane, number-wise 🔢

User

specifies the user name to login in as. who are we being today bestie? 👑

IdentityFile

specifies the file with the private key used for public key authentication with the remote host. the file must be in the Dropbear format. see dropbearkey(1) to generate one. ~/ at the start of the path will be expanded to the executing user's home directory. a path that does not start with / will be treated relative to this configuration file's directory. otherwise the path will be used as is.

because this file contains a secret it must have strict permissions to prevent abuse attempts — read/write for the executing user, and no access to anyone else. seriously, lock it down, no random access 🔒

📝 NOTES 📝

if compiled with zlib support and if the server supports it, dbclient will always use compression. always. compression stays on, no toggle, that's just the vibe 🗜️✨

👀 SEE ALSO 👀

💜 AUTHORS 💜

  • Matt Johnston <matt@ucc.asn.au>.
  • Mihnea Stoenescu wrote initial Dropbear client support.
  • Gerrit Pape <pape@smarden.org> wrote this manual page.

that's the whole page bestie — Debian source/version, dated February 1, 2023, and it's the DBCLIENT(1) manual. stay encrypted, stay iconic 💖🎀🦋

📦 where this page comes from