624
edits
Changes
From SME Server
Jump to navigationJump to searchadded Template Tutorial
== Template Tutorial ==
===Overview and Description===
This document is meant to serve as a "plain english" description of the template system in sme server. Refer to the Developers Manual for more technical descriptions.
The template system is unique to sme server. It is used to create the standard configuration files in /etc/.... in conjunction with the expand template event.
Templates are made up of fragments which add together to create the whole config file. The code in template fragments can have a default value in the absence of a specific db (database) value.
To determine what db settings are supported by template fragment code, or what the default values are, refer to (ie read) the code that is in the particular template fragments or custom template fragments associated with a /etc/file.conf
Look in /etc/e-smith/templates/... and /etc/e-smith/templates-custom/....
and subfolders and template fragments applicable to particular /etc/file.conf configuration files.
sme server uses the config files in /etc/xxxxxx just like any other Linux. Do not edit the /etc/xxxx config files directly (as would be done in a regular Linux distro).
Configuration changes are made in server manager, or by additional command line db settings, or by customising the code that generates the config settings. This code is in the templates. Templates are composed of fragments. These are not regular config files, they are the code that generates part (ie a fragment) of the config files.
The /etc/xxxx config files are created from the code in the template fragments & default values in the main template fragments in /etc/e-smith/templates/xxxx/yyyy
The code in the template fragments also look up values in the various databases in /home/e-smith/db/xxxxxxx (where the code has been written to support db settings).
In addition there are custom template fragments in the /etc/e-smith/templates-custom/xxxx/yyyy folder structure.
The code in these custom template fragments add configuration settings in addition to the settings generated by the main template fragments, or where the custom template fragments are identically named, they completely replace the settings generated by the main template fragments.
The config files are generated when you expand the templates using
expand-template /etc/xxxx/yyyy
You also need to restart affected services eg using
sv t /service/xxxxxservicename
Some signal events combine template expansion and service restart eg
signal-event email-update
or one of the many other signal events as appropriate for the task ypou are doing.
If in doubt which template to expand and service to restart, there is a "master" command that will expand all templates and restart all services, in effect reapplying all configuration settings, and it is safe to do anytime using
signal-event post-upgrade
signal-event reboot
To make a custom template change, copy the existing fragment of interest from the /etc/e-smith/templates/xxx/yyy tree to the corresponding /etc/e-smith/templates-custom/xxxx/yyyy tree, edit the copied fragment with required changes, then expand & restart as above.
You can also create new custom template fragments when an existing one does not exist that is suitable for the job. You need to name this in a correct numerical order, so the changes you want to make will be placed in the correct location in the /etc/xxxx config file.
===Why do all this by design ?===
To have robust default system settings that can easily be reverted to just by deleting the custom template fragments & expanding & restarting. The system will then return to correct functional settings.
That is why the main templates should never be modified, so all default template code remains unaltered and intact.
You will need to locate the template fragment of interest and read the code to decide which fragment you want to copy and make changes to. You can usually deduce this from the specific /etc/xxxx config file that you are trying to make changes to ie one correlates to the other.
Please review the many Howtos and Contrib wiki articles that have these types of configuration changes described, as it will provide step by step examples which can be applied to a particular need (changing the service and fragment names & the expansion config names of course). Also search the Forums on expand-template for numerous examples.
===Specific practical examples===
This section to be added
===References===
See the Howto section for articles on db commands that should give useful additional info ie
http://wiki.contribs.org/DB_Variables_Configuration
and
http://wiki.contribs.org/Useful_Commands
Refer to the Developers Guide for technical information on Templating
http://wiki.contribs.org/SME_Server:Documentation:Developers_Manual#Configuration_file_templates
----
[[Category:Howto]]
===Overview and Description===
This document is meant to serve as a "plain english" description of the template system in sme server. Refer to the Developers Manual for more technical descriptions.
The template system is unique to sme server. It is used to create the standard configuration files in /etc/.... in conjunction with the expand template event.
Templates are made up of fragments which add together to create the whole config file. The code in template fragments can have a default value in the absence of a specific db (database) value.
To determine what db settings are supported by template fragment code, or what the default values are, refer to (ie read) the code that is in the particular template fragments or custom template fragments associated with a /etc/file.conf
Look in /etc/e-smith/templates/... and /etc/e-smith/templates-custom/....
and subfolders and template fragments applicable to particular /etc/file.conf configuration files.
sme server uses the config files in /etc/xxxxxx just like any other Linux. Do not edit the /etc/xxxx config files directly (as would be done in a regular Linux distro).
Configuration changes are made in server manager, or by additional command line db settings, or by customising the code that generates the config settings. This code is in the templates. Templates are composed of fragments. These are not regular config files, they are the code that generates part (ie a fragment) of the config files.
The /etc/xxxx config files are created from the code in the template fragments & default values in the main template fragments in /etc/e-smith/templates/xxxx/yyyy
The code in the template fragments also look up values in the various databases in /home/e-smith/db/xxxxxxx (where the code has been written to support db settings).
In addition there are custom template fragments in the /etc/e-smith/templates-custom/xxxx/yyyy folder structure.
The code in these custom template fragments add configuration settings in addition to the settings generated by the main template fragments, or where the custom template fragments are identically named, they completely replace the settings generated by the main template fragments.
The config files are generated when you expand the templates using
expand-template /etc/xxxx/yyyy
You also need to restart affected services eg using
sv t /service/xxxxxservicename
Some signal events combine template expansion and service restart eg
signal-event email-update
or one of the many other signal events as appropriate for the task ypou are doing.
If in doubt which template to expand and service to restart, there is a "master" command that will expand all templates and restart all services, in effect reapplying all configuration settings, and it is safe to do anytime using
signal-event post-upgrade
signal-event reboot
To make a custom template change, copy the existing fragment of interest from the /etc/e-smith/templates/xxx/yyy tree to the corresponding /etc/e-smith/templates-custom/xxxx/yyyy tree, edit the copied fragment with required changes, then expand & restart as above.
You can also create new custom template fragments when an existing one does not exist that is suitable for the job. You need to name this in a correct numerical order, so the changes you want to make will be placed in the correct location in the /etc/xxxx config file.
===Why do all this by design ?===
To have robust default system settings that can easily be reverted to just by deleting the custom template fragments & expanding & restarting. The system will then return to correct functional settings.
That is why the main templates should never be modified, so all default template code remains unaltered and intact.
You will need to locate the template fragment of interest and read the code to decide which fragment you want to copy and make changes to. You can usually deduce this from the specific /etc/xxxx config file that you are trying to make changes to ie one correlates to the other.
Please review the many Howtos and Contrib wiki articles that have these types of configuration changes described, as it will provide step by step examples which can be applied to a particular need (changing the service and fragment names & the expansion config names of course). Also search the Forums on expand-template for numerous examples.
===Specific practical examples===
This section to be added
===References===
See the Howto section for articles on db commands that should give useful additional info ie
http://wiki.contribs.org/DB_Variables_Configuration
and
http://wiki.contribs.org/Useful_Commands
Refer to the Developers Guide for technical information on Templating
http://wiki.contribs.org/SME_Server:Documentation:Developers_Manual#Configuration_file_templates
----
[[Category:Howto]]
