1Rex::Commands(3)      User Contributed Perl Documentation     Rex::Commands(3)
2
3
4

NAME

6       Rex::Commands - All the basic commands
7

DESCRIPTION

9       This module is the core commands module.
10

SYNOPSIS

12        desc "Task description";
13
14        task "taskname", sub { ... };
15        task "taskname", "server1", ..., "server20", sub { ... };
16
17        group "group" => "server1", "server2", ...;
18
19        user "user";
20
21        password "password";
22
23        environment live => sub {
24          user "root";
25          password "foobar";
26          pass_auth;
27          group frontend => "www01", "www02";
28        };
29

COMMANDLIST

31       •   Augeas config file management library Rex::Commands::Augeas
32
33       •   Cloud Management Rex::Commands::Cloud
34
35       •   Cron Management Rex::Commands::Cron
36
37       •   Database Commands Rex::Commands::DB
38
39       •   SCP Up- and Download Rex::Commands::Upload, Rex::Commands::Download
40
41       •   File Manipulation Rex::Commands::File
42
43       •   Filesystem Manipulation Rex::Commands::Fs
44
45       •   Information Gathering Rex::Commands::Gather
46
47       •   Manipulation of /etc/hosts Rex::Commands::Host
48
49       •   Get an inventory of your Hardware Rex::Commands::Inventory
50
51       •   Manage your iptables rules Rex::Commands::Iptables
52
53       •   Kernel Commands Rex::Commands::Kernel
54
55       •   LVM Commands Rex::Commands::LVM
56
57       •   MD5 checksums Rex::Commands::MD5
58
59       •   Network commands Rex::Commands::Network
60
61       •   Notify resources to execute Rex::Commands::Notify
62
63       •   Package Commands Rex::Commands::Pkg
64
65       •   Partition your storage device(s) Rex::Commands::Partition
66
67       •   Configure packages (via debconf) Rex::Commands::PkgConf
68
69       •   Process Management Rex::Commands::Process
70
71       •   Rsync Files Rex::Commands::Rsync
72
73       •   Run Remote Commands Rex::Commands::Run
74
75       •   Source control via Subversion/Git Rex::Commands::SCM
76
77       •   Manage System Services (sysvinit) Rex::Commands::Service
78
79       •   Simple TCP/alive checks Rex::Commands::SimpleCheck
80
81       •   Sync directories Rex::Commands::Sync
82
83       •   Sysctl Commands Rex::Commands::Sysctl
84
85       •   Live Tail files Rex::Commands::Tail
86
87       •   Upload local file to remote server Rex::Commands::Upload
88
89       •   Manage user and group accounts Rex::Commands::User
90
91       •   Manage your virtual environments Rex::Commands::Virtualization
92

EXPORTED FUNCTIONS

94   no_ssh([$task])
95       Disable ssh for all tasks or a specified task.
96
97       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
101        no_ssh;
102
103       If you want to disable ssh connection for a given task, put no_ssh in
104       front of the task definition.
105
106        no_ssh task "mytask", "myserver", sub {
107          say "Do something without a ssh connection";
108        };
109
110   task($name [, @servers], $funcref)
111       This function will create a new task.
112
113       Create a local task (a server independent task)
114            task "mytask", sub {
115              say "Do something";
116            };
117
118           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
122       Create a server bound task.
123            task "mytask", "server1", sub {
124              say "Do something";
125            };
126
127           You can also specify more than one server.
128
129            task "mytask", "server1", "server2", "server3", sub {
130              say "Do something";
131            };
132
133           Or you can use some expressions to define more than one server.
134
135            task "mytask", "server[1..3]", sub {
136              say "Do something";
137            };
138
139           If you want, you can overwrite the servers with the -H command line
140           parameter.
141
142       Create a group bound task.
143           You can define server groups with the group function.
144
145            group "allserver" => "server[1..3]", "workstation[1..10]";
146
147            task "mytask", group => "allserver", sub {
148              say "Do something";
149            };
150
151   desc($description)
152       Set the description of a task.
153
154        desc "This is a task description of the following task";
155        task "mytask", sub {
156          say "Do something";
157        }
158
159   group($name, @servers)
160       With this function you can group servers, so that you don't need to
161       write too much ;-)
162
163        group "servergroup", "www1", "www2", "www3", "memcache01", "memcache02", "memcache03";
164
165       Or with the expression syntax:
166
167        group "servergroup", "www[1..3]", "memcache[01..03]";
168
169       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
172        use Rex -feature => ['use_server_auth'];
173
174        group "servergroup", "www1" => { user => "other" }, "www2";
175
176       These expressions are allowed:
177
178       •   \d+..\d+ (range)
179
180           The first number is the start and the second number is the end for
181           numbering the servers.
182
183            group "name", "www[1..3]"; # www1, www2, www3
184
185       •   \d+..\d+/\d+ (range with step)
186
187           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
191            group "name", "www[1..5/2]";      # www1, www3, www5
192            group "name", "www[111..133/11]"; # www111, www122, www133
193
194       •   \d+,\d+,\d+ (list)
195
196           With this variant you can define fixed values.
197
198            group "name", "www[1,3,7,01]"; # www1, www3, www7, www01
199
200       •   Mixed list, range and range with step
201
202           You can mix the three variants above
203
204            www[1..3,5,9..21/3]; # www1, www2, www3, www5, www9, www12, www15, www18, www21
205
206   batch($name, @tasks)
207       With the batch function you can call tasks in a batch.
208
209        batch "name", "task1", "task2", "task3";
210
211       And call it with the -b console parameter. rex -b name
212
213   user($user)
214       Set the user for the ssh connection.
215
216   password($password)
217       Set the password for the ssh connection (or for the private key file).
218
219   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
226       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
230       Command line options to set locality or authentication details are
231       still taking precedence, and may override these settings.
232
233        # auth for groups
234
235        use Rex -feature => ['0.31']; # activate setting auth for a group
236
237        group frontends => "web[01..10]";
238        group backends => "be[01..05]";
239
240        auth for => "frontends" =>
241                   user => "root",
242                   password => "foobar";
243
244        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
250        # auth for tasks
251
252        task "prepare", group => ["frontends", "backends"], sub {
253          # do something
254        };
255
256        auth for => "prepare" =>
257                   user => "root";
258
259        # auth for multiple tasks with regular expression
260
261        task "step_1", sub {
262         # do something
263        };
264
265        task "step_2", sub {
266         # do something
267        };
268
269        auth for => qr/step/ =>
270          user     => $user,
271          password => $password;
272
273        # 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
287   port($port)
288       Set the port where the ssh server is listening.
289
290   sudo_password($password)
291       Set the password for the sudo command.
292
293   timeout($seconds)
294       Set the timeout for the ssh connection and other network related stuff.
295
296   max_connect_retries($count)
297       Set the maximum number of connection retries.
298
299   get_random($count, @chars)
300       Returns a random string of $count characters on the basis of @chars.
301
302        my $rnd = get_random(8, 'a' .. 'z');
303
304   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
308        task "task1", "server1", sub {
309          say "Running on server1";
310          do_task "task2";
311        };
312
313        task "task2", "server2", sub {
314          say "Running on server2";
315        };
316
317       You may also use an arrayRef for $task if you want to call multiple
318       tasks.
319
320        do_task [ qw/task1 task2 task3/ ];
321
322   run_task($task_name, %option)
323       Run a task on a given host.
324
325        my $return = run_task "taskname", on => "192.168.3.56";
326
327       Do something on server5 if memory is less than 100 MB free on server3.
328
329        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
337        task "get_free_mem", sub {
338           return memory->{free};
339        };
340
341       If called without a hostname the task is run localy.
342
343        # 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
349        task "check_something", "server4", sub {
350          return "foo";
351        };
352
353       If you want to add custom parameters for the task you can do it this
354       way.
355
356        task "prepare", "server5", sub {
357         run_task "check_something", on => "foo", params => { param1 => "value1", param2 => "value2" };
358        };
359
360   run_batch($batch_name, %option)
361       Run a batch on a given host.
362
363        my @return = run_batch "batchname", on => "192.168.3.56";
364
365       It calls internally run_task, and passes it any option given.
366
367   public_key($key)
368       Set the public key.
369
370   private_key($key)
371       Set the private key.
372
373   pass_auth
374       If you want to use password authentication, then you need to call
375       pass_auth.
376
377        user "root";
378        password "root";
379
380        pass_auth;
381
382   key_auth
383       If you want to use pubkey authentication, then you need to call
384       key_auth.
385
386        user "bob";
387        private_key "/home/bob/.ssh/id_rsa"; # passphrase-less key
388        public_key "/home/bob/.ssh/id_rsa.pub";
389
390        key_auth;
391
392   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
397        set connection => "OpenSSH";
398        user "root";
399        krb5_auth;
400
401   parallelism($count)
402       Will execute the tasks in parallel on the given servers. $count is the
403       thread count to be used:
404
405        parallelism '2'; # set parallelism to 2
406
407       Alternatively, the following notation can be used to set thread count
408       more dynamically:
409
410        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
414       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
417   proxy_command($cmd)
418       Set a proxy command to use for the connection. This is only possible
419       with OpenSSH connection method.
420
421        set connection => "OpenSSH";
422        proxy_command "ssh user@jumphost nc %h %p 2>/dev/null";
423
424   set_distributor($distributor)
425       This sets the task distribution module. Default is "Base".
426
427       Possible values are: Base, Gearman, Parallel_ForkManager
428
429   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
433   logging
434       With this function you can define the logging behaviour of (R)?ex.
435
436       Logging to a file
437            logging to_file => "rex.log";
438
439       Logging to syslog
440            logging to_syslog => $facility;
441
442   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
447       needs will not execute before, around and after hooks.
448
449       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
453            task "mytask", "server1", sub {
454              needs MyPkg;
455            };
456
457       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
461            task "mytask", "server1", sub {
462              needs MyPkg "uname";
463            };
464
465       To call tasks defined in the Rexfile from within a module
466            task "mytask", "server1", sub {
467              needs main "uname";
468            };
469
470   include Module::Name
471       Include a module without registering its tasks.
472
473         include qw/
474           Module::One
475           Module::Two
476         /;
477
478   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
483        # define default user/password
484        user "root";
485        password "foobar";
486        pass_auth;
487
488        # define default frontend group containing only testwww01.
489        group frontend => "testwww01";
490
491        # 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
498          group frontend => "www01", "www02", "www03";
499        };
500
501        # 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
507        task "prepare", group => "frontend", sub {
508           say run "hostname";
509        };
510
511       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
515       You can call the function within a task to get the current environment.
516
517        task "prepare", group => "frontend", sub {
518          if(environment() eq "dev") {
519            say "i'm in the dev environment";
520          }
521        };
522
523       If no -E option is passed on the command line, the default environment
524       (named 'default') will be used.
525
526   LOCAL(&)
527       With the LOCAL function you can do local commands within a task that is
528       defined to work on remote servers.
529
530        task "mytask", "server1", "server2", sub {
531           # this will call 'uptime' on the servers 'server1' and 'server2'
532           say run "uptime";
533
534           # this will call 'uptime' on the local machine.
535           LOCAL {
536             say run "uptime";
537           };
538        };
539
540   path(@path)
541       Set the execution path for all commands.
542
543        path "/bin", "/sbin", "/usr/bin", "/usr/sbin", "/usr/pkg/bin", "/usr/pkg/sbin";
544
545   set($key, $value)
546       Set a configuration parameter. These variables can be used in templates
547       as well.
548
549        set database => "db01";
550
551        task "prepare", sub {
552          my $db = get "database";
553        };
554
555       Or in a template
556
557        DB: <%= $::database %>
558
559       The following list of configuration parameters are Rex specific:
560
561   get($key, $value)
562       Get a configuration parameter.
563
564        set database => "db01";
565
566        task "prepare", sub {
567          my $db = get "database";
568        };
569
570       Or in a template
571
572        DB: <%= $::database %>
573
574   before($task => sub {})
575       Run code before executing the specified task.
576
577       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
581       If called repeatedly, each sub will be appended to a list of 'before'
582       functions.
583
584       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
588       Please note, this must come after the definition of the specified task.
589
590        before mytask => sub {
591         my ($server, $server_ref, $cli_args) = @_;
592         run "vzctl start vm$server";
593        };
594
595   after($task => sub {})
596       Run code after executing the specified task.
597
598       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
602       If called repeatedly, each sub will be appended to a list of 'after'
603       functions.
604
605       Please note, this must come after the definition of the specified task.
606
607        after mytask => sub {
608         my ($server, $failed, $cli_args) = @_;
609         if($failed) { say "Connection to $server failed."; }
610
611         run "vzctl stop vm$server";
612        };
613
614   around($task => sub {})
615       Run code around the specified task (that is both before and after
616       executing it).
617
618       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
622       If called repeatedly, each sub will be appended to a list of 'around'
623       functions.
624
625       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
629       Please note, this must come after the definition of the specified task.
630
631        around mytask => sub {
632         my ($server, $server_ref, $cli_args, $position) = @_;
633
634         unless($position) {
635           say "Before Task\n";
636         }
637         else {
638           say "After Task\n";
639         }
640        };
641
642   before_task_start($task => sub {})
643       Run code before executing the specified task. This gets executed only
644       once for a task.
645
646       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
650       If called repeatedly, each sub will be appended to a list of
651       'before_task_start' functions.
652
653       Please note, this must come after the definition of the specified task.
654
655        before_task_start mytask => sub {
656          # do some things
657        };
658
659   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
663       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
667       If called repeatedly, each sub will be appended to a list of
668       'after_task_finished' functions.
669
670       Please note, this must come after the definition of the specified task.
671
672        after_task_finished mytask => sub {
673          # do some things
674        };
675
676   logformat($format)
677       You can define the logging format with the following parameters.
678
679       %D - Appends the current date yyyy-mm-dd HH:mm:ss
680
681       %h - The target host
682
683       %p - The pid of the running process
684
685       %l - Loglevel (INFO or DEBUG)
686
687       %s - The Logstring
688
689       Default is: [%D] %l - %s
690
691   connection
692       This function returns the current connection object.
693
694        task "foo", group => "baz", sub {
695          say "Current Server: " . connection->server;
696        };
697
698   cache
699       This function returns the current cache object.
700
701   profiler
702       Returns the profiler object for the current connection.
703
704   report($switch, $type)
705       This function will initialize the reporting.
706
707        report -on => "YAML";
708
709   source_global_profile(0|1)
710       If this option is set, every run() command will first source
711       /etc/profile before getting executed.
712
713   last_command_output
714       This function returns the output of the last "run" command.
715
716       On a debian system this example will return the output of apt-get
717       install foobar.
718
719        task "mytask", "myserver", sub {
720          install "foobar";
721          say last_command_output();
722        };
723
724   case($compare, $option)
725       This is a function to compare a string with some given options.
726
727        task "mytask", "myserver", sub {
728          my $ntp_service = case operating_system, {
729                        Debian  => "ntp",
730                        default => "ntpd",
731                      };
732
733          my $ntp_service = case operating_system, {
734                        qr{debian}i => "ntp",
735                        default    => "ntpd",
736                      };
737
738          my $ntp_service = case operating_system, {
739                        qr{debian}i => "ntp",
740                        default    => sub { return "foo"; },
741                      };
742        };
743
744   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
748        set_executor_for perl => "/opt/local/bin/perl";
749
750   tmp_dir($tmp_dir)
751       Set the tmp directory on the remote host to store temporary files.
752
753   inspect($varRef)
754       This function dumps the contents of a variable to STDOUT.
755
756       task "mytask", "myserver", sub {
757         my $myvar = {
758           name => "foo",
759           sys  => "bar",
760         };
761
762         inspect $myvar;
763       };
764
765   sayformat($format)
766       You can define the format of the say() function.
767
768       %D - The current date yyyy-mm-dd HH:mm:ss
769
770       %h - The target host
771
772       %p - The pid of the running process
773
774       %s - The Logstring
775
776       You can also define the following values:
777
778       default - the default behaviour.
779
780       asis - will print every single parameter in its own line. This is
781       useful if you want to print the output of a command.
782
783
784
785perl v5.34.0                      2021-07-21                  Rex::Commands(3)
Impressum