Introduction

This article explains configuration items available for Standalone Agents, Director Agents and Subagents in a JS7 - Agent Cluster. 

• An Agent makes use of two configuration files:
  • the agent.conf general configuration file which is found in the following locations:
    • Windows: C:\ProgramData\sos-berlin.com\js7\agent\var\config\agent.conf
    • Unix /var/sos-berlin.com/js7/agent/var/config/agent.conf
  • the private.conf security configuration file which is found in the following locations:
    
    • Windows: C:\ProgramData\sos-berlin.com\js7\agent\var\config\private.conf
    • Unix: /var/sos-berlin.com/js7/agent/var/config/private/private.conf
  • The configuration format makes use of Typesafe Config, see the JS7 - Configuration Format article.
  • Restart the Agent instance to apply changes to any configuration files.
• For HTTPS configuration refer to the JS7 - Configuration Templates article.

...

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

• This setting specifies public access to an Agent if incoming HTTP connections are to be used. If used with a value true then authentication is not applied.
• Default: true

Anchor
js7-journal-cluster js7-journal-cluster

Director Agent Cluster Configuration

...

• This setting is used for Director Agent instances in cluster mode only, it is not used for standalone Director Agent instances.
• The registration of Primary and Secondary Director Agent 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 Director Agent 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 Director Agent 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 Agent verifies the signature signatures of scheduling objects such as workflows during deployment. This can be performed for 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 expects the indicated directory to be populated with public keys or certificates respectively.

...

• This setting applies to the use of an Agent with a Standalone Controller or with a Controller Cluster.
• Note that the Controller element name is an example that has to be replaced by the Controller ID which is specified with the same value during installation of Controller instances.
• The distinguished-names element identifies the Controller instance's Client Authentication certificate. The certificate acts as a replacement for a password.
  • The Agent configuration specifies the distinguished names of the Controller instances that access the Agent by use of a Client Authentication certificate. For a Standalone Controller there is a single distinguished name, for a Controller Cluster each instance's distinguished name is specified.
  • 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 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 a Controller instance's certificate file (.crt) openssl x509 -in centostestcontroller-secondaryprimary.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=directorcontroller-2-0-secondaryprimary,OU=IT,O=SOS,L=Berlin,ST=Berlin,C=DE

...

js7 {
    auth {
        # User accounts for https connections
        users {
            # Controller ID for connections by primary/secondary Controller instance
            Controller {
                password="plain:secret"
                # password="sha512:bd2b1aaf7ef4f09be9f52ce2d8d599674d81aa9d6a4421696dc4d93dd0619d682ce56b4d64a9ef097761ced99e0f67265b5f76085e5b0ee7ca4696b2ad6fe2b2"                   }
        }
    }
}

Explanation:

• This setting applies to use of an Agent with a Standalone Controller or with a Controller Cluster.
• Note that the Controller element name is an example that has to be replaced by the Controller ID which is specified with the same value during installation of both cluster Controller instances.
• This setting specifies the password indicated with the Controller instance's js7.auth.agents configuration item. Passwords should be quoted.
  • The password can be specified as plain text preceded by plain:.
  • The password can be specified as a hashed value preceded by sha512:.
    • There are a number of ways to create sha512 hash values from passwords.
    • One possible solution includes using:  echo -n "secret" | openssl dgst -sha512

Director Agent Configuration

...

• This setting applies to use of the Subagent component within a Director Agent instance in a JS7 - Agent Cluster.
• Note that the subagent-id element name is an example that has to be replaced by the Subagent ID of the pairing Director Agent instance which is specified during configuration of the Agent Cluster. This is not the Agent Cluster ID. For the private.conf file of a Primary Director Agent instance this setting holds the Subagent ID of the Secondary Director Agent instance and vice versa.
• The permissions element should be used as indicated.
• The distinguished-names element identifies the pairing Director Agent instance's Client Authentication certificate. The certificate acts as a replacement for a password.
  
  • 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 Director Agent 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 Director Agent instance's certificate file (.crt) openssl x509 -in centostestdirector-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=director-2-0-secondary,OU=IT,O=SOS,L=Berlin,ST=Berlin,C=DE

...

js7 {
    auth {
        # User accounts for https connections
        users {
            # Subagent ID of pairing Director Agent instance
            subagent-id {
                 permissions = [ AgentDirector ]
                 password="plain:secret"
                 # password="sha512:bd2b1aaf7ef4f09be9f52ce2d8d599674d81aa9d6a4421696dc4d93dd0619d682ce56b4d64a9ef097761ced99e0f67265b5f76085e5b0ee7ca4696b2ad6fe2b2"              }
        }
    }
}

Explanation:

• This setting applies to use of a Subagent within a Director Agent instance in an JS7 - Agent Cluster.
• Note that the subagent-id element name is an example that has to be replaced by the Subagent ID of the pairing Director Agent instance which is specified during configuration of the Agent Cluster. This is not the Agent Cluster ID. For the private.conf file of a Primary Director Agent instance this setting holds the Subagent ID of the Secondary Director Agent instance and vice versa.
• The permissions element should be used as indicated.
• The password element specifies the password indicated with the pairing Director Agent instance's js7.auth.subagents configuration item. Passwords should be quoted. 
  • The password can be specified as plain text preceded by plain:.
  • The password can be specified as a hashed value preceded by sha512:.value preceded by sha512:.
    • There are a number of ways to create sha512 hash values from passwords.
    • One possible solution includes using:  echo -n "secret" | openssl dgst -sha512

Anchor
js7-auth-users-password-Director js7-auth-users-password-Director

Subagent Connections

...

• This setting applies to connections from Director Agent instances to the current Subagent in a JS7 - Agent Cluster.
• Note that the director-primary, director-secondary element names are examples that have to be replaced by the Subagent ID of the respective Director Agent instance which is specified during configuration of the Agent Cluster.
• The permissions element should be used as indicated.
• The distinguished-names element identifies the Director Agent instance's Client Authentication certificate. The certificate acts as a replacement for a password.
  
  • 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 Director Agent 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 pairingboth Director Agent instance's certificate files (.crt) openssl x509 -in centostestdirector-secondaryprimary.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=director-2-0-secondaryprimary,OU=IT,O=SOS,L=Berlin,ST=Berlin,C=DE

...

js7 {
    auth {
        # User accounts for https connections
        users {
            # Subagent ID of Primary Director Agent instance
            director-primary {
                permissions = [ AgentDirector ]
                password = "plain:secret-director-primary"
                # password = "sha512:308769d726e2b1e69530ac631d8ac8f26c67ae6bda1dfca41b523ac8ab7b9745a2e62750f183c9e3046e45106b402fef1ad5746365a0ccc24004776ed74a9160"             }

            # Subagent ID of Secondary Director Agent instance
            director-secondary {
                permissions = [ AgentDirector ]
                password = "plain:secret-director-secondary"
                # password = "sha512:5419dfceee6a3081f4d3aee95a7e5cdddb078b6753db77bfbebba05e6b0140aeb11cfa59b56b07ac78389c0918652b57e3bc7aa333c94d74362d5ca7f7166888"              }
         }
    }
}

...

• This setting applies to the connection from Director Agent instances to the current Subagent in an JS7 - Agent Cluster.
• Note that the director-primary, director-secondary  element names are examples that have to be replaced by the Subagent ID of the respective Director Agent instance which is specified during configuration of the Agent Cluster.
• The permissions element should be used as indicated.
• The password element specifies the password indicated with the respective Director Agent instance's js7.auth.subagents configuration item. Passwords should be quoted.
  • The password can be specified as plain text preceded by plain:.
  • The password can be specified as a hashed value preceded by sha512:.

  ...

  • • • There are a number of ways to create sha512 hash values from passwords.
      • One possible solution includes using:  echo -n "secret-director-primary" | openssl dgst -sha512

  Keystore and Truststore

  Settings in this section apply to any of Standalone Agents, Director Agent instances and Subagents.

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

  Explanation:

  • HTTPS keystore and truststore truststores are used to hold private keys and certificates.
    • Keystore and truststore settings accept the path to a file in PKCS12 format or in PEM format.
    • The keystore holds the Agent'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 a Controller and
      • Server Authentication certificates challenged by pairing Controllers.
    • A number of truststores can be specified.
  • Optionally a separate HTTPS client keystore can be used:
    • The client keystore is used for TLS mutual authentication and holds a private key and certificate created for Client Auth extended key usage. 
    • When using TLS mutual authentication then:
      • a single certificate can be used that is generated for both Server Auth and Client Auth extended key use. In this case do not use the HTTPS client keystore but use the HTTPS keystore to hold the certificate.
      • separate certificates can be used with the certificate for Server Auth key usage being stored with the HTTPS keystore and the certificate for Client Auth key use being stored with the HTTPS client keystore.
    • For details see 

      Jira
      server SOS JIRA columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 6dc67751-9d67-34cd-985b-194a8cdc9602 key JS-1959

  • Keystore and Truststore locations are specified. In addition:
    • a password for the private keys included in the keystore 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 keystore and truststore are not intended for security of the configuration, they are used to verify the integrity of certificate stores as the password used for creating and reading the certificate store must be the same.
    • The key-password is used for access to a private key in a keystore.
    • The store-password setting is used for access to a keystore or to a truststore.
    • For PKCS12 keystores both settings have to use the same value. The settings can be omitted if no passwords are used.
  • The alias setting can be used for example with a keystore that holds a number of private keys from which the relevant private key is selected by its alias name.

  Summary of Configuration Items

  General Configuration File: agent.conf

  ...

  js7.job.execution: Job Script Termination

  The following settings can be used for releases prior to 2.7.2:

  js7	job	execution		Default
  			kill-with-sigterm-command	"/bin/kill", "$pid"
  			kill-with-sigkill-command	"/bin/kill", "-KILL", "$pid"

  • The Agent can be instructed to terminate running jobs - see the JS7 - FAQ - Does JS7 reliably kill running jobsHow does JobScheduler terminate Jobs article.
  • The following settings are in place to terminate running jobs by an Agent operated for a Unix OS:
    • The setting kill-with-sigterm-command specifies the OS command executed by the Agent to forward a SIGTERM signal to the running job.
    • The setting kill-with-sigkill-command specifies the OS command executed by the Agent to forward a SIGKILL signal to the running job.
  • Both settings are specified as an array of arguments, i.e. "/bin/kill", "-KILL", "$pid" translates to the command: /bin/kill -KILL 99, provided that 99 is the Process ID of the running job.
  • This setting can be applied if the Agent is operated on an OS that makes use of a different syntax for the kill command.

  ...