| :virgo-name: Virgo |
| :version: 3.7.0.RC01 |
| |
| :umbrella-virgo-name: Eclipse Virgo |
| :tomcat-product-name: Virgo for Apache Tomcat |
| :tomcat-product-name-short: VTS |
| :jetty-product-name: Virgo Jetty Server |
| :jetty-product-name-short: VJS |
| :kernel-product-name: Virgo Kernel |
| :kernel-product-name-short: VK |
| :nano-product-name: Virgo Nano |
| :nano-product-name-short: VN |
| :user-guide: link:../../virgo-user-guide/html/index.html[User Guide] |
| :tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide] |
| |
| :gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide] |
| |
| :spring-framework-version: 4.2.9.RELEASE |
| |
| :homepage: https://www.eclipse.org/virgo |
| :ebr: http://www.eclipse.org/ebr[EBR] |
| |
| :imagesdir: assets/images |
| |
| anchor:starting-stopping"[Starting and Stopping {tomcat-product-name}] |
| |
| == Starting and Stopping {tomcat-product-name} |
| |
| Starting and Stopping {tomcat-product-name-short} |
| |
| === Starting {tomcat-product-name} |
| |
| To start {tomcat-product-name} run the `startup.sh` (Linux) or `startup.bat` (Windows) script. |
| For both platforms, the script is located in the `SERVER_HOME/bin` directory. |
| |
| [NOTE] |
| -- |
| This chapter applies to {nano-product-name} too. Note that since {nano-product-name-short} |
| has a single region you can ignore the console output from the user region and focus on the instructions. |
| A successful startup of {nano-product-name-short} is as simple as that: |
| .... |
| [2011-12-28 11:41:31.528] startup-tracker <KE0001I> Kernel starting. |
| [2011-12-28 11:41:31.602] startup-tracker <KE0002I> Kernel started. |
| .... |
| -- |
| |
| ==== Linux |
| |
| To start {tomcat-product-name}, open a terminal window and run `startup.sh`: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/startup.sh</screen> |
| .... |
| |
| Once {tomcat-product-name} has started, the console will display a log message |
| similar to the one shown below, along with other status messages: |
| |
| .... |
| [2009-11-30 12:12:12.111] Thread-2 <UR0001I> User region ready. |
| .... |
| |
| The preceding message indicates that you can start using {tomcat-product-name-short}. |
| |
| ==== Microsoft Windows |
| |
| To start {tomcat-product-name}, open a command-window and run `startup.bat`: |
| |
| .... |
| c:> cd %SERVER_HOME% |
| c:> bin\startup.bat</screen> |
| .... |
| |
| Once {tomcat-product-name} has started, the console will display a log message |
| similar to the one shown below, along with other status messages: |
| |
| .... |
| [2009-11-30 12:12:12.111] Thread-2 <UR0001I> User region ready. |
| .... |
| |
| The preceding message indicates that you can start using {tomcat-product-name-short}. |
| |
| === Starting in Clean Mode |
| |
| When you start {tomcat-product-name} in clean mode, the startup script removes the `SERVER_HOME/work` directory (and hence all |
| running applications) as well as all trace, log and dump files. It leaves the |
| `SERVER_HOME/repository` and `SERVER_HOME/pickup` directories untouched, |
| which means that any applications previously hot deployed will be automatically reinstalled. |
| |
| ==== Linux |
| |
| To start {tomcat-product-name} in clean mode, open a terminal window and run `startup.sh -clean`: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/startup.sh -clean |
| .... |
| |
| ==== Microsoft Windows |
| |
| To start {tomcat-product-name} in clean mode, open a command window and run `startup.bat -clean`: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -clean |
| .... |
| |
| === Starting in Debug Mode |
| |
| ==== Linux |
| |
| To start {tomcat-product-name} in debug mode, run |
| `startup.sh` passing in the |
| `-debug` argument: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/startup.sh -debug |
| .... |
| |
| This will start the debug agent listening on port |
| `8000` which is the default remote debug port used |
| by Eclipse. To start in debug mode with a specific port number, pass |
| this in as the value for the `-debug` argument: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/startup.sh -debug 8001 |
| .... |
| |
| This will start the debug agent listening on port |
| `8001`. To start in debug mode and suspend the VM |
| until a debugger attaches, pass in the `-suspend` |
| argument along with the `-debug` argument: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/startup.sh -debug -suspend |
| .... |
| |
| This starts the debug agent, but prevents {tomcat-product-name} from actually |
| starting until a debugger attaches to the agent. This can be useful |
| when trying to diagnose problems that occur during startup. |
| |
| ==== Microsoft Windows |
| |
| To start {tomcat-product-name} in debug mode, run |
| `startup.bat` passing in the |
| `-debug` argument: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -debug |
| .... |
| |
| This will start the debug agent listening on port |
| `8000` which is the default remote debug port used |
| by Eclipse. To start in debug mode with a specific port number, pass |
| this in as the value for the `-debug` argument: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -debug 8001 |
| .... |
| |
| This will start the debug agent listening on port |
| `8001`. To start in debug mode and suspend the VM |
| until a debugger attaches, pass in the `-suspend` |
| argument along with the `-debug` argument: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -debug -suspend |
| .... |
| |
| This starts the debug agent, but prevents {tomcat-product-name} from actually |
| starting until a debugger attaches to the agent. This can be useful |
| when trying to diagnose problems that occur during startup. |
| |
| === Starting with JMX Access Modifications |
| |
| The {tomcat-product-name} always starts with JMX access enabled, allowing you to use a management tool such as JConsole |
| to attach to the Web Server instance. |
| By default both local access and remote access over SSL with username and password |
| authentication are provided. The default port for secure JMX access is `9875` |
| and the default username and password are `admin` and `springsource`. |
| |
| ==== Linux |
| |
| To start {tomcat-product-name} with default JMX access enabled, run `startup.sh` passing |
| in no arguments: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/startup.sh |
| .... |
| |
| To start JConsole, run the `jconsole.sh` script, located in the `bin` directory, as shown: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/jconsole.sh |
| .... |
| |
| The following image shows how to specify a local connection using JConsole. |
| |
| image:jmx-local-attach.png[] |
| |
| The following image shows how to specify a remote connection in JConsole that uses SSL with the default |
| username/password (`admin/springsource` and default secure port of `9875`). |
| |
| image:jmx-remote-attach-default.png[] |
| |
| To start with the JMX remote access on a specific port number other than the default `9875`, |
| pass this port number in as the value |
| of the `-jmxport` argument: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/startup.sh -jmxport 9090 |
| .... |
| |
| This will start the {tomcat-product-name} with JMX enabled for remote connections on port `9090`. |
| |
| image:jmx-remote-attach-jmxport.png[] |
| |
| To start the JMX remote access with a custom username and password, update the `$SERVER_HOME/configuration/org.eclipse.virgo.kernel.users.properties` file. First specify the custom username by changing the value of the `role.admin` property. Then set the password of this new user by adding a new property called `user.*username*`, where `*username*` refers to the actual name of the user. Finally, restart {tomcat-product-name-short} for the changes to take effect. |
| For example, if you want change the JMX remote access username to `zebedee` with password `florence`, change the file as follows: |
| |
| [source,txt] |
| ---- |
| ################## |
| # User definitions |
| ################## |
| user.zebedee=florence |
| |
| |
| ################## |
| # Role definitions |
| ################## |
| role.admin=zebedee |
| ---- |
| |
| Specify the custom username in JConsole as shown. |
| |
| image:jmx-remote-attach-jmxusers.png[] |
| |
| To start the JMX remote access using a custom SSL certificate, edit the file located at |
| `$SERVER_HOME/configuration/keystore`. If you wish to use a different keystore, |
| pass this filename in as the value for the `-keystore` argument and the keystore |
| password in as the value for the `-keystorePassword` argument: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/startup.sh -keystore customKeystore -keystorePassword customKeystorePassword |
| .... |
| |
| This will start the {tomcat-product-name} with JMX enabled for remote connections using an SSL certificate from |
| `customKeystore` with a password of `customKeystorePassword`. |
| |
| ==== Microsoft Windows |
| |
| To start {tomcat-product-name} with default JMX access enabled, run `startup.bat` passing |
| in no arguments: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\startup.bat |
| .... |
| |
| To start JConsole, run the `jconsole.bat` script, located in the `bin` directory, as shown: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\jconsole.bat |
| .... |
| |
| The following image shows how to specify a local connection using JConsole. |
| |
| image:jmx-local-attach.png[] |
| |
| The following image shows how to specify a remote connection in JConsole that uses SSL with the default |
| username/password (`admin/springsource` and default secure port of `9875`). |
| |
| image:jmx-remote-attach-default.png[] |
| |
| To start with the JMX remote access on a specific port number other than the default `9875`, |
| pass this port number in as the value of the `-jmxport` argument: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -jmxport 9090 |
| .... |
| |
| This will start the {tomcat-product-name} with JMX enabled for remote connections on port |
| `9090`. |
| |
| image:jmx-remote-attach-jmxport.png[] |
| |
| To start the JMX remote access with a custom username and password, update the `%SERVER_HOME%\configuration\org.eclipse.virgo.kernel.users.properties` file. First specify the custom username by changing the value of the `role.admin` property. Then set the password of this new user by adding a new property called `user.*username*`, where `*username*` refers to the actual name of the user. Finally, restart {tomcat-product-name-short} for the changes to take effect. |
| For example, if you want change the JMX remote access username to `zebedee` with password `florence`, change the file as follows: |
| |
| [source,txt] |
| ---- |
| ################## |
| # User definitions |
| ################## |
| user.zebedee=florence |
| |
| |
| ################## |
| # Role definitions |
| ################## |
| role.admin=zebedee |
| ---- |
| |
| Specify the custom username in JConsole as shown. |
| |
| image:jmx-remote-attach-jmxusers.png[] |
| |
| To start the JMX remote access using a custom SSL certificate, edit the file located at |
| `%SERVER_HOME%\configuration\keystore`. If you wish to use a different |
| keystore, pass this filename in as the value for the `-keystore` argument and the |
| keystore password in as the value for the `-keystorePassword` argument: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -keystore customKeystore -keystorePassword customKeystorePassword |
| .... |
| |
| This will start the {tomcat-product-name} with JMX enabled for remote attach using an SSL certificate from |
| `customKeystore` with a password of `customKeystorePassword`. |
| |
| anchor:starting-stopping-configuration-directory[] |
| |
| === Starting with a Custom Configuration Directory |
| |
| Use the `-configDir` option to specify an alternate `configuration` directory, different from the |
| default `SERVER_HOME/configuration` directory. This option allows you to use the same {tomcat-product-name} |
| installation to run multiple instances of {tomcat-product-name-short}. Simply create a configuration directory for each |
| instance, specify unique port numbers, logging and tracing directories, and so on, and then specify that directory |
| when starting {tomcat-product-name-short}. |
| |
| If you specify a relative path for the `-configDir` parameter, |
| the startup script interprets the path as relative to the root of the {tomcat-product-name} installation, |
| and not relative to the directory from which you execute the `startup` script. |
| |
| See xref:alternate-serviceability-work[Alternate `serviceability` and `work` |
| Directories] for a known issue related to specifying an alternate `configuration` directory. |
| |
| ==== Linux |
| |
| To start {tomcat-product-name} using a configuration directory of `/configuration/node1`: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/startup.sh -configDir /configuration/node1 |
| .... |
| |
| ==== Windows |
| |
| To start {tomcat-product-name} using a configuration directory of `c:\configuration\node1`: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -configDir c:\configuration\node1 |
| .... |
| |
| === Stopping {tomcat-product-name} |
| |
| ==== Linux |
| |
| To stop a running instance of {tomcat-product-name}, start a new terminal window and run the `shutdown.sh` script: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/shutdown.sh |
| .... |
| |
| To stop a running instance of {tomcat-product-name} immediately, bypassing normal shutdown |
| processing, run `shutdown.sh` with the `-immediate` option: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/shutdown.sh -immediate |
| .... |
| |
| If, when you started the Web Server instance, you used the `-jmxport` option to specify a non-default JMX port number, |
| then you must pass this port number to the `-jmxport` of the `shutdown.sh` script |
| to gracefully shut it down. |
| For example, if you specified `9090` as the JMX port, use the following to shut down the Web Server instance: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/shutdown.sh -jmxport 9090 |
| .... |
| |
| ==== Microsoft Windows |
| |
| To stop a running instance of {tomcat-product-name}, start a new console window and run the `shutdown.bat` script: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\shutdown.bat |
| .... |
| |
| To stop a running instance of {tomcat-product-name} immediately, bypassing normal shutdown |
| processing, run `shutdown.bat` with the `-immediate` option: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\shutdown.bat -immediate |
| .... |
| |
| If, when you started the Web Server instance, you used the `-jmxport` option to specify a non-default JMX port number, |
| then you must pass this port number to the `-jmxport` of the `shutdown.bat` script to gracefully shut it down. |
| For example, if you specified `9090` as the JMX port, use the following to shut down the Web Server instance: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\shutdown.bat -jmxport 9090 |
| .... |
| |
| anchor:cleaning-without-starting[] |
| |
| === Cleaning {tomcat-product-name} without Starting it |
| |
| When you clean {tomcat-product-name}, the startup script removes the `SERVER_HOME/work` directory (and hence all |
| running applications) as well as all trace, log and dump files. It leaves the |
| `SERVER_HOME/repository` and `SERVER_HOME/pickup` directories untouched, |
| which means that any applications previously hot deployed will be automatically reinstalled next time the Web Server is started. |
| |
| Cleaning is useful when you want to start the Web Server from a clean state next time, but you don't want to start the Web Server yet. |
| |
| Cleaning is also useful for tidying up the directory structure. For example, sometimes Microsoft Windows won't let you delete the Web |
| Server installation directory. |
| See xref:windows-deletion[Problem Deleting Installation Directory under Windows] for more details. |
| |
| ==== Linux |
| |
| To clean {tomcat-product-name}, open a terminal window and run `startup.sh -clean -noStart`: |
| |
| .... |
| $ cd $SERVER_HOME |
| $ bin/startup.sh -clean -noStart |
| .... |
| |
| ==== Microsoft Windows |
| |
| To clean {tomcat-product-name}, open a command window and run `startup.bat -clean -noStart`: |
| |
| .... |
| C:> cd %SERVER_HOME% |
| C:> bin\startup.bat -clean -noStart |
| .... |
| |
| anchor:equinox-launcher[] |
| |
| === Using Equinox Launcher |
| |
| Since version 3.5 {virgo-name} uses the standard Equinox Launcher as its default launcher. |
| As a result in addition to all the launcher options described so far users can also pass arguments specific to the Equinox launcher. |
| |
| [IMPORTANT] |
| -- |
| The Equinox Launcher arguments must be placed at the end of the startup call. Here's an example |
| .... |
| $ ./startup.sh "virgo-args" "equinox-launcher-args" |
| $ ./startup.sh -clean -console 2222</screen> |
| .... |
| -- |
| |
| A full list of the accepted Equinox Launcher arguments is available at http://help.eclipse.org/[help.eclipse.org]. |
| |
