Enabling security with the security tool

Use the security tool (ssltool.py) to enable security for the cluster management console (webgui), RESTful APIs (rest), or Elastic Stack (elk-*) in your cluster.

Enabling security involves generating TLS certificates to encrypt information, and then configuring components to use those certificates for security. The security tool provides both of these functions:

Certificate generation

First, the security tool generates server certificates, which start from a root certificate:

If you provide a root certificate, the security tool generates the server certificates signed by the provided root.
If you do not provide a certificate, the security tool first generates a self-signed root certificate, and then generates server certificates signed by that root.

Security configuration

After the tool generates the server certificates, it automatically configures security using these certificates.

The security tool uses parameters from the ssltool.conf file to configure security. It uses the defaults set in that file, or any modifications you may have made to the defaults.

Before you begin

Python 2.7.5 or higher must be installed on your hosts.
You must be a cluster administrator to run ssltool.py.
To use the SSL tool, ensure that you include the JRE bin directory in your operating system PATH; for example:
```
export PATH=$EGO_TOP/jre/4.0/operating_system_type/bin:$PATH
```

About this task

The ssltool.py tool is supported on Linux® and Linux for POWER® hosts and is located at $EGO_TOP/4.0/scripts/ssltool/. This directory also contains a README.txt file for detailed usage information.

To learn about enabling security between system daemons or components, see IBM Spectrum Symphony and Transport Layer Security (TLS).

Procedure

Stop the services for the components you want to enable security:
```
egosh service stop all|service_name
```
For example:
- To stop services for all components:
```
egosh service stop all
```
- To stop services for a specific component, specify the service name. For example, to stop the webgui service:
```
egosh service stop WEBGUI
```
- To stop services for multiple components, list the service names, separating each with a space. For example, to stop the webgui, rest, and Explorer reports services (which requires also stopping the Elastic Stack services (elk-*):
```
egosh service stop WEBGUI REST elk-manager elk-elasticsearch elk-elasticsearch-master elk-elasticsearch-data
```
Access the $EGO_TOP/4.0/scripts/ssltool/ directory to run the ssltool.py tool.
Optional: If you do not have security-related files (certificates and keystores), generate them using the genss option:
```
python ./ssltool.py genss
```
The genss option is a convenient method of generating the files, as it uses the parameters and values configured in the ssltool.conf file. It uses the default values, or any modifications you may have made to the defaults.
Tip: The default values for passwords are commented out in the ssltool.conf file, so you will be prompted for passwords at run time. You can passwords (either as plain text, or AES encrypted) to the file, to avoid being prompted to enter passwords when running the security tool.
Back up components for which you want to enable security, using the config backup option:
```
python ./ssltool.py config backup conductor|component_name
```
where component_name is the component to which you want to configure security. You can use the security tool to configure these components:

webgui

Configures a certificate for the cluster management console. For the corresponding manual steps, see Enabling security for the cluster management console using a self-signed certificate.

rest

Configures a certificate for RESTful APIs. For the corresponding manual steps, see Enabling security for the RESTful APIs using a self-signed certificate.

elk

Configures a certificate for Elastic Stack. For the corresponding manual steps, see Enabling security for the Elastic Stack using a self-signed certificate.
For example:
- To back up a specific component, specify the component name. Valid components are in the aforementioned list. For example, to back up the rest component:
```
python ./ssltool.py config backup rest
```
- To back up multiple components or all of them, list the components, separating each with a space. Valid components are in the aforementioned list. For example, to back up the webgui, rest, and elk components):
```
python ./ssltool.py config backup webgui rest elk
```
Configure security for the components, using the config option:
```
python ./ssltool.py config component_nanme
```
where component_name is the component to which you want to configure security and will be the same component specified in step 4.

For example:
- To configure a specific component for security, specify the component name. For example, to configure the rest component:
```
python ./ssltool.py config rest
```
- To configure multiple components for security or all of them, list the components, separating each with a space. For example, to back up the webgui, rest, and elk components):
```
python ./ssltool.py config webgui rest elk
```
Start the services for the components, to make your configuration take effect:
```
egosh service start all|service_name
```
For example:
- To start services for all components:
```
egosh service start all
```
- To start services for a specific component, specify the service name. For example, to start the webgui service:
```
egosh service start WEBGUI
```
- To start services for multiple components, list the service names, separating each with a space. For example, to start the webgui, rest, and Explorer reports services (which requires also starting the Elastic Stack services (elk-*):
```
egosh service start WEBGUI REST elk-manager elk-elasticsearch elk-elasticsearch-master elk-elasticsearch-data
```