• NAME
• VERSION
• SYNOPSIS
• DESCRIPTION
• Template Variables
• Functions
• Filters
• SEE ALSO
• AUTHOR

NAME

esmith::template - Utilities for e-smith server and gateway development

VERSION

This file documents esmith::template version 1.7.0

SYNOPSIS

    use esmith::template;
    processTemplate(...);

DESCRIPTION

This is the interface to the E-Smith templating system. For an overview of how the system works, see section ``3.4 Templated Configuration System'' of the Dev Guide.

esmith::template exports a single function, processTemplate, which, as you might guess, processes sets of templates into a single output file.

Template Variables

The following variables are available to all templates.

$confref

DEPRECATED. Contains a reference to the hash passed in via CONFREF. If none was given it defaults to a tied esmith::config hash.

$DB

Contains a reference to an esmith::ConfigDB object pointing at the default configurations. This is to be used to call methods like $DB-services> and *not* for alterting the database.

In addition, each record in the default esmith configuration database (configuration) is available as a hash if it has multiple properties (where each key/value is a property of the record) or if it has a single property (type) then it given as a scalar.

So you can say:

    { $DomainName }     # $configdb->get('DomainName')->value;
    { $sshd{status} }   # $configdb->get('sshd')->prop('status')

Finally, variables from additional databases are usually gotten via the esmith::DB->as_hash feature.

    {  require esmith::HostsDB;
       my %Hosts = esmith::HostsDB->as_hash;
       ...
    }

Functions

processTemplate

  processTemplate({ CONFREF       => \%config,
                    TEMPLATE_PATH => $output_file
                 });

  $filled_in_template = processTemplate({ CONFREF       => \%config,
                                          TEMPLATE_PATH => $output_file
                                          OUTPUT_TYPE   => 'string'
                                        });

processTemplate() expands a set of templates based on the keys/values in %config.

The options to processTemplate are as follows...

MORE_DATA

A hash ref containing additional variables you'd like to put into the template. Key is the name of the variable, value is it's value.

    # $Foo = 'bar'
    MORE_DATA => { Foo => "bar" }

Any keys in MORE_DATA will override those from the default esmith::ConfigDB.

This replaces CONFREF.

CONFREF

DEPRECATED. A reference to the hash which will become the variables in the template. So $config{Foo} becomes $Foo. In addition, there is the $confref variable which contains a reference back to the original CONFREF.

This is usually a tied esmith::config hash.

This has been replaced by MORE_DATA and cannot be used in conjunction.

TEMPLATE_PATH

Full path to the file which fill result from this template. For example, '/etc/hosts'.

TEMPLATE_EXPAND_QUEUE

List of directories to scan for templates. If not specified it defaults to:

    /etc/e-smith/templates-custom
    /etc/e-smith/templates

it then appends the TEMPLATE_PATH to this, so the resulting search might be:

    /etc/e-smith/templates-custom/etc/host
    /etc/e-smith/templates/etc/host

All templates found are combined in ASCIIbetical order to produce the final file. The exception to this is template-begin, which always comes first, and template-end, which always comes last.

If no template-begin is found the one in /etc/e-smith/templates-default/ will be used.

If two directories contain the same template those eariler in the queue will override those later. So /etc/e-smith/templates-custom/foo will be used instead of /etc/e-smith/templates/foo.

OUTPUT_PREFIX

Directory which contains the OUTPUT_FILENAME.

OUTPUT_FILENAME

The file which results from this template.

Defaults to the TEMPLATE_PATH.

FILTER

A code ref through which each line of the resulting text is fed, for example:

    FILTER => sub { "# $_[0]" }

would put a # in front of each line of the template.

    FILTER => sub { $_[0] =~ /^\s*$/ ? '' : $_[0] }

will remove all lines that contain only whitespace.

UID

GID

The user and group ID by which the resulting file should be owned. This obviously means you have to run procTemplate as root.

Defaults to UID 0 and GID 0.

PERMS

File permissions which the resulting file should be set to have.

Defaults to 0644.

OUTPUT_TYPE

Determines if the filled in template should go straight to a file or be returned by processTemplate(). The values can be:

    string     return the filled in template
    file       write it to disk

Defaults to 'file'

For example we have a template /etc/e-smith/templates/etc/hosts that we want to expand to /etc/hosts using the normal configuration.

    # Records from esmith::ConfigDB->open will be available by default
    processTemplate({
        TEMPLATE_PATH => '/etc/hosts',
    });

Example 2: we have a template /etc/e-smith/templates-user/qmail that we want to expand to /home/e-smith/files/users/$username/.qmail

Solution:

    processTemplate({ 
        TEMPLATE_PATH => '/qmail',
        TEMPLATE_EXPAND_QUEUE => [
            '/etc/e-smith/templates-user-custom',
            '/etc/e-smith/templates-user',
        ],
        OUTPUT_PREFIX => '/home/e-smith/files/users/$username',
        OUTPUT_FILENAME => '.qmail',
        FILTER => sub { $_[0] =~ /^\s*$/ ? '' : $_[0] },
        UID => $username,
        GID => $username,
        PERMS => 0644,
    });

Example 3: we have a template fragment /etc/e-smith/templates/etc/httpd/conf/httpd.conf/80VirtualHosts that needs to iterate through the given list of VirtualHosts, process each template and return the results in a string until all the VirtualHosts have been completed. The results will be expanded into the /etc/httpd/conf/httpd.conf file.

Solution: In the 80VirtualHosts fragment, we use the OUTPUT_TYPE='string' option to return the output of processTemplate for each VirtualHost as a string, and then we add the results to the $OUT variable for inclusion in the httpd.conf template expansion. We store the VirtualHosts template in /etc/httpd/conf/httpd.conf/VirtualHosts for clarity and namespace separation.

    foreach my $ipAddress (keys %ipAddresses)
    {
        # the $OUT variable stores the output of this template fragment
        use esmith::templates;
        $OUT .= processTemplate (
            {
                MORE_DATA => { ipAddress => $ipAddress, port => $port,
                               virtualHosts => \@virtualHosts,
                               virtualHostContent => \%virtualHostContent },
                TEMPLATE_PATH => "/etc/httpd/conf/httpd.conf/VirtualHosts",
                OUTPUT_TYPE => 'string',
            });
    }

Filters

Filters are an experimental feature which allow you to filter the output of a template in various ways.

Filtering functions take a single line at a time and return the filtered version.

removeBlankLines

Removes empty lines or those containing only whitespace from a template.

SEE ALSO

Section 3.4 ``Templated Configuration System'' of the E-Smith Dev Guide

AUTHOR

Mitel Networks Corporation

For more information, see http://www.e-smith.org/