rougail/doc/service/file.md

La gestion d'un fichier

La balise file

La gestion des fichiers se fait dans un conteneur de service.

La déclaration du fichier permet de générer un fichier à partir d'un template pour le déposer à l'endroit prévu dans la déclaration de cette élément.

Il est nécessaire, au minimum, de spécifier le chemin complet du fichier :

<services>
  <service name="squid">
    <file>/etc/squid/squid.conf</file>
  </service>
</services>

En YAML :

services:
- service:
  - name: squid
    file:
    - text: /etc/squid/squid.conf

Le nom de template

Par défaut, le nom du template est déduit du nom du fichier.

Par xemple, si le fichier de destination est "/etc/squid/squid.conf", le template aura le nom "squid.conf".

Si le template a un nom différent (par exemple si plusieurs template se retrouve avec le même nom), il est possible de changer le nom du template avec l'attribut source :

<file source="template-squid.conf">/etc/squid/squid.conf</file>

En YAML :

file:
- source: template-squid.conf
  text: /etc/squid/squid.conf

Le nom de template dynamique

La source peut ếgalement être une variable :

<services>
  <service name="squid">
    <file source="source_var" source_type="variable">/etc/squid/squid.conf</file>
  </service>
</services>
<variables>
  <variable name="source_var">
    <value>template-squid.conf</value>
  </variable>
</variables>

En YAML :

services:
- service:
  - name: squid
    file:
    - source: source_var
      source_type: variable
      text: /etc/squid/squid.conf
variables:
- variable:
  - name: source_var
    value:
    - text: template-squid.conf

Les noms de fichiers dynamique

Il est possible également de définir le nom du fichier dans une variable :

<services>
  <service name="squid">
    <file file_type="variable" source="squid.conf">my_variable</file>
  </service>
</services>
<variables>
  <variable name="my_variable">
    <value>/etc/squid/squid.conf</value>
  </variable>
</variables>

En YAML :

services:
- service:
  - name: squid
    file:
    - file_type: variable
      source: squid.conf
      text: my_variable
variables:
- variable:
    name: my_variable
    value:
    - text: /etc/squid/squid.conf

Attention, la variable doit être de type "filename".

Dans le cas des fichiers dynamique, la source est obligatoire.

Il est même possible de définir une variable de type multiple, ce qui génèrera plusiers fichiers :

<services>
  <service name="squid">
    <file file_type="variable" source="squid.conf">my_variable</file>
  </service>
</services>
<variables>
  <variable name="my_variable" multi="True">
    <value>/etc/squid1/squid.conf</value>
    <value>/etc/squid2/squid.conf</value>
  </variable>
</variables>

En YAML :

services:
- service:
  - name: squid
    file:
    - file_type: variable
      source: squid.conf
      text: my_variable
variables:
- variable:
    name: my_variable
    multi: true
    value:
    - text: /etc/squid1/squid.conf
    - text: /etc/squid2/squid.conf

Dans ce cas là, le fichier source est identique mais les fichiers de destination seront différent.

Il peut être important de personnaliser le contenu du fichier suivant le fichier de destination. Dans ce cas il y a deux possibilités :

• la variable "rougail_filename" contient le nom de fichier de destination
• l'utilisateur de l'attribut "variable"

En effet, il est possible de passer le contenu d'une variable au template :

<services>
  <service name="squid">
    <file file_type="variable" source="squid.conf" variable="my_variable2">my_variable1</file>
  </service>
</services>
<variables>
  <variable name="my_variable1" multi="True">
    <value>/etc/squid1/squid.conf</value>
    <value>/etc/squid2/squid.conf</value>
  </variable>
  <variable name="my_variable2" multi="True">
    <value>squid1</value>
    <value>squid2</value>
  </variable>
</variables>

En YAML :

services:
- service:
  - name: squid
    file:
    - file_type: variable
      source: squid.conf
      variable: my_variable2
      text: my_variable1
variables:
- variable:
    name: my_variable1
    multi: true
    value:
    - text: /etc/squid1/squid.conf
    - text: /etc/squid2/squid.conf
- variable:
    name: my_variable2
    multi: true
    value:
    - text: squid1
    - text: squid2

Dans ce cas, lors de la génération du fichier /etc/squid1/squid.conf on retrouvera la variable "rougail_variable" avec la valeur "squid1" et la variable "rougail_index" avec la valeur "0". Lors de la génération du fichier /etc/squid2/squid.conf on retrouvera la variable "rougail_variable" avec la valeur "squid2" et la variable "rougail_index" avec la valeur "1".

Attention : les deux variables "my_variable1" et "my_variable2" doivent être multiple et de même longueur.

Les droits des fichiers

Par défaut les droits du fichier généré sont "0644" avec comme utilisateur "root" et groupe "root".

Il est possible de définir les droits, l'utilisateur ou le groupe d'un fichier généré :

<file mode="0640" owner="nobody" group="squid">/etc/squid/squid.conf</file>

En YAML :

file:
- mode: '0640'
  owner: nobody
  group: squid
  text: /etc/squid/squid.conf

Il est possible de personnaliser les droits par défaut dans la configuration de rougail

Désactiver la génération d'un fichier

Il est possible de désactiver la génération d'un fichier avec l'attribut "disabled" :

<file disabled="True">/etc/squid/squid.conf</file>

En YAML :

file:
- disabled: true
  text: /etc/squid/squid.conf

Il est aussi possible de définir une condition de type "disabled_if_in" ou "disabled_if_not_in" sur une balise fichier :

<services>
  <service name="test">
    <file filelist="squid">/etc/squid/squid.conf</file>
  </service>
</services>
<variables>
  <variable name="condition" type="boolean"/>
</variables>
<constraints>
  <condition name="disabled_if_in" source="condition">
    <param>False</param>
    <target type="filelist">squid</target>
  </condition>
</constraints>

En YAML :

services:
- service:
  - name: text
    file:
    - filelist: squid
      text: /etc/squid/squid.conf
variables:
- variable:
    name: condition
    type: boolean
constraints:
- condition:
  - name: disabled_if_in
    source: condition
    param:
    - text: false
    target:
    - type: filelist
      text: squid

Dans ce cas, tous les fichiers avec un attribut filelist à "squid" seront désactivés si la variable "condition" est False.

Redéfinir une fichier

Il est possible de redéfinir les éléments d'un fichier dans un dictionnaire différent en utilisant l'attribut redefine :

<file source="template-squid.conf" redefine="True">/etc/squid/squid.conf</file>

En YAML :

file:
- source: template-squid.conf
  redefine: true
  text: /etc/squid/squid.conf

Choix du moteur de templating

Par défaut, le moteur de templating est le moteur de templating compatible avec "cheetah".

Il est possible de désactiver la templatisation du fichier (il sera alors uniquement copié) :

<file engine="none">/etc/squid/squid.conf</file>

En YAML :

file:
- engine: 'none'
  text: /etc/squid/squid.conf

Ou d'utiliser le moteur "jinja" :

<file engine="jinja">/etc/squid/squid.conf</file>

En YAML :

file:
- engine: jinja
  text: /etc/squid/squid.conf

Il est possible de personnaliser le moteur par défaut dans la configuration de rougail

Inclusion de template

Un attribut "included" permet de définir la nature du fichier. Cet attribut peut avoir trois valeurs :

• "no" : c'est un fichier normal
• "name" : le répertoire de destination est listé dans un autre template, il faut que le fichier soit généré avant cet autre template
• "content" : le contenu du fichier est copié dans un autre template, il faut que le fichier soit généré avant cet autre template et ce fichier n'a pas besoin d'être installé sur le serveur cible.

Bien entendu, c'est au développeur de lister ou d'inclure le contenu de ce template dans le fichier de destination. Cet attribut permet juste de garantir que le fichier sera fait avant l'autre et de ne pas l'installer sur le serveur si ce n'est pas nécessaire.

Il est possible de personnaliser les methodes d'inclusion par défaut dans la configuration de rougail

Exemples :

• créons un template qui inclut des noms de fichiers :

Le contenu de ce template (squid.conf) est :

%import os
%set %%confdir = 'etc/squid/squid.d/'
%if %%os.path.exists(%%confdir)
 %set %%files = %%os.listdir(%%confdir)
 %%files.sort()
 %for %%file in %%files
  %if %%file.endswith('.cfg')
include '/' + %%confdir + file
  %end if
 %end for
%end if

Ajoutons un second template (squid.included.conf) qui sera copié dans ce répertoire :

template content

Et déclaront ces deux templates :

<file>/etc/squid/squid.conf</file>
<file included="name" engine="none">/etc/squid/squid.d/squid.conf</file>

En YAML :

file:
- text: /etc/squid/squid.conf
- included: name
   engine: 'none'
   text: /etc/squid/squid.d/squid.conf

Le contenu du fichier généré (/etc/squid/squid.conf) sera donc :

include squid.d/squid.conf

• créons un template qui inclut le contenu de fichiers :

Le contenu de ce template (squid.conf) est :

%import os
%set %%confdir = 'squid.d/'
%if %%os.path.exists(%%confdir)
 %set %%files = %%os.listdir(%%confdir)
 %%files.sort()
 %for %%file in %%files
  %if %%file.endswith('.cfg')
%include raw %%confdir + file
  %end if
 %end for
%end if

Ajoutons un second template (squid.included.conf) qui sera copié dans ce répertoire :

template content

Et déclaront ces deux templates :

<file>/etc/squid/squid.conf</file>
<file included="content" engine="none">squid.d/squid.conf</file>

En YAML :

file:
- text: /etc/squid/squid.conf
- included: content
   engine: 'none'
   text: squid.d/squid.conf

Le contenu du fichier généré (/etc/squid/squid.conf) sera donc maintenant :

template content