-
-
05 Jul 2021 21:04:56 UTC
- Distribution: Rex
- Module version: v1.13.4
- Source (raw)
- Browse (raw)
- Changes
- Homepage
- How to Contribute
- Repository
- Issues
- Testers (693 / 3 / 2)
- Kwalitee
Bus factor: 2- 49.25% Coverage
- License: apache_2_0
- Perl: v5.10.1
- Activity
24 month- Tools
- Download (342.78KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 118 contributors-
Jan Gehring
-
A Happy User
-
Alexander Romanenko
-
Alexandr Ciornii
-
Alex Mestiashvili
-
Ali Polatel
-
alx542
-
Anders Ossowicki
-
Andrej Zverev
-
Andrew Solomon
-
Andy Beverley
-
Arnold Bechtoldt
-
Boris Däppen
-
Brian Manning
-
Cameron Daniel
-
Chris Steigmeier
-
Christophe Wolfhugel
-
Crimson Thompson
-
Daniel Bäurer
-
Daniel Cesario
-
Daniel Dico
-
Denis Silakov
-
Dmitry Kopytov
-
Dominik Schulz
-
E. Choroba
-
Eduardo J
-
Eivin Giske Skaaren
-
elisdg
-
Elmer Quintanilla
-
Eric Johnson
-
Erik Huelsmann
-
Ferenc Erki
-
Franky Van Liedekerke
-
Fran Rodriguez
-
Gabor Szabo
-
Graham Todd
-
Harm Müller
-
Hayato Imai
-
Hiroaki Nakamura
-
Hiroki Matsuo
-
iblinder
-
Ilya Pavlov
-
James D Bearden
-
jdelgado7
-
Jean Charles Passard
-
Jean-Marie Renouard
-
Jeen Lee
-
Jens Berthold
-
Joachim Bargsten
-
John Karr
-
Jon Gentle
-
Joris DE POOTER
-
Jose Luis Martinez
-
Jose Luis Perez Diez
-
Kasim Tuman
-
Keedi Kim
-
Ken Crowell
-
Kent Fredric
-
Kirill Babikhin
-
labbeduddel
-
Leah Neukirchen
-
LeMerP
-
Mario Domgoergen
-
Max E. Aubrey
-
Mitch Broadhead
-
Nathan Abu
-
Naveed Massjouni
-
necrophcodr
-
Nicolas Leclercq
-
Nigel Gregoire
-
Nikolay A. Fetisov
-
Nils Domrose
-
okaoka
-
Oleg Hardt
-
Olivier Cherrier
-
Orange
-
Paco Esteban
-
Patrick Lauer
-
Pavel Timofeev
-
perlancar
-
Peter H. Ezetta
-
Peter Manthey
-
petersonchen
-
Pierrick DINTRAT
-
Piotr Karbowski
-
Prajithp
-
Randy Lauen
-
Renée Bäcker
-
Robert Abraham
-
Roy Storey
-
Samuele Tognini
-
Sascha Askani
-
Sascha Guenther
-
Simon Bertrang
-
Solène Rapenne
-
Stephane Benoit
-
Steve Dondley
-
Sven Dowideit
-
Tamas Molnar
-
Tianon Gravi
-
Tokuhiro Matsuno
-
Tomohiro Hosaka
-
Volker Kroll
-
Walery Wysotsky
-
Yanick Champoux
-
Yegor Korablev
-
Zane C. Bowers-Hadley
-
Сергей Романов
-
范野人
-
饶琛琳
-
Cuong Manh Le
-
David Golovan
-
Dominik Danter
-
Ilya Evseev
-
Niklas Larsson
-
Qiao Liu
-
Renato CRON
-
Peter Jankovics
- Dependencies
- AWS::Signature4
- Carp
- Cwd
- Data::Dumper
- Data::Validate::IP
- Devel::Caller
- Digest::HMAC_SHA1
- Digest::MD5
- English
- Exporter
- Fcntl
- File::Basename
- File::Spec
- File::Spec::Unix
- File::Spec::Win32
- FindBin
- HTTP::Request
- HTTP::Request::Common
- Hash::Merge
- IO::File
- IO::Select
- IO::Socket
- IO::String
- IPC::Open3
- JSON::MaybeXS
- LWP::UserAgent
- List::Util
- MIME::Base64
- Net::OpenSSH::ShellQuoter
- POSIX
- Scalar::Util
- Sort::Naturally
- Storable
- Symbol
- Term::ReadKey
- Test::Builder::Module
- Text::Glob
- Text::Wrap
- Time::HiRes
- UNIVERSAL
- URI
- URI::QueryParam
- XML::Simple
- YAML
- attributes
- base
- constant
- lib
- overload
- strict
- vars
- version
- warnings
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
NAME
Rex::Commands::Run - Execute a remote command
DESCRIPTION
With this module you can run a command.
SYNOPSIS
my $output = run 'ls -l'; sudo 'id';
EXPORTED FUNCTIONS
run($command [, $callback], %options)
This function will execute the given
$command
and returns the output. In scalar context it returns the raw output as is, and in list context it returns the list of output lines. The exit value of the command is stored in the$?
variable.run 'uptime'; my $output = run 'uptime'; my @output_lines = run 'uptime';
It supports optional callbacks as subroutine reference, which will receive the command's output sent to
STDOUT
andSTDERR
.run 'uptime', sub { my ( $stdout, $stderr ) = @_; my $server = Rex::get_current_connection()->{server}; say "[$server] $stdout\n"; };
It also takes further options in a form of a hash. Supported options are:
- cwd => $path
-
Sets the working directory of the executed command to
$path
. - only_if => $condition_command
-
Executes the command only if
$condition_command
returns success. - unless => $condition_command
-
Executes the command if
$condition_command
returns failure. - only_notified => TRUE
-
Queues the command to be executed later upon notification.
- env => { var1 => $value1, ..., varN => $valueN }
-
Sets environment variables for the given command.
- timeout => value
-
Sets the timeout for the command to be run.
- auto_die => TRUE
-
Die if the command returns with an exit code indicating failure. It can be set globally via the exec_autodie feature flag.
- command => $command_to_run
-
If present, Rex will execute
$command_to_run
, and treat the first arugment as an identifier for the givenrun()
block (e.g. to be triggered with notify). - creates => $file_to_create
-
Tries to create
$file_to_create
upon execution, and skips execution if the file already exists. - continuous_read => $callback
-
Calls
$callback
subroutine reference for each line of the command's output, passing the line as an argument. - end_if_matched => qr{$pattern}
-
End execution early as soon as
$pattern
is detected in the command's output.
Examples:
If you only want to run a command if another command succeeds or fails, use the
only_if
orunless
options.run 'some-command', only_if => 'pgrep httpd'; # only run if httpd is running run 'some-other-command', unless => 'pgrep httpd'; # only run if httpd is _not_ running
If you want to set custom environment variables you can do it like this:
run 'my_command', env => { env_var_1 => 'the value for 1', env_var_2 => 'the value for 2', };
If you want to end the command upon receiving a certain output:
run 'my_command', end_if_matched => qr{$pattern};
run($command, $arguments, %options)
This form will execute
$command
with the given$arguments
pass as an array reference. All arguments will be quoted by Rex withNet::OpenSSH::ShellQuoter-
quoter()> according to the managed host's shell.run 'ls', [ '-l', '-t', '-r', '-a' ]; run 'ls', [ '/tmp', '-l' ], auto_die => TRUE;
run($command_description, command => $command, %options)
If you only want to run a command in certain cases, you can queue the command and notify it to trigger its execution.
run 'extract-something', command => 'tar -C /foo -xzf /tmp/foo.tgz', only_notified => TRUE; # some code ... notify 'run', 'extract-something'; # now the command gets executed
can_run($command)
This function checks if a command is available in the path. It accepts a list of commands, and returns the full path to the first command found.
task 'uptime', sub { if ( my $cmd = can_run( 'uptime', 'downtime' ) ) { say run $cmd; } };
sudo
Run a single command, a code block, or all commands with
sudo
. You need perl to be available on the remote systems to usesudo
.Depending on your remote sudo configuration, you may need to define a sudo password with sudo_password first:
sudo_password 'my_sudo_password'; # hardcoding
Or alternatively, since Rexfile is plain perl, you can read the password from terminal at the start:
use Term::ReadKey; print 'I need sudo password: '; ReadMode('noecho'); sudo_password ReadLine(0); ReadMode('restore');
Similarly, it is also possible to read it from a secret file, database, etc.
You can turn sudo on globally with:
sudo TRUE; # run _everything_ with sudo
To run only a specific command with sudo, use :
say sudo 'id'; # passing a remote command directly say sudo { command => 'id' }; # passing anonymous hashref say sudo { command => 'id', user => 'different' }; # run a single command with sudo as different user
To run multiple commands with
sudo
, either use an anonymous code reference directly:sudo sub { service 'nginx' => 'restart'; say run 'id'; };
or pass it via
command
(optionally along a different user):sudo { command => sub { say run 'id'; say run 'pwd', cwd => '/home/different'; }, user => 'different', };
Note that some users receive the error
sudo: sorry, you must have a tty to run sudo
. In this case you have to disablerequiretty
for this user. You can do this in your sudoers file with the following code:Defaults:$username !requiretty
Module Install Instructions
To install Rex, copy and paste the appropriate command in to your terminal.
cpanm Rex
perl -MCPAN -e shell install Rex
For more information on module installation, please visit the detailed CPAN module installation guide.