# `files`

The `files` module can be used to copy directories from `files/` to
any location in your image at build time, as long as the location exists at
build time (e.g. you can't put files in `/home/<username>/`, because users
haven't been created yet prior to first boot).

:::note
If you want to place files into `/etc/`, there are two ways to do it:

1. copying a directory in `files/` directly to `/etc` to add all of its
   files at build time, or
2. putting the files you want there in `/usr/etc/` as part of copying things
   over to `/usr/`, which `rpm-ostree` will then copy to `/etc/` at runtime/boot.

Typically, you will want to use the latter option (putting files in `/usr/etc/`)
in almost all cases, since that is the proper directory for "system"
configuration templates on atomic Fedora distros, whereas `/etc/` is meant for
manual overrides and editing by the machine's admin *after* installation (see
issue https://github.com/blue-build/legacy-template/issues/28). However, if you
really need something to be in `/etc/` *at build time* --- for instance, if you
for some reason need to place a repo file in `/etc/yum.repos.d/` in such a way
that it is used by a `rpm-ostree` module later on --- then the former option
will be necessary.
:::

:::caution
The `files` module **cannot write to directories that will later be symlinked
to point to other places (typically `/var/`) by `rpm-ostree`**.

This is because it doesn't make sense for a directory to be both a symlink and
a real directory that has had actual files directly copied to it, so the
`files` module copying files to one of those directories (thereby instantiating
it as a real directory) and `rpm-ostree`'s behavior regarding them will
necessarily conflict.

For reference, according to the [official Fedora
documentation](https://docs.fedoraproject.org/en-US/fedora-silverblue/technical-information/#filesystem-layout),
here is a list of the directories that `rpm-ostree` symlinks to other
locations:

- `/home/` → `/var/home/`
- `/opt/` → `/var/opt/`
- `/srv/` → `/var/srv/`
- `/root/` → `/var/roothome/`
- `/usr/local/` → `/var/usrlocal/`
- `/mnt/` → `/var/mnt/`
- `/tmp/` → `/sysroot/tmp/`

So don't use `files` to copy any files to any of the directories on the left,
because at runtime `rpm-ostree` will want to link them to the ones on the
right, which will cause a conflict as explained above.

:::