Petals Registry CLI 1.1.1+

Introduction

Petals Registry CLI is a command line client to administrate a set of Petals Registry Overlay nodes.
Petals Registry CLI has 4 interaction modes:

  • Interactive Mode: in this mode, the user types in commands directly in the shell.
  • Scripting Mode: in this mode, Petals Registry CLI executes a script file that contains Petals Registry CLI commands.
  • Executable Mode: in this mode, Petals Registry CLI is launched with a command as an argument.
  • Redirection Mode: in this mode, Petals Registry CLI takes the commands to execute from the standard input.

To work, Petals Registry CLI needs to establish a connection with a Petals Registry node.
The connection is a JMX connection (see the credentials defined in the cluster.xml file of Petals Registry Overlay).

Petals Registry CLI 1.0.0+ works with Petals Registry Overlay 1.0.0 and higher.
Petals Registry CLI 1.1.0+ works with Petals Registry Overlay 1.0.1 and higher.
Petals Registry CLI 1.1.1+ works with Petals Registry Overlay 1.0.2 and higher.

Usage of Petals Registry CLI

usage: Petals Registry Command Line Interface
              
[-d] [-y] usage:  [-a <alias>] [-g <group-name>] [-h <host>] [-n <port>] [-p
<group-password>] [-y]
[-H | -V | [--file] <filename> | -c -- <command> | -C]
 -a,--alias <alias>               Connection alias in the preference file.
 -c,--command                     Execute a command given on the command line after
                                  '--'.
 -C,--console                     Enable the mode 'console'.
 -d,--debug                       Print stack trace and debugging informations
    --file <filename>             Enable the script file execution. If filename is '-',
                                  commands are read from the stdin.
 -g,--group <group-name>          The group name of the Petals Registry cluster to
                                  connect.
 -H,--help                        Print this help message and exit.
 -h,--host <host>                 The host of a member of the Petals Registry cluster to
                                  connect.
 -n,--port <port>                 The port of the Petals Registry cluster to connect.
 -p,--password <group-password>   The password of the Petals Registry cluster to
                                  connect.
 -V,--version                     Print the version number and exit.
 -y                               A flag to skip confirmation.

Which evolution would you like on Petals? Share it! http://www.petalslink.com/feedback

To get available commands, use the command 'help' on command-line: petals-cli.sh -c – help

Available commands:
   connect     Connect to a Petals Registry cluster.
   delete-topology
               Delete the given topology.
   disconnect
               Disconnect from a Petals Registry cluster.
   exit        Exit this shell.
   help        Display this help message or help for a specific command.
   list-topologies
               List the topologies registered.
   load        Load properties from files.
   print       Print a message.
   pwd         Print the working directory.
   set         Assign a value to the system property named key.
   system      Execute system command.

For help on a specific command type:
   help <command>

To get help on a command, use the command 'help' on command-line: petals-registry-cli.sh -c – help <command>

Options of Petals Registry CLI are POSIX.1-2008 or IEEE Std 1003.1 compliant.
Table of contents
Contributors

Use Cases

Full Size
A&#32;Gliffy&#32;Diagram&#32;named&#58;&#32;Petals&#95;Registry&#95;CLI&#95;Use&#95;Cases

Petals Registry CLI: the Basis

Installing Petals Registry CLI

The installation of Petals Registry CLI depends on your operating system. The following table resumes which archives is needed according to your operating system. Petals Registry CLI archives are available on the Petals's web-site: http://download.petalslink.com/petals-esb.html.

Operating System OS Version Petals archive to use Installation procedure
Debian-based Linux all Debian packages Installing Petals Registry CLI using the Debian packages
Linux all ZIP archive Installing Petals Registry CLI using the ZIP archive
Microsoft Windows all ZIP archive Installing Petals Registry CLI using the ZIP archive
Mac OS all ZIP archive Installing Petals Registry CLI using the ZIP archive

Note: The ZIP archive can be used on Debian-based systems. In this case, Petals Registry CLI should be installed as a user software without integration with the operating system.

Petals Registry CLI capabilities about script and shell usages

Interactive console

Launching Petals Registry CLI with the following command line starts an interactive console with a prompt where the user can enter commands.

> ./petals-reg-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli>

Execution of a Petals Registry CLI command directly on the command line

Launching Petals Registry CLI with the following command line executes the command specified on the command line.

> ./petals-registry-cli.sh -c -- <command> <command-args>

Execution of a Petals script file

Launching Petals Registry CLI with the following command line executes the commands from the specified Petals script.

> ./petals-registry-cli.sh <filename>
> ./petals-registry-cli.sh --file <filename>
A Petals script is text file containing commands supported by Petals Registry CLI, and comments. Comments start by '#', optionally preceded by space(s).

Execution of an inlined Petals script

Launching Petals Registry CLI with the following command line executes commands provided through the standard input ("stdin").

> cat <filename> | ./petals-registry-cli.sh -
> cat <filename> | ./petals-registry-cli.sh --file -
> ./petals-registry-cli.sh - << EOF
<command1> <command1-args>
<command2> <command2-args>
EOF
> ./petals-registry-cli.sh --file - << EOF
<command1> <command1-args>
<command2> <command2-args>
EOF

Getting help

Getting help on command line options and arguments

The help on command line options and arguments is available through the '-H' option. A text containing options, arguments and available commands is displayed according to the usage defined above.

> ./petals-registry-cli.sh -H

Getting help on commands from the command line

The help on a command is available by using the command 'help'. A usage and a description of the command is displayed:

> ./petals-registry-cli.sh -c -- help <command>

usage: <command> <command-arguments>

<command description>

>

where:

  • <command> is the command for which we want to get help.
  • <command-arguments> is the list of arguments for the command.
  • <command-description is a description of the command.

Getting help on available commands and on a command in interactive mode

The list of available commands is available by using the command 'help' without argument.
Help about a command is available by using the 'help' command. Command's usage and description are then displayed.

> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> help
Available commands:
   connect     Connect to a Petals Registry cluster.
   delete-topology
               Delete the given topology.
   disconnect
               Disconnect from a Petals Registry cluster.
   exit        Exit this shell.
   help        Display this help message or help for a specific command.
   ...

For help on a specific command type:
help <command>

petals-registry-cli> help <command>

usage: <command> <command-arguments>

<command description>

petals-registry-cli>

where:

  • <command> is the command for which we want to get help.
  • <command-arguments> is the list of arguments for the command.
  • <command-description is a description of the command.

Getting the version of Petals Registry CLI

To get the version of Petals Registry CLI, the version of the JVM running Petals Registry CLI, and its operating system, use the '-V' option:

> ./petals-registry-cli.sh -V
Petals Registry Command Line Interface 1.1.0
OpenJDK Runtime Environment 1.7.0_91-b02 Oracle Corporation
Linux 4.2.0-22-generic amd64

Working with variables

Petals Registry CLI supports variables as properties or environment variables. A variable is a placeholder with a name: ${variable-name}, that is replaced by its value when evaluating the command in which it is used. By default, a variable is a property. An environment variable is identified by a name prefixed with "env:":

connect -h ${host.name} -n ${host.port} -u ${env:USER} -p ${host.password}

Listing available variables

The command 'set' without argument lists all available variables, properties and environment variables:

> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> set
...
java.runtime.name=OpenJDK Runtime Environment
java.runtime.version=1.7.0_79-b14
java.specification.name=Java Platform API Specification
java.specification.vendor=Oracle Corporation
java.specification.version=1.7
...
env:PATH=usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/cdeneux/maven/bin
...

Setting a variable as property

A property can be set using the command 'set':

set [ property-name = property-value ]
set [ property-name =: property-value ]
set [ property-name : property-value ]

> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> set my-property-name=value

Return codes of Petals Registry CLI

Return code on error parsing mode options

If Petals Registry CLI is not able to determine the mode (interactive, scripting, executable or redirection) to use from arguments, the return code will be 1.

Return code of Petals Registry CLI launched in interactive mode

Petals Registry CLI launched in interactive mode will exist always with the return code 0, even if error occurs executing a command.
If an error occurs during a command execution or parsing:

  • The error message is displayed.
  • Petals Registry CLI is not interrupted, the user can enter other commands.

Return codes of Petals Registry CLI launched in command line mode

Return code on parsing error of the command arguments

When there is an error about options and arguments of the command, the return code of Petals Registry CLI is 1.

Return code on command execution

When there is an error about the command execution, the command is interrupted and the return code of Petals Registry CLI is 2.

Return code on connection error

When there is an error about the connection establishment, the command is not executed the return code of Petals Registry CLI is 3. If the error is due to an unresolvable hostname, the return code is 1 (ie. error on arguments).

Return code on successful command execution

When there is no error about options, arguments and execution of a the command, the return code of Petals Registry CLI is the return code of the command

Return code of commands

All commands return the return code 0 when the execution succeeds, and 1 when the execution fails. Except the command 'system' that returns the return code of the system command invoked.

Return codes of Petals Registry CLI launched in scripting modes

Return code on error reading script

When there is an error reading the command flow, Petals Registry CLI script is interrupted and the return code of Petals Registry CLI is 1.

Return code on parsing error of the command arguments

When using the script mode or inlined mode, parsing errors (invalid options and/or arguments) result in an interruption of Petals Registry CLI.
The return code 1 then pushed back.

Return code on command execution

When there is an error about a command execution, the command is interrupted, Petals Registry CLI script is interrupted and the return code of Petals Registry CLI is 2.

Return code on connection error

When there is an error about the connection establishment, the command is not executed and the return code of Petals Registry CLI is 3. If the error is due to an unresolvable hostname, the return code is 1 (ie. error on arguments).

Return code on successful command execution

When there is no error about options, arguments and execution of commands, the return code of Petals Registry CLI is the return code of the last command, except if a dedicated value is used through the command exit.

Error management of a command read from stdin or a file

If an error occurs during the execution of a flow of commands:

  • The command that has thrown the error is interrupted.
  • The return code of the command can be checked using the commands isParsingErrorReturned, isExecutionErrorReturned, isNoErrorReturned, the ternary conditional operator, and the lastErrorCode attribute.
    > ./petals-registry-cli.sh - << EOF
    list-topologies
    isNoErrorReturned ? listartefacts : exit lastErrorCode
    EOF
    


Note:

  • The return values of command isParsingErrorReturned, isExecutionErrorReturned and isNoErrorReturned are reset when invoking another command. Only the error of the last command execution can be checked.
  • The attribute lastErrorCode is an argument of the command exit to return the return code of the last executed command.

Exit from the Console mode

To exit the console mode, use the 'exit' command.
If a number is set as an argument, it is used as return code. Otherwise, the 0 is returned.

> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> exit
> echo $?
0
> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-cli> exit 1
> echo $?
1
If an asynchronous command is running, the command 'exit' will wait the end of these pending commands to really exit. If you have infinite asynchronous command as defect subscription, you can force to exit using Ctrl+C or kill the process.

Petals Registry CLI Preferences

It is possible to define preferences in Petals Registry CLI. The preferences are defined in a properties file, as key/value pairs. Two levels of preference files are defined:

  • a user level, by the file $HOME/.petals-cli/petals-registry-cli.default
  • and a system level. The location of this file is defined according to the operating system:
    OS/Distribution System level file
    Linux/Debian-based distribution /etc/petals-registry-cli/petals-registry-cli.default
    Windows %PETALS_REGISTRY_CLI_HOME%\conf\petals-registry-cli.default

If the user preference file exists, it is used. Otherwise the system preference file is used.

If Petals Registry CLI is installed through the ZIP archive, and no user level file exists, it is possible to define another preference file through the environment variable $PETALS_REG_CLI_PREFS.
If Petals Registry CLI is installed through the Debian archive, the default preference file is protected by system ACL and can be read only by users that are member of its group. So don't forget to add you users to the security group, or you can protect this file with your own group.

The preferences files contain a set of keys in several sections:

  • section 'Global preferences':
    • alias.default: the default alias to use (required).
    • user.lang: the language to use in Petals Registry CLI.
      • This property is optional. If not set, OS settings are used. If the OS language setting is not supported, then English is used.
      • If the value is specified and not supported, then English is picked up.
      • French and English are the two languages that must be supported. Others are optional (but contributions are welcome).
  • section defining aliases. An alias identifies all the properties of a connection. An alias is defined as following:
    • <alias>.host: the host of a member of the Petals Registry Cluster (required).
    • <alias>.port: the port of the member of the Petals Registry Cluster (required).
    • <alias>.group: the group name of the registry instance (optional).
    • <alias>.password: the password to join the registry instance (optional).
      When optional keys are not defined, Petals Registry CLI will ask for their values manually (or you will have to use the right options with the commands).
      If the file does not exist, or that $PETALS_REG_CLI_PREFS points to an invalid location, Petals Registry CLI will use default settings when possible. Otherwise, it will display an error message.


For a cluster member, the group and password must both be set or both be absent.
An error message is displayed if only one of them is specified.


The server alias must be unique in the properties file.
If a server alias is used twice, an error message will be displayed.


Initial content of the file:

# The default server / connection
alias.default = default

# The connection properties of the 1st cluster member
default.host=localhost
default.port=7900
default.group=default-sample
default.password=s3cr3t

Petals Registry CLI extensions

No Petals Registry CLI extensions is available now, contributions are welcomed.

Connection to a Petals Registry member

Connection options from the command line

All the required parameters for a connection can be configured on the command line as options or through the command connect:

> ./petals-registry-cli.sh -h <host> -n <port> -g <group> -p <password> -c -- <command>
> ./petals-registry-cli.sh -C
petals-registry-cli> connect -h <host1> -n <port1> -g <group1> -p <password1> 
petals-registry-cli@<host1>:<port1>>

An alias can also be used.

> ./petals-registry-cli.sh -a <alias> -c -- <command>
> ./petals-registry-cli.sh -C
petals-registry-cli> connect -a <alias1>
petals-registry-cli@<host1>:<port1>>
The arguments -h, -p, -g, -p and -a of the command line are significant only for the command line mode (ie. -c)

Default connection

In console mode, the connection is established, by the command 'connect', with the values given in the preferences file. The connection parameters are identified through the default alias defined by the property alias.default of the preferences file.

> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> connect
petals-registry-cli> Would you like to connect to <default-group>:*****@<default-host>:<default-port>? (y/n)
y
petals-registry-cli@<default-host>:<default-port>>

The confirmation can be skipped by adding the 'yes' argument to the command.

> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> connect -y
petals-registry-cli@<default-host>:<default-port>>

In command line mode, no default connection is available. A connection is automatically established with the connection parameters explicitly set on the command line.

> ./petals-registry-cli.sh -h localhost -n 7700 -g default-sample -p petals -c -- list-topologies
> ./petals-registry-cli.sh -a default -c -- list-topologies

In script mode, the connection is established, by the command 'connect', with the values given in the preferences file. The connection parameters are identified through the default alias defined by the property alias.default of the preferences file.

> ./petals-registry-cli.sh - << EOF
connect
EOF

If the preferences file does not exist and that connect was invoked without an argument, the command returns the error code 2.

Interacting with several Petals nodes without exiting Petals Registry CLI

In interactive mode or script mode, we should be able to close a connection and open another one without leaving Petals Registry CLI. This is achieved with the 'connect' and 'disconnect' commands. If no argument is set on the 'connect' command, default values are used. These default values are specified in the preferences file. If a connection already exists, the 'connect' command will realize a disconnection before to establish the new connection.

> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> connect -h <host1> -n <port1> -g <group1> -p <password1>
Connected on <host1>:<port1> with '<group1>'
petals-registry-cli@<host1>:<port1>> disconnect
petals-registry-cli> connect -a <alias>
Connected on <host1>:<port1> with '<group1>'
petals-registry-cli@<host1>:<port1>> disconnect
petals-registry-cli> connect -h <host2> -n <port2> -u <group2> -p <password2>
Connected on <host2>:<port2> with '<group2>'
petals-registry-cli@<host2>:<port2>> connect
petals-registry-cli@<host2>:<port2>> Would you like to connect to <default-user>:*****@<default-host>:<default-port>? (y/n)
y
petals-registry-cli@<default-host>:<default-port>>

Security

For security reasons, a Petals Registry CLI user may decide that there should be no default connection.
In that case, he may decide to delete the preference file, so that any user will have to type in the right information.
If the preference (properties file) does not exist, Petals Registry CLI displays an error message.

> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> connect
No default connection is available. Use 'help connect' for more information.


Another possibility is that the user allows to record a default host and port but not the credentials.
In that case, Petals Registry CLI will ask the user to type in the credentials.

> ./petals-registry-cli.sh -C

Type 'help' for help.
------------------------------------------------------------------------------
petals-registry-cli> connect
petals-registry-cli> Would you like to connect to <default-host>:<-default-port>? (y/n)
y
petals-registry-cli> Group name: wrong-groupname
petals-registry-cli> Password: right-pwd
Invalid credentials.
petals-registry-cli> Retry? (y/n)
y

petals-registry-cli> Group name: right-groupname
petals-registry-cli> Password: wrong-pwd
Invalid credentials.
petals-registry-cli> Retry? (y/n)
y

petals-registry-cli> Group name: right-groupname
petals-registry-cli> Password: right-pwd
petals-registry-cli@<default-host>:<-default-port>>

Error Messages

Error messages should be written in active form.
Negative forms should be avoided.


The preferences file does not exist.
The connect command results in the following error message.

No default connection is available. Use 'help connect' for more information.


The preferences file is invalid (missing property, or duplicate alias...).
The connect command results in the following error message.

The preferences file contains <N> error(s).

  • Error 1
  • Error2


Duplicate Alias.

The alias '<alias>' can only be used once.


Missing property.

The property '<property>' is missing.


Only group was specified for a server.

The credentials for '<alias>' are invalid: add the password or remove the group.


Only password was specified for a server.

The credentials for '<alias>' are invalid: add the group or remove the password.

Administration Commands

Working with topologies

Getting the topology

When connected to a Petals Registry member container, it is possible to get information about the Petals ESB topologies hosted by this registry.

petals-registry-cli@host:port> list-topologies
PEtALS

This command returns the list of topologies hosted.

Filtering

The list of the topologies can be limited using the filter '-p <topology-pattern>', where topology-pattern is a regexp identifying the topologies to list:

petals-registry-cli@host:port> topology-list -p P.*
PEtALS

Removing a topology

When connected to a Petals Registry member container, a remaining topology can be removed from the Petals Regsitry using the command delete-topology:

petals-registry-cli@host:port> delete-topology -t <topology-name>

where topology-name is the name of the topology to delete.

System Commands

Petals Registry CLI can directly execute system commands.
To achieve it, the system command is an argument of the 'system' command.

petals-registry-cli> system <system-command>

As an example,

petals-registry-cli> system pwd

displays the directory in which Petals Registry CLI runs.
The return code of the wrapping command is the return code of the system command.

A system command having arguments can also be enclosed with quotes:
petals-registry-cli> system "echo My linux shell: ${env:SHELL}"
My linux shell: /bin/bash
Caution to correctly escape the symbol '$' when using a system command with variables on command line:
$ petals-registry-cli -c -- system echo My linux shell: \${env:SHELL} with the temporary folder: \${java.io.tmpdir}
My linux shell: /bin/bash with the temporary folder: /tmp
$ petals-registry-cli -c -- system "echo My linux shell: \${env:SHELL} with the temporary folder: \${java.io.tmpdir}"
My linux shell: /bin/bash with the temporary folder: /tmp

Advanced usage

Logging in Petals Registry CLI

Petals Registry CLI is provided with a default Java Logging configuration. This configuration displays logging trace as following:

<LEVEL>: <message>

where <LEVEL> is the international label of the logging trace level, except for the level 'SEVERE' which is always 'ERROR'. By default, only levels 'SEVERE' and 'WARNING' are printed.

The default configuration can be overridden using the system property 'java.util.logging.config.file' to set into the launching script '$PETALS_REG_CLI_HOME/bin/petals-registry-cli.sh' or '%PETALS_REG_CLI_HOME%\bin\petals-registry-cli.bat'. An sample configuration is available in file '$PETALS_CLI_HOME/conf/petals-registry-cli-logging-sample.properties'

To add your custom command

Petals Registry CLI is provided with an API to add your own command.

Writing your command

To create a new custom command, just create a new Java class that IMPLEMENTS the interface org.ow2.petals.cli.api.command.Command.
To be auto-discovered, your command MUST be declared in a resource named 'META-INF/service/org.ow2.petals.cli.api.command.Command' (put the class name with the package part in this file).

If the new command needs third party products in addition of the ones already provided by Petals Registry CLI, they MUST be installed with your command.

No classloader isolation is available between commands, pay attention to versions of third-party products. They MUST match the version of those provided with Petals Registry CLI or those custom commands.

Custom command installation

To install your command just put all needed JAR files in the directory $PETALS_REG_CLI_HOME/extensions.

Known Problems

Petals Registry CLI seems to be frozen on command 'exit'

You entered the command exit in the interactive mode, and the Petals Registry CLI seems to be frozen: no prompt.
You probably have launched asynchronous commands as defect subscriptions, use Ctrl-C to force to exit the Petals Registry CLI or kill its process.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.