community.windows.win_nssm – Install a service using NSSM
community.windows.win_nssm – Install a service using NSSM
Note
This plugin is part of the community.windows collection (version 1.2.0).
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 | Choices/Defaults | Comments |
---|---|---|
app_environment dictionary added in 1.2.0 of community.windows |
Key/Value pairs which will be added to the environment of the service application. | |
app_parameters string |
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. | |
app_rotate_bytes integer |
Default: 104858 |
NSSM will not rotate any file which is smaller than the configured number of bytes. |
app_rotate_online integer |
Default: 0 |
If set to 1, nssm can rotate files which grow to the configured file size limit while the service is running. |
app_stop_method_console integer |
Time to wait after sending Control-C. | |
app_stop_method_skip integer |
|
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(). |
application path |
The application binary to run as a service Required when state is | |
arguments string |
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.
| |
dependencies list / elements=string |
Service dependencies that has to be started to trigger startup, separated by comma. DEPRECATED, will be removed in a major release after | |
description string |
The description to set for the service. | |
display_name string |
The display name to set for the service. | |
executable path |
Default: "nssm.exe" |
The location of the NSSM utility (in case it is not located in your PATH). |
name string / required |
Name of the service to operate on. | |
password string |
Password to be used for service startup. DEPRECATED, will be removed in a major release after | |
start_mode string |
|
If
DEPRECATED, will be removed in a major release after |
state string |
|
State of the service on the system. Values |
stderr_file path |
Path to receive error output. | |
stdout_file path |
Path to receive output. | |
user string |
User to be used for service startup. DEPRECATED, will be removed in a major release after | |
working_directory path |
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 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)
© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/community/windows/win_nssm_module.html