2,411
edits
Changes
Jump to navigation
Jump to search
mLine 1:
Line 1: − + − + Line 13:
Line 13: − + − <div class="NOTE"><blockquote class="NOTE">+ − − '''Note: ''' It is also possible to store templates as single files, rather than as a directory of fragments. This method is preserved for backwards compatibility, but does not provide the extensibility of directory based templates. Directory templates should be used for all new templates, even if that directory only contains a single fragment. − − </blockquote></div></div><div class="SECT1"> − + Line 105:
Line 101: − + Line 116:
Line 112: − + Line 124:
Line 120: − + − <div class="NOTE"><blockquote class="NOTE">+ − − '''Note: '''You may also need a <tt class="FILENAME">templates.metadata</tt> configuration file if your generated file needs to be executable. − − </blockquote></div></div><div class="SECT2"> − + − + − <div class="NOTE"><blockquote class="NOTE">+ − − '''Note: '''The number of fragments and the order of those fragments within a template directory is subject to change between releases. − − </blockquote></div></div><div class="SECT2"> − + Line 152:
Line 140: − + + − <div class="NOTE"><blockquote class="NOTE">+ − − '''Note: '''<span class="emphasis">''Never edit the standard templates.''</span> Your changes will be overwritten when packages are upgraded. − − </blockquote></div><div class="NOTE"><blockquote class="NOTE"> − − '''Note: '''The template-custom trees should be reserved for local system overrides. <span class="emphasis">''Software should not install files in this tree.''</span> − − </blockquote></div> Line 199:
Line 180: − + Line 212:
Line 193: − <div class="NOTE"><blockquote class="NOTE">+ − + − '''Note: '''You should not release RPMs which install templates in the <tt class="FILENAME">templates-custom</tt> directories. If the behaviour of a base template needs to be changed, please raise a bug to discuss the change. − − </blockquote></div></div><div class="SECT2"> − + Line 228:
Line 206: − + − + Line 291:
Line 269: − + − + − <div class="NOTE"><blockquote class="NOTE"> − − '''Note: '''Configuration files should generally <span class="emphasis">''not''</span> be writable by any user other than root. In particular, configuration files should not normally be writable the <span class="emphasis">''www''</span> user as this poses a significant security risk. Installation advice which says "chmod 777" is almost invariably wrong. − − </blockquote></div> Line 309:
Line 282: − <nowiki>TEMPLATE_PATH="/etc/sysconfig/network-scripts/route-ethX" + − + Line 323:
Line 296: − + Line 330:
Line 303: − + − <div class="NOTE"><blockquote class="NOTE">+ − − '''Note: '''<var class="LITERAL">expand-template</var> is designed for testing, and not as the standard way to expand templates. The correct way to ensure that a template is expanded is to create the <var class="LITERAL">templates2expand</var> files in the relevant events, along with any <var class="LITERAL">templates.metadata</var> files which may be required. − − </blockquote></div></div><div class="SECT2"> − + Line 366:
Line 335: − + − <div class="NOTE"><blockquote class="NOTE"> − − '''Note: '''Software which was written for SME Server before release 7 will have a number of scripts which call '''processTemplate'''. In almost all cases, these can be replaced with simple flag files in the <tt class="FILENAME">templates2expand/</tt> directory of the relevant events. The new method is <span class="emphasis">''far''</span> more efficient as a single invocation is perl is used to expand all template files. − − </blockquote></div></div></div></div>
SME Server:Documentation:Developers Manual:Chapter8 (view source)
Revision as of 09:25, 1 June 2008
, 09:25, 1 June 2008Added Template:Note box and Template:Warning box
<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 template fragments are concatenated together in <span class="emphasis">''ASCIIbetical''</span> order (US-ASCII sort order) and the complete file is parsed to generate the appropriate configuration files for the service. The use of fragments is part of the SME Server's modular and extensible architecture; it allows third-party modules to add fragments to the configuration where necessary.
The template fragments are concatenated together in <span class="emphasis">''ASCIIbetical''</span> order (US-ASCII sort order) and the complete file is parsed to generate the appropriate configuration files for the service. The use of fragments is part of the SME Server's modular and extensible architecture; it allows third-party modules to add fragments to the configuration where necessary.
{{Note box|msg=It is also possible to store templates as single files, rather than as a directory of fragments. This method is preserved for backwards compatibility, but does not provide the extensibility of directory based templates. Directory templates should be used for all new templates, even if that directory only contains a single fragment.}}
</div><div class="SECT1">
----
----
==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-begin-html template-begin-php
template-begin-html template-begin-php
template-begin-pam template-begin-shell
template-begin-pam template-begin-shell
{{Note box|msg=You may also need a <tt class="FILENAME">templates.metadata</tt> configuration file if your generated file needs to be executable.}}
</div><div class="SECT2">
----
----
===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.
{{Note box|The number of fragments and the order of those fragments within a template directory is subject to change between releases.}}
</div><div class="SECT2">
----
----
===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.
{{Warning box|msg=''Never edit the standard templates.'' Your changes will be overwritten when packages are upgraded.}}
{{Note box|msg=The template-custom trees should be reserved for local system overrides. ''Software should not install files in this tree.''}}
If a templates-custom entry exists for a template, it is merged with the standard templates directory during template expansion, using the following rules:
If a templates-custom entry exists for a template, it is merged with the standard templates directory during template expansion, using the following rules:
----
----
===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.
* Raise a New Feature Request here: http://www.contribs.org/bugzilla/. Please attach your modified template (or even better, a patch file) and provide details of why you think that the standard template should be changed.
* Raise a New Feature Request here: http://www.contribs.org/bugzilla/. Please attach your modified template (or even better, a patch file) and provide details of why you think that the standard template should be changed.
{{Note box|msg=You should not release RPMs which install templates in the <tt class="FILENAME">templates-custom</tt> directories. If the behaviour of a base template needs to be changed, please raise a bug to discuss the change.}}
</div><div class="SECT2">
----
----
===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.
{{Note box|msg=Configuration files should generally '''not''' be writable by any user other than root. In particular, configuration files should not normally be writable the ''www'' user as this poses a significant security risk. Installation advice which says <tt>chmod 777</tt> is almost invariably wrong.}}
For example, here is the metadata file <tt class="FILENAME">/etc/e-smith/templates.metadata/etc/ppp/ip-up.local</tt><nowiki>:</nowiki>
For example, here is the metadata file <tt class="FILENAME">/etc/e-smith/templates.metadata/etc/ppp/ip-up.local</tt><nowiki>:</nowiki>
which sets the group to <var class="LITERAL">daemon</var> and makes the script executable. Note that the file is readable by members of the <var class="LITERAL">daemon</var> group, but it is not writable by anyone but root. It is also possible to use the same template to generate multiple output files, such as in this example:
which sets the group to <var class="LITERAL">daemon</var> and makes the script executable. Note that the file is readable by members of the <var class="LITERAL">daemon</var> group, but it is not writable by anyone but root. It is also possible to use the same template to generate multiple output files, such as in this example:
TEMPLATE_PATH="/etc/sysconfig/network-scripts/route-ethX"
OUTPUT_FILENAME="/etc/sysconfig/network-scripts/route-eth1"
OUTPUT_FILENAME="/etc/sysconfig/network-scripts/route-eth1"
MORE_DATA={ THIS_DEVICE => "eth1" }
MORE_DATA={ THIS_DEVICE => "eth1" }
FILTER=sub { $_[0] =~ /^#/ ? '' : $_[0] } # Remove comments</nowiki>
FILTER=sub { $_[0] =~ /^#/ ? '' : $_[0] } # Remove comments
The templates.metadata file for route-eth0 just uses <var class="LITERAL">eth0</var> instead of <var class="LITERAL">eth1</var> on the second and third lines. Note also the <var class="LITERAL">FILTER</var> setting which allows post-processing of the generated template.
The templates.metadata file for route-eth0 just uses <var class="LITERAL">eth0</var> instead of <var class="LITERAL">eth1</var> on the second and third lines. Note also the <var class="LITERAL">FILTER</var> setting which allows post-processing of the generated template.
----
----
===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:
where <var class="REPLACEABLE">filename</var> is the name of the configuration file you want to generate, e.g. <tt class="FILENAME">/etc/hosts</tt>.
where <var class="REPLACEABLE">filename</var> is the name of the configuration file you want to generate, e.g. <tt class="FILENAME">/etc/hosts</tt>.
{{Note box|msg=<tt>expand-template</tt> is designed for testing, and not as the standard way to expand templates. The correct way to ensure that a template is expanded is to create the <tt>templates2expand</tt> files in the relevant events, along with any <tt>templates.metadata</tt> files which may be required.}}
</div><div class="SECT2">
----
----
===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:
[...]
[...]
}
}
{{Note box|msg=Software which was written for SME Server before release 7 will have a number of scripts which call <tt>processTemplate</tt>. In almost all cases, these can be replaced with simple flag files in the <tt>templates2expand/</tt> directory of the relevant events. The new method is '''far''' more efficient as a single invocation is perl is used to expand all template files.}}</div></div></div>