Run Icinga Agent as other Service User¶
The Icinga PowerShell Framework is shipping wish a bunch of Cmdlets to manage the Icinga Agent in a very easy way. This includes changing the current assigned Service User of the Icinga Agent to another one.
Note: Before using any of the commands below you will have to initialize the Icinga PowerShell Framework inside a new PowerShell instance with icinga -Shell
Getting started¶
There are many reasons to run the Icinga Agent as a different user than the NT AUTHORITY\NetworkService user. One could be additional permissions required, another could be to run the Icinga Agent as own independent user which is entirely managed by your Active Directory or locally available.
For easier integration the Icinga PowerShell Framework is providing the Cmdlet Set-IcingaServiceUser.
This Cmdlet ships with 4 arguments which not all of them are mandatory:
| Argument | Mandatory | Type | Description |
|---|---|---|---|
| User | * | String | The name of the user the Icinga Agent should run with. Example: NT AUTHORITY\NetworkService, mydomain\icinga, icinga |
| Password | SecureString | If the defined user is requiring a password authentication, you define it as SecureString. This is not required for system users like NT AUTHORITY\NetworkService or NT AUTHORITY\SYSTEM |
|
| Service | String | The name of the service you want to modify. By default it is already set to icinga2 |
|
| SetPermission | Switch | If the argument is set required permissions will be set. This includes directory permissions and the permissions for users to be allowed to run as service |
Changing the Service User¶
Now as we are aware on how our Cmdlet Set-IcingaServiceUser is working, we can use it to modify our service user.
Example 1: Change Service User to LocalSystem¶
Our first example will simply change the service user from NT AUTHORITY\NetworkService to NT AUTHORITY\SYSTEM:
Set-IcingaServiceUser -User 'NT AUTHORITY\SYSTEM' -SetPermission;
[Notice]: The Icinga Service User already has permission to run as service
[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writable by the Icinga Service User "NT AUTHORITY\SYSTEM"
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "NT AUTHORITY\SYSTEM"
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "NT AUTHORITY\SYSTEM"
[Notice]: Service User successfully updated
As we have set the argument -SetPermission, all directory and service permissions have been granted. As you can see the user already had permission to run as service which means no modification was done there.
Example 2: Change Service User to local user with password¶
The most common requirement will be to set the Icinga Agent Service User to either a local or domain user. This will how ever require the usage of the -Password argument, which is a SecureString which can not simply be parsed.
Of course the Framework provides the Cmdlet ConvertTo-IcingaSecureString which will properly secure a regular String into a SecureString, might how ever not be secure enough for most environments. It will depend on how you apply the configuration.
To make things easier and we only require it locally and have not many machines to deploy, we can use the Windows Get-Credential Cmdlet to assist us. This will pop up a promt on where we can enter the UserName and Password:
$cred = Get-Credential -Message 'User credentials for icinga2 service:';
Set-IcingaServiceUser -User $cred.UserName -Password $cred.Password;
In case we leave the -SetPermission argument aside, we simply get the update notification:
[Notice]: Service User successfully updated
If we how ever run our Cmdlet Test-IcingaAgent (which is described here), we will receive some errors:
[Failed]: The specified user "icinga" is not allowed to run as service
[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writable by the Icinga Service User "icinga"
[Failed]: Directory "C:\ProgramData\icinga2\var" is not accessible by the Icinga Service User "icinga"
\_ Please run the following command to fix this issue: Set-IcingaAcl -Directory 'C:\ProgramData\icinga2\var'
To simply resolve this, we can run the command from above again but this time with the -SetPermission argument:
$cred = Get-Credential -Message 'User credentials for icinga2 service:';
Set-IcingaServiceUser -User $cred.UserName -Password $cred.Password -SetPermission;
[Passed]: The specified user "icinga" is allowed to run as service
[Passed]: Directory "C:\ProgramData\icinga2\etc" is accessible and writable by the Icinga Service User "icinga"
[Passed]: Directory "C:\ProgramData\icinga2\var" is accessible and writable by the Icinga Service User "icinga"
[Passed]: Directory "C:\Program Files\WindowsPowerShell\Modules\icinga-powershell-framework\cache" is accessible and writable by the Icinga Service User "icinga"
[Notice]: Service User successfully updated
The same procedure applies to domain specific users. All you have to do is to provide the domain before the Username:
mydomain\Username