{"id":13453806,"url":"https://github.com/rhansen/unlock-cryptroot","last_synced_at":"2025-10-14T10:02:13.990Z","repository":{"id":80002293,"uuid":"48149490","full_name":"rhansen/unlock-cryptroot","owner":"rhansen","description":"Script to unlock an Ubuntu or Debian encrypted root filesystem via ssh","archived":false,"fork":false,"pushed_at":"2020-04-26T17:54:22.000Z","size":22,"stargazers_count":14,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-17T11:05:28.724Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhansen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2015-12-17T03:13:50.000Z","updated_at":"2024-11-12T12:39:42.000Z","dependencies_parsed_at":"2023-03-01T02:15:50.274Z","dependency_job_id":null,"html_url":"https://github.com/rhansen/unlock-cryptroot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhansen%2Funlock-cryptroot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhansen%2Funlock-cryptroot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhansen%2Funlock-cryptroot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhansen%2Funlock-cryptroot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhansen","download_url":"https://codeload.github.com/rhansen/unlock-cryptroot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244507828,"owners_count":20463689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T08:00:47.773Z","updated_at":"2025-10-14T10:02:13.889Z","avatar_url":"https://github.com/rhansen.png","language":"Shell","readme":"# unlock-cryptroot\n\nScript to unlock an Ubuntu or Debian encrypted root filesystem via\nssh.\n\nTo unlock the target system (after initial setup; see below):\n  1. Run the following from your workstation:\n     ```sh\n     unlock-cryptroot target.example.com\n     ```\n  2. Enter the password to your ssh key (if there is one).\n  3. Enter the drive encryption password(s).\n\nFor additional options and default file locations, run:\n```sh\nunlock-cryptroot --help\n```\n\nTested on:\n  * Ubuntu 18.04 (Bionic)\n  * Ubuntu 16.04 (Xenial)\n  * Ubuntu 14.04 (Trusty)\n\nRelevant bug reports:\n  * [Ubuntu bug #595648](https://bugs.launchpad.net/bugs/595648)\n  * [Debian bug\n    #782024](https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=782024)\n\n## Target Setup Instructions\n\n### Ubuntu 18.04 (Bionic Beaver) or newer\n\n  1. Edit `/etc/crypttab` and add the `initramfs` option to each\n     device you want to be able to remotely unlock during boot. See\n     [`man 5\n     crypttab`](https://manpages.ubuntu.com/manpages/bionic/man5/crypttab.5.html)\n     for details. (The `initramfs` option is not necessary for the\n     root device or any resume devices, but it doesn't hurt.) Update\n     your initramfs after making any changes (`sudo update-initramfs\n     -u`).\n  2. Install the dropbear ssh server into the initramfs:\n     ```sh\n     sudo apt-get install dropbear-initramfs\n     ```\n  3. If you wish to use a non-default IP address or network device,\n     set the [`ip=` kernel boot\n     parameter](https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt):\n       1. Edit `/etc/default/grub`\n       2. Add your `ip=` parameter to the `GRUB_CMDLINE_LINUX` variable\n       3. Save your changes\n       4. Run `sudo update-grub` to install the changes\n  4. Prepare keys for public key authentication:\n       1. Generate an ssh key pair for logging in to the initramfs:\n          ```sh\n          sudo sh -c '(umask 0077 \u0026\u0026 mkdir -p /etc/initramfs-tools/root/.ssh)'\n          sudo ssh-keygen -t rsa -b 4096 -o -a 100 \\\n              -f /etc/initramfs-tools/root/.ssh/id_rsa\n          ```\n       2. Add the public key to the initramfs's `authorized_keys`:\n          ```sh\n          sudo cp /etc/initramfs-tools/root/.ssh/id_rsa.pub \\\n              /etc/initramfs-tools/root/.ssh/authorized_keys\n          ```\n       3. Update the initramfs:\n          ```sh\n          sudo update-initramfs -u\n          ```\n  5. At boot, Ubuntu's initramfs will create a Netplan config file for\n     your network interface. This config file overrides the default\n     network configuration for that interface. If you do not want this\n     override, install an initramfs script that deletes the Netplan\n     config file after your system is unlocked. See the example\n     `etc_*` file.\n\n### Ubuntu 16.04 (Xenial Xerus)\n\n  1. Edit `/etc/crypttab` and add the `initramfs` option to each\n     device you want to be able to remotely unlock during boot. See\n     [`man 5\n     crypttab`](https://manpages.ubuntu.com/manpages/bionic/man5/crypttab.5.html)\n     for details. (The `initramfs` option is not necessary for the\n     root device or any resume devices, but it doesn't hurt.) Update\n     your initramfs after making any changes (`sudo update-initramfs\n     -u`).\n  2. Install the dropbear ssh server into the initramfs:\n     ```sh\n     sudo apt-get install dropbear-initramfs\n     ```\n  3. If you wish to use a non-default IP address or network device,\n     set the [`ip=` kernel boot\n     parameter](https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt):\n       1. Edit `/etc/default/grub`\n       2. Add your `ip=` parameter to the `GRUB_CMDLINE_LINUX` variable\n       3. Save your changes\n       4. Run `sudo update-grub` to install the changes\n  4. Prepare keys for public key authentication:\n       1. Generate an ssh key pair for logging in to the initramfs:\n          ```sh\n          sudo sh -c '(umask 0077 \u0026\u0026 mkdir -p /etc/initramfs-tools/root/.ssh)'\n          sudo ssh-keygen -t rsa -b 4096 -o -a 100 \\\n              -f /etc/initramfs-tools/root/.ssh/id_rsa\n          ```\n       2. Add the public key to the initramfs's `authorized_keys`:\n          ```sh\n          sudo cp /etc/initramfs-tools/root/.ssh/id_rsa.pub \\\n              /etc/initramfs-tools/root/.ssh/authorized_keys\n          ```\n       3. Update the initramfs:\n          ```sh\n          sudo update-initramfs -u\n          ```\n\n### Ubuntu 14.04 (Trusty Tahr) or older\n\n  1. If you have one or more non-root non-resume partitions that you\n     want to be able to remotely unlock:\n       1. Run `blkid` to get the UUID of each such partition.\n       2. Edit `/etc/initramfs-tools/conf.d/resume` and add a new\n          `RESUME=UUID=\u003cuuid\u003e` line for each UUID at the top of the\n          file. The last `RESUME=` line must refer to your resume\n          device. The result should look like this:\n          ```\n          RESUME=UUID=\u003cuuid of non-root non-resume device #1\u003e\n          RESUME=UUID=\u003cuuid of non-root non-resume device #2\u003e\n          RESUME=UUID=\u003cuuid of resume device\u003e\n          ```\n       3. Update the initramfs:\n          ```sh\n          sudo update-initramfs -u\n          ```\n     By default, initramfs only attempts to unlock the root device and\n     any resume devices. Adding the UUIDs of non-root non-resume\n     devices tricks initramfs into also unlocking those devices. This\n     hack is not needed in Ubuntu 16.04 (Xenial) or later thanks to a\n     new `initramfs` crypttab option added in Ubuntu 16.04 (Xenial).\n  2. Install dropbear into the initramfs:\n     ```sh\n     sudo apt-get install dropbear\n     ```\n  3. Set the [`ip=` kernel boot\n     parameter](https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt):\n       1. Edit `/etc/default/grub`\n       2. Add your `ip=` parameter to the `GRUB_CMDLINE_LINUX` variable\n       3. Save your changes\n       4. Run `sudo update-grub` to install the changes\n  4. The kernel `ip=` parameter conflicts with the system's normal\n     networking configuration, so you must set up a script to\n     deconfigure the interface after the drive is unlocked but before\n     the normal networking configuration is applied. See the example\n     `etc_*` file.\n\n## Remote Workstation Setup Instructions\n\n  1. Copy the ssh private key for the target machine's initramfs to\n     the machine that will be doing the remote unlocking:\n     ```sh\n     T=target.example.com # change as necessary\n     scp root@\"$T\":/etc/initramfs-tools/root/.ssh/id_rsa \\\n         ~/.ssh/id_rsa.initramfs_\"$T\"\n     ```\n","funding_links":[],"categories":["Shell"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhansen%2Funlock-cryptroot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhansen%2Funlock-cryptroot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhansen%2Funlock-cryptroot/lists"}