Page History
Table of Contents |
---|
Introduction
This article explains configuration items available for Standalone Controllers and Controller instances in a JS7 - Controller Cluster.
- Controllers make use of two configuration files:
- the general configuration file
controller.conf
that is available at the following locations:- Windows:
C:\ProgramData\sos-berlin.com\js7\controller\var\config\controller.conf
- Unix
/var/sos-berlin.com/js7/controller/var/config/controller.conf
- Windows:
- the security configuration from
private.conf
that is available at the following locations:- Windows:
C:\ProgramData\sos-berlin.com\js7\controller\var\config\private.conf
- Unix:
/var/sos-berlin.com/js7/controller/var/config/private/private.conf
- Windows:
- The configuration format makes use of Typesafe Config, see JS7 - Configuration Format
- Controller instances have to be restarted in order to apply changes to the configuration files.
- the general configuration file
- For HTTPS configuration please refer to the JS7 - Configuration Templates article.
...
- using HTTPS connections which are secured by private keys and certificates,
- using authentication between JS7 products:
- Option 1 (recommended):
- applying TLS mutual authentication between JOC Cockpit and Controller as well as between Controller and Agents,
- applying TLS mutual authentication between Director Agent Controller instances and Subagents in an Agent ClusterAgents.
- Option 2:
- applying password authentication between JS7 products should mutual authentication not be in place.
- Option 1 (recommended):
Find examples of private.conf
files for Controller configuration configuration for download:
- Standalone Controller
- Standalone Controller: private.conf-example-standalone-controller
- Controller Cluster
- Primary Controller instance: private.conf-example-primary-controller
- Secondary Controller instance: private.conf-example-secondary-controller
...
History
- Settings in this section are used for the History Service of JOC Cockpit instances that access the given Controller.
distinguished-names
- Specifies the distinguished name as given with the subject of the Client Authentication Certificate for incoming HTTPS connections of JOC Cockpit instances.
- Any number of distinguished names can be specified allowing a number of incoming HTTPS connections from different JOC Cockpit instances.
- Except for whitespace between attributes the precise sequence and values as available from the certificate's subject has to match this property value.
- Note that the common name (CN) element in the distinguished name has to match the fully qualified domain name (FQDN) of a JOC Cockpit instance's host.
The following command can be used to read the distinguished name from a certificate file:
Code Block title Example for OpenSSL command to read a certificate's distinguished name # read distinguished name from the JOC Cockpit instance's certificate file (.crt) openssl x509 -in joc-primary.crt -noout -nameopt RFC2253 -subject # output is returned with a prefix "subject= " or similar that is not part of the distinguished name # subject= DNQ=SOS CA,CN=joc-2-0-primary,OU=IT,O=SOS,L=Berlin,ST=Berlin,C=DE
password
- A default password is specified with the section joc of the JS7 - Settings page of JOC Cockpit and in the
private.conf
file. Thepassword
is used for authentication of theHistory
service account with the Controller, for details see next chapter about password authentication. - The password setting cannot be omitted, however, an empty password can be specified like this:
password="plain:"
- At the same time the password setting in JOC Cockpit has to be assigned an empty value.
- A default password is specified with the section joc of the JS7 - Settings page of JOC Cockpit and in the
JOC
- Settings in this section are used for services running in JOC Cockpit instances that access the given Controller.
distinguished-names
: The same applies as for theHistory
setting described above.permissions
: JOC Cockpit requires theUpdateItem
permission to enable users to deploy objects such as workflows.password
: The same applies as for theHistory
setting described above.
Password Authentication
Anchor | ||
---|---|---|
|
...
|
...
|
No settings are required when using mutual authentication with Agents.
Consider the below chapter HTTPS Keystore and Truststore Access for explanations:
- The Controller instance's keystore has to hold the Client Authentication private key and certificate.
- The Controller instance's truststore has to hold the Root CA Certificate used when signing the Agent's Server Authentication Certificate.
Password Authentication
Anchor | ||||
---|---|---|---|---|
|
Code Block | ||||
---|---|---|---|---|
| ||||
Code Block | ||||
| ||||
js7 { auth { # User accounts for https connections users { # History account of JOC Cockpit (used to release events) History { # for use with password authentication (default password stored with JOC Cockpit Settings) password="sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08" } # JOC account of JOC Cockpit (requires UpdateItem permission for deployment) JOC { # for use with password authentication (default password stored with JOC Cockpit Settings) password="sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE" permissions=[ UpdateItem ] } } } } |
...
History
- Settings in this section are used for the History Service of JOC Cockpit instances that access the given Controller.
JOC
- Settings in this section are used for services running in JOC Cockpit instances that access the given Controller.
permissions
: JOC Cockpit requires theUpdateItem
permission to enable users to deploy objects such as workflows.
- The
password
is used for authentication of theHistory
andJOC
service accounts with the Controller. Both accounts are typically running in the same JOC Cockpit instance.- If HTTP connections are used then the password is the only means for authentication.
- The password is specified with the section joc of the JS7 - Settings page of JOC Cockpit and in the
private.conf
file.- User Input to the Settings page of JOC Cockpit can look like this:
Input to the GUI simply accepts the password and does not require to use the prefixessha512:
orplain:.
- In the
private.conf
file a hashed value or a plain text value can be specified like this:password="sha512:B793649879D6..."
password="plain:JS7-History"
- User Input to the Settings page of JOC Cockpit can look like this:
- If the password is modified in the
private.conf
file then it also has to be modified in the JOC Cockpit settings too in order to make passwords match. - The password setting cannot be omitted, however, an empty password can be specified, for example with mutual authentication HTTPS connections, like this:
password="plain:"
- From the
private.conf
file that ships by default the plain text value and the hashed values are:- History:
- Plain Text:
JS7-History
- Hash:
sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08
- Plain Text:
- JOC:
- Plain Text:
JS7-JOC
Hash:sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE
- Hash:
sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE
- Plain Text:
- History:
- There are a number of ways to create sha512 hash values from passwords.
- One possible solution includes using:
echo -n "JS7-JOC" | openssl dgst -sha512
Anchor | ||||
---|---|---|---|---|
|
Code Block | ||||
---|---|---|---|---|
| ||||
js7 {
auth {
# Controller ID for connections by primary/secondary Controller instance
agents {
agent-001="plain:secret-agent-001"
agent-002="plain:secret-agent-002"
agent-003="plain:secret-agent-003"
}
}
} |
Explanation:
- The Agent ID for each Agent is specified from the examples
agent-001
,agent-002
etc. An Agent is assigned a unique Agent ID during initial operation with JOC Cockpit. The Agent ID cannot be changed unless an Agent's journal is dropped. - A plain text password is specified that is preceded with
plain:
. Passwords should be quoted.
Controller Cluster Configuration
...
Explanation:
- Note that the
Controller
element element name is an example that has to be replaced by the Controller ID which is specified with the identical values during installation of both the Controller instances in a cluster. - The
distinguished-names
setting indicates the subject of the pairing Controller's Client Authentication certificate. The certificate and subject authenticate the pairing Controller without use of passwords.- Note that the
private.conf
file of a Primary Controller instance holds the distinguished name of the Secondary Controller instances' certificate and vice versa. - Except for whitespace between attributes the precise sequence and values as available from the certificate's subject have to match this property value.
- Note that the common name (CN) element in the distinguished name has to match the fully qualified domain name (FQDN) of a Controller instance's host.
The following command can be used to read the distinguished name from a certificate file:
Code Block title Example for OpenSSL command to read a certificate's distinguished name # read distinguished name from the pairing Controller instance's certificate file (.crt) openssl x509 -in controller-secondary.crt -noout -nameopt RFC2253 -subject # output is returned with a prefix "subject= " or similar that is not part of the distinguished name # subject= DNQ=SOS CA,CN=controller-2-0-secondary,OU=IT,O=SOS,L=Berlin,ST=Berlin,C=DE
- Note that the
...
Code Block | ||||
---|---|---|---|---|
| ||||
js7 { auth { # User accounts for https connections users { # Controller ID for connections by primary/secondary Controller instance Controller { password = "plain:secret" } } } } } |
Explanation:
}
} |
Explanation:
- Note that the
Controller
element name is an example that has to be replaced by the Controller ID which is specified with identical values during installation of both Controller instances in a cluster. - If the password is modified in the
private.conf
file of a Primary Controller instance then it also has to be modified for the Secondary Controller instance to make passwords match. - A plain-text password has to be specified that is preceded with
plain:
: Passwords should be quotedThis setting applies to the use of a Controller Cluster.
JOC Cockpit Connections
The configuration is the same as for a Standalone Controller, see JOC Cockpit Connections.
...
js7 | auth | users | |||
---|---|---|---|---|---|
<controller-id> | |||||
distinguished-names | <distinguished-name>[,<distinguished-name>] | ||||
password | plain:<password> | ||||
History | |||||
distinguished-names | <distinguished-name>[,<distinguished-name>] | ||||
password | plain:<password>|sha512:<password-hash> | ||||
JOC | |||||
distinguished-names | <distinguished-name>[,<distinguished-name>] | ||||
password | plain:<password>|sha512:<password-hash> | ||||
permissions | UpdateItem |
...