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 You can also specify server options after a server name with a hash
170 reference:
171 group "servergroup", "www1" => { user => "other" }, "www2";
173 These expressions are allowed:
175 · \d+..\d+ (range)
177 The first number is the start and the second number is the end for
179 numbering the servers.
180 group "name", "www[1..3]"; # www1, www2, www3
182 · \d+..\d+/\d+ (range with step)
184 Just like the range notation, but with an additional "step"
186 defined. If step is omitted, it defaults to 1 (i.e. it behaves
187 like a simple range expression).
188 group "name", "www[1..5/2]"; # www1, www3, www5
190 group "name", "www[111..133/11]"; # www111, www122, www133
191 · \d+,\d+,\d+ (list)
193 With this variant you can define fixed values.
195 group "name", "www[1,3,7,01]"; # www1, www3, www7, www01
197 · Mixed list, range and range with step
199 You can mix the three variants above
201 www[1..3,5,9..21/3]; # www1, www2, www3, www5, www9, www12, www15, www18, www21
203 batch($name, @tasks)
205 With the batch function you can call tasks in a batch.
206 batch "name", "task1", "task2", "task3";
208 And call it with the -b console parameter. rex -b name
210 user($user)
212 Set the user for the ssh connection.
213 password($password)
215 Set the password for the ssh connection (or for the private key file).
216 auth(for => $entity, %data)
218 With this function you can modify/set special authentication parameters
219 for tasks and groups. If you want to modify a group's authentication
220 you first have to create it. (Place the auth command after the group.)
221 If you want to set special login information for a group you have to
223 activate that feature first.
224 use Rex -feature => 0.31; # activate setting auth for a group
226 # auth for groups
228 group frontends => "web[01..10]";
230 group backends => "be[01..05]";
231 auth for => "frontends" =>
233 user => "root",
234 password => "foobar";
235 auth for => "backends" =>
237 user => "admin",
238 private_key => "/path/to/id_rsa",
239 public_key => "/path/to/id_rsa.pub",
240 sudo => TRUE;
241 # auth for tasks
243 task "prepare", group => ["frontends", "backends"], sub {
245 # do something
246 };
247 auth for => "prepare" =>
249 user => "root";
250 # auth for multiple tasks with regular expression
252 task "step_1", sub {
254 # do something
255 };
256 task "step_2", sub {
258 # do something
259 };
260 auth for => qr/step/ =>
262 user => $user,
263 password => $password;
264 # fallback auth
266 auth fallback => {
267 user => "fallback_user1",
268 password => "fallback_pw1",
269 public_key => "",
270 private_key => "",
271 }, {
272 user => "fallback_user2",
273 password => "fallback_pw2",
274 public_key => "keys/public.key",
275 private_key => "keys/private.key",
276 sudo => TRUE,
277 };
278 port($port)
280 Set the port where the ssh server is listening.
281 sudo_password($password)
283 Set the password for the sudo command.
284 timeout($seconds)
286 Set the timeout for the ssh connection and other network related stuff.
287 max_connect_retries($count)
289 Set the maximum number of connection retries.
290 get_random($count, @chars)
292 Returns a random string of $count characters on the basis of @chars.
293 my $rnd = get_random(8, 'a' .. 'z');
295 do_task($task)
297 Call $task from another task. It will establish a new connection to the
298 server defined in $task and then execute $task there.
299 task "task1", "server1", sub {
301 say "Running on server1";
302 do_task "task2";
303 };
304 task "task2", "server2", sub {
306 say "Running on server2";
307 };
308 You may also use an arrayRef for $task if you want to call multiple
310 tasks.
311 do_task [ qw/task1 task2 task3/ ];
313 run_task($task_name, %option)
315 Run a task on a given host.
316 my $return = run_task "taskname", on => "192.168.3.56";
318 Do something on server5 if memory is less than 100 MB free on server3.
320 task "prepare", "server5", sub {
322 my $free_mem = run_task "get_free_mem", on => "server3";
323 if($free_mem < 100) {
324 say "Less than 100 MB free mem on server3";
325 # create a new server instance on server5 to unload server3
326 }
327 };
328 task "get_free_mem", sub {
330 return memory->{free};
331 };
332 If called without a hostname the task is run localy.
334 # this task will run on server5
336 task "prepare", "server5", sub {
337 # this will call task check_something. but this task will run on localhost.
338 my $check = run_task "check_something";
339 }
340 task "check_something", "server4", sub {
342 return "foo";
343 };
344 If you want to add custom parameters for the task you can do it this
346 way.
347 task "prepare", "server5", sub {
349 run_task "check_something", on => "foo", params => { param1 => "value1", param2 => "value2" };
350 };
351 run_batch($batch_name, %option)
353 Run a batch on a given host.
354 my @return = run_batch "batchname", on => "192.168.3.56";
356 It calls internally run_task, and passes it any option given.
358 public_key($key)
360 Set the public key.
361 private_key($key)
363 Set the private key.
364 pass_auth
366 If you want to use password authentication, then you need to call
367 pass_auth.
368 user "root";
370 password "root";
371 pass_auth;
373 key_auth
375 If you want to use pubkey authentication, then you need to call
376 key_auth.
377 user "bob";
379 private_key "/home/bob/.ssh/id_rsa"; # passphrase-less key
380 public_key "/home/bob/.ssh/id_rsa.pub";
381 key_auth;
383 krb5_auth
385 If you want to use kerberos authentication, then you need to call
386 krb5_auth. This authentication mechanism is only available if you use
387 Net::OpenSSH.
388 set connection => "OpenSSH";
390 user "root";
391 krb5_auth;
392 parallelism($count)
394 Will execute the tasks in parallel on the given servers. $count is the
395 thread count to be used:
396 parallelism '2'; # set parallelism to 2
398 Alternatively, the following notation can be used to set thread count
400 more dynamically:
401 parallelism 'max'; # set parallelism to the number of servers a task is asked to run on
403 parallelism 'max/3'; # set parallelism to 1/3 of the number of servers
404 parallelism 'max 10%'; # set parallelism to 10% of the number of servers
405 If an unrecognized value is passed, or the calculated thread count
407 would be less than 1, Rex falls back to use a single thread.
408 proxy_command($cmd)
410 Set a proxy command to use for the connection. This is only possible
411 with OpenSSH connection method.
412 set connection => "OpenSSH";
414 proxy_command "ssh user@jumphost nc %h %p 2>/dev/null";
415 set_distributor($distributor)
417 This sets the task distribution module. Default is "Base".
418 Possible values are: Base, Gearman, Parallel_ForkManager
420 template_function(sub { ... })
422 This function sets the template processing function. So it is possible
423 to change the template engine. For example to Template::Toolkit.
424 logging
426 With this function you can define the logging behaviour of (R)?ex.
427 Logging to a file
429 logging to_file => "rex.log";
430 Logging to syslog
432 logging to_syslog => $facility;
433 needs($package [, @tasks])
435 With needs you can define dependencies between tasks. The "needed"
436 tasks will be called with the same server configuration as the calling
437 task.
438 needs will not execute before, around and after hooks.
440 Depend on all tasks in a given package.
442 Depend on all tasks in the package MyPkg. All tasks will be called
443 with the server server1.
444 task "mytask", "server1", sub {
446 needs MyPkg;
447 };
448 Depend on a single task in a given package.
450 Depend on the uname task in the package MyPkg. The uname task will
451 be called with the server server1.
452 task "mytask", "server1", sub {
454 needs MyPkg "uname";
455 };
456 To call tasks defined in the Rexfile from within a module
458 task "mytask", "server1", sub {
459 needs main "uname";
460 };
461 include Module::Name
463 Include a module without registering its tasks.
464 include qw/
466 Module::One
467 Module::Two
468 /;
469 environment($name => $code)
471 Define an environment. With environments one can use the same task for
472 different hosts. For example if you want to use the same task on your
473 integration-, test- and production servers.
474 # define default user/password
476 user "root";
477 password "foobar";
478 pass_auth;
479 # define default frontend group containing only testwww01.
481 group frontend => "testwww01";
482 # define live environment, with different user/password
484 # and a frontend server group containing www01, www02 and www03.
485 environment live => sub {
486 user "root";
487 password "livefoo";
488 pass_auth;
489 group frontend => "www01", "www02", "www03";
491 };
492 # define stage environment with default user and password. but with
494 # a own frontend group containing only stagewww01.
495 environment stage => sub {
496 group frontend => "stagewww01";
497 };
498 task "prepare", group => "frontend", sub {
500 say run "hostname";
501 };
502 Calling this task rex prepare will execute on testwww01. Calling this
504 task with rex -E live prepare will execute on www01, www02, www03.
505 Calling this task rex -E stage prepare will execute on stagewww01.
506 You can call the function within a task to get the current environment.
508 task "prepare", group => "frontend", sub {
510 if(environment() eq "dev") {
511 say "i'm in the dev environment";
512 }
513 };
514 If no -E option is passed on the command line, the default environment
516 (named 'default') will be used.
517 LOCAL(&)
519 With the LOCAL function you can do local commands within a task that is
520 defined to work on remote servers.
521 task "mytask", "server1", "server2", sub {
523 # this will call 'uptime' on the servers 'server1' and 'server2'
524 say run "uptime";
525 # this will call 'uptime' on the local machine.
527 LOCAL {
528 say run "uptime";
529 };
530 };
531 path(@path)
533 Set the execution path for all commands.
534 path "/bin", "/sbin", "/usr/bin", "/usr/sbin", "/usr/pkg/bin", "/usr/pkg/sbin";
536 set($key, $value)
538 Set a configuration parameter. These variables can be used in templates
539 as well.
540 set database => "db01";
542 task "prepare", sub {
544 my $db = get "database";
545 };
546 Or in a template
548 DB: <%= $::database %>
550 The following list of configuration parameters are Rex specific:
552 get($key, $value)
554 Get a configuration parameter.
555 set database => "db01";
557 task "prepare", sub {
559 my $db = get "database";
560 };
561 Or in a template
563 DB: <%= $::database %>
565 before($task => sub {})
567 Run code before executing the specified task. The special taskname
568 'ALL' can be used to run code before all tasks. If called repeatedly,
569 each sub will be appended to a list of 'before' functions.
570 In this hook you can overwrite the server to which the task will
572 connect to. The second argument is a reference to the server object
573 that will be used for the connection.
574 Note: must come after the definition of the specified task
576 before mytask => sub {
578 my ($server, $server_ref, $cli_args) = @_;
579 run "vzctl start vm$server";
580 };
581 after($task => sub {})
583 Run code after the task is finished. The special taskname 'ALL' can be
584 used to run code after all tasks. If called repeatedly, each sub will
585 be appended to a list of 'after' functions.
586 Note: must come after the definition of the specified task
588 after mytask => sub {
590 my ($server, $failed, $cli_args) = @_;
591 if($failed) { say "Connection to $server failed."; }
592 run "vzctl stop vm$server";
594 };
595 around($task => sub {})
597 Run code before and after the task is finished. The special taskname
598 'ALL' can be used to run code around all tasks. If called repeatedly,
599 each sub will be appended to a list of 'around' functions.
600 In this hook you can overwrite the server to which the task will
602 connect to. The second argument is a reference to the server object
603 that will be used for the connection.
604 Note: must come after the definition of the specified task
606 around mytask => sub {
608 my ($server, $server_ref, $cli_args, $position) = @_;
609 unless($position) {
611 say "Before Task\n";
612 }
613 else {
614 say "After Task\n";
615 }
616 };
617 before_task_start($task => sub {})
619 Run code before executing the specified task. This gets executed only
620 once for a task. The special taskname 'ALL' can be used to run code
621 before all tasks. If called repeatedly, each sub will be appended to a
622 list of 'before_task_start' functions.
623 Note: must come after the definition of the specified task
625 before_task_start mytask => sub {
627 # do some things
628 };
629 after_task_finished($task => sub {})
631 Run code after the task is finished (and after the ssh connection is
632 terminated). This gets executed only once for a task. The special
633 taskname 'ALL' can be used to run code before all tasks. If called
634 repeatedly, each sub will be appended to a list of
635 'after_task_finished' functions.
636 Note: must come after the definition of the specified task
638 after_task_finished mytask => sub {
640 # do some things
641 };
642 logformat($format)
644 You can define the logging format with the following parameters.
645 %D - Appends the current date yyyy-mm-dd HH:mm:ss
647 %h - The target host
649 %p - The pid of the running process
651 %l - Loglevel (INFO or DEBUG)
653 %s - The Logstring
655 Default is: [%D] %l - %s
657 connection
659 This function returns the current connection object.
660 task "foo", group => "baz", sub {
662 say "Current Server: " . connection->server;
663 };
664 cache
666 This function returns the current cache object.
667 profiler
669 Returns the profiler object for the current connection.
670 report($switch, $type)
672 This function will initialize the reporting.
673 report -on => "YAML";
675 source_global_profile(0|1)
677 If this option is set, every run() command will first source
678 /etc/profile before getting executed.
679 last_command_output
681 This function returns the output of the last "run" command.
682 On a debian system this example will return the output of apt-get
684 install foobar.
685 task "mytask", "myserver", sub {
687 install "foobar";
688 say last_command_output();
689 };
690 case($compare, $option)
692 This is a function to compare a string with some given options.
693 task "mytask", "myserver", sub {
695 my $ntp_service = case operating_sytem, {
696 Debian => "ntp",
697 default => "ntpd",
698 };
699 my $ntp_service = case operating_sytem, {
701 qr{debian}i => "ntp",
702 default => "ntpd",
703 };
704 my $ntp_service = case operating_sytem, {
706 qr{debian}i => "ntp",
707 default => sub { return "foo"; },
708 };
709 };
710 set_executor_for($type, $executor)
712 Set the executor for a special type. This is primary used for the
713 upload_and_run helper function.
714 set_executor_for perl => "/opt/local/bin/perl";
716 tmp_dir($tmp_dir)
718 Set the tmp directory on the remote host to store temporary files.
719 inspect($varRef)
721 This function dumps the contents of a variable to STDOUT.
722 task "mytask", "myserver", sub {
724 my $myvar = {
725 name => "foo",
726 sys => "bar",
727 };
728 inspect $myvar;
730 };
731 sayformat($format)
733 You can define the format of the say() function.
734 %D - The current date yyyy-mm-dd HH:mm:ss
736 %h - The target host
738 %p - The pid of the running process
740 %s - The Logstring
742 You can also define the following values:
744 default - the default behaviour.
746 asis - will print every single parameter in its own line. This is
748 useful if you want to print the output of a command.
749perl v5.30.0 2019-07-24 Rex::Commands(3)