You are viewing an old version of this page. View the current version.
Compare with Current
View Page History
« Previous
Version 23
Next »
Introduction
- Controllers makes use of two configuration files:
- the general configuration file
controller.conf
which is available from the following locations:- Windows:
C:\ProgramData\sos-berlin.com\js7\controller\var\config\agent.conf
- Unix
/var/sos-berlin.com/js7/controller/var/config/agent.conf
- the security configuration from
private.conf
which is available from 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 to apply changes to the configuration files
Default Configuration
General Configuration File: controller.conf
Enable HTTP Communication
By default the Controller configuration ships with HTTP communication enabled. It is recommended that public/private keys and certificates for secure HTTPS communication are created and that HTTP communication is disabled.
# Allow HTTP connections without authentication
js7.web.server.auth.public = true
Cluster Controller Configuration
If a JS7 cluster is used then the following default configuration is applied:
Primary Controller Configuration
# Cluster configuration: not required
- A Primary Controller instance does not require any configuration items for cluster operation.
Secondary Controller Configuration
# Cluster configuration
js7.journal.cluster {
node {
is-backup = yes
}
}
- A Secondary Controller instance specifies a single node to indicate that this instance starts as a standby node (Backup).
- 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 instance.
Configuration Settings
js7.journal.cluster: Journal Cluster Settings
js7 | journal | cluster |
|
|
|
---|
|
|
| nodes |
|
|
|
|
|
| Primary | <url> |
|
|
|
| Backup | <url> |
|
|
|
| is-backup | <true>|<false> |
|
|
| watches |
|
|
|
|
|
| <url> [,<url>] |
|
- This setting is used for Controller instances in cluster mode only, it is not used for standalone Controller instances.
- The assignment of Primary and Backup Controller instances is performed by JOC Cockpit during initial operation. It is therefore not required to add settings to Controller configuration files.
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 protocol http/https, the hostname and port.is-backup
: For a Secondary Controller instance this setting specifies that during initial operation the given instance will be the standby node.
watches
- Watches are Agents in a JS7 environment that are involved in the decision about a fail-over situation. If Controller instances in a cluster are not connected to each other any longer, e.g. due to network errors, then the majority of Agents decides if a fail-over should take place.
- At least one Agent has to be specified by its URL.
js7.web.server: Authentication Settings
js7 | web | server |
|
|
|
---|
|
|
| auth | public | <true>|<false> |
- This setting specifies public access to a Controller if insecure incoming HTTP connections are to be used. If used with a value
true
then no authentication is applied. - Default:
false
Secure Configuration
It is essential to secure the connections between Controller, Agents and JOC Cockpit. This includes:
- using HTTPS connections that are secured by private/public key and certificates,
- applying mutual authentication between Controller and Agent.
# Security configuration
js7 {
auth {
# User accounts for HTTPS connections
users {
# Controller account 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"
]
}
# History account (used for release events)
History {
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"
]
password="sha512:B793649879D61613FD3F711B68F7FF3DB19F2FE2D2C136E8523ABC87612219D5AECB4A09035AD88D544E227400A0A56F02BC990CF0D4CB348F8413DE00BCBF08"
}
# JOC account (reqires UpdateRepo permission for deployment)
JOC {
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"
]
password="sha512:3662FD6BF84C6B8385FC15F66A137AB75C755147A81CC7AE64092BFE8A18723A7C049D459AB35C059B78FD6028BB61DCFC55801AE3894D2B52401643F17A07FE"
permissions=[
UpdateRepo
]
}
}
}
configuration {
# directory for trusted public keys and certificates used with signatures
trusted-signature-keys {
PGP=${js7.config-directory}"/private/trusted-pgp-keys"
X509=${js7.config-directory}"/private/trusted-x509-keys"
}
}
journal {
# allow History account to release events to free space claimed by journals
users-allowed-to-release-events=[
History
]
}
web {
# keystore and truststore location for HTTPS connections
https {
keystore {
# Default: ${js7.config-directory}"/private/https-keystore.p12"
file=${js7.config-directory}"/private/https-keystore.p12"
key-password=jobscheduler
store-password=jobscheduler
}
truststores=[
{
# Default: ${js7.config-directory}"/private/https-truststore.p12"
file=${js7.config-directory}"/private/https-truststore.p12"
store-password=jobscheduler
}
]
}
}
}
Configuration Items
General Configuration File: controller.conf
js7.web.server: Authentication Settings
js7 | web | server |
|
|
|
---|
|
|
| auth | public | <true>|<false> |
- This setting specifies public access to a Controller if insecure incoming HTTP connections are to be used. If used with the value
true
then authentication is not applied. - Default:
false
Security Configuration File: private.conf
js7.auth.users: HTTPS Authentication and Authorization
js7 | auth | users |
|
|
|
---|
|
|
| Controller |
|
|
|
|
|
| distinguished-names | <distinguished-name>[,<distinguished-name] |
|
|
| History |
|
|
|
|
|
| distinguished-names | <distinguished-name>[,<distinguished-name] |
|
|
|
| password | plain:<text>|sha512:<hashed-password> |
|
|
| JOC |
|
|
|
|
|
| distinguished-names | <distinguished-name>[,<distinguished-name] |
|
|
|
| password | plain:<text>|sha512:<hashed-password> |
|
|
|
| permissions | UpdateRepo |
- An additional authentication mechanism is applied when using HTTPS 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 and a password. This includes two certificates that are in place for a secure HTTPS connection: the given Controller's Server Authentication Certificate and the JOC Cockpit's Client Authentication Certificate.
- 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 being 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
- 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.
History
- Settings in this section are used for the History Service of JOC Cockpit instances that access the given Controller.
distinguished-names
: the same as for the Controller
setting.password
: a password has to be used in addition to use of a certificate or public key. In addition the password is used if incoming HTTP connections are allowed.
JOC
- Settings in this section are used for JOC Cockpit instances that access the given Controller.
distinguished-names
: the same as for the Controller
setting.password
: a password has to be used in addition to use of a certificate or public key. In addition the password is used if incoming HTTP connections are allowed.permissions
: JOC Cockpit requires the UpdateRepo
permission to enable users to deploy objects such as workflows.
js7.auth.agents: HTTPS Authentication and Authorization
js7 | auth | agents |
|
|
---|
|
|
| <Agent ID> | <password> |
|
|
| <Agent ID> | <password> |
- By default for HTTPS connections both Server Authentication Certificates and Client Authentication Certificates are used. If no Client Authentication Certificates should be used then the Controller has to use a password to authenticate with an Agent.
- For each Agent the
<Agent ID>
and a plain text password
is specified. A plain-text password is required. The same password has to be specified with the Agents private.conf
configuration file.
js7.web.https: HTTPS Certificates
js7 | web | https |
|
|
|
---|
|
|
| keystore |
|
|
|
|
|
| file | <path> |
|
|
|
| key-password | <text> |
|
|
|
| store-password | <text> |
|
|
| truststores |
|
|
|
|
|
| file | <path> |
|
|
|
| store-password | <text> |
- This setting is used to specify the location of a keystore and any truststores used for HTTPS connections.
- Keystore and truststore files are expected in PKCS#12 format.
keystore
- The keystore includes the private key for the Controller's incoming HTTPS connections.
- Private key types RSA and ECDSA are supported.
file
: the full path to the location of the keystore file is expected.key-password
: Any keys included with the keystore are protected with a password. The same password has to be used for all private keys in the given keystore.store-password
: The keystore file is protected by a password.
truststores
- A truststore contains the certificates or public keys for the Controller's incoming HTTPS connections.
- Certificates are signed by a Certificate Authority (CA), alternatively a self-signed certificate can be used.
- It is recommended that certificates are used instead of public keys.
- Certificates of type X.509 are supported.
file
: the full path to the location of the truststore file is expected.store-password
: A truststore file is protected by a password.- A number of truststores can be specified by repeating the
file
and store-password
settings.
js7.web.server: HTTPS Authentication
js7 | web | server |
|
|
|
---|
|
|
| auth |
|
|
|
|
|
| https-client-authentication | <on|off> |
- This setting is used to specify the authentication type for HTTPS connections to a Controller.
https-client-authentication
- The value
on
(default) specifies that mutual authentication with certificates for Server Authentication and Client Authentication is used. - The value
off
specifies that HTTP Basic Authentication only is used.
- By default JS7 makes use of mutual authentication including both Server and Client Authentication Certificates. This setting can be switched off to use Server Authentication Certificates only.
js7.configuration: Trusted Signature Keys
js7 | configuration |
|
|
|
---|
|
| trusted-signature-keys |
|
|
|
|
| PGP | <directory> |
|
|
| X509 | <directory> |
- The Controller expects a signature Fof any deployed objects such as workflows. Such signatures are created with a private key and are verified by the Controller based on the available certificates. Agents perform similar signature verification and are configured accordingly.
- When deploying objects with JOC Cockpit
- for a Low Security Level JOC Cockpit creates the signature from a single private key that is used for any JOC Cockpit user accounts allowed to deploy objects.
- for a Medium Security Level JOC Cockpit creates the signature from the private key of the JOC Cockpit user account that deploys objects.
- for a High Security Level the user creates the signature outside of JOC Cockpit and uploads the signed objects.
- The Controller supports PGP public keys and X.509 certificates. This setting expects a directory that holds a number of public key files or certificate files.
trusted-signature-keys
PGP
: specifies the directory from which PGP public keys are used to verify the signature of deployed objects.X509
: specifies the directory from which X.509 certificates are used to verify the signature of deployed objects.
js7.journal: Journal Release Permissions
js7 | journal |
|
|
---|
|
| users-allowed-to-release-events | <account>[,<account>] |
- The Controller writes a journal of events that, for example, results from order state transitions such as an order starting, failing, completing etc.
- The journal file will grow indefinately if events are not released. Typically events are consumed by JOC Cockpit and are added to the order and task history. Events are released from the Controller's journal once they have been stored persistently to the JOC Cockpit database. The Controller accordingly will free the space consumed by its journal files.
users-allowed-to-release-events
: specifies the list of accounts that are allowed to send a command to the Controller to release events.- Typically the "History" account is specified, this account is used by JOC Cockpit.
- If more than one account is specified then events are released only after all accounts have sent the command to release events to the Controller.