Chapter 3. Command Line Interface
The command line interface component provides an interactive shell. The shell uses CRaSH to map commands to management requests. It connects over SSH, using the CRaSH SSH plugin.
For more information on CRaSH, see http://code.google.com/p/crsh/.
3.1. Deploying the Command Line Interface
The portal distribution includes an archive of the gatein-management-cli application.
To deploy the application, copy
JPP_DIST/gatein-management/gatein-management-cli.war to JPP_DIST/standalone/deployments/.
3.2. Running the Command Line Interface
The syntax of the command to connect to CLI over SSH is as follows:
ssh -p <port> <user>@<host>
You can change the default port that SSH listens on by changing the property
crash.ssh.portin the JPP_DIST/standalone/deployments/gatein-management-cli.war/WEB-INF/crash/crash.properties file.
Example 3.2. crash.properties
# VFS configuration crash.vfs.refresh_period=1 # SSH configuration crash.ssh.port=2000
Important
Ensure the configured port is open, and not blocked by firewall settings.
3.3. Management Commands
The CLI component consist of management commands. These commands execute operations on managed resources in the portal. To view the list of available commands type
help in the shell.
You can add the help option
-h or --help for each command or execute the man command for detailed information about the command.
3.3.1. Using the mgmt command
The mgmt command allows a user to connect and disconnect from the management system. It also provides an
exec command which allows custom control over executing operations with the management system.
Example 3.3. mgmt help
% mgmt -h usage: mgmt[-h | --help] COMMAND [ARGS] The most commonly used mgmt commands are: exec Manually executes a management operation connect login to gatein management disconnect disconnect from management system % mgmt connect -h usage: mgmt [-h | --help] connect [-u | --username] [-p | --password] [-c | --container] [-h | --help] command usage [-u | --username] the user name [-p | --password] the user password [-c | --container] portal container name (default is portal) %
The
mgmt connect command allows you to connect to the management system. You can optionally specifying a portal container (default is 'portal') overriding the default container. The management commands are administrative operations so you must authenticate again in order to validate authorization to the portal container.
Example 3.4. Connecting to default portal container
% mgmt connect Password: Successfully connected to gatein management system: [user=root, container='portal', host='127.0.0.1'] [ /]%
Example 3.5. Connecting to portal container 'sample-portal' as user john
% mgmt connect -u john -c sample-portal Password: Successfully connected to gatein management system: [user=john, container='sample-portal', host='127.0.0.1'] [ /]%
The
mgmt exec command allows complete control over what to send to the management system.
Example 3.6. mgmt exec help
[ /]% mgmt exec -h usage: mgmt [-h | --help] exec [-c | --contentType] [-f | --file] [-a | --attribute] [-o | --operation] path [-h | --help] command usage [-c | --contentType] content type of an operation [-f | --file] File name [-a | --attribute] Specifies an attribute. [-o | --operation] Operation name path [ /]%
Example 3.7. Executing operation read-config-as-xml on managed component foo
[ /]% mgmt exec --operation read-config-as-xml --contentType xml /foo <?xml version='1.0' encoding='UTF-8'?> <data>...</data> [ /]%
3.3.2. Using the cat command
The
cat command executes the read-config-as-xml operation on a managed resource and outputs the XML data to the shell. The managed resource must support the read-config-as-xml operation.
Example 3.8. cat help
usage: cat [-h | --help] path    [-h | --help] command usage    path [ /]% cat /foo <?xml version='1.0' encoding='UTF-8'> <data>...</data> [ /]% [ /]% cat -h
3.3.3. Using the cd command
The cd command changes the current path of the CLI.
Example 3.9. cd help
[ /]% cd -h usage: cd [-h | --help] path    [-h | --help] command usage    path [ /]%
3.3.4. Using the ls command
The
ls command executes the read-resource operation on the current (or specified by the path) managed resource.
Example 3.11. ls help
[ /]% ls -h usage: ls [-h | --help] path [-h | --help] command usage path [ /]% ls foo bar [ /]% ls /foo baz [ /]%
3.3.5. Using the pwd command
The
pwd command prints out the current resource path of the CLI.
Example 3.12. pwd help
[ /]% pwd -h usage: pwd [-h | --help] [-h | --help] command usage [ /]% pwd / [ /]% cd foo/baz [baz]% pwd /foo/baz [baz]%
3.3.6. Using the export command
The
export operation executes the export-resource operation on a managed resource and writes the content to the file.
Important
The CLI is connected to the portal server over SSH so the export command writes to the server's file system.
Example 3.13. export help
[ /]% export -h usage: export [-h | --help] [-f | --file] [-r | --filter] path [-h | --help] command usage [-f | --file] File name [-r | --filter] For example, specifies the value of the filter to use during an export. path [ /]%
Example 3.14. Export resource foo to /tmp directory
[ /]% export --file /tmp foo Export complete ! File location: /tmp/foo_2011-10-21_18-29-36.zip [ /%]
Note
If you only specify a directory the export command will write a file with the name of the managed resource and a timestamp.
Example 3.15. Export resource /foo to /tmp/export-example.zip file
[ /]% export --file /tmp/export-example.zip foo Export complete ! File location: /tmp/export-example.zip [ /%]
Example 3.16. Export resource filtering on path template variable bar
[ /]% export --file /tmp/export-filter-example.zip --filter bar:baz,foo-bar foo Export complete ! File location: /tmp/export-filter-example.zip [ /%]
3.3.7. Using the import command
The
import command executes the import-resource operation on a managed resource.
Example 3.17. import help
[ /]% import -h usage: importfile [-h | --help] [-f | --file] [-m | --importMode] path [-h | --help] command usage [-f | --file] File name [-m | --importMode] The import mode for an import operation path [ /]%
Important
Since the CLI is connected to the portal server over SSH, the import command must specify a file that exists on the server.
Example 3.18. Import file /tmp/foo.zip to resource foo
[ /]% import --file /tmp/foo.zip /foo Successfully imported file /tmp/foo.zip [ /]%
Example 3.19. Import file /tmp/foo.zip to resource foo using importMode overwrite
[ /]% import --file /tmp/foo.zip --importMode overwrite /foo Successfully imported file /tmp/foo.zip [ /]%
Note
You can auto complete the import modes by typing --importMode and pressing the Tab key.
3.3.8. Using the Secure copy (SCP) command
The CLI application supports SCP to execute the
export-resource and import-resource operations. These operations are executed in order to export to and import from a host other than the portal.
Exporting
To execute the export-resource operation using SCP, the source of the SCP command is the portal server and the target is the local file to which the resource is to be exported. The command syntax for exporting is: $ scp -P <port> <user>@<host>:{portal-container}:{path} <file> The portal-container is optional with default value being 'portal'. The path is the path of the resource supporting the export-resource operation. So to export 'foo/bar' resource assuming the CLI is deployed to 'example.org'.
Example 3.21. Export of foo/bar resource with filter
Attributes like 'filter' can be added to the path of the SCP command just as you would add query parameters to a URL.
$ scp -P 2000 'root@example.org:portal:/foo/bar?filter=bar:baz,foo-bar' foo.zip
Importing
To execute the import-resource operation using SCP, the source of the SCP command is the local file and the target is the portal server.The command syntax for exporting is: $ scp -P <port> <file> <user>@<host>:{portal-container}:{path} The portal-container is optional with default value being 'portal'. The path is the path of the resource that supports the import-resource operation. So to import a foo.zip file to the /foo resource assuming the CLI is deployed to 'example.org'.
More specific examples of the SCP command can be found below pertaining to that particular management extension.