Skip to main content
Skip table of contents

HCMS Command Line Interface Tool

Explains how to use the HCMS Command Line Tool to administrate HCMS configurations

Overview

The goal of the HCMS command line client (CLI) is to simplify administration and provide support for automation. It is intended to be used in conjunction with the HCMS docker image. Older, manually created configurations may not be supported. The CLI can be downloaded from the Download Portal.

Invocation

Each invocation needs some global options (-s, -u, etc) command (usually combination of command and sub-command), its arguments and its options.
Available options, arguments and (sub-)commands can be always displayed by special option --help. Note that each (sub-)command has its own options and they cannot be mixed with global ones (i.e. -s, -u, -p and -f must be always specified before any command).

Global command line options

Credentials

User credentials are always mandatory. They can either be set by command line option or by environment variable

-s --server <RMI-URL>

Provides the RMI URL of the application server. Has precedence over the environment variable HCMS_SERVER.

-u -user <USER_NAME>

Provides application server user used. Has precedence over the environment variable HCMS_USER.

Note that the user must have sufficient permissions to execute all necessary administration tasks (service configuration, module configuration) and to create and/or modify assets in root. domain.
The default censhare user is the obvious choice, but any other administrator user in root. domain can be used instead.

-p -password <PASSWORD>

Provides application server password used. Used only when the hostname in server url is not a localhost (in that case, special password-less authentication method is used).

There are four possible ways to provide password, evaluated in this order:

  1. command-line option --password (-p)
  2. environment variable HCMS_PASSWORD
    • Note that there is a difference between unset variable and variable with empty content; the latter case is valid password of zero length.
  3. OS X Keychain Access password
    • Available only on OS X, automatically skipped on other platforms.
    • Keychain Item Name is the server URL.
    • Access to the password usually require user to enter their password. Denying access (the "Deny" button in confirmation dialog) just skips this step.
  4. Interactive prompt from terminal (console).
    • User is asked for the password only as a last resort, and only when both standard input and output are connected to real terminal. If any of them is redirected or the environment does not provide real terminal capabilities, program displays error message and exits with error status 2.

Important note: for password authentication, only users with internal authorization type are supported. This means that in version 2021.2 and higher, this user must be a special "system user" that is not authenticated via Keycloak. Alternatively, the tool can be run from the censhare server itself with localhost url, which bypasses the password authentication entirely.

Aromatization

-f --force

Do not prompt for confirmation and continue.

Commands

Application Server hcms server

hcms server status

Indicates whether the services of the application server required for the satellites are active.

hcms server enable

Activates the services of the application server required for the satellites.

hcms server disable

Turns off the services required for the satellites on the application server.

Administrate Domains

Note that commands domain and domain2 are exactly the same, except the type of domain they manage.

hcms domain create <KEY> [<OPTIONS>]

Creates a new domain and returns a YAML representation of the value.

Options:

  • -n --name <NAME>: Sets the server ui name for the domain. This option is mandatory. If this parameter is not specified, the value of <KEY> is used as the default value.
  • -s --sorting <VALUE>: Sets the "sorting" value (integer number used to sort domains in UI listings). If this parameter is not specified, default value 999 is used.

hcms domain list

Displays all current domain values as YAML.
Note that disabled domains are not included in this list.

Example:

YAML 
  - key: root.
    name: Root
    sorting: 300
    enabled: true
  - key: root.portal2.
    name: domain for portal2
    sorting: 300
    enabled: true
  - key: root.portal3.
    name: Experimental portal 3
    sorting: 300
    enabled: true
  - key: root.portal3.system.
    name: Media Portal kpo00005 - system
    sorting: 300
    enabled: true

hcms domain inspect <KEY>

Displays the domain specified by <KEY> as YAML.

Example:

YAML 
key: root.
name: Root
name_de: Root
sorting: 1
enabled: true

hcms domain update <KEY> [OPTIONS]

Updates the specified attributes of the domain value specified by <KEY>.
If the domain is currently disabled, it will be automatically enabled.

Options:

  • -n --name <NAME>: Sets the server ui name for the domain. If this parameter is not specified, the value of <KEY> is used as the default value.
  • -s --sorting <VALUE>: Sets the "sorting" value (integer number used to sort domains in UI listings). If this parameter is not specified, default value 999 is used.
  • --disabled: Domain (and all its subdomain) is disabled. Disabled domains are omitted form all listing (including the domain list command and Java Client), but they remain assigned to all assets and entities. If this parameter is not specified, domain is enabled.

hcms domain delete <KEY> [--replace-by <RKEY>]

Deletes the domain specified by <KEY>. All existing usages of this domain (assets, masterdata entities) will be replaced by <RKEY> (root. by default).

Note that if the deleted domain has any subdomains, they will be all deleted (the whole subtree). Addition confirmation is required in this case (separate from the usual "are you sure?" query).

  • --replace-by <KEY>: Use specified domain as a replacement of the deleted one. This domain must already exist. If this parameter is not specified, root. is used.

Administrate Output Channels

hcms channel create <KEY> [<OPTIONS>]

Creates a new Output Channel value and returns a YAML representation of the value.

Options:

  • -n --name <NAME>: Sets the server ui name for the default locale. If this parameter is not specified, the value of <KEY> is used as the default value.
  • -N <LOCALE>=<NAME>: Sets the server ui name for the locale <LOCALE>. If this parameter is not specified, there is no specific name for this locale.
  • -d --description <NAME>: Sets the server ui description for the default locale. If this parameter is not specified, an empty content is used.
  • -D <LOCALE>=<NAME>: Sets the server ui description for the locale <LOCALE>. If this parameter is not specified, there is no specific description for this locale.
  • -domain <NAME> Determines the value of the attribute domain. If this parameter is not specified, root. is used as the default value.
  • -domain2 <NAME>Determines the value of the attribute domain2. If this parameter is not specified, root. is used as the default value.
  • -s --sorting <VALUE>: Sets the "sorting" value (integer number used to sort domains in UI listings). If this parameter is not specified, default value 999 is used.

hcms channel list

Displays the current Output Channel values as YAML.
Note that disabled channels are not included in this list.

Example:

YAML 
  - key: root.
    name: Output channel
    name_de: Ausgabekanal
    domain: root.
    domain2: root.
    sorting: 1
    enabled: true
  - key: root.print.
    name: Print
    name_de: Print
    domain: root.
    domain2: root.
    sorting: 1
    enabled: true
  - key: root.web.
    name: Web
    name_de: Web
    domain: root.
    domain2: root.
    sorting: 2
    enabled: true
  - key: root.web.bnt.
    name: Output channel for brandnewtest
    domain: root.
    domain2: root.
    sorting: 300
    enabled: true
  - key: root.web.brandnew.
    name: Output channel for brandnew
    domain: root.
    domain2: root.
    sorting: 300
    enabled: true

hcms channel inspect <KEY>

Displays the output channel value specified by <KEY> as YAML.

Example:

YAML 
key: root.
name: Output channel
name_de: Ausgabekanal
domain: root.
domain2: root.
sorting: 1
enabled: true

hcms channel update <KEY> [OPTIONS]

Updates the specified attributes of the output channel value specified by <KEY>.
If the domain is currently disabled, it will be automatically enabled.

Options:

  • -n --name <NAME>: Sets the server ui name for the default locale.
  • -N <LOCALE>=<NAME>: Sets the server ui name for the locale <LOCALE>. Empty value removes locale-specific name. If this parameter is not specified, value is not changed.
  • -d --description <NAME>: Sets the server ui description for the default locale.
  • -D <LOCALE>=<NAME>: Sets the server ui description for the locale <LOCALE>. Empty value removes locale-specific description. If this parameter is not specified, value is not changed.
  • -domain <NAME> Determines the value of the attribute domain.
  • -domain2 <NAME>Determines the value of the attribute domain2.
  • -s --sorting <VALUE>: Sets the "sorting" value (integer number used to sort domains in UI listings). If this parameter is not specified, value is not changed.
  • --disabled: Domain (and all its subdomain) is disabled. Disabled domains are omitted form all listing (including the domain list command and Java Client), but they remain assigned to all assets and entities. If this parameter is not specified, domain is enabled.

hcms channel delete <KEY> [--replace-by <RKEY>]

Deletes the output channel specified by <KEY>. All existing usages of this channel will be replaced by <RKEY> (root. by default).

Note that if the deleted output channel has any subchannel, they will be all deleted (the whole subtree). Addition confirmation is required in this case (separate from the usual "are you sure?" query).

  • --replace-by <KEY>: Use specified output channel as a replacement of the deleted one. This output channel must already exist. If this parameter is not specified, root. is used.

Administrate Configurations

hcms configuration create <KEY> [<OPTIONS>]

Creates a new configuration and outputs it as YAML. The implicitly includes the following steps:

TEXT 
hcms server enable
hcms authentification create <KEY> --basic --name admin --password <RANDOM> --roles *
hcms group create <KEY> <KEY>:default1

Options:

  • -n --name <NAME>: Specifies the display name of the configuration. By default, the value of <KEY> is used.
  • --user-tracking <true|false> Enables or disables user tracking for HCMS Client framework. This consists of predefined statistic group hcms-client.user-tracking and request logging that uses this group.
    • Note that custom configuration of request logging is not available via commandline client yet. It will be added in one of the future versions.
  • -wc --write-channel <PRIMARY_CHANNEL> Specifies the output channel value that is automatically assigned to entities created or modified by hcms, unless explicitly overwritten in the schema. If no value is specified, root.hcms is used.
  • -rc --read-channels <READ_CHANNELS> A comma-separated list of output channel values. Only assets that are assigned an output channel value corresponding to one of these lists can be read via hcms. It is allowed to append .* to output channel values to indicate that the value and all child values are allowed. If no value is specified, root.hcms is used. Example: --read-channels root.site1.*,root.site2.ugc
  • -d --domain <DOMAIN> Specifies the domain attribute that is automatically assigned to entities created or modified by hcms, unless explicitly overwritten in the schema. If no value is specified, root. is used.
  • -d2 --domain2 <DOMAIN2> Specifies the domain2 attribute that is automatically assigned to entities created or modified by hcms, unless explicitly overwritten in the schema. If no value is specified, root. is used.
  • -nnm --no-new-masterdata [true|false] Prevents the automatic creation of master data definitions by schemas. If no value is specified, true is used.
  • -unv --update-new-version <true|false> Create new version on each update. Disabled by default. Requires server version 2019.2 to work correctly.
  • -pp --url-patch-prefix <path> Prefix of hcms endpoint url path. It is either empty (no prefix, hcms is available directly at /hcms/v1.0) or starts with slash.
  • --forwarded [true|false] Enables use of X-Forwarded-* and Forwarded HTTP headers. If no value is specified, false is used (that is, headers are not trusted).
    • Note that proper and secure configuration depends on the specific Load Balancer; details are in ecosphere article.
  • --forwarded-levels <number> Limits the maximum depth of HTTP proxies accepted in forwarded requests (X-Forwarded-* HTTP headers). If no value is specified, there is no limit - any number of nested values is accepted. Used only when forwarded is true.
  • -H <header:value> or --add--header <header:value> Adds a constant value for single header, directly in the HTTP server configuration.
    • This header will be added to each and every response regardless of the request.
    • Useful for security headers like X-Frame-Options, Strict-Transport-Security and similar. X-Content-Type-Options:nosniff is added automatically.
    • Note that the header name and value is separated by a colon, without space. Any spaces in the value itself must be escaped, or the whole argument must be put inside quotes.
    • Warning: header names and their values are not validation in any way. Some headers are very dangerous and setting them this way would completely break the application, or even the HTTP protocol itself.
  • --remove-header <headername> Removes one header from the list of constant headers.
    • The only meaningful value for configuration create is --remove-header X-Content-Type-Options, because that is the only hardcoded header added by default.
  • -s --storage local | s3push -s3bucket <bucket> [-s3region <region>] -s3secretKey <key> -s3accessKey <key> Specifies how binary data is managed by the satellites. -local Binary data associated with the asset is copied to the satellites. This is the default mode. -s3push -s3bucket <bucket> -s3key <key> Binary data associated with the asset are stored in the specified S3 bucket by the application server and are shared by the satellites. Requires several additional options:
    • -s3bucket <bucket> Id of the AWS bucket.
    • -s3region <region> AWS region. This option is not required, default region is eu-central-1.
    • -s3accessKey <key> Access key with permissions to use (read, write) the bucket. Optional is both satellite and server are on EC2 infrastructure with permissions provided via roles.
    • -s3secretKey <key> Secret key (password) with permissions to use (read, write) the bucket. Required if and only if -s3accessKey <key> is also specified.
  • --image-cache-disable Disable the dynamic image cache. Mutually exclusive with all other --image-cache-* options.
  • Dynamic image cache options form a group:
    • --image-cache-max-size Specifies size of the dynamic image cache, in megabytes. Mandatory, if the cache should be enabled.
    • --image-cache-max-age Specifieds expiration time of the dynamic image cache records, in minutes. Mandatory, if the cache should be enabled.
    • --image-cache-storage-item Specifies storage item used as a source for all image variants. If no value is specified, master is used.
    • --image-cache-default-format Specifies default image format of the generated images; it is either png or jpg. If no value is specified, png is used. Note that this value is used only when auto-detection is disabled, or if the original image is neither jpg nor png.
    • --image-cache-autodetect Specifies whether format of generated images should be the same as the format of original base image (png or jpeg). If no value is specified, automatic format detection is enabled.
    • --image-cache-s3bucket, --image-cache-s3region, --image-cache-s3accessKey, --image-cache-s3secretKey Specify AWS S3 bucket used to store the dynamic image cache content. Region is optional (eu-central-1 is the default value), keys are optional too but they must be always specified in pair (either both of them, or neither of them). If none of them are specified, dynamic image cache will use local directory (/opt/corpus/censhare-Satellite/dic) inside docker container to store the content.
  • --mgmt-domain <DOMAIN> Specifies the domain of all the newly created assets. If no value is specified, root. is used. If there are any filters defined in SatelliteManagementService, value of this option must match at least one of them.
  • --mgmt-domain2 <DOMAIN> Specifies the domain2 of all the newly created assets. If no value is specified, root. is used. If there are any filters defined in SatelliteManagementService, value of this option must match at least one of them.
  • --schema-resource-key <resource-key> Specifies resource key of the asset that contains all schemas. If no value is provided, default value is constructed from the write channel.
    • If this asset already exists, it's type and content is checked to be a valid schema storage. An existing asset with wrong type is considered a configuration error.
    • If the asset does not exist yet, it is created (with empty content).
    • In either case, all output channels are added to this asset to make sure it is visible by the satellite. This ensures that the same asset can be shared between different configurations with different channels.
YAML 
key: news-live
name: News feed live
write_channel: root.hcms.pwa.live.
read_channels:
  - root.hcms.pwa.live.
domain: root.
domain2: root.
no_new_masterdata: true
update_new_version: false
forwarded: false
storage:
    type: s3push
    defaults:
        bucket: asdfghjkl
        region: eu-central-1
        access_key: asdffhh
        secret_key: qwertyyre
    satellite_buckets: []
    server_buckets:
      - bucket: asdfghjkl
        region: eu-central-1
        access_key: asdffhh
        secret_key: qwertyyre
authorization_providers:
  - type: basic
    users:
      - name: admin
        password: F/~,+|GP}h
        roles:
          - '*'
groups:
  - id: news-live:default1
    name: news-live:default1
    certificate:
        subject: CN=news-live:default1
        valid:
            from: 2019-05-02T09:59:22Z
            until: 2119-05-02T09:59:22Z
        algorithm: SHA256WITHRSA
        issuer: CN=news-live:default1
        serial: 016a77fbf5df
        signature: 7d9660da404786ab6b286ea281bb4f33054414ca37e27bec2d79bfedf2d60bdd29ee75ba9c0c1891e83abf51d8b303eb439e738f25de2de1e706972cd0a6f2ecef4b2e620942390a929580514f1ae30cd82ed7995f70078943aba551fd175f82835506f1bdcb77bb0fda10d8fc13fd5913ddd8a322fc9e118ac1da59b45147677980cbf98562fc8f76b4b46bd5b5e6d688ed45a575cf544d494bd48eb40bcd0af9c6ca77877bd5294c3aaf0b2df632472e916a61a60fdd078c6fe7c1b042887194d26e81d69c0515f28069751f8e13597589966f8750a324588adb95e7216dab946e3b5bde45564828e611267dd2d6095f582c6ebea833da1a59e36966e72ecb
        pem: |
            -----BEGIN CERTIFICATE-----
            MIICujCCAaKgAwIBAgIGAWp3+/XfMA0GCSqGSIb3DQEBCwUAMB0xGzAZBgNVBAMT
            Em5ld3MtbGl2ZTpkZWZhdWx0MTAgFw0xOTA1MDIwOTU5MjJaGA8yMTE5MDUwMjA5
            NTkyMlowHTEbMBkGA1UEAxMSbmV3cy1saXZlOmRlZmF1bHQxMIIBIjANBgkqhkiG
            9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwklsXU5Ewt78dSPbs94ASQB4e5FTeMitHWxd
            i+xkDIY/OF84bFF5bzmi3SIHhVF71Q6IiPJe8RUlo/jz8EdsTtSp7/UKEqfkmE7e
            gn7YBdRNbU9shkJV+iy8YtobuAwH6lVwVTYolVPcUNCrJt9+eCSzOOwbV2CTrGJv
            ASdAE1+KWf2s/YWBgO4MyF2isdqBDlKwm4cXnckmfy7HhuEV6ucNxvQWmTHfDpfr
            a7qxYI0u5WXl+JqyZ7PmYtVRkC8Jgxv9W4hNKoLSephu8PlW7sT2VoNVlGjTXdjg
            GO0MoiQ94Wu7RppYAMZUVhFLwLnA5boWoJVv+jims6WtOw2F2wIDAQABMA0GCSqG
            SIb3DQEBCwUAA4IBAQB9lmDaQEeGq2sobqKBu08zBUQUyjfie+wteb/t8tYL3Snu
            dbqcDBiR6Dq/UdizA+tDnnOPJd4t4ecGlyzQpvLs70suYglCOQqSlYBRTxrjDNgu
            15lfcAeJQ6ulUf0XX4KDVQbxvct3uw/aENj8E/1ZE93YoyL8nhGKwdpZtFFHZ3mA
            y/mFYvyPdrS0a9W15taI7UWldc9UTUlL1I60C80K+cbKd4d71SlMOq8LLfYyRy6R
            amGmD90HjG/nwbBCiHGU0m6B1pwFFfKAaXUfjhNZdYmWb4dQoyRYituV5yFtq5Ru
            O1veRVZIKOYRJn3S1glfWCxuvqgz2hpZ42lm5y7L
            -----END CERTIFICATE-----

hcms configuration list

Displays the current configurations as YAML.

Note that for brevity and to limit exposition of sensitive data, this listing does not contain:

  • full certificates (in PEM format)
  • signatures of certificates
  • password
  • JWT secrets

Example:

YAML 
  - key: corpus:16112
    name: Satellite Configuration for kris0119
    write_channel: root.web.kris0119.
    read_channels:
      - root.web.kris0119.
    domain: root.
    domain2: root.
    no_new_masterdata: false
    update_as_new_version: false
    forwarded: true
    forwarded_levels: 1
    url_path_prefix: /app/kris0119
    storage:
        type: s3push
        defaults:
            bucket: cs-portal-kris0119-dev-data
            region: eu-central-1
            access_key: AKIA57HXKG2F6UES
            secret_key: RJmo5g/v94DGbNG8wHdcVmcN/t+HqJU71t
        satellite_buckets: []
        server_buckets:
          - bucket: cs-portal-kris0119-dev-data
            region: eu-central-1
            access_key: AKIA57HXKG2F6UES
            secret_key: RJmo5g/v94DGbNG8wHdcVmcN/t+HqJU71t
    authorization_providers:
      - type: jwt
        secret: l83NTXxf1eo3AcUyHOZ1sEVKa2bmZc5QlYr8kSpVKjhc
        cookie:
            name: access_token
            maxAge: unlimited
            insecure: false
            http-only: false
      - type: basic
        users:
          - name: system
            roles:
              - '*'
      - type: ip
        ranges:
          - start: 127.0.0.1
            end: 127.0.0.1
            roles:
              - '*'
    groups:
      - id: kris0119-96e71474-3e35-483e-ae98-32765a0cacba
        name: Satellite group kris0119-96e71474-3e35-483e-ae98-32765a0cacba
        certificate:
            subject: CN=kris0119-96e71474-3e35-483e-ae98-32765a0cacba
            valid:
                from: 2019-04-09T12:56:42Z
                until: 2019-04-09T12:56:42Z
            algorithm: SHA1WITHRSA

hcms configuration inspect <KEY>

Displays the configuration specified by <KEY> as YAML.

Note that output of this command contains sensitive data, in particular basic authentication passwords and JWT secrets.

Example:

YAML 
key: news-live
name: News feed live
write_channel: root.hcms.pwa.live.
read_channels:
  - root.hcms.pwa.live.
domain: root.
domain2: root.
no_new_masterdata: true
update_new_version: false
forwarded: false
storage:
    type: s3push
    defaults:
        bucket: asdfghjkl
        region: eu-central-1
        access_key: asdffhh
        secret_key: qwertyyre
    satellite_buckets: []
    server_buckets:
      - bucket: asdfghjkl
        region: eu-central-1
        access_key: asdffhh
        secret_key: qwertyyre
authorization_providers:
  - type: basic
    users:
      - name: admin
        password: F/~,+|GP}h
        roles:
          - '*'
groups:
  - id: news-live:default1
    name: news-live:default1
    certificate:
        subject: CN=news-live:default1
        valid:
            from: 2019-05-02T09:59:22Z
            until: 2119-05-02T09:59:22Z
        algorithm: SHA256WITHRSA
        issuer: CN=news-live:default1
        serial: 016a77fbf5df
        signature: 7d9660da404786ab6b286ea281bb4f33054414ca37e27bec2d79bfedf2d60bdd29ee75ba9c0c1891e83abf51d8b303eb439e738f25de2de1e706972cd0a6f2ecef4b2e620942390a929580514f1ae30cd82ed7995f70078943aba551fd175f82835506f1bdcb77bb0fda10d8fc13fd5913ddd8a322fc9e118ac1da59b45147677980cbf98562fc8f76b4b46bd5b5e6d688ed45a575cf544d494bd48eb40bcd0af9c6ca77877bd5294c3aaf0b2df632472e916a61a60fdd078c6fe7c1b042887194d26e81d69c0515f28069751f8e13597589966f8750a324588adb95e7216dab946e3b5bde45564828e611267dd2d6095f582c6ebea833da1a59e36966e72ecb
        pem: |
            -----BEGIN CERTIFICATE-----
            MIICujCCAaKgAwIBAgIGAWp3+/XfMA0GCSqGSIb3DQEBCwUAMB0xGzAZBgNVBAMT
            Em5ld3MtbGl2ZTpkZWZhdWx0MTAgFw0xOTA1MDIwOTU5MjJaGA8yMTE5MDUwMjA5
            NTkyMlowHTEbMBkGA1UEAxMSbmV3cy1saXZlOmRlZmF1bHQxMIIBIjANBgkqhkiG
            9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwklsXU5Ewt78dSPbs94ASQB4e5FTeMitHWxd
            i+xkDIY/OF84bFF5bzmi3SIHhVF71Q6IiPJe8RUlo/jz8EdsTtSp7/UKEqfkmE7e
            gn7YBdRNbU9shkJV+iy8YtobuAwH6lVwVTYolVPcUNCrJt9+eCSzOOwbV2CTrGJv
            ASdAE1+KWf2s/YWBgO4MyF2isdqBDlKwm4cXnckmfy7HhuEV6ucNxvQWmTHfDpfr
            a7qxYI0u5WXl+JqyZ7PmYtVRkC8Jgxv9W4hNKoLSephu8PlW7sT2VoNVlGjTXdjg
            GO0MoiQ94Wu7RppYAMZUVhFLwLnA5boWoJVv+jims6WtOw2F2wIDAQABMA0GCSqG
            SIb3DQEBCwUAA4IBAQB9lmDaQEeGq2sobqKBu08zBUQUyjfie+wteb/t8tYL3Snu
            dbqcDBiR6Dq/UdizA+tDnnOPJd4t4ecGlyzQpvLs70suYglCOQqSlYBRTxrjDNgu
            15lfcAeJQ6ulUf0XX4KDVQbxvct3uw/aENj8E/1ZE93YoyL8nhGKwdpZtFFHZ3mA
            y/mFYvyPdrS0a9W15taI7UWldc9UTUlL1I60C80K+cbKd4d71SlMOq8LLfYyRy6R
            amGmD90HjG/nwbBCiHGU0m6B1pwFFfKAaXUfjhNZdYmWb4dQoyRYituV5yFtq5Ru
            O1veRVZIKOYRJn3S1glfWCxuvqgz2hpZ42lm5y7L
            -----END CERTIFICATE-----

hcms configuration update <KEY> [OPTIONS]

Updates the specified attributes of the configuration specified by <KEY>.

Options (all of them are optional, missing option means that value is left unchanged):

  • -n --name <NAME>: Specifies the display name of the configuration.
  • --user-tracking <true|false> Enables or disables user tracking for HCMS Client framework. This consists of predefined statistic group hcms-client.user-tracking and request logging that uses this group.
    • Note that custom configuration of request logging is not available via commandline client yet. It will be added in one of the future versions.
  • -wc --write-channel <PRIMARY_CHANNEL> Specifies the output channel value that is automatically assigned to entities created or modified by hcms, unless explicitly overwritten in the schema.
  • -rc --read-channels <READ_CHANNELS> A comma-separated list of output channel values. Only assets that are assigned an output channel value corresponding to one of these lists can be read via hcms. It is allowed to append .* to output channel values to indicate that the value and all child values are allowed. Example: --read-channels root.site1.*,root.site2.ugc
  • -d --domain <DOMAIN> Specifies the domain attribute that is automatically assigned to entities created or modified by hcms, unless explicitly overwritten in the schema.
  • -d2 --domain2 <DOMAIN2> Specifies the domain2 attribute that is automatically assigned to entities created or modified by hcms, unless explicitly overwritten in the schema.
  • -nnm --no-new-masterdata <true|false> Prevents the automatic creation of master data definitions by schemas.
  • -unv --update-new-version <true|false> Create new version on each update. Disabled by default. Requires server version 2019.2 to work correctly.
  • -pp --url-patch-prefix <path> Prefix of hcms endpoint url path. It is either empty (no prefix, hcms is available directly at /hcms/v1.0) or starts with slash.
  • -H <header:value> or --add--header <header:value> Adds a constant value for single header, directly in the HTTP server configuration.
    • This header will be added to each and every response regardless of the request. Useful for security headers like X-Frame-Options, Strict-Transport-Security and similar.
    • Note that the header name and value is separated by a colon, without space. Any spaces in the value itself must be escaped, or the whole argument must be put inside quotes.
  • --remove-header <headername> Removes one header from the list of constant headers.
    • Note that there is no value here; all values for the given header are removed.
  • -s --storage local | s3push -s3bucket <bucket> [-s3region <region>] -s3secretKey <key> -s3accessKey <key> Specifies how binary data is managed by the satellites. If this options is not specified, storage configuration is left unchanged. -local Binary data associated with the asset is copied to the satellites. -s3push -s3bucket <bucket> -s3key <key> Binary data associated with the asset are stored in the specified S3 bucket by the application server and are shared by the satellites. Requires several additional options:
    • -s3bucket <bucket> Id of the AWS bucket.
    • -s3region <region> AWS region. This option is not required, default region is eu-central-1.
    • -s3accessKey <key> Access key with permissions to use (read, write) the bucket. Optional is both satellite and server are on EC2 infrastructure with permissions provided via roles.
    • -s3secretKey <key> Secret key (password) with permissions to use (read, write) the bucket. Required if and only if -s3accessKey <key> is also specified.
  • --image-cache-disable Disable the dynamic image cache. Mutually exclusive with all other --image-cache-* options.
  • Dynamic image cache options form a group:
    • --image-cache-max-size Specifies size of the dynamic image cache, in megabytes. Mandatory, if the cache should be enabled.
    • --image-cache-max-age Specifieds expiration time of the dynamic image cache records, in minutes. Mandatory, if the cache should be enabled.
    • --image-cache-storage-item Specifies storage item used as a source for all image variants. If no value is specified, master is used.
    • --image-cache-default-format Specifies default image format of the generated images; it is either png or jpg. If no value is specified, png is used. Note that this value is used only when auto-detection is disabled, or if the original image is neither jpg nor png.
    • --image-cache-autodetect Specifies whether format of generated images should be the same as the format of original base image (png or jpeg). If no value is specified, automatic format detection is enabled.
    • --image-cache-s3bucket, --image-cache-s3region, --image-cache-s3accessKey, --image-cache-s3secretKey Specify AWS S3 bucket used to store the dynamic image cache content. Region is optional (eu-central-1 is the default value), keys are optional too but they must be always specified in pair (either both of them, or neither of them). If none of them are specified, dynamic image cache will use local directory (/opt/corpus/censhare-Satellite/dic) inside docker container to store the content.
  • --mgmt-domain <DOMAIN> Specifies the domain of all updated and created assets. If no value is specified, root. is used for new assets and domains is left unchanged for the updated ones. If there are any filters defined in SatelliteManagementService, value of this option must match at least one of them.
  • --mgmt-domain2 <DOMAIN> Specifies the domain2 of all updated and created assets. If no value is specified, root. is used for new assets and domains is left unchanged for the updated ones. If there are any filters defined in SatelliteManagementService, value of this option must match at least one of them.
  • --schema-resource-key <resource-key> Specifies resource key of the asset that contains all schemas. If no value is provided, default value is constructed from the write channel.
    • If this asset already exists, it's type and content is checked to be a valid schema storage. An existing asset with wrong type is considered a configuration error.
    • If the asset does not exist yet, it is created (with empty content).
    • In either case, all output channels are added to this asset to make sure it is visible by the satellite. This ensures that the same asset can be shared between different configurations with different channels.

hcms configuration delete <KEY> [-G]

Deletes the configuration specified by <KEY>.
All satellite groups are also deleted, unless -G option is specified.

hcms configuration change-id <KEY> <NEW-KEY>

Change the identifier (key) of configuration group from <KEY> to <NEW-KEY>.

hcms configuration status <KEY>

List all groups in given configuration and for group, list all satellites currently connected.
This command is basically the same as group status command, but for all groups in single configuration.

Note that this command is available only in censhare server of version 2018.1 and higher.

Example output:

YAML 
connected_satellites:
    docker3:default1:
      - docker3:default1-7ede1c65921c
      - docker3:default1-ac6468dccf86
    docker3:default2: []
    test3: []

Administrate Authorization Providers

hcms authorization list <KEY>

Lists all authorization providers configured for the provided configuration group.

TEXT 
  - type: jwt
    secret: 13g4TKUugjmHSlusWiNMOAB5BbtInfSJHagVr5kSzOIKDBJSRWkAdjM4nMxI
    cookie:
        name: access_token
        maxAge: unlimited
        insecure: false
        http-only: false
  - type: basic
    users:
      - name: system
        password: e292291432703ac801664a66a554c000
        roles:
          - '*'
  - type: ip
    ranges:
      - start: 127.0.0.1
        end: 127.0.0.1
        roles:
          - '*'

hcms authorization create <KEY> [Options]

Defines a new satellite authorization provider in the configuration specified by <KEY>.

<OPTIONS> are either:

  • --basic --name <NAME> [--password <PASSWORD>] --roles <ROLES>
    • Configures a basic authentication user with the login name <NAME> password <PASSWORD> and grants him the list of roles provided by <ROLES>.
    • The roles a re specified as a comma separated list of roles or a wildcard (*), representing all roles.
    • If the --password options is not present, random password is automatically generated.
    • Example: --basic --name admin --password Kd!1A --roles schema-rw,schema-ro
  • --ip --start <START_IP> --end <END_IP> --roles <ROLES>
  • Grants an IPv4 or IPv6 range from <START_IP> to end <END_IP> the list of roles provided by <ROLES>.
  • The roles a re specified as a comma separated list of roles or a wildcard (*), representing all roles.
  • --jwt --secret <SECRET> or --jwt --pem <file>
  • Configures a JWT token authorization provider with either HMAC secret or RSA public key (loaded from PEM file).
  • Both variants also accepts additional options configuring authorization cookie:
    • --cookie <name> Name of the authorization cooke. If this option is not present, HCMS accepts and creates cookie named access_token.
    • --cookie-max-age <age> Maximum age of the authorization cookie, in seconds. Negative value means that there is not expiration time. If this option is not present, HCMS does not set any expiration time.
    • --cookie-insecure <true|false> Allow authorization cookies to be used in unencrypted http request, when set to true. If this option is not present or set to false, all cookies created by HCMS will be marked as "secure" and thus sent only over HTTPS channel.
    • --cookie-http-only <true|false> Allow authorization cookies to be issued with <strong>HttpOnly</strong> flag. If this option is not present or set to false, all cookies created by HCMS will have this flag set.
    • --cookie-same-site <unset|Strict|Lax|None> Allow authorization be issued with <strong>SameSite</strong> flag. If this option is not present or set to unset, all cookies created by HCMS will not have this flag at all. The exact interpretation of the values are out of scope of this document.
  • --disable-security
    • Grants always all roles to each request.

hcms authorization inspect <KEY> <OPTIONS>

Displays the specified authorization provider configuration, or single item in that configuration (in case of basic authorization and ip ranges).

<OPTIONS> are either:

  • --basic --name <NAME>
  • --ip --start <START_IP> --end <END_IP>
  • --jwt
  • --disbale-security

hcms authorization update <KEY> <OPTIONS>

Updates the specified attributes of the provided authorization provider configuration.

<OPTIONS> are either:

  • --basic --name <NAME> [--password <PASSWORD>] [--roles <ROLES>]
    • Changes password and/or roles of basic authentication user with the login name <NAME>.
    • The roles a re specified as a comma separated list of roles or a wildcard (*), representing all roles.
    • Both --password and --roles are optional; if the option is not present, corresponding value is left unchanged.
    • Example: --basic --name admin --roles *
  • --ip --start <START_IP> --end <END_IP> --roles <ROLES>
  • Changes assigned roles of IPv4 or IPv6 range.
  • The roles a re specified as a comma separated list of roles or a wildcard (*), representing all roles.
  • --jwt [--secret <SECRET>|--pem <file>] [--cookie <cookieName>] [--cookie-max-age <cookieMaxAge>] [--cookie-insecure <cookieInsecure>] [--cookie-same-site <SameSiteValue>] [--cookie-http-only <true|false>]
  • Changes JWT configuration: either set new HMAC secret, or new public key, or change cookie configuration.
  • All options are the same as for create command; missing option means that the value is left unchanged.
  • Only one of --secret or --pem options can be specified; it is an error if they are both present.
  • --disable-security
    • This is effectively the same as create --disable-security.

hcms authorization delete <KEY> <OPTIONS>

Deletes the provided authorization provider configuration.

<OPTIONS> are either:

  • --basic --name <NAME>
  • --ip --start <START_IP> --end <END_IP>
  • --jwt
  • --disbale-security

Administrate Shared filesystems

Similar to the auth command, shared-filesystem also always operates on single configuration.

shared-filesystem create <KEY> <NAME> --s3bucket <BUCKET> [<OPTIONS>]

Create shared filesystem in given configuration (<KEY>). Filesystem name <NAME> must be the same as filesystem name on censhare server.

Options:

  • --s3bucket <bucket> Id of the AWS bucket. Required.
  • --s3region <region> AWS region. This option is not required, default region is eu-central-1.
  • --s3accessKey <key> Access key with permissions to use (read, write) the bucket. If not present, HCMS will use EC2 authorization.
  • --s3secretKey <key> Secret key (password) with permissions to use (read, write) the bucket. If not present, HCMS will use EC2 authorization.
  • --mode <greedy|lazy> Synchronization mode: greedy or lazy. If not present, greedy is used (note that this global default can be changed by manual XML change).
  • --streaming <true|false> Enable or disable direct streaming from s3 storage, without intermediate cache on local filesystem. If not present, streaming is enabled.

shared-filesystem update <KEY> <NAME> [<OPTIONS>]

Change parameters of shared filesystem named <NAME> in given configuration (<KEY>).

Options:

  • --s3bucket <bucket> Id of the AWS bucket. If not present, value is not changed.
  • --s3region <region> AWS region. If not present, value is not changed.
  • --s3accessKey <key> Access key with permissions to use (read, write) the bucket. If not present, value is not changed. Empty string removed the value from configuration.
  • --s3secretKey <key> Secret key (password) with permissions to use (read, write) the bucket. If not present, value is not changed. Empty string removed the value from configuration.
  • --mode <greedy|lazy> Synchronization mode: greedy or lazy. If not present, value is not changed.
  • --streaming <true|false> Enable or disable direct streaming from s3 storage, without intermediate cache on local filesystem. If not present, value is not changed.

shared-filesystem delete <KEY> <NAME>

Remove shared filesystem named <NAME> from given configuration (<KEY>).

shared-filesystem list <KEY>

List all configured shared filesystems for given configuration. If there is no shared filesystem configured, it shows empty array.

Examples:

YAML 
[]
YAML 
  - bucket: censhare-qa-us-east-1
    region: us-east-1
    access_key: AKIAIM5ZU5PHFRED5A53A
    secret_key: 4luieGchwNX88zrur1wnFyda5322fsdh1wfhUk+
    name: assets
    streaming: true

Administrate Satellite Groups

hcms group create <ID> <CONFIG_KEY> [Options]

Creates a new satellite group with the given id, generates a key pair, stores the private key on filesystem and assigns the new group to the configuration <CONFIG_KEY>.

There are several possible behaviors regarding the RSA key pair and satellite certificate:

  • If the --certificate option is present and its parameter is X509 certificate, it is directly used and stored as an asset.
    • No files are created in this case, because private key is not available at all.
  • If the --certificate option is present and its parameter is RSA private key, self-signed certificate is automatically generated and stored on server.
    • Output files are created only if explicitly requested by appropriate options. No file is saved by default, because it would be just a copy of the input one.
  • If the --certificate option is not present, new RSA keys (private, public) and self-signed certificate are automatically generated (option --new-certificate is automatically implied).
    • Private RSA key is always saved to disk, because it would be lost otherwise. Default filename is <ID>.pem in current directory, but this can be changed by the -o option.

Options are:

  • -n -name <NAME> Name of the group asset. Default value is <ID>
  • --certificate <PEM-FILE> Do not generate a key and use the provided certificate or RSA key. If this option is not present, new RSA key pair is generated.
  • -o --save-private-key <pem-file> File name (and path) to store RSA private key to. Default is <ID>.pem, but only if --certificate is not present.
  • --generate-shell-file <output-file> Additional file to be generated: shell script that sets all three environment variable required by HCMS docker images (SATELLITE_ID, SATELLITE_SERVER and SATELLITE_KEY).
  • --mgmt-domain <DOMAIN> Specifies the domain of both created assets. If no value is specified, root. is used. If there are any filters defined in SatelliteManagementService, value of this option must match at least on of them.
  • --mgmt-domain2 <DOMAIN> Specifies the domain2 of both created assets. If no value is specified, root. is used. If there are any filters defined in SatelliteManagementService, value of this option must match at least on of them.

Example

YAML 
id: default1
name: default1
certificate:
    subject: CN=default1
    valid:
        from: 2019-05-06T08:34:39Z
        until: 2119-05-06T08:34:39Z
    algorithm: SHA256WITHRSA
    issuer: CN=default1
    serial: 016a8c47d59b
    signature: 46533de0f0efcfc01fbf703244fcd8cc32daa156f132c7001fb1c6dcffe4d8a4de6ce7cfbc3448bb81a9292f98ac619822665f4bb1f55d928816e6c868e47258fc78e70e170fbfa02f586fc2b7d28db3208c3a70b397b0ca86dcbeebaec776ab2f5717781ccbdcc07766eacf4bdc2da683f7cfff960fcb43ecffb2cbb4e2c793602a770e495758497bbab5bf97fbc45d6c05a055f23f19880be2603e95791e39cdcd5e31c534a4f352b7ee88cb5623104b40c241cad653b472b993a9b5f4e4d77b6151bb622cf692a7e6545356516f35ea9f8a338f98345a85c3fb64c31fc12fadf8f88ff7239f509431b8c488d4965d230b0c0bb3b6f7974b3e6b2b4a21414d
    pem: |
        -----BEGIN CERTIFICATE-----
        MIICpjCCAY6gAwIBAgIGAWqMR9WbMA0GCSqGSIb3DQEBCwUAMBMxETAPBgNVBAMT
        CGRlZmF1bHQxMCAXDTE5MDUwNjA4MzQzOVoYDzIxMTkwNTA2MDgzNDM5WjATMREw
        DwYDVQQDEwhkZWZhdWx0MTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
        AKV3OFGSVqXTXv2C/fB6WfcTWwz2/e2lvJ11rDEhu4lk2iOQrjCaq2yxJaulIlY+
        oRWSsJli8IxRywjFpWIaIgf6YATapQFH//+NL6ylvdB0HhV2ZpaBhMKz7WI+K2qG
        O2IVM802Ro+uRNp3AUXvla8KPHn5P7UXHbcrU40t/7TEFaks5tjZdmeGhtwgSAQf
        BWiyKLOXDA1mfYc6G62dAy+aLpPBjy/QxqAHBnQ1szsfVZV0NgV5fWjnTz7IzyUS
        xJvkU+A1m0PQtpNfOJEOqMSCI34UsQBA4JKruk5KqdlIgVGGdYcfjnllk5ONlo3H
        7anT/fwoZJW1xE5QiKst6zECAwEAATANBgkqhkiG9w0BAQsFAAOCAQEARlM94PDv
        z8Afv3AyRPzYzDLaoVbxMscAH7HG3P/k2KTebOfPvDRIu4GpKS+YrGGYImZfS7H1
        XZKIFubIaORyWPx45w4XD7+gL1hvwrfSjbMgjDpws5ewyobcvuuux3arL1cXeBzL
        3MB3ZurPS9wtpoP3z/+WD8tD7P+yy7Tix5NgKncOSVdYSXu6tb+X+8RdbAWgVfI/
        GYgL4mA+lXkeOc3NXjHFNKTzUrfuiMtWIxBLQMJBytZTtHK5k6m19OTXe2FRu2Is
        9pKn5lRTVlFvNeqfijOPmDRahcP7ZMMfwS+t+PiP9yOfUJQxuMSI1JZdIwsMC7O2
        95dLPmsrSiFBTQ==
        -----END CERTIFICATE-----

hcms group list

List all existing satellite groups.

Note that for brevity, this list does not show full certificate content (PEM) and signature.

YAML 
  - id: sample1
    name: Satellite sample1
    certificate:
        subject: CN=sample1
        valid:
            from: 2019-04-01T15:54:10Z
            until: 2119-04-01T15:54:10Z
        algorithm: SHA256WITHRSA
  - id: sat3
    name: sat3
    certificate:
        subject: CN=sat3
        valid:
            from: 2019-04-16T16:31:41Z
            until: 2119-04-16T16:31:41Z
        algorithm: SHA256WITHRSA
  - id: docker1
    name: docker1
    certificate:
        subject: CN=docker1
        valid:
            from: 2019-04-25T08:16:25Z
            until: 2119-04-25T08:16:25Z
        algorithm: SHA256WITHRSA

hcms group inspect <ID>

Display detailed information about satellite group. This include full PEM-encoded content of the certificate and also information about configuration this group is assigned to.

Example output:

YAML 
id: docker1
name: docker1
configuration:
  - cfg:x5
certificate:
    subject: CN=docker1
    valid:
        from: 2019-04-25T08:16:25Z
        until: 2119-04-25T08:16:25Z
    algorithm: SHA256WITHRSA
    issuer: CN=docker1
    serial: 016a5391310b
    signature: 8936b4e424eda056fb221ef158f9b252260cc4e0d17717c37a652703f7a7f03e9bf15463739621efc353b144b9c59f170f9ffbbc6de5e8a6bc8395bd89ff8e05d638cfec4149c5111dd9937045b365afbd63b90d8df752d0e228af04b4e656c872355d3497b1a29b7d3e2e83015b5d3e57026c227f7de64e1ac76a5860fafe4f0267fa48f8b87cd1495f82cca8720cae97593831623425f8830bb257730f56a76521eb127c928ba909ad4ce34ea55acecad4b8990de5738c99b7049fdf1a47dd361772bd8dfbf8c4dd03bf19c8a2495c3b02796313c0177470dfb6bcdf84e58999f75baa7a2177ae3405c85611a5a268818543e336ddd0a618fd2a7be2f5eafd
    pem: |
        -----BEGIN CERTIFICATE-----
        MIICpDCCAYygAwIBAgIGAWpTkTELMA0GCSqGSIb3DQEBCwUAMBIxEDAOBgNVBAMT
        B2RvY2tlcjEwIBcNMTkwNDI1MDgxNjI1WhgPMjExOTA0MjUwODE2MjVaMBIxEDAO
        BgNVBAMTB2RvY2tlcjEwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC5
        Ovs00qns0kXyWwGmcF3JhrzKUZRZISBKy5lGbOQO6bAucNEg9Xk6TmDIaKh9aJ+w
        KsczzxU8Linq6Gk7XbEkalQENIi0+mBnXn2KcqcSfhZwgu9JLwbWp37hh6qRGkOZ
        3l/ClL5+uwqE9jroDjfkbppoy7ZwACDq/ojtwC2vfOHJO4dM/2MFr9344c7BMrbY
        1fFGBHdhr+yVn8FuGr2mvqC66jCplv/rjCWgQm0dvF9T3yU4k40GtASHNAwXOM2W
        taBCMXbwUy0VuazHNXMbQoB92fjEfe0xjb9RHtGC/ZeNZiwqeGGBt0LmoG1vhWK4
        IXBf51tkrWrbfpqM8BkfAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAIk2tOQk7aBW
        +yIe8Vj5slImDMTg0XcXw3plJwP3p/A+m/FUY3OWIe/DU7FEucWfFw+f+7xt5eim
        vIOVvYn/jgXWOM/sQUnFER3Zk3BFs2WvvWO5DY33UtDiKK8EtOZWyHI1XTSXsaKb
        fT4ugwFbXT5XAmwif33mThrHalhg+v5PAmf6SPi4fNFJX4LMqHIMrpdZODFiNCX4
        gwuyV3MPVqdlIesSfJKLqQmtTONOpVrOytS4mQ3lc4yZtwSf3xpH3TYXcr2N+/jE
        3QO/GciiSVw7AnljE8AXdHDftrzfhOWJmfdbqnohd640BchWEaWiaIGFQ+M23dCm
        GP0qe+L16v0=
        -----END CERTIFICATE-----

hcms group update <ID> [OPTIONS]

Change satellite group properties (name of certificate).

Options are:

  • -n -name <NAME> Name of the group asset. If this option is not present, name is left unchanged.
  • --certificate <PEM-FILE> New certificate or RSA private key. See group create documentation for detailed behavior. If neither this nor --new-certificate is present, current certificate is left unchanged.
  • --new-certificate Generate new random key and certificate. See group create documentation for detailed behavior. If neither this nor --certificate is present, current certificate is left unchanged.
  • -o --save-private-key <pem-file> File name (and path) to store RSA private key to. Ignored if the certificate is not changed.
  • --generate-shell-file <output-file> Additional file to be generated: shell script that sets all three environment variable required by HCMS docker images (SATELLITE_ID, SATELLITE_SERVER and SATELLITE_KEY). Ignored if the certificate is not changed.
  • --mgmt-domain <DOMAIN> Specifies the domain of both assets. If no value is specified, domain is left unchanged. If there are any filters defined in SatelliteManagementService, value of this option must match at least on of them.
  • --mgmt-domain2 <DOMAIN> Specifies the domain2 of both assets. If no value is specified, domain is left unchanged. If there are any filters defined in SatelliteManagementService, value of this option must match at least on of them.

hcms group delete <ID>

Deletes the specified satellite group.

hcms group move <ID> <CONFIG-KEY-TARGET>

Moves the specified group and attached instances to a different configuration.

Note that is is not necessary to specify source configuration.

hcms group status <ID>...

Display all connected satellites currently connected to the specified group(s).

Note that this command is available only in censhare server of version 2018.1 and higher.

Example output:

YAML 
connected_satellites:
    docker3:default1:
      - docker3:default1-7ede1c65921c
      - docker3:default1-ac6468dccf86
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close