How to Configure Services using the Services.xml
Applied to: Cloudhouse Containers
23/07/2019 Cliff Hobbs ID: 349959
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.
To configure services using the Services.xml:
- Navigate to the relevant Container folder.
- Open the Services.xml in a text editor such as Notepad++.
- 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>
- Specify any additional properties as detailed below.
- Save the file.
- Redeploy/rerun the Container.
You can configure other properties for a service by adding the following elements as children of an existing service element:
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.
<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:
The value for the <Delay> element is the number of milliseconds the operating system will wait before executing the action.
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>
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>
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:
- 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.
You can configure two different types of 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 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.
<LogOnAs> <Username>NT Service\ConnorsLettuce</Username> <Privileges> <Privilege>SeAuditPrivilege</Privilege> <Privilege>SeBackupPrivilege</Privilege> </Privileges> </LogOnAs>
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>
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>
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 Delayed
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.).
<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.