1#!/usr/local/bin/python3.8
2# -*- coding: utf-8 -*-
3
4# Copyright: (c) 2015, Heyo
5# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
6
7DOCUMENTATION = r'''
8---
9module: win_nssm
10short_description: Install a service using NSSM
11description:
12    - Install a Windows service using the NSSM wrapper.
13    - NSSM is a service helper which doesn't suck. See U(https://nssm.cc/) for more information.
14requirements:
15    - "nssm >= 2.24.0 # (install via M(chocolatey.chocolatey.win_chocolatey)) C(win_chocolatey: name=nssm)"
16options:
17  name:
18    description:
19      - Name of the service to operate on.
20    type: str
21    required: true
22  state:
23    description:
24      - State of the service on the system.
25      - Values C(started), C(stopped), and C(restarted) are deprecated and will be removed on a major release after
26        C(2021-07-01). Please use the M(ansible.windows.win_service) module instead to start, stop or restart the service.
27    type: str
28    choices: [ absent, present, started, stopped, restarted ]
29    default: present
30  application:
31    description:
32      - The application binary to run as a service
33      - Required when I(state) is C(present), C(started), C(stopped), or C(restarted).
34    type: path
35  executable:
36    description:
37    - The location of the NSSM utility (in case it is not located in your PATH).
38    type: path
39    default: nssm.exe
40  description:
41    description:
42      - The description to set for the service.
43    type: str
44  display_name:
45    description:
46      - The display name to set for the service.
47    type: str
48  working_directory:
49    description:
50      - The working directory to run the service executable from (defaults to the directory containing the application binary)
51    type: path
52    aliases: [ app_directory, chdir ]
53  stdout_file:
54    description:
55      - Path to receive output.
56    type: path
57  stderr_file:
58    description:
59      - Path to receive error output.
60    type: path
61  app_parameters:
62    description:
63      - A string representing a dictionary of parameters to be passed to the application when it starts.
64      - DEPRECATED since v2.8, please use I(arguments) instead.
65      - This is mutually exclusive with I(arguments).
66    type: str
67  arguments:
68    description:
69      - Parameters to be passed to the application when it starts.
70      - This can be either a simple string or a list.
71      - This is mutually exclusive with I(app_parameters).
72    aliases: [ app_parameters_free_form ]
73    type: str
74  dependencies:
75    description:
76      - Service dependencies that has to be started to trigger startup, separated by comma.
77      - DEPRECATED, will be removed in a major release after C(2021-07-01), please use the
78        M(ansible.windows.win_service) module instead.
79    type: list
80  user:
81    description:
82      - User to be used for service startup.
83      - DEPRECATED, will be removed in a major release after C(2021-07-01), please use the
84        M(ansible.windows.win_service) module instead.
85    type: str
86  password:
87    description:
88      - Password to be used for service startup.
89      - DEPRECATED, will be removed in a major release after C(2021-07-01), please use the
90        M(ansible.windows.win_service) module instead.
91    type: str
92  start_mode:
93    description:
94      - If C(auto) is selected, the service will start at bootup.
95      - C(delayed) causes a delayed but automatic start after boot.
96      - C(manual) means that the service will start only when another service needs it.
97      - C(disabled) means that the service will stay off, regardless if it is needed or not.
98      - DEPRECATED, will be removed in a major release after C(2021-07-01), please use the
99        M(ansible.windows.win_service) module instead.
100    type: str
101    choices: [ auto, delayed, disabled, manual ]
102    default: auto
103  app_environment:
104    description:
105      - Key/Value pairs which will be added to the environment of the service application.
106    type: dict
107    version_added: 1.2.0
108  app_rotate_bytes:
109    description:
110      - NSSM will not rotate any file which is smaller than the configured number of bytes.
111    type: int
112    default: 104858
113  app_rotate_online:
114    description:
115      - If set to 1, nssm can rotate files which grow to the configured file size limit while the service is running.
116    type: int
117    choices:
118      - 0
119      - 1
120    default: 0
121  app_stop_method_console:
122    description:
123      - Time to wait after sending Control-C.
124    type: int
125  app_stop_method_skip:
126    description:
127      - To disable service shutdown methods, set to the sum of one or more of the numbers
128      - 1 - Don't send Control-C to the console.
129      - 2 - Don't send WM_CLOSE to windows.
130      - 4 - Don't send WM_QUIT to threads.
131      - 8 - Don't call TerminateProcess().
132    type: int
133    choices:
134      - 1
135      - 2
136      - 3
137      - 4
138      - 5
139      - 6
140      - 7
141      - 8
142      - 9
143      - 10
144      - 11
145      - 12
146      - 13
147      - 14
148      - 15
149seealso:
150  - module: ansible.windows.win_service
151notes:
152  - The service will NOT be started after its creation when C(state=present).
153  - Once the service is created, you can use the M(ansible.windowswin_service) module to start it or configure
154    some additionals properties, such as its startup type, dependencies, service account, and so on.
155author:
156  - Adam Keech (@smadam813)
157  - George Frank (@georgefrank)
158  - Hans-Joachim Kliemeck (@h0nIg)
159  - Michael Wild (@themiwi)
160  - Kevin Subileau (@ksubileau)
161  - Shachaf Goldstein (@Shachaf92)
162'''
163
164EXAMPLES = r'''
165- name: Install the foo service
166  community.windows.win_nssm:
167    name: foo
168    application: C:\windows\foo.exe
169
170# This will yield the following command: C:\windows\foo.exe bar "true"
171- name: Install the Consul service with a list of parameters
172  community.windows.win_nssm:
173    name: Consul
174    application: C:\consul\consul.exe
175    arguments:
176      - agent
177      - -config-dir=C:\consul\config
178
179# This is strictly equivalent to the previous example
180- name: Install the Consul service with an arbitrary string of parameters
181  community.windows.win_nssm:
182    name: Consul
183    application: C:\consul\consul.exe
184    arguments: agent -config-dir=C:\consul\config
185
186
187# Install the foo service, and then configure and start it with win_service
188- name: Install the foo service, redirecting stdout and stderr to the same file
189  community.windows.win_nssm:
190    name: foo
191    application: C:\windows\foo.exe
192    stdout_file: C:\windows\foo.log
193    stderr_file: C:\windows\foo.log
194
195- name: Configure and start the foo service using win_service
196  ansible.windows.win_service:
197    name: foo
198    dependencies: [ adf, tcpip ]
199    username: foouser
200    password: secret
201    start_mode: manual
202    state: started
203
204- name: Install a script based service and define custom environment variables
205  community.windows.win_nssm:
206    name: <ServiceName>
207    application: C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe
208    arguments:
209      - <path-to-script>
210      - <script arg>
211    app_environment:
212      AUTH_TOKEN: <token value>
213      SERVER_URL: https://example.com
214      PATH: "<path-prepends>;{{ ansible_env.PATH }};<path-appends>"
215
216- name: Remove the foo service
217  community.windows.win_nssm:
218    name: foo
219    state: absent
220'''
221