Page History

...

Explanation:

• Options
  • --keystoreor --keystore-file
    • Specifies the path to a PKCS12 keystore file that should hold the private key and certificate for HTTPS connections to JS7 components.
    • Users are free to specify any file name, typically the name https-keystore.p12 is used.If a keystore file is made available then the JOC Cockpit's
    • <home>/jetty_base/start.d/Further settings in the ssl.ini file has to hold a reference to the keystore location and optionally such as the keystore password . It is therefore recommended to use have to be deployed from a copy of the file using the --ini option to deploy an individual ssl.ini file. The following settings are automatically updated in the ssl.ini file:.
    • Assigning a keystore for HTTPS connections disables HTTP access and enables HTTPS access only to JOC Cockpit. The same port is alternatively used for HTTP and HTTPS connections.
  • --truststore-file
    • Specifies the path to a PKCS12 truststore file that holds the certificate(s) for HTTPS connections from JOC Cockpit to a Controller instance, LDAP server etc.
    • Users are free to specify any file name, typically the name https-truststore.p12 is used. The truststore file will be copied to the <home>
    • jetty.ssl.host: optionally specifies the network interface that is available from the --http-port option provided that the port is prefixed with the network interface, for example joc.example.com:4446.
    • jetty.ssl.port: specifies the HTTPS port that is automatically updated from the --http-port option.
    jetty.sslContext.keyStorePath: specifies the path to the keystore relative to the <home>/jetty_base/resources/joc directory directory.
    • Further settings in the If a truststore file is made available then the JOC Cockpit's <home>/jetty_base/start.d/ssl.ini file such as the keystore password have to be deployed from a copy of the file using has to hold a reference to the truststore location and optionally the truststore password. It is therefore recommended to use the --ini option .
    • Assigning a keystore for HTTPS connections disables HTTP access and enables HTTPS access only to JOC Cockpit. The same port is alternatively used for HTTP and HTTPS connections.
  • --truststore-file
    • Specifies the path to a PKCS12 truststore file that holds the certificate(s) for HTTPS connections from JOC Cockpit to a Controller instance, LDAP server etc.
    • Users are free to specify any file name, typically the name https-truststore.p12 is used. The truststore file will be copied to the <home>/jetty_base/resources/joc directory.
    • If a truststore file is made available then the JOC Cockpit's <home>/jetty_base/start.d/ssl.ini file has to hold a reference to the truststore location and optionally the truststore password. It is therefore recommended to use the --ini option to deploy an individual ssl.ini file. The following settings are automatically updated in the ssl.ini file:
      • jetty.sslContext.trustStorePath: specifies the path to the truststore relative to the <home>/jetty_base/resources/joc directory.
    • Further settings in the ssl.ini file such as the truststore password have to be deployed from a copy of the file using the --ini option.
  • --truststore or --truststore-files
    
    • The JOC Cockpit installer is used with the joc_install.xml response file. This file is available after extraction of the installer tarball and specifies options for installation of the JOC Cockpit. The file is applied when invoking the installer by ./setup.sh -u joc_install.xml, see JS7 - JOC Cockpit - Headless Installation on Linux and Windows.
    • Users should keep their copy of the response file and specify the path with this command line option. Response files can be re-used within the same minor release of the JOC Cockpit, for example when updating from release 2.3.1 to 2.2.4. When updating, for example, from release 2.2.x to 2.3.x it is recommended a check is carride out from the installer tarball if a newer version of the file is available.
    • Users should note that the response file can hold references to a license file and to a JDBC Driver .jar file. The JOC Cockpit setup is executed from the directories specified with the --setup-dir option. Paths can be used relative to this directory.
  • --backup-dir
    • If a backup directory is specified then an existing JOC Cockpit's installation directory will be added to a .tar.gz file in this directory.
    • File names are created according to the pattern: backup_js7_joc.<hostname>.<release>.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.tar.gz
    • For example: backup_js7_joc.centostest_primary.2.3.1.2022-03-19T20-50-45.tar.gz
  • --log-dir
    • If a log directory is specified then the installer script logs information about processing steps to a log file in this directory.
    • File names are created like this: install_js7_joc.<hostname>.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.log
    • For example: install_js7_joc.centostest_primary.2022-03-19T20-50-45.log
  • --http-port
    • Optionally specifies the HTTP/HTTPS port that the JOC Cockpit is operated for. This argument takes precedence over the port setting in the joc_install.xml response file.
    • Only one of the protocols HTTP or HTTPS can be used as it undermines security to operate JOC Cockpit for both protocols at the same time.
    • The port can be prefixed by the network interface, for example joc.example.com:4446.
    • Use of HTTPS connections requires additional settings, see --ini , --keystore-file and --truststore-file options.
    • When used with the --restart switch, the HTTP/HTTPS port is used to determine if JOC Cockpit is running.
  • --ini
    • Specifies one or more *.ini files that include settings for the Jetty Servlet Container, for example http.ini, https.ini, ssl.ini. The files will be copied to the JOC Cockpit installation directory. For use with HTTPS connections the following settings in the ssl.ini file have to be adjusted:
      • jetty.sslContext.keyStorePath
      • jetty.sslContext.keyStorePassword
      • jetty.sslContext.keyManagerPassword
      • jetty.sslContext.trustStorePath
      • jetty.sslContext.trustStorePassword
    • The option takes a number of files as arguments that are separated by comma, for example: --ini="/js7-deployment/ssl.ini,/js7-deployement/https.ini".
  • --keystore-file
  • --exec-start
    • This option can be used if the JOC Cockpit has been started after installation from an individual command. For example, when using systemd then the option --exec-start="sudo systemctl start joc" will start the JOC Cockpit provided that the joc.service file is configured for systemd.
    • For systemd service files see JS7 - systemd Service Files for automated Startup and Shutdown with Unix Systems.
    • This option is an alternative for use of the -restart switch that starts the JOC Cockpit from its Start Script. If specified this option overrules the --restart switch.
  • --exec-stop
    • This option can be used if the JOC Cockpit has been stopped before installation from an individual command. For example, when using systemd then the option --exec-stop="sudo systemctl stop joc" will stop the JOC Cockpit provided that the joc.service file is configured for systemd.
    • For systemd service files see the JS7 - systemd Service Files for automated Startup and Shutdown with Unix Systems aticle.
    • This option is an alternative to use of the -restart switch that stops the JOC Cockpit from its Start Script. If specified this option overrules the --restart switch.
  • --return-values
    • Optionally specifies the path to a file which return values will be added to in the format <name>=<key>. For example:
      • log_file=install_js7_joc.centostest_primary.2022-03-20T04-54-31.log
      • backup_file=backup_js7_joc.centostest_primary.2.3.1.2022-03-20T04-54-31.tar.gz
    • An existing file will be overwritten. It is recommended that a unique file name such as /tmp/return.$$.$RANDOM.properties is used.
    • A value from the file can be retrieved like this:
      • backup=$(cat /tmp/return.$$.$RANDOM.properties | grep "backup_file" | cut -d'=' -f2)
  • • to deploy an individual ssl.ini file. The following settings are automatically updated in the ssl.ini file:
      • jetty.sslContext.trustStorePath: specifies the path to the truststore relative to the <home>/jetty_base/resources/joc directory.
    • Further settings in the ssl.ini file such as the truststore password have to be deployed from a copy of the file using the --ini option.
  • --truststore
    
    • The JOC Cockpit installer is used with the joc_install.xml response file. This file is available after extraction of the installer tarball and specifies options for installation of the JOC Cockpit. The file is applied when invoking the installer by ./setup.sh -u joc_install.xml, see JS7 - JOC Cockpit - Headless Installation on Linux and Windows.
    • Users should keep their copy of the response file and specify the path with this command line option. Response files can be re-used within the same minor release of the JOC Cockpit, for example when updating from release 2.3.1 to 2.2.4. When updating, for example, from release 2.2.x to 2.3.x it is recommended a check is carride out from the installer tarball if a newer version of the file is available.
    • Users should note that the response file can hold references to a license file and to a JDBC Driver .jar file. The JOC Cockpit setup is executed from the directories specified with the --setup-dir option. Paths can be used relative to this directory.
  • --key
    • Specifies the path to the file that holds the private key that should be added to the keystore.
    • This argument is required if a keystore should be created, see --keystore.
  • --cert
    • Specifies the path to the file that holds the certificate that should be added to the keystore.
    • This argument is required if a keystore should be created, see --keystore.
  • --alias
    • Specifies the alias name of the private key and certificate entry in the keystore.
    • This argument is required if a keystore should be created, see --keystore.
  • --password
    • Specifies the password that protects the keystore and truststore.
    • Passwords for certificate stores are not intended to improve security but to prevent users from shooting themselves in their foot. For a keystore the password protects read and write access, for a truststore the password protects write access.
    • This argument is required if a keystore or truststore should be created, see --keystore, --truststore.
  • ca-bundle
    • Specifies the path to a CA Bundle file that holds the CA Intermediate certificate(s) and Root CA certificate in the indicated sequence.
    • This argument is required if a keystore should be created and the --chain switch is used. In addition this argument is required if a truststore should be created an no Root CA certificate is specified, see --ca-root.
  • ca-root
    • Specifies the path to a CA Root Certificate file.
    • This argument is required if no CA Bundle file is specified, see --ca-bundle, and a keystore should be created with the --chain argument. In addition this argument is required if a truststore should be created using the --truststore option and no CA Bundle file is specified, see --ca-bundle option.
  • ca-intermediate
    • Specifies the path to one or more CA Intermediate Certificate files.
    • If more than one file is specified then file names have to be separated by comma, for example --ca-intermediate="./certs/intermediate-ca-1.crt,./certs/intermediate-ca-2.crt".
    • This argument is required if no CA Bundle file is specified, see --ca-bundle, and a keystore should be created with the --chain argument.
  • --backup-dir
    • If a backup directory is specified then an existing keystore and truststore will be added to a .tar.gz file in this directory.
    • File names are created according to the pattern: backup_js7_certificate_store.<hostname>.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.tar.gz
    • For example: backup_js7_certificate_store.centostest_primary.2022-03-19T20-50-45.tar.gz
  • --log-dir
    • If a log directory is specified then the installer script logs information about processing steps to a log file in this directory.
    • File names are created like this: certificate_store._js7.<hostname>.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.log
    • For example: certificate_store_js7.centostest_primary.2022-03-19T20-50-45.log
• Switches
  • -h | --help
    • Displays usage.
  • --chain
  Switches
  • -h | --help
    • Displays usage.
  • -u | --user
    • Installs the JOC Cockpit configuration directory for the current user account, the installation directory is created by the root account using sudo. This switch corresponds to use of ./setup.sh -u joc_install.xml, see the JS7 - JOC Cockpit - Headless Installation on Linux and Windows for more information.
  • -E | --preserve-env
    • When installing for the current user account using the -u switch then environment variables are preserved when switching to the root account using sudo -E. This switch corresponds to use of ./setup.sh -u -E joc_install.xml.
  • --show-logs
    • Displays the log output created by the script.
  • --make-dirs
    • If directories are missing that are indicated with the --home, --backup-dir or --log-dir options then they will be created.
  • --restart
    • Stops a running JOC Cockpit before installation and starts the JOC Cockpit after installation using the JOC Cockpit's Start Script. This switch can be used with the --kill switch to control the way how JOC Cockpit is terminated. This switch is ignored if the --exec-start and --exec-stop options are used. switch to control the way how JOC
  • --show-logs
    • Displays the log output created by the script.
  • --make-dirs
    • If directories are missing that are indicated with the --keystore, --truststore, --backup-dir or --log-dir options then they will be created
    --kill
    • Kills a running JOC Cockpit if used with the --restart switch. This includes killing child processes of running tasks.
• Exit Codes
  • 1: argument errors
  • 2: non-recoverable errors
  • 3: this exit code is returned when used with the --restart switch and if it cannot be identified if a JOC Cockpit instance is running
  • 4: this exit code is returned if no --tarball option is used and download of the tarball reports errors
  • 5: this exit code is returned when used with the --restart switch and if the JOC Cockpit instance cannot be started
  • 6: this exit code is returned when used with the --restart switch and if the JOC Cockpit instance cannot be stopped
  • 7: this exit code indicates that the JOC Cockpit installation has failed
  • 8: this exit code indicates failure of the JOC Cockpit installation from logs

...