6.6. control Script

Synopsis

control <action>

Options

<action>: the action the cartridge performs.

Description

The control script enables OpenShift Enterprise or the application developer to control the state of a cartridge and its packaged software.

Table 6.3. Control Script Actions

Action Result
update-configuration, pre-build, build, deploy, post-deploy See Chapter 9, OpenShift Build Process.
start Starts the software the cartridge controls.
stop Stops the software the cartridge controls.
status Returns a zero (0) exit status if the cartridge code is running.
reload Instructs the cartridge and its packaged software to reload their configuration information. This action only operates if the cartridge is running.
restart Stops the current process and starts a new one for the packaged software.
threaddump Signals the packaged software to perform a thread dump, if applicable.
tidy Releases unused resources.
pre-snapshot Prepares the cartridge for a snapshot.
post-snapshot Tidies the cartridge after a snapshot.
pre-restore Prepares the cartridge for restoration.
post-restore Tidies the cartridge after restoration.
Lock context: locked.
Using the tidy Action

By default, the tidy action performs the following operations:

  • Garbage collects the Git repository.
  • Removes all files in the /tmp directory.

Add additional operations to the tidy action by editing the tidy() function in the $cartridge_name/bin/control file. Because applications have limited resources, it is recommended that you tidy thoroughly.

Example 6.3. Additional tidy Operations

  • rm $OPENSHIFT_{Cartridge-Short_Name}_DIR/logs/log.[0-9]
  • cd $OPENSHIFT_REPO_DIR ; mvn clean
Using the status Action

When an application developer queries the status of your packaged software, use a zero (0) exit status to indicate correct operation. Direct information to the application developer using stdout. Return errors with a non-zero exit status using stderr.

OpenShift Enterprise maintains the expected state of an application in the ~/app-root/runtime/.state file. Do not use this file to determine the status of the packaged software as it contains the expected state of the application, not the current state.

Table 6.4. Values for .state

Value Status
building Application is building.
deploying Application is deploying.
idle Application is shutdown due to inactivity.
new A gear exists, but no application is installed.
started Application started.
stopped Application is stopped.