DSC resource for configuring Windows services.
Carbon_Service [string] #ResourceName
{
Name = [string]
[ Command = [string] ]
[ Credential = [PSCredential] ]
[ Dependency = [string[]] ]
[ DependsOn = [string[]] ]
[ Ensure = [string] { Absent | Present } ]
[ OnFirstFailure = [string] { Reboot | Restart | RunCommand | TakeNoAction } ]
[ OnSecondFailure = [string] { Reboot | Restart | RunCommand | TakeNoAction } ]
[ OnThirdFailure = [string] { Reboot | Restart | RunCommand | TakeNoAction } ]
[ Path = [string] ]
[ RebootDelay = [Int32] ]
[ ResetFailureCount = [Int32] ]
[ RestartDelay = [Int32] ]
[ RunCommandDelay = [Int32] ]
[ StartupType = [string] { Automatic | Disabled | Manual } ]
[ UserName = [string] { LocalService | LocalSystem | NetworkService } ]
}
The Carbon_Service
resource configures Windows services, including name, credentials, startup type, state, failure actions, and dependencies.
The service is installed when the Ensure
property is set to Present
. If the service already exists, and its configuration doesn't match the properties being set, the service is stopped, its configuration updated, and the service is restarted. Properties not passed are ignored/left as-is.
In addition to installing the service, this resource also grants the service user the logon as a service privilege and execute permissions on the service executable.
The service is uninstalled when the Ensure
property is set to Absent
. The service is stopped, then uninstalled.
Name | Type | Description | Required? | Pipeline Input | Default Value |
---|---|---|---|---|---|
Name | String | The name of the service. | true | false | |
Path | String | The path to the service. | false | false | |
StartupType | String | The startup type: automatic, manual, or disabled. Default is automatic. | false | false | |
OnFirstFailure | FailureAction | What to do on the service's first failure. Default is to take no action. | false | false | |
OnSecondFailure | FailureAction | What to do on the service's second failure. Default is to take no action. | false | false | |
OnThirdFailure | FailureAction | What to do on the service' third failure. Default is to take no action. | false | false | |
ResetFailureCount | Int32 | How many seconds after which the failure count is reset to 0. | false | false | 0 |
RestartDelay | Int32 | How many milliseconds to wait before restarting the service. Default is 60,0000, or 1 minute. | false | false | 0 |
RebootDelay | Int32 | How many milliseconds to wait before handling the second failure. Default is 60,000 or 1 minute. | false | false | 0 |
Dependency | String[] | What other services does this service depend on? | false | false | |
Command | String | The command to run when a service fails, including path to the command and arguments. | false | false | |
RunCommandDelay | Int32 | How many milliseconds to wait before running the failure command. Default is 0, or immediately. | false | false | 0 |
UserName | String | The system account the service should run as. | false | false | |
Credential | PSCredential | The credentials of the custom account the service should run as. | false | false | |
Ensure | String | If Present , the service is installed/updated. If Absent , the service is removed. |
false | false | Present |
Demonstrates how to install a service that runs as a custom account and has custom failure actions.
Carbon_Service InstallNoOpService
{
Name = 'CarbonNoOpService';
Path = 'C:\Projects\Carbon\bin\NoOpService.bin';
StartupType = 'Automatic';
Credential = $noOpServiceCreential';
OnFirstFailure = 'RunCommand';
Command = 'example.exe /fail %1%';
RunCommandDelay = 1000;
OnSecondFailure = 'Restart';
RestartDelay = (1000*60*5); # 5 minutes as milliseconds
}
Demonstrates how to install a service that runs as a built-in account.
Carbon_Service InstallNoOpService
{
Name = 'CarbonNoOpService';
Path = 'C:\Projects\Carbon\bin\NoOpService.bin';
StartupType = 'Automatic';
UserName = 'LocalService';
}
Demonstrates how to remove a service.
Carbon_Service InstallNoOpService
{
Name = 'CarbonNoOpService';
Ensure = 'Absent';
}