unlock v0.8 [14 Nov 2018] - by Dominic


This utility provides an easy way to enter the decrypt passphrase on a remote machine which has root encryption with dm-crypt+LUKS (e.g. as set up at Debian or Ubuntu installation if you select 'encrypted LVM') - so that local access is not required when booting the machine.

When the encrypted machine boots it loads an initramfs image from a small unencrypted boot partition and then waits for the encryption passphrase, without which it cannot read the main partition. If it has previously been suitably modified (see below) you can reach it remotely (by ssh) at this boot stage and enter the passphrase, which allows booting to complete.

From a remote client you can use to enter the passphrase, provided your public key (i.e. matching the private key used for ssh connection by has previously been added to the encrypted machine's /etc/dropbear-initramfs/authorized_keys file and its initramfs has then been updated (see below). Please note this means there are two requirements for ability to remote boot the encrypted machine: you must know the passphrase *and* your public key must be pre-loaded on the encrypted machine.

You can also use in test mode (-t) in a cron job to monitor the encrypted machine and warn you if it ceases to be fully available: if all is well then running -t generates no text output, otherwise it will show an appropriate message.


./ [options] ip.address.of.remote.encrypted.machine


-d - debug mode (implementation may vary)
-h - show this help and exit
-i file - specify private key identity file (default: selected automatically by ssh)
-l - show changelog and exit
-p n - where 'n' is the ssh port used by dropbear in initramfs on the encrypted machine (default: 22)
-s file - test status of remote machine and output text if status has changed since the preceding run of ' -s' to the specified 'file'
-t - test status of remote machine and exit with code - silent if running normally
-v - show passphrase on console as you enter it

Exit Codes

0 - remote machine is running normally
1 - some error occurred or remote machine is off/unresponsive
2 - remote machine is still awaiting passphrase

Prerequisites is designed for a remote machine that has dm-crypt + LUKS on the root system so that it cannot be started up without the pre-set passphrase being entered. (The process of setting up a machine for dm-crypt + LUKS is not covered here, but it can most easily be done on Debian or Ubuntu if you use the alternate or netboot installer [file: mini.iso] and select 'Guided - use entire disk and set up encrypted LVM'.) By default, booting such an encrypted machine requires local access in order to enter the passphrase, but remote access at this stage is possible by setting up the encrypted machine thus (tested under Ubuntu 18.04):

sudo -i # become root (if not already)
apt-get install dropbear-initramfs # check/install necessary software
# add public keys for remote users who could run here, one per line:
nano /etc/dropbear-initramfs/authorized_keys
# make sure the file terminates with EOL
[[ $(tail -c1 /etc/dropbear-initramfs/authorized_keys|wc -l) -eq 1 ]] && echo OK || echo FAIL
update-initramfs -u -k all # update boot-time filesystem
hostname -I # note the ip address, please ensure it won't change on reboot


bash grep sed ssh


If you do not know the passphrase, or if you do not have a private key that matches a public key previously set up for the encrypted machine's initramfs, then cannot help you; you can get remote access only to the initial boot stage of the encrypted machine and it will be impossible to access the main system or data. If you have the passphrase but not a suitable private key, you will require local access to the encrypted machine in order to start it up fully.

More information about remote booting with dmcrypt + LUKS can be found at:

For a tool for converting an existing unencrypted partition to dm-crypt+LUKS (must be offline) see:

You can test a passphrase on an *already-mounted* dm-crypt + LUKS partition. In this example, /dev/sda5 is encrypted (as /dev/sda5_crypt), and the 'x' can be anything (required but ignored). A non-zero exit code indicates a wrong passphrase:

cryptsetup open /dev/sda5 x --test-passphrase --tries 1; echo $?

Depending on the remote machine's network configuration (a) when booting and (b) after booting has completed, these two states may have different ips or accept connections from different ports; if so, after you have successfully entered the passphrase will report that it was unable to connect and ask you to check if the remote machine is switched on - the remote machine may be working fine but with a different ip address or port. So try to ensure that the same ip address is allocated when booting (see below) as when fully booted (e.g. per /etc/network/interfaces), and is allocated in the same way.

To specify ip parameters at boot time (i.e. running from initramfs) set 'ip=' in variable GRUB_CMDLINE_LINUX in /etc/default/grub and then run update-grub. The parameters are ip=client-ip:[server-ip]:gateway-ip:netmask:[hostname]:device:autoconf - for more info see and Never specify server-ip; and do not specify a hostname because depends on the hostname when booting being '(none)'. Examples:


And afterwards run


To specify a non-standard ssh port at boot time (i.e. not 22), add a line in /etc/dropbear-initramfs/config like


And then update initramfs

update-initramfs -u -k all


Whereas runs under bash on the client machine, cryptroot-unlock resides by default in the initramfs package on the encrypted machine and can be run using SSH from a client with any OS. As with, cryptroot-unlock can only be run successfully if the appropriate public key has been stored beforehand in the encrypted machine's initramfs (see above). Subject to that, here are examples of how cryptroot-unlock can be run from a remote client logging in with SSH (instead of using

One-line example to run remotely (i.e. on client machine) to remote machine under Linux or Cygwin or Bash-on-ubuntu-on-Windows:

ssh -t -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no root@ cryptroot-unlock

Another one-line example but using a non-default private key file:

ssh -ti /path/to/private_key_file -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no root@ cryptroot-unlock

or under Windows using plink:

plink.exe -t -i C:\path\private_key_file.ppk root@ cryptroot-unlock


0.8 [14 Nov 2018] - silently correct if user supplies ip address in form name@n.n.n.n
0.7 [09 Nov 2018] - modify instructions to reference cryptroot-unlock, remove references to
0.6 [07 Nov 2018] - correct instructions for location of authorized_keys file
0.5 [06 Nov 2018] - bugfix -i option
0.4 [30 May 2017] - bugfix -t option
0.3 [20 Apr 2017] - add -s option, other fixes
0.2 [12 Apr 2017] - updated help, add -i and -t options, several other fixes
0.1 [04 Apr 2017] - initial version



I have provided this software free gratis and for nothing. If you would like to thank me with a contribution, please let me know and I will send you a link. Thank you!

My Other Sites

My Programs

Here is a selection of some (other) programs I have written, most of which run from the command line (CLI), are freely available and can be obtained by clicking on the links. Dependencies are shown and while in most cases written for a conventional Linux server, they should run even on a Raspberry Pi, and many can run under Windows using Cygwin. Email me if you have problems or questions, or if you think I could help with a programming requirement.

Backup Utilities

Debian/Ubuntu kernel and LVM Utilities

Dellmont / Three / Giffgaff / Vodafone - VoIP and Mobile Phone Account Utilities

Miscellaneous Programs


No comments yet
Hide my email
Powered by Scriptsmill Comments Script