easyrsa-upgrade - blame None

Blame

2e2eec	Samuli Seppänen	2025-02-28 13:38:20	1	# Upgrading EasyRSA
			2
			3	Note: This wiki is a work in progress.
			4
			5	This page describes the EasyRSA PKI upgrade process:
			6	EasyRSA PKI version 2 to EasyRSA version 3, see below.
			7
			8
			9	## Setup
			10
			11	1. You must install a new copy of EasyRSA v3.0.7 or above
			12	1. Copy your existing EasyRSA version 2 files and directories into `./easyrsa3`
			13	Your `./easyrsa3` directory should now look something like below (in Before section).
			14	1. Linux: run `./easyrsa upgrade pki`
			15	1. Windows: run `easyrsa-start.bat` and then `./easyrsa upgrade pki`
			16	If you have trouble starting EasyRSA-v3, please consult the relevant documentation. \\
			17	Your `./easyrsa3` directory should now look something like below (in After section).
			18
			19	### Examples
			20
			21	* Linux
			22
			23	Your current Easy-RSA Version 2 PKI is located under `/root/easyrsa`
			24	Your new Easy-RSA Version 3 PKI will be located at `/etc/openvpn/easyrsa/pki`
			25
			26	Change directory to `/etc/openvpn/easyrsa`
			27	Test that `easyrsa help` works, if that does not work then test that `./easyrsa help` works.
			28
			29	If you do not have a working copy of the `easyrsa` script then you cannot continue.
			30
			31	Copy `/root/easyrsa` to `/etc/openvpn/easyrsa`
			32
			33	* Windows
			34
			35	Your current Easy-RSA Version 2 PKI is located under `\users\easyrsa`
			36	Your new Easy-RSA Version 3 PKI will be located at `\Program Files\Openvpn\easy-rsa\pki`
			37
			38	Start Easy-RSA `EasyRSA-Start.bat`
			39
			40	Copy `\users\easyrsa` to `/Program Files\Openvpn\easy-rsa`
			41
			42	## Usage
			43
			44	To perform the upgrade:
			45
			46
			47	1. ``` ./easyrsa upgrade pki ```
			48	This will upgrade a version 2 PKI to version 3.
			49	This upgrade will also perform the CA upgrade below.
			50	The CA is set to allow duplicate certificates to allow for for renewal.
			51	The PKI is not changed only copied.
			52
			53	2. ``` ./easyrsa upgrade ca ```
			54	The CA is set to allow duplicate certificates to allow for for renewal.
			55	The PKI is not changed.
			56
			57	To automate this upgrade use `--batch`
			58
			59	## Steps
			60
			61	These CHECKS will be made if you upgrade now:
			62
			63	Before ANY changes are made a test run will be attempted ...
			64
			65	* Verify: new PKI dir does not exist and will not be over written.
			66	* Verify: new backup PKI dir does not exist and will not be over written.
			67	* Verify and Source the current PKI settings: ./vars or ./vars.bat
			68	* Verify the current ca.crt
			69
			70	Then:
			71	* CONFIRM NOW THAT THIS IS THE CORRECT ca.crt and continue or quit
			72
			73	These CHANGES will be made if you continue:
			74
			75	Before ANY changes are made a test run will be attempted ...
			76	* Complete backup of the current PKI to ./VERY-SAFE-PKI
			77	* Create new PKI dirs for use with EasyRSA-3
			78	* Copy required working database files to new PKI
			79	* Copy current PKI to new PKI
			80	* Update the CA to allow duplicates for renewal
			81	* create new openssl-easyrsa.cnf file
			82	* Remove EasyRSA-2 program files
			83	* Build new EasyRSA-3 vars file
			84
			85	### Before
			86
			87	(This list is not completely accurate ... )
			88
			89	```
			90	.
			91	├── bin
			92	│ ├── { EasyRSA v3 Windows executables ... }
			93	│
			94	├── keys
			95	│ ├── { Your current EasyRSA v2 PKI ... }
			96	│
			97	└── x509-types
			98	├── { EasyRSA v3 x509 definition files ... }
			99
			100	Linux EasyRSA-v2 program files:
			101	├── build-ca
			102	├── build-dh
			103	├── build-inter
			104	├── build-key
			105	├── build-key-pass
			106	├── build-ca.bat
			107	├── build-key-pkcs12
			108	├── build-key-server
			109	├── build-req
			110	├── build-req-pass
			111	├── clean-all
			112	├── inherit-inter
			113	├── list-crl
			114	├── make-crl
			115	├── pkitool
			116	├── revoke-crt
			117	├── revoke-full
			118	└── sign-req
			119
			120	Windows EasyRSA-v2 program files:
			121	├── build-ca-pass.bat
			122	├── build-dh.bat
			123	├── build-key.bat
			124	├── build-key-pass.bat
			125	├── build-key-pkcs12.bat
			126	├── build-key-server.bat
			127	├── build-key-server-pass.bat
			128	├── clean-all.bat
			129	├── EasyRSA-Start.bat
			130	├── init-config.bat
			131	├── revoke-full.bat
			132	├── vars.bat
			133	├── vars.bat.sample
			134	└── whichopensslcnf
			135
			136	Common EasyRSA-v2 files:
			137	├── index.txt.start
			138	├── README.txt
			139	└── serial.start
			140
			141	Common EasyRSA-v3 files:
			142	├── easyrsa
			143	├── openssl-easyrsa.cnf
			144	└── vars.example
			145
			146	```
			147
			148	### After
			149
			150	```
			151	.
			152	├── bin
			153	│ ├── { EasyRSA v3 Windows executables ... }
			154	│
			155	├── keys
			156	│ ├── { Your old EasyRSA v2 PKI ... }
			157	│
			158	├── pki
			159	│ ├── { Your new EasyRSA v3 PKI ... }
			160	│
			161	├── VERY-SAFE-PKI
			162	│ ├── { Your old EasyRSA v2 PKI ... backup files }
			163	│
			164	└── x509-types
			165	├── { EasyRSA v3 x509 definition files ... }
			166
			167	Common EasyRSA-v3 files:
			168	├── easyrsa
			169	├── openssl-easyrsa.cnf
			170	├── vars
			171	└── vars.example
			172
			173	```
			174
			175	## Fails
			176	Correct the error reported first.
			177
			178	Before you can try the update again you MUST remove these two directories:
			179
			180	* `./easyrsa3/pki`
			181	* `./easyrsa3/VERY_SAFE_PKI`
			182
			183	You may also need to remove the newly created vars file at:
			184
			185	* `./easyrsa3/vars`
			186
			187	If you find this warning at the top of the ./vars file then it is safe to remove:
			188	```
			189	########################++++++++++#########################
			190	### ###
			191	### WARNING: THIS FILE WAS AUTOMATICALLY GENERATED ###
			192	### ALL SETTINGS ARE AT THE END OF THE FILE ###
			193	### ###
			194	########################++++++++++#########################
			195	```
			196
			197	### Incompatible `vars` file
			198
			199	The the `vars` file in place uses export which Easyrsa3 does not support.
			200
			201	### Too many `vars` files #ersa-up23-fails-vars-bat
			202
			203	There exists a `vars` file and a `vars.bat` file. Only one of these files may exist.
			204
			205	### CA certificate does not match `vars`/`vars.bat` file settings
			206
			207	The current CA details do not match the `vars` file in place.
			208
			209	## v30x to v306
			210
			211	Only one change is required:
			212	`pki/index.txt.attr` \\
			213	Required: `unique_subject = no`
			214
			215
			216	## Debian-based distros
			217
			218	For users of Debian-based distros (Debian, Ubuntu, Mint, Devuan, …):
			219
			220	EasyRSA can be installed with standard package manager: `apt install easy-rsa`.
			221
			222	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/`:
			223
			224	> mkdir: cannot create directory ‘/usr/share/easy-rsa/VERY-SAFE-PKI’: Permission denied
			225
			226	Follow these steps to perform upgrade from v2 keys structure to v3:
			227
			228	* create an empty directory for migration, like `mkdir migrate-from-v2-to-v3`,
			229	* go into it: `cd migrate-from-v2-to-v3`,
			230	* copy old structure, something like: `rsync -a ~/vpn-keys/my-old-keys-v2/ .`,
			231	* check the current structure, it should look like described in [#ersa-up23-before Before],
			232	* copy the main script and 2 more files needed for upgrade: `cp -pv /usr/share/easy-rsa/{easyrsa,openssl-easyrsa.cnf,vars.example} .`
			233	* perform the upgrade: `./easyrsa upgrade pki`,
			234	* check the current structure, it should look like in [#ersa-up23-after After],
			235	* 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`.
			236
			237
			238	## Help
			239
			240	https://forums.openvpn.net/viewforum.php?f=31