cdist-contrib/type/__opendkim/man.rst
evilham ecd10de2d3
[__opendkim*] FreeBSD support and minor fixes
While adding FreeBSD support to the type I noticed various issues:

- We were making sure that the KeyTable and SigningTable were created in
  __opendkim_genkey, but that was being done with the default cdist permissions
  (0400) which could result in issues when reloading the service after privilege
  drop.
  This is addressed by checking that it exists/creating it in __opendkim (just
  once, not once per __opendkim_genkey call) with laxer permissions (0444).
- In __opendkim, the service was being started after the config file was
  installed. This is insufficient as OpenDKIM will refuse to start with the
  generated config if either SigningTable or KeyTable do not exist yet.
- __opendkim_genkey had the implicit assumption that the --directory parameter
  always ended in a slash. This was not documented and error-prone; we are now
  a bit laxer and add the trailing slash if it is missing.
- __opendkim_genkey was not changing permissions for the resulting .txt file.
  This was not critical for it to function, but it was inconsistent.
- As documented in #17, __opendkim allows for a --userid parameter that might
  cause issues with keys generated by __opendkim_genkey.
  This issue has not been addressed yet, but I recommend deprecating the
  --userid parameter.
2022-03-10 20:08:51 +01:00

99 lines
2.4 KiB
ReStructuredText

cdist-type__opendkim(7)
=======================
NAME
----
cdist-type__opendkim - Configure an instance of OpenDKIM
DESCRIPTION
-----------
OpenDKIM is a DKIM signing and verifying filter for MTAs. This type enables the
installation and basic configuration of an instance of OpenDKIM.
Note that this type does not generate or ensure that a key is present: use
`cdist-type__opendkim-genkey(7)` for that.
Note that this type is currently only implemented for Alpine Linux and FreeBSD.
Please contribute an implementation if you can.
REQUIRED PARAMETERS
-------------------
socket
A string specifying a socket to listen on for communication with the MTA. See
`opendkim.conf(5)` for details on the syntax.
OPTIONAL PARAMETERS
-------------------
basedir
A directory to `chdir(2)` to before beginning operations.
canonicalization
Directives for message canonicalization. See `opendkim.conf(5)` for details
on the syntax.
subdomains
Explicitely control whether subdomains should be signed as well. Expects a
string containing 'Y', 'N', 'y', 'n', 'yes' or 'no'.
umask
Set the umask for the socket and PID file.
userid
Change the user the opendkim program is to run as.
By default, Alpine Linux's OpenRC service will set this to `opendkim` on the
command-line and FreeBSD's rc will set it to `mailnull`.
custom-config
The string following this parameter is appended as-is in the configuration, to
enable more complex configurations.
BOOLEAN PARAMETERS
------------------
syslog
Log to syslog.
EXAMPLES
--------
.. code-block:: sh
__opendkim \
--socket inet:8891@localhost \
--basedir /var/lib/opendkim \
--canonicalization relaxed/simple \
--subdomains no \
--umask 002 \
--syslog \
--custom-config "Mode v"
require='__opendkim' \
__opendkim_genkey mykey \
--domain example.com \
--selector default \
--sigkey example.com
SEE ALSO
--------
`cdist-type__opendkim-genkey(7)`
`opendkim(8)`
`opendkim.conf(5)`
AUTHORS
-------
Joachim Desroches <joachim.desroches@epfl.ch>
Evilham <contact@evilham.com>
COPYING
-------
Copyright \(C) 2022 Joachim Desroches, Evilham. 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.