node-windows

# node-windows This library can be used to install/start/stop/uninstall Node scripts as Windows background services for **production** environments. This is not a tool for developing applications, it is a tool for releasing them. This tool generates an executable that will run your app with whichever version of Node.js is installed on the computer. See [node-mac](http://github.com/coreybutler/node-mac) and [node-linux](http://github.com/coreybutler/node-linux) if you need to support those operating systems. [Tweet me (@goldglovecb)](http://twitter.com/goldglovecb) if you need me. ## Sponsors

## Overview The following features are available in node-windows: - **Service Management**: Run Node.js scripts as native Windows services. Includes monitoring. - **Event Logging**: Create logs in the Event log. - **Commands**: - _Elevated Permissions_: Run a command with elevated privileges (may prompt user for acceptance) - _Sudo_: Run an `exec` command as a sudoer. - _Identify Administrative Privileges_: Determines whether the current user has administrative privileges. - _List Tasks_: A method to list running windows tasks/services. - _Kill Task_: A method to kill a specific windows service/task (by PID). ## Installation The recommended way to install node-windows is with npm, using the global flag: `npm install -g node-windows` Then, in your project root, run: `npm link node-windows` However; it is possible to use node-windows without the global flag (i.e. install directly into the project root). More details regarding why this is not the recommended approach are available throughout this Readme. ## NO NATIVE MODULES Using native node modules on Windows can suck. Most native modules are not distributed in a binary format. Instead, these modules rely on `npm` to build the project, utilizing [node-gyp](https://github.com/TooTallNate/node-gyp). This means developers need to have Visual Studio (and potentially other software) installed on the system, just to install a native module. This is portable, but painful... mostly because Visual Studio itself is over 2GB. **node-windows does not use native modules.** There are some binary/exe utilities, but everything needed to run more complex tasks is packaged and distributed in a readily usable format. So, no need for Visual Studio... at least not for this module. --- # Windows Services node-windows has a utility to run Node.js scripts as Windows services. Please note that like all Windows services, creating one requires administrative privileges. To create a service with node-windows, prepare a script like: ```js var Service = require('node-windows').Service; // Create a new service object var svc = new Service({ name:'Hello World', description: 'The nodejs.org example web server.', script: 'C:\\path\\to\\helloworld.js', nodeOptions: [ '--harmony', '--max_old_space_size=4096' ] //, workingDirectory: '...' //, allowServiceLogon: true }); // Listen for the "install" event, which indicates the // process is available as a service. svc.on('install',function(){ svc.start(); }); svc.install(); ``` The code above creates a new `Service` object, providing a pretty name and description. The `script` attribute identifies the Node.js script that should run as a service. Upon running this, the script will be visible from the Windows Services utility. The `Service` object emits the following events: - _install_ - Fired when the script is installed as a service. - _alreadyinstalled_ - Fired if the script is already known to be a service. - _invalidinstallation_ - Fired if an installation is detected but missing required files. - _uninstall_ - Fired when an uninstallation is complete. - _alreadyuninstalled_ - Fired when an uninstall is requested and no installation exists. - _start_ - Fired when the new service is started. - _stop_ - Fired when the service is stopped. - _error_ - Fired in some instances when an error occurs. In the example above, the script listens for the `install` event. Since this event is fired when a service installation is complete, it is safe to start the service. Services created by node-windows are similar to most other services running on Windows. They can be started/stopped from the windows service utility, via `NET START` or `NET STOP` commands, or even managed using the sc utility. ### Command-line Options It may be desired to specify command-line switches to your script. You can do this by setting the `scriptOptions` within the service config: ```js var svc = new Service({ name:'Hello World', description: 'The nodejs.org example web server.', script: 'C:\\path\\to\\helloworld.js', scriptOptions: '-c C:\\path\\to\\somewhere\\special -i' }); ``` ### Environment Variables Sometimes you may want to provide a service with static data, passed in on creation of the service. You can do this by setting environment variables in the service config, as shown below: ```js var svc = new Service({ name:'Hello World', description: 'The nodejs.org example web server.', script: 'C:\\path\\to\\helloworld.js', env: { name: "HOME", value: process.env["USERPROFILE"] // service is now able to access the user who created its' home directory } }); ``` You can also supply an array to set multiple environment variables: ```js var svc = new Service({ name:'Hello World', description: 'The nodejs.org example web server.', script: 'C:\\path\\to\\helloworld.js', env: [{ name: "HOME", value: process.env["USERPROFILE"] // service is now able to access the user who created its' home directory }, { name: "TEMP", value: path.join(process.env["USERPROFILE"],"/temp") // use a temp directory in user's home directory }] }); ``` ### Node Executable Path There are times when you may want to specify a specific `node` executable to use to run your script. You can do this by setting the `execPath` in the service config, as shown below: ```js var svc = new Service({ name:'Hello World', description: 'The nodejs.org example web server.', script: 'C:\\path\\to\\helloworld.js', execPath: 'C:\\path\\to\\specific\\node.exe' }); ``` ### User Account Attributes If you need to specify a specific user or particular credentials to manage a service, the following attributes may be helpful. The `user` attribute is an object with three keys: `domain`,`account`, and `password`. This can be used to identify which user the service library should use to perform system commands. By default, the domain is set to the local computer name, but it can be overridden with an Active Directory or LDAP domain. For example: **app.js** ```js var Service = require('node-windows').Service; // Create a new service object var svc = new Service({ name:'Hello World', script: require('path').join(__dirname,'helloworld.js'), //, allowServiceLogon: true }); svc.logOnAs.domain = 'mydomain.local'; svc.logOnAs.account = 'username'; svc.logOnAs.password = 'password'; ... ``` Both the account and password must be explicitly defined if you want the service module to run commands as a specific user. By default, it will run using the user account that launched the process (i.e. who launched `node app.js`). If you want to instruct winsw to allow service account logins, specify `allowServiceLogon: true`. This is disabled by default since some users have experienced issues running this without service logons. The other attribute is `sudo`. This attribute has a single property called `password`. By supplying this, the service module will attempt to run commands using the user account that launched the process and the password for that account. This should only be used for accounts with administrative privileges. **app.js** ```js var Service = require('node-windows').Service; // Create a new service object var svc = new Service({ name:'Hello World', script: require('path').join(__dirname,'helloworld.js') }); svc.sudo.password = 'password'; ... ``` ### Depending on other services The service can also be made dependant on other Windows services. ```js var svc = new Service({ name:'Hello World', description: 'The nodejs.org example web server.', script: 'C:\\path\\to\\helloworld.js', dependsOn: ["serviceA"] }); ``` ### Cleaning Up: Uninstall a Service Uninstalling a previously created service is syntactically similar to installation. ```js var Service = require('node-windows').Service; // Create a new service object var svc = new Service({ name:'Hello World', script: require('path').join(__dirname,'helloworld.js') }); // Listen for the "uninstall" event so we know when it's done. svc.on('uninstall',function(){ console.log('Uninstall complete.'); console.log('The service exists: ',svc.exists); }); // Uninstall the service. svc.uninstall(); ``` The uninstall process only removes process-specific files. **It does NOT delete your Node.js script!** ### What Makes node-windows Services Unique? Lots of things! **Long Running Processes & Monitoring:** The built-in service recovery for Windows services is fairly limited and cannot easily be configured from code. Therefore, node-windows creates a wrapper around the Node.js script. This wrapper is responsible for restarting a failed service in an intelligent and configurable manner. For example, if your script crashes due to an unknown error, node-windows will attempt to restart it. By default, this occurs every second. However; if the script has a fatal flaw that makes it crash repeatedly, it adds unnecessary overhead to the system. node-windows handles this by increasing the time interval between restarts and capping the maximum number of restarts. **Smarter Restarts That Won't Pummel Your Server:** Using the default settings, node-windows adds 25% to the wait interval each time it needs to restart the script. With the default setting (1 second), the first restart attempt occurs after one second. The second occurs after 1.25 seconds. The third after 1.56 seconds (1.25 increased by 25%) and so on. Both the initial wait time and the growth rate are configuration options that can be passed to a new `Service`. For example: ```js var svc = new Service({ name:'Hello World', description: 'The nodejs.org example web server.', script: 'C:\\path\\to\\helloworld.js', wait: 2, grow: .5 }); ``` In this example, the wait period will start at 2 seconds and increase by 50%. So, the second attempt would be 3 seconds later while the fourth would be 4.5 seconds later. **Don't DOS Yourself!** Repetitive recycling could potentially go on forever with a bad script. To handle these situations, node-windows supports two kinds of caps. Using `maxRetries` will cap the maximum number of restart attempts. By default, this is unlimited. Setting it to 3 would tell the process to no longer restart a process after it has failed 3 times. Another option is `maxRestarts`, which caps the number of restarts attempted within 60 seconds. For example, if this is set to 3 (the default) and the process crashes/restarts repeatedly, node-windows will cease restart attempts after the 3rd cycle in a 60 second window. Both of these configuration options can be set, just like `wait` or `grow`. Finally, an attribute called `abortOnError` can be set to `true` if you want your script to **not** restart at all when it exits with an error. ### How Services Are Made node-windows uses the [winsw](https://github.com/kohsuke/winsw) utility to create a unique `.exe` for each Node.js script deployed as a service. A directory called `daemon` is created and populated with `myappname.exe` and `myappname.xml`. The XML file is a configuration for the executable. Additionally, `winsw` will create some logs for itself in this directory (which are viewable in the Event log). The `myappname.exe` file launches the node-windows wrapper, which is