Merge branch 'wikijs' into 'master'

Add a type for wikijs.

See merge request ungleich-public/cdist-contrib!15

.gitlab-ci.yml

@@ -1,14 +1,29 @@
 stages:
     - test
+    - doc
 
-image: code.ungleich.ch:5050/ungleich-public/cdist/cdist-ci:latest
+image: code.ungleich.ch:5050/ungleich-public/cdist-contrib/ci-container:latest
 
 shellcheck:
     stage: test
     script:
-        - ./scripts/run-shellcheck.sh
+        - make lint
 
 manpages:
     stage: test
     script:
-      - ./scripts/run-manpage-checks.sh
+      - make check-manpages
+
+docs:
+    stage: doc
+    only:
+      - master
+    before_script:
+      - eval $(ssh-agent -s)
+      - echo "$CD_SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null
+      - mkdir -p ~/.ssh
+      - echo "$CD_SSH_SERVER_HOSTKEYS" > ~/.ssh/known_hosts
+      - chmod 644 ~/.ssh/known_hosts
+    script:
+      - make html
+      - sftp fnux@staticwebhosting.ungleich.ch:public_html/cdist-contrib <<< "put -r docs/dist/html/*"

Makefile

@@ -0,0 +1,70 @@
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "man             build only man user documentation"
+	@echo "html            build only html user documentation"
+	@echo "docs            build both man and html user documentation"
+	@echo "check-manpages  check for manpage in types"
+	@echo "lint            run shellcheck on types"
+	@echo "check           run both type manpage checks and linting"
+	@echo "clean           clean"
+
+DOCS_SRC_DIR=./docs/src
+TYPEDIR=./type
+
+SPHINXM=make -C $(DOCS_SRC_DIR) man
+SPHINXH=make -C $(DOCS_SRC_DIR) html
+SPHINXC=make -C $(DOCS_SRC_DIR) clean
+
+################################################################################
+# Manpages
+#
+MAN7DSTDIR=$(DOCS_SRC_DIR)/man7
+
+# Use shell / ls to get complete list - $(TYPEDIR)/*/man.rst does not work
+# Using ls does not work if no file with given pattern exist, so use wildcard
+MANTYPESRC=$(wildcard $(TYPEDIR)/*/man.rst)
+MANTYPEPREFIX=$(subst $(TYPEDIR)/,$(MAN7DSTDIR)/cdist-type,$(MANTYPESRC))
+MANTYPES=$(subst /man.rst,.rst,$(MANTYPEPREFIX))
+
+# Link manpage: do not create man.html but correct named file
+$(MAN7DSTDIR)/cdist-type%.rst: $(TYPEDIR)/%/man.rst
+	mkdir -p $(MAN7DSTDIR)
+	ln -sf "../../../$^" $@
+
+DOCSINDEX=$(MAN7DSTDIR)/index.rst
+DOCSINDEXH=$(DOCS_SRC_DIR)/index.rst.sh
+
+$(DOCSINDEX): $(DOCSINDEXH)
+	$(DOCSINDEXH)
+
+# Manpages: .cdist Types
+DOT_CDIST_PATH=${HOME}/.cdist
+DOTMAN7DSTDIR=$(MAN7DSTDIR)
+DOTTYPEDIR=$(DOT_CDIST_PATH)/type
+
+# Link manpage: do not create man.html but correct named file
+$(DOTMAN7DSTDIR)/cdist-type%.rst: $(DOTTYPEDIR)/%/man.rst
+	ln -sf "$^" $@
+
+man: $(MANTYPES) $(DOCSINDEX)
+	$(SPHINXM)
+
+html: $(MANTYPES) $(DOCSINDEX)
+	$(SPHINXH)
+
+docs: man html
+
+check-manpages:
+	./scripts/run-manpage-checks.sh
+
+lint:
+	./scripts/run-shellcheck.sh
+
+check: check-manpages lint
+
+clean:
+	$(SPHINXC)
+	rm -f docs/src/index.rst
+	rm -rf docs/src/man7/
+	rm -rf docs/src/__pycache__/

README.md

@@ -6,7 +6,8 @@ maintained in cdist itself or were not accepted in code cdist but could still
 be useful.
 
 This project does not have releases and is continously updated: see git history
-for change log.
+for change log. You will find HTML documentation at
+[contrib.cdi.st](https://contrib.cdi.st).
 
 ## Using cdist-contrib
 
@@ -32,14 +33,11 @@ And you would run [cdist][cdist] from the same directory as follows:
 
 ## Participating in the [cdist][cdist] community
 
-Join us on [#cdist:ungleich.ch][cdistmatrix] on matrix or on
-[#cdist over mattermost][cdistmattermost].
-
+Join us on [#cdist:ungleich.ch][cdistmatrix] on matrix!
 
 [cdist]: https://www.cdi.st/
 [cdistconfig]: https://www.cdi.st/manual/latest/cdist-configuration.html
 [cdistmatrix]: https://matrix.to/#/#cdist:ungleich.ch
-[cdistmattermost]: https://chat.ungleich.ch/ungleich/channels/cdist
 
 ## Contributing
 
@@ -53,3 +51,11 @@ Every type in cdist-contrib must:
 
   * Have a `man.rst` documentation page.
   * Pass [shellcheck](http://shellcheck.net/) without errors.
+
+## Other resources
+
+Some people/organizations are known to keep some cdist types that might be of
+interest to others:
+
+* [cdist-evilham](https://git.sr.ht/~evilham/cdist-evilham): Evilham's cdist-types
+* [cdist-recycledcloud](https://code.recycled.cloud/e-Durable/cdist-recycledcloud): e-Durable SA / Recycled Cloud public types

docs/src/Makefile

@@ -0,0 +1,235 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS   ?=
+SPHINXBUILD  ?= sphinx-build
+PAPER        ?=
+BUILDDIR     ?= ../dist
+# for cache, etc.
+_BUILDDIR     = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+    $(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(_BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  epub3      to make an epub3"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  dummy      to check syntax errors of document sources"
+
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf $(_BUILDDIR)/*
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+.PHONY: dirhtml
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/cdist-docs.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/cdist-docs.qhc"
+
+.PHONY: applehelp
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+.PHONY: devhelp
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/cdist-docs"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/cdist-docs"
+	@echo "# devhelp"
+
+.PHONY: epub
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:
+	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+	@echo
+	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: latex
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b cman $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	mkdir -p $(BUILDDIR)/man/man7
+	mv -f $(BUILDDIR)/man/*.7 $(BUILDDIR)/man/man7/
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+.PHONY: dummy
+dummy:
+	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
+	@echo
+	@echo "Build finished. Dummy builder generates no files."

docs/src/conf.py

@@ -0,0 +1,101 @@
+#!/usr/bin/env python3
+
+import sys
+import os
+import sphinx_rtd_theme
+
+from datetime import date
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+# sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath(os.path.join(
+    os.path.dirname(os.path.realpath(__file__)), "..", "..")))
+
+# -- General configuration ------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'docs.src.manpage',
+    'sphinx.ext.extlinks',
+]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+source_suffix = ['.rst']
+
+# The encoding of source files.
+# source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'cdist-contrib'
+copyright = 'cdist-contrib contributors'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+
+version = str(date.today())
+release = os.popen('git rev-parse HEAD').read()
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'cdistcontribdoc'
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+root_mandir = os.path.dirname(os.path.realpath(__file__))
+mandirs = []
+for mansubdir in ('man7',):
+    mandirs.append((os.path.join(root_mandir, mansubdir), mansubdir[-1]))
+man_pages = []
+for mandir, section in mandirs:
+    for root, dirs, files in os.walk(mandir):
+        for fname in files:
+            froot, fext = os.path.splitext(fname)
+            if fext == '.rst':
+                man_page = (os.path.join('man' + str(section), froot),
+                            froot, '', [], section)
+                man_pages.append(man_page)
+
+# man_pages = [
+#    ('cdist-type', 'cdist-type', 'cdist-type documentation',
+#         [author], 1),
+#    ('man7/cdist-type__file', 'cdist-type__file',
+#        '', [], 1),
+#    ('cdist-type__directory', 'cdist-type__directory',
+#        'cdist-type__directory documentation', [author], 1),
+# ]
+
+# If true, show URL addresses after external links.
+# man_show_urls = False

docs/src/index.rst.sh

@@ -0,0 +1,40 @@
+#!/bin/sh
+
+__cdist_pwd="$(pwd -P)"
+__cdist_mydir="${0%/*}";
+__cdist_abs_mydir="$(cd "$__cdist_mydir" && pwd -P)"
+__cdist_myname=${0##*/};
+__cdist_abs_myname="$__cdist_abs_mydir/$__cdist_myname"
+
+filename="${__cdist_myname%.sh}"
+dest="$__cdist_abs_mydir/$filename"
+
+if ! command -v pandoc > /dev/null; then
+	echo "Pandoc is required to generate HTML index from README." >&2
+	exit 1
+fi
+
+cd "$__cdist_abs_mydir"
+
+exec > "$dest"
+
+pandoc -f markdown -t rst ../../README.md
+
+cat << EOF
+
+.. toctree::
+   :hidden:
+
+EOF
+
+# If there is no such file then ls prints error to stderr,
+# so redirect stderr to /dev/null.
+for type in $(ls man7/cdist-type__*.rst 2>/dev/null | LC_ALL=C sort); do
+    no_dir="${type#man7/}";
+    no_type="${no_dir#cdist-type}";
+    name="${no_type%.rst}";
+    manref="${no_dir%.rst}"
+    man="${manref}(7)"
+
+    echo "      $name" "<man7/${manref}>"
+done

docs/src/manpage.py

@@ -0,0 +1,87 @@
+import sphinx.builders.manpage
+import sphinx.writers.manpage
+from docutils.frontend import OptionParser
+from sphinx.util.console import bold, darkgreen
+from six import string_types
+from docutils.io import FileOutput
+from os import path
+from sphinx.util.nodes import inline_all_toctrees
+from sphinx import addnodes
+from sphinx.util import logging
+
+"""
+    Extension based on sphinx builtin manpage.
+    It does not write its own .SH NAME based on config,
+    but leaves everything to actual reStructuredText file content.
+"""
+
+
+logger = logging.getLogger(__name__)
+
+
+class ManualPageTranslator(sphinx.writers.manpage.ManualPageTranslator):
+
+    def header(self):
+        tmpl = (".TH \"%(title_upper)s\" \"%(manual_section)s\""
+                " \"%(date)s\" \"%(version)s\" \"%(manual_group)s\"\n")
+        return tmpl % self._docinfo
+
+
+class ManualPageWriter(sphinx.writers.manpage.ManualPageWriter):
+
+    def __init__(self, builder):
+        super().__init__(builder)
+        self.translator_class = (
+            self.builder.get_translator_class() or ManualPageTranslator)
+
+
+class ManualPageBuilder(sphinx.builders.manpage.ManualPageBuilder):
+
+    name = 'cman'
+    default_translator_class = ManualPageTranslator
+
+    def write(self, *ignored):
+        docwriter = ManualPageWriter(self)
+        docsettings = OptionParser(
+            defaults=self.env.settings,
+            components=(docwriter,),
+            read_config_files=True).get_default_values()
+
+        logger.info(bold('writing... '), nonl=True)
+
+        for info in self.config.man_pages:
+            docname, name, description, authors, section = info
+            if isinstance(authors, string_types):
+                if authors:
+                    authors = [authors]
+                else:
+                    authors = []
+
+            targetname = '%s.%s' % (name, section)
+            logger.info(darkgreen(targetname) + ' { ', nonl=True)
+            destination = FileOutput(
+                destination_path=path.join(self.outdir, targetname),
+                encoding='utf-8')
+
+            tree = self.env.get_doctree(docname)
+            docnames = set()
+            largetree = inline_all_toctrees(self, docnames, docname, tree,
+                                            darkgreen, [docname])
+            logger.info('} ', nonl=True)
+            self.env.resolve_references(largetree, docname, self)
+            # remove pending_xref nodes
+            for pendingnode in largetree.traverse(addnodes.pending_xref):
+                pendingnode.replace_self(pendingnode.children)
+
+            largetree.settings = docsettings
+            largetree.settings.title = name
+            largetree.settings.subtitle = description
+            largetree.settings.authors = authors
+            largetree.settings.section = section
+
+            docwriter.write(largetree, destination)
+        logger.info("")
+
+
+def setup(app):
+    app.add_builder(ManualPageBuilder)

scripts/ci-container/Dockerfile

@@ -0,0 +1,7 @@
+# This image is used in the cdist-contrib CI for linting and generating the
+# documentation.
+FROM fedora:latest
+MAINTAINER Timothée Floure <fnux@ungleich.ch>
+
+RUN dnf install -y git findutils make python3-sphinx python3-sphinx_rtd_theme \
+			ShellCheck openssh-clients pandoc

scripts/run-shellcheck.sh

@@ -1,21 +1,29 @@
-#!/bin/sh
+#!/bin/sh -eu
 
-SHELLCHECKCMD="shellcheck -s sh -f gcc -x"
+SHELLCHECKCMD='shellcheck -s sh -f gcc -x'
 # Skip SC2154 for variables starting with __ since such variables are cdist
 # environment variables.
 SHELLCHECK_SKIP=': __.*is referenced but not assigned.*\[SC2154\]'
-SHELLCHECKTMP=".shellcheck.tmp"
+SHELLCHECKTMP='.shellcheck.tmp'
 
 # Move to top-level cdist-contrib directory.
-cd $(dirname $0)/..
+cd "$(dirname $0)"/..
 
-check () {
-	find type/ -type f $1 $2 -exec ${SHELLCHECKCMD} {} + | grep -v "${SHELLCHECK_SKIP}"  > "${SHELLCHECKTMP}"
-	test ! -s "${SHELLCHECKTMP}" || { cat "${SHELLCHECKTMP}"; exit 1; }
+check() {
+	find type/ -type f "$@" -exec ${SHELLCHECKCMD} {} + \
+	| grep -v "${SHELLCHECK_SKIP}" >>"${SHELLCHECKTMP}" || true
 }
 
-check -path "*/explorer/*"
-check -path "*/files/*.sh"
+rm -f "${SHELLCHECKTMP}"
+
+check -path '*/explorer/*'
+check -path '*/files/*' -name '*.sh'
 check -name manifest
 check -name gencode-local
 check -name gencode-remote
+
+if test -s "${SHELLCHECKTMP}"
+then
+	cat "${SHELLCHECKTMP}" >&2
+	exit 1
+fi

type/__dma/explorer/auth_conf

@@ -0,0 +1,49 @@
+#!/bin/sh -e
+#
+# 2020 Dennis Camera (dennis.camera at ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+# This explorer determines the path of dma's auth.conf file
+
+# No dma.conf -> use default
+test -f /etc/dma/dma.conf || {
+	echo /etc/dma/auth.conf
+	exit 0
+}
+test -r /etc/dma/dma.conf || {
+	echo 'Cannot read /etc/dma/dma.conf' >&2
+	exit 1
+}
+
+# Get AUTHPATH from dma.conf
+awk -F'[ \t]' '
+{
+	sub(/#.*$/, "", $0)  # remove comments
+	if (!$0) next  # ignore empty lines
+}
+$1 == "AUTHPATH" {
+	# Store authpath. In dma conf parsing last wins.
+	if ($2) authpath = substr($0, index($0, " ") + 1)
+}
+END {
+	if (authpath) {
+		print authpath
+		exit 0
+	} else exit 1
+}
+' /etc/dma/dma.conf \
+|| echo /etc/dma/auth.conf  # default

type/__dma/explorer/conf

@@ -0,0 +1,34 @@
+#!/bin/sh -e
+#
+# 2020 Dennis Camera (dennis.camera at ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+# This explorer returns a sorted list of "active" (= non-commented) lines
+# in the dma.conf file.
+# "Trailing" line comments are stripped off.
+#
+# NOTE: This explorer assumes that the sort(1) utility supports the non-POXIX
+#       -s (stable sort) option.
+
+CONF_PATH=/etc/dma  # set in Makefile
+dma_conf="${CONF_PATH:?}/dma.conf"
+
+test -f "${dma_conf}" || exit 0
+
+grep -v -e '^[ \t]*#\|^$' "${dma_conf}" \
+| sed -e 's/[ \t]*#.*$//' \
+| sort -s -k 1,1

type/__dma/files/update_dma_conf.awk

@@ -0,0 +1,178 @@
+#!/usr/bin/awk -f
+#
+# 2020 Dennis Camera (dennis.camera at ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+
+function comment_line(line) {
+	# returns the position in line at which the comment's text starts
+	# (0 if the line is not a comment)
+	match(line, /^[ \t]*\#+[ \t]*/)
+	return RSTART ? (RLENGTH + 1) : 0
+}
+function empty_line(line) { return line ~ /^[ \t]*$/ }
+function is_word(s) { return s ~ /^[A-Z_]+$/ }  # "looks like a plausible word"
+
+function first(line, sep_re) {
+	# returns the part of the line until sep is found
+	# (or the whole line if sep is not found)
+	if (!sep_re) sep_re = "[" SUBSEP "]"
+	match(line, sep_re)
+	return RSTART ? substr(line, 1, RSTART - 1) : line
+}
+
+function rest(line, sep_re) {
+	# returns the part of the line after the first occurrence of sep is found.
+	# (or nothing if sep is not found)
+	if (!sep_re) sep_re = "[" SUBSEP "]"
+	if (match(line, sep_re))
+		return substr(line, RSTART + RLENGTH)
+}
+
+function conf_pop(word, value) {
+	# returns the next value for the config `word` and delete it from the list.
+	# if value is set, this function will only return value if it is the first
+	# option in the list, otherwise it returns 0.
+
+	if (!(word in conf)) return 0
+	if (!value) {
+		if (index(conf[word], SUBSEP))  # more than one element?
+			value = substr(conf[word], 1, index(conf[word], SUBSEP) - 1)
+		else
+			value = conf[word]
+	}
+
+	if (index(conf[word], SUBSEP)) {
+		if (index(conf[word], value SUBSEP) != 1) return 0
+		conf[word] = substr(conf[word], length(value) + 2)
+	} else {
+		if (conf[word] != value) return 0
+		delete conf[word]
+	}
+	return value
+}
+
+function print_conf(word, value) {
+	# print a config line with the given parameters
+	printf "%s", word
+	if (value) printf " %s", value
+	printf "\n"
+}
+
+function print_confs(word,    value) {
+	# print config lines for all values stored in conf[word].
+	if (!(word in conf)) return
+	if (conf[word]) {
+		while (value = conf_pop(word))
+			print_conf(word, value)
+	} else {
+		print_conf(word)
+		delete conf[word]
+	}
+}
+
+BEGIN {
+	FS = "\n"
+	EQS = "[ \t]"  # copied from dma/conf.c
+
+	if (ARGV[2]) exit (e=1)
+
+	# Loop over file twice!
+	ARGV[2] = ARGV[1]
+	ARGC++
+
+	# read the "should" state into the `conf` array.
+	while (getline < "/dev/stdin") {
+		word = first($0, EQS)
+		if ((word in conf))
+			conf[word] = conf[word] SUBSEP rest($0, EQS)
+		else
+			conf[word] = rest($0, EQS)
+	}
+}
+
+# first pass, gather information about where which information is stored in the
+# current config file. This information will be used in the second pass.
+NR == FNR {
+	if (comment_line($0)) {
+		# comment line
+		word = first(substr($0, comment_line($0)), " ")
+		if (is_word(word)) last_occ["#" word] = FNR
+	} else {
+		word = first($0, EQS)
+		if (is_word(word)) last_occ[word] = FNR
+	}
+}
+
+# before second pass prepare hashes containing location information to be used
+# in the second pass.
+NR > FNR && FNR == 1 {
+	# First we drop the locations of commented-out options if a non-commented
+	# option is available. If a non-commented option is available, we will
+	# append new config options there to have them all at one place.
+	for (k in last_occ)
+		if (k ~ /^\#/ && (substr(k, 2) in last_occ))
+			delete last_occ[k]
+
+	# Reverse the option => line mapping. The line_map allows for easier lookups
+	# in the second pass.
+	for (k in last_occ) line_map[last_occ[k]] = k
+}
+
+# second pass, generate and output new config
+NR > FNR {
+	if (comment_line($0) || empty_line($0)) {
+		# comment or empty line
+		print
+
+		if ((FNR in line_map)) {
+			if (line_map[FNR] ~ /^\#/) {
+				# This line contains a commented config option. If the conf hash
+				# contains options to be set, we output them here because this
+				# option is not used in the current config.
+				k = substr(line_map[FNR], 2)
+				if ((k in conf)) print_confs(k)
+			}
+
+			if (("INSECURE" in conf) && line_map[FNR] ~ /^\#?SECURE$/) {
+				# INSECURE goes where SECURE comment is.
+				print_confs("INSECURE")
+			}
+		}
+	} else {
+		word = first($0, EQS)
+		value = rest($0, EQS)
+		sub(/[ \t]*\#.*$/, "", value)  # ignore comments in value
+
+		if ((word in conf) && value == first(conf[word])) {
+			# keep config options we want
+			conf_pop(word)
+			print
+		}
+
+		if ((FNR in line_map) && line_map[FNR] == word) {
+			# rest of config options should be here
+			print_confs(word)
+		}
+	}
+}
+
+END {
+	if (e) exit
+
+	# print rest of config options (
+	for (word in conf) print_confs(word)
+}

type/__dma/gencode-remote

@@ -0,0 +1,177 @@
+#!/bin/sh -e
+#
+# 2020 Dennis Camera (dennis.camera@ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+quote() { printf "'%s'" "$(printf '%s' "$*" | sed -e "s/'/'\\\\''/g")"; }
+drop_awk_comments() { quote "$(sed '/^[[:blank:]]*#.*$/d;/^$/d' "$@")"; }
+
+CONF_PATH=/etc/dma  # set in Makefile
+
+# Determine mailname
+if test -f "${__object:?}/parameter/mailname"
+then
+	mailname=$(cat "${__object:?}/parameter/mailname")
+else
+	case $(cat "${__global:?}/explorer/os")
+	in
+		(debian|devuan|ubuntu)
+			# On Debian-like systems use /etc/mailname unless --mailname is used
+			mailname='/etc/mailname'
+			;;
+		(*)
+			mailname=${__target_fqdn:?}
+			;;
+	esac
+fi
+
+
+# Generate "should" values for config
+conf_should=$(
+	if test -s "${__object:?}/parameter/smarthost"
+	then
+		printf 'SMARTHOST %s\n' "$(cat "${__object:?}/parameter/smarthost")"
+	fi
+
+	printf 'MAILNAME %s\n' "${mailname}"
+
+	if test -s "${__object:?}/explorer/auth_conf"
+	then
+		printf "AUTHPATH %s\n" "$(cat "${__object:?}/explorer/auth_conf")"
+	fi
+
+	case $(cat "${__object:?}/parameter/security")
+	in
+		(ssl|tls)
+			default_smtp_port=465
+			echo 'SECURETRANSFER'
+			;;
+		(starttls)
+			default_smtp_port=587
+			echo 'SECURETRANSFER'
+			echo 'STARTTLS'
+			;;
+		(opportunistic)
+			default_smtp_port=25
+			echo 'SECURETRANSFER'
+			echo 'STARTTLS'
+			echo 'OPPORTUNISTIC_TLS'
+			;;
+		(insecure)
+			default_smtp_port=25
+			echo 'INSECURE'
+			;;
+	esac
+
+	if test -s "${__object:?}/parameter/port"
+	then
+		printf 'PORT %u\n' "$(cat "${__object:?}/parameter/port")"
+	elif test "${default_smtp_port}" -ne 25  # DMA uses port 25 by default
+	then
+		printf 'PORT %u\n' "${default_smtp_port}"
+	fi
+
+	if test -f "${__object:?}/parameter/masquerade"
+	then
+		while read -r line
+		do
+			printf 'MASQUERADE %s\n' "${line}"
+		done <"${__object:?}/parameter/masquerade"
+	fi
+
+	if test -f "${__object:?}/parameter/defer"
+	then
+		echo 'DEFER'
+	fi
+
+	if test -f "${__object:?}/parameter/fullbounce"
+	then
+		echo 'FULLBOUNCE'
+	fi
+
+	if test -f "${__object:?}/parameter/nullclient"
+	then
+		test -s "${__object:?}/parameter/smarthost" || {
+			echo '--nullclient requires a --smarthost to be defined' >&2
+			exit 1
+		}
+
+		echo 'NULLCLIENT'
+	fi
+)
+# Sort conf_should to compare against "conf_is"
+conf_should=$(echo "${conf_should}" | sort -s -k 1,1)
+
+config_updated=false
+if ! echo "${conf_should}" | cmp -s "${__object:?}/explorer/conf" -
+then
+	# config needs to be updated
+	dma_conf="${CONF_PATH:?}/dma.conf"
+
+	# The following AWK script will output the new config file to be stored on
+	# disk. To do so it reads the current dma.conf file and the config options
+	# that should be set (from stdin).
+	# Note that the path to the current dma.conf is passed to AWK twice, because
+	# the new file cannot be generated in one pass.
+
+	# The logic tries to place options at a sensible location, that is:
+	# a) if the option is already used in the config file:
+	#    group all similar options (e.g. MASQUERADE) at one place in the order
+	#    they are listed in stdin.
+	# b) if it is a new option and a "default comment" (e.g. "#PORT 25") exists:
+	#    place options grouped directly after the comment (the comment is left
+	#    alone)
+	# c) otherwise:
+	#    options are grouped by word (the first word in the line) and appended
+	#    at the end of the file.
+
+	cat <<-CODE
+	awk $(drop_awk_comments "${__type:?}/files/update_dma_conf.awk") $(quote "${dma_conf}") <<'EOF' >$(quote "${dma_conf}.tmp") \
+	&& cat $(quote "${dma_conf}.tmp") >$(quote "${dma_conf}")
+	${conf_should}
+	EOF
+	rm $(quote "${dma_conf}.tmp")
+	CODE
+
+	config_updated=true
+	echo 'config updated' >>"${__messages_out:?}"
+fi
+
+
+# Send a test email if enabled and necessary (=configuration changed)
+if test -f "${__object:?}/parameter/send-test-mail"
+then
+	if grep -q '^__mail_alias/root:' "${__messages_in:?}" \
+	|| grep -q '^__dma_auth/' "${__messages_in:?}" \
+	|| ${config_updated}
+	then
+		cat <<-CODE
+		sendmail root <<'EOF'
+		Subject: [cdist] Test mail from '${__target_fqdn:?}'
+
+		Hi,
+
+		you can ignore this message.
+		Its sole purpose is to notify you that root mail on ${__target_fqdn:?}
+		will be redirected to you.
+
+		Enjoy!
+		EOF
+		CODE
+	fi
+fi

type/__dma/man.rst

@@ -0,0 +1,112 @@
+cdist-type__dma(7)
+============================
+
+NAME
+----
+cdist-type__dma - Setup the DragonFly Mail Agent as the MTA.
+
+
+DESCRIPTION
+-----------
+This (singleton) type uses DMA, a small Mail Transport Agent (MTA), to accept
+mails from locally installed Mail User Agents (MUA) and either deliver the mails
+to a remote smart host for delivery or communicate with remote SMTP servers
+directly.
+
+
+REQUIRED PARAMETERS
+-------------------
+None.
+
+
+BOOLEAN PARAMETERS
+------------------
+defer
+    If enabled, mail will not be sent immediately, but stored in a queue.
+    To flush the queue and send the mails, ```dma -q`` has to be run
+    periodically (e.g. using a cron job.)
+    This type does not manage such a cron job, but some operating systems ship
+    such a cron job with the package.
+fullbounce
+    Enable if bounce messages should include the complete original message,
+    not just the headers.
+nullclient
+    Enable to bypass aliases and local delivery, and instead forward all mails
+    to the defined ``--smarthost``.
+send-test-mail
+    If set, this type will send a test email to root after setup, to check if
+    the configured settings work.
+
+
+OPTIONAL PARAMETERS
+-------------------
+mailname
+    If present, this will be the hostname used to identify this host and the
+    remote part of the sender addresses.
+    If not defined, it defaults to ``/etc/mailname`` on Debian derivatives and
+    to ``__target_fqdn`` otherwise.
+    See `dma(8)` for more information.
+
+    Note: on Debian derivatives the ``/etc/mailname`` file should be updated
+    instead of using this parameter.
+masquerade
+    Masquerade the envelope-from addresses with this address/hostname.
+    Use this setting if mails are not accepted by destination mail servers
+    because your sender domain is invalid.
+    This option can be used multiple times.
+    For more information see the `dma(8)` man page.
+port
+    The port on which to deliver email.
+    If not provided, a sensible default port will be used based on the
+    ``--security`` argument.
+security
+    Configures whether and how DMA should use secure connections.
+
+    ssl/tls
+        Enable TLS/SSL secured transfer.
+    starttls
+        Use STARTTLS to establish a secure connection.
+    opportunistic (default)
+        Will try to establish a secure connection using STARTTLS, but allow
+        unencrypted transfer if STARTTLS fails.
+        Most useful when dma is used without a smarthost, delivering remote
+        messages directly to the outside mail exchangers.
+    insecure
+        allow plain text SMTP login over an insecure connection.
+        Should really *not* be used anymore!
+smarthost
+    The mail server used to send email.
+    It must be configured to act as a relay for the host being configured by
+    this type so that mail can be sent to users non-local to the smarthost.
+
+
+EXAMPLES
+--------
+
+.. code-block:: sh
+
+    # Install DMA and use the smarthost mx1.domain.tld to send mail.
+    __dma --smarthost mx1.domain.tld --send-test-mail
+
+    # Install DMA in a default configuration.
+    __dma
+
+
+SEE ALSO
+--------
+- `DragonFly Mail Agent <https://github.com/corecode/dma>`_
+- `DragonFly Handbook MTA <https://www.dragonflybsd.org/handbook/mta/>`_
+
+
+AUTHORS
+-------
+Evilham <contact@evilham.com>
+Dennis Camera <dennis.camera@ssrq-sds-fds.ch>
+
+
+COPYING
+-------
+Copyright \(C) 2020 Evilham and Dennis Camera. 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.

type/__dma/manifest

@@ -0,0 +1,66 @@
+#!/bin/sh -e
+#
+# 2020 Dennis Camera (dennis.camera@ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+os=$(cat "${__global:?}/explorer/os")
+
+# Install DMA
+case ${os}
+in
+	(alpine)
+		__package dma --state present
+		export require='__package/dma'
+		;;
+	(debian|devuan|ubuntu)
+		__package dma --state present
+		export require='__package/dma'
+		;;
+	(freebsd)
+		# Stop sendmail if necessary
+		__process 'sendmail' --name 'sendmail.*' --state absent \
+			--stop '/etc/rc.d/sendmail onestop'
+
+		# ... and disable it
+		__key_value 'rcconf-sendmail-enable' --file '/etc/rc.conf' \
+			--key 'sendmail_enable' --delimiter '=' --value '"NONE"' \
+			--exact_delimiter
+
+		# Setup mailwrapper accordingly
+		__file '/etc/mail/mailer.conf' --mode 0644 --source - <<-'EOF'
+			#
+			# Execute the "real" sendmail program, named /usr/libexec/sendmail/sendmail
+			#
+			sendmail	/usr/libexec/dma
+			send-mail	/usr/libexec/dma
+			mailq		/usr/libexec/dma
+			newaliases	/usr/libexec/dma
+			rmail		/usr/libexec/dma
+		EOF
+		;;
+	(*)
+		cat <<EOF >&2
+Your OS (${os}) is not supported yet.
+
+Maybe adding support is as simple as adapting the packages or allowing it,
+we highly encourage you to open a PR with the necessary changes.
+See: https://code.ungleich.ch/ungleich-public/cdist-contrib/
+EOF
+		exit 1
+		;;
+esac

type/__dma/parameter/boolean

@@ -0,0 +1,4 @@
+defer
+fullbounce
+nullclient
+send-test-mail

type/__dma/parameter/default/security

@@ -0,0 +1 @@
+opportunistic

type/__dma/parameter/optional

@@ -0,0 +1,4 @@
+mailname
+port
+security
+smarthost

type/__dma/parameter/optional_multiple

@@ -0,0 +1 @@
+masquerade

type/__dma_auth/explorer/auth_conf

@@ -0,0 +1 @@
+../../__dma/explorer/auth_conf

type/__dma_auth/explorer/state

@@ -0,0 +1,91 @@
+#!/bin/sh -e
+#
+# 2020 Dennis Camera (dennis.camera at ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+# This explorer looks for a line matching the server parameter
+# in dma's auth.conf and reports:
+#   present:            a line matching login + host + password exists
+#   absent:             no line matching login + host exists
+#   different_login:    a line exists but with a different login user
+#   different_password: a line exists but with a different password
+#   multiple:           multiple lines matching host exist (should not happen)
+
+auth_conf=$("${__type_explorer:?}/auth_conf")
+test -r "${auth_conf}" || exit 0
+
+awk -F'\n' '
+function getvalue(path) {
+	# Reads the first line of the file located at path and returns it.
+	getline < path
+	close(path)
+	return $0
+}
+
+BEGIN {
+	DP = "[: \t]"  # copied from dma/conf.c
+
+	parameter_dir = ENVIRON["__object"] "/parameter/"
+
+	# Read the parameters of this object
+	host_param = ENVIRON["__object_id"]
+	login_param = getvalue(parameter_dir "login")
+	passwd_param = getvalue(parameter_dir "password")
+
+	state = "absent"
+}
+
+/^#/ || /^$/ {
+	# skip comments and empty lines
+	next
+}
+
+{
+	# parse line
+
+	login = substr($0, 1, index($0, "|") - 1)
+	if (!login) { login = $0 }  # if no "|" found
+
+	host = substr($0, length(login) + 2)
+
+	if (match(host, DP)) {
+		passwd = substr(host, RSTART + 1)
+		host = substr(host, 1, RSTART - 1)
+	} else {
+		passwd = ""
+	}
+}
+
+host == host_param {
+	# a match…
+	if (state == "absent") {
+		if (login != login_param)
+			state = "different_login"
+		else if (passwd != passwd_param)
+			state = "different_password"
+		else
+			state = "present"
+	} else {
+		# report "multiple" to that the type can remove the duplicates.
+		state = "multiple"
+	}
+}
+
+END {
+	print state
+}
+' "${auth_conf}"

type/__dma_auth/files/update_dma_auth.awk

@@ -0,0 +1,93 @@
+#!/usr/bin/awk -f
+#
+# 2020 Dennis Camera (dennis.camera@ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+function getvalue(path) {
+	# Reads the first line of the file located at path and returns it.
+	getline < path
+	close(path)
+	return $0
+}
+
+function print_should() {
+	printf "%s|%s:%s\n", login_param, host_param, passwd_param
+}
+
+BEGIN {
+	FS = "\n"
+	DP = "[: \t]"  # copied from dma/conf.c
+
+	parameter_dir = ENVIRON["__object"] "/parameter/"
+
+	mode = (getvalue(parameter_dir "state") != "absent")
+
+	host_param = ENVIRON["__object_id"]
+	login_param = getvalue(parameter_dir "login")
+	passwd_param = getvalue(parameter_dir "password")
+}
+
+# skip comments and empty lines
+/^#/ || /^$/ {
+	print
+	next
+}
+
+{
+	# parse line (like dma/conf.c would)
+
+	login = substr($0, 1, index($0, "|") - 1)
+	if (!login) { login = $0 }  # if no "|" found
+
+	host = substr($0, length(login) + 2)
+
+	if (match(host, DP)) {
+		passwd = substr(host, RSTART + 1)
+		host = substr(host, 1, RSTART - 1)
+	} else {
+		passwd = ""
+	}
+}
+
+host == host_param {
+	if (mode) {
+		# state_should == present
+		if (!written) {
+			# replace first line if host matches (but only if no line has
+			# been written already -> no duplicates)
+			print_should()
+			written = 1
+		}
+		next
+	} else {
+		# state_should == absent
+		next
+	}
+}
+
+# leave other lines alone
+{
+	print
+}
+
+END {
+	if (mode && !written) {
+		# append line if no match to replace was found
+		print_should()
+	}
+}

type/__dma_auth/gencode-remote

@@ -0,0 +1,72 @@
+#!/bin/sh -e
+#
+# 2020 Dennis Camera (dennis.camera@ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+quote() { printf "'%s'" "$(printf '%s' "$*" | sed -e "s/'/'\\\\''/g")"; }
+drop_awk_comments() { quote "$(sed '/^[[:blank:]]*#.*$/d;/^$/d' "$@")"; }
+
+state_is=$(cat "${__object:?}/explorer/state")
+state_should=$(cat "${__object:?}/parameter/state")
+
+server=${__object_id:?}
+login=$(cat "${__object:?}/parameter/login")
+
+
+auth_conf=$(cat "${__object:?}/explorer/auth_conf")
+test -n "${auth_conf}" || {
+	echo 'Cannot determine path of dma auth.conf' >&2
+	exit 1
+}
+
+if test "${state_is}" = "${state_should}"
+then
+	# state is as it should
+	exit 0
+fi
+
+case ${state_should}
+in
+	(present)
+		test -n "${login}" || { echo '--login must be non-empty' >&2; exit 1; }
+
+		if test "${state_is}" = 'absent'
+		then
+			printf 'add authuser %s on %s\n' "${login}" "${server}" >>"${__messages_out:?}"
+		else
+			printf 'set authuser %s on %s\n' "${login}" "${server}" >>"${__messages_out:?}"
+		fi
+		;;
+	(absent)
+		printf 'delete authuser %s on %s\n' "${login}" "${server}" >>"${__messages_out:?}"
+		;;
+	(*)
+		printf 'Invalid --state: %s.\n' "${state_should}" >&2
+		printf 'Acceptable values are: present, absent.\n' >&2
+		exit 1
+		;;
+esac
+
+
+cat <<EOF
+test -f $(quote "${auth_conf}") || touch $(quote "${auth_conf}")
+
+awk $(drop_awk_comments "${__type:?}/files/update_dma_auth.awk") <$(quote "${auth_conf}") >$(quote "${auth_conf}.tmp") \
+&& cat $(quote "${auth_conf}.tmp") >$(quote "${auth_conf}")
+rm -f $(quote "${auth_conf}.tmp")
+EOF

type/__dma_auth/man.rst

@@ -0,0 +1,66 @@
+cdist-type__dma_auth(7)
+=======================
+
+NAME
+----
+cdist-type__dma_auth - Configure SMTP logins for the DragonFly Mail Agent MTA.
+
+
+DESCRIPTION
+-----------
+This cdist type allows you to set up credentials to log in to remote SMTP
+servers.
+
+NB: dma currently (v0.13) does not differentiate between users on a host.
+    It will use whatever user it finds in the ``auth.conf`` first.
+    Thus, this type will use the ``__object_id`` as the host specifier.
+
+
+REQUIRED PARAMETERS
+-------------------
+login
+    The user's LOGIN name on the SMTP server.
+password
+    The user's password (in plain text.)
+
+
+OPTIONAL PARAMETERS
+-------------------
+state
+    Either ``present`` or ``absent``. Defaults to ``present``.
+
+BOOLEAN PARAMETERS
+------------------
+None.
+
+
+EXAMPLES
+--------
+
+.. code-block:: sh
+
+    # Set the password for smarthost
+    __dma_auth smarthost.example.com --login joe --password hunter2
+
+    # Set credentials for user at an external provider
+    __dma_auth mail.provider.com --login paul@example.com --password letmein
+
+    # Delete credentials for example.com (for all users)
+    __dma_auth example.com --login '' --password '' --state absent
+
+SEE ALSO
+--------
+:strong:`cdist-type__dma`\ (7), :strong:`dma`\ (8)
+
+
+AUTHORS
+-------
+Dennis Camera <dennis.camera@ssrq-sds-fds.ch>
+
+
+COPYING
+-------
+Copyright \(C) 2020 Dennis Camera. 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.

type/__dma_auth/parameter/default/state

@@ -0,0 +1 @@
+present

type/__dma_auth/parameter/optional

@@ -0,0 +1 @@
+state

type/__dma_auth/parameter/required

@@ -0,0 +1,2 @@
+login
+password

type/__mail_alias/explorer/aliases

@@ -0,0 +1,73 @@
+#!/bin/sh -e
+#
+# 2020 Dennis Camera (dennis.camera at ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+# Find aliases for a given user name and print the aliases (each one on a
+# separate line)
+
+aliases_file=$("${__type_explorer:?}/aliases_file")
+test -r "${aliases_file}" || exit 0
+
+: "${__object_id:?}"  # assert __object_id is set, because it is used in AWK
+
+awk -F ':[ \t]*' '
+function print_aliases(aliases,    matches) {
+	# prints comma-separated aliases (one per line)
+	split(aliases, matches, /,[ \t]*/)
+	for (i in matches) {
+		gsub(/^[ \t]*|[ \t]*$/, "", matches[i])
+		if (matches[i]) print matches[i]
+	}
+}
+
+/^#/ {
+	# comment line (ignore)
+	select = 0; cont = 0  # comments terminate alias lists and continuations
+	next
+}
+
+{
+	# is this line a continuation line?
+	# (the prev. line ended in a backslash or the line starts with whitespace)
+	is_cont = /^[ \t]/ || cont
+
+	# detect if the line is a line to be continued (ends with a backslash)
+	cont = /\\$/
+
+	# if it is, we drop the backslash from the line
+	if (cont) sub(/[ \t]*\\$/, "", $0)
+}
+
+is_cont {
+	# if in the alias list of the "target" user, we also print these aliases.
+	if (select) print_aliases($0)
+	next
+}
+
+$1 == ENVIRON["__object_id"] {
+	# "target" user -> print alias list
+	select = 1
+	print_aliases($2)
+	next
+}
+
+{
+	# other user
+	select = 0
+}
+' "${aliases_file}"

type/__mail_alias/explorer/aliases_file

@@ -0,0 +1,52 @@
+#!/bin/sh -e
+#
+# 2020 Dennis Camera (dennis.camera at ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+# This explorer finds the aliases file to modify.
+
+found() { echo "$*"; exit 0; }
+
+check_file() {
+	if test -f "$1"
+	then
+		found "$1"
+	fi
+}
+
+case $("${__explorer:?}/os")
+in
+	(freebsd|openbsd|solaris)
+		check_file /etc/mail/aliases
+
+		# default
+		found /etc/mail/aliases
+		;;
+	(alpine|debian|devuan|ubuntu)
+		check_file /etc/aliases
+
+		# default
+		found /etc/aliases
+		;;
+	(*)
+		check_file /etc/mail/aliases
+		check_file /etc/aliases
+
+		# default
+		found /etc/aliases
+		;;
+esac

type/__mail_alias/files/update_aliases.awk

@@ -0,0 +1,96 @@
+#!/usr/bin/awk -f
+#
+# 2020 Dennis Camera (dennis.camera@ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+function getvalue(path,    line) {
+	# Reads the first line of the file located at path and returns it.
+	getline line < path
+	close(path)
+	return line
+}
+
+function sepafter(f, def,    _) {
+	# finds the separator between field $f and $(f+1)
+	_ = substr($0, length($f)+1, index(substr($0, length($f)+1), $(f+1))-1)
+	return _ ? _ : def
+}
+
+function write_aliases(    line) {
+	if (aliases_written) return
+
+	# print aliases line
+	printf "%s%s", ENVIRON["__object_id"], sepafter(1, ": ")
+	while ((getline line < aliases_should_file) > 0) {
+		if (aliases_written) printf ", "
+		printf "%s", line
+		aliases_written = 1
+	}
+	printf "\n"
+	close(aliases_should_file)
+}
+
+BEGIN {
+	FS = ":[ \t]*"
+
+	parameter_dir = ENVIRON["__object"] "/parameter/"
+
+	mode = (getvalue(parameter_dir "state") != "absent")
+	aliases_should_file = (parameter_dir "/alias")
+}
+
+/^[ \t]*\#/ {
+	# comment line (leave alone)
+	select = 0; cont = 0  # comments terminate alias lists and continuations
+	print
+	next
+}
+
+{
+	# is this line a continuation line?
+	# (the prev. line ended in a backslash or the line starts with whitespace)
+	is_cont = /^[ \t]/ || cont
+
+	# detect if the line is a line to be continued (ends with a backslash)
+	cont = /\\$/
+}
+
+is_cont {
+	# we only print the line if it has not been rewritten (select)
+	if (!select) print
+	next
+}
+
+$1 == ENVIRON["__object_id"] {
+	# "target" user -> rewrite aliases list
+	select = 1
+	if (mode) write_aliases()
+	next
+}
+
+{
+	# other user
+	select = 0
+	print
+}
+
+END {
+	# if the last line was an alias, the separator will be reused (looks better)
+	if (mode && !aliases_written)
+		write_aliases()
+}

type/__mail_alias/gencode-remote

@@ -0,0 +1,87 @@
+#!/bin/sh -e
+#
+# 2020 Dennis Camera (dennis.camera@ssrq-sds-fds.ch)
+#
+# This file is part of cdist.
+#
+# cdist is free software: 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.
+#
+# cdist is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with cdist. If not, see <http://www.gnu.org/licenses/>.
+#
+
+quote() { printf "'%s'" "$(printf '%s' "$*" | sed -e "s/'/'\\\\''/g")"; }
+drop_awk_comments() { quote "$(sed '/^[[:blank:]]*#.*$/d;/^$/d' "$@")"; }
+
+aliases_file=$(cat "${__object:?}/explorer/aliases_file")
+
+test -n "${aliases_file}" || {
+	echo 'Could not determine aliases file path.' >&2
+	exit 1
+}
+
+
+state_should=$(cat "${__object:?}/parameter/state")
+
+case ${state_should}
+in
+	(present)
+		if cmp -s "${__object:?}/explorer/aliases" "${__object:?}/parameter/alias"
+		then
+			# all good!
+			exit 0
+		fi
+
+		test -s "${__object:?}/parameter/alias" || {
+			printf 'The --alias parameter is required if --state present.\n' >&2
+			printf 'Use --state absent to remove all aliases.\n' >&2
+			exit 1
+		}
+
+		if test -s "${__object:?}/explorer/aliases"
+		then
+			echo "update aliases" >>"${__messages_out:?}"
+		else
+			echo "add aliases" >>"${__messages_out:?}"
+		fi
+		;;
+	(absent)
+		# nothing to do if no aliases found.
+		test -s "${__object:?}/explorer/aliases" || exit 0
+
+		echo "delete aliases" >>"${__messages_out:?}"
+		;;
+	(*)
+		printf 'Invalid --state: %s.\n' "${state_should}" >&2
+		printf 'Acceptable values are: present, absent.\n' >&2
+		exit 1
+esac
+
+cat <<EOF
+test -f $(quote "${aliases_file}") || touch $(quote "${aliases_file}")
+
+awk $(drop_awk_comments "${__type:?}/files/update_aliases.awk") <$(quote "${aliases_file}") >$(quote "${aliases_file}.tmp") \
+|| {
+	rm -f $(quote "${aliases_file}.tmp")
+	echo 'Generating new aliases file failed!' >&2
+	exit 1
+}
+
+if ! cmp -s $(quote "${aliases_file}") $(quote "${aliases_file}.tmp")
+then
+	# aliases file was modified, replace:
+	cat $(quote "${aliases_file}.tmp") >$(quote "${aliases_file}")
+
+	# then, run newaliases if present ("missing" on Alpine Linux because of typo)
+	command -v newaliases >/dev/null 2>&1 && newaliases || true
+fi
+rm -f $(quote "${aliases_file}.tmp")
+EOF

type/__mail_alias/man.rst

@@ -0,0 +1,76 @@
+cdist-type__mail_alias(7)
+=========================
+
+NAME
+----
+cdist-type__mail_alias - Manage mail aliases.
+
+
+DESCRIPTION
+-----------
+This cdist type allows you to configure mail aliases (/etc/aliases).
+
+
+REQUIRED PARAMETERS
+-------------------
+None.
+
+
+OPTIONAL PARAMETERS
+-------------------
+state
+    'present' or 'absent', defaults to 'present'
+alias
+    an alias, i.e. a mail address where mail for the user should be redirected
+    to.
+    This parameter can be specified multiple times to redirect to multiple
+    recipients.
+    If ``--state`` is ``present`` this parameter is required.
+    See `aliases(5)` for the different forms this parameter can take.
+
+
+BOOLEAN PARAMETERS
+------------------
+None.
+
+
+EXAMPLES
+--------
+
+.. code-block:: sh
+
+    # Redirect root mail to a "real" email address
+    __mail_alias root --alias admin@example.com
+
+    # Disable redirection of mail for joe
+    __mail_alias joe --state absent
+
+
+BUGS
+----
+- Quoted strings are not parsed by this type. As a result, aliases
+  containing ``,`` (commas) are treated incorrectly (they are treated as
+  separate aliases.)
+  Make sure that email addresses, file names, and pipe commands do not contain
+  commas.
+- ``:include:`` directives in the aliases file are not evaluated by this type.
+  They are treated like a regular alias, the values of the included file are
+  not expanded.
+
+
+SEE ALSO
+--------
+:strong:`aliases`\ (5)
+
+
+AUTHORS
+-------
+Dennis Camera <dennis.camera@ssrq-sds-fds.ch>
+
+
+COPYING
+-------
+Copyright \(C) 2020 Dennis Camera. 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.

type/__mail_alias/parameter/default/state

@@ -0,0 +1 @@
+present

type/__mail_alias/parameter/optional

@@ -0,0 +1 @@
+state

type/__mail_alias/parameter/optional_multiple

@@ -0,0 +1 @@
+alias

type/__matrix_element/man.rst

@@ -1,5 +1,5 @@
 cdist-type__matrix_element(7)
-======================
+=============================
 
 NAME
 ----

type/__matterbridge/man.rst

@@ -33,9 +33,9 @@ EXAMPLES
 
 .. code-block:: sh
 
-    __matterbridge --version 1.16.3 --config - << EOF
+    __matterbridge --version 1.16.3 --config - <<- EOF
     [...]
-EOF
+    EOF
 
 
 SEE ALSO

type/__netbox/man.rst

@@ -122,7 +122,6 @@ basepath
     webroot ``/``. For example, if installed at https://example.com/netbox/, set
     the value ``netbox/``.
 
-http-proxy
 https-proxy
     Proxy which will be used with any HTTP request like webhooks.
 
@@ -171,12 +170,12 @@ redis-ssl
 
 smtp-use-tls
     Uses TLS to connect to the SMTP email server. `See documentation
-    <https://docs.djangoproject.com/en/3.1/ref/settings/#email-use-tls>`_
+    <https://docs.djangoproject.com/en/3.1/ref/settings/#email-use-tls>`__
     for more information.
 
 smtp-use-ssl
     Uses implicit TLS with the SMTP email server. `See documentation
-    <https://docs.djangoproject.com/en/3.1/ref/settings/#email-use-ssl>`_
+    <https://docs.djangoproject.com/en/3.1/ref/settings/#email-use-ssl>`__
     for more information.
 
 login-required

type/__netbox_uwsgi/man.rst

@@ -65,10 +65,7 @@ protocol
     parameter. Possible values are ``uwsgi``, ``http``, ``fastcgi`` and
     ``scgi``. If nothing given, it defaults to ``uwsgi``.
 
-uwsgi-bind
-http-bind
-fastcgi-bind
-scgi-bind
+scgi-bind, uwsgi-bind, http-bind, fastcgi-bind
     Bind the application to a specific protocol instead of implicit uwsgi via
     ``--bind-to``. If such parameter given, ``--bind-to`` will be ignored. Must
     be a UNIX/TCP socket. Can be set multiple times.

type/__unbound/files/unbound.conf.sh

@@ -1,10 +1,5 @@
 #!/bin/sh
 
-module_config="validator iterator"
-if [ -n "$DNS64_PREFIX" ]; then
-	module_config="dns64 $module_config"
-fi
-
 generate_interface() {
   for i in $INTERFACES; do
     echo "	interface: $i"
@@ -31,12 +26,6 @@ generate_local_data() {
 	done
 }
 
-generate_dns64_prefix() {
-	if [ -n "$DNS64_PREFIX" ]; then
-		echo "	dns64-prefix: $DNS64_PREFIX"
-	fi
-}
-
 cat << EOF
 #
 # THIS FILE HAS BEEN GENERATED BY CDIST, DO NOT EDIT BY HAND.
@@ -517,7 +506,7 @@ $(generate_access_control)
 	# most modules have to be listed at the beginning of the line,
 	# except cachedb(just before iterator), and python (at the beginning,
 	# or, just before the iterator).
-	module-config: "$module_config"
+	module-config: "dns64 validator iterator"
 
 	# File with trusted keys, kept uptodate using RFC5011 probes,
 	# initial file like trust-anchor-file, then it stores metadata.
@@ -787,8 +776,7 @@ $(generate_local_data)
 
 	# DNS64 prefix. Must be specified when DNS64 is use.
 	# Enable dns64 in module-config.  Used to synthesize IPv6 from IPv4.
-	# dns64-prefix: $DNS64_PREFIX"
-	$(generate_dns64_prefix)
+	dns64-prefix: $DNS64_PREFIX
 
 	# DNS64 ignore AAAA records for these domains and use A instead.
 	# dns64-ignore-aaaa: "example.com"

type/__unbound/gencode-remote

@@ -2,7 +2,7 @@
 
 UNBOUND_CERTS_DIR=/etc/unbound
 
-if [ -f "$__object/parameter/enable-rc" ]; then
+if [ -f "$__object/parameter/enable_rc" ]; then
 	echo "unbound-control-setup -d $UNBOUND_CERTS_DIR"
 	echo "chown unbound:unbound $UNBOUND_CERTS_DIR/*.pem $UNBOUND_CERTS_DIR/*.key"
 fi

type/__unbound/man.rst

@@ -13,6 +13,9 @@ answers from specified upstrean DNS server. This is a singleton type.
 
 REQUIRED PARAMETERS
 -------------------
+dns64_prefix
+  IPv6 prefix used for DNS64.
+
 forward_addr
   DNS servers used to lookup names, can be provided multiple times. It can be
   either an IPv4 or IPv6 address but no domain name.
@@ -23,21 +26,18 @@ interface
   Interface to listen on, can be provided multiple times. Defaults to
   '127.0.0.1' and '::1'.
 
-access-control
+access_control
   Controls which clients are allowed queries to the unbound service (everything
   but localhost is refused by default), can be provided multiple times. The
   format is described in unbound.conf(5).
 
-rc-interface
+rc_interface
   Address or path to socket used for remote control (see `--enable_control`. Defaults to `127.0.0.1`).
 
-local-data
+local_data
   Configure local data, which is served in reply to queries for it. Can be
   specified multiple times.
 
-dns64-prefix
-  Enable DNS64 with specified prefix.
-
 BOOLEAN PARAMETERS
 ------------------
 disable-ip4
@@ -48,7 +48,7 @@ disable-ip6
   Do not answer or issue queries over IPv6. Cannot be used alongside the
   `--disable-ip4` flag.
 
-enable-rc
+enable_rc
   Enable remote control (see `unbound-control(8)`).
 
 EXAMPLES
@@ -58,12 +58,12 @@ EXAMPLES
 
     __ungleich_unbound \
       --interface '::0' \
-      --dns64-prefix '2a0a:e5c0:2:10::/96' \
-      --forward-addr '2a0a:e5c0:2:1::5' \
-      --forward-addr '2a0a:e5c0:2:1::6' \
-      --access-control '::0/0 deny' \
-      --access-control '2a0a:e5c0::/29 allow' \
-      --access-control '2a09:2940::/29 allow' \
+      --dns64_prefix '2a0a:e5c0:2:10::/96' \
+      --forward_addr '2a0a:e5c0:2:1::5' \
+      --forward_addr '2a0a:e5c0:2:1::6' \
+      --access_control '::0/0 deny' \
+      --access_control '2a0a:e5c0::/29 allow' \
+      --access_control '2a09:2940::/29 allow' \
       --ip6
 
 SEE ALSO

type/__unbound/manifest

@@ -33,55 +33,52 @@ case "$os" in
 esac
 
 # Required parameters:
-FORWARD_ADDRS=$(cat "$__object/parameter/forward-addr")
+DNS64_PREFIX=$(cat "$__object/parameter/dns64_prefix")
+export DNS64_PREFIX
+FORWARD_ADDRS=$(cat "$__object/parameter/forward_addr")
 export FORWARD_ADDRS
 
 # Optional parameters:
-if [ -f "$__object/parameter/dns64-prefix" ]; then
-	DNS64_PREFIX=$(cat "$__object/parameter/dns64-prefix")
-	export DNS64_PREFIX
-fi
-
 if [ -f "$__object/parameter/interface" ]; then
    INTERFACES=$(cat "$__object/parameter/interface")
    export INTERFACES
 fi
 
-if [ -f "$__object/parameter/access-control" ]; then
-   ACCESS_CONTROLS=$(cat "$__object/parameter/access-control")
+if [ -f "$__object/parameter/access_control" ]; then
+   ACCESS_CONTROLS=$(cat "$__object/parameter/access_control")
    export ACCESS_CONTROLS
 fi
 
-if [ -f "$__object/parameter/rc-interface" ]; then
-   RC_INTERFACE=$(cat "$__object/parameter/rc-interface")
+if [ -f "$__object/parameter/rc_interface" ]; then
+   RC_INTERFACE=$(cat "$__object/parameter/rc_interface")
    export RC_INTERFACE
 fi
 
-if [ -f "$__object/parameter/local-data" ]; then
-   LOCAL_DATA=$(cat "$__object/parameter/local-data")
+if [ -f "$__object/parameter/local_data" ]; then
+   LOCAL_DATA=$(cat "$__object/parameter/local_data")
    export LOCAL_DATA
 fi
 
 # Boolean parameters:
-if [ -f "$__object/parameter/disable-ip4" ] && \
-   [ -f "$__object/parameter/disable-ip6" ]; then
+if [ -f "$__object/parameter/disable_ip4" ] && \
+   [ -f "$__object/parameter/disable_ip6" ]; then
     echo "--disable-ip4 and --disable-ip6 cannot be used at the same time." >&2
     exit 1
 fi
 
-if [ -f "$__object/parameter/disable-ip4" ]; then
+if [ -f "$__object/parameter/disable_ip4" ]; then
     export DO_IP4='no'
 else
     export DO_IP4='yes'
 fi
 
-if [ -f "$__object/parameter/disable-ip6" ]; then
+if [ -f "$__object/parameter/disable_ip6" ]; then
     export DO_IP6='no'
 else
     export DO_IP6='yes'
 fi
 
-if [ -f "$__object/parameter/enable-rc" ]; then
+if [ -f "$__object/parameter/enable_rc" ]; then
     export RC_ENABLE='yes'
 else
     export RC_ENABLE='no'

type/__unbound/parameter/boolean

@@ -1,3 +1,3 @@
-disable-ip6
-disable-ip4
-enable-rc
+disable_ip6
+disable_ip4
+enable_rc

type/__unbound/parameter/optional

@@ -1 +1 @@
-rc-interface
+rc_interface

type/__unbound/parameter/optional_multiple

@@ -1,3 +1,3 @@
-access-control
-local-data
+access_control
+local_data
 interface

type/__unbound/parameter/required

@@ -0,0 +1 @@
+dns64_prefix

type/__unbound/parameter/required_multiple

@@ -1 +1 @@
-forward-addr
+forward_addr

type/__wikijs/files/config.yml.sh

@@ -0,0 +1,46 @@
+#!/bin/sh
+
+if [ $# -ne 1 ];
+then
+	echo "You have to give me the database password as an argument:"
+	echo "on some systems, anyone can read env(1)."
+	exit 1;
+fi
+
+generate_ssl_section () {
+
+	cat << EOF
+ssl:
+  enabled: ${SSL}
+EOF
+
+if [ "$SSL" = "true" ]; then
+	cat << EOF
+  port: $HTTPS_PORT
+  provider: letsencrypt
+  domain: ${__target_host:?}
+  subscriberEmail: ${LE_EMAIL:?}
+EOF
+	fi
+}
+
+cat << EOF
+port: $HTTP_PORT
+db:
+  type: postgres
+  host: localhost
+  port: 5432
+  user: ${DB_USER:?}
+  pass: $1
+  db: ${DB_NAME:?}
+  ssl: false
+$(generate_ssl_section)
+pool:
+  min: 2
+  max: 10
+bindIP: 0.0.0.0
+logLevel: warn
+offline: false
+ha: false
+dataPath: ./data
+EOF

type/__wikijs/files/wikijs-openrc

@@ -0,0 +1,10 @@
+#!/sbin/openrc-run
+
+command='/usr/bin/node'
+command_args='server'
+command_background=true
+description="Run wiki.js"
+directory='/var/wiki'
+error_log=/var/log/"$RC_SVCNAME".err
+output_log=/var/log/"$RC_SVCNAME".log
+pidfile="/run/$RC_SVCNAME.pid"

type/__wikijs/gencode-remote

@@ -0,0 +1,26 @@
+#!/bin/sh
+
+VERSION_FILE=/var/wiki/version
+version=$(cat "${__object:?}/parameter/version")
+
+# Check for installation
+cat << EOF
+if [ -f $VERSION_FILE ] && [ "\$(cat $VERSION_FILE)" = "$version" ];
+then
+	# Assume everything is done already.
+	exit 0;
+else
+	echo "$version" > $VERSION_FILE
+fi
+EOF
+
+# Download and copy source
+cat << EOF
+wget -O - https://github.com/Requarks/wiki/releases/download/$version/wiki-js.tar.gz | tar xz -C /var/wiki
+EOF
+
+# Install deps and launch
+cat << EOF
+cd /var/wiki || exit 1
+service wikijs restart
+EOF

type/__wikijs/man.rst

@@ -0,0 +1,64 @@
+cdist-type__wikijs(7)
+========================
+
+NAME
+----
+cdist-type__wikijs - Deploy the wiki.js software.
+
+DESCRIPTION
+-----------
+
+See wiki.js.org for more information. This type deploys with a postgresql
+database, since it is the upstream recommended for production, and they seem to
+strongly suggest that in the next releases, they will not support anything else.
+
+Currently, this type servers wikijs as standalone, listening on ports 80 and
+443, and with a service file for OpenRC. Feel free to contribute a
+generalisation if you require one.
+
+REQUIRED PARAMETERS
+-------------------
+
+database-password
+  The password to the PSQL database.
+
+version
+  'wikijs' version to be deployed.
+
+OPTIONAL PARAMETERS
+-------------------
+
+database
+  The name of the PSQL database to connect to. If omitted, then 'wikijs' is
+  used.
+
+database-user
+  The name of the PSQL database user to connec as. If omitted, then 'wikijs' is
+  used.
+
+letsencrypt-mail
+  If the SSL parameter is passed, then we setup wikijs to automatically obtain
+  certificates: this is the email used to sign up to a LE account.
+
+http-port
+  Specify HTTP port, defaults to 80.
+
+http-port
+  Specify HTTPS port, defaults to 443. Only relevant if the SSL flag is enabled.
+
+BOOLEAN PARAMETERS
+------------------
+
+ssl
+  Whether or not to enable the wikijs automatic obtention of LE certificates.
+
+AUTHORS
+-------
+Joachim Desroches <joachim.desroches@epfl.ch>
+
+COPYING
+-------
+Copyright \(C) 2020 Joachim Desroches. 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.

type/__wikijs/manifest

@@ -0,0 +1,64 @@
+#!/bin/sh
+
+os="$(cat "${__global:?}"/explorer/os)"
+
+case "$os" in
+	alpine)
+		:
+		;;
+	*)
+		echo "This type has no implementation for $os. Aborting." >&2;
+		exit 1;
+esac
+
+DB_USER=wikijs
+if [ -f "${__object:?}/parameter/database-user" ];
+then
+	DB_USER="$(cat "${__object:?}/parameter/database-user")"
+fi
+export DB_USER
+
+DB_NAME=wikijs
+if [ -f "${__object:?}/parameter/database" ];
+then
+	DB_NAME="$(cat "${__object:?}/parameter/database")"
+fi
+export DB_NAME
+
+SSL=false
+if [ -f "${__object:?}/parameter/ssl" ];
+then
+	SSL=true
+fi
+export SSL
+
+if [ "$SSL" = "true" ];
+then
+	if [ -f "${__object:?}/parameter/letsencrypt-mail" ];
+	then
+		LE_EMAIL="$(cat "${__object:?}/parameter/letsencrypt-mail")"
+		export LE_EMAIL
+	else
+		echo "You must specify an email account if you request SSL."
+		echo "Hit me."
+		exit 1
+	fi
+fi
+
+HTTP_PORT=$(cat "${__object:?}/parameter/http-port")
+HTTPS_PORT=$(cat "${__object:?}/parameter/https-port")
+export HTTP_PORT HTTPS_PORT
+
+db_pass="$(cat "${__object:?}/parameter/database-password")"
+
+__package nodejs
+__directory /var/wiki/
+
+# These things are Alpine-dependant.
+__file /etc/init.d/wikijs --source "${__type:?}/files/wikijs-openrc"
+__package nghttp2-dev  # Required for some reason, else a symbol is missing
+
+mkdir -p "${__object:?}/files"
+"${__type:?}/files/config.yml.sh" "$db_pass" > "${__object:?}/files/config.yml"
+require='__directory/var/wiki' \
+	__file /var/wiki/config.yml --source "${__object:?}/files/config.yml"

type/__wikijs/parameter/boolean

@@ -0,0 +1 @@
+ssl

type/__wikijs/parameter/default/http-port

@@ -0,0 +1 @@
+80

type/__wikijs/parameter/default/https-port

@@ -0,0 +1 @@
+443

type/__wikijs/parameter/optional

@@ -0,0 +1,5 @@
+database
+database-user
+letsencrypt-mail
+http-port
+https-port

type/__wikijs/parameter/required

@@ -0,0 +1,2 @@
+database-password
+version