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 :

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

En YAML :

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

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

En YAML :

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

## Le nom de template dynamique

La source peut ếgalement être une variable :

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

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

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

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

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

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

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

```yml
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é :

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

En YAML :

```yml
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](../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" :

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

En YAML :

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

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 :

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

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

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

En YAML :

```yml
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é) :

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

En YAML :

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

Ou d'utiliser le moteur "jinja" :

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

En YAML :

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

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 :

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

En YAML :

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

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

En YAML :

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