community.windows.win_nssm – Install a service using NSSM
Note
This plugin is part of the community.windows collection (version 1.8.0).
You might already have this collection installed if you are using the ansible
package.
It is not included in ansible-core
.
To check whether it is installed, run ansible-galaxy collection list
.
To install it, use: ansible-galaxy collection install community.windows
.
To use it in a playbook, specify: community.windows.win_nssm
.
Synopsis
Install a Windows service using the NSSM wrapper.
NSSM is a service helper which doesn’t suck. See https://nssm.cc/ for more information.
Requirements
The below requirements are needed on the host that executes this module.
nssm >= 2.24.0 # (install via chocolatey.chocolatey.win_chocolatey)
win_chocolatey: name=nssm
Parameters
Parameter |
Comments |
---|---|
Key/Value pairs which will be added to the environment of the service application. |
|
A string representing a dictionary of parameters to be passed to the application when it starts. DEPRECATED since v2.8, please use arguments instead. This is mutually exclusive with arguments. |
|
NSSM will not rotate any file which is smaller than the configured number of bytes. Default: 104858 |
|
If set to 1, nssm can rotate files which grow to the configured file size limit while the service is running. Choices:
Default: 0 |
|
Time to wait after sending Control-C. |
|
To disable service shutdown methods, set to the sum of one or more of the numbers 1 - Don’t send Control-C to the console. 2 - Don’t send WM_CLOSE to windows. 4 - Don’t send WM_QUIT to threads. 8 - Don’t call TerminateProcess(). Choices:
|
|
The application binary to run as a service Required when state is |
|
Parameters to be passed to the application when it starts. This can be either a simple string or a list. This is mutually exclusive with app_parameters. |
|
Service dependencies that has to be started to trigger startup, separated by comma. |
|
The description to set for the service. |
|
The display name to set for the service. |
|
The location of the NSSM utility (in case it is not located in your PATH). Default: “nssm.exe” |
|
Name of the service to operate on. |
|
Password to be used for service startup. This is not required for the well known service accounts and group managed service accounts. |
|
If
Choices:
|
|
State of the service on the system. Choices:
|
|
Path to receive error output. |
|
Path to receive output. |
|
User to be used for service startup. Group managed service accounts must end with Before |
|
The working directory to run the service executable from (defaults to the directory containing the application binary) |
Notes
Note
The service will NOT be started after its creation when
state=present
.Once the service is created, you can use the M(ansible.windowswin_service) module to start it or configure some additionals properties, such as its startup type, dependencies, service account, and so on.
See Also
See also
- ansible.windows.win_service
The official documentation on the ansible.windows.win_service module.
Examples
- name: Install the foo service
community.windows.win_nssm:
name: foo
application: C:\windows\foo.exe
# This will yield the following command: C:\windows\foo.exe bar "true"
- name: Install the Consul service with a list of parameters
community.windows.win_nssm:
name: Consul
application: C:\consul\consul.exe
arguments:
- agent
- -config-dir=C:\consul\config
# This is strictly equivalent to the previous example
- name: Install the Consul service with an arbitrary string of parameters
community.windows.win_nssm:
name: Consul
application: C:\consul\consul.exe
arguments: agent -config-dir=C:\consul\config
# Install the foo service, and then configure and start it with win_service
- name: Install the foo service, redirecting stdout and stderr to the same file
community.windows.win_nssm:
name: foo
application: C:\windows\foo.exe
stdout_file: C:\windows\foo.log
stderr_file: C:\windows\foo.log
- name: Configure and start the foo service using win_service
ansible.windows.win_service:
name: foo
dependencies: [ adf, tcpip ]
username: foouser
password: secret
start_mode: manual
state: started
- name: Install a script based service and define custom environment variables
community.windows.win_nssm:
name: <ServiceName>
application: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
arguments:
- <path-to-script>
- <script arg>
app_environment:
AUTH_TOKEN: <token value>
SERVER_URL: https://example.com
PATH: "<path-prepends>;{{ ansible_env.PATH }};<path-appends>"
- name: Remove the foo service
community.windows.win_nssm:
name: foo
state: absent
Authors
Adam Keech (@smadam813)
George Frank (@georgefrank)
Hans-Joachim Kliemeck (@h0nIg)
Michael Wild (@themiwi)
Kevin Subileau (@ksubileau)
Shachaf Goldstein (@Shachaf92)