nixos/acme: Add module documentation
This commit is contained in:
Franz Pletz
parent
9374ddb895
commit
1685b9d06e
4 changed files with 134 additions and 58 deletions
|
|
@ -26,6 +26,7 @@ effect after you run <command>nixos-rebuild</command>.</para>
|
|||
|
||||
<!-- FIXME: auto-include NixOS module docs -->
|
||||
<xi:include href="postgresql.xml" />
|
||||
<xi:include href="acme.xml" />
|
||||
<xi:include href="nixos.xml" />
|
||||
|
||||
<!-- Apache; libvirtd virtualisation -->
|
||||
|
|
|
|||
|
|
@ -55,6 +55,7 @@ let
|
|||
cp -prd $sources/* . # */
|
||||
chmod -R u+w .
|
||||
cp ${../../modules/services/databases/postgresql.xml} configuration/postgresql.xml
|
||||
cp ${../../modules/security/acme.xml} configuration/acme.xml
|
||||
cp ${../../modules/misc/nixos.xml} configuration/nixos.xml
|
||||
ln -s ${optionsDocBook} options-db.xml
|
||||
echo "${version}" > version
|
||||
|
|
|
|||
|
|
@ -131,67 +131,72 @@ in
|
|||
};
|
||||
|
||||
###### implementation
|
||||
config = mkIf (cfg.certs != { }) {
|
||||
config = mkMerge [
|
||||
(mkIf (cfg.certs != { }) {
|
||||
|
||||
systemd.services = flip mapAttrs' cfg.certs (cert: data:
|
||||
let
|
||||
cpath = "${cfg.directory}/${cert}";
|
||||
cmdline = [ "-v" "-d" cert "--default_root" data.webroot "--valid_min" cfg.validMin ]
|
||||
++ optionals (data.email != null) [ "--email" data.email ]
|
||||
++ concatMap (p: [ "-f" p ]) data.plugins
|
||||
++ concatLists (mapAttrsToList (name: root: [ "-d" (if root == null then name else "${name}:${root}")]) data.extraDomains);
|
||||
systemd.services = flip mapAttrs' cfg.certs (cert: data:
|
||||
let
|
||||
cpath = "${cfg.directory}/${cert}";
|
||||
cmdline = [ "-v" "-d" cert "--default_root" data.webroot "--valid_min" cfg.validMin ]
|
||||
++ optionals (data.email != null) [ "--email" data.email ]
|
||||
++ concatMap (p: [ "-f" p ]) data.plugins
|
||||
++ concatLists (mapAttrsToList (name: root: [ "-d" (if root == null then name else "${name}:${root}")]) data.extraDomains);
|
||||
|
||||
in nameValuePair
|
||||
("acme-${cert}")
|
||||
({
|
||||
description = "ACME cert renewal for ${cert} using simp_le";
|
||||
after = [ "network.target" ];
|
||||
serviceConfig = {
|
||||
Type = "oneshot";
|
||||
SuccessExitStatus = [ "0" "1" ];
|
||||
PermissionsStartOnly = true;
|
||||
User = data.user;
|
||||
Group = data.group;
|
||||
PrivateTmp = true;
|
||||
};
|
||||
path = [ pkgs.simp_le ];
|
||||
preStart = ''
|
||||
mkdir -p '${cfg.directory}'
|
||||
if [ ! -d '${cpath}' ]; then
|
||||
mkdir -m 700 '${cpath}'
|
||||
chown '${data.user}:${data.group}' '${cpath}'
|
||||
fi
|
||||
'';
|
||||
script = ''
|
||||
cd '${cpath}'
|
||||
set +e
|
||||
simp_le ${concatMapStringsSep " " (arg: escapeShellArg (toString arg)) cmdline}
|
||||
EXITCODE=$?
|
||||
set -e
|
||||
echo "$EXITCODE" > /tmp/lastExitCode
|
||||
exit "$EXITCODE"
|
||||
'';
|
||||
postStop = ''
|
||||
if [ -e /tmp/lastExitCode ] && [ "$(cat /tmp/lastExitCode)" = "0" ]; then
|
||||
echo "Executing postRun hook..."
|
||||
${data.postRun}
|
||||
fi
|
||||
'';
|
||||
})
|
||||
);
|
||||
in nameValuePair
|
||||
("acme-${cert}")
|
||||
({
|
||||
description = "ACME cert renewal for ${cert} using simp_le";
|
||||
after = [ "network.target" ];
|
||||
serviceConfig = {
|
||||
Type = "oneshot";
|
||||
SuccessExitStatus = [ "0" "1" ];
|
||||
PermissionsStartOnly = true;
|
||||
User = data.user;
|
||||
Group = data.group;
|
||||
PrivateTmp = true;
|
||||
};
|
||||
path = [ pkgs.simp_le ];
|
||||
preStart = ''
|
||||
mkdir -p '${cfg.directory}'
|
||||
if [ ! -d '${cpath}' ]; then
|
||||
mkdir -m 700 '${cpath}'
|
||||
chown '${data.user}:${data.group}' '${cpath}'
|
||||
fi
|
||||
'';
|
||||
script = ''
|
||||
cd '${cpath}'
|
||||
set +e
|
||||
simp_le ${concatMapStringsSep " " (arg: escapeShellArg (toString arg)) cmdline}
|
||||
EXITCODE=$?
|
||||
set -e
|
||||
echo "$EXITCODE" > /tmp/lastExitCode
|
||||
exit "$EXITCODE"
|
||||
'';
|
||||
postStop = ''
|
||||
if [ -e /tmp/lastExitCode ] && [ "$(cat /tmp/lastExitCode)" = "0" ]; then
|
||||
echo "Executing postRun hook..."
|
||||
${data.postRun}
|
||||
fi
|
||||
'';
|
||||
})
|
||||
);
|
||||
|
||||
systemd.timers = flip mapAttrs' cfg.certs (cert: data: nameValuePair
|
||||
("acme-${cert}")
|
||||
({
|
||||
description = "timer for ACME cert renewal of ${cert}";
|
||||
wantedBy = [ "timers.target" ];
|
||||
timerConfig = {
|
||||
OnCalendar = cfg.renewInterval;
|
||||
Unit = "acme-simp_le-${cert}.service";
|
||||
};
|
||||
})
|
||||
);
|
||||
systemd.timers = flip mapAttrs' cfg.certs (cert: data: nameValuePair
|
||||
("acme-${cert}")
|
||||
({
|
||||
description = "timer for ACME cert renewal of ${cert}";
|
||||
wantedBy = [ "timers.target" ];
|
||||
timerConfig = {
|
||||
OnCalendar = cfg.renewInterval;
|
||||
Unit = "acme-simp_le-${cert}.service";
|
||||
};
|
||||
})
|
||||
);
|
||||
})
|
||||
|
||||
};
|
||||
{ meta.maintainers = with lib.maintainers; [ abbradar fpletz globin ];
|
||||
meta.doc = ./acme.xml;
|
||||
}
|
||||
];
|
||||
|
||||
}
|
||||
|
|
|
|||
69
nixos/modules/security/acme.xml
Normal file
69
nixos/modules/security/acme.xml
Normal file
|
|
@ -0,0 +1,69 @@
|
|||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
version="5.0"
|
||||
xml:id="module-security-acme">
|
||||
|
||||
<title>SSL/TLS Certificates with ACME</title>
|
||||
|
||||
<para>NixOS supports automatic domain validation & certificate
|
||||
retrieval and renewal using the ACME protocol. This is currently only
|
||||
implemented by and for Let's Encrypt. The alternative ACME client
|
||||
<literal>simp_le</literal> is used under the hood.</para>
|
||||
|
||||
<section><title>Prerequisites</title>
|
||||
|
||||
<para>You need to have a running HTTP server for verification. The server must
|
||||
have a webroot defined that can serve
|
||||
<filename>.well-known/acme-challenge</filename>. This directory must be
|
||||
writeable by the user that will run the ACME client.</para>
|
||||
|
||||
<para>For instance, this generic snippet could be used for Nginx:
|
||||
|
||||
<programlisting>
|
||||
http {
|
||||
server {
|
||||
server_name _;
|
||||
listen 80;
|
||||
listen [::]:80;
|
||||
|
||||
location /.well-known/acme-challenge {
|
||||
root /var/www/challenges;
|
||||
}
|
||||
|
||||
location / {
|
||||
return 301 https://$host$request_uri;
|
||||
}
|
||||
}
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
</section>
|
||||
|
||||
<section><title>Configuring</title>
|
||||
|
||||
<para>To enable ACME certificate retrieval & renewal for a certificate for
|
||||
<literal>foo.example.com</literal>, add the following in your
|
||||
<filename>configuration.nix</filename>:
|
||||
|
||||
<programlisting>
|
||||
security.acme.certs."foo.example.com" = {
|
||||
webroot = "/var/www/challenges";
|
||||
email = "foo@example.com";
|
||||
};
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<para>The private key <filename>key.pem</filename> and certificate
|
||||
<filename>fullchain.pem</filename> will be put into
|
||||
<filename>/var/lib/acme/foo.example.com</filename>. The target directory can
|
||||
be configured with the option <literal>security.acme.directory</literal>.
|
||||
</para>
|
||||
|
||||
<para>Refer to <xref linkend="ch-options" /> for all available configuration
|
||||
options for the <literal>security.acme</literal> module.</para>
|
||||
|
||||
</section>
|
||||
|
||||
</chapter>
|
||||
Loading…
Reference in a new issue