5,576
edits
Changes
From SME Server
Jump to navigationJump to searchCreated page with "{{Level|Developer}} === 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 displa..."
{{Level|Developer}}
=== 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 "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/
[[Category:Howto]]
[[Category:SME Server Development Framework]]
[[Category:Development Tools]]
[[Category:SME9-Development]]
=== 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 "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/
[[Category:Howto]]
[[Category:SME Server Development Framework]]
[[Category:Development Tools]]
[[Category:SME9-Development]]
