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 filesystem 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 Controls whether Rex should use the default or explicitly
195 configured "PATH" settings when executing commands or not. See also
196 the path command and the set_path configuration option. Available
197 since version 0.44.
198 source_profile
200 Source "$HOME/.profile" before running a command. Available since
201 version 0.44.
202 source_global_profile
204 Source "/etc/profile" before running a command. Available since
205 version 0.44.
206 exec_autodie
208 If you execute a command with run() Rex will die() if the command
209 returns a "RETVAL != 0". Available since version 0.44.
210 exec_and_sleep
212 Sometimes some commands that fork away didn't keep running. With
213 this flag rex will wait a few ms before exiting the shell.
214 Available since version 0.43.
215 disable_strict_host_key_checking
217 Disabling strict host key checking for openssh connection mode.
218 Available since version 0.43.
219 reporting
221 Enable reporting. Available since version 0.43.
222 empty_groups
224 Enable usage of empty groups. Available since version 0.42.
225 use_server_auth
227 Enable the usage of special authentication options for servers.
228 Available since version 0.42.
229 no_tty
231 Disable pty usage for ssh connections. Available since version
232 0.41.
233 no_local_template_vars
235 Use global variables in templates. Available since version 0.40.
236 sudo_without_sh
238 Run sudo commands directly without the use of 'sh'. This might
239 break things. Available since version 0.40.
240 sudo_without_locales
242 Run sudo commands without locales. This will break things if you
243 don't use English locales. Available since version 0.40.
244 exit_status
246 This option tells Rex to return a non zero value on exit if a task
247 fails. Available since version 0.39.
248 0.35
250 This option enables the features of 0.31 and the possibility to
251 call tasks as a functions without the need to use a hash reference
252 for the parameters. Available since version 0.35.
253 0.31
255 To enable special authentication options for a server group. This
256 will overwrite the default authentication options for a task.
257 Available since version 0.31.
258
260 Many thanks to the contributors for their work. Please see CONTRIBUTORS
261 <https://metacpan.org/release/Rex/source/CONTRIBUTORS> file for a
262 complete list.
263
265 Rex is a free software, licensed under: The Apache License, Version
266 2.0, January 2004
267perl v5.38.0 2023-08-07 Rex(3)