How to use the vars file

[TinCanTech]

TLDR version;

#### vars Autodetection

  A 'vars' file is a file named simply `vars` (without an extension) that
  Easy-RSA will source for configuration. This file is specifically designed
  *not* to replace variables that have been set with a higher-priority method
  such as CLI opts or env-vars.

  The following locations are checked, in this order, for a vars file. Only the
  first one found is used:

  1. The file referenced by the `--vars` CLI option
  2. The file referenced by the env-var named `EASYRSA_VARS_FILE`
  3. The directory referenced by the `--pki` CLI option (Recommended)
  4. The directory referenced by the `EASYRSA_PKI` env-var
  5. The directory referenced by the `EASYRSA` env-var
  6. The default PKI directory at `$PWD/pki` (See note below)
  7. The default working directory at `$PWD`

  Defining the env-var `EASYRSA_NO_VARS` will override the sourcing of the vars
  file in all cases, including defining it subsequently as a global option.

  Note: If the vars file `$PWD/pki/vars` is sourced then it is forbidden from
        setting/changing the current PKI, as defined by `EASYRSA_PKI` env-var.

#### Use of `--pki` verses `--vars`

  It is recommended to use option `--pki=DIR` to define your PKI at runtime.
  This method will always auto-load the `vars` file found in defined PKI.

  In a multi-PKI installation, use of `--vars` can potentially lead to
  a vars file that is configured to set a PKI which cannot be verified
  as the expected PKI. Use of `--vars` is not recommended.

See: doc/EasyRSA-Advanced.md

---

EasyRSA uses a hierarchy to select which vars file to use. However, this is approach
can easily lead to using the wrong vars file and subsequent mistakes.

Instead, this hierarchy has been slightly modified.

The default vars file is now ALWAYS ./vars, the current working directory.
If this file exists then it can potentially conflict with other vars files.
If this file does not exist then there are no potential conflicts.

For a single PKI, using default directory ./pki, and the default vars file
./vars, is acceptable.

If a vars file also exists in the PKI then that will conflict with the default.
It is recommended but not required, to move the vars file to the PKI, thus
removing the default ./vars file and the conflict.

For multiple PKIs, it is strongly recommended to use a vars file inside each PKI
and then use easyrsa --pki=DIR to declare which PKI you wish to use. This will
auto-select the correct vars file, inside the declared PKI.
This method can not use vars to accidentally set a different PKI.

If a default ./vars file also exists then it will conflict with the PKI vars file.

After careful consideration, it has been found that the vars file is better suited
to be used inside each PKI, instead of a global, default ./vars file.

However, for a single PKI installation, the vars file location is moot, provided
that there is only one vars file.

---

There is also a new command make-vars, which can be used to create a vars file.
To use make-vars, you must direct the output to the desired location:

./easyrsa make-vars > pki/vars

Redirecting the output means that you can select where you need the vars file.

[TinCanTech]

The systemic cause of this problem can be found here:

easy-rsa/doc/EasyRSA-Advanced.md

Lines 31 to 39 in 060299f

	The following locations are checked, in this order, for a vars file. Only the
	first one found is used:
	1. The file referenced by the `--vars` CLI option
	2. The file referenced by the env-var named `EASYRSA_VARS_FILE`
	3. The directory referenced by the `EASYRSA_PKI` env-var
	4. The default PKI directory at `$PWD/pki`
	4. The directory referenced by the `EASYRSA` env-var
	5. The directory containing the easyrsa program

Specifically:

3. The directory referenced by the EASYRSA_PKI env-var
4. The default PKI directory at $PWD/pki

Unless EASYRSA_PKI is set prior to sourcing vars then it will always be the same as $PWD/pki. When sourcing vars in $PWD/pki, it is possible for the vars file to set EASYRSA_PKI and change the PKI from the expected PKI at $PWD/pki, because EASYRSA_PKI has not been set prior to sourcing vars.

Example:

• A vars file exists in $PWD/pki. By default, it will be sourced.
• In the vars file there is set_var EASYRSA_PKI wrong-pki.
• After sourcing the vars file the PKI will be set to wrong-pki, not the expected pki.

The correct solution is to not allow vars to set the PKI, at all.

However, in a single PKI installation, this does not matter.

For a multi-PKI installation the new version allows a single option --pki=DIR to dictate precisely which vars file and PKI to use.

With one more change, the "conflicting vars file" error can also be removed and fall back to the documented hierarchy ONLY -- But keep the check to ensure that the PKI has not changed unexpectedly.

[TinCanTech]

This has been resoled, see #1015