# Distribute Files

With Hiera it is possible to download files and git repositories as well as to create directories and symlinks.


## Create Directories

The `files::directories` hash specifies directories to be created. The keys of the hash are the absolute pathnames of the directories, the optional value a hash with:

- `owner`: file owner (optional, default `root`)
- `group`: file owner (optional, default `root`)
- `mode`: file permissions (optional, default `755`)

Parent directories are automatically created with default settings. If that is not desired, a custom definition for each parent directory is required.

Example:

```
files::directories:
  /etc/test1:
  /etc/test2/foo/bar:
    owner: 'buchel_k'
    group: 'unx-nogroup'
    mode: '775'
```

## Create Symlinks

The `files::symlinks` hash is used to configure symlinks. The keys of the hash are the absolute
pathnames of the symlinks, the values of the hash are the corresponding symlink
targets.

Example:
```
files::symlinks:
  '/opt/foo': '/var/lib/foo'
```

Per default the symlink definitions are not merged over the full Hiera hierarchy, only the most specific definiton is used. To allow merge, set

```
files::symlinks::merge: true
```

Then also existing files and symlinks are not overwritten. Also this can be changed with

```
files::symlinks::force: true
```
but this is then applies for all symlink definitions.

## Create (Text) Files with Specific Content

Textfiles with specific content can be created as follows:

```yaml
files::files:
  /testdir/test/three:
    content: | 
      hello world t
      this is a test
```

## Delete Files / Directories
Individual files and directories can be deleted as follows:

```yaml
files::files:
  /testdir/test/two:
    ensure: absent
    force: true
```

The option `force: true` is only needed for directories. For a directory, if absent, the directory will not be deleted (even if it is empty)!


## Download Git Repositories

To synchronize a git repository to the host you might list them in the `files::git` hash. The key is the destination directory and the value is a hash with following options:

- `url`: URL of the public git repository to clone
- `revision`: what branch, tag or commit-hash should be checked out (optional)

Example:

```
files::git:
  /var/test/container-images:
    ensure: latest
    url: 'https://git.psi.ch/linux-infra/container_images.git'
    revision: 'main'
```

If the `ensure` is missing, it will initialize the checkout with the default branch, but afterwards leave the checkout as is and not try to ensure that it is on a given revision (branch, tag or commit).

Possible values for `ensure` are: present, bare, mirror, absent, latest .

More details on the possible values of ensure you can find in [this documentation](https://forge.puppet.com/modules/puppetlabs/vcsrepo/reference#ensure)

Note that submodules are automatically initialized.

## Download Files

Files to download need to be placed on a git repository on `git.psi.ch` (internal) or `gitlab.psi.ch` (DMZ, Extranet, Tier3), where they need to be publicly available.

For configuration in Hiera there is the `filecopy::files` hash where the keys is the destination path of the file. And the value is another hash with following options:

- `repo`: the Git repository to download from
- `branch`: the Git branch in the repository (optional, default `master`)
- `path`: the file path inside the repository
- `owner`: file owner (optional, default `root`)
- `mode`: file permissions (optional, default `0644`)


Example:

```
filecopy::files:
  '/tmp/test1':
     repo: 'talamo_i/copy-file-test'
     path: 'abc'
     mode: '0600'
     owner: 'talamo_i'
```

Note that the `filecopy::files` hash is **not merged** over the hierarchy, so only the most specific one will apply.

This download functionality can be disabled with
```
base::enable_filecopy: false
```