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

----

This page describes the EasyRSA PKI upgrade process:
  EasyRSA version 2 to EasyRSA version 3, see below. \\
  [#ersa-up33 EasyRSA version <3.0.6 to EasyRSA version >3.0.6]

[[TOC(notitle, inline)]]

----

== 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
 * create new openssl-easyrsa.cnf file
 * Remove EasyRSA-2 program files
 * Build new EasyRSA-3 vars file


== Setup #ersa-up23-setup

 1. You must install a new copy of EasyRSA v3.0.7 or above
 1. Copy your existing EasyRSA v2 files and directories into `./easyrsa3` \\
    Your `./easyrsa3` directory should now look ''something'' like [#ersa-up23-before Before] below:
 1. Linux: run `./easyrsa`
 1. Windows: run `easyrsa-start.bat` and then `./easyrsa` \\
    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:

=== 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   ###
  ###                                                     ###
  ########################++++++++++#########################
 }}}

=== CA certificate does not match vars 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`

== Help #ersa-up23-help

Help: 
  #easyrsa at freenode IRC. \\
  https://forums.openvpn.net/viewforum.php?f=31