NAME
Win32::ServiceManager - Manage Windows Services
VERSION
version 0.001000
SYNOPSIS
use Win32::ServiceManager;
use Path::Class 'file';
my $dir = file(__FILE__)->parent->absolute;
my $sc = Win32::ServiceManager->new(
nssm_path => $dir->file(qw( cgi exe nssm.exe ))->stringify,
);
$sc->create_service(
name => 'LynxWebServer01',
display => 'Lynx Web Server 1',
description => 'Handles Web Requests on port 3001',
command =>
$dir->file(qw( App script server.pl ))->stringify .
' -p 3001',
);
$sc->start_service('LynxWebServer01', { use_sc => 0 });
$sc->stop_service('LynxWebServer01');
$sc->delete_service('LynxWebServer01');
METHODS
create_service
$sc->create_service(
name => 'GRWeb1',
display => 'Giant Robot Web Worker 1',
description => 'Handles Giant Robot Web Requests on port 3001',
use_perl => 1,
use_nssm => 1,
command => 'C:\code\GR\script\server.pl -p 3001',
depends => [qw(MSSQL Apache2.4)],
);
Takes a hash of the following arguments:
* "name"
(required) The name of the service (which is used when doing a "sc
start" etc.)
* "use_nssm"
(defaults to the value of use_nssm_default) Set this to start your
service with "nssm"
* "use_perl"
(defaults to the value of use_perl_default) Set this to create perl
services. Uses $^X. If for some reason you want to use a different
perl you will have to set "use_perl" to false.
* "display"
(required) The display name to give the service
* "description"
(optional) The description to give the service.
* "command"
(required) The command that is effectively your service
* "args"
(optional) Arguments that get passed to the command above. XXX: do
these even make sense?
* "depends"
(optional) List of service names that must be started for your service
to function. You may either pass a string or an array ref. A string
gets passed on directly, the array reference gets properly joined
together.
Note: there are many options that "sc" can use to create and modify
services. I have taken the few that we use in my project and forced the
rest upon you, gentle user. For example, whether you like it or not
these services will restart on failure and start automatically on boot.
I am completely willing to add more options, but in 4 distinct projects
we have never needed more than the above. Patches Welcome!
start_service
$sc->start_service('GRWeb1', { use_sc => 1 });
Starts a service with the passed name. The second argument is an
optional hashref with the following options:
* "usc_sc"
(defaults to the value of "use_sc_default") Set this to false if you
want to block until the service starts.
stop_service
$sc->stop_service('GRWeb1', { use_sc => 1 });
Stops a service with the passed name. The second argument is an optional
hashref with the following options:
* "usc_sc"
(defaults to the value of "use_sc_default") Set this to false if you
want to block until the service stops.
restart_service
$sc->restart_service('GRWeb1', { use_sc => 1 });
Stops and starts a service with the passed name. The second argument is
an optional hashref with the following options:
* "usc_sc"
(defaults to the value of "use_sc_default") Set this to false if you
want to block until the service starts. (Note that the blocking until
the service has stopped is required.)
ATTRIBUTES
use_nssm_default
The default value of "use_nssm" for the "create_service" method.
use_perl_default
The default value of "use_perl" for the "create_service" method.
use_sc_default
Set this to true (default) to use "sc" to start or stop services. "sc"
is faster, but asyncronous. Sometimes using ye olde "net" is better as
it allows for restarts, for example.
nssm_path
Set this to the path to nssm (default is just 'nssm.exe').
nssm
nssm <http://nssm.cc> is a handy service wrapper for Windows. Instead of
adding hooks directly to your program to handly Windows service signals,
this program runs your program for you and intercepts the signals and
acts appropriately. It is open source and clocks in at less than two
megabytes of RAM. The code is at "git://git.nssm.cc/nssm/nssm.git".
PRO-TIPS
The best way to use this module is to subclass it for your software. So
for example we have a subclass that looks something like the following:
package Lynx::ServiceManager
use Moo;
extends 'Win32::ServiceManager';
our $DIR = file(__FILE__)->parent->absolute;
sub create_catalyst_service {
my ($self, $i) = @_;
$self->create_service(
name => "LynxWebServer$i",
display => "Lynx Web Server $i",
description => 'Handles Web Requests on port 3001',
command =>
$dir->file(qw( App script server.pl ))->stringify .
" -p 300$i",
);
}
sub start_catalyst_service { $_[0]->start_service("LynxWebServer$_[1]", $_[2]) }
...
The above makes it very easy for use to start, stop, add, and remove
catalyst services.
CAVEAT LECTOR
I have used this at work and am confident in it, but it has only been
used on Windows Server 2008. The tests can do no better than ensure the
generated strings are as expected, instead of ensuring that a service
was correctly created or started or whatever.
Additionally, in my own work when I get an error from "sc" I just report
it and move forward. Because of this I have done very little to make
exceptions useful. I am open to making them objects but again, I do not
need that myself, so Patches Welcome!
AUTHOR
Arthur Axel "fREW" Schmidt <frioux+cpan@gmail.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2013 by Arthur Axel "fREW" Schmidt.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.