Configure the PCE

Before running the PCE, set up its runtime configuration.

Use the PCE Runtime Environment File (runtime_env.yml) to configure the PCE software. By default, the file is located in /etc/illumio-pce/runtime_env.yml. You can create the runtime_env.yml file manually or use the PCE software setup script to create and modify the file using interactive prompts at the command line.

For detailed descriptions of the runtime parameters, see Reference: PCE Runtime Parameters.

Set Configuration File Location

By default, runtime_env.yml is located in /etc/illumio-pce/runtime_env.yml. You can override the default location by setting the ILLUMIO_RUNTIME_ENV environment variable. If you do, you must also set ILLUMIO_RUNTIME_ENV in in the file /etc/sysconfig/illumio-pce to enable the PCE software start-up script to find the file. Log in as root and run the following command (replace location with the actual full path).

root> echo "ILLUMIO_RUNTIME_ENV=location/runtime_env.yml" > /etc/sysconfig/illumio-pce

For example, if the location is /var/lib/illumio/data, run the following command:

root> echo "ILLUMIO_RUNTIME_ENV=/var/lib/illumio/data/runtime_env.yml" > /etc/sysconfig/illumio-pce

Run the PCE Setup Script

From the host command line, as root, run the following command to launch the setup script:

[root]# illumio-pce-env setup

The setup script interactively prompts you to provide values for configuration parameters. For descriptions of all the parameters, see Reference: PCE Runtime Parameters. A few of these values, such as node_type, will not be the same on all nodes of the PCE cluster; however, many of the values will be the same on all the nodes.

When you start the setup script, it checks whether the $ILLUMIO_RUNTIME_ENV environment variable is set.

$ Illumio PCE Runtime Setup (new configuration -> ENV=my_pce.yml):

The ILLUMIO_RUNTIME_ENV variable controls where the runtime file will be stored. When the ILLUMIO_RUNTIME_ENV variable is not set, the setup script alerts you that the configuration is new and displays the default directory for the runtime file: /etc/illumio-pce/runtime_env.yml.

$ Illumio PCE Runtime Setup (new configuration)

General Configuration

The setup script displays descriptive help text followed by a prompt where you can accept the previous value, the default value, or enter a new value. When the field is optional, press Enter to leave the field empty or accept the default value (if one exists). Fields that have default values display # default next to the values.

The prompt shows the previous value in brackets:

node_type [core]:

Press Enter to use the value in brackets.

opts => core [ data0 data1 ] 
node_type [core]: ?

When a field has multiple options, type the first few characters of the option and press Tab to auto-complete the field or suggest choices. When prompted for a directory or filename, using auto-complete can help you quickly populate the field.

Press CTRL+C to escape to a control menu, which provides the following options:

• Quit without saving
• Restart the script (with an optional field value)
• Skip to a future field (with a field value)
• Save (with an optional target file)
• Exit

For example, entering this command saves the configuration to a different file and quits the setup.

$ Type (q)uit, (r)estart, (f)ield, (s)ave to file or default resume: save /tmp/sample.cfg

Command-line Batch or List Mode

To operate the setup script from the command line, use the --batch option. Instead of prompting for each value, it accepts any previous or default values automatically. When the configuration is missing required fields, the script displays an error and returns a non-zero exit code.

To set a value on the command line:

[root]# illumio-pce-env setup front_end_https_port=7443 pce_fqdn="sample.illumio.com" -b

This command sets the values instead of prompting for them. You can also pre-set the values in non-batch mode by using key=value arguments.

To display the currently configured values and replace them with command-line values, use the --list option. The --list option does not prompt for values or save the configuration to the runtime_env.yml file. The --list option is useful to validate your TLS certificate.

Advanced Runtime Environment Parameters

Your Illumio Support Representative might provide advanced parameters to add to your runtime_env.yml file. When you include the name of these parameters on the command line, the setup script prompts for them.

[root]# illumio-pce-env setup advanced_parameter_name_1 advanced_parameter_name_2 ...

Additional Options

When using the setup script, several additional options are available. You can use -h to display these options.

Usage

[root]# illumio-pce-env setup [options...] [field[:field...]=[value[,value...]]...

Display Options

File Options

(Optional) Validate and Configure TLS Certificate

The PCE validates your TLS certificates at start up and displays an error message when the certificate or its chain of trust is invalid.

For information on the contents and formats of your certificates, see TLS Requirements.

You can validate the certificates yourself before or after configuring the PCE as described in Run the PCE Setup Script.

To validate your TLS certificate yourself, including the chain of trust and other aspects, run the following command:

illumio-pce-env setup --list

When the --list option is specified, this command checks your configuration and certificates, and indicates possible problems; it does not create a new runtime_env.yml configuration file.

Validate After Configuring PCE

To validate the certificates you have already configured and saved in the locations defined in the runtime_env.yml file, run the following command:

illumio-pce-env setup --list --test 5

Specify a verbosity level argument—1 (least) to 5 (most)—with the --test option. At verbosity level 5, the command displays the results of its certificate validation.

Alternative Syntax for Certificate Validation

After configuring the PCE, you can validate your certificates in the following additional ways:

• illumio-pce-env setup --list --test 5:some.alternative.hostAndDomainName

  This syntax checks the certificate and chain against the specified some.alternative.hostAndDomainName, such as the FQDN you plan to use for the PCE in production.

• illumio-pce-env setup --list --test 5+

  The + syntax creates a loopback OpenSSL server running on port 4433 and attempts to curl to it.

Validate Before Configuring PCE Certificates

If you have not configured your runtime_env.yml file yet, and want to validate your certificates before copying them to your planned production location, run the following command.

# illumio-pce-env setup --batch --list \
email=required@emailaddress node=value \
cert=/path/to/cert \
pkey=/path/to/private_key \
trust=/path/to/certificate_chain \
--test 5

Messages, Errors, and Warnings

These messages indicate correctly configured certificates:

• Valid: Certificate chain is verified
• Valid: web_service_certificate tests passed.

These error message indicate possible problems with your certificates:

• Warning: group xxx can write to web_service_certificate
• Error: unable to find trusted_ca_bundle yyy
• Warning: trusted_ca_bundle missing or inaccessible.
• Missing CA
• Error: unable to verify certificate chain
• Error: unable to validate web_service_certificate

Install Certificate

Copy the TLS certificate and private key to each nodes in your deployment.

You can store the files in any readable location on the node. The PCE RPM installation creates the /var/lib/illumio-pce/cert directory where you can store these files.

The certificate and private key must be readable by the PCE runtime user.

Verify the PCE Runtime Environment

1. After configuring the runtime_env.yml file, run the environment check command as the PCE runtime user to ensure the node is set up correctly:

   # sudo -u ilo-pce illumio-pce-env check 
   Checking PCE runtime environment.
   OK

   This command checks various aspects of the PCE setup. For example, it verifies that the NTP client is installed, running, and synchronized to a time source.

2. Correct any errors.

3. Proceed to the next task: Start and Initialize the PCE.