README.txt

======================================================
Apache Geronimo v2.2.1 

http://geronimo.apache.org/
------------------------------------------------------


______________________
Release Notes
======================

 Please read the RELEASE_NOTES-2.2.1.txt for a complete list of new features 
 available in this release. 
 
  
______________________
Documentation
======================
 
 This README serves as quick introduction to Geronimo. More complete
 documentation can be found here:
 
   -  http://cwiki.apache.org/GMOxDOC22/documentation.html
   OR
   -  http://cwiki.apache.org/GMOxDOC21/documentation.html


______________________
Installing Geronimo
======================

 To install Geronimo, simply unpack the .zip (Windows) or tar.gz (Unix) file
 containing Geronimo.

 Note for Windows platforms:
 The maximum path length for a directory path is 255 characters. Installing
 Geronimo into a long directory path may cause the installation or server
 startup to fail. 
 It is recommended that you use a short directory name, such as "c:\g\".


______________________
Starting Geronimo 
======================

 There are three general techniques for starting Geronimo (assuming the current
 directory is <geronimo_home>):

 1. GShell -- "./bin/gsh geronimo/start-server"
 2. Script -- "./bin/geronimo.sh run"
 3. Java   -- "java -Djava.endorsed.dirs=$JRE_HOME/lib/endorsed:lib/endorsed -Djava.ext.dirs=$JRE_HOME/lib/ext:lib/ext -javaagent:bin/jpa.jar -jar bin/server.jar"

Additional information on command environments can be found below.


______________________
Application Deployment
======================

 Applications can be deployed to a Geronimo server in several ways:

 1. Administrative command scripts -
      ./bin/gsh deploy/deploy MyApp.war MyDeploymentPlan.xml"
 2. Administrative console -
      Login to the admin console and click "Deploy New" under Applications
 3. Hot deploy -
      Copy your archive(s) into the "<geronimo-home>/deploy" directory.
      The hot deploy service will automatically deploy these artifacts.
 4. Maven -
      Applications can be installed as part of a maven build

 When you deploy an application using an administrative command, you will need
 to supply an administrator's username/password. If you do not specify the
 username and password, you will be prompted for them.


______________________
Configuration
======================

 Commonly modified configuration parameters, such as port numbers, can be set
 by editing the file:
     <geronimo_home>/var/config/config-substitutions.properties
 
 Additional configuration attributes can be updated in the file:
     <geronimo_home>/var/config/config.xml

 Note: The server must not be running when these files are modified.

 Once the server has started, you can access the Geronimo Administration Console
 at http://localhost:8080/console/ . The default user name is "system" and the
 default password is "manager".

 
______________________
Security Configuration
======================

 The default administration user/password for the Geronimo Administration
 Console and command line deployment tool is system/manager.  You can change
 these defaults directly from the Geronimo Administration Console by accessing
 Security -> Users and Groups and change the user name and password from the
 Console Realm Users portlet.

 As an alternative, the same changes can be made by editing the following files:
     <geronimo_home>/var/security/users.properties
     <geronimo_home>/var/security/groups.properties

 Access to the var/security directory should be appropriately secured on
 systems where you install Geronimo.

 Passwords in users.properties are encrypted by the server. Passwords can be
 changed using the Geronimo Administration Console. They can also be changed
 using a text editor. While the server is stopped, simply edit the
 users.properties file. The password(s) will be encrypted the next time the
 server is started. 

 To prevent potential security exposures, we strongly recommend you update the 
 default user names and passwords on your system.


______________________
GShell
======================

 Geronimo provides a command shell environment for executing commands,
 called GShell. 

 To start a GShell environment, from the <geronimo_home> directory, execute 
 "./bin/gsh" (Unix) or "bin\gsh" (Windows). This will start a GShell command
 environment. From here, you can execute Geronimo administrative commands as
 well as general GShell commands.  Alternatively, you can invoke a GShell
 command at the same time that you invoke gsh, for example:
  
   ./bin/gsh geronimo/stop-server

 A list of common gsh commands are:

   help
   geronimo/start-server
   geronimo/stop-server
   deploy/deploy 
   deploy/undeploy 
   deploy/list-modules
   deploy/install-plugin
   deploy/assemble

 Usage information for any command can be obtained by using the --help option.
 For example:

   geronimo/start-server --help 

 For more information on GShell and GShell commands, see the
 Geronimo 2.2.1 documentation.

______________________
Script
======================

 Geronimo provides a number of .sh or .bat scripts that can be used to
 administer Geronimo servers. To use most of these scripts, you must first set
 either the JAVA_HOME or JRE_HOME environment variable:

   export JAVA_HOME=<path-to-JDK>
  or
   export JRE_HOME=<path-to-JRE>

 Unix scripts provided by Geronimo (there are .bat equivalents):

   geronimo.sh -- used to start and stop servers in foreground or background
   startup.sh -- start a Geronimo server running as a background process
   shutdown.sh -- stop a running Geronimo server
   client.sh -- start a Geronimo application client
   deploy.sh -- deploy, list, and undeploy plugins and applications
   jaxws-tools.sh -- generate WSDL from Java code or Java code from WSDL

 For example, "./bin/deploy.sh list-modules"

 The geronimo.sh and shutdown.sh scripts have multiple sub-commands. Executing
 the scripts without any arguments will generate usage information. Executing
 "help <sub-command>" will generate usage information for that particular
 command.


______________________
Support
======================
 
 Any problems with this release can be reported to the Geronimo user mailing
 list or Jira issue tracker.

 Mailing list archive:
     http://mail-archives.apache.org/mod_mbox/geronimo-user/

 User mailing list:
     user@geronimo.apache.org

 User mailing list subscription:
     user-subscribe@geronimo.apache.org

 Jira:
     https://issues.apache.org/jira/browse/GERONIMO

 Information concerning security issues and reporting security concerns: 
     http://geronimo.apache.org/security-reports.html

 _______________________________________
 Notice Regarding Cryptographic Software
 =======================================
 This distribution includes cryptographic software.  The country in 
 which you currently reside may have restrictions on the import, 
 possession, use, and/or re-export to another country, of 
 encryption software.  BEFORE using any encryption software, please 
 check your country's laws, regulations and policies concerning the
 import, possession, or use, and re-export of encryption software, to 
 see if this is permitted.  See <http://www.wassenaar.org/> for more
 information.

 The U.S. Government Department of Commerce, Bureau of Industry and
 Security (BIS), has classified this software as Export Commodity 
 Control Number (ECCN) 5D002.C.1, which includes information security
 software using or performing cryptographic functions with asymmetric
 algorithms.  The form and manner of this Apache Software Foundation
 distribution makes it eligible for export under the License Exception
 ENC Technology Software Unrestricted (TSU) exception (see the BIS 
 Export Administration Regulations, Section 740.13) for both object 
 code and source code.

 The following provides more details on the included cryptographic
 software:
   
   Software related to cryptographic functionality is located in 
   an artifcact referred to as geronimo-util.  The source code for
   this functionality can be reviewed at:
   
   http://svn.apache.org/repos/asf/geronimo/server/
   
   The URL above is a reference to the Apache Geronimo Server source
   tree for all development (and released) source trees.