What does it mean NethServer uses fragments?

Howto FAQ
1

I would like to know, in brief, what are fragments, how NethServer uses them and a couple of examples if possible.

2

Fragments are portions of templates: http://docs.nethserver.org/projects/nethserver-devel/en/latest/templates.html

3

in brief

fragments are part of code, stored into /etc/e-smith/templates tree (and in templates-custom tree)

they can be plain text files or (often) perl scripts that read values from db and use them to create a part (or whole) conf file…

and example…

let’s say we have a service myservice that needs its conf file in /etc/myservice/ dir, named myservice.conf

first of all I create the right path:

mkdir -p /etc/e-smith/templates/etc/myservice/myservice.conf

then I move into the new dir and create my template fragments; the naming convention is XYfragmentname, where XY are numbers and fragmentname is something that helps to identify the role/content
this is valid for NEW services
N.B. acting this way is the RIGHT way… be aware that all the /templates/ tree is NOT backuped

usually, users must not edit fragments into the /template/ tree…

if I need to add or override some default part in the conf file, I must:

create the corrisponding path into the /templates-custom/ tree

following the above example

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

then:

  • if you want to add a value, just create in that dir a file YZmyfragment with the needed code/content
    since fragments are evaluated in numeric order, choose YX accordingly to your need
    for exampke, creating a 15myfragment, its content will be between content of 10fragment and 20fragment in the resulting file

  • if you need to override something, just copy the involved fragment from /templates/ tree into this directory and edit it accordingly to your need; it’s content will override the content of the “original” fragment

fragments are evaluated and expanded into their final conf files with the

expand-template templatename

command

if/when you don’t need anymore your customization, removing the relevant fragment and re expanding the template will undo everything

uysually you don’t need to use the expand-template command, but you use the rigth event to exmpand it and restart involved services

as I said above, the content of /templates-custom/ tree is always included into backups (as db files)
it contains alla the customization you have done to your setup and it is needed to restore the server features.
be aware that sometimes, usually after a data restore on a new hardware (and maybe a new O.S. release), you should always check your custom fragments to avoid problems

4 Likes