The Command-Line Deployer


The actual deployer is located in the following JAR file:

 <geronimo installation dir>/bin/deployer.jar

To use this deployer, a Win32 batch script and *nix shell script is provided in the same directory:

  • deploy.bat

  • deploy.sh

For ease of use, this batch file or *nix shell script should be added to your PATH environment variable. Even without installing the deployer script file, however, the deployer can always be accessed via the following command issued from the <geronimo installation directory>:

 java -jar bin/deployer.jar [options]  command [command options]

When using one of the script files, the command line is simplified to:

 deploy [options]  command [command options]

Available Options

The options available for the deployer include the following:

  • --uri

  • --host

  • --port

  • --driver

  • --user

  • --password

  • --syserr

  • --verbose

  • --offline

Each of these options is described in the following sections.

The --uri Option

The URI to a Geronimo server instance is where the target for deployment resides. Deployed modules are sent to this server. If not specified, the default is the Geronimo server running on the local machine.

The general URI syntax, for Geronimo servers, is:

 deployer:geronimo:jmx[://host[:port]]

For example, to see the modules running on a server running on 192.168.1.11, port 3030, use the following command:

 deploy --uri deployer:geronimo:jmx://192.168.1.11:3030 list-modules

When this option is used, the --host or --port must not be specified. This option is an alternative to --host/--port when specifying a deployment Geronimo server instance.

The --host Option

This option is usually used in conjunction with --port. It specifies a Geronimo server instance, where the deployment will be performed.

When using the --host and --port options, you must not use the --uri option.

For example, to see the modules running on a server running on 192.168.1.11, port 3030, use the following command:

 deploy --host 192.168.1.11  --port 3030 list-modules

The default is the local host.

The --port Option

This option is usually used in conjunction with --host option. It specifies the TCP port at which a Geronimo server instance listens to for deployment commands.

When using the --host and --port options, you must not use the --uri option.

See the preceding section, “The --host Option” for a usage example. The default port value is 1099. This is also the default port that a Geronimo instance will listen to for deployment commands.

The --driver Option

Since the deployer is actually a JSR-88–complaint client, it is capable of accepting other JSR-88 complaint server drivers. This should allow the deployer to be used with other non-Geronimo servers in the future.

The syntax is:

 deploy --driver <path to JSR-88 plugin JAR>  list-modules

The default value is the Geronimo’s JSR-88 driver JAR.

The --user Option

This option specifies the username used in authentication with the server to gain deployment access on the target server. By default, the Geronimo server is configured with a geronimo-properties-realm security realm. This default realm contains a single user that has deployment access, called system.

In production, the deployer can be configured to allow deployment access only from specific authenticated users. An example usage (for the default configuration) is:

 deploy --user system --password manager list-modules

The --password Option

Use this option in conjunction with the --user option to authenticate a user for deployment access to the target Geronimo instance. By default, the Geronimo server is configured with a geronimo- properties-realm security realm. This default realm contains one single user that has deployment access. This user is named system and has its password set to be manager.

See the preceding section, “The --user Option” for an example.

The --syserr Option

The option causes deployer logging to be displayed to the syserr stream. Typically, this is the same console where the deployment command is issued.

By default, no logging will be printed to the console.

The --verbose Option

Enabling this option causes the deployer to print detailed information to the console during its operation.

By default, the status output is relatively sparse and uncluttered. Use this option to troubleshoot deployment problems.

The --offline Option

Run the deployer on the local server without requiring a running instance of the Geronimo server locally. For example, to see the modules deployed on the local server, even when no Geronimo server is running, use the following command:

 deploy --offline list-modules

Available Commands

The following sections describe the commands available with the deployer, as well as their associated command options.

The help Command

This is a handy command that can be used to display the options, commands, and command options that are available with the deployer. For general usage help, simply run the deployer with no options or commands:

 deploy

To see all the options available, use the following command:

 deploy help options

To see a description of any available command, use the following command:

 deploy help <command>

For example, to get help on the deploy command, use the following from the command line:

 deploy help deploy

The deploy Command

This is the primary command used to install a module, together with an optional plan, to a Geronimo server instance. The general syntax, with command options, is:

 deploy deploy [--targets target1;target2;target 3;...]  [module] [plan]

The optional targets specification is a standard part of JSR-88, but it is not currently used by Geronimo. In the future, it may be used in scenarios where a Geronimo server can contain and manage multiple configuration stores.

The module is a J2EE deployable module, such as a WAR, EAR, JAR or RAR containing EJBs or JCA connectors, and so on. If the deployment descriptors included in the module are sufficient to deploy the module, there is no need to specify a plan. In the cases where a Geronimo-specific plan is already included in the module archive being deployed, there is also no need to specify a plan.

Note that when Geronimo-specific deployment plans are specified with the deploy command, the deployment plan can have any name. For example, if you specify a Geronimo-specific deployment plan for a WAR file during deployment, it does not have to be named geronimo-web.xml.

Occasionally, you may be deploying a module whose binaries are already uploaded to the Geronimo code repository. For example, you may be deploying a JDBC connector that is included in the Geronimo distribution. In these cases, the dependencies specified in the deployment plan refers to these predeployed modules, and there is no need to specify a module with the deploy command.

Once deployed, a module is identified by its module ID within Geronimo. This is a key concept since most of the other deployment commands work with module IDs.

The undeploy Command

This command stops a running module via the module ID and then uninstalls all the configuration information files and binaries from the server instance. The general syntax of this is command is as follows:

 deploy undeploy <module ID> [<module ID> ....]

This command actually has a generalized JSR-88 syntax that specifies a TargetModuleID (instead of <module ID> shown in the syntax) that can include a target (cluster or host) identification. You specify this by using the following notation:

 <target name>|<module ID/module name>

But this generalized syntax is not required by Geronimo at this time. Geronimo only supports a single target.

This command will remove the configuration from the config-store. The module cannot be started again, once undeployed, unless you use the deploy command again.

If the intention is to undeploy and then deploy again, this can be accomplished in one single step, using the redeploy command.

The redeploy Command

This command provides the following sequence of operations:

  1. Stops the specified configuration

  2. Undeploys the specified configuration from the server

  3. Deploys the specified module and/or plan to the server

  4. Starts the specified module

See the previous sections about the undeploy command, and the deploy command for more details on the deployment process. Note that the module is always started after this command.

The general command syntax is:

 deploy redeploy [module] [plan] [<module ID> [<module ID> ....]]

This command actually has a generalized JSR-88 syntax that specifies a TargetModuleID (instead of <module ID> shown in the syntax) that can include a target (cluster or host) identification. You specify this by using the following notation:

 <target name>|<module ID/module name>

But this generalized syntax is not required by Geronimo at this time. Geronimo only supports a single target.

With Geronimo, you will only specify a single <module ID>, if any, with this command.

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.

The start Command

This command starts module(s) running in the Geronimo server. The general syntax is:

 deploy start [<module ID> [<module ID> ....]]

This command actually has a generalized JSR-88 syntax that specifies a TargetModuleID (instead of <module ID> in the syntax) that can include a target (cluster or host) identification. You specify this by using the following notation:

 <target name>|<module ID/module name>

But this generalized syntax is not required by Geronimo at this time. Geronimo only supports a single target.

If you specify more than one <module ID>, Geronimo will attempt to start each one.

The <module ID> you specify must represent modules that are already deployed into the Geronimo server or system modules.

The stop Command

This command stops running configuration(s) in the Geronimo server. The general syntax is:

 deploy stop [<module ID> [<module ID> ....]]

This command actually has a generalized JSR-88 syntax that specifies a TargetModuleID (instead of <module ID> in the syntax) that can include a target (cluster or host) identification. You specify this by using the following notation:

 <target name>|<module ID/module name>

But this generalized syntax is not required by Geronimo at this time. Geronimo only supports a single target.

If you specify more than one <module ID>, Geronimo will attempt to stop each one.

The <module ID> you specify must represent a configuration that is current running on the Geronimo server.

The login Command

The main purpose of this command is save the tedious repeated use of --user <username> --password <password> options required when using the deployer repeatedly.

The general syntax for the command is:

 deploy [--uri <uri to host>] --user <username>  --password <password> login

This command will save the login information (including both username and password) to the user’s home directory (may be at different locations, depending on the operating system used) in a file named .geronimo-deployer (which is hidden in a *nix environment).

The command recognizes the use of --uri or --host and --port. It will maintain and manage login information for multiple hosts that you deploy to.

The list-modules Command

This command displays all the deployed modules on the server. Running modules are represented by their module IDs in Geronimo. By default, the --all option is used, and 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.

The general syntax for the command is:

 deploy list-modules [--all | --started | --stopped] [target*]

The --started command option will restrict the listing to only started modules. The --stopped command option will restrict the listing to only stopped modules.

The target option is applicable to generalized JSR-88 deployment. Geronimo typically only supports one single target at this point. In specialized situations involving multiple configuration stores (say, one that is read-only on CD-ROM, and one on disk), targets may be useful. This option is typically not used with Geronimo.

The list-targets Command

This command lists all the possible targets when issuing a command from the Geronimo server instance. Currently, Geronimo supports only one form of multiple targets - multiple configuration stores. This may be useful in specialized situations (say, one configuration store is read-only on CD-ROM, and the other one is on disk). However, the default, and typical Geronimo configuration involves only one single configuration store, and, therefore, one single target.

The general syntax for the command is:

 deploy list-targets

This command may be more useful when using the deployer with other JSR-88–compliant servers. The following is the typical output from the command:

 Available Targets:   geronimo/j2ee-system/1.1/car?ServiceModule=geronimo/j2ee-system/1.1/car,j2eeTy pe=ConfigurationStore,name=Local

The distribute Command

This command installs the module to the target but does not start it. The command does not mark the distributed module to start, and the module will not be started even if the server restarts. You must use the start command to start this module. The general command is as follows:

 deploy distribute [--inPlace] [--targets target1;target2;target 3;...]  [module] [plan]

The command options are meaningful when using a JSR-88–compliant server. Geronimo currently only supports a single target. The --inPlace option enables a server to execute the module without copying it to the configuration store (repository), but this is not supported by Geronimo at this time.

The search-plugins Command

This command will search for and display all available Geronimo plug-ins from a specified repository. You will also be prompted to select a plug-in for installation. The general command is as follows:

 deploy search-plugins <repository URL>

For example, to see all of the plug-ins available at the www.geronimoplugins.com repository, use the following command:

 deploy search-plugins  http://www.geronimoplugins.com/repository/geronimo-1.1/

A typical listing of available plug-ins may look like this:

     Security         1 : Apache Directory 0.92 for Geronimo (1.1)     Core Geronimo             Geronimo Admin Console (Jetty) (1.1)             Geronimo Admin Console (Tomcat) (1.1)             Geronimo Welcome Web App (Jetty) (1.1)             Geronimo Welcome Web App (Tomcat) (1.1)     Scheduling         2 : Quartz Job Deployer (0.1)         3 : Quartz Scheduler Integration (0.1)         4 : Quartz Scheduler Integration (0.2)         5 : Quartz Job Deployer (0.2)     Examples             Jakarta JSP Examples (Jetty) (1.1)         6 : Jakarta JSP Examples (Tomcat) (1.1)             LDAP Example Web App (Jetty) (1.1)         7 : LDAP Example Web App (Tomcat) (1.1)         8 : LDAP Example Security Realm (1.1)             Jakarta Servlet Examples (Jetty) (1.1)         9 : Jakarta Servlet Examples (Tomcat) (1.1)     Resources             Oracle XA Driver for Console (Jetty) (1.0)         10: Oracle XA Driver for Console (Tomcat) (1.0) Install Service [enter number or 'q' to quit]:

You can then install a plug-in by simply entering the corresponding number.

The install-plugin Command

The install-plugin command can be used to install a specified plug-in (CAR) file. The general form of this command is as follows:

 deploy install-plugin <CAR file of plugin>

For example, to install a previously downloaded Tomcat JSP examples CAR plug-in file, use the following command:

 deploy install-plugin jsp-examples-tomcat-1.1.car

The result is:

 Checking for status every 1000ms: Downloading geronimo/jsp-examples-tomcat/1.1/car... (125%) Downloading geronimo/jsp-examples-tomcat/1.1/car... (166%) Downloaded geronimo/jsp-examples-tomcat/1.1/car (1088 kB) (100%)     **** Installation Complete!     Used existing: geronimo/j2ee-server//car     Used existing: geronimo/tomcat//car     Downloaded 1088 kB in 3s (362 kB/s)     Now starting geronimo/jsp-examples-tomcat/1.1/car...     Started geronimo/jsp-examples-tomcat/1.1/car @     http://localhost:8080/jsp-examples




Professional Apache Geronimo
Professional Apache Geronimo (Wrox Professional Guides)
ISBN: 0471785431
EAN: 2147483647
Year: 2004
Pages: 148

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net