From 6ff0e2e09d1e545d33e524bd12ed5f67ceabd3b7 Mon Sep 17 00:00:00 2001 From: Dennis Hoer Date: Sun, 28 Sep 2014 20:18:30 -0700 Subject: [PATCH] Merge TLDR into README --- README.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- TLDR.md | 70 -------------------------------------------- 2 files changed, 84 insertions(+), 73 deletions(-) delete mode 100644 TLDR.md diff --git a/README.md b/README.md index d0623ac..258ea5a 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,6 @@ [![Build Status](https://travis-ci.org/dhoer/chef-nssm.svg)](https://travis-ci.org/dhoer/chef-nssm) This cookbook installs the Non-Sucking Service Manager (http://nssm.cc), and exposes resources to `install` and `remove` Windows services. -Read [TLDR](https://github.com/dhoer/chef-nssm/blob/master/TLDR.md) for more details about usage, chefspec matchers, getting help, and contributing. ## Requirements @@ -21,12 +20,12 @@ Chef 11.14.2 and Ruby 1.9.3 or higher. Add `recipe[nssm]` to a run list. -### Examples +### Quick Start To install a Windows service: nssm 'service name' do - program 'C:\\Windows\\System32\\java.exe' + program 'C:\Windows\System32\java.exe' args '-jar C:/path/to/my-executable.jar' action :install end @@ -37,6 +36,88 @@ To remove a Windows service: action :remove end +### Using Parameters + +A parameter is a hash key representing the same name as the registry entry which controls the associated functionality. So, for example, the following sets the startup directory for a service: + + nssm 'service name' do + program 'C:\Windows\System32\java.exe' + args '-jar C:/path/to/my-executable.jar' + params( + AppDirectory: 'C:/path/to', + AppStdout: 'C:/path/to/log/service.log', + AppStderr: 'C:/path/to/log/error.log', + AppRotateFiles: 1 + ) + action :install + end + +### Arguments with Spaces + +Having spaces in `servicename`, `program` and `params` attributes is not a problem, but spaces in an argument is a different matter. + +When dealing with an argument containing spaces, surround it with [3 double quotes](http://stackoverflow.com/a/15262019): + + nssm 'service name' do + program 'C:\Program Files\Java\jdk1.7.0_67\bin\java.exe' + args '-jar """C:/path/with spaces to/my-executable.jar"""' + action :install + end + +When dealing with arguments requiring [interpolation](http://en.wikibooks.org/wiki/Ruby_Programming/Syntax/Literals#Interpolation) and it contains one or more arguments with spaces, then encapsulate the `args` string using `%()` notation and use `"""` around arguments with spaces: + + my_path_with_spaces = 'C:/path/with spaces to/my-executable.jar' + nssm 'service name' do + program 'C:\Program Files\Java\jdk1.7.0_67\bin\java.exe' + args %(-jar """#{my_path_with_spaces}""") + action :install + end + +### Attributes + +- `node['nssm']['src']` - This can either be a URI or a local path to nssm zip. +- `node['nssm']['sha256']` - SHA-256 checksum of the file. Chef will not download it if the local file matches the checksum. + +### Resource/Provider + +#### Actions + +- :install: Install a Windows service. +- :remove: Remove Windows service. + +#### Attribute Parameters + +- :servicename: Name attribute. The name of the Windows service. +- :program: The program to be run as a service. +- :args: String of arguments for the program. Optional +- :params: Hash of key value pairs where key represents associated registry entry. Optional +- :start: Start service after installing. Default: true + +## ChefSpec Matchers + +The NSSM cookbook includes custom [ChefSpec](https://github.com/sethvargo/chefspec) matchers you can use to test your own cookbooks that consume Windows cookbook LWRPs. + +Example Matcher Usage + + expect(chef_run).to install_nssm_service('service name').with( + :program 'C:\\Windows\\System32\\java.exe' + :args '-jar C:/path/to/my-executable.jar' + ) + +NSSM Cookbook Matchers + +- install_nssm_service(servicename) +- remove_nssm_service(servicename) + +## Getting Help + +- Ask specific questions on [Stack Overflow](http://stackoverflow.com/questions/tagged/chef-nssm). +- Report bugs and discuss potential features in [Github issues](https://github.com/dhoer/chef-nssm/issues). + +## Contributing + +Please refer to [CONTRIBUTING](https://github.com/dhoer/chef-nssm/blob/master/CONTRIBUTING.md). + ## License MIT - see the accompanying [LICENSE](https://github.com/dhoer/chef-nssm/blob/master/LICENSE.md) file for details. diff --git a/TLDR.md b/TLDR.md deleted file mode 100644 index 219edf6..0000000 --- a/TLDR.md +++ /dev/null @@ -1,70 +0,0 @@ -# TL;DR - -## Usage - -Advanced usage of NSSM. - -### Arguments with Spaces - -Having spaces in `servicename` and `program` attributes is not a problem, but spaces in an argument is a different matter. - -When dealing with an argument containing spaces, add [3 double quotes](https://stackoverflow.com/questions/7760545/cmd-escape-double-quotes-in-parameter/15262019#15262019?s=62228804c3f84fceb873ee30dd784161) `"""` around it: - - nssm 'service name' do - program 'C:\Program Files\Java\jdk1.7.0_67\bin\java.exe' - args '-jar """C:/path/with spaces to/my-executable.jar"""' - action :install - end - -When dealing with arguments requiring [interpolation](http://en.wikibooks.org/wiki/Ruby_Programming/Syntax/Literals#Interpolation) and contain an argument with spaces, then encapsulate `args` using `%{}` notation and use `"""` around arguments with spaces: - - my_path_with_spaces = 'C:/path/with spaces to/my-executable.jar' - nssm 'service name' do - program 'C:\Program Files\Java\jdk1.7.0_67\bin\java.exe' - args %{-jar """#{my_path_with_spaces}"""} - action :install - end - -### Attributes - -- `node['nssm']['src']` - This can either be a URI or a local path to nssm zip. -- `node['nssm']['sha256']` - SHA-256 checksum of the file. Chef will not download it if the local file matches the checksum. - -### Resource/Provider - -#### Actions - -- :install: Install a Windows service. -- :remove: Remove Windows service. - -#### Attribute Parameters - -- :servicename: Name attribute. The name of the Windows service. -- :program: The program to be run as a service. -- :args: String of arguments for the program. Optional -- :start: Start service after installing. Default: true - -## ChefSpec Matchers - -The NSSM cookbook includes custom [ChefSpec](https://github.com/sethvargo/chefspec) matchers you can use to test your own cookbooks that consume Windows cookbook LWRPs. - -Example Matcher Usage - - expect(chef_run).to install_nssm_service('service name').with( - :program 'C:\\Windows\\System32\\java.exe' - :args '-jar C:/path/to/my-executable.jar' - ) - -NSSM Cookbook Matchers - -- install_nssm_service(servicename) -- remove_nssm_service(servicename) - -## Getting Help - -- Ask specific questions on [Stack Overflow](http://stackoverflow.com/questions/tagged/chef-nssm). -- Report bugs and discuss potential features in [Github issues](https://github.com/dhoer/chef-nssm/issues). - -## Contributing - -Please refer to [CONTRIBUTING](https://github.com/dhoer/chef-nssm/blob/master/CONTRIBUTING.md).