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 the task, batch, or environment following it.
153 desc 'This is the description of the following task';
155 task 'mytask', sub {
156 say 'Do something';
157 };
158 desc 'This is the description of the following batch';
160 batch mybatch => 'task1', 'task2', 'task3';
161 desc 'This is the description of the following environment';
163 environment production => sub {
164 ...
165 };
166 group($name, @servers)
168 With this function you can group servers, so that you don't need to
169 write too much ;-)
170 group "servergroup", "www1", "www2", "www3", "memcache01", "memcache02", "memcache03";
172 Or with the expression syntax:
174 group "servergroup", "www[1..3]", "memcache[01..03]";
176 If the "use_server_auth" feature flag is enabled, you can also specify
178 server options after a server name with a hash reference:
179 use Rex -feature => ['use_server_auth'];
181 group "servergroup", "www1" => { user => "other" }, "www2";
183 These expressions are allowed:
185 • \d+..\d+ (range)
187 The first number is the start and the second number is the end for
189 numbering the servers.
190 group "name", "www[1..3]"; # www1, www2, www3
192 • \d+..\d+/\d+ (range with step)
194 Just like the range notation, but with an additional "step"
196 defined. If step is omitted, it defaults to 1 (i.e. it behaves
197 like a simple range expression).
198 group "name", "www[1..5/2]"; # www1, www3, www5
200 group "name", "www[111..133/11]"; # www111, www122, www133
201 • \d+,\d+,\d+ (list)
203 With this variant you can define fixed values.
205 group "name", "www[1,3,7,01]"; # www1, www3, www7, www01
207 • Mixed list, range and range with step
209 You can mix the three variants above
211 www[1..3,5,9..21/3]; # www1, www2, www3, www5, www9, www12, www15, www18, www21
213 batch($name, @tasks)
215 With the batch function you can call tasks in a batch.
216 batch "name", "task1", "task2", "task3";
218 And call it with the -b console parameter. rex -b name
220 user($user)
222 Set the user for the ssh connection.
223 password($password)
225 Set the password for the ssh connection (or for the private key file).
226 auth(for => $entity, %data)
228 With this command you can set or modify authentication parameters for
229 tasks and groups. (Please note this is different than setting
230 authentication details for the members of a host group. If you are
231 looking for that, please check out the group
232 <https://metacpan.org/pod/Rex::Commands#group> command.)
233 If you want to set special login information for a group you have to
235 enable at least the 0.31 feature flag, and ensure the "group" is
236 declared before the "auth" command.
237 Command line options to set locality or authentication details are
239 still taking precedence, and may override these settings.
240 # auth for groups
242 use Rex -feature => ['0.31']; # activate setting auth for a group
244 group frontends => "web[01..10]";
246 group backends => "be[01..05]";
247 auth for => "frontends" =>
249 user => "root",
250 password => "foobar";
251 auth for => "backends" =>
253 user => "admin",
254 private_key => "/path/to/id_rsa",
255 public_key => "/path/to/id_rsa.pub",
256 sudo => TRUE;
257 # auth for tasks
259 task "prepare", group => ["frontends", "backends"], sub {
261 # do something
262 };
263 auth for => "prepare" =>
265 user => "root";
266 # auth for multiple tasks with regular expression
268 task "step_1", sub {
270 # do something
271 };
272 task "step_2", sub {
274 # do something
275 };
276 auth for => qr/step/ =>
278 user => $user,
279 password => $password;
280 # fallback auth
282 auth fallback => {
283 user => "fallback_user1",
284 password => "fallback_pw1",
285 public_key => "",
286 private_key => "",
287 }, {
288 user => "fallback_user2",
289 password => "fallback_pw2",
290 public_key => "keys/public.key",
291 private_key => "keys/private.key",
292 sudo => TRUE,
293 };
294 port($port)
296 Set the port where the ssh server is listening.
297 sudo_password($password)
299 Set the password for the sudo command.
300 timeout($seconds)
302 Set the timeout for the ssh connection and other network related stuff.
303 max_connect_retries($count)
305 Set the maximum number of connection retries.
306 get_random($count, @chars)
308 Returns a random string of $count characters on the basis of @chars.
309 my $rnd = get_random(8, 'a' .. 'z');
311 do_task($task)
313 Call $task from another task. It will establish a new connection to the
314 server defined in $task and then execute $task there.
315 task "task1", "server1", sub {
317 say "Running on server1";
318 do_task "task2";
319 };
320 task "task2", "server2", sub {
322 say "Running on server2";
323 };
324 You may also use an arrayRef for $task if you want to call multiple
326 tasks.
327 do_task [ qw/task1 task2 task3/ ];
329 run_task($task_name, %option)
331 Run a task on a given host.
332 my $return = run_task "taskname", on => "192.168.3.56";
334 Do something on server5 if memory is less than 100 MB free on server3.
336 task "prepare", "server5", sub {
338 my $free_mem = run_task "get_free_mem", on => "server3";
339 if($free_mem < 100) {
340 say "Less than 100 MB free mem on server3";
341 # create a new server instance on server5 to unload server3
342 }
343 };
344 task "get_free_mem", sub {
346 return memory->{free};
347 };
348 If called without a hostname the task is run localy.
350 # this task will run on server5
352 task "prepare", "server5", sub {
353 # this will call task check_something. but this task will run on localhost.
354 my $check = run_task "check_something";
355 }
356 task "check_something", "server4", sub {
358 return "foo";
359 };
360 If you want to add custom parameters for the task you can do it this
362 way.
363 task "prepare", "server5", sub {
365 run_task "check_something", on => "foo", params => { param1 => "value1", param2 => "value2" };
366 };
367 run_batch($batch_name, %option)
369 Run a batch on a given host.
370 my @return = run_batch "batchname", on => "192.168.3.56";
372 It calls internally run_task, and passes it any option given.
374 public_key($key)
376 Set the public key.
377 private_key($key)
379 Set the private key.
380 pass_auth
382 If you want to use password authentication, then you need to call
383 pass_auth.
384 user "root";
386 password "root";
387 pass_auth;
389 key_auth
391 If you want to use pubkey authentication, then you need to call
392 key_auth.
393 user "bob";
395 private_key "/home/bob/.ssh/id_rsa"; # passphrase-less key
396 public_key "/home/bob/.ssh/id_rsa.pub";
397 key_auth;
399 krb5_auth
401 If you want to use kerberos authentication, then you need to call
402 krb5_auth. This authentication mechanism is only available if you use
403 Net::OpenSSH.
404 set connection => "OpenSSH";
406 user "root";
407 krb5_auth;
408 parallelism($count)
410 Will execute the tasks in parallel on the given servers. $count is the
411 thread count to be used:
412 parallelism '2'; # set parallelism to 2
414 Alternatively, the following notation can be used to set thread count
416 more dynamically:
417 parallelism 'max'; # set parallelism to the number of servers a task is asked to run on
419 parallelism 'max/3'; # set parallelism to 1/3 of the number of servers
420 parallelism 'max 10%'; # set parallelism to 10% of the number of servers
421 If an unrecognized value is passed, or the calculated thread count
423 would be less than 1, Rex falls back to use a single thread.
424 proxy_command($cmd)
426 Set a proxy command to use for the connection. This is only possible
427 with OpenSSH connection method.
428 set connection => "OpenSSH";
430 proxy_command "ssh user@jumphost nc %h %p 2>/dev/null";
431 set_distributor($distributor)
433 This sets the task distribution module. Default is "Base".
434 Possible values are: Base, Gearman, Parallel_ForkManager
436 template_function(sub { ... })
438 This function sets the template processing function. So it is possible
439 to change the template engine. For example to Template::Toolkit.
440 logging
442 With this function you can define the logging behaviour of (R)?ex.
443 Logging to a file
445 logging to_file => "rex.log";
446 Logging to syslog
448 logging to_syslog => $facility;
449 needs($package [, @tasks])
451 With needs you can define dependencies between tasks. The "needed"
452 tasks will be called with the same server configuration as the calling
453 task.
454 needs will not execute before, around and after hooks.
456 Depend on all tasks in a given package.
458 Depend on all tasks in the package MyPkg. All tasks will be called
459 with the server server1.
460 task "mytask", "server1", sub {
462 needs MyPkg;
463 };
464 Depend on a single task in a given package.
466 Depend on the uname task in the package MyPkg. The uname task will
467 be called with the server server1.
468 task "mytask", "server1", sub {
470 needs MyPkg "uname";
471 };
472 To call tasks defined in the Rexfile from within a module
474 task "mytask", "server1", sub {
475 needs main "uname";
476 };
477 include Module::Name
479 Include a module without registering its tasks.
480 include qw/
482 Module::One
483 Module::Two
484 /;
485 environment($name => $code)
487 Define an environment. With environments one can use the same task for
488 different hosts. For example if you want to use the same task on your
489 integration-, test- and production servers.
490 # define default user/password
492 user "root";
493 password "foobar";
494 pass_auth;
495 # define default frontend group containing only testwww01.
497 group frontend => "testwww01";
498 # define live environment, with different user/password
500 # and a frontend server group containing www01, www02 and www03.
501 environment live => sub {
502 user "root";
503 password "livefoo";
504 pass_auth;
505 group frontend => "www01", "www02", "www03";
507 };
508 # define stage environment with default user and password. but with
510 # a own frontend group containing only stagewww01.
511 environment stage => sub {
512 group frontend => "stagewww01";
513 };
514 task "prepare", group => "frontend", sub {
516 say run "hostname";
517 };
518 Calling this task rex prepare will execute on testwww01. Calling this
520 task with rex -E live prepare will execute on www01, www02, www03.
521 Calling this task rex -E stage prepare will execute on stagewww01.
522 You can call the function within a task to get the current environment.
524 task "prepare", group => "frontend", sub {
526 if(environment() eq "dev") {
527 say "i'm in the dev environment";
528 }
529 };
530 If no -E option is passed on the command line, the default environment
532 (named 'default') will be used.
533 LOCAL(&)
535 With the LOCAL function you can do local commands within a task that is
536 defined to work on remote servers.
537 task "mytask", "server1", "server2", sub {
539 # this will call 'uptime' on the servers 'server1' and 'server2'
540 say run "uptime";
541 # this will call 'uptime' on the local machine.
543 LOCAL {
544 say run "uptime";
545 };
546 };
547 path(@path)
549 Set the execution path for all commands.
550 path "/bin", "/sbin", "/usr/bin", "/usr/sbin", "/usr/pkg/bin", "/usr/pkg/sbin";
552 It's a convenience wrapper for the set_path configuration option.
554 set($key, $value)
556 Set a configuration parameter. These variables can be used in templates
557 as well.
558 set database => "db01";
560 task "prepare", sub {
562 my $db = get "database";
563 };
564 Or in a template
566 DB: <%= $::database %>
568 The following list of configuration parameters are Rex specific:
570 get($key, $value)
572 Get a configuration parameter.
573 set database => "db01";
575 task "prepare", sub {
577 my $db = get "database";
578 };
579 Or in a template
581 DB: <%= $::database %>
583 before($task => sub {})
585 Run code before executing the specified task.
586 The task name is a regular expression to find all tasks with a matching
588 name. The special task name 'ALL' can also be used to run code before
589 all tasks.
590 If called repeatedly, each sub will be appended to a list of 'before'
592 functions.
593 In this hook you can overwrite the server to which the task will
595 connect to. The second argument is a reference to the server object
596 that will be used for the connection.
597 Please note, this must come after the definition of the specified task.
599 before mytask => sub {
601 my ($server, $server_ref, $cli_args) = @_;
602 run "vzctl start vm$server";
603 };
604 after($task => sub {})
606 Run code after executing the specified task.
607 The task name is a regular expression to find all tasks with a matching
609 name. The special task name 'ALL' can be used to run code after all
610 tasks.
611 If called repeatedly, each sub will be appended to a list of 'after'
613 functions.
614 Please note, this must come after the definition of the specified task.
616 after mytask => sub {
618 my ($server, $failed, $cli_args) = @_;
619 if($failed) { say "Connection to $server failed."; }
620 run "vzctl stop vm$server";
622 };
623 around($task => sub {})
625 Run code around the specified task (that is both before and after
626 executing it).
627 The task name is a regular expression to find all tasks with a matching
629 name. The special task name 'ALL' can be used to run code around all
630 tasks.
631 If called repeatedly, each sub will be appended to a list of 'around'
633 functions.
634 In this hook you can overwrite the server to which the task will
636 connect to. The second argument is a reference to the server object
637 that will be used for the connection.
638 Please note, this must come after the definition of the specified task.
640 around mytask => sub {
642 my ($server, $server_ref, $cli_args, $position) = @_;
643 unless($position) {
645 say "Before Task\n";
646 }
647 else {
648 say "After Task\n";
649 }
650 };
651 before_task_start($task => sub {})
653 Run code before executing the specified task. This gets executed only
654 once for a task.
655 The task name is a regular expression to find all tasks with a matching
657 name. The special task name 'ALL' can be used to run code before all
658 tasks.
659 If called repeatedly, each sub will be appended to a list of
661 'before_task_start' functions.
662 Please note, this must come after the definition of the specified task.
664 before_task_start mytask => sub {
666 # do some things
667 };
668 after_task_finished($task => sub {})
670 Run code after the task is finished (and after the ssh connection is
671 terminated). This gets executed only once for a task.
672 The task name is a regular expression to find all tasks with a matching
674 name. The special task name 'ALL' can be used to run code after all
675 tasks.
676 If called repeatedly, each sub will be appended to a list of
678 'after_task_finished' functions.
679 Please note, this must come after the definition of the specified task.
681 after_task_finished mytask => sub {
683 # do some things
684 };
685 logformat($format)
687 You can define the logging format with the following parameters.
688 %D - Appends the current date yyyy-mm-dd HH:mm:ss
690 %h - The target host
692 %p - The pid of the running process
694 %l - Loglevel (INFO or DEBUG)
696 %s - The Logstring
698 Default is: [%D] %l - %s
700 connection
702 This function returns the current connection object.
703 task "foo", group => "baz", sub {
705 say "Current Server: " . connection->server;
706 };
707 cache
709 This function returns the current cache object.
710 profiler
712 Returns the profiler object for the current connection.
713 report($switch, $type)
715 This function will initialize the reporting.
716 report -on => "YAML";
718 source_global_profile(0|1)
720 If this option is set, every run() command will first source
721 /etc/profile before getting executed.
722 last_command_output
724 This function returns the output of the last "run" command.
725 On a debian system this example will return the output of apt-get
727 install foobar.
728 task "mytask", "myserver", sub {
730 install "foobar";
731 say last_command_output();
732 };
733 case($compare, $option)
735 This is a function to compare a string with some given options.
736 task "mytask", "myserver", sub {
738 my $ntp_service = case operating_system, {
739 Debian => "ntp",
740 default => "ntpd",
741 };
742 my $ntp_service = case operating_system, {
744 qr{debian}i => "ntp",
745 default => "ntpd",
746 };
747 my $ntp_service = case operating_system, {
749 qr{debian}i => "ntp",
750 default => sub { return "foo"; },
751 };
752 };
753 set_executor_for($type, $executor)
755 Set the executor for a special type. This is primary used for the
756 upload_and_run helper function.
757 set_executor_for perl => "/opt/local/bin/perl";
759 tmp_dir($tmp_dir)
761 Set the tmp directory on the remote host to store temporary files.
762 inspect($varRef)
764 This function dumps the contents of a variable to STDOUT.
765 task "mytask", "myserver", sub {
767 my $myvar = {
768 name => "foo",
769 sys => "bar",
770 };
771 inspect $myvar;
773 };
774 sayformat($format)
776 You can define the format of the say() function.
777 %D - The current date yyyy-mm-dd HH:mm:ss
779 %h - The target host
781 %p - The pid of the running process
783 %s - The Logstring
785 You can also define the following values:
787 default - the default behaviour.
789 asis - will print every single parameter in its own line. This is
791 useful if you want to print the output of a command.
792perl v5.36.1 2023-08-07 Rex::Commands(3)