GShell Commands
GShell is a command-line processing environment that can be used for the execution of commands. It includes support for editing, command history, input/output redirection, and more. A number of Geronimo administrative commands have been implemented using GShell.
Excerpt | ||
---|---|---|
| ||
Here is the list for all the GShell commands |
Commands | Description |
---|---|
Display help information | |
Print arguments to STDOUT | |
Load a file or URL to the current shell | |
Clear the terminal screen | |
Set a variable | |
Unset a variable | |
Exit GShell | |
Start a server | |
Stop the server | |
Wait for the server to start | |
Start an application client | |
Connect to a Geronimo server | |
Save the username and password for this connection | |
Disconnect from a Geronimo server | |
Deploy a module | |
Redeploy a module | |
Undeploy a module | |
Distribute a module | |
Start a module | |
Restart a module | |
Stop a module | |
List modules | |
List targets | |
Install plug-ins into the server | |
Install library | |
Install a plug-in | |
Extract a Geronimo server from the current one | |
Connect to a remote GShell server | |
Start a remote GShell server | |
Monitor cluster heartbeat | |
Administer cluster |
Running GShell and Getting Help
A simple launcher script/.bat file is located in the <Geronimo_HOME>/bin
directory, where <Geronimo_HOME> is the server's installation directory.
- On linux/Unix/Solaris, execute <Geronimo_HOME>/bin/gsh.sh
- On Windows, execute <Geronimo_HOME>\bin\gsh.bat
Note: do not launch GShell with the --secure option (supported in Geronimo 2.1.0.1 or later). It is only supported in GShell commands, but not the scripts.
The help (or ?) command alone will display all GShell commands that are available in the current environment. To obtain help information on any specific command, use the --help (-h) option. Here is an example:
No Format |
---|
deploy/list-modules --help
|
or
No Format |
---|
deploy/list-modules -h
|
You can use the exit or quit command to exit GShell.
GShell Commands
Note: Windows users, use forward slash "/" instead of the traditional back slash "\" when specifying directory paths within GShell commands. Using back slash may cause errors in processing the command.
General Options
Here are common options that apply to most of GShell commands:
Option | Usage | Description |
---|---|---|
-u, or --user | -u <user> | It is used to provide username. Initially the user name is system. If you don't provide this option, you will be prompted to. |
-w, or --password | -w <password> | It is used to provide password. Initially the password is manager.If you don't provide this option, you will be prompted to. |
-s, --hostname, or --server | -s <server hostname> | This option can be used to specify the hostname. If no hostname is specified then the hostname defaults to localhost. |
-p, or --port | -p <port> | This option can be used to specify a port to contact the host. If not specified, the default port is 1099. |
--secure | --secure | Can be used to communicate with JMX server via a secure channel.This option is only available in Geronimo 2.1.0.1 or later. |
Note: For Geronimo 2.1.0.1 or above, you can work with the RMI/JMX --secure option in GShell commands. You may need to check Secure option prerequisites before using this option.
Echo or print
The echo (print) command is used to print arguments to STDOUT.
Source
The source command takes an external file (or URL) and reads the content in line by line, executing each line. For example, if you have a file named example.gsh, with its content like this:
Panel | ||||
---|---|---|---|---|
| ||||
echo "Hello" |
In GShell, use source command following this syntax:
No Format |
---|
source ./example.gsh
|
or
No Format |
---|
. ./example.gsh
|
You will get the following results:
No Format |
---|
Hello
Testing source now
Bye
|
Clear
The clear command can be used to clear the screen.
Note: This command is not available on the Windows platform.
Setting and unsetting variables
The set command can be used to set a variable, and follows this syntax:
No Format |
---|
set <variable1>=string
set <variable2>="A string separated by space"
|
variable1 is a variable containing no space or special character, so there is no need to add the quotation marks. Here is an example:
No Format |
---|
set username=system
set password=manager
deploy/connect -u $username -w $password
set newstring="two strings"
echo $newstring
|
The unset command is used to cancel your previous setting.
No Format |
---|
unset <variable>
|
Starting and stopping a server
The server can be started through GShell using the geronimo/start-server command. This command provides the following options:
No Format |
---|
geronimo/start-server -A <JAR> -D <name=value> -G <name=value> -H <dir> -J <flag> -P <name>
-b -j <dir> -l <file> -m <module> -p <port> -q -t <time> -u <user> -v -w <password> --secure
|
These commands are described in the following table except the general options:
Option | Usage | Description |
---|---|---|
-A, or --javaagent | -A <JAR> | Identify the specific Java Agent with a JAR file containing its path. To disable it, set it to 'none'. |
-D, or --property | -D <name=value> | Define system properties. See Java system properties for more information about the property details. |
-G, or --gproperty | -G <name=value> | Define org.apache.geronimo properties. This option is probably used if you start two or more Geronimo instances on your server. |
-H, or --home | -H <dir> | Provide a specific Geronimo home directory. This option is probably used if you start two or more Geronimo instances on your server. |
-J, or --javaopt | -J <flag> | Set a Java Virtual Machine (JVM) flag. See Java command line options for more information about this option. |
-P, or --profile | -P <name> | Select a configuration profile. |
-b, or --background | -b | If provided, the server process will run in the background. |
-j, or --jvm | -j <dir> | Use a specific JVM for the server process. See supported JVMs for JVMs supported by Geronimo. |
-l, or --logfile | -l <file> | Capture the console output to a log file. |
-m, or --module | -m <module> | Start up a specific module. |
-q, or --quiet | -q | Suppress warning and informative message. |
-t, or --timeout | -t <time> | Identify the timeout in seconds. |
-v, or --verbose | -v | Enable verbose output, resulting in more console output than is normally present. |
The server can be stopped using the geronimo/stop-server command. It uses the following syntax:
No Format |
---|
geronimo/stop-server -u <user> -w <password> -s <server hostname> -p <port> --secure
|
See general options for information about the options of this command.
Waiting for the server to start
The geronimo/wait-for-server command is used to verify if the server has started in the given time (in seconds). It has the following syntax:
No Format |
---|
geronimo/wait-for-server -u <user> -w <password> -s <server hostname> -p <port> -t <time> --secure
|
Option | Usage | Description |
---|---|---|
-t, or --timeout | -t <time> | Can be used to specify the time (in seconds) to wait while verifying the that the server has started. |
If the -t option is not provided, the default timeout is 60 seconds. See general options for information about the rest of options.
Starting an application client
Before starting a client, you have to deploy the application to the server. See developing deployment plans for information about deployment plan templates for application clients, and deploying modules for how to deploy your applications to the server.
The geronimo/start-client command has the following syntax:
No Format |
---|
geronimo/start-client <config-name> <args> -A <JAR> -D <name=value> -G <name=value> -H <dir> -J <flag> -P <name>
-b -j <dir> -l <file> -t <time> -v --secure
|
where config-name is the configurations for your application client, and args are application specific arguments. The geronimo/start-client command can be issued with the following options:
Option | Usage | Description |
---|---|---|
-A, or --javaagent | -A <JAR> | Identify the specific Java Agent with a JAR file containing its path. To disable it, set it to 'none'. |
-D, or --property | -D <name=value> | Define system properties. See Java system properties for more information about the property details. |
-G, or --gproperty | -G <name=value> | Define org.apache.geronimo properties. This option is probably used if you start two or more Geronimo instances on your server. |
-H, or --home | -H <dir> | Provide a specific Geronimo home directory. This option is probably used if you start two or more Geronimo instances on your server. |
-J, or --javaopt | -J <flag> | Set a Java Virtual Machine (JVM) flag. See Java command line options for more information about this option. |
-P, or --profile | -P <name> | Select a configuration profile. |
-b, or --background | -b | If provided, the server process will run in the background. |
-j, or --jvm | -j <dir> | Use a specific JVM for the server process. See supported JVMs for JVMs supported by Geronimo. |
-l, or --logfile | -l <file> | Capture the console output to a log file. |
-q, or --quiet | -q | Suppress warning and informative message. |
-t, or --timeout | -t <time> | Identify the timeout in seconds. |
-v, or --verbose | -v | Enable verbose output, resulting in more console output than is normally present. |
Connecting to an already running server
GShell allows you to run a series of commands on a remote server. To do that you first need to connect to the remote server. The deploy/connect command can be used to connect to an instance of Geronimo that is already running.
No Format |
---|
deploy/connect -u <user> -w <password> -s <server hostname> -p <port> --secure
|
See general options for information about the options of this command.
The deploy/disconnect command can be used to disconnect from an already connected server. Since only one instance of the server can be connected at a time, no additional options are needed to specify which server to disconnect from. If you are trying to connect to a second server instance, use this command to disconnect first.
Saving the username and password for current connection
Gshell allows you to save your credential after connecting to a running server. Simply specify your username and password with deploy/login, and you will not be bothered with inputting your credential repeatedly. This command behaves in the same way as login command option of deploy.
No Format |
---|
deploy/login -u <user> -w <password> -s <server hostname> -p <port>
|
See general options for information about the options of this command.
Deploying modules
The deploy/deploy command can be used to deploy a module to a server that you have previously connected to as mentioned in connecting to an already running server. If no existing connection is available, the deploy/deploy command will first establish a connection and then execute the specific command. Once deployed, a module is identified by its module ID within Geronimo. The deploy/deploy command has the following syntax:
No Format |
---|
deploy/deploy <module> <deployment plan> -u <user> -w <password> -s <server hostname> -p <port> -t <target1;target2> -i --secure
|
A module file can be one of the following:
- J2EE Enterprise Application Archive (EAR) file
- J2EE Web Application Archive (WAR) file
- J2EE Enterprise JavaBean Archive (JAR) file
- J2EE Java Resource Archive (RAR) file
If the deployment plan for a WAR file is not in the WEB-INF directory, its location must be specified after the module in the command.
Option | Usage | Description |
---|---|---|
-i, or --inPlace | -i | Can be used to specify an in-place deployment from the directory you are actually developing the application. |
-t, or --targets | -t <target1;target2> | Can be used to specify the repository targets to which the module should be deployed. You can list targets to get a list of targets available on the Geronimo server. |
If the -i option is provided, the path to the application would need to be provided in place of the location of the module. See general options for information about the other options of this command.
Redeploying modules
The deploy/redeploy command is used to deploy a newer version of a module onto a server where the older module is already deployed. It functions in a similar way to deploy/deploy but lacks an in-place deployment option.
The deploy/redeploy command has the following syntax:
No Format |
---|
deploy/redeploy <module> <deployment plan> <module_id> -u <user> -w <password> -s <server hostname> -p <port> --secure |
If you do not specify the module_id, the plan supplied (or plan inside the module) will be used to determine the actual configuration that you wish to redeploy. Redeploying a plan with an existing module ID allows you to modify the configuration of a running module without intermediate undeployment. See general options for information about the options of this command.
Undeploying modules
The deploy/undeploy command is used to properly remove a module from a server. Once undeployed, the module cannot be started again, unless you use the deploy command again. The module id must be provided for the module you wish to undeploy.
No Format |
---|
deploy/undeploy -u <user> -w <password> -s <server hostname> -p <port> <module_id> --secure
|
See general options for information about the options of this command.
Distributing modules
The deploy/distribute command works exactly like deploy/deploy except the module is not started once it has been deployed into the server and is not marked to be started each time the server starts. The command can be issued in the same way, with the same options, as deploy/deploy. The -t option can be used to specify the repository targets to which the module should be distributed. You can list targets to get a list of targets available on the Geronimo server. See general options for information about other options of this command.
No Format |
---|
deploy/distribute <module> <deployment plan> -u <user> -w <password> -s <server hostname> -p <port> -i -t <target1;target2> --secure
|
Starting modules
The deploy/start command starts a previously deployed module that is not running, and uses this syntax:
No Format |
---|
deploy/start -u <user> -w <password> -s <server hostname> -p <port> <module_id> --secure
|
See general options for information about the options of this command.
Stopping modules
The deploy/stop command stops a running module, and uses this syntax:
No Format |
---|
deploy/stop -u <user> -w <password> -s <server hostname> -p <port> <module_id> --secure
|
The command can be issued with the same options, as deploy/start.
Restarting modules
The deploy/restart command ommand restart a module that is already running, or a previously stopped module.
No Format |
---|
deploy/restart -u <user> -w <password> -s <server hostname> -p <port> <module_id> --secure
|
The command can be issued with the same options, as deploy/start.
Listing modules
The deploy/list-modules command lists available modules on an active server, and uses this syntax:
Panel | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||
deploy/list-modules -u <user> -w <password> -s <server hostname> -p <port> filterOptions --secure where
|
By default, all started or stopped modules are displayed. Any started modules are shown with a "+" sign next to them. All Web−tier modules that have a externally accessible URL associated with them will also have this URL shown next to the module. Running modules are represented by their module IDs in Geronimo. See general options for information about other options of this command.
Listing targets
The deploy/list-targets command lists available targets on an active server, and uses this syntax:
No Format |
---|
deploy/list-targets -u <user> -w <password> -s <server hostname> -p <port> --secure
|
See general options for information about the options of this command.
Listing plug-ins
The deploy/list-plugins command lists available configurations on an active server, and uses this syntax:
No Format |
---|
deploy/list-plugins -u <user> -w <password> -s <server hostname> -p <port> -r <repository> -rr -rl --secure
|
The options are explainied in the following table:
Option | Usage | Description |
---|---|---|
-rr, or --refresh-repository | -rr | Refresh the repository. |
-rl, or --refresh-list | -rl | Refresh the plug-in list. |
-r, or --repository | -r <repository> | Can be used to provide the repository URL. |
This command lists server plugins suitable for installation on your configured server, and will allow you to select them to be downloaded and installed. See general options for information about other options of this command.
Installing libraries
The deploy/install-library command can be used to install a library, and uses this syntax:
No Format |
---|
deploy/install-library <libraryFile> -g <groupId> -u <user> -w <password> -s <server hostname> -p <port> --secure
|
where libraryFile specifies the library file, usually a JAR. If the file name is not in a Maven recognizable format, you have to rename it following this format:
No Format |
---|
<artifactId>-<version>.<type>
|
The options are explainied in the following table:
Option | Usage | Description |
---|---|---|
-g, or --groupId | -g <groupId> | Can be used to specify the group ID of the library. |
See general options for information about other options of this command.
If successfully installed, the library will be found in <Geronimo_HOME>/repository
, where <Geronimo_HOME> is the server's installation directory.
Installing a plug-in
The deploy/install-plugin command can be used to install a plug-in (must be a CAR file) on the active server, and uses this syntax:
No Format |
---|
deploy/install-plugin <plugin> -u <user> -w <password> -s <server hostname> -p <port> --secure
|
where plugin specifies the plug-in to be installed. See general options for information about the options of this command.
Assembling
The deploy/assemble command can be used to extract a customer Geronimo server from the current one.
No Format |
---|
deploy/assemble -a <artifact> -f <format> -g <groupId> -l -p <port> -s <server hostname> -t <path> -u <user> -w <password>
-s <server hostname> -p <port> --secure
|
The options are explainied in the following table:
Option | Usage | Description |
---|---|---|
-a, or --artifact | -a <artifact> | Can be used to provide the server artifact name. |
-f, or --format | -f <format> | Can be used to specify if the assembly is in .zip or tar.gz format. |
-g, or --groupId | -g <groupId> | Can be used to specify the group ID of the library. |
-t, or --path | -t <path> | Can be used to provide the assembly location, where your specific plug-ins are stored. |
-l, or --list | -l | Can be used to refresh the plug-in list. |
See general options for information about other options of this command.
Your successfully assembled server will be found in <Geronimo_HOME>/var/temp
, where <Geronimo_HOME> is the server's installation directory.
Wiki Markup |
---|
{scrollbar} |
Excerpt | ||
---|---|---|
| ||
This page provides a list of all Geronimo GShell commands available. |
...
borderStyle | solid |
---|
...