diff options
Diffstat (limited to 'README.adoc')
| -rw-r--r-- | README.adoc | 180 |
1 files changed, 0 insertions, 180 deletions
diff --git a/README.adoc b/README.adoc deleted file mode 100644 index 5ecc8bb8f967..000000000000 --- a/README.adoc +++ /dev/null @@ -1,180 +0,0 @@ -= mkinitcpio Wireguard hook -:author: David Harrigan -:email: <dharrigan [@] gmail [dot] com> -:docinfo: true -:doctype: book -:icons: font -:numbered: -:sectlinks: -:sectnums: -:setanchors: -:source-highlighter: highlightjs -:toc: -:toclevels: 5 - -== ChangeLog - -IMPORTANT: Until this package has stabilised and until it has reached a 1.0.0 -release, *please be very careful* to examine the version changes listed below -as the package requirements and instructions can change to reflect a better -understanding of the problem domain. *DO NOT ASSUME THAT ANYTHING UNTIL AT -LEAST A 1.0.0 RELEASE* - -WARNING: Read the warning above. - -|=== -|Version | Note - -| *0.4.1* -a| -* Remove unnecessary license headers and simply copy UNLICENSED to appropriate place -* Minor bugfixes - thanks @undiabler! - -| *0.4.0* -a| -* Add a route based upon the ALLOWED_IPS. - -| *0.3.0* -a| -* Various tidy ups and script improvements. -* Rename PRIVATE_KEY_FILE to PRIVATE_KEYFILE - BREAKING CHANGE! - -| *0.2.0* -a| -* Don't include the entire `/etc/wireguard` directory, instead use a subdirectory, namely `/etc/wireguard/initcpio` to keep things separate. - -| *0.1.0* -a| -* Initial Release. - -|=== - -== Rationale - -Firstly, encryption. Encrypt all the things. - -Secondly, I think https://www.wireguard.io[Wireguard] is pretty awesome. It's -really easy to setup and use and works flawlessly (at least for me 😄). - -Thirdly, the ability to remotely unlock encrypted partitions is extremely -useful. However, a limitation is that in order to remotely unlock the -partition via SSH, you normally need to be on the same network (or at least -routeable) to the computer that needs unlocking. - -As far as I could tell, there was nothing available in -https://aur.archlinux.org[AUR] that provided a Wireguard hook for -`mkinitcpio`. Creating a hook should allow a basic Wireguard interface to be -established so that - via a secure network - you could gain access to the -remote machine. This is my small attempt to achieve that aim. - -IMPORTANT: I developed this little hook for myself and I'm releasing it into -the general community in the (probably misguided) hope that others may find it -useful too. As usual, no warranty implied or otherwise is given towards the -fitness of this software in meeting *YOUR* needs. Please refer to the included -https://unlicense.org[Unlicense] license file for more information. That said, -I find this little hook useful - perhaps you may too - so please enjoy! Oh, -and please be be awesome to each other! - -WARNING: Ensure you have read the Arch wiki section on -https://wiki.archlinux.org/index.php/Dm-crypt/Specialties#Remote_unlocking_of_the_root_(or_other)_partition[remote -unlocking]. It's a *very* good idea to get remote unlocking working *first* on -your local network - proving that it works for you (this includes using either -*tinyssh* or *dropbear* to authenticate and unlock successfully) -- *before* attempting to setup this mkinitcpio Wireguard hook for remote -unlocking. - -IMPORTANT: It is also *strongly* recommend that a *separate* Wireguard network -is setup and configured *just* for unlocking. You see, a private key (and a -public key) and a configuration file are written to the ramdisk (which -typically lives in an unencrypted boot partition). It's super trivially easy -for anyone to copy this ramdisk, extract out the contents and use the private -key and Wireguard configuration found therein to connect to your Wireguard -network. As a minimum, you could disable (on the remote peer *nominally called -the `server`*) the ability for the target machine (the `client` - the one on -which you are remotely unlocking partitions) to connect and authenticate - -only enabling connection *when* and *if* required. Please be careful and think -this through! Safety first! - -== OS Installation - -Standard installation rules apply. Here's an example using the -https://github.com/Jguer/yay[yay] package manager to install the utility. - -`yay -S mkinitcpio-wireguard` - -Please refer to your favourite package manager's documentation in learn how to -install it for you 😄 - -NOTE: Obviously, you must also install Wireguard! Choose either manual -installation (using git and compiling it yourself), or using `wireguard-arch` -or `wireguard-dkms`. Life is short, so personally I just roll with -`wireguard-arch`. Seems to work OOTB for me, but YMMV... - -== Configuration - -IMPORTANT: The setup and running of `mkinitcpio-wireguard` is *very* basic and -makes *lots* of assumptions. *This is intentional!* This hook is simple -because it is designed to get a minimal Wireguard up and running so that you -can remotely unlock encrypted partitions. The script does not attempt to do -anything else. This script will never be super fancy or clever. - -WARNING: Please read and familiarise yourself with how Wireguard works. In -particular, please refer to the *numerous* examples online of how to setup and -configure Wireguard. It is *strongly* suggested you get Wireguard up and -running first. A few examples of where to find documentation are listed below: - -* https://wiki.archlinux.org/index.php/WireGuard -* https://www.wireguard.com/quickstart/ -* https://git.zx2c4.com/WireGuard/about/src/tools/man/wg.8 - -After installing `mkinitcpio-wireguard`, an example configuration file will be -written to `/etc/wireguard/initcpio/unlock`. You *MUST* edit this file to suit -your particular Wireguard requirements. The file is really simple and -therefore should be pretty self-explanatory. - -NOTE: If you have an existing `wg0.conf` in your `/etc/wireguard` directory, -you can use the contents of that file as a reference. Please be aware of the -warning above concerning the recommended use of a separate network for remote -unlocking. - -== Hook Installation - -After you have edited the `/etc/wireguard/initcpio/unlock` file to suit your -needs, ensure that you've added the `wireguard` hook to the *HOOKS* array of -`/etc/mkinitcpio.conf`. Shown below is an example that also includes the use -of `netconf`, `tinyssh` and `encryptssh`. - ----- -HOOKS=(base udev autodetect keyboard keymap modconf block netconf wireguard tinyssh encryptssh filesystems fsck) ----- - -== Final Steps - -Lastly, run (still as root): - ----- -mkinitcpio -P ----- - -This will regenerate the ramdisk with your Wireguard configuration. - -You should now be able to reboot your machine and after the interface has come -up be able to ping it via your Wireguard network! You should now also be able -to SSH to the machine (you did remember to set that all up before doing this, -right?) and unlock any encrypted partitions and thus enable the continuation -of your boot process! FTW! - -NOTE: It could take a minute or two for your Wireguard interface to -authenticate and be recognised by the remote peer. Please be patient and hang -on in there! - -== Unlicensed - -Find the full unlicense in the UNLICENSE file, but here's a snippet. -This is free and unencumbered software released into the public domain. - ----- -Anyone is free to copy, modify, publish, use, compile, sell, or distribute -this software, either in source code form or as a compiled binary, for any -purpose, commercial or non-commercial, and by any means. ----- |