HCMS CLI for managing satellite groups

A satellite group (cluster) is a group of satellites. Such a group has a unique ID, but single satellites within it are not. Satellites within such a group share the same Censhare asset as well as the same certificate. To distinguish between them, a random suffix is generated on start and changes with each new start respectively. A satellite cluster is required for scalability and robustness.

Please do not confuse satellite groups with configuration groups. Both groups are explained in this article.

View commands

Command	Argument	Meaning
`hcms group list`	-	Displays all groups as a YAML output, for all HCMS configurations.
`hcms group inspect`	Group id	Displays information about the specified group as a YAML output.
`hcms group status`	Group id	Displays all satellites currently connected to the specified group(s).

Sample YAML outputs

`list`

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

CODE

  - 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

`inspect`

Complete output for one satellite group, with configuration as the ID of the HCMS configuration it is assigned to.

CODE

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-----

`status`

CODE

connected_satellites:
    docker3:default1:
      - docker3:default1-7ede1c65921c
      - docker3:default1-ac6468dccf86

CRUD commands

Options required

These commands require and/or allow using attributes, e.g., updating only an attribute.

Command	1st Argument	2nd Argument	Meaning
`hcms group create`	Satellite group ID	HCMS configuration id	Defines a new satellite group for the specified configuration.
`hcms group update`	Satellite group ID	-	Updates the specified attributes of the specified satellite group.

hcms group create creates a new satellite group with the given id, generates a key pair, stores the private key on the filesystem and assigns the new group to the specified HCMS configuration.

Notes on certificates

Upon creation of the new stellite group, several behaviors are possible regarding the RSA key pair and satellite certificate.

Certificate option is provided	With which value	Result
Provided	An X509 certificte	The provided X509 certificate is directly used and stored as an asset. No files are created in this case, becausethe private key is not available at all.
Provided	An RSA certificate	A self-signed certificate is automatically generated and stored on the server. Output files are created only if explicitly requested by appropriate options (see next section). No file is saved by default, because it would be just a copy of the input one.
Not provided.	-	New RSA keys (private, public) and a self-signed certificate are automatically generated. The private RSA key is always saved to the current directory on the disk. Its default filename is `<ID>.pem` which can be changed by the `-o` option (see next section). This behavior is identical to `--new-certificate` option.

Options

All options are not mandatory.

Option short	Option long	Default option value	Meaning
`-n`	`--name`	-	Group name as appears in any UIs
-	`--certificate`	-	See previous section
-	`--new-certificate`	-	Generates new random key and certificate. Identical to `--certificate` with no option specified.
`-o`	`--save-private-key`	`<GROUPID>.pem`	Saves the newly generated RSA key to the specified file.
-	`--generate-shell-file`	-	An additional file to be generated: a Shell script that sets all three environment variable required by HCMS docker images (`SATELLITE_ID`, `SATELLITE_SERVER` and `SATELLITE_KEY`).
-	`--mgmt-domain`	`root.`	A domain where the `.pem` file asset and the Shell file asset will be stored. If there are any filters defined in the Satellite Management Service, the value of this option must match at least on of them.
-	`--mgmt-domain2`	`root.`	A second domain where the `.pem` file asset and the Shell file asset will be stored. If there are any filters defined in the Satellite Management Service, the value of this option must match at least on of them.

No options/attributes required

These commands will affect the group configuration as a whole, i.e., not possible to specify attributes.

Command	1st Argument	2nd Argument	Meaning
`hcms group delete`	Satellite grooup ID	HCMS configuration id	Deletes the specified satellite group.
`hcms group move`	Satellite grooup ID	HCMS configuration id	Moves the specified group and attached instances to a different configuration.

Note Satellite Management Service is a Censhare Server Service. You can find it in the Java Admin Client (under Services), or in the corresponding configuration file on the Server (censhare-Custom/censhare-Server/app/services/satellitemanagement/).