The service itself does not ship with any installation tools or commands and entirely relies on the Icinga PowerShell Framework being installed. The Framework will provide a bunch of tools to make this step easy and user friendly.
Using the Wizard¶
The most straight-forward way to install the service is by using the Kickstart Script or the installation wizard of the Framework. In case you already run the wizard during installation, you most likely have chosen to install the service already. If not you can of course install the service manually.
In order to manually install the service, you can use the Icinga PowerShell Framework and the provided Cmdlets provided. There are two commands available dealing with the download and installation.
Download the Service binary¶
At first we can run
Get-IcingaFrameworkServiceBinary to start the download wizard asking a bunch of questions. By default, the Wizard will download the
.zip archive directly from Github, you can however also specify a custom location.
Please ensure for custom locations to enter the full path to the
.zip file, like
Start the service wizard asking us questions about location and install destination:
$ServiceData = Get-IcingaFrameworkServiceBinary;
For a more automated approach you can skip the entire wizard by providing an answer to both the download url and installation question as argument:
$ServiceData = Get-IcingaFrameworkServiceBinary -FrameworkServiceUrl 'https://github.com/Icinga/icinga-powershell-service/releases/download/v1.0.0/icinga-service-v1.0.0.zip' -ServiceDirectory 'C:\Program Files\icinga-framework-service\';
Note: For the next step it is important that you store the output of
Get-IcingaFrameworkServiceBinary inside a variable for later usage, like
ServiceData in our example.
Install the service¶
Now as we downloaded the Service binary and placed it into the correct location in the step above, we can use
Install-IcingaFrameworkService for the actual installation. The most easiest part is to store the result of
Get-IcingaFrameworkServiceBinary into a variable, like we did in our example with
ServiceData. We can now simply access the content of
ServiceData and provide the arguments to our Cmdlet. In addition we will have to specify which user the service will be running with. This can either be a custom local/domain user or one of the default Windows service users
- NT AUTHORITY\NetworkService
- NT AUTHORITY\LocalService
- NT Authority\SYSTEM
Install-IcingaFrameworkService -Path $ServiceData.ServiceBin -User 'NT AUTHORITY\NetworkService';
Note: For default Windows service users the
Password argument is not required. This will only apply to local/domain users. Please note that
Password is a secure string and you will have to parse it like this. The most easiest way is to use the dialog box for entering credentials and then using the returned object as arguments:
$cred = Get-Credential; Install-IcingaFrameworkService -Path $ServiceData.ServiceBin -User $cred.UserName -Password $cred.Password;
As different method you could also use the Icinga custom Cmdlet
ConvertTo-IcingaSecureString for converting a
String to a
SecureString which might be handy for automated installations:
$SecurePassword = ConvertTo-IcingaSecureString 'my_secret_password'; Install-IcingaFrameworkService -Path $ServiceData.ServiceBin -User 'my_user' -Password $SecurePassword;
Important: For security reasons we do not recommend to use direct shell inputs on the PowerShell for entering the password. Please make always sure to use a method to make it impossible to read a password from the command line history!
For example you could use
Read-Host with the
$SecurePassword = Read-Host -Prompt 'Enter Service password' -AsSecureString; Install-IcingaFrameworkService -Path $ServiceData.ServiceBin -User 'my_user' -Password $SecurePassword;
Regardless of the steps above, if everything works properly the service is now installed onto the system with the name
Checking Service state¶
To validate if the installation was successful you can check if the service is installed and running by using
Status Name DisplayName ------ ---- ----------- Running icingapowershell Icinga PowerShell Service
Installing background daemons¶
As we are now finished with the service installation we can make use of it by registering background daemons.