From 2bb92ad07da71a59ed07b38d8fa18cd921806bd5 Mon Sep 17 00:00:00 2001
From: Konrad Bucheli <konrad.bucheli@psi.ch>
Date: Tue, 18 Jul 2023 11:31:13 +0200
Subject: [PATCH] document how to distribute files

---
 _toc.yml                                      |  1 +
 admin-guide/configuration/distribute_files.md | 95 +++++++++++++++++++
 2 files changed, 96 insertions(+)
 create mode 100644 admin-guide/configuration/distribute_files.md

diff --git a/_toc.yml b/_toc.yml
index eb10f0dc..1ac9ff6c 100644
--- a/_toc.yml
+++ b/_toc.yml
@@ -33,6 +33,7 @@ chapters:
           - file: admin-guide/architecture/active-directory
       - file: admin-guide/configuration
         sections:
+          - file: admin-guide/configuration/distribute_files
           - file: admin-guide/configuration/vgroot
           - file: admin-guide/configuration/xrdp
           - file: admin-guide/configuration/custom_nameservers
diff --git a/admin-guide/configuration/distribute_files.md b/admin-guide/configuration/distribute_files.md
new file mode 100644
index 00000000..e89b38f3
--- /dev/null
+++ b/admin-guide/configuration/distribute_files.md
@@ -0,0 +1,95 @@
+# Distribute Files
+
+With Hiera it is possible to download files and git repositories as well as to create directories and symlinks.
+
+## 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 reside in the `master` branch and 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
+- `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
+```
+
+## 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 what sha-hash should be checked out
+
+Example:
+
+```
+files::git:
+  /var/test/container-images:
+    url: 'https://git.psi.ch/linux-infra/container_images.git'
+    revision: 'main'
+```
+
+## 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.