How to Configure Services using the Services.xml

Save to PDF

Applied to: Cloudhouse Containers

23/07/2019 Cliff Hobbs   ID: 349959

Purpose

The purpose of this article is to detail how to configure services for a Cloudhouse Compatibility Container™ through the Services.xml file

Overview of the Services.xml file

When you deploy a Cloudhouse Container to the machine scope, any services configured in the Services.xml file (located in the Container's folder) are registered on the system. 

The format of the Services.xml file is detailed below.

Step-by-step process

To configure services using the Services.xml:

  1. Navigate to the relevant Container folder.
  2. Open the Services.xml in a text editor such as Notepad++.
  3. Create an entry for the new service under the <Services> section (creating this if required), ensuring you specify the <Name> and <ImagePath>properties at a minimum. For example:
    <Services>
        <Service>
            <Name>service1</Name>
            <ImagePath>%defaultdir%\Cloudhouse.container.run.exe --RunConditions run1</ImagePath>
        </Service>
    </Services>

Important

To run a virtualised executable as a service, the value of the <Imagepath> element should begin with Cloudhouse.Container.Run.exe followed by the corresponding run condition to execute. The entry for the RunCondition must have the value of:

  • <WaitCondition> defined as Exit
  • TimeoutInSeconds set to 0

If set incorrectly, the service host will not detect the service is running.

<Programs>
    <Program>
        <RunCondition>run1</RunCondition>
        <ProcessWindowStyle>Normal</ProcessWindowStyle>
        <Path>%DefaultDir%\AppAcceleratorV.exe</Path>
        <Args>/f "%DefaultDir%\ProgData\Program Files\services\service.exe"</Args>
        <WorkingDirectory />
        <WaitCondition TimeoutInSeconds="0">Exit</WaitCondition>
    </Program>
</Programs>
  1. Specify any additional properties as detailed below.
  2. Save the file.
  3. Redeploy/rerun the Container.

Additional Properties

You can configure other properties for a service by adding the following elements as children of an existing service element:


Actions

The <Actions> element defines a list of actions to execute in the event of the first, second, and subsequent failures, which is the same as configuring these for the service on the Recovery tab of the Services applet.

Note

We recommend you only configure a maximum of three <Actions> elements, using the third for subsequent failures.

<Actions>       
    <Action>          
        <Type>Run</Type> 
        <Delay>5000</Delay>        
    </Action>        
    <Action>          
        <Type></Type>          
        <Delay></Delay>        
    </Action>        
    <Action>          
        <Type>Restart</Type>          
        <Delay>10000</Delay>        
    </Action>        
</Actions>

The possible values for the <Type> element are:

  • Run
  • Restart
  • Reboot

The value for the <Delay> element is the number of milliseconds the operating system will wait before executing the action.

DependOnService

The <DependOnService> element is used to list any other services the service depends on. The deployment will ensure they exist before deploying the Container and will configure the service with the dependencies listed. The services listed can be virtual, non-virtual, inside/outside of the Container.

<DependOnService>
    <Name>DifferentService1</Name>
    <Name>DifferentService2</Name>
</DependOnService>

Description and DisplayName

The values defined for the <Description> and <DisplayName> elements will be shown in the Windows Services Manager to help identify the service.

<Description>A service deployed by a Cloudhouse Container</Description>
<DisplayName>Service is number 1</DisplayName>

LogOnAs

The <LogOnAs> element specifies the user account the service runs under once the service is deployed, which can be a different account if required. However, it cannot be a full domain user that requires a password to logon.

<LogOnAs>
      <Username>NT Service\CustomVirtualService</Username>      
</LogOnAs>

Possible values for the <Username> element are:

  • LocalSystem
  • NT Authority\LocalService
  • NT Authority\NetworkService
  • NT Service\<ServiceName> where <ServiceName> is the name the of the service the account is to run under otherwise Windows will not allow the creation of the service.

Note

Please contact Cloudhouse support for assistance if you need to configure a service to logon using a full domain user account that requires a password as this is currently unsupported.

Privileges

You can configure two different types of Privileges:

Note

See the following Microsoft documents for information on privileges:

The values supported by both elements are the same.

Required Privileges

Required Privileges are the privileges needed for the service to start and run.

The <RequiredPrivileges> element is used to detail the privileges a service requires (one <RequiredPrivilege> privilege per entry), which are applied at the time the service is deployed.

If a Container needs to deploy a service and start it, the user account performing the deployment needs to have the correct <RequiredPrivileges> otherwise the Container fails to deploy.

If however, the service only needs to be deployed and not started, then the <RequiredPrivileges> element does not need to be defined.

<RequiredPrivileges>
      <RequiredPrivilege>SeDebugPrivilege</RequiredPrivilege>
      <RequiredPrivilege>SeIncreaseQuotaPrivilege</RequiredPrivilege>
</RequiredPrivileges>

User Privileges

User Privileges can be used to grant privileges to a user they would normally not have so that they can run a service.

The <Privileges> element is used to detail the privileges to grant to the user (one <Privilege> per entry), which are applied to the user at the time the service is deployed.

Note

Typically you probably won't need to use this. But there may be occasions where your application is currently running under a service account that cannot be ported to the new environment. In this case, the Packager creates a new custom service account in the new environment and uses the <Privileges> element to grant this account the relevant privileges required to run the service.

<LogOnAs>
      <Username>NT Service\ConnorsLettuce</Username>
      <Privileges>
        <Privilege>SeAuditPrivilege</Privilege>
        <Privilege>SeBackupPrivilege</Privilege>
      </Privileges>
</LogOnAs>

Recovery

The <Recovery> element defines the command to execute if the service fails.

<Services>
    <Service>
        <Name>ATestService</Name>
        <ImagePath>C:\Services\WindowsTestService.exe</ImagePath>
        <Recovery>
            <Command>%ProgramFiles%\runthis.exe</Command>
        </Recovery>
    <Service>
</Services>

Reset

The <Reset> element defines the number of seconds before the recovery actions reset, that is Windows decides to go back to the action configured for the First failure setting. By default, this is 86,400 seconds, which is 24 hours and matches the default Windows behaviour set for the service on the Recovery tab of the Services applet.

<Services>
    <Service>
        <Name>ATestService</Name>
        <ImagePath>C:\Services\WindowsTestService.exe</ImagePath>
        <Recovery>
            <Reset>86400</Reset>
            <Actions>
                <Action>
                    <Type>restart</Type>
                    <Delay>10000</Delay>
               </Action>
            </Actions>
        </Recovery>
    <Service>
</Services>

Startup and StartOnDeploy

The <Startup> and <StartOnDeploy> elements can be used to configure when the deployment tools and Windows start the service.

The <Startup> element sets the startup type of the deployed service ready for Windows to action when it starts. This element can be one of the following:

  • Automatic
  • Automatic Delayed
  • Manual 
  • Disabled

If the service was running at the time the application was containerised, the value of the <StartOnDeploy> element is set to true, and the Container starts the service when deployed.

If the service was not running at the time the application was containerised, the value of the <StartOnDeploy> element is set to false, and the Container does not start the service when deployed.

If the service needs to be started, some other process will need to start it (for example the user, the application when it runs, a scheduled task, etc.).

Important

It is invalid for the <StartOnDeploy> element to be configured as true if you configure the <Startup> element as disabled

<Services>
  <Service>
    <Name>CoolService</Name>
    <ImagePath>Something Valid</ImagePath>
    <StartOnDeploy>true</StartOnDeploy>
    <Startup>Automatic</StartupType>
  </Service>
</Services>

This completes how to configure Services using the Services.xml file.

Source:
Was this article helpful?

Table of Contents

    Can't find what you're looking for?

    Contact Support