rougail/doc/service/file.md

# La gestion d'un fichier

## La balise file

La gestion des fichiers se fait dans un conteneur de [service](service.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 le fichier /etc/squid2/squid.conf on retrouvera la variable "rougail_variable" avec la valeur "squid2".

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 une autre valeur à un ou plusieurs de ces attributs :

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

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

Il est 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é 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>
```