.. include:: /substitutions.rst
.. include:: /urls.rst

.. _pureos_remote_disk_unlock:

Remote disk unlock
==================

You can enable remote disk unlock to enter your disk unlock password over the network.
This is most useful for servers, which might not have a keyboard or display attached, but it works for any PureOS system.

Enable remote disk unlock
-------------------------

#. Open a terminal emulator.

   * On systems with a desktop environment, :ref:`launch a terminal emulator <pureos_terminal_launch>`.
   * On systems with no desktop environment, a terminal emulator starts by default once you log in.

#. Install packages: ``sudo apt install -y dropbear-initramfs``

   * Commands using ``sudo`` may prompt for your password.
     If so, type your password and press Enter.
     For security, nothing is shown on the screen when typing.

#. Apply configuration for Dropbear: ``sudo sed -E -e 's|^#?DROPBEAR_OPTIONS=.*|DROPBEAR_OPTIONS="-I 180 -j -k -p 4522 -s -c cryptroot-unlock"|' -i /etc/dropbear/initramfs/dropbear.conf``

   * This applies the following configuration options:
   * ``-I 180``: Disconnect clients if there is no activity for 180 seconds (3 minutes).
   * ``-j -k``: Disable local and remote port forwarding.
   * ``-p 4522``: Listen on port 4522.
   * ``-s``: Do not allow password logins (we will log in with an SSH public key).
   * ``-c cryptroot-unlock``: Only allow unlocking the disk (do not allow running other commands).

#. Configure boot networking:

   * For DHCP automatic addresses: ``echo "IP=::::$(hostname)-init::dhcp" | sudo tee /etc/initramfs-tools/conf.d/ip.conf``
   * For static addresses, consult the documentation for `the ip= command line parameter <linux_nfsroot_ip_>`_.

Next, authorize a client to connect during boot.

Authorize a client to connect
-----------------------------

#. :ref:`Enable remote SSH access <pureos_remote_ssh_access>` on the server if you have not already done so.
#. Copy your local SSH public key to the server.
   On the client: ``rsync ~/.ssh/id_ed25519.pub <username>@<hostname>.local:~/next_key.pub``

   * Your local SSH key might have a different name than ``id_ed25519.pub`` if you created a different type of SSH key.

#. Authorize this key and update the initramfs.
   On the server: ``sudo cat ~/next_key.pub >>/etc/dropbear/initramfs/authorized_keys; sudo update-initramfs -u -k all``

Unlock remotely
---------------

#. Power on the server.
#. When the server is ready to unlock the disk, find the server's IP address.

   * For DHCP automatic addressing, check your DHCP server for the address assigned to ``<hostname>-init``.
     In home/small office networks, the DHCP server is usually your router.
   * For static addressing, use the static address you assigned.

#. On the authorized client, connect to the server: ``ssh -p 4522 root@<address>``
#. If this is your first time connecting from this system, SSH will ask to confirm the server's identity.
   On a trusted network, you can type ``yes`` and press Enter.
   SSH will save this identity and use it to authenticate the server in the future.

   .. code-block::

      The authenticity of host '[172.21.1.191]:4522 ([172.21.1.191]:4522)' can't be established.
      ED25519 key fingerprint is SHA256:jNvyq0MREPrdHO+H/tgtI5N24Bgl4l1fORCSXTnoB6Q.
      This key is not known by any other names.
      Are you sure you want to continue connecting (yes/no/[fingerprint])?

#. The server will prompt for the disk unlock password; type it and press Enter.