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