2,411
edits
Changes
Jump to navigation
Jump to search
mLine 1:
Line 1: − + − + Line 21:
Line 21: − + Line 105:
Line 105: − + Line 116:
Line 116: − + Line 132:
Line 132: − + Line 143:
Line 143: − + Line 152:
Line 152: − + Line 199:
Line 199: − + Line 219:
Line 219: − + Line 228:
Line 228: − + − + Line 291:
Line 291: − + Line 323:
Line 323: − + Line 338:
Line 338: − +
SME Server:Documentation:Developers Manual:Chapter8 (view source)
Revision as of 13:31, 25 April 2008
, 13:31, 25 April 2008Adjusting header(s)
<div class="CHAPTER">
<div class="CHAPTER">
=Configuration file templates=
==Configuration file templates==
<div class="SECT1">
<div class="SECT1">
==Design of the template system==
===Design of the template system===
Every piece of software has its own configuration format, and writing parsers for each one is a complex, time-consuming and error-prone process. The SME Server software avoids the whole issue by using templates which <span class="emphasis">''generate''</span> the correct configuration.
Every piece of software has its own configuration format, and writing parsers for each one is a complex, time-consuming and error-prone process. The SME Server software avoids the whole issue by using templates which <span class="emphasis">''generate''</span> the correct configuration.
----
----
==The Text::Template module==
===The Text::Template module===
The <code class="CLASSNAME">Text::Template</code> module allows arbitary Perl code to be embedded in a template file by surrounding it in braces (<var class="LITERAL">"{"</var> and <var class="LITERAL">"}"</var>). The code inside the braces is interpreted and its return value replaces the section between, and including, the braces. For instance:
The <code class="CLASSNAME">Text::Template</code> module allows arbitary Perl code to be embedded in a template file by surrounding it in braces (<var class="LITERAL">"{"</var> and <var class="LITERAL">"}"</var>). The code inside the braces is interpreted and its return value replaces the section between, and including, the braces. For instance:
----
----
===template-begin and template-end===
====template-begin and template-end====
Each template directory can contain two optional files <tt class="FILENAME">template-begin</tt> and <tt class="FILENAME">template-end</tt> . The template-begin file is always processed as the first file of the template, and the template-end file is always processed as the last file.
Each template directory can contain two optional files <tt class="FILENAME">template-begin</tt> and <tt class="FILENAME">template-end</tt> . The template-begin file is always processed as the first file of the template, and the template-end file is always processed as the last file.
----
----
===/etc/e-smith/templates-default===
====/etc/e-smith/templates-default====
The <tt class="FILENAME">/etc/e-smith/templates-default</tt> directory contains a set of template-begin and template-end files for various languages. For example, if your template generates a perl script, you would link <tt class="FILENAME">template-begin</tt> to <tt class="FILENAME">/etc/e-smith/templates-default/template-begin-perl</tt> and automatically get the <var class="LITERAL"><nowiki>#!/usr/bin/perl -w</nowiki></var> line and a comment containing the contents of the default template-begin file.
The <tt class="FILENAME">/etc/e-smith/templates-default</tt> directory contains a set of template-begin and template-end files for various languages. For example, if your template generates a perl script, you would link <tt class="FILENAME">template-begin</tt> to <tt class="FILENAME">/etc/e-smith/templates-default/template-begin-perl</tt> and automatically get the <var class="LITERAL"><nowiki>#!/usr/bin/perl -w</nowiki></var> line and a comment containing the contents of the default template-begin file.
----
----
===Template fragment ordering===
====Template fragment ordering====
Template fragments are assembled in ASCII-betical order, with two exceptions: template-begin always comes first, and template-end always comes last. Template fragments are often named to start with a two digit number to make the ordering obvious, but this is not required.
Template fragments are assembled in ASCII-betical order, with two exceptions: template-begin always comes first, and template-end always comes last. Template fragments are often named to start with a two digit number to make the ordering obvious, but this is not required.
----
----
===Templates for user home directories: templates-user===
====Templates for user home directories: templates-user====
Most of the templates on the system map to single, fixed output files, such as <tt class="FILENAME">/etc/hosts</tt>. However, templates are also used to generate configuration files such as mail delivery instructions for users. These templates are stored in the <tt class="FILENAME">/etc/e-smith/template-user/</tt> tree.
Most of the templates on the system map to single, fixed output files, such as <tt class="FILENAME">/etc/hosts</tt>. However, templates are also used to generate configuration files such as mail delivery instructions for users. These templates are stored in the <tt class="FILENAME">/etc/e-smith/template-user/</tt> tree.
----
----
===Local site overrides: templates-custom and templates-user-custom===
====Local site overrides: templates-custom and templates-user-custom====
It is possible that the standard templates are not correct for a particular installation, and so the local system administrator can override the extsing templates by placing files in the <tt class="FILENAME">templates-custom</tt> tree. This is a parallel tree to the normal templates hierarchy, and is normally empty. There is also a <tt class="FILENAME">template-user-custom</tt> tree for overriding entries in the templates-user tree.
It is possible that the standard templates are not correct for a particular installation, and so the local system administrator can override the extsing templates by placing files in the <tt class="FILENAME">templates-custom</tt> tree. This is a parallel tree to the normal templates hierarchy, and is normally empty. There is also a <tt class="FILENAME">template-user-custom</tt> tree for overriding entries in the templates-user tree.
----
----
===How to resolve conflicts with standard templates===
====How to resolve conflicts with standard templates====
It is possible that the standard templates may specify behaviour which is not appropriate for your application. In many cases the templates will be driven by configuration database settings which allow their behaviour to be customized, which should be the first thing to check.
It is possible that the standard templates may specify behaviour which is not appropriate for your application. In many cases the templates will be driven by configuration database settings which allow their behaviour to be customized, which should be the first thing to check.
----
----
===Subdirectory templates===
====Subdirectory templates====
It is also possible to split templates into further subdirectories. This can be very useful for evaluating the same fragments in a loop, for example for each virtual domain in <tt class="FILENAME">httpd.conf</tt> or each ibay in <tt class="FILENAME">smb.conf</tt>.
It is also possible to split templates into further subdirectories. This can be very useful for evaluating the same fragments in a loop, for example for each virtual domain in <tt class="FILENAME">httpd.conf</tt> or each ibay in <tt class="FILENAME">smb.conf</tt>.
----
----
==Template expansion==
===Template expansion===
<div class="SECT2">
<div class="SECT2">
===Mapping templates to events: templates2expand===
====Mapping templates to events: templates2expand====
The SME Server is designed to ensure consistent and reliable operation, without requiring command-line access. Whenever an event is signalled, the relevant templates for that event are expanded and the services are notified of the configuration changes.
The SME Server is designed to ensure consistent and reliable operation, without requiring command-line access. Whenever an event is signalled, the relevant templates for that event are expanded and the services are notified of the configuration changes.
----
----
===Template permissions and ownership: templates.metadata===
====Template permissions and ownership: templates.metadata====
Templates are normally expanded to be owned by <var class="LITERAL">root</var> and are not executable, which is a reasonable default for most configuration files. However, templates may need to generate configuration files which are owned by a different user, or which need to be executable or have other special permissions. This can be done by creating a <var class="LITERAL">templates.metadata</var> file which defines the additional attributes for the expansion.
Templates are normally expanded to be owned by <var class="LITERAL">root</var> and are not executable, which is a reasonable default for most configuration files. However, templates may need to generate configuration files which are owned by a different user, or which need to be executable or have other special permissions. This can be done by creating a <var class="LITERAL">templates.metadata</var> file which defines the additional attributes for the expansion.
----
----
===Manual testing: expand-template===
====Manual testing: expand-template====
It is sometimes useful to expand templates manually during testing, which can be done with the '''expand-template''' command. The syntax of this command is simply:
It is sometimes useful to expand templates manually during testing, which can be done with the '''expand-template''' command. The syntax of this command is simply:
----
----
===Perl API: processTemplate===
====Perl API: processTemplate====
In rare circumstances you may need to call '''processTemplate''' directly. Explicit calls to '''processTemplate''' are typically only used when the output filename is variable, such as when processing the <var class="LITERAL">.qmail</var> files for each group:
In rare circumstances you may need to call '''processTemplate''' directly. Explicit calls to '''processTemplate''' are typically only used when the output filename is variable, such as when processing the <var class="LITERAL">.qmail</var> files for each group: