Net::Dropbear::SSHd - Embed and control a Dropbear SSH server inside of perl


  use Net::Dropbear::SSHd;
  my $sshd = Net::Dropbear::SSHd->new(
    addrs      => '2222',
    keys       => $key_filename,
    hooks      => {
      on_log => sub
        my $priority = shift;
        my $msg      = shift;
        warn( "$msg\n" );
        return HOOK_CONTINUE;


Net::Dropbear::SSHd allows you to embed and control an SSH server (using Dropbear) from perl.


Maybe you're asking yourself why you'd want to do that? Imagine that you want to run a service where you let users run remote commands over SSH, say SFTP or git. Also imagine that you'd like maintain the users or public keys in a database instead of in a file. A good example of this behavior would be Github and other cloud-based git-over-ssh solutions.

I'm pretty confident that one could get OpenSSH to do this, but I saw a couple problems:

The user must be a real user

Any user that wants to connect must be a real user at the OS level. Managing multiple users, let alone millions, is a nightmare.

OpenSSH really likes running as root

Until recently, running as non-root was even possible. It's now possible, but a lot of interesting features are restricted.

Authorized keys can be provided through a script owned by root

A continuation of the point above, but in order to enable OpenSSH to verify a key, a script can be provided. This script (and all directories leading to the script) must be owned by root.

OpenSSH (and SSH) have a lot of options

And while that is a good thing in general, in this particular case I was not confident that I could tune all the options correctly to make sure I wasn't completely securing the system.

I really didn't want to provide outside users with a clever way to gain access to my machine. That's where this module comes into play. The goal of Net::Dropbear::SSHd is that you can control the entire lifecycle of SSHd, including which usernames are accpeted, which public keys are authorized and what commands are ran.



  my $sshd = Net::Dropbear::SSHd->new({ %params });

Returns a new Net::Dropbear::SSHd object.



A string or an array of addresses to bind to. Default: Nothing


An array of strings that are the server keys for Dropbear. Default: Generate keys automatically


A hashref of coderef's that get called during key points of the SSH server session. See "Hooks".

Dropbear options


Default: off

If Dropbear is complied with trace debuging turned on (not the default), turning this on will enable Dropbear's debugging information to be dumped.


Default: off

Turning the forkbg option on means that Dropbear will fork into the background. Since Net::Dropbear::SSHd forks to run the main Dropbear code, doing this second fork would seem redundant.


Default: off

Turning the usingsyslog option on means Dropbear will use syslog to output it's logs. Regardless of this setting, the on_log hook will still be called.


Default: on

Turning the norootlogin option on means that root can not login.


Default: on

Turning the noauthpass option on means that password authentication is not allowed


Default: on

Turning the norootpass option on means that root cannot authenticate using a password.


Default: off

Turning the allowblankpass option on means that if the SSH client requests it, Dropbear will authenticate someone with a blank password.


Default: off

Turning the delay_hostkey option on tells Dropbear to not generate hostkey files until the first user connects. This allows for faster startup times the very first time in exchange for a delayed connection for the very first user.


Default: off

Turning on the domotd option means that when an interactive session is started, the message of the day is sent.


Default: on

Turning on the noremotetcp option means that Dropbear will not create remote forwarded TCP tunnels.


Default: on

Turning on the nolocaltcp option means that Dropbear will not create locally forwarded TCP tunnels.


During the run of Dropbear, Net::Dropbear::SSHd hooks into certain points of the processing. With these hooks, the outcome of Dropbear can be changed. Each hook can return one of the hook constants: "HOOK_COMPLETE", "HOOK_CONTINUE" or "HOOK_FAILURE". Unless otherwise noted, returning "HOOK_CONTINUE" will result in Dropbear continuing as though the hook hadn't been called. See the hooks attribute.

on_log(priority, message)

The on_log hook is called when Dropbear logs anything.

HOOK_COMPLETE - No more logging will take place

HOOK_FAILURE - Logging will continue as normal


The on_start hook is called after Dropbear is done initalizing.


HOOK_FAILURE - Dropbear will exit


The on_username hook is called when a username is given. Returning anything but HOOK_CONTINUE from this will prevent on_passwd_fill or on_shadow_fill from being called.

HOOK_COMPLETE - The username is acceptable and dummy entries are used for the password file

HOOK_FAILURE - The username is rejected

on_passwd_fill(AuthState, username)

The on_passwd_fill hook is called when Dropbear is filling in information for a user from the passwd file. The AuthState paramater is an object that can be manipulated to fill in information for Dropbear. See Net::Dropbear::XS::AuthState. If any AuthState data is left invalid, Dropbear will exit.

HOOK_COMPLETE - The AuthState object should be used as the passwd information.

HOOK_FAILURE - The passwd information is invalid and the user connection will be rejected.

on_shadow_fill(crypt_password, pw_name)

The on_shadow_fill hook is called when the shadow file is consulted for a users password. Note that this is called even if HOOK_COMPLETE is returned from on_passwd_fill. The first paramter (crypt_password) is mutable and can be used to set what the user's crypted password is. If the crypt_password is invalid (null), Dropbear will exit.

HOOK_COMPLETE - The shadow file will not be consulted for the given user


on_crypt_passwd(input_passwd, salt, pw_name)

The on_crypt_passwd hook is used as an opportunity to crypt the password given by the connection yourself. It will give you the password as it was entered, and you are expected to change $_[0] in place to a crypted version that will match the value given in either on_passwd_fill or on_shadow_fill.

HOOK_COMPLETE - The crypt function doesn't need to be ran, and Dropbear can check the value of input_passwd directly.


on_check_pubkey(authkeys, pw_name)

The on_check_pubkey hook is called right before the the public keys for a user is checked. The first paramater, authkeys, is an string that can be populated with an authorized_keys(8) file and it will be used to authenticate the user given with pw_name.


HOOK_FAILURE - The public keys could not be retrieved and will not be checked.


The on_new_channel hook is called when the client requests a new channel. The first paramater, on_new_channel, will contain the channel type as a string.




The on_chansess_command hook is called when a new command is being requested by the client. The first paramater, chaness, is an object that should be used to let Dropbear know how to interact with the channel. See Net::Dropbear::XS::SessionAccept for more details.

HOOK_COMPLETE - No attempts will be made to start the command specified

HOOK_CONTINUE - The values from chansess will be copied into Dropbear and used in Dropbear's default operations

HOOK_FAILURE - The command session will behave as though the command had vailed



Call $sshd->run to start Dropbear.


If Dropbear has been started, then this will return the Child::Link::Proc object of the child process. If Dropbear is not running, this will return undef. In the child process this will be undef as well.


The comm method is a convience for both parent and child processes. This contains a two-way socket between the parent and child (and sub-children) processes. This is a AF_UNIX socket, which means you can pass new file handles between the processes.


Returns true if Dropbear is running, false if it's not.


This will stop Dropbear.


This waits for Dropbear to exit after it is sent the kill signal.


The constants below are exported by default.


This is used to indicate that a hook is done and not to use Dropbear's default operations.


This is used to indicate that the hook has decided not to do anything.


This is used to indicate that the hook has failed and Dropbear should not continue.


Since Dropbear is a program itself, it is ran as a child process. Each connection will also have it's own child process.


Jon Gentle <>


Copyright 2015-2016 Jon Gentle


This is free software. You may redistribute copies of it under the terms of the Artistic License 2 as published by The Perl Foundation.

This includes a complete copy of Dropbear that is patched and used. The majority of Dropbear is Copyright (c) 2002-2014 Matt Johnston under the MIT license. See for details about Dropbear and it's license.