...

• 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\agentcontroller.conf
    • Unix /var/sos-berlin.com/js7/controller/var/config/agentcontroller.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

...

Anchor
js7-web-server-auth-public js7-web-server-auth-public

HTTP Connections

By default the Controller configuration ships with HTTP communication connections enabled. It is recommended that public/private keys and certificates for secure HTTPS communication connections are created used and that HTTP communication is connections are disabled.

# Allow HTTP connections without authentication
js7.web.server.auth.public = true

Anchor
js7-journal-cluster js7-journal-cluster

Cluster Controller Configuration

If a JS7 Controller cluster is used then the following default configuration is has to be applied:

Primary Controller Configuration

...

• A Secondary Controller instance specifies a single node this setting to indicate that this instance starts as a standby node (Backup). Without this setting being 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 instance. 

...

• This setting is used for Controller instances in cluster mode only, it is not used for standalone Controller instances.
• The assignment registration of Primary and Backup Secondary 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.

...

• using HTTPS connections that are secured by private/public key and certificates,
• applying mutual authentication between Controller and Agent.
• Consider detailed explanations from the subsequent chapters.

# 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
                }
            ]
        }
    }
}

Client Authentication

Anchor
js7-auth-users-Controller js7-auth-users-Controller

Controller Connections

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"
                ]
            }
        }
    }
}

Explanation:

• This setting applies to use of a Controller Cluster.
• This setting specifies the distinguished name indicated with the pairing Controller's Client Authentication certificate. The certificate acts as a replacement for a password.
  • The Controller configuration specifies the distinguished name of a pairing Controller that would access this Controller by use of a Client Authentication certificate.
  • Consider that the common name (CN) setting in the distinguished name has to match the fully qualified domain name (FQDN) of a Controller's host.

Server Authentication

Anchor
js7-web-https-keystore js7-web-https-keystore

HTTPS Keystore and Truststore Locations

js7 {
    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
                }
            ]
        }
    }
}

Explanation:

• HTTPS keystore and truststore are used to hold private keys and certificates
  • The keystore holds the Controller instance's private key and certificate. This information is used
    • for Server Authentication with JOC Cockpit and
    • for Client Authentication with Agents.
  • The truststore holds the certificate(s) used to verify
    • Client Authentication certificates presented by JOC Cockpit and
    • Server Authentication certificates presented by Agents.
• Keystore and Truststore locations are specified. In addition
  • for the keystore a password for the private keys included and a password for access to the keystore can be specified
  • for the truststore a password for access to the truststore can be specified.
• Passwords for keystores and truststores have no tendency to improve security of the configuration: the passwords have to be specified as plain text and have to be in reach of the Controller. This mechanism is not too different from hiding the key under your doormat. In fact limiting ownership and access permissions for keystore and truststore files to the JS7 Controller's run-time account are more important than using a password.
  • The key-password is used for access to a private key in keystore.
  • The store-password setting is used for access to a keystore or to a truststore.
  • For PKCS12 (*.p12) keystores both settings have to use the same value. The settings can be omitted if no passwords are used.

Configuration Items

General Configuration File: controller.conf

...