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

NAME

6       Rex - the friendly automation framework
7

DESCRIPTION

9       Rex is an automation framework that is friendly to any combinations of
10       local and remote execution, push and pull style of management, or
11       imperative and declarative approach.
12
13       Its flexibility makes it a great fit for many different use cases, but
14       most commonly Rex is used to automate application deployment and data
15       center infrastructure management tasks.
16
17       See Rex::Commands for a starting point of available built-in commands.
18
19       See rex <https://metacpan.org/pod/distribution/Rex/bin/rex> for more
20       information about how to use rex on the command line.
21

SYNOPSIS

23           # In a Rexfile:
24           use Rex -feature => [qw/1.4/];
25
26           user "root";
27           password "ch4ngem3";
28
29           desc "Show system information";
30           task "sysinfo", sub {
31              say run "uname -a";
32           };
33
34           1;
35
36           # On the command line:
37           $ rex -H server[01..10] sysinfo
38

CLASS METHODS

40   get_current_connection
41       This function is deprecated since 0.28! See Rex::Commands::connection.
42
43       Returns the current connection as a hashRef.
44
45       server
46           The server name
47
48       ssh 1 if it is a ssh connection, 0 if not.
49
50   is_ssh
51       Returns 1 if the current connection is a ssh connection. 0 if not.
52
53   is_local
54       Returns 1 if the current connection is local. Otherwise 0.
55
56   is_sudo
57       Returns 1 if the current operation is executed within sudo.
58
59   get_sftp
60       Returns the sftp object for the current ssh connection.
61
62   connect
63       Use this function to create a connection if you use Rex as a library.
64
65        use Rex;
66        use Rex::Commands::Run;
67        use Rex::Commands::Fs;
68
69        Rex::connect(
70          server    => "remotehost",
71          user      => "root",
72          password   => "f00b4r",
73          private_key => "/path/to/private/key/file",
74          public_key  => "/path/to/public/key/file",
75        );
76
77        if(is_file("/foo/bar")) {
78          print "Do something...\n";
79        }
80
81        my $output = run("uptime");
82

FEATURE FLAGS

84       Everyone knows the pain if something gets deprecated and one has to
85       port his old (and stable) code to a new version of a library or a
86       framework. There is enough work to do instead of fixing code to work
87       with newer versions of them.
88
89       So there is one promise new versions of Rex has to fulfill. They must
90       be backward compatible.
91
92       I know this might be impossible in one way or another, but to minimize
93       this danger there is a thing called feature flags. If there is the need
94       to break backward compatibility in favor of a new feature there will be
95       a feature flag for this change. And only if this feature flag gets
96       enabled in the Rexfile it will break compatibility.
97
98       So the default is always to remain compatible.
99
100       If you have a problem that occurs after an update, it is considered as
101       a bug. Please report this bug in our issue tracker.
102
103       Also see the backwards compatibility
104       <https://metacpan.org/release/Rex/source/CONTRIBUTING.md#backwardscompatibility>
105       section of the CONTRIBUTING guide.
106
107   How to enable feature flags
108       You can enable feature flags in your Rexfile with the following code:
109
110           use Rex -feature => ['1.4'];
111
112       or even multiple ones like this:
113
114           use Rex -feature => [qw(1.4 exec_autodie)];
115
116   List of feature flags
117       1.4 Enable per-task argument parsing (task_chaining_cmdline_args).
118           Furthermore, all features from earlier versions are activated.
119           Available since version 1.4.
120
121       no_task_chaining_cmdline_args
122           Disable per-task argument parsing. Available since version 1.4.
123
124       task_chaining_cmdline_args
125           Enable per-task argument parsing: "rex --rex --args task1
126           --task1arg=value task2 --task2arg" so task1 only gets "task1arg"
127           and task2 only gets "task2arg". Available since version 1.4.
128
129       1.3 Activating the new template engine by default. Furthermore, all
130           features from earlier versions are activated. Available since
131           version 1.3.
132
133       no_template_ng
134           Disabling the new template engine. Available since version 1.3.
135
136       1.0 Disabling usage of a tty. This increases compatibility for remote
137           execution. Furthermore, all features from earlier versions are
138           activated. Available since version 1.0.
139
140       no_autodie
141           Will disable autodie feature. Available since version 1.0.
142
143       tty Enable pty usage for ssh connections. Available since version 1.0.
144
145       template_ng
146           Enabling the new template engine (better error reporting, etc.).
147           Available since version 0.56.
148
149       0.56
150           Will activate autodie feature. Furthermore, all features from
151           earlier versions are activated. Available since version 0.56.
152
153       autodie
154           Will enable autodie feature: die on all failed filesystem commands
155           <https://metacpan.org/pod/Rex::Commands::Fs>. Available since
156           version 1.13.1.
157
158       0.55
159           Will activate using Net::OpenSSH by default if present.
160           Furthermore, all features from earlier versions are activated.
161           Available since version 0.55.
162
163       0.54
164           Will activate checking services for existence before trying to
165           manipulate them, and "set()" will overwrite already existing values
166           (instead of concatenating). Furthermore, all features from earlier
167           versions are activated. Available since version 0.54.
168
169       0.53
170           Will activate register_cmdb_top_scope. And all things 0.51 and down
171           activated. Available since version 0.53.
172
173       register_cmdb_top_scope
174           Will register all cmdb top scope variables automatically in the
175           templates. Available since version 0.53.
176
177       0.51
178           Will load Rex::Constants and the CMDB by default. And all things
179           0.47 and down activated. Available since version 0.51.
180
181       disable_taskname_warning
182           Disable warning about invalid task names (they should match
183           "/^[a-zA-Z_][a-zA-Z0-9_]*$/"). Available since version 0.47.
184
185       verbose_run
186           Explicitly output "Successfully executed" or "Error executing"
187           messages for "run()" commands. Available since version 0.47.
188
189       no_cache
190           Disable caching (like discovery results of remote OS, hardware,
191           shell, etc.). Available since version 0.46.
192
193       no_path_cleanup
194           Rex cleans the path before executing a command. With this feature
195           Rex doesn't cleanup the path. Available since version 0.44.
196
197       source_profile
198           Source "$HOME/.profile" before running a command. Available since
199           version 0.44.
200
201       source_global_profile
202           Source "/etc/profile" before running a command. Available since
203           version 0.44.
204
205       exec_autodie
206           If you execute a command with "run()" Rex will "die()" if the
207           command returns a "RETVAL != 0". Available since version 0.44.
208
209       exec_and_sleep
210           Sometimes some commands that fork away didn't keep running. With
211           this flag rex will wait a few ms before exiting the shell.
212           Available since version 0.43.
213
214       disable_strict_host_key_checking
215           Disabling strict host key checking for openssh connection mode.
216           Available since version 0.43.
217
218       reporting
219           Enable reporting. Available since version 0.43.
220
221       empty_groups
222           Enable usage of empty groups. Available since version 0.42.
223
224       use_server_auth
225           Enable the usage of special authentication options for servers.
226           Available since version 0.42.
227
228       no_tty
229           Disable pty usage for ssh connections. Available since version
230           0.41.
231
232       no_local_template_vars
233           Use global variables in templates. Available since version 0.40.
234
235       sudo_without_sh
236           Run sudo commands directly without the use of 'sh'. This might
237           break things. Available since version 0.40.
238
239       sudo_without_locales
240           Run sudo commands without locales. This will break things if you
241           don't use English locales. Available since version 0.40.
242
243       exit_status
244           This option tells Rex to return a non zero value on exit if a task
245           fails. Available since version 0.39.
246
247       0.35
248           This option enables the features of 0.31 and the possibility to
249           call tasks as a functions without the need to use a hash reference
250           for the parameters. Available since version 0.35.
251
252       0.31
253           To enable special authentication options for a server group. This
254           will overwrite the default authentication options for a task.
255           Available since version 0.31.
256

CONTRIBUTORS

258       Many thanks to the contributors for their work. Please see CONTRIBUTORS
259       <https://metacpan.org/release/Rex/source/CONTRIBUTORS> file for a
260       complete list.
261

LICENSE

263       Rex is a free software, licensed under: The Apache License, Version
264       2.0, January 2004
265
266
267
268perl v5.36.0                      2022-07-20                            Rex(3)
Impressum