Esmith::templates
NAME
esmith::template - Utilities for e-smith server and gateway development
In a root terminal you can do the command below if you want to display the up-to-date content
perldoc esmith::templates
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 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
AUTHOR
Mitel Networks Corporation For more information, see http://www.e-smith.org/