CDIST-TYPE__FILE(7)

💖 cdist-type__file(7) 💖

okay bestie, welcome to the manual page for cdist-type__file — it's a cdist type, it manages files, and honestly? it's giving main character energy in the cdist universe. no cap. 🎀

---

✨ NAME ✨

cdist-type__file — manage files. that's it. that's the whole job. slay. 💅

---

🌸 DESCRIPTION 🌸

so this cdist type lets you create files, remove files, and set file attributes on the target. three vibes, one type. iconic.

if the file already exists on the target, then here's what happens depending on what it is:

• regular file, and state is:
  • present — replace it with the source file if they are not equal 🔁
  • exists — do nothing. literally nothing. it's fine. it's chill. 🧘
• symlink — replace it with the source file
• directory — replace it with the source file

there's one exception to all of this: when state is pre-exists, an error is raised if the file would have been created otherwise (like, if it's not present, or it's not a regular file). so no sneaky creation, bestie. 🚫

in any case, make sure that the file attributes are as specified. every time. periodt.

---

👑 REQUIRED PARAMETERS 👑

none. zero. nada. nothing is required, you're free, go wild. 🦋

---

💅 OPTIONAL PARAMETERS 💅

• state — 'present', 'absent', 'exists' or 'pre-exists', defaults to 'present'. and here's what each one means:
  • present — the file is exactly the one from source
  • absent — the file does not exist
  • exists — the file from source, but only if it doesn't already exist
  • pre-exists — check that the file exists and is a regular file, but do not create or modify it
• group — group to chgrp to. defaults to root.
• mode — unix permissions, suitable for chmod. defaults to a very secure 0600. 🔒
• owner — user to chown to. defaults to root.
• source — if supplied, copy this file from the host running cdist to the target. if not supplied, an empty file or directory will be created. and if source is '-' (dash), take what was written to stdin as the file content. 📥
• onchange — the code to run if file is modified.

---

📬 MESSAGES 📬

here's the little receipts this type hands out:

• chgrp <group> — changed group membership
• chown <owner> — changed owner
• chmod <mode> — changed mode
• create — empty file was created (no --source specified)
• remove — file exists, but state is absent, file will be removed by generated code.
• upload — file was uploaded

---

🌈 EXAMPLES 🌈

okay this is the fun part, let's get into it:

# Create  /etc/cdist-configured as an empty file
__file /etc/cdist-configured
# The same thing
__file /etc/cdist-configured --state present
# Use __file from another type
__file /etc/issue --source "$__type/files/archlinux" --state present
# Delete existing file
__file /etc/cdist-configured --state absent
# Supply some more settings
__file /etc/shadow --source "$__type/files/shadow" \
   --owner root --group shadow --mode 0640 \
   --state present
# Provide a default file, but let the user change it
__file /home/frodo/.bashrc --source "/etc/skel/.bashrc" \
   --state exists \
   --owner frodo --mode 0600
# Check that the file is present, show an error when it is not
__file /etc/somefile --state pre-exists
# Take file content from stdin
__file /tmp/whatever --owner root --group root --mode 644 --source - << DONE
    Here goes the content for /tmp/whatever
DONE

that last one with the heredoc? chef's kiss. 🍓

---

💜 AUTHORS 💜

Nico Schottelius <nico-cdist--@--schottelius.org>

---

📜 COPYING 📜

Copyright (C) 2011-2013 Nico Schottelius. You can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

---

⭐ COPYRIGHT ⭐

ungleich GmbH 2021

---

and that's the whole page, bestie!! this was cdist-type__file, version 7.0.0, dated Jul 31, 2022 — screenshot it, bookmark it, tell your friends, and go manage some files responsibly. mwah 💖✨🎀