Changes

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 class="NOTE"><blockquote class="NOTE">

</div><div class="SECT1">

 

'''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">

----

----

  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 class="NOTE"><blockquote class="NOTE">

</div><div class="SECT2">

 

'''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">

----

----

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">

 

'''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">

----

----

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.

{{Note box|msg=The template-custom trees should be reserved for local system overrides. ''Software should not install files in this tree.''}}

 

'''Note: '''<span class="emphasis">''Never edit the standard templates.''</span> Your changes will be overwritten when packages are upgraded.

 

 

'''Note: '''The template-custom trees should be reserved for local system overrides. <span class="emphasis">''Software should not install files in this tree.''</span>

 

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:

* 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.

<div class="NOTE"><blockquote class="NOTE">

{{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">

'''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">

----

----

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.}}

<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.

 

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:

  <nowiki>TEMPLATE_PATH="/etc/sysconfig/network-scripts/route-ethX"

  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.

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 class="NOTE"><blockquote class="NOTE">

</div><div class="SECT2">

 

'''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">

----

----

     [...]

     [...]

  }

  }

 

{{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>

<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>