1Rex::Commands(3) User Contributed Perl Documentation Rex::Commands(3)
2
6 Rex::Commands - All the basic commands
7
9 This module is the core commands module.
10
12 desc "Task description";
13 task "taskname", sub { ... };
15 task "taskname", "server1", ..., "server20", sub { ... };
16 group "group" => "server1", "server2", ...;
18 user "user";
20 password "password";
22 environment live => sub {
24 user "root";
25 password "foobar";
26 pass_auth;
27 group frontend => "www01", "www02";
28 };
29
31 • Augeas config file management library Rex::Commands::Augeas
32 • Cloud Management Rex::Commands::Cloud
34 • Cron Management Rex::Commands::Cron
36 • Database Commands Rex::Commands::DB
38 • SCP Up- and Download Rex::Commands::Upload, Rex::Commands::Download
40 • File Manipulation Rex::Commands::File
42 • Filesystem Manipulation Rex::Commands::Fs
44 • Information Gathering Rex::Commands::Gather
46 • Manipulation of /etc/hosts Rex::Commands::Host
48 • Get an inventory of your Hardware Rex::Commands::Inventory
50 • Manage your iptables rules Rex::Commands::Iptables
52 • Kernel Commands Rex::Commands::Kernel
54 • LVM Commands Rex::Commands::LVM
56 • MD5 checksums Rex::Commands::MD5
58 • Network commands Rex::Commands::Network
60 • Notify resources to execute Rex::Commands::Notify
62 • Package Commands Rex::Commands::Pkg
64 • Partition your storage device(s) Rex::Commands::Partition
66 • Configure packages (via debconf) Rex::Commands::PkgConf
68 • Process Management Rex::Commands::Process
70 • Rsync Files Rex::Commands::Rsync
72 • Run Remote Commands Rex::Commands::Run
74 • Source control via Subversion/Git Rex::Commands::SCM
76 • Manage System Services (sysvinit) Rex::Commands::Service
78 • Simple TCP/alive checks Rex::Commands::SimpleCheck
80 • Sync directories Rex::Commands::Sync
82 • Sysctl Commands Rex::Commands::Sysctl
84 • Live Tail files Rex::Commands::Tail
86 • Upload local file to remote server Rex::Commands::Upload
88 • Manage user and group accounts Rex::Commands::User
90 • Manage your virtual environments Rex::Commands::Virtualization
92
94 no_ssh([$task])
95 Disable ssh for all tasks or a specified task.
96 If you want to disable ssh connection for your complete tasks (for
98 example if you only want to use libVirt) put this in the main section
99 of your Rexfile.
100 no_ssh;
102 If you want to disable ssh connection for a given task, put no_ssh in
104 front of the task definition.
105 no_ssh task "mytask", "myserver", sub {
107 say "Do something without a ssh connection";
108 };
109 task($name [, @servers], $funcref)
111 This function will create a new task.
112 Create a local task (a server independent task)
114 task "mytask", sub {
115 say "Do something";
116 };
117 If you call this task with (R)?ex it will run on your local
119 machine. You can explicit run this task on other machines if you
120 specify the -H command line parameter.
121 Create a server bound task.
123 task "mytask", "server1", sub {
124 say "Do something";
125 };
126 You can also specify more than one server.
128 task "mytask", "server1", "server2", "server3", sub {
130 say "Do something";
131 };
132 Or you can use some expressions to define more than one server.
134 task "mytask", "server[1..3]", sub {
136 say "Do something";
137 };
138 If you want, you can overwrite the servers with the -H command line
140 parameter.
141 Create a group bound task.
143 You can define server groups with the group function.
144 group "allserver" => "server[1..3]", "workstation[1..10]";
146 task "mytask", group => "allserver", sub {
148 say "Do something";
149 };
150 desc($description)
152 Set the description of a task.
153 desc "This is a task description of the following task";
155 task "mytask", sub {
156 say "Do something";
157 }
158 group($name, @servers)
160 With this function you can group servers, so that you don't need to
161 write too much ;-)
162 group "servergroup", "www1", "www2", "www3", "memcache01", "memcache02", "memcache03";
164 Or with the expression syntax:
166 group "servergroup", "www[1..3]", "memcache[01..03]";
168 If the "use_server_auth" feature flag is enabled, you can also specify
170 server options after a server name with a hash reference:
171 use Rex -feature => ['use_server_auth'];
173 group "servergroup", "www1" => { user => "other" }, "www2";
175 These expressions are allowed:
177 • \d+..\d+ (range)
179 The first number is the start and the second number is the end for
181 numbering the servers.
182 group "name", "www[1..3]"; # www1, www2, www3
184 • \d+..\d+/\d+ (range with step)
186 Just like the range notation, but with an additional "step"
188 defined. If step is omitted, it defaults to 1 (i.e. it behaves
189 like a simple range expression).
190 group "name", "www[1..5/2]"; # www1, www3, www5
192 group "name", "www[111..133/11]"; # www111, www122, www133
193 • \d+,\d+,\d+ (list)
195 With this variant you can define fixed values.
197 group "name", "www[1,3,7,01]"; # www1, www3, www7, www01
199 • Mixed list, range and range with step
201 You can mix the three variants above
203 www[1..3,5,9..21/3]; # www1, www2, www3, www5, www9, www12, www15, www18, www21
205 batch($name, @tasks)
207 With the batch function you can call tasks in a batch.
208 batch "name", "task1", "task2", "task3";
210 And call it with the -b console parameter. rex -b name
212 user($user)
214 Set the user for the ssh connection.
215 password($password)
217 Set the password for the ssh connection (or for the private key file).
218 auth(for => $entity, %data)
220 With this command you can set or modify authentication parameters for
221 tasks and groups. (Please note this is different than setting
222 authentication details for the members of a host group. If you are
223 looking for that, please check out the group
224 <https://metacpan.org/pod/Rex::Commands#group> command.)
225 If you want to set special login information for a group you have to
227 enable at least the 0.31 feature flag, and ensure the "group" is
228 declared before the "auth" command.
229 Command line options to set locality or authentication details are
231 still taking precedence, and may override these settings.
232 # auth for groups
234 use Rex -feature => ['0.31']; # activate setting auth for a group
236 group frontends => "web[01..10]";
238 group backends => "be[01..05]";
239 auth for => "frontends" =>
241 user => "root",
242 password => "foobar";
243 auth for => "backends" =>
245 user => "admin",
246 private_key => "/path/to/id_rsa",
247 public_key => "/path/to/id_rsa.pub",
248 sudo => TRUE;
249 # auth for tasks
251 task "prepare", group => ["frontends", "backends"], sub {
253 # do something
254 };
255 auth for => "prepare" =>
257 user => "root";
258 # auth for multiple tasks with regular expression
260 task "step_1", sub {
262 # do something
263 };
264 task "step_2", sub {
266 # do something
267 };
268 auth for => qr/step/ =>
270 user => $user,
271 password => $password;
272 # fallback auth
274 auth fallback => {
275 user => "fallback_user1",
276 password => "fallback_pw1",
277 public_key => "",
278 private_key => "",
279 }, {
280 user => "fallback_user2",
281 password => "fallback_pw2",
282 public_key => "keys/public.key",
283 private_key => "keys/private.key",
284 sudo => TRUE,
285 };
286 port($port)
288 Set the port where the ssh server is listening.
289 sudo_password($password)
291 Set the password for the sudo command.
292 timeout($seconds)
294 Set the timeout for the ssh connection and other network related stuff.
295 max_connect_retries($count)
297 Set the maximum number of connection retries.
298 get_random($count, @chars)
300 Returns a random string of $count characters on the basis of @chars.
301 my $rnd = get_random(8, 'a' .. 'z');
303 do_task($task)
305 Call $task from another task. It will establish a new connection to the
306 server defined in $task and then execute $task there.
307 task "task1", "server1", sub {
309 say "Running on server1";
310 do_task "task2";
311 };
312 task "task2", "server2", sub {
314 say "Running on server2";
315 };
316 You may also use an arrayRef for $task if you want to call multiple
318 tasks.
319 do_task [ qw/task1 task2 task3/ ];
321 run_task($task_name, %option)
323 Run a task on a given host.
324 my $return = run_task "taskname", on => "192.168.3.56";
326 Do something on server5 if memory is less than 100 MB free on server3.
328 task "prepare", "server5", sub {
330 my $free_mem = run_task "get_free_mem", on => "server3";
331 if($free_mem < 100) {
332 say "Less than 100 MB free mem on server3";
333 # create a new server instance on server5 to unload server3
334 }
335 };
336 task "get_free_mem", sub {
338 return memory->{free};
339 };
340 If called without a hostname the task is run localy.
342 # this task will run on server5
344 task "prepare", "server5", sub {
345 # this will call task check_something. but this task will run on localhost.
346 my $check = run_task "check_something";
347 }
348 task "check_something", "server4", sub {
350 return "foo";
351 };
352 If you want to add custom parameters for the task you can do it this
354 way.
355 task "prepare", "server5", sub {
357 run_task "check_something", on => "foo", params => { param1 => "value1", param2 => "value2" };
358 };
359 run_batch($batch_name, %option)
361 Run a batch on a given host.
362 my @return = run_batch "batchname", on => "192.168.3.56";
364 It calls internally run_task, and passes it any option given.
366 public_key($key)
368 Set the public key.
369 private_key($key)
371 Set the private key.
372 pass_auth
374 If you want to use password authentication, then you need to call
375 pass_auth.
376 user "root";
378 password "root";
379 pass_auth;
381 key_auth
383 If you want to use pubkey authentication, then you need to call
384 key_auth.
385 user "bob";
387 private_key "/home/bob/.ssh/id_rsa"; # passphrase-less key
388 public_key "/home/bob/.ssh/id_rsa.pub";
389 key_auth;
391 krb5_auth
393 If you want to use kerberos authentication, then you need to call
394 krb5_auth. This authentication mechanism is only available if you use
395 Net::OpenSSH.
396 set connection => "OpenSSH";
398 user "root";
399 krb5_auth;
400 parallelism($count)
402 Will execute the tasks in parallel on the given servers. $count is the
403 thread count to be used:
404 parallelism '2'; # set parallelism to 2
406 Alternatively, the following notation can be used to set thread count
408 more dynamically:
409 parallelism 'max'; # set parallelism to the number of servers a task is asked to run on
411 parallelism 'max/3'; # set parallelism to 1/3 of the number of servers
412 parallelism 'max 10%'; # set parallelism to 10% of the number of servers
413 If an unrecognized value is passed, or the calculated thread count
415 would be less than 1, Rex falls back to use a single thread.
416 proxy_command($cmd)
418 Set a proxy command to use for the connection. This is only possible
419 with OpenSSH connection method.
420 set connection => "OpenSSH";
422 proxy_command "ssh user@jumphost nc %h %p 2>/dev/null";
423 set_distributor($distributor)
425 This sets the task distribution module. Default is "Base".
426 Possible values are: Base, Gearman, Parallel_ForkManager
428 template_function(sub { ... })
430 This function sets the template processing function. So it is possible
431 to change the template engine. For example to Template::Toolkit.
432 logging
434 With this function you can define the logging behaviour of (R)?ex.
435 Logging to a file
437 logging to_file => "rex.log";
438 Logging to syslog
440 logging to_syslog => $facility;
441 needs($package [, @tasks])
443 With needs you can define dependencies between tasks. The "needed"
444 tasks will be called with the same server configuration as the calling
445 task.
446 needs will not execute before, around and after hooks.
448 Depend on all tasks in a given package.
450 Depend on all tasks in the package MyPkg. All tasks will be called
451 with the server server1.
452 task "mytask", "server1", sub {
454 needs MyPkg;
455 };
456 Depend on a single task in a given package.
458 Depend on the uname task in the package MyPkg. The uname task will
459 be called with the server server1.
460 task "mytask", "server1", sub {
462 needs MyPkg "uname";
463 };
464 To call tasks defined in the Rexfile from within a module
466 task "mytask", "server1", sub {
467 needs main "uname";
468 };
469 include Module::Name
471 Include a module without registering its tasks.
472 include qw/
474 Module::One
475 Module::Two
476 /;
477 environment($name => $code)
479 Define an environment. With environments one can use the same task for
480 different hosts. For example if you want to use the same task on your
481 integration-, test- and production servers.
482 # define default user/password
484 user "root";
485 password "foobar";
486 pass_auth;
487 # define default frontend group containing only testwww01.
489 group frontend => "testwww01";
490 # define live environment, with different user/password
492 # and a frontend server group containing www01, www02 and www03.
493 environment live => sub {
494 user "root";
495 password "livefoo";
496 pass_auth;
497 group frontend => "www01", "www02", "www03";
499 };
500 # define stage environment with default user and password. but with
502 # a own frontend group containing only stagewww01.
503 environment stage => sub {
504 group frontend => "stagewww01";
505 };
506 task "prepare", group => "frontend", sub {
508 say run "hostname";
509 };
510 Calling this task rex prepare will execute on testwww01. Calling this
512 task with rex -E live prepare will execute on www01, www02, www03.
513 Calling this task rex -E stage prepare will execute on stagewww01.
514 You can call the function within a task to get the current environment.
516 task "prepare", group => "frontend", sub {
518 if(environment() eq "dev") {
519 say "i'm in the dev environment";
520 }
521 };
522 If no -E option is passed on the command line, the default environment
524 (named 'default') will be used.
525 LOCAL(&)
527 With the LOCAL function you can do local commands within a task that is
528 defined to work on remote servers.
529 task "mytask", "server1", "server2", sub {
531 # this will call 'uptime' on the servers 'server1' and 'server2'
532 say run "uptime";
533 # this will call 'uptime' on the local machine.
535 LOCAL {
536 say run "uptime";
537 };
538 };
539 path(@path)
541 Set the execution path for all commands.
542 path "/bin", "/sbin", "/usr/bin", "/usr/sbin", "/usr/pkg/bin", "/usr/pkg/sbin";
544 set($key, $value)
546 Set a configuration parameter. These variables can be used in templates
547 as well.
548 set database => "db01";
550 task "prepare", sub {
552 my $db = get "database";
553 };
554 Or in a template
556 DB: <%= $::database %>
558 The following list of configuration parameters are Rex specific:
560 get($key, $value)
562 Get a configuration parameter.
563 set database => "db01";
565 task "prepare", sub {
567 my $db = get "database";
568 };
569 Or in a template
571 DB: <%= $::database %>
573 before($task => sub {})
575 Run code before executing the specified task.
576 The task name is a regular expression to find all tasks with a matching
578 name. The special task name 'ALL' can also be used to run code before
579 all tasks.
580 If called repeatedly, each sub will be appended to a list of 'before'
582 functions.
583 In this hook you can overwrite the server to which the task will
585 connect to. The second argument is a reference to the server object
586 that will be used for the connection.
587 Please note, this must come after the definition of the specified task.
589 before mytask => sub {
591 my ($server, $server_ref, $cli_args) = @_;
592 run "vzctl start vm$server";
593 };
594 after($task => sub {})
596 Run code after executing the specified task.
597 The task name is a regular expression to find all tasks with a matching
599 name. The special task name 'ALL' can be used to run code after all
600 tasks.
601 If called repeatedly, each sub will be appended to a list of 'after'
603 functions.
604 Please note, this must come after the definition of the specified task.
606 after mytask => sub {
608 my ($server, $failed, $cli_args) = @_;
609 if($failed) { say "Connection to $server failed."; }
610 run "vzctl stop vm$server";
612 };
613 around($task => sub {})
615 Run code around the specified task (that is both before and after
616 executing it).
617 The task name is a regular expression to find all tasks with a matching
619 name. The special task name 'ALL' can be used to run code around all
620 tasks.
621 If called repeatedly, each sub will be appended to a list of 'around'
623 functions.
624 In this hook you can overwrite the server to which the task will
626 connect to. The second argument is a reference to the server object
627 that will be used for the connection.
628 Please note, this must come after the definition of the specified task.
630 around mytask => sub {
632 my ($server, $server_ref, $cli_args, $position) = @_;
633 unless($position) {
635 say "Before Task\n";
636 }
637 else {
638 say "After Task\n";
639 }
640 };
641 before_task_start($task => sub {})
643 Run code before executing the specified task. This gets executed only
644 once for a task.
645 The task name is a regular expression to find all tasks with a matching
647 name. The special task name 'ALL' can be used to run code before all
648 tasks.
649 If called repeatedly, each sub will be appended to a list of
651 'before_task_start' functions.
652 Please note, this must come after the definition of the specified task.
654 before_task_start mytask => sub {
656 # do some things
657 };
658 after_task_finished($task => sub {})
660 Run code after the task is finished (and after the ssh connection is
661 terminated). This gets executed only once for a task.
662 The task name is a regular expression to find all tasks with a matching
664 name. The special task name 'ALL' can be used to run code after all
665 tasks.
666 If called repeatedly, each sub will be appended to a list of
668 'after_task_finished' functions.
669 Please note, this must come after the definition of the specified task.
671 after_task_finished mytask => sub {
673 # do some things
674 };
675 logformat($format)
677 You can define the logging format with the following parameters.
678 %D - Appends the current date yyyy-mm-dd HH:mm:ss
680 %h - The target host
682 %p - The pid of the running process
684 %l - Loglevel (INFO or DEBUG)
686 %s - The Logstring
688 Default is: [%D] %l - %s
690 connection
692 This function returns the current connection object.
693 task "foo", group => "baz", sub {
695 say "Current Server: " . connection->server;
696 };
697 cache
699 This function returns the current cache object.
700 profiler
702 Returns the profiler object for the current connection.
703 report($switch, $type)
705 This function will initialize the reporting.
706 report -on => "YAML";
708 source_global_profile(0|1)
710 If this option is set, every run() command will first source
711 /etc/profile before getting executed.
712 last_command_output
714 This function returns the output of the last "run" command.
715 On a debian system this example will return the output of apt-get
717 install foobar.
718 task "mytask", "myserver", sub {
720 install "foobar";
721 say last_command_output();
722 };
723 case($compare, $option)
725 This is a function to compare a string with some given options.
726 task "mytask", "myserver", sub {
728 my $ntp_service = case operating_system, {
729 Debian => "ntp",
730 default => "ntpd",
731 };
732 my $ntp_service = case operating_system, {
734 qr{debian}i => "ntp",
735 default => "ntpd",
736 };
737 my $ntp_service = case operating_system, {
739 qr{debian}i => "ntp",
740 default => sub { return "foo"; },
741 };
742 };
743 set_executor_for($type, $executor)
745 Set the executor for a special type. This is primary used for the
746 upload_and_run helper function.
747 set_executor_for perl => "/opt/local/bin/perl";
749 tmp_dir($tmp_dir)
751 Set the tmp directory on the remote host to store temporary files.
752 inspect($varRef)
754 This function dumps the contents of a variable to STDOUT.
755 task "mytask", "myserver", sub {
757 my $myvar = {
758 name => "foo",
759 sys => "bar",
760 };
761 inspect $myvar;
763 };
764 sayformat($format)
766 You can define the format of the say() function.
767 %D - The current date yyyy-mm-dd HH:mm:ss
769 %h - The target host
771 %p - The pid of the running process
773 %s - The Logstring
775 You can also define the following values:
777 default - the default behaviour.
779 asis - will print every single parameter in its own line. This is
781 useful if you want to print the output of a command.
782perl v5.34.0 2022-01-19 Rex::Commands(3)