Template Tutorial/fr

Aperçu et description

Ce document est destiné à servir de description en "langage clair" du système de gabarit (template) de SME server. Reportez-vous à la page Gabarit (template) de fichiers de configuration du Guide du Developeur pour SME server pour une description plus technique.

Le système gabarit est unique à SME Server. Il est utilisé pour créer les fichiers de configuration standard dans /etc/... en conjonction avec l'événement expand-template.

Les gabarits sont constitués de fragments qui s'additionnent pour créer le fichier de configuration tout entière. Le code dans fragments de gabarits peut avoir une valeur par défaut en l'absence d'une valeur spécifique dans la db (base de données).

Afin de déterminer quels paramètres de base de données sont pris en compte par le code du fragment de gabarit, ou quelles sont les valeurs par défaut, reportez-vous (c'est à dire lisez) au code qui est dans les fragments de gabarit, ou dans les fragments de gabarit personnalisé associé à un fichier /etc/file.conf

Regardez dans /etc/e-smith/templates/ et /etc/e-smith/templates-custom/ et leurs sous-dossiers à la recherche des fragments de gabarit associés aux fichiers de configuration d’intérêt comme /etc/file.conf.

	Note:
	SME Server utilise les fichiers de configuration dans le dossier /etc/ comme n'importe quel autre système Linux. Ne pas modifier directement les fichiers de configuration dans le dossier /etc/ (comme on le ferait dans une distro Linux standard).

Les changements de configuration sont faites dans le gestionnaire de serveur (server-manager), ou par les paramètres de base de données en ligne de commande supplémentaires, ou en adaptant le code qui génère les paramètres de configuration. Ce code est dans les gabarits (templates). Les gabarits sont composés de fragments. Ce ne sont pas des fichiers de configuration réguliers, ils sont le code qui génère une partie (c'est à dire un fragment) des fichiers de configuration.

Les fichiers de configuration dans le dossier /etc/ sont créés à partir du code dans les fragments de gabarits et les valeurs par défaut dans les fragments de gabarits principaux et la base de données de configuration interne dans /etc/e-smith/templates/.

Le code dans les fragments de gabarits recherche également des valeurs dans les différentes bases de données dans /home/e-smith/db/ (quand le code a été écrit pour s'appuyer sur les paramètres de bases de données).

En outre, il y a des fragments de gabarits personnalisés dans le dossier /etc/e-smith/templates-custom/. Le code dans ces fragments de gabarits personnalisés ajoute des paramètres de configuration en plus des paramètres générés par les fragments de gabarit principaux, ou lorsque les fragments de gabarit personnalisés sont nommés de façon identique, ils vont complètement remplacer les paramètres générés par les fragments de gabarit principaux.

Le fichier de configuration /etc/file.conf est généré lorsque vous exécutez la commande suivante :

expand-template /etc/file.conf

Vosu aurrez probablement besoin de relancer le service affecté en utilisant :

sv t /service/servicename

Certains signaux d’événement combinent l'utilisation de gabarits et le redémarrage du service

signal-event email-update

ou l'un des nombreux signaux tout autre événement en fonction de la tâche que vous faites.

En cas de doute de gabarit à développer et de service à redémarrer, il y a un une commande "maîtresse" qui permettra d'appliquer tous les gabarits et de redémarrer tous les services, avec pour effet de réinitialiser tous les les paramètres de configuration. Il est sécuritaire de le faire à tout moment en utilisant

signal-event post-upgrade
signal-event reboot

Pour effectuer un changement personnalisé de gabarit, copiez le fragment d'intérêts existants dans sous le répertoire /etc/e-smith/templates/ dans le dossier correspondant sous /etc/e-smith/templates-custom/ en conservant la même structure de dossier. Éditez le fragment copié avec les modifications désirées, puis appliquez le gabarit au fichier de configuration et redémarrez le service affecté comme décrit au dessus.

Vous pouvez aussi creer un nouveau fragment de gabarit quand le fragment souhaité n'existe pas déjà. Vous aurez à lui trouver un nom correspondant à l'ordre akphanumérique adapté à la position à laquelle vous voulez que votre nouveau paramètre occupe au milieu des autres fragments dans le fichier de configuration /etc/xxxx .

Pourquoi tout cela dans la conception de SME?

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

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

pico -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
sv t /service/mysqld

Check status of the service

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
sv t /service/mysqld

Check status of the service

sv s /service/mysqld

php.ini

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

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

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

and add the following text

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

Save & exit from vi or pico

Ctrl c
Ctrl x

Expand template & restart service

expand-template /etc/httpd/conf/httpd.conf
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

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.

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

---