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
- 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
- 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.
- For HTTPS configuration please refer to the JS7 - Configuration Templates article.
...
Code Block |
---|
language | text |
---|
title | Default configuration: enable HTTP communication |
---|
linenumbers | true |
---|
|
# Allow HTTP connections without authentication
js7.web.server.auth.public = true |
js7 | web | server |
|
|
|
---|
|
|
| auth | public | <true>true |<false> false |
- This setting specifies public access to a Controller if incoming HTTP connections are to be used. If used with a value
true
then authentication is not applied. - Default:
false
true
Anchor |
---|
| js7-journal-cluster |
---|
| js7-journal-cluster |
---|
|
Controller Cluster Configuration
...
- A Secondary Controller instance specifies this setting to indicate that this instance starts as a standby node (Backup). When this setting is not in place, both instances of a Controller Cluster will start as standalone instances.
- This setting is relevant for initial operation only. It is independent of which Controller instance later on will be the active one and which instance will be the standby one.
- This setting has to be added by the user before starting a Secondary Controller.
...
js7 | journal | cluster |
|
|
|
---|
|
|
| node |
|
|
|
|
|
| Primary | <url> |
|
|
|
| Backup | <url> |
|
|
|
| is-backup | <yes>yes|<no>no |
- This setting is used for Controller instances in cluster mode only, it is not used for standalone Controller instances.
- The registration of Primary and Secondary Controller instances is performed by the JOC Cockpit during initial operation.
- Therefore the only setting required for cluster operation is:
js7.journal.cluster.node.is-backup=yes
: For a Secondary Controller instance this setting specifies that during initial operation the given instance will be the inactive standby node.
- Additional settings can be applied. However, we recommend that the JOC Cockpit is used instead.
nodes
Primary, Backup
: For a Primary Controller instance this setting specifies the URLs of the Primary
and Backup
(Secondary) instance. The URL includes specification of the http/https protocol, the hostname and port.
...
Explanation:
- The Controller verifies the signature signatures of deployable scheduling objects such as workflows during deployment. This can be performed using PGP and X.509 signatures.
- The
trusted-signature-keys
setting specifies the location of PGP public keys and X.509 certificates. - If no PGP public keys are used or if no X.509 certificates are used then this setting should not be used as it is expected that the indicated directory is populated with public keys or certificates respectively.
...
- 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.
Find examples of private.conf
files for configuration Controller configuration for download:
...
Code Block |
---|
language | yml |
---|
linenumbers | true |
---|
|
js7 {
auth {
# User accounts for https connections
users {
# History account of JOC Cockpit (used to release events)
History {
# for use with TLS mutual authentication
distinguished-names=[
"DNQ=SOS CA, CN=joc-2-0-primary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE",
"DNQ=SOS CA, CN=joc-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
]
# for use with password authentication (default password stored with JOC Cockpit Settings)
password="sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08"
}
# for use of an empty password
# JOC account of JOC Cockpit ( # password="plain:"
}
# JOC account of JOC Cockpit (requires UpdateItem permission for deployment)
JOC {
# for use with TLS mutual authentication
distinguished-names=[
"DNQ=SOS CA, CN=joc-2-0-primary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE",
"DNQ=SOS CA, CN=joc-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
]
# for use with password authentication (default password stored with JOC Cockpit Settings)
password="sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE"
permissions=[
# for use of an empty password
UpdateItem# password="plain:"
]permissions=[
}
}UpdateItem
}
} |
Explanation:
Password Authentication
...
Code Block |
---|
language | yml |
---|
linenumbers | true |
---|
|
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
]
}
}
}
} |
Explanation:
Controller Cluster Configuration
Client Authentication
Explanation:
History
- Settings in this section are used for the History Service of JOC Cockpit instances that access the given Controller.
distinguished-names
password
- A default password is specified with the section joc of the JS7 - Settings page of JOC Cockpit and in the
private.conf
file. The password
is used for authentication of the History
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:
- At the same time the password setting in JOC Cockpit has to be assigned an empty value.
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 the History
setting described above.permissions
: JOC Cockpit requires the UpdateItem
permission to enable users to deploy objects such as workflows.password
: The same applies as for the History
setting described above.
...
...
...
Agent Connections
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 |
---|
| js7-auth-users-password-JOC |
---|
| js7-auth-users-password-JOC |
---|
|
JOC Cockpit Connections Code Block |
---|
language | yml |
---|
linenumbers | true |
---|
|
js7 {
auth {
|
Code Block |
---|
language | yml |
---|
linenumbers | true |
---|
|
js7 {
auth {
# User accounts for https connections
users {
# ControllerHistory account IDof forJOC connectionsCockpit by primary/secondary Controller instance(used to release events)
ControllerHistory {
distinguished-names=[
# for use with password authentication (default password stored with JOC Cockpit Settings)
"DNQ=SOS CA, CN=controller-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE password="sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08"
}
]
# JOC account }
of JOC Cockpit (requires UpdateItem permission for deployment)
}
}
} |
Explanation:
JOC {
# for use with password authentication (default password stored with JOC Cockpit Settings)
password="sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE"
permissions=[
UpdateItem
]
}
}
}
} |
Explanation:
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 the UpdateItem
permission to enable users to deploy objects such as workflows.
- The
password
is used for authentication of the History
and JOC
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:
Image Added
Input to the GUI simply accepts the password and does not require to use the prefixes sha512:
or plain:.
- 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"
- 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:
- 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
- JOC:
- Plain Text:
JS7-JOC
- Hash:
sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE
- 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 |
---|
| js7-auth-users-password-Agent |
---|
| js7-auth-users-password-Agent |
---|
|
Agent Connections Code Block |
---|
language | yml |
---|
linenumbers | true |
---|
|
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
Client Authentication
Anchor |
---|
| js7-auth-users-Controller |
---|
| js7-auth-users-Controller |
---|
|
Controller Connections Code Block |
---|
language | yml |
---|
linenumbers | true |
---|
|
js7 {
auth {
# User accounts for https connections
users {
# Controller ID for connections by primary/secondary Controller instance
Controller {
distinguished-names=[
"DNQ=SOS CA, CN=controller-2-0-secondary, OU=IT, O=SOS, L=Berlin, ST=Berlin, C=DE"
]
}
}
}
} |
Explanation:
- Note that the
Controller
element Note that the Controller
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.of passwords.
...
Code Block |
---|
language | yml |
---|
linenumbers | true |
---|
|
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.
...
Settings in this section apply to both Standalone Controller and Controller Cluster instances.
Anchor |
---|
| js7-web-https-keystore |
---|
| js7-web-https-keystore |
---|
|
HTTPS Keystore and Truststore ...
Access
Code Block |
---|
language | yml |
---|
linenumbers | true |
---|
|
js7 {
web {
# keystore and truststore location for https connections
https {
client-keystore {
# Default: ${js7.config-directory}"/private/https-client-keystore.p12"
file=${js7.config-directory}"/private/https-client-keystore.p12"
key-password="jobscheduler"
store-password="jobscheduler"
}
keystore {
# Default: ${js7.config-directory}"/private/https-keystore.p12"
file=${js7.config-directory}"/private/https-keystore.p12"
key-password="jobscheduler"
store-password="jobscheduler"
# alias=
}
truststores=[
{
# Default: ${js7.config-directory}"/private/https-truststore.p12"
file=${js7.config-directory}"/private/https-truststore.p12"
store-password="jobscheduler"
# alias=
}
]
}
}
} |
...
Security Configuration File: private.conf
js7.auth.users: HTTPS Authentication and Authorizationjs7.auth.users: HTTPS Authentication and Authorizationjs7 | auth | users |
|
|
|
---|
|
|
| <controller-id> |
|
|
|
|
|
| js7 | auth | users | <controller-id> | distinguished-names | <distinguished-name>[,<distinguished-name>] | 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 | |
|
|
| 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 |
- An additional authentication mechanism is applied when using HTTPS Server Authentication certificates or public keys for incoming connections. See below: the client of the incoming connection, e.g. JOC Cockpit, is required to provide a Client Authentication certificate. This includes two certificates which are in place for a secure HTTPS connection: the given Controller's Server Authentication certificate and the JOC Cockpit's Client Authentication certificate. As an alternative to Client Authentication a password can be used.
- The fact that a given certificate is to be used for Server Authentication and/or Client Authentication is specified with the key usage when the certificate is created and signed.
- The distinguished name that is specified with the Controller's configuration has to match the Client Authentication Certificate's or Client public key's subject attribute. This attribute specifies the hostname and additional information that is created when the certificate or public key is generated.
<controller-id>
- This element holds the Controller ID that has been specified during installation of a Standalone Controller or Controller Cluster.
- Settings in this section are used for connections from a pairing Controller instance.
distinguished-names
- Specifies the distinguished name as given with the subject of the Client Authentication Certificate for incoming HTTPS connections of a pairing Controller instance.
- One or two distinguished names can be specified allowing incoming HTTPS connections from a Standalone Controller or Controller Cluster.
History
- An additional authentication mechanism is applied when using HTTPS Server Authentication certificates or public keys for incoming connections. See below: the client of the incoming connection, e.g. JOC Cockpit, is required to provide a Client Authentication certificate. This includes two certificates which are in place for a secure HTTPS connection: the given Controller's Server Authentication certificate and the JOC Cockpit's Client Authentication certificate. As an alternative to Client Authentication a password can be used.
- The fact that a given certificate is to be used for Server Authentication and/or Client Authentication is specified with the key usage when the certificate is created and signed.
- The distinguished name that is specified with the Controller's configuration has to match the Client Authentication Certificate's or Client public key's subject attribute. This attribute specifies the hostname and additional information that is created when the certificate or public key is generated.
<controller-id>
- This element holds the Controller ID that has been specified with identical values during installation of both Controller instances in a cluster.
- Settings in this section are used for connections from a pairing Controller instance, e.g. for a Secondary Controller instance if the given configuration is used for the Primary Controller instance and vice versa.
distinguished-names
- Specifies the distinguished name as given with the subject of the Client Authentication Certificate for incoming HTTPS connections of a pairing Controller instance.
- Any number of distinguished names can be specified allowing a number of incoming HTTPS connections from different Controller instances. At a given point in time only one pairing Controller instance can connect to the given Controller.
- Except for whitespace between attributes the precise sequence and values as available from the certificate's subject has to match this property value.
History
- Settings in this section are used for the History Service of JOC Cockpit instances that access the given Controller.
distinguished-names
: the same applies as for the <controller-id>
setting described above. The JOC Cockpit Client Authentication certificate is used.password
: a symmetric password that is used for authentication of the History Service to the Controller for both HTTP and HTTPS connections, see below.
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 the <controller-id>
setting described above. The JOC Cockpit Client Authentication certificate is used.password
: a symmetric password is used for authentication of the History Service to the Controller for both HTTP and HTTPS connections, see below.permissions
: JOC Cockpit requires the UpdateItem
permission to enable users to deploy objects such as workflows.- . The JOC Cockpit Client Authentication certificate is used.
password
: a symmetric password that is used for authentication of the History Service to the Controller for both HTTP and HTTPS connections, see below.
JOC
distinguished-names
: the same applies as for the <controller-id>
setting described above. The JOC Cockpit Client Authentication certificate is used.password
: a symmetric password is used for authentication of the History Service to the Controller for both HTTP and HTTPS connections, see below.permissions
: JOC Cockpit requires the UpdateItem
permission to enable users to deploy objects such as workflows.
- The
password
is used for authentication of the History
and JOC
service accounts with the Controller. Both accounts are typically running in the same JOC Cockpit instance. The password
is used for authentication of the History
and JOC
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. If HTTPS connections with mutual authentication are used then the password is not required as certificate based authentication is in place. However, if a password is specified then it has to match.
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:
Image Removed
Input to the GUI simply accepts the password and does not require to use the prefixes sha512:
or plain:.
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"
- If the password is modified in the
private.conf
file then it also has to be modified in the JOC Cockpit settings to make the passwords match. - The password setting cannot be omitted, however, an empty password can be specified, for example with mutual authentication HTTPS connections, like this:
- 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
- JOC:
- Plain Text:
JS7-JOC
- Hash:
sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE
...