Access Keys:
Skip to content (Access Key - 0)

Click the arrows to expand the menu.




Download the PDF
of this documentation:

Deploy a Service

Many popular services are easy to configure to run with the CloudIQ Manager.

Windows

Deploying a Windows service is a relatively simple process. Create a Fabric Archive (FAR) Definition XML file that will direct the installation and operation of the service.

Here is an example, which we will go through in detail:

<?xml version="1.0" encoding="utf-8"?>
<far xmlns="http://www.appistry.com/ns/far"
name="win-service" version="1.00" 
display-name="Windows Service version 1.0" 
description="A Service for Windows">
<support-files>
<file name="service_1.0-win32-x86.msi"/>
<file name="settings.cfg"/>
<file name="install.bat"/>
<file name="query.bat"/>
<file name="uninstall.bat"/>
</support-files>
<service>
<install>
   <exec executable="install.bat" 
         output="instout.txt" 
         error="insterr.txt" 
         timeout="3 minutes"/>
</install>
<uninstall>
   <exec executable="uninstall.bat" 
         output="uninout.txt" 
         error="uninerr.txt" 
         timeout="3 minutes"/>
</uninstall>
<start>
   <exec executable="sc.exe"
         output="startout.txt" 
         error="starterr.txt" 
         timeout="1 minute">
      <arg value="start"/>
      //This should be the name that the
      //service registers with Windows
      <arg value="win-service1.0"/> 
   </exec>
</start>
<stop>
   <exec executable="sc.exe" 
         output ="stopout.txt" 
         error="stoperr.txt" 
         timeout="1 minute">
      <arg value="stop"/>
      <arg value="win-service1.0"/>
   </exec>
</stop>
<query>
   <exec executable="query.bat" 
         output="queryout.txt" 
         error="queryerr.txt" 
         timeout="1 minute">
      <arg value="win-service1.0"/>
   </exec>
</query>
</service>
</far>

Support Files (optional)

Any files to be included in the deployable package. If required, include a configuration file (for example, settings.cfg) or any other files required by service. From within the fabric, these files can be found by fabric applications by prepending '$FABRIC_HOME/fars/far-name' to the path of the file, where 'far-name' corresponds to the FAR's 'name' attribute (in the example, 'win-service)') In the example, we include executables and scripts for installing, uninstalling and running the service, but these may also be found by relative, absolute or any available (to all workers) network path.

Install (required)

The '<install>' element, containing an executable program or script for installing the service, will be executed one time, when the service is deployed. The service must be able to be installed quietly (i.e., no user prompts). The '<exec>' element (required) has an optional '<arg>' sub-element. Create an 'install.bat'(as appropriate), to contain the service installer and with additional activities, such as copying configuration files, setting environment variables, etc. Ideally, the installer should register the service with Windows.

Example 'install.bat':

@echo off
service_1.0-win32-x86.msi /q
copy settings.cfg "C:\Program Files\Windows Service Company\win-service1.0\config"
No Script Required
If no configuration files are needed, the service-installer could be referenced directly from the '<install>' element, without an 'install.bat'.

Uninstall (required)

The '<uninstall>' element, containing an executable program or script for uninstalling the service, will be executed one time, when the service is deleted from the fabric or a new version is deployed. The service must be able to be uninstalled quietly (i.e., no user prompts). The '<exec>' element (required) has an optional '<arg>' sub-element. Create an 'uninstall.bat'(as appropriate), to accompany the service uninstaller with additional activities, such as deleting configuration files and directories, removing environment variables, etc. Ideally, the installer should unregister the service with Windows.

Example 'uninstall.bat': 

@echo off
msiexec /uninstall service_1.0-win32-x86.msi /quiet
rd /q /s "C:\Program Files\Windows Service Company\win-service1.0"
Beware "rd" ...
In the uninstaller example, 'rd /q /s "C:\Program Files\Windows Service Company\win-service1.0"' will remove the entire service directory.


Start (required)

The executable path (with arguments if necessary) to start the service.

Our example uses 'sc' to start the service. To use 'sc', the service must be registered with Windows during installation. 

<start>
<exec executable="sc.exe"
   output="startout.txt" 
   error="starterr.txt" 
   timeout="1 minute">
<arg value="start"/>
<arg value="win-service1.0"/> 
</exec>
</start>

Stop (required)

The executable path (with arguments if necessary) to stop the service.

Our example uses 'sc' to stop the service. To use 'sc', the service must be registered with Windows during installation. 

<stop>
<exec executable="sc.exe" 
   output ="stopout.txt" 
   error="stoperr.txt" 
   timeout="1 minute">
<arg value="stop"/>
<arg value="win-service1.0"/>
</exec>
</stop>

Query

The executable path (with arguments if necessary) to query the state of the service. See Query Elements for more information.

Kill (optional)

The executable path (with arguments) to an appropriate kill command. The '<kill>' element must be included between '<stop>' and '<query>' elements. Review the '<kill>' example provided.

Kill Is Optional
The 'taskkill' command used in this example is optional. The '/im' option will search for a specified image name of the process to be terminated. The '/f' option will forcefully kill the service.
<kill>
<exec executable="taskkill.exe" 
   output="killout.txt" 
   error="killerr.txt" 
   timeout="5 minutes">
<arg value="/im win-service1.0 /f"/>
</exec>
</kill>

Package and Deploy

Use the fabric_pkg command to package the FAR. Any files to be packaged should be in the directory containing 'win-service.xml' or a sub-directory. 

fabric_pkg create win-service.xml -verbose

Deploy the newly created 'win-service.far' using the fabric_ctl deploy command:

fabric_ctl deploy win-service.far
Congratulations!
Your Windows service is now running on the CloudIQ Platform.

Linux

Deploying a Linux service to the fabric is a relatively simple process. Create a Fabric Archive (FAR) Definition XML file that will direct the installation and operation of the service.

Here is an example, which we will go through in detail:

<?xml version="1.0" encoding="utf-8"?>
<far xmlns="http://www.appistry.com/ns/far"
name="lin-service" version="1.00" 
display-name="Linux Service 1.0">
<support-files>
<file name="service-1.0.0.tar.gz"/>
<file name="install.sh"/>
<file name="query.sh"/>
<file name="uninstall.sh"/>
</support-files>
<service rights="elevated">
<install>
   <exec executable="/bin/sh"
         output="instout.txt" 
         error="insterr.txt" 
         timeout="3 minutes">
      <arg value="install.sh"/>
   </exec>
</install>
<uninstall>
   <exec executable="/bin/sh" 
         output="uninout.txt" 
         error="uninerr.txt" 
         timeout="3 minutes">
      <arg value="uninstall.sh"/>
   </exec>
</uninstall>
<start>
   <exec executable="/bin/su"
         output="startout.txt" 
         error="starterr.txt" 
         timeout="1 minute">
      <arg value="-"/>
      <arg value="serviceuser"/>
      <arg value="-c"/>
      <arg value="/usr/local/service-1.0.0/bin/startup.sh"/>
   </exec>
</start>
<stop>
   <exec executable="/bin/su"
         output="startout.txt" 
         error="starterr.txt" 
         timeout="1 minute">
      <arg value="-"/>
      <arg value="serviceuser"/>
      <arg value="-c"/>
      <arg value="/usr/local/service-1.0.0/bin/shutdown.sh"/>
   </exec>
</stop>
<query>
   <exec executable="/bin/sh" 
         output="queryout.txt" 
         error="queryerr.txt" 
         timeout="1 minute">
      <arg value="query.sh"/>
   </exec>
</query>
</service>
</far>

Support Files

Any files to be included in the deployable package. If required, include a configuration file (for example, settings.cfg) or any other files required by the service. From within the fabric, these files can be found by fabric applications by prepending '$FABRIC_HOME/fars/far-name' to the path of the file, where 'far-name' corresponds to the FAR's 'name' attribute (in the example, 'lin-service)') In the example, we include executables and scripts for installing, uninstalling and running the service, but these may also be found by relative, absolute or any available (to all workers) network path.

Service Rights Attribute

The XML uses '<service rights="elevated">' to identify the authority under which actions will be performed. The choice is 'elevated' or 'default'. Choosing 'elevated' rights will execute as 'Appistry System Service (fabric_system_service)'. In Linux, this is 'root' priveledge.

FAR Directories
When a service is deleted, the service's files are deleted from its FAR directory but the files written during execution of that service ('output', 'error' or files written by the service itself) and the FAR directory are NOT deleted. If you desire these files to be deleted, your uninstall script should clean these up. If the files are written by an 'elevated' service, you will need to be logged in with 'root' permission to remove them.

Install (required)

The '<install>' element, containing an executable program or script for installing the service, will be executed one time, when the service is deployed. The '<exec>' element (required) has an optional '<arg>' sub-element. Create an 'install.sh'(as appropriate), to contain the service installer and with additional activities, such as copying configuration files, setting environment variables, etc.

For example, the following script creates a user and group for 'fabservices', sets up its environment for the fabric, expands the service into '/usr/local' and changes ownership of the service directory to be run by 'serviceuser'.

#!/bin/sh
groupadd serviceuser
useradd serviceuser -g servicegroup
echo ". /etc/fabric_env" >> /home/serviceuser/.bashrc
/bin/tar zxf service-1.0.0.tar.gz -C /usr/local
chown -R serviceuser:servicegroup /usr/local/service-1.0.0

Uninstall (required)

Review and update the 'uninstall.sh' script as desired, which gets called as '/bin/sh uninstall.sh' in the XML. Be sure to account for any modification you made to the 'install.sh. The script will be invoked if the service is deleted or if a newer version is deployed. It forcefully removes the service directory and deletes the 'serviceuser' user.

#!/bin/sh
/bin/rm -rf /usr/local/service-1.0.0
userdel -r serviceuser
FAR Directories
When a service is deleted, the service's files are deleted from its FAR directory but the files written during execution of that service ('output', 'error' or files written by the service itself) and the FAR directory are NOT deleted. If you desire these files to be deleted, your uninstall script should clean these up. If the files are written by an 'elevated' service, you will need to be logged in with 'root' permission to remove them.

Start (required)

The executable path (with arguments if necessary) to start the service. Review the '<start>' element in the XML, which calls the service's start command as 'serviceuser': '/bin/su - serviceuser -c /usr/local/service-1.0.0/bin/start.sh'.

<start>
<exec executable="/bin/su"
   output="startout.txt" 
   error="starterr.txt" 
   timeout="1 minute">
<arg value="-"/>
<arg value="serviceuser"/>
<arg value="-c"/>
<arg value="/usr/local/service-1.0.0/bin/startup.sh"/>
</exec>
</start>

Stop (required)

The executable path (with arguments if necessary) to start the service. Review the '<stop>' element in the XML, which essentially calls the command '/bin/su - serviceuser -c /usr/local/service-1.0.0/bin/shutdown.sh'.

<stop>
<exec executable="/bin/su"
   output="startout.txt" 
   error="starterr.txt" 
   timeout="1 minute">
<arg value="-"/>
<arg value="serviceuser"/>
<arg value="-c"/>
<arg value="/usr/local/service-1.0.0/bin/shutdown.sh"/>
</exec>
</stop>

Query

The executable path (with arguments if necessary) to query the state of the service. See Query Elements for more information.

Kill (optional)

The executable path (with arguments) to an appropriate kill command. The '<kill>' element must be included between '<stop>' and '<query>' elements. Review the '<kill>' example provided.

<kill>
<exec executable="pkill"
   output="killout.txt"
   error="killerr.txt">
<arg value="-u"/>
<arg value="serviceuser"/>
<arg value="service"/>
</exec>
</kill>

Package and Deploy

Use the fabric_pkg command to package the FAR:

$ fabric_pkg create lin-service.xml -verbose

Deploy the newly created 'lin-service.far' to the fabric using the fabric_ctl deploy command:

$ fabric_ctl deploy lin-service.far