E-mail
IntroductionPetals Registry CLI is a command line client to administrate a set of Petals Registry Overlay nodes.
To work, Petals Registry CLI needs to establish a connection with a Petals Registry node.
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>
|
Table of contents
Contributors
No contributors found for: authors on selected page(s)
|
Use 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.