Content is available under Creative Commons Attribution.


Administration Guide



The controller is configured by controller.xml by default. If you run the controller and this file doesn’t exist, you’ll be prompted for a few questions to create the file

This will create a controller.xml such as:


Command Line Options

The controller understands certain command line options.  These options may be viewed at any time by passing –help as a parameter to controller.exe.

General Options:

AddAgent Options:

SSH Options:


Environments are defined in environments.xml in the same folder as controller executable. In Leroy an environment is a logical collection of agents grouped together with common roles to all other environments.






<workflow> is the top level tag required for a workflow. Workflows are stored in the workflows/ folder and may be named anything.xml.

A leroy deployment workflow must be surrounded by a <workflow></workflow> tag.

Unless a step in a workflow indicates serial=yes all steps will be run simultaneously across multiple hosts in a threaded manner automatically. It is up to the creator of the workflow to ensure that there are not conditions that occur where Leroy is contending for the same resource. Leroy is intended to be a simplistic yet powerful programming language expressed in xml that allows developers, build and release engineers and system administrators to describe a singular deployment workflow to work in multiple environments.


<workflow> supports the following attributes.


By setting these items here in the workflow level, you are creating defaults for all steps.


Supports: Properties


Built in properties:
${Leroy.Workflow} – the called workflow
${Leroy.Environment} – the called environment
${id} – the id of the current agent


Common Step Attributes

Certain options are common to all the possible steps in a workflow.


Run myscript.bat only on jboss_app01 in the role “jboss”. If there is an error, no further steps will be run except those marked with runOnError=yes or runOnlyOnError=yes. And this step won’t be run if some previous step failed. If we see the string “[Error]” in the output, then abort the workflow with error. Since serial=yes then wait for all previous jobs to complete and join threads on this step. If there are more than 10 agents in this role, only run 10 at a time.

Run myscript.bat script only on 1 (any) agent from jboss role.


Execute runs a command on a remote host. In order to execute a command, you have to put the script in the /commands folder relative to the controller root. Execute commands are transferred to the target host and executed. The success or failure of a given command is determined by the exit code returned to the shell. If leroy sees zero that is considered success. If we see non-zero that is considered failure. In some cases when we run scripts and programs we’ll see that they will return zero even though there is a legitimate failure. In these cases, one can define a post process script where we can define one or many strings to catch that determine error. These strings may be expressed with regular expressions.

If a command times out (see the timeout common step attribute), then its process gets killed by Leroy.

Attention powershell users: Commands must have the extension .ps1 to properly execute as powershell scripts.





This example will run the command test.bat on all roles in this environment called: jboss. The script test.bat must exist in the ${controllerRoot}/commands folder, otherwise the deployment will fail.  Using serial=”yes” means that the step will only run on one agent at a time.


This example will run test.bat but only in an environment called “test”


This example will run test.bat but only on an agent called “web01”


This example will run test.bat but only on an agent called “web01” in the test environment.


This example doesn’t require a script in the ${controllerRoot}/commands folder, rather the script itself is embedded in the xml.  It will use the working directory c:\temp


This example runs a script called echo-test.bat and sets an environment variable called STRING as: “Testing String 123”


This example runs a script called echo-test.bat and passes 3 command line arguments as ARG1 ARG2 ARG3 respectively.


This example will run run a script where failure is determined if we see the string: [ERROR]



Transfer can do several things:



‘exclude’ specifications have precedence over ‘include’ specifications, so if a file is matched by any of the excludes, it is definitely not extracted from the archive, regardless of any includes. If any ‘include’ patterns are specified, only the files matching any of those patterns will be extracted, otherwise all files will be extracted from the archive – in both cases provided that a file isn’t excluded, of course. The patterns must be valid Perl Regular Expressions.


This example will transfer a file called application.war to the /home/jboss/instance/deploy folder to all hosts in the environment of the role: jboss

This example transfers to /home/jboss/instance/deploy then unzips it using explode=yes

This example requests that each agent fetches a file from a url and copies to the /home/jboss/instance/deploy folder.

This example has the controller fetch a file and place it into its artifacts folder as, then distributes the file to all hosts in the jboss role.  See more details about the fetch command in it’s own section below.


Causes an agent to sleep for the specified number of seconds.



Sleep has no elements.


This example causes all agents in the role jboss to sleep for 14 seconds each.


Causes the controller to wait for all agents to complete the previous step’s execution before dispatching any of the following steps to the agents.



Echo simply prints something to controller’s standard output.  Please note that an “echo” statement defaults to serial=”yes” behavior.  If this is undesirable, explicitly state serial=”no”.




Fetch will cause the controller to fetch a file from a URL and store it in the controller’s artifacts folder. This is different then specifying a url in a transfer task since that causes the agent to do the url fetch. Typical use of this would be to fetch a collection of artifacts from your favorite build server and populate your controllers artifacts folder, then perform transfers to your roles.



Fetch has no elements.



Import is a pseudo-step that you can use to import other workflow files into the current workflow. The imported workflow’s steps will effectively be inserted in the current workflow at the place of the <import> or <import_once>. This is a good way to implement workflow “functions” or methods, as you may import a file as many times as you want in as many places as you wish.

There are 2 ways of importing workflow files: <import> and <import_once>. They are pretty much the same, the only difference is that  <import_once> checks whether the file is already imported or not and imports it if and only if it is not imported before.




Post-process configurations allows one to call upon a post-process configuration in an execute step to test for error conditions. Post-process scripts are stored in postprocess.xml. Regular expression and properties are supported inside post-process definitions. Post-process definitions are called by: Common Step Attributes.

Example: ${controllerRoot}/postprocess.xml


Creating Agents

Agents are created from the controller and stored in agents.xml. All agents in all environments require a unique name. A nice nomenclature that we recommend is:


An example of this would be: uslaxweb01_facebook_dev_apache

To add an agent, you simply run:

This will prompt you for the following:

This process will add an entry to agents.xml and ensure the name is unique, create a folder called ${controllerRoot}/installed_agents, in it will be a list of folders of each agent that has been generated by the controller. The controller will also have a copy of each agent as a zip file in ${controllerRoot}. Copy the zip file to your machine that you want the agent to run on, unzip, and simply run agent.exe. There is also an install_service.bat file that is included with windows agents that allows you to install the agent as a service. The reason why we create agents from the controller is because we use key-pairs to configure mutual authentication between the controller and the agent and setup these keys in each agent.

When adding agent you can specify an –environment option. That means you want to add agent into the given environment in addition to adding it into the system in general. In that case you will be asked to input the ‘Agent Logical Name’ (which is alternatively called Agent ID). It should be unique in the given environment. This allows identifying agents in the environment in a very useful and comfortable way.

All the parameters which are asked by controller when adding agent can be specified in command line. Have a look at the “AddAgent Options” for more details. If you specify all necessary parameters in the command line then controller will not ask any questions and will create agent in silence.  Otherwise the controller will ask user to input missing parameters manually.

If you would like to add an agent into the system and install it at the same time, you can set –ssh-install option with –addagent. For more details have a look at the description of –ssh-install command line parameter and “SSH Options”.

Exporting Agents

If you have already created an agent, and need the controller to create another copy of it with the proper SSL keys, you can run the command:

If you would like to export an agent and install it at the same time, you can set –ssh-install option with –extractagent. For more details have a look at the description of –ssh-install command line parameter and “SSH Options”.

Also you can export all agents available in the system just by one command.

Installing Agents

Controller even can install agents for you through an ssh session. You can run the following command:

Controller will prompt you to enter ssh parameters (host, port, user, etc.) to initiate ssh connection. When the connection is established it will copy the agent bundle into the specified destination directory. Agent bundle is a zip file created by controller when adding or extracting an agent.

If you don’t want controller to ask questions about ssh parameters you can specify them in the command line. If at least one ssh option is specified in the command line then controller will not ask any questions. Of course in that case if you haven’t specified any mandatory parameter (e.g. host) in the command line then controller will fail providing an explanation. For more details have a look at the description of –ssh-install command line parameter and “SSH Options”.

Special properties

An agent has special properties, that are set automatically:

These special properties can be used like any other property, including in preconditions.

Agent Command Line

The agent understands several command line parameters:


The ${controllerRoot}/agents.xml file is an inventory of all the agents in the system. Each agent name is unique and no two can be the same in the entire system. Agents.xml also holds agent properties for each agent. Agent properties are used for host specific values, such as a url to a specific host, the location of an executable, or perhaps a unique port or id. The agents.xml file is managed by the controller, when you use the controller to –addagent the controller checks to see if an entry already exists in agents.xml. If not, then the entry is added to it.



Configuration Management

Build configurations

Leroy can be used to generate configurations for your system and application. Learn more.


Python deployment automation helper functions built into leroy

Leave a Reply

by: Epic Force