HomeDocumentation > Reference > Tools and commands > gogo commands for Geronimo

The gogo commands for Geronimo is an extension of Apache karaf Shell to interact with Geronimo kernel. Those command names are made up of two parts: <scope>:<name> by convention as listed below. Click each command to learn about its usage.

To enter the karaf shell, press Enter after you start up the Geronimo server using geronimo run command.

Note that if the <name> portion of the command is unique, then you only need to type it. If not, then you must either type the full <scope>:<name> or arrange the scope search path accordingly. For example, you can use list-modules instead of deploy:list-modules to list all modules in the server repository.

Following options are common to those commands:

generaloptions includes:

<p>-s or --server, --hostname</p>
<p>Hostname, default localhost</p>
<p>-p or --port</p>
<p>Port, default 1099</p>
<p>-u or --username</p>
<p>Specify an Username to start the server</p>
<p>-w or --password</p>
<p>Specify the password to start the server</p>
<p>--help</p>
<p>Display this help message</p>

geronimo:start-server

The server can be started through Felix Shell using the geronimo:start-server command. It uses the following syntax:

start-server generaloptions commandoptions

where

commandoptions includes:

<p>-A or --javaagent</p>
<p>Use a specific Java Agent, set to <em>none</em> to disable</p>
<p>-b or --background</p>
<p>Run the server process in the background</p>
<p>-D or --property</p>
<p>Define system properties</p>
<p>-G or --gproperty</p>
<p>Define server system properties</p>
<p>-H or --home</p>
<p>Use a specific server home directory</p>
<p>-j or --jvm</p>
<p>Use a specific Java Virtual Machine for server process</p>
<p>-J or --javaopt</p>
<p>Set a Java Virtual Machine flag</p>
<p>-l or --logfile</p>
<p>Capture console output to a specified log file</p>
<p>-m or --modules</p>
<p>Start up a specific module by name</p>
<p>-P or --profile</p>
<p>Specify a configuration profile</p>
<p>-q or --quite</p>
<p>Suppress informative and warning messages</p>
<p>-t or --timeout</p>
<p>Specify the timeout for the server process in seconds</p>
<p>-v or --verbose</p>
<p>Enable verbose output; specify multiple times to increase verbosity</p>
<p>--secure</p>
<p>Use secure channel</p>

Back to Top

geronimo:stop-server

The server can be stopped using the geronimo/stop-server command. It uses the following syntax:

stop-server generaloptions commandoptions

Where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

stop-server command examples

Use this syntax to stop the server.

server> geronimo:stop-server --hostname localhost -p 1099

Back to Top

geronimo:wait-for-server

The command is used to verify if the server has started in the given time (in seconds). It uses the following syntax:

wait-for-server generaloptions commandoptions

Where

commandoptions includes:

<p>-t or --timeout</p>
<p>Specify the time (in seconds) to wait while verifying the that the server has started. 60 seconds by default</p>

Back to Top

deploy:login

The command is used to save the username and password for the current connection to a file to avoid future prompting. This command is used for remote connections only. It has the following syntax:

login generaloptions commandoptions

where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

login command examples

Use this syntax to save the username and password of the current connection so that you will not be prompted for credentials again when you issue other commands via the connection. Make sure you use deploy:connect firstly to connect to a remote instance, then use deploy:login to record the credential.

server> deploy:login

Back to Top

deploy:encrypt

The command is used to generates an encrypted string using org.apache.geronimo.util.EncryptionManager. It has the following syntax:

encrypt commandoptions string

where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

string is a string to be encrypted

encrypt command examples

Use this syntax to encrypt string passw0rd on an active server so that the encryption settings of that server will be used.

server> deploy:encrypt passw0rd


Online encryption result is shown below:

String to encrypt: passw0rd
Online encryption result:
{Simple}rO0ABXNyABlqYXZheC5jcnlwdG8uU2VhbGVkT2JqZWN0PjY9psO3VHACAARbAA1lbmNv
ZGVkUGFyYW1zdAACW0JbABBlbmNyeXB0ZWRDb250ZW50cQB+AAFMAAlwYXJhbXNBbGd0ABJMamF2YS9s
YW5nL1N0cmluZztMAAdzZWFsQWxncQB+AAJ4cHB1cgACW0Ks8xf4BghU4AIAAHhwAAAAEG2NoqXONCcU
GqfK0reVCpVwdAADQUVT

Back to Top

deploy:assemble-server

The command is used to extract a customized server assembly from the current one. It has the following syntax:

assemble-server generaloptions commandoptions

Where

commandoptions includes:

<p>-a, or --artifact</p>
<p>Specify the artifact name of target server</p>
<p>-f, or --format</p>
<p>Specify if the assembly is in .zip or tar.gz format</p>
<p>-g, or --groupId</p>
<p>Specify the group ID of the library</p>
<p>-t, or --path</p>
<p>Specify the assembly location, where your specific plug-ins are stored. The default location is <code>&lt;ce_home&gt;/var/temp/</code> </p>
<p>-l, or --list</p>
<p>Refresh the plug-in list</p>

assemble-server command examples

Use this syntax to create a custom server assembly, which is placed at <ce_home>/var/temp/.

server> deploy:assemble-server -f zip -g group1 -a assemble1

Back to Top

geronimo:start-client

The command is used to start a Java EE application client. Note that before starting a client, you have to deploy the application to the server. It has the following syntax:

start-client generaloptions commandoptions

Where

commandoptions includes:

<p>-A or --javaagent</p>
<p>Use a specific Java Agent, set to <em>none</em> to disable</p>
<p>-b or --background</p>
<p>Run the server process in the background</p>
<p>-D or --property</p>
<p>Define system properties</p>
<p>-G or --gproperty</p>
<p>Define server system properties</p>
<p>-H or --home</p>
<p>Use a specific server home directory</p>
<p>-j or --jvm</p>
<p>Use a specific Java Virtual Machine for server process</p>
<p>-J or --javaopt</p>
<p>Set a Java Virtual Machine flag</p>
<p>-l or --logfile</p>
<p>Capture console output to a specified log file</p>
<p>-P or --profile</p>
<p>Specify a configuration profile</p>
<p>-t or --timeout</p>
<p>Specify the timeout for the server process in seconds</p>
<p>-v or --verbose</p>
<p>Enable verbose output; specify multiple times to increase verbosity</p>

Back to Top

deploy:connect

The command is used to connect to an instance of server that is already running. After connected successfully, you can run a series of commands on the remote server. It has the following syntax:

connect generaloptions commandoptions

Where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

Note that you can also use ssh:ssh command provided by Karaf shell to connect to a remote instance.

connect command examples

Use this syntax to connect to a remote server instance:

server> deploy:connect -u system -p manager -s <remote-ip>

Back to Top

deploy:disconnect

The command is used to close the connection to a remote server. 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. It has the following syntax:

disconnect

disconnect command examples

Use this syntax to disconnect a current connection.

server> deploy:disconnect

Back to Top

deploy:deploy-module

The command is used to deploy a module to the server. Once deployed, a module is identified by its module ID within the server. It has the following syntax:

deploy-module generaloptions commandoptions <module> <deployment plan>

where

module is a module file, which is required for the command and can be one of the following Java applications:

<ul> <li>Java EE Enterprise Application Archive (EAR) file</li> </ul>
<ul> <li>Java EE Web Application Archive (WAR) file</li> </ul>
<ul> <li>Java EE Enterprise JavaBean Archive (JAR) file</li> </ul>
<ul> <li>Java EE Java Resource Archive (RAR) file</li> </ul>
<ul> <li>Web Archive Bundle(WAB) file</li> </ul>
<ul> <li>Enterprise Bundle Archive(EBA) file</li> </ul>

deployment plan is an optional plan file for Java EE module. If the deployment plan for a Java EE archive file is not in the WEB-INF directory, its location must be specified after the module in the command. See Creating deployment plans for more details.
commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>
<p>-i or --inPlace</p>
<p>Add and start an archive or directory to an active server, without the archive or directory being copied into the server directory tree</p>
<p>-t or --targets</p>
<p>Specify the target repository to be deployed into. See <a href="#gogocommandsforGeronimo-gogocommandlisttargets">list-targets</a> for the names of repositories available on the server.</p>

deploy-module command examples

Use this syntax to deploy a WAR file.

deploy-module d:/HelloWorld.war

Use this syntax to deploy a WAR file whose deployment plan is located outside of the WEB-INF directory.

server> deploy:deploy-module d:/HelloWorld.war d:/geronimo-web.xml

Back to Top

deploy:distribute-module

The command works exactly like deploy-modules 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. It has the same syntax and options as deploy-modules:

distribute-module generaloptions commandoptions <module> <deployment plan>

distribute command examples

Use this syntax to distribute a module whose deployment plan is located outside of the WEB-INF directory.

server> deploy:distribute-module d:/HelloWorld.war d:/geronimo-web.xml

Back to Top

deploy:list-targets

The command is used to list all available target repositories on the server. It has the following syntax:

list-targets generaloptions commandoptions

where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

list-targets command examples

Use this syntax to list all available target repository where you can deploy applications to on the localhost.

server> deploy:list-targets
Available Targets:
org.apache.geronimo.framework/j2ee-system/3.0-SNAPSHOT/car?ServiceModule=org.apache.geronimo.framework/j2ee-system/3.0-SNAPSHOT/car,j2eeType=ConfigurationStore,name=Local

Back to Top

deploy:list-plugins

The command is used to list all of plug-ins in a Geronimortain maven repository. It has the following syntax:

list-plugins generaloptions commandoptions

where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>
<p>-rr or --refresh-repository</p>
<p>refresh repository</p>
<p>-r or --repository</p>
<p>repository URL</p>
<p>-rl or --refresh-list</p>
<p>referensh plug-in list</p>

list-plugins command examples

Use this syntax to first access the list of repositories. Select a repository from the list, plug-ins in this repository is displayed.

list-plugins

Use this syntax to display the list of plug-ins in the given repository using secure channel.

server> deploy:list-plugins --secure -r http://geronimo.apache.org/plugins/geronimo-3.0/

Back to Top

deploy:new-server-instance

The command is used to create a new server instance. It has the following syntax:

new-server-instance generaloptions commandoptions instancename

where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

instancename is the name of the new instance.

new-server-instance command examples

Use this syntax to create a new server instance instance2.

server> deploy:new-server-instance instance2

Back to Top

deploy:redeploy-module

The command is used to deploy a newer version of a module onto a server where the older module is already deployed. It has the following syntax:

redeploy-module generaloptions commandoptions <module> <deployment plan> <module id>

where

module is a module file, which is required for the command and can be one of the following Java applications:

<ul> <li>Java EE Enterprise Application Archive (EAR) file</li> </ul>
<ul> <li>Java EE Web Application Archive (WAR) file</li> </ul>
<ul> <li>Java EE Enterprise JavaBean Archive (JAR) file</li> </ul>
<ul> <li>Java EE Java Resource Archive (RAR) file</li> </ul>
<ul> <li>Web Archive Bundle(WAB) file</li> </ul>

deployment plan is an optional plan file for Java EE module. If the deployment plan for a Java EE archive file is not in the WEB-INF directory, its location must be specified after the module in the command. See Understanding deployment plans for more details.
module id is the configuration on the server you want to replace. 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.
commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

redeploy-module command examples

Use this syntax to deploy a newer version of an existing module .

server> deploy:redeploy-module D:/HelloWorld.war default/HelloWorld/1.0/car

Back to Top

deploy:undeploy-module

The command is used to properly remove a module from a server. It has the following syntax:

undeploy-module generaloptions commandoptions <module id>

where

module id is the configuration name you want to remove from the server. It must be provided.
commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

undeploy-module command examples

Use this syntax to remove an existing module.

server> deploy:undeploy-module default/HelloWorld/1.0/car

Back to Top

deploy:start-module

The command is used to start an existing module on the server which is not running. It use the following syntax:

start-module generaloptions commandoptions <module id>

where

module id is the configuration name you want to start on the server. It must be provided.
commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

start-module command examples

Use this syntax to start an existing module.

server> deploy:start-module default/HelloWorld/1.0/car

Back to Top

deploy:stop-module

The command is used to stop a running module on the server. It use the following syntax:

start-module generaloptions commandoptions <module id>

where

module id is the configuration name you want to stop on the server. It must be provided.
commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

stop-module command examples

Use this syntax to stop a running module.

server> deploy:stop-module default/HelloWorld/1.0/car

Back to Top

deploy:restart-module

The command is used to restart a module on the server. It has the following syntax:

restart-module generaloptions commandoptions <module id>

where

module id is the configuration name you want to restart on the server. It must be provided.
commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

restart-module command examples

Use this syntax to restart a module.

server> deploy:restart-module default/HelloWorld/1.0/car

Back to Top

deploy:list-modules

The command is used to list modules in the target repository. It has the following syntax:

list-modules generaloptions commandoptions <targetname>

where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>
<p>-t or --stopped</p>
<p>Show stopped modules only</p>
<p>-r or --started</p>
<p>Show started modules only</p>
<p>-a or --all</p>
<p>Show both started and stopped modules, this one is default if you did not specify any parameters</p>

targetname is the name of target repository. See list-targets for more details.

list-modules command examples

Use this syntax to list the started modules in the target repository.

server> deploy:list-modules -r

Back to Top

deploy:install-plugin

The command is used to install a geronimo plug-in into the server. It has the following syntax:

install-plugin generaloptions commandoptions <configuration archive>

where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

configuration archive is the fully qualified name of plug-in archive. The archive must be a valid plug-in file with .car suffix.

install-plugin command examples

Use this syntax to deploy a CAR file.

server> deploy:install-plugin d:/HelloWorld-1.0.car

Back to Top

deploy:install-library

The command is used to install a Java library file into the server. Meanwhile, the library file will be converted into an OSGi by the server. It has the following syntax:

install-library generaloptions commandoptions <configuration archive>

where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>
<p>-g or --groupId </p>
<p>Specify the group ID of the library</p>

configuration archive is the fully qualified name of library archive.

If installed successfully, the library will be found in <geronimo_home>/repository. Meanwhile, the library file will be converted into an OSGi by the server.

install-library command examples

Use this syntax to install a java library file.

server> deploy:install-library d:/temp/openejb-ejbd-3.2-SNAPSHOT.jar

Back to Top

deploy:install-bundle

The command is used to install an OSGi bundle or a common jar library file into the server(the jar file will be converted into an OSGi bundle), and the bundle information will be recorded in etc/startup.properties file. It has the following syntax:

install-bundle generaloptions commandoptions <bundle file>

where

commandoptions includes:

<p>--groupId</p>
<p>Defines a group Id for the bundle.</p>
<p>--startLevel</p>
<p>Specifies start level of the bundle.</p>
<p>--start</p>
<p>Specifies whether to start the bundle after installation. By default, the bundle is not started.</p>

bundle file is the fully qualified name of bundle to be installed.

install-bundle command examples

Use this syntax to install an OSGi bundle. If the file is a jar library file, the library file will be converted into an OSGi bundle by the server.

server> deploy:install-bundle --groupId myCompany --start --startLevel 100 d:/HelloWorld-1.0.jar

Back to Top

deploy:uninstall-bundle

The command is used to uninstall a bundle in server. It has the following syntax:

unlinstall-bundle generaloptions commandoptions bundleId

where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

bundleId is id of the bundle to be uninstalled.

uninstall-bundle command examples

Use this syntax to uninstall an OSGi bundle with id 361 in the server.

server> deploy:uninstall-bundle 361

Back to Top

deploy:unlock-keystore

The command is used to unlock a keystore and private key in server. It has the following syntax:

unlock-keystore generaloptions commandoptions <keystore>

where

commandoptions includes:

<p>--secure</p>
<p>Use secure channel</p>

keystore is the name of keystore or private key you want to unlock.

Back to Top

equinox:diagnose

The command is used to diagnose constraints of an installed OSGi bundle and verify if the bundle can be resolved successfully. The command is only available in Equinox OSGi runtime.

diagnose generaloptions commandoptions <bundleIDs>

where
commandoptions includes:

<p>-s or --simple</p>
<p>Do not perform deeper analysis of resolver problems</p>

bundleIDs is a list of bundle IDs seperated by whitepaces.

diagnose command examples

Use this syntax to diagnose the resolver problem of a bundle with Id 85.

server> diagnose 85
mvn:org.apache.geronimo.framework/geronimo-service-builder/3.0-SNAPSHOT [85]
No unresolved constraints.

Back to Top

eba:resolve

The command is used to resolve constraints of an Aries applications and create the deployment manifest application.MF for the application.

resolve generaloptions commandoptions <AppPath>

where
commandoptions includes:

<p>-o or --out</p>
<p>Specify the name of a file to write the application in.</p>

AppPath is location of Aries application to be resolved.

resolve command examples

Use this syntax to resolve an Aries application.

server> eba:resolve d:/temp/myAriesApp.eba
Attempting to resolve myAriesApp application.
Application myAriesApp is now resolved.

Back to Top

obr:geronimo-refresh

The command is used to refresh bundle status in the repository of Geronimo server. This command is useful when you installed a new bundle in to Geronimo server and want the bundle information to be added in to the bundle repository of the server.

geronimo-refresh generaloptions

Back to Top