this renders the same in the manpage and a little more clearly in the
html manual. in the manpage there continues to be no distinction from
regular text, the html manual gets code-type markup (which was probably
the intention for most of these uses anyway).
we can't embed syntactic annotations of this kind in markdown code
blocks without yet another extension. replaceable is rare enough to make
this not much worth it, so we'll go with «thing» instead. the module
system already uses this format for its placeholder names in attrsOf
paths.
the conversion procedure is simple:
- find all things that look like options, ie calls to either `mkOption`
or `lib.mkOption` that take an attrset. remember the attrset as the
option
- for all options, find a `description` attribute who's value is not a
call to `mdDoc` or `lib.mdDoc`
- textually convert the entire value of the attribute to MD with a few
simple regexes (the set from mdize-module.sh)
- if the change produced a change in the manual output, discard
- if the change kept the manual unchanged, add some text to the
description to make sure we've actually found an option. if the
manual changes this time, keep the converted description
this procedure converts 80% of nixos options to markdown. around 2000
options remain to be inspected, but most of those fail the "does not
change the manual output check": currently the MD conversion process
does not faithfully convert docbook tags like <code> and <package>, so
any option using such tags will not be converted at all.
This allows to set the default bit size for all the Diffie-Hellman
parameters defined in security.dhparams.params and it's particularly
useful so that we can set it to a very low value in tests (so it doesn't
take ages to generate).
Regardless for the use in testing, this also has an impact in production
systems if the owner wants to set all of them to a different size than
2048, they don't need to set it individually for every params that are
set.
I've added a subtest to the "dhparams" NixOS test to ensure this is
working properly.
Signed-off-by: aszlig <aszlig@nix.build>
@Ekleog writes in https://github.com/NixOS/nixpkgs/pull/39526:
> I think a default of 4096 is maybe too much? See certbot/certbot#4973;
> Let's Encrypt supposedly know what they are doing and use a
> pre-generated 2048-bit DH params (and using the same DH params as
> others is quite bad, even compared to lower bit size, if I correctly
> remember the attacks available -- because it increases by as much the
> value of breaking the group).
> Basically I don't have anything personal against 4096, but fear it may
> re-start the arms race: people like having "more security" than their
> distributions, and having NixOS already having more security than is
> actually useful (I personally don't know whether a real-size quantum
> computer will come before or after our being able to break 2048-bit
> keys, let alone 3072-bit ones -- see wikipedia for some numbers).
> So basically, I'd have set it to 3072 in order to both decrease build
> time and avoid having people setting it to 8192 and complaining about
> how slow things are, but that's just my opinion. :)
While he suggests is 3072 I'm using 2048 now, because it's the default
of "openssl dhparam". If users want to have a higher value, they can
still change it.
Signed-off-by: aszlig <aszlig@nix.build>
First of all let's start with a clean up the multiline string
indentation for descriptions, because having two indentation levels
after description is a waste of screen estate.
A quick survey in the form of the following also reveals that the
majority of multiline strings in nixpkgs is starting the two beginning
quotes in the same line:
$ find -name '*.nix' -exec sed -n -e '/=$/ { n; /'\'\''/p }' {} + | wc -l
817
$ find -name '*.nix' -exec grep "= *'' *\$" {} + | wc -l
14818
The next point is to get the type, default and example attributes on top
of the description because that's the way it's rendered in the manual.
Most services have their enable option close to the beginning of the
file, so let's move it to the top.
Also, I found the script attribute for dhparams-init.service a bit hard
to read as it was using string concatenation to split a "for" loop.
Now for the more substantial clean ups rather than just code style:
* Remove the "with lib;" at the beginning of the module, because it
makes it easier to do a quick check with "nix-instantiate --parse".
* Use ConditionPathExists instead of test -e for checking whether we
need to generate the dhparams file. This avoids spawning a shell if
the file exists already and it's probably more common that it will
exist, except for the initial creation of course.
* When cleaning up old dhparams file, use RemainAfterExit so that the
unit won't be triggered again whenever we stop and start a service
depending on it.
* Capitalize systemd unit descriptions to be more in par with most
other unit descriptions (also see 0c5e837b66).
* Use "=" instead of "==" for conditionals using []. It's just a very
small nitpick though and it will only fail for POSIX shells. Bash on
the other side accepts it anyway.
Signed-off-by: aszlig <aszlig@nix.build>
Cc: @Ekleog
This option allows us to turn off stateful generation of Diffie-Hellman
parameters, which in some way is still stateful as the generated DH
params file is non-deterministic.
However what we can avoid with this is to have an increased surface for
failures during system startup, because generation of the parameters is
done during build-time.
Another advantage of this is that we no longer need to take care of
cleaning up the files that are no longer used and in my humble opinion I
would have preferred that #11505 (which puts the dhparams in the Nix
store) would have been merged instead of #22634 (which we have now).
Luckily we can still change that and this change gives the user the
option to put the dhparams into the Nix store.
Beside of the more obvious advantages pointed out here, this also
effects test runtime if more services are starting to use this (for
example see #39507 and #39288), because generating DH params could take
a long time depending on the bit size which adds up to test runtime.
If we generate the DH params in a separate derivation, subsequent test
runs won't need to wait for DH params generation during bootup.
Of course, tests could still mock this by force-disabling the service
and adding a service or activation script that places pre-generated DH
params in /var/lib/dhparams but this would make tests less readable and
the workaround would have to be made for each test affected.
Note that the 'stateful' option is still true by default so that we are
backwards-compatible with existing systems.
Signed-off-by: aszlig <aszlig@nix.build>
Cc: @Ekleog, @abbradar, @fpletz
We're going to implement an option which allows us to turn off stateful
handling of Diffie-Hellman parameter files by putting them into the Nix
store.
However, modules now might need a way to reference these files, so we
add a now path option to every param specified, which carries a
read-only value of the path where to find the corresponding DH params
file.
I've also improved the description of security.dhparams.params a bit so
that it uses <warning/> and <note/>.
The NixOS VM test also reflects this change and checks whether the old
way to specify the bit size still works.
Signed-off-by: aszlig <aszlig@nix.build>
Cc: @Ekleog
