h1. Introduction

{section}
{column}

Once Petals ESB is installed through the Debian package, it can be started or stopped with two different ways:
* at system level: the Petals ESB containers are running with a dedicated system user '{{petals}}'. To use in production mode,
* at user level: the Petals ESB containers are running as a process of the user that launches them. To use in a development mode.

Startup and shutdown operations are realized through the script or command '{{petals-esb}}'. In following chapters we can find use-cases to explain how to use the script, and a reference guide about this script.

{column}
{column:width=35%}
{panel:title=Table of contents}{toc:outline=true}{panel}
{panel:title=Contributors}{contributors:order=name|mode=list|showAnonymous=true|showCount=true|showLastTime=true}{panel}
{column}
{section}

h1. Starting Petals ESB

h2. Starting Petals ESB at system level

h3. Automatic startup

The Petals ESB package comes with an automatic startup script based on System V ({{initd}}) to automatically launch Petals ESB containers as system services when the host boots.
To start the Petals containers, for example, launch the following command on a Ubuntu box:
{code}
cdeneux@sph-latitude-D630:~$ sudo service petals-esb start
{code}

Two natures of containers are identified:
* the "available containers" that are configured. These containers are to configure into the directory {{/etc/petals-esb/container-available}}. One sub-directory by container.
* and, the "enable containers" that are automatically started. These containers are to configure into the directory {{/etc/petals-esb/container-enable}}. One sub-directory by container.

As "Enable containers" are a subset of "Available containers", we recommend to put the configuration of a container into a sub-directory of {{/etc/petals-esb/container-available}}, and create a symbolic link on this sub-directory into {{/etc/petals-esb/container-enable}} to "enable" it.

{info}
It's not possible to automatically start a container in debug mode. Use a manual startup.
{info}

{note}
The automatic startup starts all Petals ESB containers declared in the directory {{/etc/petals-esb/container-enable}}. So if you add a new Petals ESB container in this directory, and use the command "{{service petals-esb start}}", all other Petals ESB containers will be also started, and as they are already started, errors will occurs.
{note}

h3. Manual startup

A Petals ESB container configured at system level (its configuration is located in {{/etc/petals-esb/container-available}}, and uses sub-directories of {{/var/lib/petals-esb}} and {{/var/log/petals-esb}}) can be started using a manual startup, for example, to test its configuration. This startup is done using the same mechanism as a Petals ESB container configured at user level, but using the system user '{{petals}}' to be compliant with ACL of the filesystem:
{code}
sudo -u petals petals-esb -u <container-configuration>
{code}
where {{<container-configuration>}} is the URL of the container configuration (ie, URL locating the file {{server.properties}})
{quote}For example, to launch the default sample container
{code}
sudo -u petals petals-esb -u file:///etc/petals-esb/container-available/default/server.properties
{code}
{quote}

{note}
+Note 1:+ When manually starting a Petals ESB container, it will be automatically stopped when closing your shell. Don't use this way to start a Petals ESB container as a system service.

h2. Starting Petals ESB at user level

A Petals ESB container configured at user level (its full configuration is located under the user's home directory) can be *only* started using a manual startup:
{code}
petals-esb -u <container-configuration>
{code}
where {{<container-configuration>}} is the URL of the container configuration (ie, URL locating the file {{server.properties}})
{quote}For example:
{code}
petals-esb -u file:///home/cdeneux/my-petals-esb-containers/demo1/server.properties
{code}
{quote}

{note}
When manually starting a Petals ESB container, it will be automatically stopped when closing your shell.
{note}

h1. Stopping Petals ESB

The process stopping a Petals ESB container reads the contents of its topology file to get the JMX credentials required to connect to the container and invoke a shutdown. The security to block a shutdown is based on filesystem ACLs of the configuration files of the container. So, don't forget to set the right ACL on these files.

{quote}
Example: "{{me:my-group rw-r-----}}" for your container to authorize you ({{me}}) and all member of the group {{my-group}}) to shutdown the container.
{quote}

h2. Stopping Petals ESB at system level

h3. Automatic stop

To stop the Petals containers started as system services uses the following command on a Ubuntu box, for example:
{code}
cdeneux@sph-latitude-D630:~$ sudo service petals-esb stop
{code}

{note}
The automatic stop stops all Petals ESB containers declared in the directory /etc/petals-esb/container-enable. So if you have removed a Petals ESB container in this directory since the last automatic startup, it will not be stopped. Use a manual stop to stop it.
{note}

h3. Manual stop

h4. Manual stop of a Petals ESB container automatically started

To stop a Petals ESB container started as system service use the following command:
{code}
sudo -u petals petals-esb -u <container-configuration> stop
{code}
where {{<container-configuration>}} is the URL of the container configuration (ie, URL locating the file {{server.properties}})
{quote}For example, to stop the default sample container
{code}
sudo -u petals petals-esb -u file:///etc/petals-esb/container-available/default/server.properties stop
{code}
{quote}

h4. Manual stop of a Petals ESB container manually started

If you have manually started a Petals ESB container at system level, just kill it with a Ctrl-C on its console, or use the following command from another shell:
{code}
sudo -u petals petals-esb -u <container-configuration> stop
{code}
where {{<container-configuration>}} is the URL of the container configuration (ie, URL locating the file {{server.properties}})
{quote}For example, to stop the default sample container
{code}
sudo -u petals petals-esb -u file:///etc/petals-esb/container-available/default/server.properties stop
{code}
{quote}

h2. Stopping Petals ESB at user level

To stop your Petals ESB container, just kill it with a Ctrl-C on its console, or use the following command from another shell:
{code}
petals-esb -u <container-configuration> stop
{code}
where {{<container-configuration>}} is the URL of the container configuration (ie, URL locating the file {{server.properties}})
{quote}For example
{code}
petals-esb -u file:///home/cdeneux/my-petals-esb-containers/demo1/server.properties stop
{code}
{quote}

h1. Reference guide of script '{{petals-esb}}'

{info}This reference guide is also available as "man" page installed with the Debian package '{{petals-esb}}'.{info}

h2. Synopsis

{code}
petals-esb -u container-cfg-url [stop] [-e]
petals-esb -h
petals-esb -V
{code}

h2. Description

*petals-esb* is used to start and stop manually a Petals ESB container.

h2. Options

|| Short option || Long option || Description ||
| {{-e}} | {{--error}} | Print the extended error message (stack-trace). |
| {{-h}} | {{--help}} | Print usage. |
| {{-u container-cfg-url}} | {{--url container-cfg-url}} | The URL of the Petals container configuration to start or stop. |
| {{-V}} |{{--version}} | Print the version number and exit. |
| {{stop}} | N/A | Stop the local Petals ESB container. |