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

Options of command line

-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
-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'
-g		- if ping, or -gPingTimeout
-i		- ignore exit code
-v(0|1|2)	- verbosity level
-vt		- verbosity including date-time

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!

Embedding command line

if (!$ENV{SMELEM}) {	# command volley:
	system($^X, 'script', '-k0', 'target', $0)
} else {		# command script:
	....
}

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

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 not affected targets. 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. [-cassign and -ping, -credo, -cloop]

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 !host! and !node! may be used.

!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'.

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: Forming command line, any argument will be (re)quoted automatically if special characters found. 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

Loop (cyclical execution until success) requirement and pause size for subsequent turns.

-cpause

-p

=> false | true

Command prestart pause. Used internally in -cloop processing.

-corder

-o

=> 's' | 'c' | 'b'

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.

-cxtgt

-x

=> target | [targets]

Targets to exclude from command execution. Will be expanded using -target.

-dirb

=> base directory

Base 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 | 0

Echo printout level, verbosity level.

-echot

-vt

=> false | true

Including date-time with echo printout, may be useful redirecting STDOUT.

-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 or cmdfile.

$ENV{SMCFP}, istarget, isscript may be mentioned in conditions.

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.

-vsml

-vsmr

=> '!'

Left and right substitution marks for command line. See also -cline.

METHODS

METHODS

cmdfile (script file, command file)

cmdfile (script file, command file => history file)

cmdfile (script file, command file, ? history file, ? redirect log file)

cmdfile (sub{}(command row, redirect log file),...)

Proceeds text file interpreting rows as script commands and moving rows proceeded to history file if given.

This is an utility method from Sys::Manage::CmdFile may be useful sometimes.

execute (-option=>value,...) -> success

execute ([command line arguments],-option=>value,...) -> success

Executes -cline for each -ctarget expanded using -target and -cxtgt.

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 directory for volley script execution, -dirb. May be used as sign of flow under Sys::Manage::Cmd but not Sys::Manage::Conn::rdo.

$ENV{SMELEM} - target element name. May be used as sign of flow under Sys::Manage::Cmd or Sys::Manage::Conn::rdo.

$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{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..

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