Enable SSL for host factory by using a properly
chained certificate from a trusted certificate authority (CA). SSL communication between the
host factory server and
client enables secure access for the host factory RESTful
APIs.
About this task
SSL communication for host factory follows your SSL
setting for RESTful web servers, which is enabled during installation by default. If you disabled
SSL for web server communication during installation, SSL for host factory is also disabled.
Important: Ensure that you use the same SSL
setting (either enabled or disabled) for the cluster management console, RESTful web
servers, and host factory. You cannot enable SSL for one and
disable SSL for others; without a uniform configuration, errors occur. Note, however, that when SSL
is uniformly enabled, you can use different certificates and keys as required.
When SSL is enabled for your production environment, you must use a properly chained certificate
that is issued or signed by a trusted certificate authority (CA). You can use your own self-signed
certificate or an external certificate. When you have a valid certificate (either self-signed or
external), follow these steps to import your certificate for use with host factory. (For testing, you can
use the built-in self-signed certificate at $EGO_TOP/wlp/usr/shared/resources/security/;
see Enabling SSL for host factory (self-signed certificate)).
Procedure
Follow these steps to enable SSL for host factory with an external
certificate from a trusted CA.
-
Stop the HostFactory service:
egosh service stop HostFactory
-
Specify your certificate file and private key in the hostfactoryconf.json
file at $EGO_ESRVDIR/hostfactory/conf/.
You can define this configuration at the cluster level and retrieve it for host factory, or define it
exclusively for host factory.
- To retrieve cluster-level SSL configuration from the ego.conf file on a
management host that runs the HostFactory service:
- In hostfactoryconf.json, set the HF_REST_TRANSPORT_ARG
parameter to an environment variable. For
example:
"HF_REST_TRANSPORT_ARG": "$EGO_DEFAULT_TS_PARAMS"
- In ego.conf, set the CERTIFICATE and
PRIVATE_KEY subparameters for the EGO_DEFAULT_TS_PARAMS
parameter to the certificate file and private key. Optionally, you can also define the
CIPHER, CAFILE, and SERVER_AUTH
subparameters. For
example:
EGO_DEFAULT_TS_PARAMS: "SSL[CERTIFICATE=/opt/cert.pem,PRIVATE_KEY=/opt/cert.key,CIPHER=ECDHE-ECDSA-AES256-GCM-SHA384,
CAFILE=/opt/cacert.pem,SERVER_AUTH={}]"
- To define SSL parameters separately for host factory, set
HF_REST_TRANSPORT_ARG in hostfactoryconf.json to specify
the certificate file and its private key as subparameters in the following
format:
"HF_REST_TRANSPORT_ARG": "SSL[subparameter, ...]"
where
the subparameters are:
- CERTIFICATE: Path to the certificate file.
- PRIVATE_KEY: Path to the private key file.
The HF_REST_TRANSPORT_ARG parameter uses the same subparameters as
the EGO_DEFAULT_TS_PARAMS parameter in ego.conf.
Optionally, you can also define the CIPHER, CAFILE, and
SERVER_AUTH subparameters.
For
example:
"HF_REST_TRANSPORT_ARG": "SSL[CERTIFICATE=/opt/user.pem,PRIVATE_KEY=/opt/user.key,
CIPHER=ECDHE-ECDSA-AES256-GCM-SHA384,CAFILE=/opt/cacert.pem,SERVER_AUTH={}]"
- Optional:
Set the HF_REST_LISTEN_PORT parameter in
hostfactoryconf.json to specify the listening port for host factory client requests. Valid
value is either 0 or a port number in the range 1024 -
65535. The default SSL port is 9443. If you specify 0 or if the
parameter is not defined, a random port is assigned.
For example:
"HF_REST_LISTEN_PORT": 9443
-
Save your changes to hostfactoryconf.json.
-
Import the host factory CA certificate to the default server keystore (serverKeyStore.jks) on the
primary host. If high availability
is enabled, ensure that you import the host factory CA certificate also on
each primary-candidate host.
-
Start the HostFactory service:
egosh service start HostFactory
Results
You can now access the host factory APIs over SSL with your
own self-signed or production certificate.