rougail/doc/service/file.md

# La gestion d'un fichier

## La balise file

La gestion des fichiers se fait dans un conteneur de [service](README.md).

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

Dans ce cas, le nom du template est déduit du nom du fichier, ici cela sera "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>
```

## 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>
```

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

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

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

Il est possible de personnaliser les droits par défaut dans la [configuration de rougail](../dev/config.md)

## 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>
```

Il est aussi possible de définir une [condition](../condition/README.md) 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>
```

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

## Choix du moteur de templating

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

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

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

Ou d'utiliser le moteur "jinja2" :

```
<file engine="jinja2">/etc/squid/squid.conf</file>
```

Il est possible de personnaliser le moteur par défaut dans la [configuration de rougail](../dev/config.md)

## 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](../dev/config.md)

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

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

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

```
template content
```