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

  • IP Address on the local machine to bind to (default: all)
  • Port of local machine to bind to
  • IP Address / Hostname of controller that agents will reach out to.
  • Log level.
  • Log file.
  • Agent Check-in timeout, specifically, how long the controller will wait for agents to report in before giving up.

This will create a controller.xml such as:


  • element: controller
    • attribute: bind  – The IP address the controller binds to. Leave blank to bind to all.
    • attribute: host  – The hostname that agents will use to connect to the controller.
    • attribute: port  – The TCP port that the controller listens on.
    • attribute: logLevel  – The controller log level. This may be “none”, “debug”, “info”, “warning”, or “error”. Default is “warning”.
    • attribute: logFile  – The controller log file. Default is standard output.
    • attribute: agentsCheckinTimeout  – The maximum time (in seconds) that the controller should wait for all agents to connect.
    • attribute: redirectionPorts – Range(s) of ports from which agent redirection port numbers can be selected. See the Agent Redirection section for details.

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. The usual behavior by the controller is to deploy the given workflow to the given environment. The options described below with [action modifier] deviate from that and make the controller perform another type of action instead.

General Options:

  • --help  : Print the help message and exit.
  • -v [ --version ] : Print version info and exit.
  • --addagent  : [action modifier] Used to add an agent to the system.  The result will be a zip file which contains everything necessary to install an agent. Additionally ‘AddAgent Options’ can be specified (see below for more details).
  • --extractagent  : [action modifier] Used to re-generate the agent zip file.
  • --extractagent-all : [action modifier] used to re-generate .zip installation package for all agents.
  • --ssh-install  <agent bundle>: [action modifier] Used to install an already generated agent via ssh session. Additionally ‘SSH Options’ can be specified (see below for more details).
  • --workflow  <workflow file> : Used to pick a workflow to run.  By default, it will look in the “workflows” directory, and it will automatically append .xml
  • --environment  <environment name> : Used to pick an environment to run the workflow on.  The environments are by default defined in environments.xml — see the section below for more details.
  • --environment-file  <environment file>: [optional] Specify the file path where environments are defined. Defaulted to environments.xml.
  • --config <controller configuration file>: [optional] Specify the file path where controller settings are defined. Defaulted to controller.xml.
  • --port <port number>: [optional] Specify the port number on which to listen for agents. Whenever given, it overrides the port attribute specified in the controller configuration file (controller.xml).
  • --add-global-property  <key>=<value> : [optional, can be specified multiple times] Sets a global-level property.  See the properties section below for more details.
  • --add-workflow-property  <key>=<value> : [optional, can be specified multiple times] Sets a workflow-level property.  See the properties section below for more details.
  • --add-environment-property  <key>=<value> : [optional, can be specified multiple times] Sets an environment-level property.  See the properties section below for more details.
  • --preflight-check  : [action modifier] Runs a “preflight check” – a parsing and semantics checking of all XML and properties, without actually accepting agent connections and running a workflow.  A workflow and environment should be passed to do a preflight. If the environment is not specified then the given workflow will be checked on all environments. If the workflow is not specified then all workflows (from ./workflows directory and recursively from all sub-directories) will be checked on the given environment. And of course if both workflow and environment are missing then all workflows will be checked on all environments.
  • --no-check-artifacts : [optional] This will prevent nonexistent transfer artifacts from causing preflight check failure. Can be used only with --preflight-check.
  • --force-agent-update  : [optional] This will update agents (even if they are up to date).
  • --generate-configs  : [action modifier] Recursively loads files from resources (specified in the ‘configuration’ step of the workflow) and copies them to a temporary directory, compiling properties in the file.
  • --leroy-configuration-root <directory path>: [optional] Custom root directory to load configuration files from, in addition to or in place of those found in the current directory and the controller executable’s directory.
  • --deploy-only <agent IDs>: [optional] Deploy only to the specified agent IDs instead of all agents in the target environment. Multiple agents IDs can be simply specified by separating them with spaces after --deploy-only, like this: --deploy-only web1 jboss2 db1
  • --disable-full-agent-checkin : [optional] When agent checkin timeout is over, continue with all the agents that have reported in thus far, if any, instead of aborting the deployment due to missing agents.
  • --redirection-ports : [optional] Range(s) of ports from which agent redirection port numbers can be selected. Overrides any redirectionPorts  attribute specified in environments.xml  or controller.xml . See the Agent Redirection section for details.
  • --clean-ipc : [optional] Remove all IPC objects and set up fresh ones. IMPORTANT: use this only when no other controller process is running on the system!

AddAgent Options:

  • --agent-platform  <platform-name>:    The agent platform/architecture.
  • --agent-name  <name>: The agent name to be added in the system.
  • --agent-logicalname  <agent-id>: The agent logical name (alternatively called AgentID) in the environment. Makes sense only if --environment  option is specified.
  • --agent-lockerpath  <path>:  The locker path of agent.

SSH Options:

  • --ssh-host  <host>: The ssh host to connect to.
  • --ssh-port  <port>: The ssh port to connect to. Defaulted to 22.
  • --ssh-user  <user>: The user to initiate ssh connection. Defaulted to the current user.
  • --ssh-pass  <password>: The password to initiate ssh connection.
  • --ssh-destdir  <destination-directory>: The destination directory to install the agent to. Defaulted to “~/.leroy_agent”.


  • properties  – Top level tag that contains property definitions. Properties can be defined on the following levels:
    • global – as defined in properties/global.xml file.
    • workflow – as defined inside the <workflow>  tag for a given workflow.
    • step – a workflow step can have its own properties.
    • environment – as defined in properties/environment/<env-name>.xml (each environment may have its own properties).
    • agent – as defined in properties/agent/<agent-name>.xml and/or properties/agent/<env-name>-<agent-id>.xml (each agent may have its own properties and its own environment-specific properties).
  • Elements and attributes
    • element: property – A single property definition. The property value is nested inside the element.
      • attribute: name – (string) The name of the property.
      • attribute: export – (yes/no) If set to “yes” then the property is automatically exported as an environment variable as well. Default is “no”.
    • element: import – import properties
      • attribute: file – (string) Import a file containing property definitions, relative to the folder containing the controller executable, or an absolute path.

Built-in properties:
${Leroy.Home} – The path of the directory where the controller executable resides in.
${Leroy.Workflow} – The called workflow.
${Leroy.Environment} – The called environment’s name.
${environmentName} – The called environment’s name.
${Leroy.AgentName} – The name of the current agent.
${agentName} – The name of the current agent.
${id} – The id of the current agent within the called environment.
${agent.OS} – The agent’s platform identifier in the format of [OS]-[Platform], e.g. Darwin-x86_64. For Windows this will be either Win64 or Win32.



Environments are defined in environments.xml in the same folder as controller executable, or in any other folder that you pass in to the controller as --leroy-configuration-root. In Leroy an environment is a logical collection of agents grouped together with roles. Roles may or may not be common across all environments. If roles aren’t used consistently across all environments, Leroy will assume that you have forgotten to specify some roles in some of the environments, and will issue a warning, but you aren’t required to “fix” that if the setup you have is actually what you wanted to have.



  • element: environments  – Top level element that contains environments.
    • element: environment  – Container for an environment.
      • attribute: name  – The name of the environment, each environment name must be unique.
      • attribute: redirectionPorts  – Range(s) of ports from which agent redirection port numbers can be selected for this environment. Overrides any redirectionPorts  attribute specified in controller.xml . See the Agent Redirection section for details.
      • attribute: sslFilesPrefix  – The prefix of SSL files to use when deploying to this environment. If not given, the name of the environment is assumed to be that prefix. See the SSL Files section for details.
      • element: agents  – A container for multiple agent elements
        • element: agent  – An element representing each agent in an environment.
          • attribute: name  – The name of the agent.
          • attribute: roles  – one role, or many roles that are comma delimited. A role is a logical grouping of agents in order to perform tasks.
          • attribute: id  – The ID of the agent in the scope of the environment (aka the agent logical name). It must be unique within the environment, but can appear in other environments too (assigned to possibly different agents). This is useful in workflow step preconditions that you want to restrict to be run only on a specific agent in the environment, without knowing or caring about what actual names those agents have across the multitude of environments.




<workflow>  is the top level tag required for a workflow. Workflows are stored in the workflows/ folder (or subfolders thereof) 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. In any case though, workflow steps will always run in their order of declaration on any given agent when considered in isolation. It’s just that non-serial steps can run out of sync when considering different agents. For example, agent2 might be running step 4 while at the same time agent1 might still be on step 2. Such a situation cannot happen if either of the steps 2, 3 or 4 are serial.

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.

  • maxAgentsRunning  – (number) The maximum number of agents that can perform a task at one time.
  • lockerPath  – (string) A path to use for all agents to store its locker cache. This value overrides the value that is defined on the agent locally.
  • agentTimeout  – (number=30) The amount of time in seconds that the controller will wait for an agent to come back after connection with agent was dropped. A negative number here indicates infinity, i.e. no timeout for waiting. The default is 30 seconds.
  • defaultStepTimeout  – (number=0) The default timeout for workflow’s steps, which will be used for a step if the latter doesn’t have the  timeout  attribute specified. The default is 0 seconds (i.e. no timeout).
  • defaultPollingNoticeInterval  – (number=60) The default interval between successive notifications on how long a step has been executing till now, which will be used for a step if the latter doesn’t have the  pollingNoticeInterval  attribute specified. The default is 60 seconds.
  • extendedOutput  (yes/no) – The default value for  extendedOutput  attribute for the  execute  steps contained within the workflow. See execute attributes.


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


In addition to the usual workflow step elements, <workflow></workflow> supports:


environment , just like Execute does. The environment variables defined here will be automatically applied to all execute  steps in the workflow.

Example workflows here can help to better understand a workflow structure.

Common Step Attributes

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

  • precondition  – These are implemented using xpath operators and are ways for property values to determine if a workflow step will be run or not via a boolean check.
  • runOnError  – (yes/no) which defaults to false (no) but if true (yes) will run the step even if an error has occurred prior to this moment in some step on some agent during this workflow execution.
  • runOnlyOnError  – (yes/no) which defaults to false (no) but if true (yes) will run the step if and only if an error has occurred prior to this moment in some step on some agent during this workflow execution.
  • ignoreError  – (yes/no) which defaults to false (no) but if true (yes) will ignore an error produced by this step, and continue as if nothing happened.
  • role  – A comma-delimited list of roles which are allowed to run the command.  If blank, every agent is allowed to run the command.
  • serial  – (yes/no) If yes, it will force the step to run on all agents at the same time, meaning that when an agent is performing this step, other agents are either performing this same step, or have finished this step and other waiting for other agents to catch up. No agent can perform another step if any of the agents is performing a serial step at the time. Leroy will wait for all prior steps to finish on all agents before starting a serial step, then it will wait for all agents to finish that step before moving on to the next step. Defaults to no.
  • maxAgents  – the maximum number of agents allowed to run this workflow step at a time. If not set, it uses the workflow’s  maxAgentsRunning  attribute. If that’s not set either, no such limit is enforced.
  • runOnAny  – The number of agents which should run the step. If not set, the step will run an all agents (taking into account the role and precondition of course).
  • caption  – Gives the step a name of your choosing. That name will be included in the logs pertaining to the step.
  • timeout  – The number of seconds to wait for the step to complete before giving up on it. 0 means there is no timeout. Defaults to the workflow’s defaultStepTimeout  attribute value. Has effect only for execute, transfer, fetch and sleep steps.
  • pollingNoticeInterval  – The number of seconds between successive notifications on how long the step has been executing till now. 0 means no such notifications. Defaults to the workflow’s defaultPollingNoticeInterval  attribute value. Has effect only if the step is subject to potential timeout.


Run myscript.bat only in the role “jboss”, and if the property myscript_execution_enabled has value yes for the given agent. 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 step has failed prior to it. If in the command’s output we find a match to the “startsWithFailed” postProcess entry’s pattern, then consider the execution to have finished with error. Since serial="yes"  then wait for all previous steps to complete on all agents before starting this step on any agent, and continue with the next steps only when this one finished on all agents. If there are more than 10 agents in this role that satisfy the precondition, only run 10 at a time. If 30 seconds have passed since the start of myscript.bat execution and it hasn’t finished yet, then declare timeout, terminate that process along with all of its children, and mark the step as finished with error. “Step has been executing for N seconds” notifications will be printed in the controller output every 10 seconds.

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


Execute runs a command on a remote host (agent). 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 (unless postProcess  is specified). 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, or non-zero when in fact there is no real failure. In these cases, one can define a post process script where we can define one or many strings to catch that determine success or failure. These strings are 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.


  • Uses the Common Step Attributes
  • command  (file) – Executes the command given. The file must exist in the ${controllerRoot}/commands folder. The command is transferred to the agent (if the agent does not already have a current and matching copy), and executed.
  • workingDirectory  (string) – This is the folder that the command or script will run in, on the remote host. If omitted, the process will be launched in a subdirectory under the agent’s directory.
  • postProcess (string) – Post-process hooks are used to process output and determine if a process has succeeded or failed. Useful when success/failure can’t be reliably determined using the process exit code. The value of the attribute is used as the name of the post-process check to use, which must exist in postprocess.xml .
  • extendedOutput  (yes/no) – Controls whether output messages retrieved from the command will be prefixed with extended info about the command, namely the script/program file, arguments, working directory, environment variables. Defaults to true (yes).
  • shell  (string) – If a nested <script>  tag is used, this is the shell that is to be used to execute the script.  The value is ignored when using the script  element with type="python" . The default value for shell is the default system shell. One can specify any shell here like /bin/csh, /bin/tcsh or powershell.exe for example.  The shell process will receive the script via standard input.


  • properties : See here.
  • environment : Set environment variables for this command being executed.
    • attribute: name  – The name of the environment variable to set. Value is nested inside element.  Note that properties that are defined with export="yes"  will automatically be passed as environment variables to your executed command, in addition to the ones explicitly specified here with <environment>  elements.
  • arguments  – provide command line arguments to the command.
    • element: argument  – for each command line argument we pass, put in an argument tag nested inside arguments, in the needed order. Value is nested inside element.
  • script : Run an embedded script inside this script  tag. Note: Leroy property replacement will be performed within embedded scripts, in contrast to non-embedded script files found under commands/.
    • attribute: type  – (string) – May have the values shell  or python . If python , the script will run using the builtin Python within the Leroy agent executable (any system-wide Python that may be installed is ignored for type="python" scripts).


This example will run the command test.bat on all agents in the target environment that have the role jboss. The script test.bat must exist in the ${controllerRoot}/commands folder, otherwise the deployment will fail during the precheck stage. See the Common Step Attributes for explanation on serial="yes" .


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” and only if the target environment is “test”.


This example doesn’t require a script in the ${controllerRoot}/commands folder, rather the script itself is embedded in the workflow 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 a script where failure is determined on whether we see the string: [ERROR], regardless of the exit code



transfer  can do several things:

  • Transfers a file from the controller to an agent or group of agents.
  • Transfers a zip, tar, tgz, 7z (many formats) file from the controller to an agent or group of agents and explodes the file on the agent to the specified path.
  • Causes the agents to fetch a file using http, https, ftp, ftps, sftp, scp, file, tftp protocols.


  • Uses the Common Step Attributes
  • artifact  (file/URL) – This argument can either be either a file name that is in the artifacts folder of the controller, or a URL. URLs follow the standard convention of protocol://user:[email protected]/path?query . Supported protocols are http, https, sftp, ftp, ftps, scp, tftp, file.
  • to  (folder/file) – Folder or file path to transfer the file to. If the artifact is a URL, you must specify the file name in addition to the directory path. For example, if you were to transfer a file from the controller’s artifact folder, you can just specify the target folder like: to=/opt/folder but if you are fetching a URL you must do: to=/opt/folder/  This attribute can be omitted if the artifact  is not a URL and explode="no" , in which case the artifact is stored in the agent’s locker for quick use later; this is a good way to stage large artifacts and get the transfers out of the way prior to running your workflow to minimize downtime.
  • explode  (yes/no) – If set to “yes” and the file that is being transferred is a supported archive, then the agent will explode it in the folder specified in the to  attribute.
  • cleanup  (yes/no) – If set to “yes”, the artifact  is not a URL, and to  is specified, then will cause deleting everything from the target directory (specified with to= ) before doing the transfer.


  • properties : See here.
  • includes  – if transfer’s explode  attribute is set to ‘yes’, this element can be used to provide regular expression patterns of files to extract from the archive when unpacking.
    • element: include  – put patterns embedded in include  statements nested inside includes
      • attribute: scope  – Scope of the pattern to apply to.  Possible values are wholePath  and filename .  The default is wholePath
  • excludes  – if transfer’s explode  attribute is set to ‘yes’, provide regular expression patterns of files to NOT extract from the archive when unpacking.
    • element: exclude  – put patterns embedded in exclude  statements nested inside excludes .
      • attribute: scope  – Scope of the pattern to apply to.  Possible values are wholePath  and filename .  The default is wholePath .

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 exclude d, 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 target environment that have 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  step in it’s own section below.


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



sleep can have only the properties element: see here.


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


Causes the controller to wait for all agents to complete the previous steps’ execution before dispatching any of the following steps to the agents. This is conceptually equivalent to a no-op step with serial="yes" as its sole attribute.  join can’t have any elements, not even properties! Nor it can have any attributes, not even the Common Step Attributes!



echo simply prints something to controller’s standard output. Please note that an echo step defaults to serial="yes"  behavior. If this is undesirable, explicitly state serial="no" for each echo step as needed.


  • Uses the Common Step Attributes, those that make sense for echo  that is ( role doesn’t make sense for example).


echo must have the unnamed element present, which will be the string that will be printed to controller’s standard output.

From named elements, echo can have only the properties element: see here.



fetch will cause the controller to fetch a file from a URL and store it in the controller’s artifacts folder (or to an absolute path specified). This is different from specifying a URL in a transfer step since that causes the agent (each agent) to do the URL fetch, as opposed to the controller doing it. Typical use of this would be to fetch a collection of artifacts from your favorite build server and populate your controller’s artifacts folder, then perform transfers to your agents.


  • Uses the Common Step Attributes
  • url (URL) – This is the URL of the file you want to fetch
  • to (filename) – This is the name of the file you want to save your fetch as in the artifacts folder. Or you can specify an absolute file path, which will be used to store the file into rather than putting it inside the artifacts folder.


fetch can have only the properties element: see here.



import and import_once are pseudo-steps 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. That enables great reusability of workflows and workflow steps.

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 was not imported before.


  • file  – The sub-workflow file to import. This can be an absolute or relative path to a workflow XML file. Relative paths are first considered relative to the workflows  directory, then relative to the current directory. Specifying the .xml file extension in this attribute is optional.
  • precondition  – An optional condition to determine if a specified file (sub-workflow) should be imported or not. For more information have a look at the Common Step Attributes.


import and import_once can have only the properties element: see here.



Post-process configurations allows one to call upon a post-process check in an execute step to test for error conditions. Post-process scripts are stored in postprocess.xml. Regular expressions and properties are supported inside post-process definitions. The executed process’ output is checked against post-process patterns line by line. Post-process definitions can be called by: Execute Attributes.

Example: ${controllerRoot}/postprocess.xml

SSL Files

Leroy uses a set of 3 files to make the communication between controller and agents be over SSL, i.e. encrypted and secure. The common names of those files are: controller.crt, controller.key, dh512.pem. When those files aren’t present in a controller installation, Leroy controller will generate them automatically. It is possible to use separate, environment-specific SSL files sets, that will have slightly different file names as explained further down in this section.

The .key (private key) file and the dhN.pem (Diffie-Hellman parameters) file are to be kept secure – never shared with anybody. Only the controller installation administrators should have a read access to those files.

The .crt (certificate file) must also be present alongside each and every installed agent’s directory, that need to communicate with the controller using that certificate. The file name at agents’ locations must be controller.crt, regardless of what the corresponding certificate file’s name is at the controller side. This is automatically taken care of when you create agent bundles using the --addagent, --extractagent, or --extractagent-all options. If you create agent bundles manually however, you need to copy the corresponding .crt file into the bundle and make sure the copy is named exactly controller.crt.

It is possible to use different sets of SSL files for different environments (e.g. you could have a separate SSL files set for prod environment, another set for demo environment, and use the default set for everything else). This would allow you to control at the filesystem permissions level which users can deploy to which environments. An environment-specific set of SSL files is distinguished from the default set by having the file names start with some well-defined prefix like so:  PREFIX-controller.crt, PREFIX-controller.key, PREFIX-dh512.pem; where PREFIX is by default the environment’s name, but can be altered to whatever you like it to be by using the  sslFilesPrefix attribute of the environment.

Example: Let’s assume you have files prod-controller.crt, prod-controller.key, prod-dh512.pem present in the controller’s directory alongside with the default set of the SSL files (those that have no prefix in the file names). Then if you have an environment named “prod”, the deployments to that environment will use these prod-* SSL files set instead of the default ones. Suppose additionally you have another environment named “prod_reporting”, and you want to use the existing prod-* SSL files set for it too instead of using the defaults or creating a new prod_reporting-* files set. Then all you have to do is have sslFilesPrefix="prod" attribute present in the “prod_reporting” environment’s definition. Relevant part from the environments.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:

  • ${id} : The Agent ID in the environment. The same agent can have different IDs in different environments, but the same Agent ID can’t be duplicated in scope of one environment. In other words this is a logical name of the agent.
  • ${agent.OS}: The agent’s platform identifier in the format of [OS]-[Platform], e.g. Darwin-x86_64. For Windows this will be either Win64 or Win32.
  • ${Leroy.Environment}: The environment name that is being deployed now. This is commonly used in preconditions where you want something to only occur in one environment: precondition=”‘${Leroy.Environment}’ = ‘dev'”
  • ${Leroy.Workflow}: The name of the workflow that is currently being deployed.

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

Agent Command Line

The agent understands several command line parameters:

  • –service : installs the agent as a service (Windows only)
  • –config <config.xml> : Uses a specified configuration XML file.  The default is agent.xml
  • –log <filename> : Specify a file name to log to.  The default is standard output.
  • –loglevel <none|debug|info|warning|error> : Specify an error level to log.  The default is warning.
  • –python [<filepath>|-] : Invoke the internal Python interpreter. A python script file can be given to execute; if not given or given “-“, the code to execute will be read from standard input.
  • –agent-name <name> : Name of the agent. Is optional, and taken from agent.xml if this argument is not given.
  • –controller <host>:<port> : Host:port of the controller to connect to. Is optional, and taken from agent.xml if this argument is not given.


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.

  • agents – top level container to hold agent
    • element agent – An instance of an agent
      • attribute name – A unique name of an agent.
      • element Supports: Properties



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