= **Upgrading EasyRSA** #ersa-up23-top

----

**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. \\
  [#ersa-up33 EasyRSA CA version <3.0.6 to EasyRSA version >3.0.6]

[[TOC(notitle, inline)]]

----

== Setup #ersa-up23-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 [#ersa-up23-before Before] below:
 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 [#ersa-up23-after After] below:

=== 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 #ersa-up23-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 #ersa-up23-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 #ersa-up23-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 #ersa-up23-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 #ersa-up23-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 #ersa-up23-fails-bad-vars

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 #ersa-up23-fails-ca-vars

The current CA details do not match the `vars` file in place.

== v30x to v306 #ersa-up33

Only one change is required:
  `pki/index.txt.attr` \\
  Required: `unique_subject = no`


== Debian-based distros #ersa-up23-debian

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 #ersa-up23-help

  https://forums.openvpn.net/viewforum.php?f=31