topo

Owned by Former user (Deleted)
Last updated: Nov 27, 2024 by Felicity Borrelli
16 min read

This command is used to register containers in STR and to create, update, remove, and view pico configurations.

usage: topo <subcommand> <options>

Note!

This command is valid only for the MZ_HOME owner.

When you make changes in pico configurations, using topo, these are automatically validated before they are copied to the active registry.

If the command and its arguments can be parsed but fails the validation, you can update the configuration or use a reset command to undo the changes. An error message will appear if the validation fails. You can disable the validation by using the option --no-activation. Changes performed by the mzsh topo will then remain in the master registry until you submit a separate topo activate command. 

You can use the following subcommands with topo:

  • activate

  • container

  • convert

  • diff

  • env

  • get

  • hash

  • help

  • migrate

  • open

  • rebase-configs

  • register

  • reset

  • set

  • setupremote

  • show

  • unset

The option --allow-disconnected is available for all subcommands except for setupremote. You should only include this option when the Platform is unreachable and you want to use cached data.

Navigate to the required section on this page:

activate

Usage: topo activate [--dry-run] [-v, --verbose]

Use topo activate to move staged changes in the master registry to the active registry.

Option

Description

Option

Description

[--dry-run]

Use this option to validate the staged changes without performing the activation.

[–hash <hash value>]

Compare the provided hash value with the actual hash that represents the current state of active registry. The activation fails if the values are not equal. For further information, see hash below,

[-v, --verbose]

Use this option for detailed information about the changes.

Hint!

The options --dry-run and --verbose are useful to learn the mzsh topo syntax. When you have edited the configuration manually, use the following command, to view the corresponding edits in a scripted syntax:

$ mzsh topo activate --dry-run --verbose

Example - Output from activate with verbose Option

You can then restore the master registry with the command mzsh topo reset.

Example - Restart the picos to apply the changes

Changes to the STR are not applied on running pico instances or services. If you, for example, have updated the properties of the Platform and an EC, both must be restarted after activation.

Example, after an mzsh topo activate of ec5, mzsh shutdown and startup needs to be done to apply the changes.

container

Use topo container to display the name of the current container.

Option

Description

Option

Description

[--allow-disconnected]

Use this option when the Platform is unreachable and you want to operate on cached data.

convert

Use topo convert to move the configuration of a specific XML file to STR.

Option

Description

Option

Description

[-c, --container <container>]

Use this option to specify a target container.

[-g, --container-group <container group>]

Use this option to specify a target container group.

[--dry-run]

Use this option to validate that the conversion and display the result of the conversion without updating the STR.

[-f, --file <filename>

Use this option to specify the source XML file.

diff

Use topo diff to view differences between the master repository and the active repository in the STR.    

Option

Description

Option

Description

[-e, --show-entries]

Use this option for viewing differences in an easy-to-read format. By default, the output from the command displays topo set commands that correspond to the staged changes.

[ -f, --from] <registry>

Use this option when you want to compare the active registry with the backup registry

[-q, --brief]

Use this option to only view the names of the updated registry files. The default value is false.

env

Use topo env to display or set environment variables that are used my the mzsh command. These variables are written to the script file MZ_HOME/bin/mzsh.
The three variables MZ_PLATFORM, MZ_CONTAINER and MZ_CONTAINER_TYPEare handled differently than the rest. In order to update the value in the script file you use the parameters starting with --update-<value> as per below table. In order to both update the value in the script file and use the value immediately you will have to combine the --update-<value> parameter with the -e parameter.

Option

Description

Option

Description

[-e, --effective]

Use this option to read the environment parameters in runtime, i e the "effective values" after accounting for overrides. The default behaviour is to read the values as they are defineds in the mzsh script file, not accounting for the possibility to override these values with environment  variables. 

[--update-java-home <value>]

Use this option to update the value of JAVA_HOME

[ --update-mz-container <value>]

Use this option to update the value of MZ_CONTAINER.

[--update-mz-home <value> ]

Use this option to update the value of MZ_HOME.

[--update-mz-platform <value> ]

Use this option to update the mzsh value of MZ_PLATFORM.

get

Use topo get to retrieve pico configurations in the target path from STR.

Paths in STR are structured as follows:

Option

Description

Option

Description

[--default-val <value>]

Use this option to replace a missing value in the target path with a default value.

[ --exclude-dynamic]

Use this option to exclude non-static data in the output e g _status in a pico configuration. This is useful in case of errors that blocks the topo command.

[--format <full|data-only>]

Use this option to exclude metadata from the command output.

  • full - Include meta data

  • data-only - exclude meta data

Default: full

[-l, --local]

Use this option to select the local container, unless another container is specified in the target path.

Default: false

[-p, --perspective <resolve | default>]

Use this option to retrieve the attributes of templates instead of the template names.

  • resolve - attributes

  • default - template names

Default: default

hash

Use topo hash to retrieve a value that represents the current state of the active registry. This is useful when you need to handle concurrent changes of the STR. For instance, an application may need to retrieve a pico configuration to evaluate the required changes. In the meantime, a second application or a user may update the same configuration

help

Use topo help to retrieve a description of a subcommand.

Run the following command for an overview of the various topo subcomands

Run the following command for a description of a specific subcomand

migrate    

Use topo migrate to move pico configurations from MZ_HOME to STR. The upgrader runs this command during upgrade to 8.0.

open

Use topo open to open a cell, container- or pico configuration file in a text editor. When you save and close the editor, the command will call topo activate to move the staged changes in the master registry to the active registry.

Option

Description

Option

Description

[-n, --no-activation]

Use this option to skip activation after changes in master registry.

Run the following command to open a cell configuration:

Run the following command to open a container configuration:

Run the following command to open a pico configuration:

If the pico name is not unique in the system, you will be prompted to specify the container.

To avoid ambiguous references, specify the name of the container and the pico configuration.

Run the following command to open the custom or the standard services  configuration:

By default, the command opens the vi editor. To use a different editor set the environment variable EDITOR.

rebase-configs

Use topo rebase to inset a standard template in a pico configuration and remove attributes that are identical to attributes in the template. The command automatically detects the pico configuration type and applies one of the following templates:

  • mz.standard-platform.conf

  • mz.standard-ec.conf

  • mz.standard-sc

This command is useful to reduce the size of the pico configurations and thereby facilitate maintenance.

The changes are written to the master registry. To validate and activate the changes you can either use the --activate option or run topo activate after the topo rebase-configs command. 

For further information about templates, see STR File Structure.

Option

Description

Option

Description

[-a, --activate]

Use this option to immediately activate after changes in master registry.

register

When you install an execution container, and the Platform is running, it is automatically registered in the Platform Container. If the platform is not running during the installation, use topo register to register the Execution Container manually.

Option

Description

Option

Description

[-a, --address <ip/host>]

Use this when you need to set a different host address for the container than the one that is specified in the common property pico.rcp.server.host, which is the default value. This option is typically used together with the -u option.

[-c, --container <container>]

Use this option when you need to change the existing container name. This option is typically used together with the -u option.

[-g, --container-group <container group>]

Use this option when you need to change the existing container group. This option is typically used together with the -u option.

[--mz-home <path>]

Use this option when you need to set a different home directory for the container than the one that is specified in the environment variable MZ_HOME, which is the default value. 

[-u]

Use this option to allow updates of an already registered container. By default, updates are not allowed and the command will attempt to register a new container.

reset

Use this option to remove any changes to the master registry in STR since the activation

set

Use topo set to create and update pico configurations in the specified target-path of STR.

Option

Description

Option

Description

[-l, --local ]

Use this option to select the local container, unless another container is specified in the target path.

[--no-activation, -n]

Use this option to skip activation after changes in master registry.

[-s, --strict-json]

Use this option when you want to specify the configuration in JSON format instead of HOCON format.

Run the following command to create a new pico configuration.

The <config> argument may contain a key-value pair that specifies a template or a pico configuration in HOCON format.

Run the following command to add or update an attribute of a pico configuration.

mzsh topo set topo://container:<container>/pico:<pico>/val:<attribute> <attribute value>

Run the following command to add or update an object that contains one or more attributes.

The <config> argument may contain a pico configuration in HOCON format.

setupremote

Use the command topo setupremote to enable remote access via SSH to an Execution Container, e g from the Platform container.

Option

Description

Option

Description

[-c, --container <container>]

Use this option to specify a different container than the local one, which is the default value.

[-g, --container-group <container group>]

Use this option to setup remote access to a container in specific container group. This is useful when you have multiple containers with identical names in different containers groups.

[--host-key <path>]

Use this option to use a pre-generated host key instead of the one that is generated when you run topo setupremote.

[--java-home <path>]

Use this option when the target container is located on a different host. The default value is specified by the environment variable JAVA_HOME in the current shell.

[--no-authorized-key]

By default, the topo setupremote command will obtain a public authorization key from the user home directory on the Platform Container host and store it in the STR, i e the file mz.conf. Use the option
--no-authorized-key
to skip this operation.

[--no-host-key]

By default, the topo setupremote command will store the public host key of the Execution Container in the STR, i e the file mz.conf. Use the option --no-host-key to skip this operation.

[--no-ssh-details]

Use this option to exclude ssh-username and ssh-address from STR. These attributes are required for remote access. If you use this option you will need to update the STR manually.

[--ssh-address <ip/host>]

Use this option when the target container is located on a different host or when you want to bind to a specific IP address or hostname. The default value is specified by the address attribute for container in mz.conf.

[--ssh-port <port>]

Use this option when you want to use a different port than 22 for SSH.  

[--ssh-username <username>]

Use this option when the target container is located on a different host or when a specific username is required for SSH. The default SSH user is the OS user that runs the topo setupremote command.

show

Use topo show to retrieve various types of information about pico instances that are defined in the STR. 

Option

Description

Option

Description

[ --exclude-dynamic]

Exclude non-static data in the output e g _status in a pico configuration. This is useful in case of errors that blocks the topo command.

[ --format <format>]

Set the format of the returned data:

  • csv
    json
    table (default)

[ -l, --local ]

Use this option to view pico instances in the local container only. By default, all containers are included.

 

[--timeout-seconds <time>]

Use this option to limit the time for retrieving dynamic information, e g _status.The default value is 10 seconds.

 

The following views are available:

  • jvm-args - Displays the JVM arguments that are used by the pico instances in the system. JVM arguments that are set in templates are included.

  • status - Displays the container name, pico name, pico type and running state.

  • status-sc - Displays similar view as status but only includes SCs.

  • status-ec - Displays similar view as status but only includes ECs.

  • status-long - Displays similar view as status but also includes the status of replication between Platform Container and Execution Containers.

  • pico-view - Displays similar view as status but also includes memory usage and the pico response time.

  • pico-view2 - Displays similar view as pico-view but also includes uptime. 

  • ports - Displays the ports that are used by the pico instances in the system. Ports that are set in templates and on cell- and container level, are included. If both webserver and httpd ports are displayed, then webserver ports take precedence. 

unset      

Use topo unset to remove pico configurations in the specified target-path of STR.

Option

Description

Option

Description

[-l, --local]

Use this option to select the local container, unless another container is specified in the target path.       

[-n, --no-activation]

Use this option to skip activation after changes in master registry.

Run the following command to remove a pico configuration.

mzsh topo unset topo://container:<container>/pico:<pico>

 

 

File Paths in Attributes

When you enter a path that is relative to MZ_HOME in the value of an attribute, it is recommend that you use ${mz.home} as a substitution.

In the following example MZ_HOME will be resolved to its current value e g /home/user/mz.

The next example uses a path that is always relative to MZ_HOME.

Conflicting Attributes

The name of an attribute may contain the full name of another attribute. For instance, mz.httpd.security.keystore is a system property but its name is also a part of mz.httpd.security.keystore.password.

In this case you must ensure that the name of both properties are surrounded by quotes, or one of the properties will be overwritten at activation.

When there are conflicting properties and you are using the mzsh topo command, also add single quotes, surrounding the target path (topo://..).

Updating IP, Hostname, and Ports in JDBC URL

You can update the IP address, hostname, and ports int he JDBC URL using the mzsh topo get and mzsh topo set commands as shown in the examples below.

Return Codes

Listed below are the different return codes for the topo command:

Code

Description

Code

Description

0

Will be returned if the command is successful.

1

Will be returned if the argument count is incorrect or argument(s) are invalid.

3

Will be returned if the target path argument for the subcommand get does not exist.