[[running_crash]]
= Running CRaSH

There are several ways to run CRaSH, as a standalone application it controls its own JVM or as an embedded
service in an existing runtime like a web application or a Spring application.

== Standalone

=== Standalone mode

The standalone mode allows you to run CRaSH from the command line directly. It provides the same functionality as the
war deployment but does not require a web container as it runs its own virtual machine. The _crash_ directory
in the application contains the standalone distribution.

The bin directory _/crash/bin_ can be added to the system path, it contains the _crash.sh_ script that will start
the standalone mode, for instance you can set it up this way:

[subs="attributes,specialcharacters", options="nowrap"]
----
> export PATH=/.../crash/bin:$PATH
> crash.sh
   ______
 .~      ~. |`````````,       .'.                   ..'''' |         |
|           |'''|'''''      .''```.              .''       |_________|
|           |    `.       .'       `.         ..'          |         |
 `.______.' |      `.   .'           `. ....''             |         | {crash-version}

Follow and support the project on http://www.crashub.org
Welcome to jerry + !
It is {localdatetime} now
----

Let's review quickly what you can find in standalone crash:

* The _bin_ directory contains the _crash.sh_ script and the standalone crash jar file
* The _conf_ directory contains the configuration properties _crash.properties_ and JVM logging configuration _logging.properties_
* The _cmd_ directory contains the commands that will be available in crash by default it contains a few example commands
* The _lib_ directory contains the various libraries used by crash, you should place additional jar files there

=== Attach mode

The attach mode allows you to attach CRaSH to a JVM located on the same host with the attach API provided by the Hotspot
JVM. It is the standalone mode attached to a running JVM specified by a process id. CRaSH will hook into the targetted JVM
instead of the JVM started by CRaSH. Let's see quickly an example of how to use it:

[subs="attributes,specialcharacters", options="nowrap"]
----
> jps
3165 RemoteMavenServer
20650 Test
20651 Jps

> crash.sh 20650
   ______
 .~      ~. |`````````,       .'.                   ..'''' |         |
|           |'''|'''''      .''```.              .''       |_________|
|           |    `.       .'       `.         ..'          |         |
 `.______.' |      `.   .'           `. ....''             |         | {crash-version}

Follow and support the project on http://vietj.github.com/crash
Welcome to jerry + !
It is {localdatetime} now
%
----

In this example we attached crash to the Test JVM. We obtained the Test JVM PID thanks to the _jps_ command that belongs
to the Java Platform. During this mode the commands are executed in the target JVM.

=== Configuration

The standalone mode relies on the +org.crsh.standalone.CRaSH+ class main method to configure and run the shell. The
startup scripts _crash.sh_ and _crash.bar_ configures this class. You can tweak those scripts to your environment,
let's review the options and arguments of +CRaSH+:

==== _--cmd_ option

The _--cmd_ option specifies a directory containing command source files. Such directory contains commands as _.groovy_ files,
commands can be in directories for grouping purpose. Several folders can be specified by repeating the option.

==== _--cmd-mode_ option

The standalone shell search commands in folders (specified with the _--cmd_ option and in the classpath (under the
_/crash/commands/_ folder). The _--cmd-mode_ option defines how to handle the classpath commands:

* The _read_ option value uses commands from directories and classpath.
* The _copy_ option value scans the classpath during the startup and copies the commands in the first command folder, then commands
 are used from the folders. This value requires at least one command directory to be specified for extracting the commands.

==== _--conf_ option

The _--conf_ option specifies a directory containing configuration files. Several folders can be specified by repeating the option.

==== _--conf-mode_ option

The standalone shell search configuration files in folders (specified with the _--conf_ option and in the classpath (under the
_/crash/_ folder). The _--conf-mode_ option defines how to handle the classpath configuration:

* The _read_ option value uses configuration files from directories and classpath.
* The _copy_ option value scans the classpath during the startup and copies the files in the first configuration folder, then configuration
 are used from the folders. This value requires at least one conf directory to be specified for extracting the configuration files.

==== _--property_ option

The _--cmd_ option sets and overrides a shell configuration property, the value follows the pattern _a=b_, for instance:

----
crash.sh --property crash.telnet.port=3000
----

==== _--non-interactive_ option

The _--non-interactive_ option disable the usage of the JVM input and output.

----
crash.sh --non-interactive
----

==== _pid_ arguments

The +org.crsh.standalone.CRaSH+ main has an optional list of arguments that are JVM _process id_. When one or several JVM process id
  are specified, CRaSH will dynamically attach to this virtual machine and will be executed in that machine. By default the two JVM will
  communicate with a socket unless the _non-interactive_ option is set.

WARNING: When more than one process id is specified, the _non-interactive_ option must be set because CRaSH will not be able
to aggregate two command lines in the same terminal.

=== Resource extraction

When the options _--cmd-mode_ or _--conf-mode_ are set to the _copy_, CRaSH will scan the classpath and extract the
 resources in the corresponding directory.

The default value of these options is _copy_ however no copy happens unless at least one directory for extracting the resources
is specified, therefore

* The +org.crsh.standalone.CRaSH+ does nothing by default
* The _crash.sh_ or _crash.bat_ extracts the resources in the corresponding directory as the _cmd_ and _conf_ directories
are specified

To prevent any resource copying the value _read_ should be used.

== Embedded mode

=== Embedding in a web app

CRaSH can use a standard web archive to be deployed in a web container. The war file is used for its packaging capabilities
and triggering the CRaSH life cycle start/stop. In this mode CRaSH has two packaging available:

* A __core__ war file found under _deploy/core/crash.war_ provides the base CRaSH functionnalities

You have to copy the _crash.war_ in the appropriate server, regardless of the packaging used.

If you want you can embed CRaSH in your own _web.xml_ configuration:

.Embedding CRaSH in a web application
[source,xml]
----
<web-app>
  <listener>
    <listener-class>org.crsh.plugin.WebPluginLifeCycle</listener-class>
  </listener>
</web-app>
----

=== Embedding in Spring

CRaSH can be easily embedded and configured in a Spring configuration.

==== Embedding as a Spring bean

Here is an example of embedding crash:

.Embedding CRaSH in Spring
[source,xml]
----
<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans
       http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

	<bean class="org.crsh.spring.SpringBootstrap">
    <property name="config">
      <props>
        <!-- VFS configuration -->
        <prop key="crash.vfs.refresh_period">1</prop>

        <!-- SSH configuration -->
        <prop key="crash.ssh.port">2000</prop>

        <!-- Optional SSH timeouts -->
        <prop key="crash.ssh.auth_timeout">300000</prop>
        <prop key="crash.ssh.idle_timeout">300000</prop>

        <!-- Telnet configuration -->
        <prop key="crash.telnet.port">5000</prop>

        <!-- Authentication configuration -->
        <prop key="crash.auth">simple</prop>
        <prop key="crash.auth.simple.username">admin</prop>
        <prop key="crash.auth.simple.password">admin</prop>
      </props>
    </property>
  </bean>

</beans>
----

The configuration properties are set as properties with the _config_ property of the +SpringBootstrap+ bean.

Any Spring managed beans that extend +org.crsh.plugin.CRaSHPlugin+ will be automatically
registered as plugins in addition to those declared in +META-INF/services/org.crsh.plugin.CRaSHPlugin+.

==== Embedding in a Spring web app

In case you are embedding CRaSH in a Spring application running with a servlet container, the bean
 +org.crsh.spring.SpringWebBootstrap+ can be used instead of +org.crsh.spring.SpringBootstrap+. The +SpringWebBootstrap+
 extends the +SpringBootstrap+ class and adds the _WEB-INF/crash_ directory to the command path.

An example packaging comes with the CRaSH distribution, a _spring_ war file found under _deploy/spring/crash.war_ provides
the base CRaSH functionnalities bootstrapped by the Spring Framework. It can be used as an example for embedding CRaSH
 in Spring.

This example is bundled with a _spring_ command that shows how the Spring factory or beans can be accessed within
a CRaSH command.
