NAME

App::MrShell - do everything the mrsh commandline tool can do and more

SYNOPSIS

my $mrsh = App::MrShell
    -> new
    -> set_hosts('host1', 'host2', 'host3')
    -> queue_command('uptime')
    -> queue_command('mii-tool', 'eth0')
    -> queue_command('dmesg | head')
    -> run_queue;

DESCRIPTION

This package can do all the things mrsh can do and possibly more. The methods mostly support chaining to make script writing easier and more attractive. The API hides the POE nature of the project, but the author is not opposed to exposing it if anybody wants such a thing.

OPTIONS METHODS

set_shell_command_option

The first argument is normally a space separated list of command-and-arguments (with some basic quoting support). If called with no arguments, a null-command will be set indicating that there isn't a shell command to prepend hostnames with -- the author can't imagine why this would be useful, but allows that it could be someday for someone.

If the first argument is an arrayref, all following arguments will be ignored. The arrayref will be copied as the shell command. [] can be used as the arrayref to set a null-command.

set_group_option

Setup groups of hosts. Pairs are spliced off the stack with first element as the name of a group, the second element as either a space delimited set of hostnames or an arrayref of hostnames. Example:

$mrsh->set_group_option( group1 => [qw(host1 host2 host3)],
    group2=>['localhost'] );

set_logfile_option

When provided, write a logfile of all lines received, where and when they were executed.

set_debug_option

Turn on various debugging messages. The optional argument specifies the debug level. No argument, 0, and 1 are all equivalent. While levels greater than one indicate an increased amount of debugging noise.

set_no_command_escapes_option

When expanding hosts in host-routing mode, slashes and spaces are escaped so they function correctly when subshelled. This disables that functionality.

read_config

The options above can be specified from a config file, which is documented in the command line tool. The config file is read using Config::Tiny.

set_usage_error

Pass in a function name to call on error. Useful for showing pod2usage() information. Example:

my $mrsh = App::MrShell->new->set_usage_error("pod2usage");

COMMAND METHODS

set_hosts

Set the hosts, groups, and routed strings for the next "queue_command". Hosts have some special magic concerning groups. Hosts that being with an @ character are considered groups are are expanded that way (see config file).

Also see the section on --host in the mrsh documentation.

queue_command

Push a command into the stack for the given hosts (specified by "set_hosts" or by the default hosts in the config file).

Commands are pushed as an array, although, given the nature of http://openssh.com/ it's probably ok to pass in the command as a single string; or even to pass in multiple commands, ; separated and let the shell sort it out.

set_subst_vars

Set any built in or extra subst vars. These will only ever be set once per "subst_cmd_vars"() call, so setting built-in keys will override the built-in values, with the exception of %u at least and %u during host-routing mode -- since those are special subst vars, their substitutions will be difficult to override.

subst_cmd_vars

Substitute command vars, including the special magic of host routing and the escaping associated with it (e.g. %h for the hostname). These are better documented in the COMMAND ESCAPES section.

Others (that is non-internal substs) can be added with "set_subst_vars"(), although %h and %u are magic and setting them manually probably won't work.

As arguments, the function takes the command, upon which substitution should occur, as an array.

run_queue

Run whatever commands are queued. This starts a POE::Session and issues a POE::Kernel->run().

VARS

@DEFAULT_SHELL_COMMAND

This can be specified, perhaps better, via "set_shell_command_option"() or via the config file.

REPORTING BUGS / REQUEST FEATURES

You can report bugs either via http://rt.cpan.org/ or via the issue tracking system on github (http://github.com/jettero/mrsh/issues). I'm likely to notice either fairly quickly.

For feature requests, just go ahead and email me. I've never minded a discussion of this nature yet.

AUTHOR

Paul Miller <jettero@cpan.org>

THANKS

Dennis Boone -- http://github.com/drboone

COPYRIGHT

Copyright 2009-2010 Paul Miller -- released under the GPL

SEE ALSO

ssh(1), perl(1), mrsh, POE, POE::Wheel::Run, Term::ANSIColor