Carbon_Service

DSC resource for configuring Windows services.

Syntax

Carbon_Service [String] #ResourceName
{
    Name = [string]
    [Command = [string]]
    [Credential = [PSCredential]]
    [Dependency = [string[]]]
    [DependsOn = [string[]]]
    [Description = [string]]
    [DisplayName = [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]]
    [PsDscRunAsCredential = [PSCredential]]
    [RebootDelay = [Int32]]
    [ResetFailureCount = [Int32]]
    [RestartDelay = [Int32]]
    [RunCommandDelay = [Int32]]
    [StartupType = [string]{ Automatic | Disabled | Manual }]
    [UserName = [string]{ LocalService | LocalSystem | NetworkService }]
}

Description

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.

Carbon_Service is new in Carbon 2.0.

Related Commands

Parameters

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
DisplayName String

The service's display names.

false false
Description String

The service's description.

false false
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

EXAMPLE 1

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
}

EXAMPLE 2

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';
}

EXAMPLE 3

Demonstrates how to remove a service.

Carbon_Service InstallNoOpService
{
    Name = 'CarbonNoOpService';
    Ensure = 'Absent';
}