unlock v0.3 [20 Apr 2017] - by Dominic
This utility provides an easy way to enter the decrypt passphrase on a remote machine which has root 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 (suitably-modified - see below) boots it starts a little ssh server (dropbear) and waits for the passphrase: with local access you see the ip address but if you only have remote access you will have to find it some other way - to make this easier, set the ip on the encrypted machine as static or ensure that your DHCP server always allocates the encrypted machine the same ip address.
From a remote client you can use this utility 'unlock' to enter the passphrase, provided your public key (i.e. matching the private key used for ssh connection by 'unlock') has previously been into the encrypted machine's /etc/initramfs-tools/root/.ssh/authorized_keys 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 use 'unlock' 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 unlock -t generates no text output, otherwise it will show an appropriate message.
./unlock [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 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 'unlock -s' to the specified 'file'
-t - test status of remote machine and exit - silent if running normally (exit code 0: running normally, code 1: error or machine is off, code 2: awaiting passphrase)
-v - show passphrase on console as you enter it
0 - remote machine is running normally
1 - some error occurred or remote machine is off/unresponsive
2 - remote machine is still awaiting passphrase
'unlock' 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 using the automatic installer by selecting 'Guided - use entire disk and set up encrypted LVM'.) Normally 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 16.04.2):
sudo -i # become root (if not already)
apt-get install openssh-server dropbear # check/install necessary software
# add public keys for remote users who could run unlock here, one per line:
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 utility 'unlock' 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 when booting and when fully loaded, these two states may have different ips; if so, after you have successfully entered the passphrase 'unlock' will report that it was unable to connect and ask you to check if the remote machine is switched on when actually it is working fine, but at a different ip address. You are advised to ensure that the same ip address is allocated when booting (see below) and when full 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 parameter 'ip=' in GRUB_CMDLINE_LINUX in /etc/default/grub and then run update-grub. The parameters are ip=client-ip:[server-ip]:gw-ip:netmask:[hostname]:device:autoconf - for more info see https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt and https://www.eugenemdavis.com/set-static-ip-initramfs.html. Never specify server-ip; and do not specify a hostname because 'unlock' depends on the hostname when booting being '(none)'. Examples:
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
- TimeDicer - Onsite/offsite data backup for Windows (uses rdiff-backup)
- Finding a 4D Backup Solution
- Web Scraping How To - extracting data from web sites
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.
- TimeDicer - Onsite/offsite data backup for Windows (uses rdiff-backup) [ GNU/Linux & MS Windows©: 2008-16 ]
- rdiffweb-install - GNU/Linux script to install rdiffWeb. [ GNU/Linux: 2011-16 ]
- rdiff-backup-regress - GNU/Linux script to regress an rdiff-backup archive. [ GNU/Linux: 2012-16 ]
Debian/Ubuntu kernel and LVM Utilities
- kernel-remove - GNU/Linux script to list the installed GNU/Linux kernels in a Debian-based distro (e.g. Ubuntu), and can be used to remove an unwanted kernel and related packages, updating grub appropriately. (Ubuntu Tweak can do the same but kernel-remove.sh is a command-line script so does not require GUI.) [ GNU/Linux-Debian/Ubuntu: 2010-15 ]
- kernel-update - GNU/Linux script to install/update Ubuntu kernel (also optionally btrfs-progs and duperemove) with latest version. [ GNU/Linux-Ubuntu: 2015-16 ]
- lvm-usage - GNU/Linux script to show available disk space and how it is used; run as cron job to warn if usage is above a set percentage. Provides additional information if LVM is in use. [ GNU/Linux-Debian/Ubuntu: 2012-16 ]
- lvm-delete-snapshot - GNU/Linux script to remove LVM snapshot that has been left over by another process. [ GNU/Linux-Debian/Ubuntu: 2012-16 ]
Dellmont / Three / Giffgaff / Vodafone - VoIP and Mobile Phone Account Utilities
- dellmont-credit-checker - GNU/Linux script to check credit balance on many Dellmont / Finarea / Betamax portals such as voicetrading.com and voipdiscount.com. [ GNU/Linux: 2008-17 ]
- sms-sender - GNU/Linux script to send text messages using Dellmont’s voicetrading.com. [ GNU/Linux: 2012-16 ]
- get-vt-cdrs - GNU/Linux script to download CDRs (call detail records) from Dellmont’s voicetrading.com or voippro.com. [ GNU/Linux: 2010-17 ]
- saynoto0870 - For people in UK, a GNU/Linux script which performs automated lookup of the www.saynoto0870.com database, finding cheap or free geographic number replacements for expensive non-geographic (087* or 084*) numbers. [ GNU/Linux: 2012-12 ]
- three-credit-checker - GNU/Linux script which checks credit/calls/text/data remaining on a mobile phone account with three.co.uk. [ GNU/Linux: 2014-16 ]
- giffgaff-credit-checker - GNU/Linux script which checks credit/calls/text/data remaining on a mobile phone account with giffgaff.com. [ GNU/Linux: 2014-17 ]
- vodafone-compile-bills - GNU/Linux script which reprocesses downloaded call record 'csv' files from vodafone.co.uk so that they can be easily analysed via spreadsheet - including analysis of bundled minutes which even Vodafone do not seem able to perform! [ GNU/Linux: 2012-16 ]
- sleepwalker - Windows© program which can be run from a remote machine to 'wake up' a Windows© machine behind a router, wait for it to start and then initiate Remote Desktop session. [MS Windows©: 2008-14]
- pass - GNU/Linux local program for easy entering of decrypt passphrase on a remote machine which has root dm-crypt+LUKS. [ GNU/Linux: 2017-17 ]
- nano-update - GNU/Linux program to check/configure/make/install editor nano to the latest stable version found at http://www.nano-editor.org. [ GNU/Linux: 2015-16 ]
- pdf-compress - GNU/Linux program to create smaller b/w pdf file from an original large pdf file, especially when original resulted from scanning. [ GNU/Linux: 2016-17 ]
- form-extractor - GNU/Linux program to extract form tags from a web page or downloaded file. [ GNU/Linux: 2012-16 ]
- 123-dns-manager - GNU/Linux program for automated 123-Reg.co.uk Advanced DNS management. [ GNU/Linux: 2016-17 ]
- 123-dns-sync - GNU/Linux program to update DNS record at 123-Reg.co.uk to match external ip. [ GNU/Linux: 2016-17 ]
- recover-space - GNU/Linux program to enable a virtual disk volume to be compacted. [ GNU/Linux: 2014-15 ]
- tiny-device-monitor - GNU/Linux program to test webpages (including password-protected) or machines to check they are live; use as a cron job for your own websites, for hardware presenting a webpage, or for any machines with a presence on your local LAN or on the internet. [ GNU/Linux: 2009-16 ]
- dutree - GNU/Linux program to show a tree-style list of files and directories at the specified location and greater than the specified size (default 1GB). [ GNU/Linux: 2012-15 ]
- disk-wiper - GNU/Linux script to wipe a disk drive comprehensively and also check it for bad blocks. For use on a surplus drive (not SSD, not GPT) before passing to a third party. [ GNU/Linux: 2011-16 ]
- myip-upload - GNU/Linux and Windows (Cygwin) script to obtain external ip and upload it to remote site/file by ftp. [ GNU/Linux & MS Windows©: 2014-16 ]
- man2text - GNU/Linux one-liner program to convert man page output to straightforward text. [ GNU/Linux: 2012-12 ]
- Accounts - Multi-business multi-currency accounting software, uses Access [MS Windows©: 1996-2016]
- Rents Program - Residential lettings/landlord front office program, with many special features for UK market [MS Windows©: 1991-2016]