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 the task, batch, or environment following it.
153
154        desc 'This is the description of the following task';
155        task 'mytask', sub {
156          say 'Do something';
157        };
158
159        desc 'This is the description of the following batch';
160        batch mybatch => 'task1', 'task2', 'task3';
161
162        desc 'This is the description of the following environment';
163        environment production => sub {
164          ...
165        };
166
167   group($name, @servers)
168       With this function you can group servers, so that you don't need to
169       write too much ;-)
170
171        group "servergroup", "www1", "www2", "www3", "memcache01", "memcache02", "memcache03";
172
173       Or with the expression syntax:
174
175        group "servergroup", "www[1..3]", "memcache[01..03]";
176
177       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
180        use Rex -feature => ['use_server_auth'];
181
182        group "servergroup", "www1" => { user => "other" }, "www2";
183
184       These expressions are allowed:
185
186       •   \d+..\d+ (range)
187
188           The first number is the start and the second number is the end for
189           numbering the servers.
190
191            group "name", "www[1..3]"; # www1, www2, www3
192
193       •   \d+..\d+/\d+ (range with step)
194
195           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
199            group "name", "www[1..5/2]";      # www1, www3, www5
200            group "name", "www[111..133/11]"; # www111, www122, www133
201
202       •   \d+,\d+,\d+ (list)
203
204           With this variant you can define fixed values.
205
206            group "name", "www[1,3,7,01]"; # www1, www3, www7, www01
207
208       •   Mixed list, range and range with step
209
210           You can mix the three variants above
211
212            www[1..3,5,9..21/3]; # www1, www2, www3, www5, www9, www12, www15, www18, www21
213
214   batch($name, @tasks)
215       With the batch function you can call tasks in a batch.
216
217        batch "name", "task1", "task2", "task3";
218
219       And call it with the -b console parameter. rex -b name
220
221   user($user)
222       Set the user for the ssh connection.
223
224   password($password)
225       Set the password for the ssh connection (or for the private key file).
226
227   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
234       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
238       Command line options to set locality or authentication details are
239       still taking precedence, and may override these settings.
240
241        # auth for groups
242
243        use Rex -feature => ['0.31']; # activate setting auth for a group
244
245        group frontends => "web[01..10]";
246        group backends => "be[01..05]";
247
248        auth for => "frontends" =>
249                   user => "root",
250                   password => "foobar";
251
252        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
258        # auth for tasks
259
260        task "prepare", group => ["frontends", "backends"], sub {
261          # do something
262        };
263
264        auth for => "prepare" =>
265                   user => "root";
266
267        # auth for multiple tasks with regular expression
268
269        task "step_1", sub {
270         # do something
271        };
272
273        task "step_2", sub {
274         # do something
275        };
276
277        auth for => qr/step/ =>
278          user     => $user,
279          password => $password;
280
281        # 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
295   port($port)
296       Set the port where the ssh server is listening.
297
298   sudo_password($password)
299       Set the password for the sudo command.
300
301   timeout($seconds)
302       Set the timeout for the ssh connection and other network related stuff.
303
304   max_connect_retries($count)
305       Set the maximum number of connection retries.
306
307   get_random($count, @chars)
308       Returns a random string of $count characters on the basis of @chars.
309
310        my $rnd = get_random(8, 'a' .. 'z');
311
312   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
316        task "task1", "server1", sub {
317          say "Running on server1";
318          do_task "task2";
319        };
320
321        task "task2", "server2", sub {
322          say "Running on server2";
323        };
324
325       You may also use an arrayRef for $task if you want to call multiple
326       tasks.
327
328        do_task [ qw/task1 task2 task3/ ];
329
330   run_task($task_name, %option)
331       Run a task on a given host.
332
333        my $return = run_task "taskname", on => "192.168.3.56";
334
335       Do something on server5 if memory is less than 100 MB free on server3.
336
337        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
345        task "get_free_mem", sub {
346           return memory->{free};
347        };
348
349       If called without a hostname the task is run localy.
350
351        # 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
357        task "check_something", "server4", sub {
358          return "foo";
359        };
360
361       If you want to add custom parameters for the task you can do it this
362       way.
363
364        task "prepare", "server5", sub {
365         run_task "check_something", on => "foo", params => { param1 => "value1", param2 => "value2" };
366        };
367
368   run_batch($batch_name, %option)
369       Run a batch on a given host.
370
371        my @return = run_batch "batchname", on => "192.168.3.56";
372
373       It calls internally run_task, and passes it any option given.
374
375   public_key($key)
376       Set the public key.
377
378   private_key($key)
379       Set the private key.
380
381   pass_auth
382       If you want to use password authentication, then you need to call
383       pass_auth.
384
385        user "root";
386        password "root";
387
388        pass_auth;
389
390   key_auth
391       If you want to use pubkey authentication, then you need to call
392       key_auth.
393
394        user "bob";
395        private_key "/home/bob/.ssh/id_rsa"; # passphrase-less key
396        public_key "/home/bob/.ssh/id_rsa.pub";
397
398        key_auth;
399
400   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
405        set connection => "OpenSSH";
406        user "root";
407        krb5_auth;
408
409   parallelism($count)
410       Will execute the tasks in parallel on the given servers. $count is the
411       thread count to be used:
412
413        parallelism '2'; # set parallelism to 2
414
415       Alternatively, the following notation can be used to set thread count
416       more dynamically:
417
418        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
422       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
425   proxy_command($cmd)
426       Set a proxy command to use for the connection. This is only possible
427       with OpenSSH connection method.
428
429        set connection => "OpenSSH";
430        proxy_command "ssh user@jumphost nc %h %p 2>/dev/null";
431
432   set_distributor($distributor)
433       This sets the task distribution module. Default is "Base".
434
435       Possible values are: Base, Gearman, Parallel_ForkManager
436
437   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
441   logging
442       With this function you can define the logging behaviour of (R)?ex.
443
444       Logging to a file
445            logging to_file => "rex.log";
446
447       Logging to syslog
448            logging to_syslog => $facility;
449
450   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
455       needs will not execute before, around and after hooks.
456
457       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
461            task "mytask", "server1", sub {
462              needs MyPkg;
463            };
464
465       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
469            task "mytask", "server1", sub {
470              needs MyPkg "uname";
471            };
472
473       To call tasks defined in the Rexfile from within a module
474            task "mytask", "server1", sub {
475              needs main "uname";
476            };
477
478   include Module::Name
479       Include a module without registering its tasks.
480
481         include qw/
482           Module::One
483           Module::Two
484         /;
485
486   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
491        # define default user/password
492        user "root";
493        password "foobar";
494        pass_auth;
495
496        # define default frontend group containing only testwww01.
497        group frontend => "testwww01";
498
499        # 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
506          group frontend => "www01", "www02", "www03";
507        };
508
509        # 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
515        task "prepare", group => "frontend", sub {
516           say run "hostname";
517        };
518
519       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
523       You can call the function within a task to get the current environment.
524
525        task "prepare", group => "frontend", sub {
526          if(environment() eq "dev") {
527            say "i'm in the dev environment";
528          }
529        };
530
531       If no -E option is passed on the command line, the default environment
532       (named 'default') will be used.
533
534   LOCAL(&)
535       With the LOCAL function you can do local commands within a task that is
536       defined to work on remote servers.
537
538        task "mytask", "server1", "server2", sub {
539           # this will call 'uptime' on the servers 'server1' and 'server2'
540           say run "uptime";
541
542           # this will call 'uptime' on the local machine.
543           LOCAL {
544             say run "uptime";
545           };
546        };
547
548   path(@path)
549       Set the execution path for all commands.
550
551        path "/bin", "/sbin", "/usr/bin", "/usr/sbin", "/usr/pkg/bin", "/usr/pkg/sbin";
552
553       It's a convenience wrapper for the set_path configuration option.
554
555   set($key, $value)
556       Set a configuration parameter. These variables can be used in templates
557       as well.
558
559        set database => "db01";
560
561        task "prepare", sub {
562          my $db = get "database";
563        };
564
565       Or in a template
566
567        DB: <%= $::database %>
568
569       The following list of configuration parameters are Rex specific:
570
571   get($key, $value)
572       Get a configuration parameter.
573
574        set database => "db01";
575
576        task "prepare", sub {
577          my $db = get "database";
578        };
579
580       Or in a template
581
582        DB: <%= $::database %>
583
584   before($task => sub {})
585       Run code before executing the specified task.
586
587       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
591       If called repeatedly, each sub will be appended to a list of 'before'
592       functions.
593
594       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
598       Please note, this must come after the definition of the specified task.
599
600        before mytask => sub {
601         my ($server, $server_ref, $cli_args) = @_;
602         run "vzctl start vm$server";
603        };
604
605   after($task => sub {})
606       Run code after executing the specified task.
607
608       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
612       If called repeatedly, each sub will be appended to a list of 'after'
613       functions.
614
615       Please note, this must come after the definition of the specified task.
616
617        after mytask => sub {
618         my ($server, $failed, $cli_args) = @_;
619         if($failed) { say "Connection to $server failed."; }
620
621         run "vzctl stop vm$server";
622        };
623
624   around($task => sub {})
625       Run code around the specified task (that is both before and after
626       executing it).
627
628       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
632       If called repeatedly, each sub will be appended to a list of 'around'
633       functions.
634
635       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
639       Please note, this must come after the definition of the specified task.
640
641        around mytask => sub {
642         my ($server, $server_ref, $cli_args, $position) = @_;
643
644         unless($position) {
645           say "Before Task\n";
646         }
647         else {
648           say "After Task\n";
649         }
650        };
651
652   before_task_start($task => sub {})
653       Run code before executing the specified task. This gets executed only
654       once for a task.
655
656       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
660       If called repeatedly, each sub will be appended to a list of
661       'before_task_start' functions.
662
663       Please note, this must come after the definition of the specified task.
664
665        before_task_start mytask => sub {
666          # do some things
667        };
668
669   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
673       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
677       If called repeatedly, each sub will be appended to a list of
678       'after_task_finished' functions.
679
680       Please note, this must come after the definition of the specified task.
681
682        after_task_finished mytask => sub {
683          # do some things
684        };
685
686   logformat($format)
687       You can define the logging format with the following parameters.
688
689       %D - Appends the current date yyyy-mm-dd HH:mm:ss
690
691       %h - The target host
692
693       %p - The pid of the running process
694
695       %l - Loglevel (INFO or DEBUG)
696
697       %s - The Logstring
698
699       Default is: [%D] %l - %s
700
701   connection
702       This function returns the current connection object.
703
704        task "foo", group => "baz", sub {
705          say "Current Server: " . connection->server;
706        };
707
708   cache
709       This function returns the current cache object.
710
711   profiler
712       Returns the profiler object for the current connection.
713
714   report($switch, $type)
715       This function will initialize the reporting.
716
717        report -on => "YAML";
718
719   source_global_profile(0|1)
720       If this option is set, every run() command will first source
721       /etc/profile before getting executed.
722
723   last_command_output
724       This function returns the output of the last "run" command.
725
726       On a debian system this example will return the output of apt-get
727       install foobar.
728
729        task "mytask", "myserver", sub {
730          install "foobar";
731          say last_command_output();
732        };
733
734   case($compare, $option)
735       This is a function to compare a string with some given options.
736
737        task "mytask", "myserver", sub {
738          my $ntp_service = case operating_system, {
739                        Debian  => "ntp",
740                        default => "ntpd",
741                      };
742
743          my $ntp_service = case operating_system, {
744                        qr{debian}i => "ntp",
745                        default    => "ntpd",
746                      };
747
748          my $ntp_service = case operating_system, {
749                        qr{debian}i => "ntp",
750                        default    => sub { return "foo"; },
751                      };
752        };
753
754   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
758        set_executor_for perl => "/opt/local/bin/perl";
759
760   tmp_dir($tmp_dir)
761       Set the tmp directory on the remote host to store temporary files.
762
763   inspect($varRef)
764       This function dumps the contents of a variable to STDOUT.
765
766        task "mytask", "myserver", sub {
767          my $myvar = {
768            name => "foo",
769            sys  => "bar",
770          };
771
772          inspect $myvar;
773        };
774
775   sayformat($format)
776       You can define the format of the say() function.
777
778       %D - The current date yyyy-mm-dd HH:mm:ss
779
780       %h - The target host
781
782       %p - The pid of the running process
783
784       %s - The Logstring
785
786       You can also define the following values:
787
788       default - the default behaviour.
789
790       asis - will print every single parameter in its own line. This is
791       useful if you want to print the output of a command.
792
793
794
795perl v5.38.0                      2023-08-07                  Rex::Commands(3)
Impressum