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       You can also specify server options after a server name with a hash
170       reference:
171
172        group "servergroup", "www1" => { user => "other" }, "www2";
173
174       These expressions are allowed:
175
176       ·   \d+..\d+ (range)
177
178           The first number is the start and the second number is the end for
179           numbering the servers.
180
181            group "name", "www[1..3]"; # www1, www2, www3
182
183       ·   \d+..\d+/\d+ (range with step)
184
185           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
189            group "name", "www[1..5/2]";      # www1, www3, www5
190            group "name", "www[111..133/11]"; # www111, www122, www133
191
192       ·   \d+,\d+,\d+ (list)
193
194           With this variant you can define fixed values.
195
196            group "name", "www[1,3,7,01]"; # www1, www3, www7, www01
197
198       ·   Mixed list, range and range with step
199
200           You can mix the three variants above
201
202            www[1..3,5,9..21/3]; # www1, www2, www3, www5, www9, www12, www15, www18, www21
203
204   batch($name, @tasks)
205       With the batch function you can call tasks in a batch.
206
207        batch "name", "task1", "task2", "task3";
208
209       And call it with the -b console parameter. rex -b name
210
211   user($user)
212       Set the user for the ssh connection.
213
214   password($password)
215       Set the password for the ssh connection (or for the private key file).
216
217   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
222       If you want to set special login information for a group you have to
223       activate that feature first.
224
225        use Rex -feature => 0.31; # activate setting auth for a group
226
227        # auth for groups
228
229        group frontends => "web[01..10]";
230        group backends => "be[01..05]";
231
232        auth for => "frontends" =>
233                   user => "root",
234                   password => "foobar";
235
236        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
242        # auth for tasks
243
244        task "prepare", group => ["frontends", "backends"], sub {
245          # do something
246        };
247
248        auth for => "prepare" =>
249                   user => "root";
250
251        # auth for multiple tasks with regular expression
252
253        task "step_1", sub {
254         # do something
255        };
256
257        task "step_2", sub {
258         # do something
259        };
260
261        auth for => qr/step/ =>
262          user     => $user,
263          password => $password;
264
265        # 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
279   port($port)
280       Set the port where the ssh server is listening.
281
282   sudo_password($password)
283       Set the password for the sudo command.
284
285   timeout($seconds)
286       Set the timeout for the ssh connection and other network related stuff.
287
288   max_connect_retries($count)
289       Set the maximum number of connection retries.
290
291   get_random($count, @chars)
292       Returns a random string of $count characters on the basis of @chars.
293
294        my $rnd = get_random(8, 'a' .. 'z');
295
296   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
300        task "task1", "server1", sub {
301          say "Running on server1";
302          do_task "task2";
303        };
304
305        task "task2", "server2", sub {
306          say "Running on server2";
307        };
308
309       You may also use an arrayRef for $task if you want to call multiple
310       tasks.
311
312        do_task [ qw/task1 task2 task3/ ];
313
314   run_task($task_name, %option)
315       Run a task on a given host.
316
317        my $return = run_task "taskname", on => "192.168.3.56";
318
319       Do something on server5 if memory is less than 100 MB free on server3.
320
321        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
329        task "get_free_mem", sub {
330           return memory->{free};
331        };
332
333       If called without a hostname the task is run localy.
334
335        # 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
341        task "check_something", "server4", sub {
342          return "foo";
343        };
344
345       If you want to add custom parameters for the task you can do it this
346       way.
347
348        task "prepare", "server5", sub {
349         run_task "check_something", on => "foo", params => { param1 => "value1", param2 => "value2" };
350        };
351
352   run_batch($batch_name, %option)
353       Run a batch on a given host.
354
355        my @return = run_batch "batchname", on => "192.168.3.56";
356
357       It calls internally run_task, and passes it any option given.
358
359   public_key($key)
360       Set the public key.
361
362   private_key($key)
363       Set the private key.
364
365   pass_auth
366       If you want to use password authentication, then you need to call
367       pass_auth.
368
369        user "root";
370        password "root";
371
372        pass_auth;
373
374   key_auth
375       If you want to use pubkey authentication, then you need to call
376       key_auth.
377
378        user "bob";
379        private_key "/home/bob/.ssh/id_rsa"; # passphrase-less key
380        public_key "/home/bob/.ssh/id_rsa.pub";
381
382        key_auth;
383
384   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
389        set connection => "OpenSSH";
390        user "root";
391        krb5_auth;
392
393   parallelism($count)
394       Will execute the tasks in parallel on the given servers. $count is the
395       thread count to be used:
396
397        parallelism '2'; # set parallelism to 2
398
399       Alternatively, the following notation can be used to set thread count
400       more dynamically:
401
402        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
406       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
409   proxy_command($cmd)
410       Set a proxy command to use for the connection. This is only possible
411       with OpenSSH connection method.
412
413        set connection => "OpenSSH";
414        proxy_command "ssh user@jumphost nc %h %p 2>/dev/null";
415
416   set_distributor($distributor)
417       This sets the task distribution module. Default is "Base".
418
419       Possible values are: Base, Gearman, Parallel_ForkManager
420
421   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
425   logging
426       With this function you can define the logging behaviour of (R)?ex.
427
428       Logging to a file
429            logging to_file => "rex.log";
430
431       Logging to syslog
432            logging to_syslog => $facility;
433
434   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
439       needs will not execute before, around and after hooks.
440
441       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
445            task "mytask", "server1", sub {
446              needs MyPkg;
447            };
448
449       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
453            task "mytask", "server1", sub {
454              needs MyPkg "uname";
455            };
456
457       To call tasks defined in the Rexfile from within a module
458            task "mytask", "server1", sub {
459              needs main "uname";
460            };
461
462   include Module::Name
463       Include a module without registering its tasks.
464
465         include qw/
466           Module::One
467           Module::Two
468         /;
469
470   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
475        # define default user/password
476        user "root";
477        password "foobar";
478        pass_auth;
479
480        # define default frontend group containing only testwww01.
481        group frontend => "testwww01";
482
483        # 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
490          group frontend => "www01", "www02", "www03";
491        };
492
493        # 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
499        task "prepare", group => "frontend", sub {
500           say run "hostname";
501        };
502
503       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
507       You can call the function within a task to get the current environment.
508
509        task "prepare", group => "frontend", sub {
510          if(environment() eq "dev") {
511            say "i'm in the dev environment";
512          }
513        };
514
515       If no -E option is passed on the command line, the default environment
516       (named 'default') will be used.
517
518   LOCAL(&)
519       With the LOCAL function you can do local commands within a task that is
520       defined to work on remote servers.
521
522        task "mytask", "server1", "server2", sub {
523           # this will call 'uptime' on the servers 'server1' and 'server2'
524           say run "uptime";
525
526           # this will call 'uptime' on the local machine.
527           LOCAL {
528             say run "uptime";
529           };
530        };
531
532   path(@path)
533       Set the execution path for all commands.
534
535        path "/bin", "/sbin", "/usr/bin", "/usr/sbin", "/usr/pkg/bin", "/usr/pkg/sbin";
536
537   set($key, $value)
538       Set a configuration parameter. These variables can be used in templates
539       as well.
540
541        set database => "db01";
542
543        task "prepare", sub {
544          my $db = get "database";
545        };
546
547       Or in a template
548
549        DB: <%= $::database %>
550
551       The following list of configuration parameters are Rex specific:
552
553   get($key, $value)
554       Get a configuration parameter.
555
556        set database => "db01";
557
558        task "prepare", sub {
559          my $db = get "database";
560        };
561
562       Or in a template
563
564        DB: <%= $::database %>
565
566   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
571       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
575       Note: must come after the definition of the specified task
576
577        before mytask => sub {
578         my ($server, $server_ref, $cli_args) = @_;
579         run "vzctl start vm$server";
580        };
581
582   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
587       Note: must come after the definition of the specified task
588
589        after mytask => sub {
590         my ($server, $failed, $cli_args) = @_;
591         if($failed) { say "Connection to $server failed."; }
592
593         run "vzctl stop vm$server";
594        };
595
596   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
601       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
605       Note: must come after the definition of the specified task
606
607        around mytask => sub {
608         my ($server, $server_ref, $cli_args, $position) = @_;
609
610         unless($position) {
611           say "Before Task\n";
612         }
613         else {
614           say "After Task\n";
615         }
616        };
617
618   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
624       Note: must come after the definition of the specified task
625
626        before_task_start mytask => sub {
627          # do some things
628        };
629
630   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
637       Note: must come after the definition of the specified task
638
639        after_task_finished mytask => sub {
640          # do some things
641        };
642
643   logformat($format)
644       You can define the logging format with the following parameters.
645
646       %D - Appends the current date yyyy-mm-dd HH:mm:ss
647
648       %h - The target host
649
650       %p - The pid of the running process
651
652       %l - Loglevel (INFO or DEBUG)
653
654       %s - The Logstring
655
656       Default is: [%D] %l - %s
657
658   connection
659       This function returns the current connection object.
660
661        task "foo", group => "baz", sub {
662          say "Current Server: " . connection->server;
663        };
664
665   cache
666       This function returns the current cache object.
667
668   profiler
669       Returns the profiler object for the current connection.
670
671   report($switch, $type)
672       This function will initialize the reporting.
673
674        report -on => "YAML";
675
676   source_global_profile(0|1)
677       If this option is set, every run() command will first source
678       /etc/profile before getting executed.
679
680   last_command_output
681       This function returns the output of the last "run" command.
682
683       On a debian system this example will return the output of apt-get
684       install foobar.
685
686        task "mytask", "myserver", sub {
687          install "foobar";
688          say last_command_output();
689        };
690
691   case($compare, $option)
692       This is a function to compare a string with some given options.
693
694        task "mytask", "myserver", sub {
695          my $ntp_service = case operating_sytem, {
696                        Debian  => "ntp",
697                        default => "ntpd",
698                      };
699
700          my $ntp_service = case operating_sytem, {
701                        qr{debian}i => "ntp",
702                        default    => "ntpd",
703                      };
704
705          my $ntp_service = case operating_sytem, {
706                        qr{debian}i => "ntp",
707                        default    => sub { return "foo"; },
708                      };
709        };
710
711   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
715        set_executor_for perl => "/opt/local/bin/perl";
716
717   tmp_dir($tmp_dir)
718       Set the tmp directory on the remote host to store temporary files.
719
720   inspect($varRef)
721       This function dumps the contents of a variable to STDOUT.
722
723       task "mytask", "myserver", sub {
724         my $myvar = {
725           name => "foo",
726           sys  => "bar",
727         };
728
729         inspect $myvar;
730       };
731
732   sayformat($format)
733       You can define the format of the say() function.
734
735       %D - The current date yyyy-mm-dd HH:mm:ss
736
737       %h - The target host
738
739       %p - The pid of the running process
740
741       %s - The Logstring
742
743       You can also define the following values:
744
745       default - the default behaviour.
746
747       asis - will print every single parameter in its own line. This is
748       useful if you want to print the output of a command.
749
750
751
752perl v5.28.0                      2017-03-01                  Rex::Commands(3)
Impressum