commit 8d01b0862d3d52d72539cff65a405c09d864f82f · pyrox.dev/nixpkgs

+31 -3

nixos/modules/security/acme.nix

···

       425
        
       

     

       426
        
         certConfigs = mapAttrs certToConfig cfg.certs;

     

       427
        
       

     

       0
        
       
     

       0
        
       
     

       428
        
         # These options can be specified within

     

       429
        
         # security.acme or security.acme.certs.<name>

     

       430
        
         inheritableOpts =

     
···

       432
        
             validMinDays = mkOption {

     

       433
        
               type = types.int;

     

       434
        
               default = if inheritDefaults then defaults.validMinDays else 30;

     

       0
        
       
     

       435
        
               description = "Minimum remaining validity before renewal in days.";

     

       436
        
             };

     

       437
        
       

     

       438
        
             renewInterval = mkOption {

     

       439
        
               type = types.str;

     

       440
        
               default = if inheritDefaults then defaults.renewInterval else "daily";

     

       0
        
       
     

       441
        
               description = ''

     

       442
        
                 Systemd calendar expression when to check for renewal. See

     

       443
        
                 <citerefentry><refentrytitle>systemd.time</refentrytitle>

     
···

       452
        
             webroot = mkOption {

     

       453
        
               type = types.nullOr types.str;

     

       454
        
               default = if inheritDefaults then defaults.webroot else null;

     

       0
        
       
     

       455
        
               example = "/var/lib/acme/acme-challenge";

     

       456
        
               description = ''

     

       457
        
                 Where the webroot of the HTTP vhost is located.

     
···

       465
        
             server = mkOption {

     

       466
        
               type = types.nullOr types.str;

     

       467
        
               default = if inheritDefaults then defaults.server else null;

     

       0
        
       
     

       468
        
               description = ''

     

       469
        
                 ACME Directory Resource URI. Defaults to Let's Encrypt's

     

       470
        
                 production endpoint,

     
···

       475
        
             email = mkOption {

     

       476
        
               type = types.str;

     

       477
        
               default = if inheritDefaults then defaults.email else null;

     

       0
        
       
     

       478
        
               description = ''

     

       479
        
                 Email address for account creation and correspondence from the CA.

     

       480
        
                 It is recommended to use the same email for all certs to avoid account

     
···

       485
        
             group = mkOption {

     

       486
        
               type = types.str;

     

       487
        
               default = if inheritDefaults then defaults.group else "acme";

     

       0
        
       
     

       488
        
               description = "Group running the ACME client.";

     

       489
        
             };

     

       490
        
       

     

       491
        
             reloadServices = mkOption {

     

       492
        
               type = types.listOf types.str;

     

       493
        
               default = if inheritDefaults then defaults.reloadServices else [];

     

       0
        
       
     

       494
        
               description = ''

     

       495
        
                 The list of systemd services to call <code>systemctl try-reload-or-restart</code>

     

       496
        
                 on.

     
···

       500
        
             postRun = mkOption {

     

       501
        
               type = types.lines;

     

       502
        
               default = if inheritDefaults then defaults.postRun else "";

     

       0
        
       
     

       503
        
               example = "cp full.pem backup.pem";

     

       504
        
               description = ''

     

       505
        
                 Commands to run after new certificates go live. Note that

     
···

       512
        
             keyType = mkOption {

     

       513
        
               type = types.str;

     

       514
        
               default = if inheritDefaults then defaults.keyType else "ec256";

     

       0
        
       
     

       515
        
               description = ''

     

       516
        
                 Key type to use for private keys.

     

       517
        
                 For an up to date list of supported values check the --key-type option

     
···

       522
        
             dnsProvider = mkOption {

     

       523
        
               type = types.nullOr types.str;

     

       524
        
               default = if inheritDefaults then defaults.dnsProvider else null;

     

       0
        
       
     

       525
        
               example = "route53";

     

       526
        
               description = ''

     

       527
        
                 DNS Challenge provider. For a list of supported providers, see the "code"

     
···

       532
        
             dnsResolver = mkOption {

     

       533
        
               type = types.nullOr types.str;

     

       534
        
               default = if inheritDefaults then defaults.dnsResolver else null;

     

       0
        
       
     

       535
        
               example = "1.1.1.1:53";

     

       536
        
               description = ''

     

       537
        
                 Set the resolver to use for performing recursive DNS queries. Supported:

     
···

       543
        
             credentialsFile = mkOption {

     

       544
        
               type = types.path;

     

       545
        
               default = if inheritDefaults then defaults.credentialsFile else null;

     

       0
        
       
     

       546
        
               description = ''

     

       547
        
                 Path to an EnvironmentFile for the cert's service containing any required and

     

       548
        
                 optional environment variables for your selected dnsProvider.

     
···

       555
        
             dnsPropagationCheck = mkOption {

     

       556
        
               type = types.bool;

     

       557
        
               default = if inheritDefaults then defaults.dnsPropagationCheck else true;

     

       0
        
       
     

       558
        
               description = ''

     

       559
        
                 Toggles lego DNS propagation check, which is used alongside DNS-01

     

       560
        
                 challenge to ensure the DNS entries required are available.

     
···

       564
        
             ocspMustStaple = mkOption {

     

       565
        
               type = types.bool;

     

       566
        
               default = if inheritDefaults then defaults.ocspMustStaple else false;

     

       0
        
       
     

       567
        
               description = ''

     

       568
        
                 Turns on the OCSP Must-Staple TLS extension.

     

       569
        
                 Make sure you know what you're doing! See:

     
···

       577
        
             extraLegoFlags = mkOption {

     

       578
        
               type = types.listOf types.str;

     

       579
        
               default = if inheritDefaults then defaults.extraLegoFlags else [];

     

       0
        
       
     

       580
        
               description = ''

     

       581
        
                 Additional global flags to pass to all lego commands.

     

       582
        
               '';

     
···

       585
        
             extraLegoRenewFlags = mkOption {

     

       586
        
               type = types.listOf types.str;

     

       587
        
               default = if inheritDefaults then defaults.extraLegoRenewFlags else [];

     

       0
        
       
     

       588
        
               description = ''

     

       589
        
                 Additional flags to pass to lego renew.

     

       590
        
               '';

     
···

       593
        
             extraLegoRunFlags = mkOption {

     

       594
        
               type = types.listOf types.str;

     

       595
        
               default = if inheritDefaults then defaults.extraLegoRunFlags else [];

     

       0
        
       
     

       596
        
               description = ''

     

       597
        
                 Additional flags to pass to lego run.

     

       598
        
               '';

     

       599
        
             };

     

       600
        
           };

     

       601
        
       

     

       602
       -
         certOpts = { name, ... }: {

     

       603
       -
           options = (inheritableOpts { inherit (cfg) defaults; inheritDefaults = cfg.certs."${name}".inheritDefaults; }) // {

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       604
        
             # user option has been removed

     

       605
        
             user = mkOption {

     

       606
        
               visible = false;

     
···

       696
        
             };

     

       697
        
       

     

       698
        
             defaults = mkOption {

     

       699
       -
               type = types.submodule ({ ... }: { options = inheritableOpts {}; });

     

       700
        
               description = ''

     

       701
        
                 Default values inheritable by all configured certs. You can

     

       702
        
                 use this to define options shared by all your certs. These defaults

···

       425
        
       

     

       426
        
         certConfigs = mapAttrs certToConfig cfg.certs;

     

       427
        
       

     

       428
       +
         mkDefaultText = val: "Inherit from security.acme.defaults, otherwise ${val}" ;

     

       429
       +
       

     

       430
        
         # These options can be specified within

     

       431
        
         # security.acme or security.acme.certs.<name>

     

       432
        
         inheritableOpts =

     
···

       434
        
             validMinDays = mkOption {

     

       435
        
               type = types.int;

     

       436
        
               default = if inheritDefaults then defaults.validMinDays else 30;

     

       437
       +
               defaultText = mkDefaultText "30";

     

       438
        
               description = "Minimum remaining validity before renewal in days.";

     

       439
        
             };

     

       440
        
       

     

       441
        
             renewInterval = mkOption {

     

       442
        
               type = types.str;

     

       443
        
               default = if inheritDefaults then defaults.renewInterval else "daily";

     

       444
       +
               defaultText = mkDefaultText "'daily'";

     

       445
        
               description = ''

     

       446
        
                 Systemd calendar expression when to check for renewal. See

     

       447
        
                 <citerefentry><refentrytitle>systemd.time</refentrytitle>

     
···

       456
        
             webroot = mkOption {

     

       457
        
               type = types.nullOr types.str;

     

       458
        
               default = if inheritDefaults then defaults.webroot else null;

     

       459
       +
               defaultText = mkDefaultText "null";

     

       460
        
               example = "/var/lib/acme/acme-challenge";

     

       461
        
               description = ''

     

       462
        
                 Where the webroot of the HTTP vhost is located.

     
···

       470
        
             server = mkOption {

     

       471
        
               type = types.nullOr types.str;

     

       472
        
               default = if inheritDefaults then defaults.server else null;

     

       473
       +
               defaultText = mkDefaultText "null";

     

       474
        
               description = ''

     

       475
        
                 ACME Directory Resource URI. Defaults to Let's Encrypt's

     

       476
        
                 production endpoint,

     
···

       481
        
             email = mkOption {

     

       482
        
               type = types.str;

     

       483
        
               default = if inheritDefaults then defaults.email else null;

     

       484
       +
               defaultText = mkDefaultText "null";

     

       485
        
               description = ''

     

       486
        
                 Email address for account creation and correspondence from the CA.

     

       487
        
                 It is recommended to use the same email for all certs to avoid account

     
···

       492
        
             group = mkOption {

     

       493
        
               type = types.str;

     

       494
        
               default = if inheritDefaults then defaults.group else "acme";

     

       495
       +
               defaultText = mkDefaultText "'acme'";

     

       496
        
               description = "Group running the ACME client.";

     

       497
        
             };

     

       498
        
       

     

       499
        
             reloadServices = mkOption {

     

       500
        
               type = types.listOf types.str;

     

       501
        
               default = if inheritDefaults then defaults.reloadServices else [];

     

       502
       +
               defaultText = mkDefaultText "[]";

     

       503
        
               description = ''

     

       504
        
                 The list of systemd services to call <code>systemctl try-reload-or-restart</code>

     

       505
        
                 on.

     
···

       509
        
             postRun = mkOption {

     

       510
        
               type = types.lines;

     

       511
        
               default = if inheritDefaults then defaults.postRun else "";

     

       512
       +
               defaultText = mkDefaultText "''";

     

       513
        
               example = "cp full.pem backup.pem";

     

       514
        
               description = ''

     

       515
        
                 Commands to run after new certificates go live. Note that

     
···

       522
        
             keyType = mkOption {

     

       523
        
               type = types.str;

     

       524
        
               default = if inheritDefaults then defaults.keyType else "ec256";

     

       525
       +
               defaultText = mkDefaultText "'ec256'";

     

       526
        
               description = ''

     

       527
        
                 Key type to use for private keys.

     

       528
        
                 For an up to date list of supported values check the --key-type option

     
···

       533
        
             dnsProvider = mkOption {

     

       534
        
               type = types.nullOr types.str;

     

       535
        
               default = if inheritDefaults then defaults.dnsProvider else null;

     

       536
       +
               defaultText = mkDefaultText "null";

     

       537
        
               example = "route53";

     

       538
        
               description = ''

     

       539
        
                 DNS Challenge provider. For a list of supported providers, see the "code"

     
···

       544
        
             dnsResolver = mkOption {

     

       545
        
               type = types.nullOr types.str;

     

       546
        
               default = if inheritDefaults then defaults.dnsResolver else null;

     

       547
       +
               defaultText = mkDefaultText "null";

     

       548
        
               example = "1.1.1.1:53";

     

       549
        
               description = ''

     

       550
        
                 Set the resolver to use for performing recursive DNS queries. Supported:

     
···

       556
        
             credentialsFile = mkOption {

     

       557
        
               type = types.path;

     

       558
        
               default = if inheritDefaults then defaults.credentialsFile else null;

     

       559
       +
               defaultText = mkDefaultText "null";

     

       560
        
               description = ''

     

       561
        
                 Path to an EnvironmentFile for the cert's service containing any required and

     

       562
        
                 optional environment variables for your selected dnsProvider.

     
···

       569
        
             dnsPropagationCheck = mkOption {

     

       570
        
               type = types.bool;

     

       571
        
               default = if inheritDefaults then defaults.dnsPropagationCheck else true;

     

       572
       +
               defaultText = mkDefaultText "true";

     

       573
        
               description = ''

     

       574
        
                 Toggles lego DNS propagation check, which is used alongside DNS-01

     

       575
        
                 challenge to ensure the DNS entries required are available.

     
···

       579
        
             ocspMustStaple = mkOption {

     

       580
        
               type = types.bool;

     

       581
        
               default = if inheritDefaults then defaults.ocspMustStaple else false;

     

       582
       +
               defaultText = mkDefaultText "false";

     

       583
        
               description = ''

     

       584
        
                 Turns on the OCSP Must-Staple TLS extension.

     

       585
        
                 Make sure you know what you're doing! See:

     
···

       593
        
             extraLegoFlags = mkOption {

     

       594
        
               type = types.listOf types.str;

     

       595
        
               default = if inheritDefaults then defaults.extraLegoFlags else [];

     

       596
       +
               defaultText = mkDefaultText "[]";

     

       597
        
               description = ''

     

       598
        
                 Additional global flags to pass to all lego commands.

     

       599
        
               '';

     
···

       602
        
             extraLegoRenewFlags = mkOption {

     

       603
        
               type = types.listOf types.str;

     

       604
        
               default = if inheritDefaults then defaults.extraLegoRenewFlags else [];

     

       605
       +
               defaultText = mkDefaultText "[]";

     

       606
        
               description = ''

     

       607
        
                 Additional flags to pass to lego renew.

     

       608
        
               '';

     
···

       611
        
             extraLegoRunFlags = mkOption {

     

       612
        
               type = types.listOf types.str;

     

       613
        
               default = if inheritDefaults then defaults.extraLegoRunFlags else [];

     

       614
       +
               defaultText = mkDefaultText "[]";

     

       615
        
               description = ''

     

       616
        
                 Additional flags to pass to lego run.

     

       617
        
               '';

     

       618
        
             };

     

       619
        
           };

     

       620
        
       

     

       621
       +
         certOpts = { name, config, ... }: {

     

       622
       +
           options = (inheritableOpts {

     

       623
       +
             inherit (cfg) defaults;

     

       624
       +
             # During doc generation, name = "<name>" and doesn't really

     

       625
       +
             # exist as a cert. As such, handle undfined certs.

     

       626
       +
             inheritDefaults = (lib.attrByPath

     

       627
       +
               [name]

     

       628
       +
               { inheritDefaults = false; }

     

       629
       +
               cfg.certs

     

       630
       +
             ).inheritDefaults;

     

       631
       +
           }) // {

     

       632
        
             # user option has been removed

     

       633
        
             user = mkOption {

     

       634
        
               visible = false;

     
···

       724
        
             };

     

       725
        
       

     

       726
        
             defaults = mkOption {

     

       727
       +
               type = types.submodule { options = inheritableOpts {}; };

     

       728
        
               description = ''

     

       729
        
                 Default values inheritable by all configured certs. You can

     

       730
        
                 use this to define options shared by all your certs. These defaults

+137 -22

nixos/modules/security/acme.xml

···

       7
        
        <para>

     

       8
        
         NixOS supports automatic domain validation &amp; certificate retrieval and

     

       9
        
         renewal using the ACME protocol. Any provider can be used, but by default

     

       10
       -
         NixOS uses Let's Encrypt. The alternative ACME client <literal>lego</literal>

     

       11
       -
         is used under the hood.

     

       0
        
       
     

       12
        
        </para>

     

       13
        
        <para>

     

       14
        
         Automatic cert validation and configuration for Apache and Nginx virtual

     
···

       29
        
         <para>

     

       30
        
          You must also set an email address to be used when creating accounts with

     

       31
        
          Let's Encrypt. You can set this for all certs with

     

       32
       -
          <literal><xref linkend="opt-security.acme.email" /></literal>

     

       33
        
          and/or on a per-cert basis with

     

       34
        
          <literal><xref linkend="opt-security.acme.certs._name_.email" /></literal>.

     

       35
        
          This address is only used for registration and renewal reminders,

     
···

       38
        
       

     

       39
        
         <para>

     

       40
        
          Alternatively, you can use a different ACME server by changing the

     

       41
       -
          <literal><xref linkend="opt-security.acme.server" /></literal> option

     

       42
        
          to a provider of your choosing, or just change the server for one cert with

     

       43
        
          <literal><xref linkend="opt-security.acme.certs._name_.server" /></literal>.

     

       44
        
         </para>

     
···

       60
        
          = true;</literal> in a virtualHost config. We first create self-signed

     

       61
        
          placeholder certificates in place of the real ACME certs. The placeholder

     

       62
        
          certs are overwritten when the ACME certs arrive. For

     

       63
       -
          <literal>foo.example.com</literal> the config would look like.

     

       64
        
         </para>

     

       65
        
       

     

       66
        
       <programlisting>

     

       67
        
       <xref linkend="opt-security.acme.acceptTerms" /> = true;

     

       68
       -
       <xref linkend="opt-security.acme.email" /> = "admin+acme@example.com";

     

       69
        
       services.nginx = {

     

       70
        
         <link linkend="opt-services.nginx.enable">enable</link> = true;

     

       71
        
         <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {

     
···

       114
        
       

     

       115
        
       <programlisting>

     

       116
        
       <xref linkend="opt-security.acme.acceptTerms" /> = true;

     

       117
       -
       <xref linkend="opt-security.acme.email" /> = "admin+acme@example.com";

     

       118
        
       

     

       119
        
       # /var/lib/acme/.challenges must be writable by the ACME user

     

       120
        
       # and readable by the Nginx user. The easiest way to achieve

     
···

       218
        
       

     

       219
        
       # Now we can configure ACME

     

       220
        
       <xref linkend="opt-security.acme.acceptTerms" /> = true;

     

       221
       -
       <xref linkend="opt-security.acme.email" /> = "admin+acme@example.com";

     

       222
        
       <xref linkend="opt-security.acme.certs" />."example.com" = {

     

       223
        
         <link linkend="opt-security.acme.certs._name_.domain">domain</link> = "*.example.com";

     

       224
        
         <link linkend="opt-security.acme.certs._name_.dnsProvider">dnsProvider</link> = "rfc2136";

     
···

       231
        
         <para>

     

       232
        
          The <filename>dnskeys.conf</filename> and <filename>certs.secret</filename>

     

       233
        
          must be kept secure and thus you should not keep their contents in your

     

       234
       -
          Nix config. Instead, generate them one time with these commands:

     

       235
        
         </para>

     

       236
        
       

     

       237
        
       <programlisting>

     

       238
       -
       mkdir -p /var/lib/secrets

     

       239
       -
       tsig-keygen rfc2136key.example.com &gt; /var/lib/secrets/dnskeys.conf

     

       240
       -
       chown named:root /var/lib/secrets/dnskeys.conf

     

       241
       -
       chmod 400 /var/lib/secrets/dnskeys.conf

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       242
        
       

     

       243
       -
       # Copy the secret value from the dnskeys.conf, and put it in

     

       244
       -
       # RFC2136_TSIG_SECRET below

     

       245
        
       

     

       246
       -
       cat &gt; /var/lib/secrets/certs.secret &lt;&lt; EOF

     

       247
       -
       RFC2136_NAMESERVER='127.0.0.1:53'

     

       248
       -
       RFC2136_TSIG_ALGORITHM='hmac-sha256.'

     

       249
       -
       RFC2136_TSIG_KEY='rfc2136key.example.com'

     

       250
       -
       RFC2136_TSIG_SECRET='your secret key'

     

       251
       -
       EOF

     

       252
       -
       chmod 400 /var/lib/secrets/certs.secret

     

       0
        
       
     

       0
        
       
     

       253
        
       </programlisting>

     

       254
        
       

     

       255
        
         <para>

     
···

       258
        
          journalctl -fu acme-example.com.service</literal> and watching its log output.

     

       259
        
         </para>

     

       260
        
        </section>

     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       0
        
       
     

       261
        
        <section xml:id="module-security-acme-regenerate">

     

       262
        
         <title>Regenerating certificates</title>

     

       263

···

       7
        
        <para>

     

       8
        
         NixOS supports automatic domain validation &amp; certificate retrieval and

     

       9
        
         renewal using the ACME protocol. Any provider can be used, but by default

     

       10
       +
         NixOS uses Let's Encrypt. The alternative ACME client

     

       11
       +
         <link xlink:href="https://go-acme.github.io/lego/">lego</link> is used under

     

       12
       +
         the hood.

     

       13
        
        </para>

     

       14
        
        <para>

     

       15
        
         Automatic cert validation and configuration for Apache and Nginx virtual

     
···

       30
        
         <para>

     

       31
        
          You must also set an email address to be used when creating accounts with

     

       32
        
          Let's Encrypt. You can set this for all certs with

     

       33
       +
          <literal><xref linkend="opt-security.acme.defaults.email" /></literal>

     

       34
        
          and/or on a per-cert basis with

     

       35
        
          <literal><xref linkend="opt-security.acme.certs._name_.email" /></literal>.

     

       36
        
          This address is only used for registration and renewal reminders,

     
···

       39
        
       

     

       40
        
         <para>

     

       41
        
          Alternatively, you can use a different ACME server by changing the

     

       42
       +
          <literal><xref linkend="opt-security.acme.defaults.server" /></literal> option

     

       43
        
          to a provider of your choosing, or just change the server for one cert with

     

       44
        
          <literal><xref linkend="opt-security.acme.certs._name_.server" /></literal>.

     

       45
        
         </para>

     
···

       61
        
          = true;</literal> in a virtualHost config. We first create self-signed

     

       62
        
          placeholder certificates in place of the real ACME certs. The placeholder

     

       63
        
          certs are overwritten when the ACME certs arrive. For

     

       64
       +
          <literal>foo.example.com</literal> the config would look like this:

     

       65
        
         </para>

     

       66
        
       

     

       67
        
       <programlisting>

     

       68
        
       <xref linkend="opt-security.acme.acceptTerms" /> = true;

     

       69
       +
       <xref linkend="opt-security.acme.defaults.email" /> = "admin+acme@example.com";

     

       70
        
       services.nginx = {

     

       71
        
         <link linkend="opt-services.nginx.enable">enable</link> = true;

     

       72
        
         <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {

     
···

       115
        
       

     

       116
        
       <programlisting>

     

       117
        
       <xref linkend="opt-security.acme.acceptTerms" /> = true;

     

       118
       +
       <xref linkend="opt-security.acme.defaults.email" /> = "admin+acme@example.com";

     

       119
        
       

     

       120
        
       # /var/lib/acme/.challenges must be writable by the ACME user

     

       121
        
       # and readable by the Nginx user. The easiest way to achieve

     
···

       219
        
       

     

       220
        
       # Now we can configure ACME

     

       221
        
       <xref linkend="opt-security.acme.acceptTerms" /> = true;

     

       222
       +
       <xref linkend="opt-security.acme.defaults.email" /> = "admin+acme@example.com";

     

       223
        
       <xref linkend="opt-security.acme.certs" />."example.com" = {

     

       224
        
         <link linkend="opt-security.acme.certs._name_.domain">domain</link> = "*.example.com";

     

       225
        
         <link linkend="opt-security.acme.certs._name_.dnsProvider">dnsProvider</link> = "rfc2136";

     
···

       232
        
         <para>

     

       233
        
          The <filename>dnskeys.conf</filename> and <filename>certs.secret</filename>

     

       234
        
          must be kept secure and thus you should not keep their contents in your

     

       235
       +
          Nix config. Instead, generate them one time with a systemd service:

     

       236
        
         </para>

     

       237
        
       

     

       238
        
       <programlisting>

     

       239
       +
       systemd.services.dns-rfc2136-conf = {

     

       240
       +
         requiredBy = ["acme-example.com.service", "bind.service"];

     

       241
       +
         before = ["acme-example.com.service", "bind.service"];

     

       242
       +
         unitConfig = {

     

       243
       +
           ConditionPathExists = "!/var/lib/secrets/dnskeys.conf";

     

       244
       +
         };

     

       245
       +
         serviceConfig = {

     

       246
       +
           Type = "oneshot";

     

       247
       +
           UMask = 0077;

     

       248
       +
         };

     

       249
       +
         path = [ pkgs.bind ];

     

       250
       +
         script = ''

     

       251
       +
           mkdir -p /var/lib/secrets

     

       252
       +
           tsig-keygen rfc2136key.example.com &gt; /var/lib/secrets/dnskeys.conf

     

       253
       +
           chown named:root /var/lib/secrets/dnskeys.conf

     

       254
       +
           chmod 400 /var/lib/secrets/dnskeys.conf

     

       255
        
       

     

       256
       +
           # Copy the secret value from the dnskeys.conf, and put it in

     

       257
       +
           # RFC2136_TSIG_SECRET below

     

       258
        
       

     

       259
       +
           cat &gt; /var/lib/secrets/certs.secret &lt;&lt; EOF

     

       260
       +
           RFC2136_NAMESERVER='127.0.0.1:53'

     

       261
       +
           RFC2136_TSIG_ALGORITHM='hmac-sha256.'

     

       262
       +
           RFC2136_TSIG_KEY='rfc2136key.example.com'

     

       263
       +
           RFC2136_TSIG_SECRET='your secret key'

     

       264
       +
           EOF

     

       265
       +
           chmod 400 /var/lib/secrets/certs.secret

     

       266
       +
         '';

     

       267
       +
       };

     

       268
        
       </programlisting>

     

       269
        
       

     

       270
        
         <para>

     
···

       273
        
          journalctl -fu acme-example.com.service</literal> and watching its log output.

     

       274
        
         </para>

     

       275
        
        </section>

     

       276
       +
       

     

       277
       +
        <section xml:id="module-security-acme-config-dns-with-vhosts">

     

       278
       +
         <title>Using DNS validation with web server virtual hosts</title>

     

       279
       +
       

     

       280
       +
         <para>

     

       281
       +
          It is possible to use DNS-01 validation with all certificates,

     

       282
       +
          including those automatically configured via the Nginx/Apache

     

       283
       +
          <literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link></literal>

     

       284
       +
          option. This configuration pattern is fully

     

       285
       +
          supported and part of the module's test suite for Nginx + Apache.

     

       286
       +
         </para>

     

       287
       +
       

     

       288
       +
         <para>

     

       289
       +
          You must follow the guide above on configuring DNS-01 validation

     

       290
       +
          first, however instead of setting the options for one certificate

     

       291
       +
          (e.g. <xref linkend="opt-security.acme.certs._name_.dnsProvider" />)

     

       292
       +
          you will set them as defaults

     

       293
       +
          (e.g. <xref linkend="opt-security.acme.defaults.dnsProvider" />).

     

       294
       +
         </para>

     

       295
       +
       

     

       296
       +
       <programlisting>

     

       297
       +
       # Configure ACME appropriately

     

       298
       +
       <xref linkend="opt-security.acme.acceptTerms" /> = true;

     

       299
       +
       <xref linkend="opt-security.acme.defaults.email" /> = "admin+acme@example.com";

     

       300
       +
       <xref linkend="opt-security.acme.defaults" /> = {

     

       301
       +
         <link linkend="opt-security.acme.defaults.dnsProvider">dnsProvider</link> = "rfc2136";

     

       302
       +
         <link linkend="opt-security.acme.defaults.credentialsFile">credentialsFile</link> = "/var/lib/secrets/certs.secret";

     

       303
       +
         # We don't need to wait for propagation since this is a local DNS server

     

       304
       +
         <link linkend="opt-security.acme.defaults.dnsPropagationCheck">dnsPropagationCheck</link> = false;

     

       305
       +
       };

     

       306
       +
       

     

       307
       +
       # For each virtual host you would like to use DNS-01 validation with,

     

       308
       +
       # set acmeRoot = null

     

       309
       +
       services.nginx = {

     

       310
       +
         <link linkend="opt-services.nginx.enable">enable</link> = true;

     

       311
       +
         <link linkend="opt-services.nginx.virtualHosts">virtualHosts</link> = {

     

       312
       +
           "foo.example.com" = {

     

       313
       +
             <link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;

     

       314
       +
             <link linkend="opt-services.nginx.virtualHosts._name_.acmeRoot">acmeRoot</link> = null;

     

       315
       +
           };

     

       316
       +
         };

     

       317
       +
       }

     

       318
       +
       </programlisting>

     

       319
       +
       

     

       320
       +
         <para>

     

       321
       +
          And that's it! Next time your configuration is rebuilt, or when

     

       322
       +
          you add a new virtualHost, it will be DNS-01 validated.

     

       323
       +
         </para>

     

       324
       +
        </section>

     

       325
       +
       

     

       326
       +
        <section xml:id="module-security-acme-root-owned">

     

       327
       +
         <title>Using ACME with services demanding root owned certificates</title>

     

       328
       +
       

     

       329
       +
         <para>

     

       330
       +
          Some services refuse to start if the configured certificate files

     

       331
       +
          are not owned by root. PostgreSQL and OpenSMTPD are examples of these.

     

       332
       +
          There is no way to change the user the ACME module uses (it will always be

     

       333
       +
          <literal>acme</literal>), however you can use systemd's

     

       334
       +
          <literal>LoadCredential</literal> feature to resolve this elegantly.

     

       335
       +
          Below is an example configuration for OpenSMTPD, but this pattern

     

       336
       +
          can be applied to any service.

     

       337
       +
         </para>

     

       338
       +
       

     

       339
       +
       <programlisting>

     

       340
       +
       # Configure ACME however you like (DNS or HTTP validation), adding

     

       341
       +
       # the following configuration for the relevant certificate.

     

       342
       +
       # Note: You cannot use `systemctl reload` here as that would mean

     

       343
       +
       # the LoadCredential configuration below would be skipped and

     

       344
       +
       # the service would continue to use old certificates.

     

       345
       +
       security.acme.certs."mail.example.com".postRun = ''

     

       346
       +
         systemctl restart opensmtpd

     

       347
       +
       '';

     

       348
       +
       

     

       349
       +
       # Now you must augment OpenSMTPD's systemd service to load

     

       350
       +
       # the certificate files.

     

       351
       +
       <link linkend="opt-systemd.services._name_.requires">systemd.services.opensmtpd.requires</link> = ["acme-finished-mail.example.com.target"];

     

       352
       +
       <link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.opensmtpd.serviceConfig.LoadCredential</link> = let

     

       353
       +
         certDir = config.security.acme.certs."mail.example.com".directory;

     

       354
       +
       in [

     

       355
       +
         "cert.pem:${certDir}/cert.pem"

     

       356
       +
         "key.pem:${certDir}/key.pem"

     

       357
       +
       ];

     

       358
       +
       

     

       359
       +
       # Finally, configure OpenSMTPD to use these certs.

     

       360
       +
       services.opensmtpd = let

     

       361
       +
         credsDir = "/run/credentials/opensmtpd.service";

     

       362
       +
       in {

     

       363
       +
         enable = true;

     

       364
       +
         setSendmail = false;

     

       365
       +
         serverConfiguration = ''

     

       366
       +
           pki mail.example.com cert "${credsDir}/cert.pem"

     

       367
       +
           pki mail.example.com key "${credsDir}/key.pem"

     

       368
       +
           listen on localhost tls pki mail.example.com

     

       369
       +
           action act1 relay host smtp://127.0.0.1:10027

     

       370
       +
           match for local action act1

     

       371
       +
         '';

     

       372
       +
       };

     

       373
       +
       </programlisting>

     

       374
       +
        </section>

     

       375
       +
       

     

       376
        
        <section xml:id="module-security-acme-regenerate">

     

       377
        
         <title>Regenerating certificates</title>

     

       378

+1 -1

nixos/modules/services/networking/prosody.xml

···

       72
        
          a TLS certificate for the three endponits:

     

       73
        
           <programlisting>

     

       74
        
       security.acme = {

     

       75
       -
         <link linkend="opt-security.acme.email">email</link> = "root@example.org";

     

       76
        
         <link linkend="opt-security.acme.acceptTerms">acceptTerms</link> = true;

     

       77
        
         <link linkend="opt-security.acme.certs">certs</link> = {

     

       78
        
           "example.org" = {

···

       72
        
          a TLS certificate for the three endponits:

     

       73
        
           <programlisting>

     

       74
        
       security.acme = {

     

       75
       +
         <link linkend="opt-security.acme.defaults.email">email</link> = "root@example.org";

     

       76
        
         <link linkend="opt-security.acme.acceptTerms">acceptTerms</link> = true;

     

       77
        
         <link linkend="opt-security.acme.certs">certs</link> = {

     

       78
        
           "example.org" = {

+1 -1

nixos/modules/services/web-apps/discourse.xml

···

       25
        
         };

     

       26
        
         <link linkend="opt-services.discourse.secretKeyBaseFile">secretKeyBaseFile</link> = "/path/to/secret_key_base_file";

     

       27
        
       };

     

       28
       -
       <link linkend="opt-security.acme.email">security.acme.email</link> = "me@example.com";

     

       29
        
       <link linkend="opt-security.acme.acceptTerms">security.acme.acceptTerms</link> = true;

     

       30
        
       </programlisting>

     

       31
        
          </para>

···

       25
        
         };

     

       26
        
         <link linkend="opt-services.discourse.secretKeyBaseFile">secretKeyBaseFile</link> = "/path/to/secret_key_base_file";

     

       27
        
       };

     

       28
       +
       <link linkend="opt-security.acme.defaults.email">security.acme.email</link> = "me@example.com";

     

       29
        
       <link linkend="opt-security.acme.acceptTerms">security.acme.acceptTerms</link> = true;

     

       30
        
       </programlisting>

     

       31
        
          </para>

+2 -2

nixos/modules/services/web-apps/jitsi-meet.xml

···

       20
        
         };

     

       21
        
         <link linkend="opt-services.jitsi-videobridge.openFirewall">services.jitsi-videobridge.openFirewall</link> = true;

     

       22
        
         <link linkend="opt-networking.firewall.allowedTCPPorts">networking.firewall.allowedTCPPorts</link> = [ 80 443 ];

     

       23
       -
         <link linkend="opt-security.acme.email">security.acme.email</link> = "me@example.com";

     

       24
        
         <link linkend="opt-security.acme.acceptTerms">security.acme.acceptTerms</link> = true;

     

       25
        
       }</programlisting>

     

       26
        
          </para>

     
···

       46
        
         };

     

       47
        
         <link linkend="opt-services.jitsi-videobridge.openFirewall">services.jitsi-videobridge.openFirewall</link> = true;

     

       48
        
         <link linkend="opt-networking.firewall.allowedTCPPorts">networking.firewall.allowedTCPPorts</link> = [ 80 443 ];

     

       49
       -
         <link linkend="opt-security.acme.email">security.acme.email</link> = "me@example.com";

     

       50
        
         <link linkend="opt-security.acme.acceptTerms">security.acme.acceptTerms</link> = true;

     

       51
        
       }</programlisting>

     

       52
        
          </para>

···

       20
        
         };

     

       21
        
         <link linkend="opt-services.jitsi-videobridge.openFirewall">services.jitsi-videobridge.openFirewall</link> = true;

     

       22
        
         <link linkend="opt-networking.firewall.allowedTCPPorts">networking.firewall.allowedTCPPorts</link> = [ 80 443 ];

     

       23
       +
         <link linkend="opt-security.acme.defaults.email">security.acme.email</link> = "me@example.com";

     

       24
        
         <link linkend="opt-security.acme.acceptTerms">security.acme.acceptTerms</link> = true;

     

       25
        
       }</programlisting>

     

       26
        
          </para>

     
···

       46
        
         };

     

       47
        
         <link linkend="opt-services.jitsi-videobridge.openFirewall">services.jitsi-videobridge.openFirewall</link> = true;

     

       48
        
         <link linkend="opt-networking.firewall.allowedTCPPorts">networking.firewall.allowedTCPPorts</link> = [ 80 443 ];

     

       49
       +
         <link linkend="opt-security.acme.defaults.email">security.acme.email</link> = "me@example.com";

     

       50
        
         <link linkend="opt-security.acme.acceptTerms">security.acme.acceptTerms</link> = true;

     

       51
        
       }</programlisting>

     

       52
        
          </para>