{"_id":"@capturebridge/os-service","name":"@capturebridge/os-service","dist-tags":{"latest":"2.3.1"},"versions":{"2.3.1":{"name":"@capturebridge/os-service","version":"2.3.1","description":"Run Node.JS programs as native Operating System Services.","main":"index.js","directories":{"example":"example"},"dependencies":{"nan":"^2.25.0"},"contributors":[{"name":"Stephen Vickers","email":"stephen.vickers@nospaceships.com"},{"name":"NoSpaceships Ltd","email":"hello@nospaceships.com"}],"repository":{"type":"git","url":"git://github.com/nospaceships/node-os-service.git"},"keywords":["background-process","background-service","daemon","linux-daemon","linux-service","service","windows","windows-daemon","windows-service"],"author":{"name":"NoSpaceships Ltd","email":"hello@nospaceships.com"},"license":"MIT","scripts":{"install":"node-gyp rebuild"},"gypfile":true,"gitHead":"06da2a4d8ee9d2b89fd98dcf0f9bdafa09b3082e","_id":"@capturebridge/os-service@2.3.1","bugs":{"url":"https://github.com/nospaceships/node-os-service/issues"},"homepage":"https://github.com/nospaceships/node-os-service#readme","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-1Bxxy5fcPMyaCiFU2sKBPM/9inYlCVKF4YRl4n+YPhp6jlBLmq8t6T5xsds+Jbxw/ijB2Q1RGVn+PCDjfAa2eA==","shasum":"572c575b9fe2ba218b2c8445797bd6eec34ab6d0","tarball":"https://registry.npmjs.org/@capturebridge/os-service/-/os-service-2.3.1.tgz","fileCount":8,"unpackedSize":38595,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHxLJR6P+PiL9NERlwVJ0ni882MSI6QYqo2r1ZeAeomNAiAYl+RD2hq9NLxJYVeSCW5FQNs/tJz19HSz8CFCsBlm3g=="}]},"_npmUser":{"name":"capturebridge-bot","email":"npm@capturebridge.net"},"maintainers":[{"name":"capturebridge-bot","email":"npm@capturebridge.net"},{"name":"tpaul","email":"Tr@visPaul.me"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/os-service_2.3.1_1771710616884_0.40801347863918225"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-21T21:50:16.764Z","2.3.1":"2026-02-21T21:50:17.079Z","modified":"2026-02-21T21:50:17.350Z"},"maintainers":[{"name":"capturebridge-bot","email":"npm@capturebridge.net"},{"name":"tpaul","email":"Tr@visPaul.me"}],"description":"Run Node.JS programs as native Operating System Services.","homepage":"https://github.com/nospaceships/node-os-service#readme","keywords":["background-process","background-service","daemon","linux-daemon","linux-service","service","windows","windows-daemon","windows-service"],"repository":{"type":"git","url":"git://github.com/nospaceships/node-os-service.git"},"contributors":[{"name":"Stephen Vickers","email":"stephen.vickers@nospaceships.com"},{"name":"NoSpaceships Ltd","email":"hello@nospaceships.com"}],"author":{"name":"NoSpaceships Ltd","email":"hello@nospaceships.com"},"bugs":{"url":"https://github.com/nospaceships/node-os-service/issues"},"license":"MIT","readme":"\n# os-service\n\nThis module implements the ability to run a [Node.js][nodejs] based JavaScript\nprogram as a native Windows or Linux service.\n\nThis module is installed using [node package manager (npm)][npm]:\n\n    # This module contains C++ source code which will be compiled\n    # during installation on Windows platforms using node-gyp.  A\n    # suitable build chain must be configured on Windows platforms\n    # before installation.\n    \n    npm install os-service\n\nIt is loaded using the `require()` function:\n\n    var service = require (\"os-service\");\n\nA program can then be added, removed and run as a service:\n\n    service.add (\"my-service\");\n    \n    service.remove (\"my-service\");\n    \n    service.run (function () {\n        // Stop request received (i.e. a kill signal on Linux or from the\n        // Service Control Manager on Windows), so let's stop!\n        service.stop ();\n    });\n\n[nodejs]: http://nodejs.org \"Node.js\"\n[npm]: https://npmjs.org/ \"npm\"\n\n# Batch Service Creation\n\nTwo approaches can be taken when adding and removing services.\n\nIn the first approach a program can be responsible for adding, removing and\nstarting itself as a service.  This is typically achieved by supporting\nprogram arguments such as `--add`, `--remove`, and `--run`, and executing the\nappropriate action.\n\nThe following example adds the calling program as a service when called\nwith a `--add` parameter, and removes the created service when called with a\n`--remove` parameter:\n\n    if (process.argv[2] == \"--add\") {\n        service.add (\"my-service\", {programArgs: [\"--run\"]}, function(error){ \n           if (error)\n              console.trace(error);\n        });\n    } else if (process.argv[2] == \"--remove\") {\n        service.remove (\"my-service\", function(error){ \n           if (error)\n              console.trace(error);\n        });\n    } else if (process.argv[2] == \"--run\") {\n        service.run (function () {\n            service.stop (0);\n        });\n        \n        // Run service program code...\n    } else {\n        // Show usage...\n    }\n\nNote the `--run` argument passed in the `options` parameter to the\n`service.add()` function.  When the service is started using the Windows\nService Control Manager, or the Linux service management facilities,  the first\nargument to the program will be `--run`.  The above program checks for this and\nif specified runs as a service using the `service.run()` function.\n\nAlso note that neither the node binary or the programs fully qualified path\nare specified.  These parameters are automatically calculated it not\nspecified.  Refer to the `service.add()` function description for details\nabout how this works.\n\nIn the second approach a dedicated service management program can be\nresponsible for adding and removing many services in batch.  The program\nadding and removing services is not a service itself, and would never call\nthe `service.run()` function.\n\nThe following example adds or removes number of services:\n\n    if (program.argv[2] == \"--add\") {\n        service.add (\"service1\", {programPath: \"c:\\example\\svc1.js\",\n            function(error) { \n                if (error) {\n                    console.trace(error);\n                } else {\n                    service.add (\"service2\", {programPath: \"c:\\example\\svc2.js\",\n                        function(error) { \n                            if (error) {\n                                console.trace(error);\n                            }\n                        });\n                }\n            });\n    } else {\n        service.remove (\"service2\", function(error) { \n            if (error) {\n                console.trace(error);\n            } else {\n                service.remove (\"service1\", function(error) { \n                    if (error) {\n                        console.trace(error);\n                    }\n                });\n            }\n        });\n    }\n\nNote that unlike the previous example the `--run` argument is not passed in\nthe `options` parameter to the `service.add()` function.  Since each service\nprogram does not add or remove itself as a service it only needs to run, and\nas such does not need to be told to so.\n\nAlso note that the `programPath` argument is passed in the options parameter\nto the `service.add()` function, to specify the fully qualified path to each\nservice program - which would otherwise default to the service management\nprogram adding the services.\n\nEach of the service programs can simply start themselves as services using the\nfollowing code:\n\n    service.run (function () {\n        service.stop (0);\n    });\n    \n    // Run service program code...\n\n# Running Service Programs\n\nWhen a service program starts it can always call the `service.run()` function\nregardless of whether it is started at the console, by the Windows Service\nControl Manager, or the Linux service management facilities.\n\nOn Windows, when the `service.run()` function is called this module will\nattempt to connect to the Windows Service Control Manager so that control\nrequests can be received - so that the service can be stopped.  When starting a\nprogram at the console an attempt to connect to the Windows Service Control\nManager will fail.  In this case the `service.run()` function will assume the\nprogram is running at the console and silently ignore this error.\n\nOn Linux, services started at the console will run in the foreground, this\nallows command sequences such as `CTRL+C` to be used, e.g. during development.\nWhen Linux services are started using the Linux service management facilities,\ni.e. `service my-service start`, they can be stopped using the signals `SIGINT`\nand `SIGTERM`, or again using the Linux service management facilities, i.e.\n`service my-service stop`.\n\nThis behaviour results in a program which can be run either at the console, the\nWindows Service Control Manager, or the Linux service management facilities\nwith no change.\n\n# Current Working Directory\n\nUpon starting the current working directory of a service program will be\nplatform specific the , e.g. the `\"%windir%\\system32\"` directory on Windows.\nService programs need to consider this when working with relative directory and\nfile paths.\n\nThis path will most likely be different when running the same program at the\nconsole, so a service program may wish to change the current working\ndirectory to a more suitable location using the `process.chdir()` function to\navoid different behaviour between the two methods of starting a program.\n\n# Using This Module\n\nThis module attempts to behave in exactly the same way on Windows and Linux\nplatforms - at least the API is exactly the same for both platforms both from\na service management and service running perspective.\n\nOn Windows platforms the Windows Service Control Manager WIN32 API is used to\nmanage services.  On Linux platforms a `systemd` unit is created if it is\navailable, otherwise the `chkconfig` command is used.  If `chkconfig` is not\navailable the `update-rc.d` command is tried instead.\n\n## service.add (name, [options], cb)\n\nThe `add()` function adds a service.\n\nThe `name` parameter specifies the name of the created service.  The optional\n`options` parameter is an object, and can contain the following items:\n\n * `displayName` - The services display name, defaults to the `name` parameter\n   - this parameter will be used on Windows platforms only\n * `nodePath` - The fully qualified path to the node binary used to run the\n   service (i.e. `c:\\Program Files\\nodejs\\node.exe`, defaults to the value of\n   `process.execPath`\n * `nodeArgs` - An array of strings specifying parameters to pass to\n   `nodePath`, defaults to `[]`\n * `programPath` - The program to run using `nodePath`, defaults to the value\n   of `process.argv[1]`\n * `programArgs` - An array of strings specifying parameters to pass to\n   `programPath`, defaults to `[]`\n * `runLevels` - An array of numbers specifying Linux run-levels at which\n   the service should be started for Linux platforms, defaults to\n   `[2, 3, 4, 5]`, this is only used when `chkconfig` or `update-rc.d` is used\n\tto install a service\n * `username` - For Windows platforms a username and password can be specified,\n   the service will be run using these credentials when started, see the\n   `CreateService()` functions [win32 API documentation][createservice] for\n   details on the format of the username, on all other platforms this parameter\n   is ignored\n * `password` - See the `username` parameter\n * `systemdWantedBy` - For when systemd will be used a target can be specified\n   for the `WantedBy` attribute under the `[Install]` section in the generated\n   systemd unit file, defaults to `multi-user.target`\n * `dependencies` - AN array of strings specifying other services this service\n   depends on, this is optional\n\n[createservice]: https://msdn.microsoft.com/en-us/library/windows/desktop/ms682450(v=vs.85).aspx \"CreateService()\"\n\nThe service will be set to automatically start at boot time, but not started.\nThe service can be started using the `net start \"my-service\"` command on\nWindows and `service my-service start` on Linux.\n\nThe `cb` callback function is called once the service has been added. The\nfollowing arguments will be passed to the callback function:\n\n * `error` - Instance of the `Error` class, or `null` if no error occurred\n\nThe following example installs a service named `my-service`, it explicitly\nspecifies the services display name, and specifies a number of parameters to\nthe program:\n\n    var options = {\n        displayName: \"MyService\",\n        programArgs: [\"--server-port\", 8888],\n        username: \".\\Stephen Vickers\",\n        password: \"MyPassword :)\"\n    };\n    \n    service.add (\"my-service\", options, function(error) {\n        if (error)\n            console.trace(error);\n    });\n\n## service.remove (name, cb)\n\nThe `remove()` function removes a service.\n\nThe `name` parameter specifies the name of the service to remove.  This will\nbe the same `name` parameter specified when adding the service.\n\nThe service must be in a stopped state for it to be removed.  The\n`net stop \"my-service\"` command can be used to stop the service on Windows and\nthe `service my-service stop` on Linux before it is to be removed.\n\nThe `cb` callback function is called once the service has been removed. The\nfollowing arguments will be passed to the callback function:\n\n * `error` - Instance of the `Error` class, or `null` if no error occurred\n\nThe following example removes the service named `my-service`:\n\n    service.remove (\"my-service\", function(error) {\n        if (error)\n            console.trace(error);\n    });\n\n## service.run (callback)\n\nThe `run()` function will attempt to run the program as a service.\n\n**NOTE** When run the service will NOT make any changes to the `process.stdout`\nand `process.stderr` streams.  Users are required to utilise whatever logging\nmodules they require to managing process logging and its destination.  Older\nversions of this module (versions before 2.0.0) would support re-directing\nthese streams to a specific writeable stream, support for that was removed in\nversion 2.0.0.\n\nThe `callback` function will be called when the service receives a stop request,\ne.g. because the Windows Service Controller was used to send a stop request to\nthe service, or a `SIGTERM` signal was received.\n\nThe program should perform cleanup tasks and then call the `service.stop()`\nfunction.\n\nThe following example starts a program as a service:\n    \n    service.run (function () {\n        service.stop ();\n    });\n\n## service.stop ([rcode])\n\nThe `stop()` function will cause the service to stop, and the calling program\nto exit.\n\nOnce the service has been stopped this function will terminate the program by\ncalling the `process.exit()` function, passing to it the `rcode` parameter\nwhich defaults to `0`.  Before calling this function ensure the program has\nfinished performing cleanup tasks.\n\n**BE AWARE, THIS FUNCTION WILL NOT RETURN.**\n\nThe following example stops the calling program specifying a return code of\n`0`, the function will not return:\n\n    service.run (function () {\n        service.stop (0);\n    });\n\n# Example Programs\n\nExample programs are included under the modules `example` directory.\n\n# Changes\n\n## Version 1.0.0 - 30/12/2014\n\n * Initial release\n\n## Version 1.0.1 - 03/03/2015\n\n * Support Linux platforms which don't have the start-stop-daemon program\n \n## Version 1.0.2 - 30/03/2015\n\n * Linux start/stop link under `/etc/rcN.d` directories are not removed\n\n## Version 1.0.3 - 22/09/2015\n\n * Host repository on GitHub\n\n## Version 1.1.0 - 09/10/2015\n\n * Migrate C++ addon code to use the Native Abstractions for Node framework\n * Add missing shebang line '#!' to start/stop script template\n * Not possible to specify run levels for Linux start/stop script (added new\n   `runLevels` item to the `options` parameter to the `add()` function\n\n## Version 1.1.1 - 08/02/2016\n\n * Remove extraneous semicolon from the README.md file\n\n## Version 1.2.0 - 29/02/2016\n\n * On Windows platforms allow users to specify a username/password with which\n   a service should be run, the `username` and `password` options parameters\n   were added to the `add()` function\n\n## Version 1.3.0 - 15/05/2016\n\n * Require nan 2.3.x to support node version 6\n\n## Version 1.4.0 - 20/03/2017\n\n * Support Linux systemd\n\n## Version 1.4.1 - 27/03/2017\n\n * The systemd install doesn't work because of typo in directory name in\n   index.js\n\n## Version 1.4.2 - 14/07/2017\n\n * Service not automatically started on boot when under the systemd service\n   (added `WantedBy` attribute to generated systemd unit)\n * Umask not set in system 5 init script\n\n## Version 1.5.0 - 06/01/2018\n\n * Address warnings for 'v8::Value::ToUint32 was declared deprecated'\n * Override the stdout/stderr handles instead of using the deprecated\n   `__defineGetter__()` function\n * Specify dependancies when adding a service\n\n## Version 2.0.0 - 12/02/2018\n\n * Remove support to override stdout/stderr with a logstream (let users use\n   their required/own logging modules) - the run() function now only accepts\n   one argument whereas previously this was either two or three\n\n## Version 2.1.0 - 02/05/2018\n\n * Support Node.js 10\n\n## Version 2.1.2 - 06/06/2018\n\n * Set NoSpaceships Ltd to be the owner and maintainer\n\n## Version 2.1.3 - 07/06/2018\n\n * Remove redundant sections from README.md\n\n## Version 2.2.0 - 02/01/2020\n\n * Support Node.js 12.x\n\n## Version 2.3.0 - 08/01/2024\n\n * Support Node.js 20.x\n\n# License\n\nCopyright (c) 2018 NoSpaceships Ltd <hello@nospaceships.com>\n\nCopyright (c) 2014 Stephen Vickers <stephen.vickers.sv@gmail.com>\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n","readmeFilename":"README.md","_rev":"1-87b1263b0333f601d81f699b694d995b"}