HelpersInstallChocolateyWindowsService.md

Install-ChocolateyWindowsService

NOTE: This function requires a Chocolatey for Business License to use.

Installs a Windows Service using Install Util, plus some extra awesome-sauce.

Syntax

Install-ChocolateyWindowsService `
  -Name <string> `
  -ServiceExecutablePath <string> `
  [-Username <string>] `
  [-Password <string>] `
  [-DisplayName <string>] `
  [-Description <string>] `
  [-StartupType <ChocolateyWindowsServiceStartupType> {Unknown | Manual | Automatic | Disabled}] `
  [-DoNotStartService] `
  [-DoNotReinstallService] `
  [<CommonParameters>]

Description

This installs a Windows Service onto a machine. When provided a user name, this will ensure that user exists, is in the Administrators group, and has all of the correct privileges to run as a service. For more details on the privileges, see the Username parameter below.

If a user is not a built in user and no password is provided, Chocolatey will manage the password, which will be different for every machine and user and very complex. For more details on the password, see the Password parameter below.

One of the additional advanced features of this function is being able to upgrade a service without shutting it down first - Chocolatey will move the current running service and put in all of the new binaries. It will require a restart of the service to move to the new code, but you can upgrade a service in place without shutting it down first (one time). To use this, you must supply the DoNotReinstallService switch. See the parameter below for more details.

Notes

Requires Chocolatey for Business.

Aliases

None

Examples

EXAMPLE 1

Install-ChocolateyWindowsService -Name 'bob' -ServiceExecutablePath 'c:\somewhere\to\service.exe'

EXAMPLE 2

$toolsDir   = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"
$serviceExe = Join-Path $toolsDir 'service\dan-agent.exe'

$packageArgs = @{
  Name                  = 'dan'
  DisplayName           = 'Dan Agent'
  ServiceExecutablePath = $serviceExe
  Username              = 'DanTheBuilder'
}

Install-ChocolateyWindowsService @packageArgs

EXAMPLE 3 This is the installation code for the Chocolatey Agent service itself.

$toolsDir   = "$(Split-Path -parent $MyInvocation.MyCommand.Definition)"
$serviceExe = Join-Path $toolsDir 'service\chocolatey-agent.exe'

$packageArgs = @{
  Name                  = 'chocolatey-agent'
  DisplayName           = 'Chocolatey Agent'
  Description           = 'Chocolatey Agent is a backgound service for Chocolatey.'
  StartupType           = 'Automatic'
  ServiceExecutablePath = $serviceExe
  Username              = 'ChocolateyLocalAdmin'
}

$pp = Get-PackageParameters
if ($pp['Username']) { $packageArgs['Username'] = $pp['Username'] }
if ($pp['Password']) { $packageArgs['Password'] = $pp['Password'] }
if ($pp['EnterPassword']) { $packageArgs['Password'] = Read-Host "Enter password for $($packageArgs['Username']):" -AsSecureString}
if ($pp['UseDefaultChocolateyConfigUser']) { $packageArgs.Remove('Username') }

# We don't want to shut down the service when we are running in background mode
if ($env:ChocolateyBackgroundService -eq 'true') {
  Write-Warning "Detected running in background mode to upgrade the chocolatey-agent. Upgrade will attempt without restarting the service. \n Changes to service itself (like user/password) will be ignored."
  $packageArgs['DoNotReinstallService'] = $true
}

# Explicit request not to restart or reinstall the service.
if ($pp['NoRestartService'] -or $pp['DoNotReinstallService']) {
  Write-Warning "Upgrade will attempt without restarting the service. \n Changes to service itself (like user/password) will be ignored."
  $packageArgs['DoNotReinstallService'] = $true
}

Install-ChocolateyWindowsService @packageArgs

Inputs

None

Outputs

None

Parameters

-Description [<string>]

The description of the service.

Property	Value
Aliases
Required?	false
Position?	Named
Default Value
Accept Pipeline Input?	true (ByPropertyName)

-DisplayName [<string>]

The display name of the service.

Property	Value
Aliases
Required?	false
Position?	Named
Default Value
Accept Pipeline Input?	true (ByPropertyName)

-DoNotReinstallService

Do not uninstall/restart service. This is for advanced scenarios when you need to deploy a newer version of a service and control when the restart happens over to the newly deployed code.

Property	Value
Aliases
Required?	false
Position?	Named
Default Value
Accept Pipeline Input?	true (ByPropertyName)

-DoNotStartService

Do not start service after install. This keeps the service from starting up when installing/upgrading.

Property	Value
Aliases
Required?	false
Position?	Named
Default Value
Accept Pipeline Input?	true (ByPropertyName)

-Name <string>

The name of the service to install.

Property	Value
Aliases
Required?	true
Position?	0
Default Value
Accept Pipeline Input?	true (ByPropertyName)

-Password [<string>]

The password for the service - defaults to empty. If the user is not a built-in account like LocalSystem and the user name is provided without a password being provided, the password will automatically be a Chocolatey Managed Password.

When Chocolatey manages the password for an account, it creates a very complex password:

• 32 characters long
• Uppercase, lowercase, numbers, and symbols to meet very stringent complexity requirements
• Different for every machine
• Completely unguessable

No one at Chocolatey Software could even tell you what the password is for a particular machine without local access.

Property	Value
Aliases
Required?	false
Position?	Named
Default Value
Accept Pipeline Input?	true (ByPropertyName)

-ServiceExecutablePath <string>

The full path (absolute path) to the service executable file.

Property	Value
Aliases
Required?	true
Position?	1
Default Value
Accept Pipeline Input?	true (ByPropertyName)

-StartupType [<ChocolateyWindowsServiceStartupType>]

The startup type of the service. Defaults to Automatic.

Property	Value
Aliases
Required?	false
Position?	Named
Default Value
Accept Pipeline Input?	true (ByPropertyName)

-Username [<string>]

The username for the service - defaults to LocalSystem (SYSTEM). If the user does not exist, the user will be created. When a user is specified for a service, the following things will also occur as part of this function:

• User added to Administrators group
• User given privilege/right to run as a service (SeServiceLogonRight)
• User given privilege/right to log on as a batch (SeBatchLogonRight)
• User given privilege/right to log on interactively (SeInteractiveLogonRight)
• User given privilege/right to log on network (SeNetworkLogonRight)

Property	Value
Aliases	user
Required?	false
Position?	2
Default Value
Accept Pipeline Input?	true (ByPropertyName)

[[Function Reference|HelpersReference]]

NOTE: This documentation has been automatically generated from licensed code.