Working with STR
A principle behind the configuration representation used in the STR, is to support both manual configuration, i e editing configuration files in a text editor, and scripted configuration using the mzsh topo
 command. Most changes to the files can be done in either way.Â
The figure below illustrates how you can edit a particular system property, either using a command or a text editor.Â
Updating a system property in STR
Manual Configuration
There are three methods of manually editing configurations in STR.
Method 1
- Open a configuration file under
MZ_HOME/common/config/cell/default/master
. - Edit the file and save.
Run the mzsh command
topo activate
. This is required in order the for changes to become effective.Â$ mzsh topo activate
Method 2
Open a configuration by running the
mzsh command
topo open. The configuration opens in vi or the editor specified by the environment variable EDITOR.Example - Opening a cell configuration
$ mzsh topo open cell:default
Example - Opening a container configuration
$ mzsh topo open main1
Example - Opening a pico configuration
$ mzsh topo open ec1
or
$ mzsh topo open container:main1/pico:ec1
If the pico name is not unique in the system, you will be prompted to specify the container.
Example - Multiple pico configuration sharing the same name
$ mzsh topo open ec2 (/home/main1/common/config/cell/default/master/containers/main1/picos/ec2.conf,ec2,topo://container:main1/pico:ec2) (/home/main1/common/config/cell/default/master/containers/exec1/picos/ec2.conf,ec2,topo://container:exec1/pico:ec2) Multiple entries, select one: (1) topo://container:main1/pico:ec2 (2) topo://container:exec1/pico:ec2 [1] :
- Edit the configuration and save. The mzsh commandÂ
topo activate
 will be called with theÂ--verbose
 option and the saved changes are displayed in a scripted syntax.
Method 3
As an alternative to the command line  tool, you can manage pico configurations and start/stop pico instances from the System Administration GUI. For further information, see Managing Picos in Desktop.
Activation and Validation
When you use the mzsh commands  topo
 set
or topo open
, changes 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. Â
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 activate command.Â
 $ mzsh topo set --no-activation
The options Example - Output from activate with verbose option You can then restore the master registry with the the command Restart the picos to apply the changes Note! Changes to the STR are not applied on running pico instances or services. For instance, if you 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.--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
$ mzsh topo activate -v --dry-run
mzsh topo set topo://container:main1/pico:ec1/val:config.properties.ec.httpd.port 9096 # (was: 9092)
Dry-run: Validation successful
Dry-run: Stopping without performing activation
Dry-run: Active registry not changed
mzsh topo reset
.$ mzsh shutdown ec5
$ mzsh startup ec5
Note!
For further information about the various sub-commands that are available in the mzsh topo
 command, see 2.1.15 topo in Command Line Tool User's Guide.
For further information about how to manage pico- and service configurations, see Managing Picos with Topo and Managing Service Configurations.
When you enter a path that is relative to MZ_HOME in the value of an attribute, it is recommend that you use In the following example MZ_HOME will be resolved to its current value e g Example - Resolved path The next example uses a path that is always relative to MZ_HOME. Substituted path Note! When you are using The name of an attribute may contain the full name of another attribute. For instance, 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. Example - Handling conflicting attributes, manual editing When there are conflicting properties and you are using the mzsh topo command, also add single quotes, surrounding the target path (topo://..). Example - Handling conflicting attributes, scripted editingFile Paths in Attributes
${mz.home}
as a substitution./home/user/mz.
$ mzsh topo set topo://container:main1/val:common.pico.rcp.tls.keystore $MZ_HOME/keys/platform.keys
$ mzsh topo set topo://container:main1/obj:common.pico.rcp.tls.keystore '{ keystore=${mz.home}"/keys" }'
${mz.home}
as a substitution, make sure to set attributes as part of an object, using the obj
keyword.Conflicting Attributes
mz.httpd.security.keystore
is a system property but its name is also a part of mz.httpd.security.keystore.password.
common : {
"pico.rcp.tls.keystore" : "home/mz/keys",
"pico.rcp.tls.keystore.password" : "..."
}
$ 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"' "..."