NAME
Sys::Manage::Cmd - Systems management command volley
SYNOPSIS
- Command line script
-
use Sys::Manage::Cmd; my $s =Sys::Manage::Cmd->new(); # Script associations (see also embedded in source): $s->{-assoc}->{'.ftp'}=sub{['ftp','-n','-s:loginfile','!elem!','<',$_[1]->[0]]}; # Target collections: $s->{-target}->{'all'} =[1,2,3,4,5,6]; # Target branches: $s->{-branch}->{1} =[1,2]; $s->{-branch}->{2} =[3,4]; $s->{-branch}->{3} =[5,6]; # Command-line setup / loop: $s->set([@ARGV]); # Command assignments: #$s->set(-k=>'assign', -o=>'b', -i=>0, -ping=>1); #$s->execute(-a=>'assignment name', -t=>[targets], -cline=>[command line]); #... # Command line execution: $s->set(-k=>'cmd', -o=>'b', -i=>0, -ping=>0); $s->execute([@ARGV]);
- Command line
-
script -option -option... target command-line script -option... -ttarget... command-line script cmdfile|regask|logask|cmdstat...
- Examples of command line
-
script all dir !elem! script -ob -tall dir !elem! script -rPrevId -tall dir !elem! script -aTest -tall dir !elem! script -l10 -tall dir !elem! script regask -1day errors script logask -1day pids
- Options of command line
-
(see also
-cline
and-c
,-i
,-k
,-l
,-o
,-r
,-t
,-u
,-x
,-v
,-g
)-kNameSpace - kind (namespace) of command -rCommandId - redo command id (used also inside '-l'); or switch (for '-a') -aAssignName - assignment name, to use as command id -lPauseSecs - loop with pause before each subsequent redo -lg... - ... for pings usuccessful only -lv, -lw... - ... console 'v'erbose or 'w'indowed subsequent turns -o(s|c|b) - order of execution: 's'equental 'c'oncurrent 'b'ranched (concurrent branches) -tTargetName - target, may be several '-t', instead of positional argument -xTargetExcl - exclusion from target list, may be several '-x' -cCompleteName - add summary execution of scriptic command using this target -c - 'complete' is default target for summary execution -uUser:pswd - user name and password for target -g - ping target before command, also use -gPingTimeout -gx - exclude unsuccessful targets sequentially -i - ignore exit code -v(0|1|2) - verbosity level -vc... - ... cmdfile rows include -vt... - ... date-time include
- Embedded commands
-
(see also
-cline
and-assoc
)script.ext - interpreting of scripts alike '.pl', '.bat', '.ftp', '.rdo.*' rcmd, rdo, - commands to remote nodes using fput, fget, Sys::Manage::Conn mput, mget (!elem!, !user!, !pswd! substitutions not needed) cmdfile - evaluate command lines file or Perl script using Sys::Manage::CmdFile regask - display registration file system filtered with condition: 'all', 'dir's, 'pid's, 'err's, 'warn's and errs, expression logask - display '-log' filtered with condition: 'all', 'pid's, 'err's, 'warn's and errs, expression cmdstat - display current status using 'logask', deprecated !elem!, < - target element and source file substitutions !user!, !pswd! - user name and password substitutions !log! - log filesystem name substitution
- Embedding command line
-
(see also
ENVIRONMENT
andSLOTS
)if (!defined($ENV{SMELEM}) # command volley: || ($ENV{SMELEM} eq '')) { system($^X, 'script', '-k0', 'target', $0) } elsif (!$ENV{SMDIR}) { die "Execute this script on Manager!" } elsif ($ENV{SMDIR}) { die "Execute this script on Agent!" } else { # command script: .... 1 # success }
DESCRIPTION
The purpose of this module is to implement a command volley scripts. Such script should describe collections of targets and should contain a simple code to execute command line given for each target expanded. Such script can contain immediate command lines to be executed and may be scheduled. Executions of command line (stdout and stderr) are logged into file system. Logging is used also to exclude already executed assignments and successfully executed loops. Autotruncation of log file systems prevents excess.
Command execution or command assignment metaphors are a significant part of many systems management programs. This module may be a simplest implementation. There is no user interface and database, only Perl script(s), file system, command lines.
This module is implemented and tested with Perl 5.6.0 on Windows 2000.
CONCEPTS
- CONCEPTS
-
There are several basic ideas:
- Name space or kind of commands
-
A several kinds of commands may be imagined, i.e. scheduled periodical commands, operator initiated actions, significant assignments. Each kind of commands will have separate subdirectory for log file system. Each kind of commands may have separate subdirectory for command scripts. This is useful at least when reading and autotruncating logs. [
-ckind
,ENVIRONMENT
] - Command execution identifiers or assignment names
-
The identifiers are an unique strings automatically sequentially generated. This is useful for ordinary periodical or operator initiated commands.
Given by operator assignment names may be used instead of automatically generated identifiers. Autotruncation of log file system is missed when using assignment name.
[
-cassign
,-credo
,ENVIRONMENT
] - Loops, Redoes, Assignments, Ping, Sequence
-
Loop is a periodical restart of command until success for all targets.
Redo is a single reexecution of command into existing command identifier for all unsuccessful or not affected targets.
Assignment is a single (re)execution of command for all targets not affected.
Redo is used inside Loop and may be used separately. Loop may be used with Assignment, but may be better to write a special script for assignments and schedule it. Redo switch may be used with Assignment to extend command execution to unsuccessful targets.
Ping switch may be used with Assignment to avoid error registrations for hosts inaccessible.
Sequential unsuccessful targets exclusion may be useful as conditional processing targets of sequential commands.
[
-cassign
and-ping
,-credo
,-cloop
,-vgxi
] - Targets
-
Target collections are named lists of elements to be expanded until target elements. Target collections or target elements are used to execute command line given for each target element.
There are no assumptions on the nature of target (i.e. computer, daemon, user...). Only the name of the target element ('!elem!') may be substituted into command line (see
-cline
for other substitutions possible).Networked features, except
-ping
, are a subject for a separate script(s) or module(s), i.e. Sys::Manage::Conn via-assoc
.[
-cline
,-ctarget
,-cxtgt
,-target
] - Branches of targets
-
Sequential execution of commands may be too long.
Concurrent execution may be too exacting in system resources or telecommunications.
So, branched execution implemented as concurrently executed branches with sequentially executed target elements.
Target collections are named lists of elements to be expanded until target elements using target collections.
[
-branch
,-corder
] - Script associations
-
Sometimes a system administrator writes a script with loop to execute command for each target. When targets are already described, a command line should be simplest for real improvement. I.e. 'volley Collection SomeScript.pl' may be typed instead of 'perl SomeScript.pl'. But this is also way for unusual scripts, like ftp. A last but one command line element '<' results in opening the last element as input stream for command.
[
-assoc
]
SLOTS
- SLOTS
- -assoc
-
=> {association name =>[command line template],...} => {association name =>sub{}(self, [command line]),...}
Associations for commands. Association may be command name, file name or file name extension.
See source code for predefinitions and examples.
Consider Sys::Manage::Conn commands in the source code: 'rcmd' and 'lcmd', 'rdo' and 'ldo' (and script file names matching /\.(rdo|rdo)(?:\.\w+){0,1}$/i), 'fput', 'fget'.
See also
-cline
. - -branch
-
=> {branch name => [branch elements],...}
Branches of
-target
s. Used in-corder
. Will be expanded using-target
. - -cassign
- -a
-
=> assignment name
Command assignment name. See also
-credo
. - -cbranch
- -b
-
=> false | branch name
Command ordering branch name. Used internally in
-corder
processing. - -cerr
-
=> false | [exit code, running, missed]
Statistics of unsuccessful executions of command by
execute
. - -cfg
- -config
-
=> false | true | filename
Instruction to load configuration file. Default file name is 'Sys-Manage-Cmd-cfg.pl'. It will be searched in
ENVIRONMENT
, within 'bin' and 'var' subdirectories and base directory. $_ will contain object to be configured.See also Sys::Manage::Conn configuration file.
- -cid
-
=> false | command identifier
Identifier of command
execute
ed. - -cignor
- -i
-
=> false | true
Command exit code ignoring. Default is to consider and register non-zero exit code as unsuccessful.
- -ckind
- -k
-
=> 'cmd' | name space
Kind (name space) of commands. Special '0' value brings to obtain real value from
-cline
path as considered inENVIRONMENT
. - -cline
-
=>[command line]
Command line or command line template to be executed.
Command script search path (see also
ENVIRONMENT
)If command file (the first command line element usually) is not found with -f operation,
-dirb
/lib--ckind
,-dirb
/lib,-dirb
/bin paths tried.String substitutions (see also
-vsml
,-vsmr
,ENVIRONMENT
):!elem! - element name, also may be used !target!, !host! and !node!.
!log! - log filesystem name.
!pswd! - password, using
-pswd
.!user! - user name, using
-user
.'<' (last but one) - open last element as input stream.
Special commands (in
-assoc
syntax):['do', 'perl script file',...] - execute via do('perl script file').
['eval', 'perl code',...] - execute via eval('perl code').
['eval', sub{}(self, args),...] - execute via eval{&}.
['-e', 'perl code',...] - execute via '$^X -e'.
['
cmdfile
', command file, ? history file, ? redirect log file] - evaluate Sys::Manage::CmdFile or Perl script file by this script.['
cmdstat
'] - display current status, deprecated.['
regask
', ?-opt, ?start, ?end, query] - display registration file system. Options: 'v'erbose output (default), 's'tring return (for function call); '>=' or '<=' start and end conditions (default), '>' or '<' conditions. Start and End: 'yyyy-dd-mm...' row sample; /[\d]+[dhm]/ - days, hours, minutes ago. Query: 'all' (default), 'dir'ectories used, 'pid's running, 'err'ors, expression.['
logask
', ?-opt, ?start, ?end, query] - display-log
contents. Options: 'v'erbose output (default), 's'tring return (for function call); '>=' or '<=' start and end conditions (default), '>' or '<' conditions. Start and End: 'yyyy-dd-mm...' row sample; /[\d]+[dhm]/ - days, hours, minutes ago. Query: 'all' (default), 'pid's running, 'err'ors, expression.Sys::Manage::Conn commands (implemented via
-assoc
): 'rcmd' and 'lcmd', 'rdo' and 'ldo' (and script file names matching /\.(ldo|rdo)(?:\.\w+){0,1}$/i), 'fput', 'fget'.Quoting or escaping of command line arguments
There are no uniform quoting/escaping rules for any platform or application. So automatic quoting/escaping may result ill-posedness. But it is handy to quote source command line elements only once.
This module automatically quotes/escapes target command line elements if special characters found. Trustworthy internal escaping for internal command lines (branching, concurrenting, looping) may be used.
Sys::Manage::Conn::rcmd and Sys::Manage::Conn::rdo arguments will be (re)quoted automatically.
Single Sys::Manage::Conn::rcmd argument will not be (re)quoted automatically to allow rich shell command lines.
Exit code
Usually exit code of the command is $?>>8 and 0 is treated as success. Scripts be evaluating (via 'do', 'eval' or '-e') should return true value on success, false or die otherwise. Sys::Manage::Conn::rdo returns result of the script or !($?>>8).
- -cloop
- -l
-
=> false | seconds to pause | .'g' | .'v' | .'w'
- -lg
- -lv
- -lw
-
Loop (cyclical execution until success) requirement and pause size for subsequent turns.
The general behaviour is full redo of all unsuccessful target elements. Marked with 'g' character ping behaviour involves only targets previously missed or unreachable.
Subsequent turns of loop may be 'v'erbose to current console for testing or opened in a new console 'w'indow. These behaviours are very dependent on platform.
- -cnsum
- -c
-
=> false | name | 'complete' if '-c' only
Add summary execution of scriptic command line using given value as target name in $ENV{SMELEM}. Default 'complete' used if
-c
only in the command line.The script may read STDIN for contents of all logs (execution registration files) of the command. $ENV{SMLOG} contains directory name of this files.
- -cpause
- -p
-
=> false | true
Command prestart pause. Used internally in
-cloop
processing. - -corder
- -o
-
=> 's' | 'c' | 'b'
- -ob
- -oc
- -os
-
Command execution order:
's'equental 'c'oncurrent 'b'ranched (concurrent branches)
- -credo
- -r
-
=> false | true (1|'y'|'+') | command id
Command identifier to redo. Or switch to extend
-cassign
field to unsuccessful targets. Used also in-cloop
processing. - -ctarget
- -t
-
=> target | [targets]
Command target(s). Will be expanded using
-target
. - -cuser
- -u
-
=> false | 'user:password' | 'user'
Command login username and password for
-ctarget
. May be used instead of-user
and-pswd
. - -cxtgt
- -x
-
=> target | [targets]
Targets to exclude from command execution. Will be expanded using
-target
. - -dirb
-
=> base directory
Base (root) directory for volley script execution. Default via $0. See also
ENVIRONMENT
. - -dirl
-
=> limit of logged commands
Logged commands limit. Overfilling results deletion of oldest entries. See source code for default.
- -dirm
-
=> directory marker sign
Directory marker, '/' or '\'. Default via $0 or $^O.
- -dsmd
-
=> undef | sub{}(self, -target|-branch|-user|-pswd|-assoc, ?name) -> [values]
External metadata store interface. May be used instead any of
-target
,-branch
,-user
,-pswd
,-assoc
slot to obtain names and values. - -echo
- -v
-
=> 2 | 1 | 0 | .'c' | .'t'
- -vc
- -vt
-
Echo printout level, verbosity level. Digital level may be supplied with character switches:
'c' - echo each command executing within 'cmdfile'; 't' - include date-time to STDOUT, useful when redirecting.
- -log
-
=> false | true | log file name
Operation logging switch. For separate summary log file in addition to command execution registration file systems.
- -logevt
-
=> undef | 'Sys::Syslog' | 'Win32::EventLog' | 'opcmsg' | => sub{}(self, elem log, [command line], '' | unsuccess reason)
- -logevth*
-
=> undef | -logevt handle
Element commanding event trigger. '-logevth*' names may be used to store trigger object or handle. In addition to
-log
. - -ping
- -g
-
=> undef | true | pingtime | ping object
- -pingcount
-
=> 4 | number of attempts
- -pingprot
-
=> 'icmp' | protocol name
- -pingtime
-
=> 15 | number of seconds
Target element ping check switch and ping parameters, using Net::Ping. Command execution for inaccessible target will not be performed and registered as erroneous, but will be reported as missed. So,
-cassign
may be repeated for this target. - -pswd
-
=> undef | {user=>password,...} | sub{}(self, elem, user)
User password discoverer for
-cline
substitutions. See also-user
. - -reject
-
=> undef | sub{}(self) -> reject message
Commands reject condition. May be useful supplying service to suboperators through Sys::Manage::CmdFile.
$ENV{SMCFP}, {
-cline
}->[0] and other-cline
elements,istarget
,isscript
may be mentioned in conditions.See also Sys::Manage::Conn -reject.
Example:
$s->set(-reject=>sub{ if (!$ENV{SMCFP}) {} elsif ($ENV{SMCFP} =~/\b(?:Admin|Administrator|root|test)\b/i) { $_[0]->set(-k=>$1) if $ENV{SMCFP} =~/(sched|assign)/i && ($_[0]->{-ckind} eq 'cmd'); } elsif ($ENV{SMCFP} =~/\b(?:Operator)\b/i) { $_[0]->set(-k=>($ENV{SMCFP} =~/(assign)/ ? "op-$1" : 'op-cmd')); return('illegal target') if !$_[0]->istarget('collection'); return('illegal script') if !$_[0]->isscript('lib-op'); } else { return("unconsidered queue '$ENV{SMCFP}'") } ''});
- -target
-
=> {collection name => [collection elements],...}
Collections of targets for commands. Not described target considered as target element too.
- -user
-
=> undef | {elem=>user,...} | {elem=>[user, password],...} | sub{}(self, elem)
User name discoverer for
-cline
substitutions. See also-pswd
. - -vgxi
- -gx
-
=> true | false
Initiation of excluding unsuccessful targets flow. Temporary variables file will be used to accumulate and exclude unsuccessful target elements on each sequent
execute
. May be useful for script with severalexecute
calls, or-cline
=> 'cmdfile
'. - -vsml
- -vsmr
-
=> '!'
Left and right substitution marks for command line. See also
-cline
.
METHODS
- METHODS
- cmd (
execute
args) -> success -
Executes command volley given by arguments: clears description of the last command (excluding
-ckind
and-corder
) and callsexecute
with arguments given.May be useful inside scripts with multiple commands.
- daemonize ()
-
Suppresses STDIN, STDOUT, STDERR and calls setsid. See perlipc.
- execute (-option=>value,...) -> success
- execute ([command line arguments],-option=>value,...) -> success
-
Executes
-cline
for each-ctarget
expanded using-target
and-cxtgt
, according to values of all otherSLOTS
.Fundamental result method.
- isscript (?'lib') -> exists?
- istarget (targets possible) -> contains?
-
Useful for
-reject
checks of command script and targets requested by-cline
and-ctarget
.Script is checked to be within
-ckind
lib directory, or 'lib' directory if it listed.Targets are checked to be within possible targets listed.
- new ('class', -option=>value,...) -> new object
- new ('class', [command line arguments], -option=>value,...) -> new object
-
Creates new Sys::Manage::Cmd object. See also
set
syntax. - set () -> (slot names of the object)
- set (-option) -> value of the option given
- set (-option=>value,...) -> self object
- set ([command line arguments], -option=>value,...) -> self object
-
Retrieves and sets values of the
SLOTS
. $s->{-option} direct access may be used also, butset
smartly processes some options.Within the same
set
call, '-options' overwrites [command line arguments], so default values should be set before.When [command line arguments] used, subsequent branch or loop may be executed implicitly.
ENVIRONMENT
- ENVIRONMENT
-
$ENV{SMCFP} - from Sys::Manage::CmdFile.
$ENV{SMDIR} - base (root) directory for volley script execution,
-dirb
. May be used as sign of flow under Sys::Manage::Cmd.$ENV{SMELEM} - target element name. May be used as sign of flow under Sys::Manage::Cmd or Sys::Manage::Conn agent.
$ENV{SMLIB} - directory of command script executing, if found.
$ENV{SMLOG} - log filesystem name considering command or assignment id and target element.
$ENV{SMPID} - management script process id.
$ENV{SMPSWD} - target element password.
$ENV{SMSECS} - number of seconds remaining for subsequent operation.
$ENV{SMUSER} - target element user.
./ - base directory,
-dirb
, also may be used for volley script and writing command scripts../bin - system scripts (including volley script) and useful utilities, if exists.
./lib - command scripts library to find files to execute.
./lib-namespace - specialized --"--, for each
-ckind
../log-namespace -
-ckind
command execution registration file system, for each-ckind
../var - persistent data - stored variables, summary log, etc..
LIMITATIONS, BUGS, PROBLEMS
- Limitations, Bugs, Problems
-
Implemented and tested with Perl 5.6.0 and 5.8.8 on Windows 2000/2003.
Requoting of command lines is not exhaustive.
Fault tolerance for var files is commented in the source code, this is in doubt.
Exhaustive timeouts may be implemented only with $SIG{ALRM} and alarm().
See at the top of the source code.
VERSION
- '2009-10-04'
-
New
-cnsum
/-c
. - '2009-05-18'
-
Translated
-u
printout - password excluded. - '2009-04-01'
-
New
regask
. - '2008-12-24'
-
Changed format of log file and messages.
- '2008-10-31'
-
New
logask
;cmdstat
deprecated. - '2008-06-05'
-
Concurrent pids (
-corder
eq 'c') logged into-log
.New
cmdstat
embedded command using-log
. - '2007-08-13'
-
-dirl
log truncation dehosed. - '2007-08-10'
-
New $ENV{SMSECS}.
- '2007-03-07'
-
Changed Sys::Manage::CmdEscort - added runtime hardlinks from './log-' files to './var' directory - for monitoring and diagnostics during runtime.
- '2007-01-29'
-
New Sys::Manage::Conn mput and Sys::Manage::Conn mget commands.
- '2007-01-25'
-
Description of quoting corrected in
-cline
.Internal command line escaping implemented.
- '2005-12-18'
-
New
-lg
,-lv
,-lw
options.New
daemonize
method. - '2005-12-14'
-
New
cmd
method may be useful inside scripts with multiple commands.New
-u
option for command login username and password.New
-vc
option to echo 'cmdfile
' commands separate from-echo
level. - '2005-12-09'
-
New
-gx
switch to process targets of sequential commands conditionally. - '2005-11-26'
-
New '
cmdfile
' predefined command, see-cline
.Improvement of
vload
. - '2005-11-25'
-
Published 0.50 version.
- '2005-09-09'
-
Started.
LICENSE
This is free software; you can use redistribute it and/or modify it under the same terms as Perl itself.
AUTHOR
Andrew V Makarow <makarow at mail.com>, for demed
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 881:
You forgot a '=back' before '=head1'