...

Introduction

• The Controller makes use of two configuration files:
  • the general configuration from controller.conf
  • the security configuration from private.conf
• Restart the Controller instance to apply changes to any configuration file .

General Configuration

File: controller.conf

...

• following configuration items are initially populated by the JOC Cockpit installer and can be modified by a user later on. 
• JOC Cockpit makes use of the joc.properties configuration file that is populated by installation options. This file can be found by default in the following locations:
  • Linux: /var/sos-berlin.com/js7/

...

• • joc/

...

• • resources/

...

• • joc/

...

• • joc.

...

• • properties
  • Windows: C:\ProgramData\sos-berlin.com\js7\joc\resources\joc\joc.properties
  • The location of this file is indicated below as JETTY_BASE/resources/joc/joc.properties.
• The Jetty Servlet Container that ships with JOC Cockpit makes use of the following configuration file:
  • Linux: /var/sos-berlin.com/js7/joc/start.ini
  • Windows: C:\ProgramData\sos-berlin.com\js7\joc\start.ini
  • The location of this file is indicated below as JETTY_BASE/start.ini
• Restart the JOC Cockpit instance to apply changes to the JOC Cockpit or Jetty configuration files.
• See the JS7 - Settings article for run-time settings that do not require a restart of the JOC Cockpit.

JOC Cockpit

Installation Options

The following example of a JETTY_BASE/resources/joc/joc.properties file is created from the installer and can be modified by the user:

################################################################################
### If JOC Cockpit is used in a cluster then type a title to identify which node
### is currently used. Further type an ordering (Primary <= 0, Backup > 0) for
### the display order in JOC's dashboard

title = PRIMARY JOC COCKPIT
ordering = 0


################################################################################
### Path to log4j configuration file. Path can be absolute or relative
### to this file.

log4j.configuration = log4j2.xml


################################################################################
### Path to hibernate configuration file of JOC's database.
### Path can be absolute or relative to this file.

hibernate_configuration_file = hibernate.cfg.xml


################################################################################
### The time (in seconds) to establish the connection with the
### remote host. Default = 2

jobscheduler_connection_timeout = 2


################################################################################
### The time (in seconds) waiting for data after the connection
### has been established; maximum time of inactivity between two data packets.
### Default = 5

jobscheduler_socket_timeout = 5


################################################################################
### Should hostname verification be carried out for https certificates.
### Default false

https_with_hostname_verification = true


################################################################################
### Location, type and password of the Java truststore which contains the
### HTTPS connection certificates for each JobScheduler Controller.
### The path is relative to JETTY_BASE/resources/joc.

# keystore_path = https-keystore.p12
# keystore_type = PKCS12
# keystore_password = jobscheduler
# key_password = jobscheduler
# key_alias =

# truststore_path = https-truststore.p12
# truststore_type = PKCS12
# truststore_password = jobscheduler


################################################################################
### JOC Cockpit requires configuration of a security level for the
### signing mechanism: options "high", "medium" and "low".
### high:
###      public PGP/X.509 keys are stored for verification only
###      all signing will be done externally outside of JOC Cockpit
### medium:
###      a private PGP/X.509 key will be stored for signing
###      signing will be done automatically with the provided key
### low:
###      no keys will be stored
###      signing will be done internally with default keys
###
### This flag controls the security level used. Default low

security_level = low


################################################################################
### Settings for a custom logo file on the login page
### The logo file has to be located in ./jetty_base/webapps/root/ext/images
### Possible units for height are according to
### https://www.w3schools.com/cssref/css_units.asp (default px)
### Possible values for the position are "top" or "bottom" (default=bottom).

custom_logo_name =
custom_logo_height =
custom_logo_position =


################################################################################
### Normally, the user permissions control whether a view such as dashboard,
### workflows, etc. are shown or hidden. Here you can force to show (=true) or
### hide (=false) a view independently of the permissions. If the value is unequal
### true or false then the permissions win.

show_view_dashboard =
show_view_monitor =
show_view_dailyplan =
show_view_workflows =
show_view_filetransfers =
show_view_resources =
show_view_history =
show_view_auditlog =
show_view_configuration =

Logger Settings

• For details see JS7 - Log Rotation and JS7 - Log Levels and Debug Options

Database Connection Settings

• For details see JS7 - Database

Controller Connection Settings

HTTPS Connection Settings

• For details see JS7 - JOC Cockpit HTTPS Connections

Custom Logo Settings

Dashboard Settings

Security Options

• Note: Changes to the above setting are ignored. Instead, the above setting is applied by the installer for informational purposes only.
• To modify the security level of JOC Cockpit re-run the installer and select the respective installation option.
• For details see the JS7 - Security Architecture article.

Jetty Servlet Container

Installation Options

Technically any options for the Jetty Servlet Container can be used as available from the product. The section belowis focused on settings that are added by the JOC Cockpit installer or that preferably are modified by users after installation.

The following example of a JETTY_BASE/start.ini configuration file is created from the installer and can be modified by the user:

# --------------------------------------- 
# Module: http
# Enables an HTTP connector on the server.
# --------------------------------------- 
--module=http

## Connector host/address to bind to
# jetty.http.host=0.0.0.0

## Connector host/address to bind to
jetty.http.port=4446

# ---------------------------------------
# Module: https
# Adds HTTPS protocol support to the TLS(SSL) Connector
# ---------------------------------------
# --module=https

# ---------------------------------------
# Module: ssl
# Enables a TLS(SSL) Connector on the server.
# ---------------------------------------
# --module=ssl

## Connector host/address to bind to
# jetty.ssl.host=0.0.0.0

## Connector port to listen on
# jetty.ssl.port=4443

## Keystore file path (relative to $jetty.base)
# jetty.sslContext.keyStorePath=resources/joc/https-keystore.p12

## Keystore type (PKCS12, JKS)
# jetty.sslContext.keyStoreType=PKCS12

## Keystore password
# jetty.sslContext.keyStorePassword=jobscheduler

## KeyManager password (same as keystore password for pkcs12 keystore type)
# jetty.sslContext.keyManagerPassword=jobscheduler

## Truststore file path (relative to $jetty.base)
# jetty.sslContext.trustStorePath=resources/joc/https-truststore.p12

## Truststore type (PKCS12, JKS)
# jetty.sslContext.trustStoreType=PKCS12

## Truststore password
# jetty.sslContext.trustStorePassword=jobscheduler

## Client certificate authentication is required
# jetty.sslContext.needClientAuth=false
## Client certificate authentication is desired
# jetty.sslContext.wantClientAuth=true
## The Endpoint Identification Algorithm
## Same as javax.net.ssl.SSLParameters#setEndpointIdentificationAlgorithm(String)
# jetty.sslContext.endpointIdentificationAlgorithm=

HTTP Connection Settings

Options are enabled by use of the --module=http setting.

HTTPS Connection Settings

Options are enabled by use of the --module=https and --module=ssl settings.

Such options are not added by the installer but can be enabled and modified by the user.

Certificate Based Authentication Settings

Options are enabled by use of the --module=https and --module=ssl settings.

• Note explanations in the JS7 - Certificate based Authentication article.
• For details see the  JS7 - JOC Cockpit HTTPS Connections article

...

# Cluster configuration
js7.journal.cluster {
    nodes {
        Primary = "https://controller-2-0-primary:4443"
        Backup = "https://controller-2-0-secondary:4443"
    }
    watches = [ "https://agent-2-0-primary:4443" ]
}

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

js7.journal.cluster: Journal Cluster Settings

...

• This setting is used for Controllers in cluster mode only, it is not used for standalone Controller instances.
• nodes
  • This setting specifies the URLs of the Primary and Backup (Secondary) instance. The URL includes to specify the protocol http/https, the hostname and port.
• 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

...

• This setting specifies public access to a Controller should insecure incoming HTTP connections be used. If used with a value true then no authentication applies.
• Default: false

Security Configuration

File: private.conf

Default Location: /var/sos-berlin.com/js7/controller/var/config/private/private.conf

# 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 {
        # Controller truststore location
        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 unused 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
                }
            ]
        }
    }
}

js7.auth.users: HTTPS Authentication and Authorization

...

• When using HTTPS Certificates or public keys for incoming connections, see below, then an additional authentication mechanism applies: the client of the incoming connection, e.g. JOC Cockpit, is required to provide a Client Authentication certificate or a password. This includes that two certificates are in place for a secure HTTPS connection: the Controller's Server Authentication Certificate and the JOC Cockpit's Client Authentication Certificate. 
  • The fact that a given certificate is used for Server Authentication and/or Client Authentication is specified with the key usage when creating and signing the certificate.
  • 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 if this configuration is used for the Primary Controller 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.
    • Any number of distinguished names can be specified, thus allowing a number of incoming HTTPS connections from different Controllers. At a given point in time only one pairing Controller 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:  same as for Controller setting.
  • password: a password can be used in addition to use of a certificate or public key. In addition the password is applied in case that insecure incoming HTTP connections are allowed.
• JOC
  • Settings in this section are used for JOC Cockpit instances that access the given Controller.
  • distinguished-names:  same as for Controller setting.
  • password:  a password can be used in addition to use of a certificate or public key. In addition the password is applied in case that insecure incoming HTTP connections are allowed.
  • permissions: JOC Cockpit requires the UpdateRepo permission to enable users to deploy objects such as workflows.

js7.configuration: Signature Keys

...

• For any deployed objects such as workflows the Controller expects a signature. Such signatures are created with a private key and are verified by the Controller based on the available certificates. 
• 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 deploy 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 X509 certificates. This setting expects a directory respectively 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 X509 certificates are used to verify the signature of deployed objects.

js7.journal: Journal Release Permissions

...

• The Controller writes a journal of events that e.g. result from order state transitions such as an order starting, failing, completing etc.
• The journal file will grow unlimited if events are not released. Typically events are consumed by JOC Cockpit and are added to the order and task history. With events being stored persistently to the JOC Cockpit database they can be released from the Controller's journal. 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 the JS7 - Configuration - JOC Cockpit.
  • If more than one account is specified then events are released only after all accounts did send the command to release events to the Controller.

js7.web.https: HTTPS Certificates

...

• 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 type 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 any private keys.
  • 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 to use certificates instead of public keys.
  • Certificates of type X509 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.