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 and SLOTS)

        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 -targets. 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 executeed.

-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 in ENVIRONMENT.

-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 several execute 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 calls execute 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 other SLOTS.

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, but set 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'