Template Tutorial

Languages:

English  • français

Overview and Description

This document is meant to serve as a "plain english" description of the template system in SME server. Refer to the Configuration file templates of the SME Server Developer's Guide 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 database 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.

	Note:
	SME Server uses the config files in the /etc/ folder just like any other Linux system. Do not edit the configuration files in the /etc/ folder directly (as would be done in a regular Linux distro).

Configuration changes are made in server manager, or by additional command line database settings, or by customizing the code that generates the configuration settings. This code is in the templates. Templates are composed of fragments. These are not regular configuration files, they are the code that generates part (i.e. a fragment) of the configuration files.

The configuration files in the /etc/ folder are created from the code in the template fragments and default values in the main template fragments and the internal configuration database in /etc/e-smith/templates/.

The code in the template fragments also look up values in the various databases in /home/e-smith/db/ (where the code has been written to support database settings).

In addition there are custom template fragments in the /etc/e-smith/templates-custom/ 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/file.conf

For SME 10For SME 9 and before

systemctl restart dhcpd

for supervised services

sv t /service/servicename

or for any service

service restart servicename

Some signal events combine template expansion and service restart

signal-event email-update

or one of the many other signal events as appropriate for the task you 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/ tree to the corresponding /etc/e-smith/templates-custom/ tree while keeping the same folder structure. Edit the copied fragment with required changes, then expand the configuration file and restart affected services as described 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.

Template fragment code - perl vs text

Some templates are inserted as literal text into the output files, and some templates are actually running perl code to generate the output text.

The template fragments using perl code, include braces ("{" and "}") and will likely contain lines beginning with

$OUT .= "blah, blah, blah"; 

If the template you have copied includes perl code, you will need to write the appropriate perl code to create your new output, or place your text changes after the final closing brace ("}") of the perl commands.

templates.metadata

Template output file location, ownership, and other metadata can also be controlled by configuration settings stored under /etc/e-smith/templates.metadata.

While the default output location for most templated config files matches the path to the collection of template fragments, it is also possible to specify a different output filename using an entry within the /etc/e-smith/templates.metadata folder.

/var/service/qpsmtpd/config/peers/0

The qpsmtpd 'plugins' directives in /etc/e-smith/templates/var/service/qpsmtpd/config/plugins do NOT affect the content of /var/service/qpsmtpd/plugins as expected.

Instead, due to this line in /etc/e-smith/templates.metadata/var/service/qpsmtpd/config/plugins:

OUTPUT_FILENAME="/var/service/qpsmtpd/config/peers/0"

This command:

expand-template /var/service/qpsmtpd/config/plugins

Will actually update the contents of /var/service/qpsmtpd/config/peers/0.

Note: /var/service/qpsmtpd/config/plugins is not templated at this time.

/etc/samba/smb.cnf

/etc/samba/smb.cnf is updated based on the template fragments in /etc/e-smith/templates/etc/smb.cnf.

Specific practical examples

These are examples only, please ensure you determine and use the correct settings and template fragments.

dhcpd.conf

Examine the template fragments in /etc/e-smith/templates/etc/dhcpd.conf and determine which fragment you wish to change. Let's say you want to modify a value that is in 25DomainNameServers fragment (for the DNS server setting), and in the 25Routers fragment (for the gateway/router setting).

Copy the fragments to the custom template tree

mkdir -p /etc/e-smith/templates-custom/etc/dhcpd.conf
echo "option domain-name-servers 4.2.2.1;" > /etc/e-smith/templates-custom/etc/dhcpd.conf/25DomainNameServers
echo "option routers 192.168.1.4;" > /etc/e-smith/templates-custom/etc/dhcpd.conf/25Routers

Expand template and restart dhcpd

expand-template /etc/dhcpd.conf

For SME 10For SME 9 and before

systemctl restart dhcpd

sv t /service/dhcpd

Examine /etc/dhcpd.conf to see that your changes have been created.

masq

Examine the template fragments in /etc/e-smith/templates/etc/rc.d/init.d/masq

Let's say you wish to block access to your server from an external IP, and there is no fragment that is suitable. Refer http://forums.contribs.org/index.php/topic,45495.0.html In this case create a new fragment.

Create a new template fragment

nano -w /etc/e-smith/templates-custom/etc/rc.d/init.d/masq/40DenyZombies

Add the following to the fragment

/sbin/iptables -A INPUT -s 24.71.223.10/32 -j DROP # waste of space IP
/sbin/iptables -A INPUT -s 24.64.0.0/13 -j DROP # supporting telco

Then save and exit

Ctrl x 
yes

Expand template and restart masq (masquerading)

expand-template /etc/rc.d/init.d/masq

For SME 10For SME 9 and before

systemctl restart masq

/etc/init.d/masq restart

Check your change is working

mysql

Q) Is slaving SME's MySQL server for replication possible? Is binary logging possible? If so, do you edit the my.cnf file or some file to initiate binary logging?

A) First step is to go to the mysql web site and research what you want to do, see http://dev.mysql.com/doc/

When you find out what needs to be added to the /etc/my.cnf file, you can then make appropriate changes via a sme server custom template.

Examine the template fragments in /etc/e-smith/templates/etc/my.cnf

Determine which fragment your revised code needs to go into. See the 000readme fragment for info.

If no fragment is suitable you will need to create a new fragment. In the following example replace 005mysql with the appropriate existing or new fragment name.

Let's say you wish to modify the /etc/e-smith/templates/etc/my.cnf/005mysqld

Create a new directory and copy the existing template to the custom template tree (or create a new custom template)

mkdir -p /etc/e-smith/templates-custom/etc/my.cnf/
cp /etc/e-smith/templates/etc/my.cnf/005mysqld /etc/e-smith/templates-custom/etc/my.cnf/005mysqld

Edit and make your required additions & changes. This is where you add the changes determined from the mysql documentation.

nano -w /etc/e-smith/templates-custom/etc/my.cnf/005mysqld

Save and exit

Ctrl o
Ctrl x

Expand template and restart mysqld

expand-template /etc/my.cnf

For SME 10For SME 9 and before

systemctl restart mariadb

sv t /service/mysqld

Check status of the service

For SME 10For SME 9 and before

systemctl status mariadb

sv s /service/mysqld

In this particular example there appears to be a requirement to share the mysql databases with LAN (local) or WAN (external) users. To achieve this you may need to change access permissions to your mysql databases, refer http://wiki.contribs.org/SME_Server:Documentation:FAQ#Access_MySQL_from_the_local_network http://wiki.contribs.org/SME_Server:Documentation:FAQ#Access_MySQL_from_a_remote_network http://wiki.contribs.org/SME_Server:Documentation:FAQ#Create_MySQL_user.28s.29_with_access_from_other_computers

Check your changes are working

Removal To remove these custom changes you delete the custom template, expand the template and then restart the service, as follows

rm /etc/e-smith/templates-custom/etc/my.cnf/005mysqld
expand-template /etc/my.cnf

For SME 10For SME 9 and before

systemctl restart mariadb

sv t /service/mysqld

Check status of the service

For SME 10For SME 9 and before

systemctl status mariadb

sv s /service/mysqld

php.ini

Note:

This is only valid for SME 9 and before. Starting SME10, php-fpm pools are in use. And default php pool is php74-IBAYNAME. php74 will use its own php.ini in /etc/opt/remi/php74/php.ini but thoses values are overriden by the php-fpm.d/ibays.conf which is also templates. And the service to restart would be php74-php-fpm. If you set to use another version of php, then you need to change 74 to the other version eg 80 with the exception of Core version for 54 in SME10 is defined by service php-fpm.

Examine the template fragments in /etc/e-smith/templates/etc/php.ini and determine which fragment you wish to change. Let's say you want to modify a value that is in the 40DataHandling fragment.

Copy the fragment to the custom template tree:

mkdir -p /etc/e-smith/templates-custom/etc/php.ini
cp /etc/e-smith/templates/etc/php.ini/40DataHandling /etc/e-smith/templates-custom/etc/php.ini/40DataHandling

Edit the fragment and make your required changes:

nano -w /etc/e-smith/templates-custom/etc/php.ini/40DataHandling

Save changes and exit (press the following keys together):

Ctrl o
Ctrl x

Expand template and restart httpd-e-smith:

expand-template /etc/php.ini

For SME 10For SME 9 and before

systemctl restart php-fpm

sv t /service/httpd-e-smith

Examine /etc/php.ini to see that your changes have been created.

httpd.conf

This example comes from a forum post at http://forums.contribs.org/index.php/topic,40336.0.html where a user asks how to redirect the "404 page not found rule" to a php file.

Make a custom template folder

mkdir -p /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf

Edit the template fragment with vi or nano

cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
nano S85ErrorPages

and add the following text:

# Add custom error pages here
ErrorDocument 404 /notfound.html

Save & exit from vi or nano

Ctrl c
Ctrl x

Expand template & restart service

expand-template /etc/httpd/conf/httpd.conf

For SME 10For SME 9 and before

systemctl status httpd-e-smith

sv t /service/httpd-e-smith

Using your favourite html editor, create a suitable web page & save it in the Primary/html ibay (or otherwise applicable ibay) with the filename of notfound.html.

Then open your browser and type in an incorrect URL (making sure the domain is valid) eg

http://www.mydomain.com/dunno 

and your new error page should be displayed.

If custom error pages are required for virtual domains, create a new html error page for each domain and save it in the html folder of the appropriate ibay.

This concept can also apply to other common error document pages such as:

400 Bad Request
401 Unauthorized
403 Forbidden

These errors can be catered for by appropriate lines in the template fragment to point to the particular pages.

A full list of error codes can be found at http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

smb.conf

This example comes from a forum post at http://forums.contribs.org/index.php/topic,49238.0.html where a user asks how to enable domain login to SME8 server from Windows 98 workstations,

and is based on advice from http://ubuntuforums.org/showthread.php?t=1617097

The SME server template fragments were examined & it was determined that the most suitable for the requirement was /etc/e-smith/templates/etc/smb.conf/11lanmanPasswords

Make a custom template folder

cp /etc/e-smith/templates/etc/smb.conf/11lanmanPasswords /etc/e-smith/templates-custom/etc/smb.conf/

Edit the template fragment with vi, nano or nano

cd /etc/e-smith/custom-templates/etc/smb.conf
nano 11lanmanPasswords

and change the contents to the following code (in this example the perl code shown will allow parameters to be controlled by db commands rather than hard coding the parameters as text into the fragment)

{
$OUT .= "lanman auth = $smb{'LanManPasswords'}\n" if $smb{'LanManPasswords'};
$OUT .= "client lanman auth = $smb{'ClientLanManPasswords'}\n" if $smb{'ClientLanManPasswords'};
$OUT .= "client plaintext auth = $smb{'ClientPlaintextPasswords'}\n" if $smb{'ClientPlaintextPasswords'};
}

Save & exit from nano

Ctrl c
Ctrl x

Then check & note current settings

config show smb

Then issue

config setprop smb LanManPasswords yes
config setprop smb ClientLanManPasswords yes
config setprop smb ClientPlaintextPasswords yes

Expand template & restart service (both included in the one signal-event command)

 signal-event workgroup-update

Then review settings

config show smb

Then manually check /etc/samba/smb.conf to see all changes & settings are present eg

cat /etc/samba/smb.conf

Additional steps are required to modify passwords for Windows 98 users, from this post http://ubuntuforums.org/showthread.php?t=1617097

Re input passwords for every Windows 98 user (where username is the sme user who is logging into any Windows 98 workstation)

smbpasswd -a username

Then every Windows 98 user should log out and then log in again on their Windows 98 workstations (to pick up the changes on the server & allow successful login)

More examples to be added to this section

Quick steps & tips

From http://forums.contribs.org/index.php/topic,45855.0.html

In order to override a SME template, the filename in .../templates-custom/... should to be identical to the filename in .../templates/....

Here's how to go about creating a custom template:

1. Identify the service performing the task I want to customize
2. Identify the configuration file that needs to be customized
3. Change the config file manually
4. Restart the affected service
5. Verify that restarting the service did not return the config file to the original configuration (dnscache, for example, regenerates .../dnscache/root/servers each time the service is restarted)
6. Verify that the change introduced, fixes the problem I am addressing
7. Locate the default template fragment that generates the piece of the config file I want to modify
8. Copy the default template fragment into the appropriate .../templates-custom/... folder tree
9. Edit the .../templates-custom/... copy of the template fragment
10. Use expand-template to regenerate the target config file
11. Verify (using file date and time, or by using a slightly different value for the new parameter than was used in step 3) that the config file now contains the output generated by the new custom template fragement.
12. Re-test
13. Document the operation in the wiki if it seems to me that the info would be useful to others

Not every config option of every program is templated; for example, there is no template (that I can find) to control /var/service/qpsmtpd/config.

Not every template is in the location you might expect (.../qpsmtpd/peers/0 is built using the template fragments in .../qpsmtpd/config/plugins due to the instructions in .../templates.metadata/...).

Not every function is controlled by only one template (or config file) - email attachment size, for example, is affected by settings in qmail, qpsmtpd, php and clamd.

Finally, template fragments are processed alpha-numerically - so be sure that your customizations are inserted into the target config file in a sensible location.

Detailed generic troubleshooting & configuration steps

From http://forums.contribs.org/index.php/topic,48300.msg239719.html#msg239719

This article refers to modifying a wordpress installation, but can be applied to any installed web application.

Here is a process that can be followed when trying to reverse-engineer a situation with a template or db setting affecting a website:

For SME 10For SME 9 and before

in SME10 the command to restart the web server will expand also the template and overwrite your temp changes so just edit the db setting you want and do that

systemctl status httpd-e-smith

Edit /etc/httpd/conf/httpd.conf directly.

locate the area that needs to be changed

insert the required commands restart the web server using

sv t /service/httpd-e-smith

test

If something is broken, then return to the start (by resetting defaults) using:

expand-template /etc/httpd/conf/httpd.conf; sv t httpd-e-smith

If the problem is fixed by the temporary config file changes, then identify the template fragment that generates the section that needs to be modified:

cd /etc/e-smith/templates/etc/httpd/conf/httpd.conf
grep -ril <some text near temporary change> *

In the above grep command, replace <some text near temporary change> with the text you are looking for.

Then examine the files listed to see if the required change can be made using a db variable, or made via a custom template fragment. You will need to have a moderate understanding of the template/fragment code to determine this, ask on the forum if unsure or read the Developers Manual.

If nothing is returned, repeat the search in /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf.

If the required changes are not supported by using a db variable, then create a custom template fragment:

mkdir -p /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
cp /etc/e-smith/templates/etc/httpd/conf/httpd.conf/<TheFileINeedToCustomize> .

(note the trailing space and dot at the end of the last line).

Now edit the "custom" template fragment created, and those contents will be used instead of the default template fragment used when the affected file (/etc/httpd/conf/httpd.conf) is generated using 'expand-template'.

Some templates are inserted as literal text into the output files, and some templates are actually running perl code to generate the output text. The perl templates will include braces ("{" and "}") and will likely contain lines beginning with $OUT .= "blah, blah, blah";. If the template you've decided to copy includes perl code, you will need to write perl code to create your new output or place your changes after the final closing brace ("}") of the perl commands.

After making the changes:

expand-template /etc/httpd/conf/httpd.conf; sv t httpd-e-smith

If the changes have broken something:

cd /etc/e-smith/templates-custom/etc/httpd/conf/httpd.conf
rm <TheFileINeedToCustomize>
expand-template /etc/httpd/conf/httpd.conf; sv t httpd-e-smith

It is also useful to create a file to display your PHP version information:

cd /path/to/wordpress

(insert path to your application)

echo '<?php phpinfo(); ?>
' > pi.php

Now browse to http://wordpress.url/pi.php (or your applications URL) and you should get a long listing of detailed information about the specific PHP that is invoked when running php from your wordpress or application folder.

Having phpinfo() sitting around on your server may introduce a security risk, so remove the file when finished troubleshooting.

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

---