...
- The JOC Cockpit certificate authority has to be available and the root private key and certificate have been created.
- Valid security tokens have been generated with JOC Cockpit for the desired Controller and Agent instances.
- For details see JS7 - Certificate Authority - Manage Certificates with JOC Cockpit
Command Line Client
The command line client is available with the Instance Start Script for Unix and Windows
Certificate Rollout
Rollout of certificates includes to perform the following steps
- JOC Cockpit
- The JOC Cockpit certificate authority has to be available and the Root CA private key and certificate have been created.
- Valid security tokens have been generated with JOC Cockpit for the Controller and Agent instances that require a certificate.
for a Controller instance: ./bin/controller_instance.sh|cmd
- For details see JS7 - Controller - Command Line Operation
- for an Agent instance:
./bin/agent_<port>.sh|cmd
Standard Arguments
The following arguments are used independently from an HTTP or HTTPS connection to JOC Cockpit:
- Controller/Agent Instance
- Both components include the Certificate Rollout Client that is available from the Controller/Agent Instance Start Script.
- The Certificate Rollout Client connects to JOC Cockpit. Authentication is performed by use of the one-time security token generated with the previous step.
- The JOC Cockpit certificate authority is requested to create a private key and server/client certificate for the specified host. Private key and certificate are created on-the-fly and are returned to the Certificate Rollout Client. In addition, JOC Cockpit stores the certificate with its database. The Certificate Rollout Client
- stores the private key in a keystore file,
- stores the server/client certificate in a truststore file,
- updates the configuration in the
./config/private/private.conf
file.
Certificate Rollout Client
The Controller/Agent Instance Start Script for Unix and Windows includes the Certificate Rollout Client and is available from the following locations:
- for a Controller instance:
./bin/controller_instance.sh|cmd
- for an Agent instance:
./bin/agent_<port>.sh|cmd
Standard Arguments
The following arguments are used independently from an HTTP or HTTPS connection to JOC Cockpit:
Expand |
---|
title | List of Standard Arguments |
---|
|
Argument | Required | Description | Example |
---|
--joc-uri | Yes | URI of the JOC Cockpit instance from which to receive the private key and certificate. | --joc-uri=http://myhost.example.com:4446 | --token | Yes | UUID of the security token for one-time authentication with JOC Cockpit. | --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b | --dn-only | No | Flag to receive relevant Distinguished Names (DN) to update the private.conf file, without generating certificates. | --dn-only | --subject-dn | Yes | The subject of the requested certificate includes the Distinguished Name (DN) consisting of CN, OU, O, L, S, C attributes. The hostname of the requesting client is specified as CN. | --subject-dn="CN=myhost, OU=IT Operations, O=SOS, L=Berlin, S=Berlin, C=DE" | --san | Yes | The Subject Alternative Name (SAN) specifies the hostname of the requesting client and optionally variations of the hostname, e.g. the domain part (FQDN). Alternative hostnames are separated by comma. | --san="myhost, myhost.example.com" | --key-alias | Yes | Alias name used when storing the requested private key and certificate to the target keystore. | --key-alias="MyKeyAlias" | --ca-alias | Yes | Alias name used when storing the requested CA certificate in both, the target keystore and truststore. | --ca-alias="MyTrustedCertificateAlias" |
|
|
|
| --target-keystore | Yes | Path to the keystore to which the requested private key and |
|
Expand |
---|
title | List of Standard Arguments |
---|
|
Argument | Required | Description | Example |
---|
--joc-uri | Yes | URI of the JOC Cockpit instance from which to receive the private key and certificate. | --joc-uri=http://myhost.example.com:4446 | --token | Yes | UUID of the security token for one-time authentication with JOC Cockpit. | --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b | --dn-only | No | Flag to receive relevant Distinguished Names (DN) to update the private.conf file, without generating certificates. | --dn-only | --subject-dn | Yes | The subject of the requested certificate includes the Distinguished Name (DN) consisting of CN, OU, O, L, S, C attributes. The hostname of the requesting client is specified as CN. | --subject-dn="CN=myhost, OU=IT Operations, O=SOS, L=Berlin, S=Berlin, C=DE" | --san | Yes | The Subject Alternative Name (SAN) specifies the hostname of the requesting client and optionally variations of the hostname, e.g. the domain part (FQDN). Alternative hostnames are separated by comma. | --san="myhost, myhost.example.com" | --key-alias | Yes | Alias name used when storing the requested private key and certificate to the target keystore. | --key-alias="MyKeyAlias" | --ca-alias | Yes | Alias name used when storing the requested CA certificate in both, the target keystore and truststore. | --ca-alias="MyTrustedCertificateAlias" | --target-keystore | Yes | Path to the keystore to which the requested private key and certificate should be stored. | --target-keystore=/var/sos-berlin.com/js7/controller/var/config/private/https-keystore.p12 | --target-keystore-type | No | Type of the keystore used. Supported values include: PKCS12 (default),
JKS (deprecated). | --target-keystore-type=PKCS12 | --target-keystore-pass | No | Password for access to the keystore. | --target-keystore-pass="YourKeystorePassword" | --target-keystore-entry-pass | No | Password for the requested private key that should be added to the keystore. | --target-keystore-entry-pass="YourKeystoreEntryPassword" | --target-truststore | Yes | Path to the truststore to which the trusted CA certificate should be stored. | --target- | truststorekeystore=/var/sos-berlin.com/js7/controller/var/config/private/https- | truststorekeystore.p12 | --target- | truststorekeystore-type | No | Type of the | truststore keystore used. Supported values include: PKCS12 (default),
JKS (deprecated). | --target- | truststorekeystore-type=PKCS12 | --target- | truststorekeystore-pass | No | Password for access to the | truststorekeystore. | --target- | truststorekeystore-pass=" | YourTruststorePasswordYourKeystorePassword" | -- | helptarget-keystore-entry-pass | No | Displays usage information, this option has to be specified as the only command line option and has no value. |
Explanation: |
Arguments for use with JOC Cockpit HTTPS Connections
The following arguments are used in addition to standard arguments in case that JOC Cockpit is set up for HTTPS connections:
Password for the requested private key that should be added to the keystore. | --target-keystore-entry-pass="YourKeystoreEntryPassword" |
|
|
|
| --target-truststore | Yes | Path to the truststore to which the trusted CA certificate should be stored. | --target-truststore=/var/sos-berlin.com/js7/controller/var/config/private/https-truststore.p12 | --target-truststore-type | No | Type of the truststore used. Supported values include: PKCS12 (default),
JKS (deprecated). | --target-truststore-type=PKCS12 | --target-truststore-pass | No | Password for access to the truststore. | --target-truststore-pass=" YourTruststorePassword"
| --help | No | Displays usage information, this option has to be specified as the only command line option and has no value. |
|
Explanation: |
Arguments for use with JOC Cockpit HTTPS Connections
The following arguments are used in addition to standard arguments in case that JOC Cockpit is set up for HTTPS connections:
Expand |
---|
title | List of Arguments for use with JOC Cockpit HTTPS Connections |
---|
|
Argument | Required | Description | Example |
---|
--source-truststore | No | Path to the truststore holding the trusted certificate(s) to connect to JOC Cockpit by HTTPS. | --source-truststore=/home/sos/public/js7-truststore.p12 | --source-truststore-type | No | Type of the truststore used. Supported values include: PKCS12 (default),
JKS (deprecated). | --source-truststore-type=PKCS12 | --source-truststore-pass | No | Password for access to the truststore. | --source-truststore-pass="YourTruststorePassword" | --source-certificate | No | Path to a certificate file holding |
|
Expand |
---|
title | List of Arguments for use with JOC Cockpit HTTPS Connections |
---|
|
|
Argument | Required | Description | Example |
---|
--source-truststore | No | Path to the truststore holding the trusted certificate(s) to connect to JOC Cockpit by HTTPS. | --source-truststore=/home/sos/public/js7-truststore.p12 |
--source-truststore-type | No | Type of the truststore used. Supported values include: PKCS12 (default),
JKS (deprecated). | --source-truststore-type=PKCS12 |
--source-truststore-pass | No | Password for access to the truststore. | --source-truststore-pass="YourTruststorePassword" |
--source-certificate | No | Path to a certificate file holding the JOC Cockpit server authentication certificate. | --source-certificate=/home/sos/public/js7-joc-cockpit.crt |
--source-ca-cert | No | Path to the CA certificate file(s) that are used to verify the JOC Cockpit server authentication certificate. A number of paths can be specified, separated by comma. | --source-ca-cert="/home/sos/public/intermediate_ca.crt, /home/sos/public/root_ca.crt" |
Explanation:
An HTTPS connection to JOC Cockpit requires to verify the JOC Cockpit server authentication certificate.The --source-truststore-*
arguments are used to specify a truststore that holds the root CA certificate and optionally any intermediate CA certificates involved in signing the JOC Cockpit server authentication certificate. |
The and =/home/sos/public/js7-joc-cockpit.crt |
--source-ca-cert |
arguments are used as an alternative to | No | Path to the CA certificate file(s) that are used to verify the JOC Cockpit server authentication certificate. A number of paths can be specified, separated by comma. | --source- |
truststore-* arguments in case that JOC Cockpit server authentication certificates are available from individual files instead of being available from a common truststore. Supported certificate formats include PEM.
Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication
The following arguments are used in addition to HTTPS connection arguments in case that JOC Cockpit is setup for JOC Cockpit - HTTPS Mutual Authentication.
ca-cert="/home/sos/public/intermediate_ca.crt, /home/sos/public/root_ca.crt" |
Explanation: |
Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication
The following arguments are used in addition to HTTPS connection arguments in case that JOC Cockpit is setup for JOC Cockpit - HTTPS Mutual Authentication.
Expand |
---|
title | List of Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication |
---|
|
Argument | Required | Description | Example |
---|
--source-keystore | No | Path of the keystore holding the client's private key and certificate |
|
Expand |
---|
title | List of Arguments for use with JOC Cockpit HTTPS Connections using Mutual Authentication |
---|
|
Argument | Required | Description | Example |
---|
--source-keystore | No | Path of the keystore holding the client's private key and certificate for client authentication. | --source-keystore=/home/sos/private/js7-keystore.p12 | --source-keystore-type | No | Type of keystore used. Supported values include: PKCS12 (default),
JKS (deprecated). | --source-keystore-type=PKCS12 | --source-keystore-pass | No | Password for access to the keystore holding the private key for client authentication. | --source-keystore | -pass="YourKeystorePassword"=/home/sos/private/js7-keystore.p12 | --source-keystore-entry-passtype | No | Password for the private key entry in the keystoreType of keystore used. Supported values include: PKCS12 (default),
JKS (deprecated). | --source-keystore- entry-pass="YourKeystoreEntryPassword"type=PKCS12 | --source-privatekeystore-keypass | No | Path to Password for access to the keystore holding the private key file holding the client for client authentication private key. | --source- privatekeystore- key=/home/sos/private/client.key |
Explanation: An HTTPS connection to JOC Cockpit with mutual authentication requires- to verify the JOC Cockpit server authentication certificate by the requesting client and
- to verify the client authentication certificate of the requesting client by JOC Cockpit.
The arguments are used to specify a keystore that holds the client's private key and certificate for client authentication.The pass="YourKeystorePassword" | --source-keystore-entry-pass | No | Password for the private key entry in the keystore. | --source-keystore |
-*-entry-pass="YourKeystoreEntryPassword" |
argument is used as an alternative to key key | No | Path to the private key file holding the client authentication private key. |
keystore-* arguments in case that the private key is available from an individual file instead of a keystore. |
Examples
Example for use with an HTTP Connection to JOC Cockpit
Code Block |
---|
language | bash |
---|
title | HTTP Connection to JOC Cockpit |
---|
collapse | true |
---|
|
./bin/controller_instance.sh cert \
--token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \
--joc-uri=http://somehost.example.com:4446 \
--san="myhost.example.com, myhost" \
--subject-dn="CN=myhost, OU=IT Operations, O=SOS, C=DE, L=Berlin, ST=Berlin" \
--key-alias=myhost \
--ca-alias="Root CA" \
--target-keystore=/var/sos-berlin.com/js7/controller/var/config/private/https-keystore.p12 \
--target-keystore-pass=jobscheduler \
--target-keystore-entry-pass=jobscheduler \
--target-truststore=/var/sos-berlin.com/js7/controller/var/config/private/https-truststore.p12 \
--target-truststore-pass=jobscheduler |
Explanation:
...
private-key=/home/sos/private/client.key |
Explanation: |
Examples
Example for use with the Controller/Agent Instance Start Script and default values
Code Block |
---|
language | bash |
---|
title | with instance startscript and default values |
---|
|
# use with a Controller instance
./bin/controller_instance.sh cert --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446
# use with an Agent instance
./bin/agent_<port>.sh cert --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446 |
Explanation:
- the
cert
argument for the Instance Start Script to build the Java classpath and to start the Java executable. - The
--token
argument specifies the one-time token to connect to JOC Cockpit. - The
--joc-uri
argument specifies the URL for JOC Cockpit. - If no additional arguments are used then the Command Line Client determines default values for the Keystore and Truststore from the instances'
./config/private/private.conf
configuration, including defaults for the DN and for the SAN of the certificate.
Example for use with the Controller/Agent Instance Start Script to update relevant DN entries
Code Block |
---|
language | bash |
---|
title | HTTPS Connection to JOC Cockpit with Mutual Authentication from a Client Truststore |
---|
collapse | true |
---|
| with instance startscript and default values |
---|
|
# use with a Controller instance
./bin/controller_instance.sh cert \
--dn-only --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \
---joc-uri=https://somehostmyhost.example.com:4446 \
# use with an Agent instance
./bin/agent_<port>.sh cert --dn-only --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446 |
Explanation:
- With the
--dn-only
argument only relevant Distinguished Names (DNs) will be updated to the ./config/private/private.conf
configuration file.
Example for use with an HTTP Connection to JOC Cockpit
Code Block |
---|
language | bash |
---|
title | HTTP Connection to JOC Cockpit |
---|
collapse | true |
---|
|
./bin/controller_instance.sh cert \
--token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --san="myhost.example.com, myhost" \
--subject-dn="CN=myhost, OU=IT Operations, O=SOS, C=DE, L=Berlin, ST=Berlin" \
--key-alias=myhost \
--ca-alias="Root CA" \
--source-keystore=/home/sos/private/js7-keystore.p12 \
--source-keystore-pass="" \
--source-keystore-entry-pass="" \
--source-truststore=/home/sos/private/js7-truststore.p12joc-uri=http://somehost.example.com:4446 \
--source-truststore-passsan="myhost.example.com, myhost" \
--targetsubject-keystore=/var/sos-berlin.com/js7/controller/var/config/private/https-keystore.p12 \
--target-keystore-pass=jobscheduler \
dn="CN=myhost, OU=IT Operations, O=SOS, C=DE, L=Berlin, ST=Berlin" \
--target-keystore-entry-pass=jobschedulerkey-alias=myhost \
--ca-alias="Root CA" \
--target-truststorekeystore=/var/sos-berlin.com/js7/controller/var/config/private/https-truststorekeystore.p12 \
--target-keystore-pass=jobscheduler \
--target-keystore-truststoreentry-pass=jobscheduler |
Explanation:
...
\
--target-truststore=/var/sos-berlin.com/js7/controller/var/config/private/https-truststore.p12 \
--target-truststore-pass=jobscheduler |
Explanation:
Example for use with an HTTPS Connection to JOC Cockpit and Mutual Authentication from a Client
...
Truststore
Code Block |
---|
language | bash |
---|
title | HTTPS Connection to JOC Cockpit with Mutual Authentication from a Client Key FileTruststore |
---|
collapse | true |
---|
|
./bin/controller_instance.sh cert \
--token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \
--joc-uri=https://myhostsomehost.example.com:4446 \
--san="myhost.example.com, myhost" \
--subject-dn="CN=myhost, OU=IT Operations, O=SOS, C=DE, L=Berlin, ST=Berlin" \
--key-alias=myhost \
--ca-alias="Root CA" \
--source-private-keykeystore=/home/sos/private/myhostjs7-keystore.keyp12 \
--source-keystore-certificate=/home/sos/public/myhost.pempass="" \
--source-keystore-caentry-certpass="/home/sos/public/intermediate_ca.pem, /home/sos/public/root_ca.pem" \
--targetsource-keystore=truststore=/home/sos/private/js7-truststore.p12 \
--source-truststore-pass="" \
--target-keystore=/var/sos-berlin.com/js7/controller/var/config/private/https-keystore.p12 \
--target-keystore-pass=jobscheduler \
--target-keystore-entry-pass=jobscheduler \
--target-truststore=/var/sos-berlin.com/js7/controller/var/config/private/https-truststore.p12 \
--target-truststore-pass=jobscheduler |
Explanation:
Example for use with an HTTPS Connection to JOC Cockpit and Mutual Authentication from a Client Key File
Code Block |
---|
language | bash |
---|
title | HTTPS Connection to JOC Cockpit with Mutual Authentication from a Client Key File |
---|
collapse | true |
---|
|
./bin/controller_instance.sh cert/private/https-keystore.p12 \
--target-keystore-pass=jobscheduler \
--target-keystore-entry-pass=jobschedulertoken=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b \
--targetjoc-truststore=var/sos-berlin.com/js7/controller/var/config/private/https-truststore.p12uri=https://myhost.example.com:4446 \
--target-truststore-pass=jobscheduler |
Explanation:
Example for use with the Controller/Agent Instance Start Script and default values
Code Block |
---|
language | bash |
---|
title | with instance startscript and default values |
---|
|
# use with a Controller instance
./bin/controller_instance.sh cert --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446
# use with an Agent instance
./bin/agent_<port>.sh cert --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446 |
Explanation:
- the
cert
argument for the Instance Start Script to build the Java classpath and to start the Java executable. - The
--token
argument specifies the one-time token to connect to JOC Cockpit. - The
--joc-uri
argument specifies the URL for JOC Cockpit. - If no additional arguments are used then the Command Line Client determines default values for the Keystore and Truststore from the instances'
./config/private/private.conf
configuration, including defaults for the DN and for the SAN of the certificate.
Example for use with the Controller/Agent Instance Start Script to update relevant DN entries
Code Block |
---|
language | bash |
---|
title | with instance startscript and default values |
---|
|
# use with a Controller instance
./bin/controller_instance.sh cert --dn-only --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446
# use with an Agent instance
./bin/agent_<port>.sh cert --dn-only --token=73bfc4b8-3f15-44b9-a75b-cdb44aec8f4b --joc-uri=https://myhost.example.com:4446 |
Explanation:
san="myhost.example.com, myhost" \
--subject-dn="CN=myhost, OU=IT Operations, O=SOS, C=DE, L=Berlin, ST=Berlin" \
--key-alias=myhost \
--ca-alias="Root CA" \
--source-private-key=/home/sos/private/myhost.key \
--source-certificate=/home/sos/public/myhost.pem \
--source-ca-cert="/home/sos/public/intermediate_ca.pem, /home/sos/public/root_ca.pem" \
--target-keystore=var/sos-berlin.com/js7/controller/var/config/private/https-keystore.p12 \
--target-keystore-pass=jobscheduler \
--target-keystore-entry-pass=jobscheduler \
--target-truststore=var/sos-berlin.com/js7/controller/var/config/private/https-truststore.p12 \
--target-truststore-pass=jobscheduler |
Explanation:
- tbdWith the
--dn-only
argument only relevant Distinguished Names (DNs) will be updated to the ./config/private/private.conf
configuration file.