Code Block
usage: topo <subcommand> <options>

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.

activate

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

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

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.

Insert excerpt

	MD82:1.4.4 Working with STR
	MD82:1.4.4 Working with STR
nopanel	true

container

Code Block
Usage: topo container

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

Option	Description
[--allow-disconnected]	Use this option when the Platform is unreachable and you want to operate on cached data.

convert

Code Block
Usage: topo convert [-c, --container <container>] [-g, --container-group <container group>] [--dry-run] [-f, --file <filename>]

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

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.

Info

title	Example - Converting an XML file

Code Block

language	text

$ mzsh topo convert --container main1

diff

Code Block
Usage: topo diff [-e, --show-entries] [-f, --from <registry>] [-q, --brief]

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

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.

Info

title	Example - Output from diff command

With -e option:

Code Block
UPDATE (containers/main1/picos/ec1.conf) config.properties.aaa:"2" # (was: "1")

Without -e option:

Code Block
mzsh topo set topo://container:main1/pico:ec1/val:config.properties.aaa "2" # (was: "1")

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

Info

title	Example - Comparing registry files

Run the following command to view the differences between the active registry and the master registry.

Code Block

language	text

$ mzsh topo diff

or

Code Block

language	text

$ mzsh topo diff --from master

Run the following command to view the differences between the active registry and the backup registry.

Code Block

language	text

$ mzsh topo diff --from backup

env

Code Block
Usage: topo env [-e, --effective] [--update-java-home <value>] [--update-mz-container <value>] [--update-mz-home <value>] [--update-mz-platform <value>]

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.

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.

Info

title	Example - Reading the environment variables

Code Block

$ mzsh topo env
export JAVA_HOME="/opt/Java/JavaVirtualMachines/jdk1.8.0_121.jdk/Contents/Home"
export MZ_CONTAINER="main1"
export MZ_CONTAINER_TYPE="platform"
export MZ_PLATFORM="http://localhost:9000"
export MZ_HOME="/user/home/mz/main1"

Info

title	Example - Setting the environment variable JAVA_HOME

Code Block
$ mzsh topo env --update-java-home /opt/Java/JavaVirtualMachines/jdk1.8.0_121.jdk/Contents/Home

get

Code Block
Usage: topo get [--default-val <value>] [ --exclude-dynamic] [--format <full \| data-only>] [-l, --local] [-p, --perspective] <target path>]

...

Info

title	Example - Viewing pico attributes

Run the following command to view a specific attribute in a pico configuration.

Code Block

language	text

$ mzsh topo get topo://container:main1/pico:ec2/val:_name

You can retrieve the attributes of multiple pico processes by replacing the full path with a regular expression.

Code Block

language	text

$ mzsh topo get --format data-only topo://container:main1/pico:.*/val:_name

hash

Code Block
Usage: topo hash

...

Info

title	Example - Using hash values

Application 1 retrieves a new hash value.
Code Block
language text
theme Eclipse
$ mzsh topo hash "3a2e373fa1653c7f0e757e2682c70317-2028777631"
Application 1 retrieves the properties of ec1.
Code Block
language text
theme Eclipse
$ mzsh topo get -l pico:ec1/obj:config.properties
Application 1 updates a property but does not call topo activate. The hash is specified to ensure that changes by other users are not activated inadvertently later on.
Code Block
language text
theme Eclipse
$ mzsh topo set -l --no-activation --hash 3a2e373fa1653c7f0e757e2682c70317-2028777631 \ topo://pico:ec1/val:config.properties.ec.httpd.port 9090
Application 2 updates the properties of ec1. The hash value is updated.
Code Block
language text
theme Eclipse
$ mzsh topo set -l topo://pico:ec1/val:config.properties.ec.httpd.port 9090
Application 1 calls topo activate with hash value retrieved in step 1.
Code Block
language text
theme Eclipse
$ mzsh topo activate --hash 3a2e373fa1653c7f0e757e2682c70317-2028777631

The activation fails since the hash values do not match.

Code Block

Specified hash does not match transaction id:  d9cd38f3793647028bd7e5d64c354ad5-2055434210 != 3a2e373fa1653c7f0e757e2682c70317-2028777631)
This may indicate concurrent modification of registry: Operation aborted!

Application 1 resets the master registry, retrieves a new hash and starts over.
Code Block
language text
theme Eclipse
$ mzsh topo reset $ mzsh topo hash

help

Code Block
Usage: topo help [<subcommand>]

...

Code Block

language	text

$ mzsh topo help <command>

migrate

Code Block
Usage: topo migrate

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

open

Code Block
Usage: topo open [-n, --no-activation] <target path>

...

Info

title	Example - Setting nano as the default editor

Code Block
$ export EDITOR=nano

rebase-configs

Code Block
Usage: topo rebase-configs [-a, --activate] <target path>

...

Info

title	Example - Rebasing an EC configuration

Code Block
$ mzsh topo rebase-configs topo://container:main1/pico:ec1$ mzsh topo active --verbose

or

Code Block
mzsh topo rebase-configs --actoivate topo://container:main1/pico:ec1

register

Code Block
Usage: topo register [-a, --address] [-c, --container] [-g, --container-group <container group>] [--mz-home <mz home>] [-u]

...

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

Code Block
Usage: topo reset

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

set

Code Block
Usage: topo set [-l, --local] [-n, --no-activation] [-s, --strict-json] <target path> <config>

...

Info

title	Example - Updating a pico object

This command adds the properties value1 and value2:

Code Block

language	text

$ mzsh topo set topo://container:main1/pico:ec2/obj:config.properties.example_object '{
 value1=1
 value2=2
}'

The following commands does not overwrite the properties value1 and value2 in example_object but adds value3:

Code Block
$ mzsh topo set topo://container:main1/pico:ec2/obj:config.properties.example_object '{ value3=3 }'

setupremote

Code Block

Usage: topo setupremote [-c, --container <container>] [-g, --container-group <container group>] [--host-key <path>] [--javahome <path>] [--no-authorized-key] [--no-host-key] [-- no-ssh-details] [--ssh-address <ip/host>] [--ssh-port <port>] [--ssh-username <username>]

...

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.

...

Info

title	Example - Views

Code Block

$ mzsh topo show jvm-args
+-------------------------------------------------------------
| container | name     | config.jvmargs                      | 
+-----------+----------+-------------------------------------+
| main1     | platform | args=[                              | 
|           |          |     "-XX:MaxMetaspaceSize=256M",    | 
|           |          |     "-Xms192M",                     | 
|           |          |     "-Xmx1024M"                     | 
|           |          | ]                                   | 
+-----------+----------+-------------------------------------+
| main1     | ecsa1    | args=[                              | 
|           |          |     "-server"                       | 
|           |          | ]                                   | 
|           |          | maxDirect=[                         | 
|           |          |     "-XX:MaxDirectMemorySize=4096M" | 
|           |          | ]                                   | 
|           |          | maxMetaspace=[                      | 
|           |          |     "-XX:MaxMetaspaceSize=196M"     | 
|           |          | ]                                   | 
|           |          | xms=[                               | 
|           |          |     "-Xms64M"                       | 
|           |          | ]                                   | 
|           |          | xmx=[                               | 
|           |          |     "-Xmx256M"                      | 
|           |          | ]                                   | 
+-----------+----------+-------------------------------------+
| main1     | psc1     | args=[                              | 
|           |          |     "-server"                       | 
|           |          | ]                                   | 
|           |          | maxDirect=[                         | 
|           |          |     "-XX:MaxDirectMemorySize=4096M" | 
|           |          | ]                                   | 
|           |          | maxMetaspace=[                      | 
|           |          |     "-XX:MaxMetaspaceSize=196M"     | 
|           |          | ]                                   | 
|           |          | xms=[                               | 
|           |          |     "-Xms64M"                       | 
|           |          | ]                                   | 
|           |          | xmx=[                               | 
|           |          |     "-Xmx256M"                      | 
|           |          | ]                                   | 
+-----------+----------+-------------------------------------+
| exec1     | ec2      | args=[                              | 
|           |          |     "-server"                       | 
|           |          | ]                                   | 
|           |          | maxDirect=[                         | 
|           |          |     "-XX:MaxDirectMemorySize=4096M" | 
|           |          | ]                                   | 
|           |          | maxMetaspace=[                      | 
|           |          |     "-XX:MaxMetaspaceSize=196M"     | 
|           |          | ]                                   | 
|           |          | xms=[                               | 
|           |          |     "-Xms64M"                       | 
|           |          | ]                                   | 
|           |          | xmx=[                               | 
|           |          |     "-Xmx256M"                      | 
|           |          | ]                                   | 
+-------------------------------------------------------------

Code Block

$ mzsh topo show status
+---------------------------------------------------------------
| container | name     | type     | state       | config-state | 
+-----------+----------+----------+-------------+--------------+
| main1     | platform | platform | running     | in-sync      | 
| main1     | ecsa1    | ecsa     | not-started |              | 
| main1     | psc1     | sc       | not-started |              | 
| exec1     | ec2      | ec       | not-started |              | 
+---------------------------------------------------------------

Code Block

$ mzsh topo show ports
+----------------------------------------------------------------------------
| container | name     | type     | ports                                   | 
+-----------+----------+----------+-----------------------------------------+
| main1     | platform | platform | "mz.pcc.restful.port"="9090"            | 
|           |          |          | "mz.servicehost.port.range"="5451-5500" | 
|           |          |          | "mz.wi.port"="9000"                     | 
|           |          |          | "pico.rcp.platform.port"="6790"         | 
|           |          |          | "pico.synchronizer.port"="6791"         | 
+-----------+----------+----------+-----------------------------------------+
| main1     | ecsa1    | ecsa     | "ec.httpd.port"="9093"                  | 
|           |          |          | "pico.rcp.platform.port"="6790"         | 
|           |          |          | "pico.synchronizer.port"="6791"         | 
+-----------+----------+----------+-----------------------------------------+
| main1     | psc1     | sc       | "mz.servicehost.port.range"="5801-5850" | 
|           |          |          | "pico.rcp.platform.port"="6790"         | 
|           |          |          | "pico.synchronizer.port"="6791"         | 
+-----------+----------+----------+-----------------------------------------+
| exec1     | ec2      | ec       | "ec.httpd.port"="9090"                  | 
|           |          |          | "pico.rcp.platform.port"="6790"         | 
|           |          |          | "pico.synchronizer.port"="6791"         | 
+----------------------------------------------------------------------------

unset

Code Block
Usage: topo unset [-l, --local] [-n, --no-activation] <target path>

...

Info

title	Example - Removing a pico attribute

Code Block

language	text

$ mzsh topo unset topo://container:main1/pico:ec2/val:ec_type ecsa

Excerpt

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.

Info

title	Example - Resolved path

Code Block

language	text
theme	Eclipse

$ mzsh topo set topo://container:main1/val:common.pico.rcp.tls.keystore $MZ_HOME/keys/platform.keys

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

Info

title	Substituted path

Code Block

language	text
theme	Eclipse

$ mzsh topo set topo://container:main1/obj:common.pico.rcp.tls.keystore '{ keystore=${mz.home}"/keys" }'

Note

title	Note!

When you are using ${mz.home} as a substitution, make sure to set attributes as part of an object, using the obj keyword.

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.

Info

title	Example - Handling conflicting attributes, manual editing

Code Block
common : { "pico.rcp.tls.keystore" : "home/mz/keys", "pico.rcp.tls.keystore.password" : "..." }

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

Info

title	Example - Handling conflicting attributes, scripted editing

Code Block

$ mzsh topo set 'topo://container:<platform container>/val:common."pico.rcp.tls.keystore"' "home/mz/keys"
 
$ mzsh topo set 'topo://container:<platform container>/val:common."pico.rcp.tls.keystore.password"' "..."

...

Versions Compared

Old Version 2

New Version 3

Key

activate

container

convert

diff

env

get

hash

help

migrate

open

rebase-configs

register

reset

set

setupremote

show

unset

File Paths in Attributes

Conflicting Attributes

Page Comparison

Versions Compared

Old Version 2

New Version 3

Key

activate

container

convert

diff

env

get

hash

help

migrate

open

rebase-configs

register

reset

set

setupremote

show

unset

File Paths in Attributes

Conflicting Attributes