Home A - Z
Page Index

An Otter Wiki

Commit 2e2eec

2025-02-28 13:38:20 Samuli Seppänen: Add easyrsa-upgrade page
/dev/null .. Pages/easyrsa-upgrade.md
@@ 0,0 1,240 @@
+ # Upgrading EasyRSA
+
+ **Note**: This wiki is a *work in progress*.
+
+ This page describes the EasyRSA PKI upgrade process:
+ EasyRSA PKI version 2 to EasyRSA version 3, see below.
+
+
+ ## Setup
+
+ 1. You must install a new copy of EasyRSA v3.0.7 or above
+ 1. Copy your existing **EasyRSA version 2 files and directories** into `./easyrsa3`
+ Your `./easyrsa3` directory should now look *something* like below (in Before section).
+ 1. Linux: run `./easyrsa upgrade pki`
+ 1. Windows: run `easyrsa-start.bat` and then `./easyrsa upgrade pki`
+ If you have trouble starting EasyRSA-v3, please consult the relevant documentation. \\
+ Your `./easyrsa3` directory should now look *something* like below (in After section).
+
+ ### Examples
+
+ * **Linux**
+
+ Your current Easy-RSA **Version 2** PKI is located under `/root/easyrsa`
+ Your new Easy-RSA **Version 3** PKI will be located at `/etc/openvpn/easyrsa/pki`
+
+ Change directory to `/etc/openvpn/easyrsa`
+ Test that `easyrsa help` works, if that does not work then test that `./easyrsa help` works.
+
+ If you do not have a working copy of the `easyrsa` script then you **cannot** continue.
+
+ Copy `/root/easyrsa` to `/etc/openvpn/easyrsa`
+
+ * **Windows**
+
+ Your current Easy-RSA **Version 2** PKI is located under `\users\easyrsa`
+ Your new Easy-RSA **Version 3** PKI will be located at `\Program Files\Openvpn\easy-rsa\pki`
+
+ Start Easy-RSA `EasyRSA-Start.bat`
+
+ Copy `\users\easyrsa` to `/Program Files\Openvpn\easy-rsa`
+
+ ## Usage
+
+ To perform the upgrade:
+
+
+ 1. ``` ./easyrsa upgrade pki ```
+ This will upgrade a version 2 PKI to version 3.
+ This upgrade will also perform the CA upgrade below.
+ The CA is set to allow duplicate certificates to allow for for renewal.
+ The PKI is not changed only copied.
+
+ 2. ``` ./easyrsa upgrade ca ```
+ The CA is set to allow duplicate certificates to allow for for renewal.
+ The PKI is not changed.
+
+ To automate this upgrade use `--batch`
+
+ ## Steps
+
+ These CHECKS will be made if you upgrade now:
+
+ Before ANY changes are made a test run will be attempted ...
+
+ * Verify: new PKI dir does not exist and will not be over written.
+ * Verify: new backup PKI dir does not exist and will not be over written.
+ * Verify and Source the current PKI settings: ./vars or ./vars.bat
+ * Verify the current ca.crt
+
+ Then:
+ * CONFIRM NOW THAT THIS IS THE CORRECT ca.crt and continue or quit
+
+ These CHANGES will be made if you continue:
+
+ Before ANY changes are made a test run will be attempted ...
+ * Complete backup of the current PKI to ./VERY-SAFE-PKI
+ * Create new PKI dirs for use with EasyRSA-3
+ * Copy required working database files to new PKI
+ * Copy current PKI to new PKI
+ * Update the CA to allow duplicates for renewal
+ * create new openssl-easyrsa.cnf file
+ * Remove EasyRSA-2 program files
+ * Build new EasyRSA-3 vars file
+
+ ### Before
+
+ (This list is not completely accurate ... )
+
+ ```
+ .
+ ├── bin
+ │ ├── { EasyRSA v3 Windows executables ... }
+ │
+ ├── keys
+ │   ├── { Your current EasyRSA v2 PKI ... }
+ │
+ └── x509-types
+ ├── { EasyRSA v3 x509 definition files ... }
+
+ Linux EasyRSA-v2 program files:
+ ├── build-ca
+ ├── build-dh
+ ├── build-inter
+ ├── build-key
+ ├── build-key-pass
+ ├── build-ca.bat
+ ├── build-key-pkcs12
+ ├── build-key-server
+ ├── build-req
+ ├── build-req-pass
+ ├── clean-all
+ ├── inherit-inter
+ ├── list-crl
+ ├── make-crl
+ ├── pkitool
+ ├── revoke-crt
+ ├── revoke-full
+ └── sign-req
+
+ Windows EasyRSA-v2 program files:
+ ├── build-ca-pass.bat
+ ├── build-dh.bat
+ ├── build-key.bat
+ ├── build-key-pass.bat
+ ├── build-key-pkcs12.bat
+ ├── build-key-server.bat
+ ├── build-key-server-pass.bat
+ ├── clean-all.bat
+ ├── EasyRSA-Start.bat
+ ├── init-config.bat
+ ├── revoke-full.bat
+ ├── vars.bat
+ ├── vars.bat.sample
+ └── whichopensslcnf
+
+ Common EasyRSA-v2 files:
+ ├── index.txt.start
+ ├── README.txt
+ └── serial.start
+
+ Common EasyRSA-v3 files:
+ ├── easyrsa
+ ├── openssl-easyrsa.cnf
+ └── vars.example
+
+ ```
+
+ ### After
+
+ ```
+ .
+ ├── bin
+ │ ├── { EasyRSA v3 Windows executables ... }
+ │
+ ├── keys
+ │ ├── { Your old EasyRSA v2 PKI ... }
+ │
+ ├── pki
+ │ ├── { Your new EasyRSA v3 PKI ... }
+ │
+ ├── VERY-SAFE-PKI
+ │ ├── { Your old EasyRSA v2 PKI ... backup files }
+ │
+ └── x509-types
+ ├── { EasyRSA v3 x509 definition files ... }
+
+ Common EasyRSA-v3 files:
+ ├── easyrsa
+ ├── openssl-easyrsa.cnf
+ ├── vars
+ └── vars.example
+
+ ```
+
+ ## Fails
+ **Correct the error reported first.**
+
+ Before you can try the update again you MUST remove these two directories:
+
+ * `./easyrsa3/pki`
+ * `./easyrsa3/VERY_SAFE_PKI`
+
+ You **may** also need to remove the newly created vars file at:
+
+ * `./easyrsa3/vars`
+
+ If you find this warning at the top of the ./vars file then it is safe to remove:
+ ```
+ ########################++++++++++#########################
+ ### ###
+ ### WARNING: THIS FILE WAS AUTOMATICALLY GENERATED ###
+ ### ALL SETTINGS ARE AT THE END OF THE FILE ###
+ ### ###
+ ########################++++++++++#########################
+ ```
+
+ ### Incompatible `vars` file
+
+ The the `vars` file in place uses export which Easyrsa3 does not support.
+
+ ### Too many `vars` files #ersa-up23-fails-vars-bat
+
+ There exists a `vars` file and a `vars.bat` file. Only one of these files may exist.
+
+ ### CA certificate does not match `vars`/`vars.bat` file settings
+
+ The current CA details do not match the `vars` file in place.
+
+ ## v30x to v306
+
+ Only one change is required:
+ `pki/index.txt.attr` \\
+ Required: `unique_subject = no`
+
+
+ ## Debian-based distros
+
+ For users of Debian-based distros (Debian, Ubuntu, Mint, Devuan, …):
+
+ EasyRSA can be installed with standard package manager: `apt install easy-rsa`.
+
+ **Do not** use `make-cadir` to create a directory for migration, because it creates a symlink `.easyrsa` to `/usr/share/easy-rsa/easyrsa`, but when you run a function `./easyrsa upgrade`, it will try to create subdirectories in `/usr/share/easy-rsa/`:
+
+ > mkdir: cannot create directory ‘/usr/share/easy-rsa/VERY-SAFE-PKI’: Permission denied
+
+ Follow these steps to perform upgrade from v2 keys structure to v3:
+
+ * create an empty directory for migration, like `mkdir migrate-from-v2-to-v3`,
+ * go into it: `cd migrate-from-v2-to-v3`,
+ * copy old structure, something like: `rsync -a ~/vpn-keys/my-old-keys-v2/ .`,
+ * check the current structure, it should look like described in [#ersa-up23-before Before],
+ * copy the main script and 2 more files needed for upgrade: `cp -pv /usr/share/easy-rsa/{easyrsa,openssl-easyrsa.cnf,vars.example} .`
+ * perform the upgrade: `./easyrsa upgrade pki`,
+ * check the current structure, it should look like in [#ersa-up23-after After],
+ * now you can replace script by a symlink, so following `easy-rsa` package update in future will adjust your `./easyrsa`: `ln -sfv /usr/share/easy-rsa/easyrsa ./easyrsa`.
+
+
+ ## Help
+
+ https://forums.openvpn.net/viewforum.php?f=31
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9