1Rex(3) User Contributed Perl Documentation Rex(3)
2
6 Rex - the friendly automation framework
7
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 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 See Rex::Commands for a starting point of available built-in commands.
18 See rex <https://metacpan.org/pod/distribution/Rex/bin/rex> for more
20 information about how to use rex on the command line.
21
23 # In a Rexfile:
24 use Rex -feature => [qw/1.4/];
25 user "root";
27 password "ch4ngem3";
28 desc "Show system information";
30 task "sysinfo", sub {
31 say run "uname -a";
32 };
33 1;
35 # On the command line:
37 $ rex -H server[01..10] sysinfo
38
40 get_current_connection
41 This function is deprecated since 0.28! See Rex::Commands::connection.
42 Returns the current connection as a hashRef.
44 server
46 The server name
47 ssh 1 if it is a ssh connection, 0 if not.
49 is_ssh
51 Returns 1 if the current connection is a ssh connection. 0 if not.
52 is_local
54 Returns 1 if the current connection is local. Otherwise 0.
55 is_sudo
57 Returns 1 if the current operation is executed within sudo.
58 get_sftp
60 Returns the sftp object for the current ssh connection.
61 connect
63 Use this function to create a connection if you use Rex as a library.
64 use Rex;
66 use Rex::Commands::Run;
67 use Rex::Commands::Fs;
68 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 if(is_file("/foo/bar")) {
78 print "Do something...\n";
79 }
80 my $output = run("uptime");
82
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 So there is one promise new versions of Rex has to fulfill. They must
90 be backward compatible.
91 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 So the default is always to remain compatible.
99 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 Also see the backwards compatibility
104 <https://metacpan.org/release/Rex/source/CONTRIBUTING.md#backwardscompatibility>
105 section of the CONTRIBUTING guide.
106 How to enable feature flags
108 You can enable feature flags in your Rexfile with the following code:
109 use Rex -feature => ['1.4'];
111 or even multiple ones like this:
113 use Rex -feature => [qw(1.4 exec_autodie)];
115 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 no_task_chaining_cmdline_args
122 Disable per-task argument parsing. Available since version 1.4.
123 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 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 no_template_ng
134 Disabling the new template engine. Available since version 1.3.
135 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 no_autodie
141 Will disable autodie feature. Available since version 1.0.
142 tty Enable pty usage for ssh connections. Available since version 1.0.
144 template_ng
146 Enabling the new template engine (better error reporting, etc.).
147 Available since version 0.56.
148 0.56
150 Will activate autodie feature. Furthermore, all features from
151 earlier versions are activated. Available since version 0.56.
152 autodie
154 Will enable autodie feature: die on all failed filesytem commands
155 <https://metacpan.org/pod/Rex::Commands::Fs>. Available since
156 version 1.13.1.
157 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 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 0.53
170 Will activate register_cmdb_top_scope. And all things 0.51 and down
171 activated. Available since version 0.53.
172 register_cmdb_top_scope
174 Will register all cmdb top scope variables automatically in the
175 templates. Available since version 0.53.
176 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 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 verbose_run
186 Explicitly output "Successfully executed" or "Error executing"
187 messages for "run()" commands. Available since version 0.47.
188 no_cache
190 Disable caching (like discovery results of remote OS, hardware,
191 shell, etc.). Available since version 0.46.
192 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 source_profile
198 Source "$HOME/.profile" before running a command. Available since
199 version 0.44.
200 source_global_profile
202 Source "/etc/profile" before running a command. Available since
203 version 0.44.
204 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 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 disable_strict_host_key_checking
215 Disabling strict host key checking for openssh connection mode.
216 Available since version 0.43.
217 reporting
219 Enable reporting. Available since version 0.43.
220 empty_groups
222 Enable usage of empty groups. Available since version 0.42.
223 use_server_auth
225 Enable the usage of special authentication options for servers.
226 Available since version 0.42.
227 no_tty
229 Disable pty usage for ssh connections. Available since version
230 0.41.
231 no_local_template_vars
233 Use global variables in templates. Available since version 0.40.
234 sudo_without_sh
236 Run sudo commands directly without the use of 'sh'. This might
237 break things. Available since version 0.40.
238 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 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 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 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
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
263 Rex is a free software, licensed under: The Apache License, Version
264 2.0, January 2004
265perl v5.32.1 2021-03-06 Rex(3)