Render Ruby Templates Safely with erb3.2

Someone hands you a config template with a few values to fill in at build time, and erb3.2 already does that without a full Ruby script. This guide covers passing values from the command line, controlling whitespace, and reading the Ruby that ERB generates behind an expression. It targets the installed erb3.2 from ruby3.2 package version 3.2.3-1ubuntu0.24.04.8, which reports ERB version 4.0.2. Give it about 15 minutes if Ruby and the template are ready.

You need a shell, a readable template, and permission to write to the output directory. Rendering evaluates Ruby from the template, so treat every template as code, not as inert text. Do not render an untrusted file just to preview it, and skip sudo: nothing here needs root.

1. Confirm the installed command

Check which executable will run and record its version:

$ command -v erb3.2
/usr/bin/erb3.2
$ erb3.2 --version
4.0.2

The unversioned erb name is an alias on this installation. Use erb3.2 in scripts when you need the Ruby 3.2 command selected explicitly.

Checkpoint: If the command is missing, stop and install the Ruby package through your normal package-management process. Do not work around a missing executable by copying a different system's script into /usr/local/bin.

2. Render a value into a template

ERB copies ordinary text and evaluates code in <% ... %> tags. An expression in <%= ... %> is inserted into the output. The command accepts var=value assignments after its switches and before the input file:

$ printf '%s\n' 'Hello, <%= name %>!' | erb3.2 name=Ruby
Hello, Ruby!

For a file, replace standard input with its path:

$ erb3.2 name=Ruby greeting.erb > greeting.html
$ sed -n '1,5p' greeting.html

The output is written to standard output. Shell redirection creates or truncates the destination before erb3.2 runs, so do not point it at the template or at a useful existing output.

3. Add control flow and repeated output

Use ordinary Ruby statements for setup and flow control. The following reads a list, then emits one line per value:

<% names = ['Ada', 'Grace'] %>
<% names.each do |name| %>
<%= name %>
<% end %>

Render it from standard input and inspect the result:

$ erb3.2 -T - < names.erb
Ada
Grace

The -T - trim mode removes the newline around lines whose ERB directive starts with <% and ends with %>, which is useful when control-flow tags would otherwise leave blank lines. The default trim mode is 0, where the end-of-line remains. Modes 1 and 2 remove specific end-of-line cases; choose one deliberately and verify the resulting whitespace.

4. Make percent-prefixed lines explicit

With trim mode -, a line ending in -%> loses its newline, and leading whitespace is removed when the directive starts with <%-. A line beginning with % is also treated as Ruby code by the underlying ERB processing. If your source contains literal percent-led text, use -P to disable that special treatment:

$ printf '%s\n' '% this remains text' | erb3.2 -P -
% this remains text

Do not add -P mechanically to a template that relies on percent-prefixed Ruby lines. If the result has unexpected blank lines, compare the default output with one trim mode at a time rather than editing several tags at once.

5. Check encodings and libraries

Use -U to set the default internal encoding to UTF-8. Use -E external:internal when the input and internal encodings need explicit values. You can omit the internal value after the colon; the manual says that leaves Ruby's default internal encoding as nil:

$ printf '%s\n' '<%= __ENCODING__ %>' | erb3.2 -U -
UTF-8

Load a Ruby library with -r when the template uses it. For example, the installed command can load the standard prime library while rendering:

$ printf '%s\n' '<%= Prime.each(10).to_a.join(", ") %>' | erb3.2 -r prime -
2, 3, 5, 7

Loading a library is executable behaviour, not a harmless formatting option. Keep the library list short and review it when a template changes.

6. Inspect a failure before changing the template

This is where ERB stops being friendly: syntax errors and runtime errors both land on standard error, in Ruby's own words rather than a template-flavoured one. Preserve the input and run a small diagnostic first:

$ erb3.2 report.erb > /tmp/report.html
$ status=$?
$ printf 'erb3.2 exit status: %s\n' "$status"
$ test "$status" -eq 0

Exit status 0 means the command completed. A non-zero status means the output may be incomplete, so do not deploy or rename it, however tempting that is at the end of a long day. The temporary path prevents a failed render from destroying the previous report. When the content is correct, replace the destination explicitly:

$ mv /tmp/report.html report.html

If you need to see what ERB will execute, use -x:

$ printf '%s\n' 'Hello, <%= 1 + 1 %>' | erb3.2 -x -
#coding:UTF-8
_erbout = +''; _erbout.<< "Hello, ".freeze; _erbout.<<(( 1 + 1 ).to_s); _erbout.<< "\n".freeze
; _erbout

Use -n with -x when generated Ruby line numbers will help locate a template line. This output is diagnostic Ruby source, not the rendered document.

Done means