b12f/nixpkgs
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

nixos/cassandra: Convert option docs to markdown

Browse source
This commit is contained in:
Robert Hensing 2022-06-12 11:19:20 +02:00
parent e2c261f2c0
commit fe11145ec9
1 changed files with 64 additions and 63 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

127
nixos/modules/services/databases/cassandra.nix
View file

@ -4,11 +4,12 @@ let
inherit (lib) inherit (lib)
concatStringsSep concatStringsSep
flip flip
literalDocBook literalMD
literalExpression literalExpression
optionalAttrs optionalAttrs
optionals optionals
recursiveUpdate recursiveUpdate
mdDoc
mkEnableOption mkEnableOption
mkIf mkIf
mkOption mkOption
@ -107,7 +108,7 @@ in
clusterName = mkOption { clusterName = mkOption {
type = types.str; type = types.str;
default = "Test Cluster"; default = "Test Cluster";
description = '' description = mdDoc ''
The name of the cluster. The name of the cluster.
This setting prevents nodes in one logical cluster from joining This setting prevents nodes in one logical cluster from joining
another. All nodes in a cluster must have the same value. another. All nodes in a cluster must have the same value.
@ -117,19 +118,19 @@ in
user = mkOption { user = mkOption {
type = types.str; type = types.str;
default = defaultUser; default = defaultUser;
description = "Run Apache Cassandra under this user."; description = mdDoc "Run Apache Cassandra under this user.";
}; };
group = mkOption { group = mkOption {
type = types.str; type = types.str;
default = defaultUser; default = defaultUser;
description = "Run Apache Cassandra under this group."; description = mdDoc "Run Apache Cassandra under this group.";
}; };
homeDir = mkOption { homeDir = mkOption {
type = types.path; type = types.path;
default = "/var/lib/cassandra"; default = "/var/lib/cassandra";
description = '' description = mdDoc ''
Home directory for Apache Cassandra. Home directory for Apache Cassandra.
''; '';
}; };
@ -139,7 +140,7 @@ in
default = pkgs.cassandra; default = pkgs.cassandra;
defaultText = literalExpression "pkgs.cassandra"; defaultText = literalExpression "pkgs.cassandra";
example = literalExpression "pkgs.cassandra_3_11"; example = literalExpression "pkgs.cassandra_3_11";
description = '' description = mdDoc ''
The Apache Cassandra package to use. The Apache Cassandra package to use.
''; '';
}; };
@ -147,8 +148,8 @@ in
jvmOpts = mkOption { jvmOpts = mkOption {
type = types.listOf types.str; type = types.listOf types.str;
default = [ ]; default = [ ];
description = '' description = mdDoc ''
Populate the JVM_OPT environment variable. Populate the `JVM_OPT` environment variable.
''; '';
}; };
@ -156,20 +157,20 @@ in
type = types.nullOr types.str; type = types.nullOr types.str;
default = "127.0.0.1"; default = "127.0.0.1";
example = null; example = null;
description = '' description = mdDoc ''
Address or interface to bind to and tell other Cassandra nodes Address or interface to bind to and tell other Cassandra nodes
to connect to. You _must_ change this if you want multiple to connect to. You _must_ change this if you want multiple
nodes to be able to communicate! nodes to be able to communicate!
Set listenAddress OR listenInterface, not both. Set {option}`listenAddress` OR {option}`listenInterface`, not both.
Leaving it blank leaves it up to Leaving it blank leaves it up to
InetAddress.getLocalHost(). This will always do the Right `InetAddress.getLocalHost()`. This will always do the "Right
Thing _if_ the node is properly configured (hostname, name Thing" _if_ the node is properly configured (hostname, name
resolution, etc), and the Right Thing is to use the address resolution, etc), and the Right Thing is to use the address
associated with the hostname (it might not be). associated with the hostname (it might not be).
Setting listen_address to 0.0.0.0 is always wrong. Setting {option}`listenAddress` to `0.0.0.0` is always wrong.
''; '';
}; };
@ -177,8 +178,8 @@ in
type = types.nullOr types.str; type = types.nullOr types.str;
default = null; default = null;
example = "eth1"; example = "eth1";
description = '' description = mdDoc ''
Set listenAddress OR listenInterface, not both. Interfaces Set `listenAddress` OR `listenInterface`, not both. Interfaces
must correspond to a single address, IP aliasing is not must correspond to a single address, IP aliasing is not
supported. supported.
''; '';
@ -188,18 +189,18 @@ in
type = types.nullOr types.str; type = types.nullOr types.str;
default = "127.0.0.1"; default = "127.0.0.1";
example = null; example = null;
description = '' description = mdDoc ''
The address or interface to bind the native transport server to. The address or interface to bind the native transport server to.
Set rpcAddress OR rpcInterface, not both. Set {option}`rpcAddress` OR {option}`rpcInterface`, not both.
Leaving rpcAddress blank has the same effect as on Leaving {option}`rpcAddress` blank has the same effect as on
listenAddress (i.e. it will be based on the configured hostname {option}`listenAddress` (i.e. it will be based on the configured hostname
of the node). of the node).
Note that unlike listenAddress, you can specify 0.0.0.0, but you Note that unlike {option}`listenAddress`, you can specify `"0.0.0.0"`, but you
must also set extraConfig.broadcast_rpc_address to a value other must also set `extraConfig.broadcast_rpc_address` to a value other
than 0.0.0.0. than `"0.0.0.0"`.
For security reasons, you should not expose this port to the For security reasons, you should not expose this port to the
internet. Firewall it if needed. internet. Firewall it if needed.
@ -210,8 +211,8 @@ in
type = types.nullOr types.str; type = types.nullOr types.str;
default = null; default = null;
example = "eth1"; example = "eth1";
description = '' description = mdDoc ''
Set rpcAddress OR rpcInterface, not both. Interfaces must Set {option}`rpcAddress` OR {option}`rpcInterface`, not both. Interfaces must
correspond to a single address, IP aliasing is not supported. correspond to a single address, IP aliasing is not supported.
''; '';
}; };
@ -233,7 +234,7 @@ in
<logger name="com.thinkaurelius.thrift" level="ERROR"/> <logger name="com.thinkaurelius.thrift" level="ERROR"/>
</configuration> </configuration>
''; '';
description = '' description = mdDoc ''
XML logback configuration for cassandra XML logback configuration for cassandra
''; '';
}; };
@ -241,24 +242,24 @@ in
seedAddresses = mkOption { seedAddresses = mkOption {
type = types.listOf types.str; type = types.listOf types.str;
default = [ "127.0.0.1" ]; default = [ "127.0.0.1" ];
description = '' description = mdDoc ''
The addresses of hosts designated as contact points in the cluster. A The addresses of hosts designated as contact points in the cluster. A
joining node contacts one of the nodes in the seeds list to learn the joining node contacts one of the nodes in the seeds list to learn the
topology of the ring. topology of the ring.
Set to 127.0.0.1 for a single node cluster. Set to `[ "127.0.0.1" ]` for a single node cluster.
''; '';
}; };
allowClients = mkOption { allowClients = mkOption {
type = types.bool; type = types.bool;
default = true; default = true;
description = '' description = mdDoc ''
Enables or disables the native transport server (CQL binary protocol). Enables or disables the native transport server (CQL binary protocol).
This server uses the same address as the <literal>rpcAddress</literal>, This server uses the same address as the {option}`rpcAddress`,
but the port it uses is not <literal>rpc_port</literal> but but the port it uses is not `rpc_port` but
<literal>native_transport_port</literal>. See the official Cassandra `native_transport_port`. See the official Cassandra
docs for more information on these variables and set them using docs for more information on these variables and set them using
<literal>extraConfig</literal>. {option}`extraConfig`.
''; '';
}; };
@ -269,8 +270,8 @@ in
{ {
commitlog_sync_batch_window_in_ms = 3; commitlog_sync_batch_window_in_ms = 3;
}; };
description = '' description = mdDoc ''
Extra options to be merged into cassandra.yaml as nix attribute set. Extra options to be merged into {file}`cassandra.yaml` as nix attribute set.
''; '';
}; };
@ -278,8 +279,8 @@ in
type = types.lines; type = types.lines;
default = ""; default = "";
example = literalExpression ''"CLASSPATH=$CLASSPATH:''${extraJar}"''; example = literalExpression ''"CLASSPATH=$CLASSPATH:''${extraJar}"'';
description = '' description = mdDoc ''
Extra shell lines to be appended onto cassandra-env.sh. Extra shell lines to be appended onto {file}`cassandra-env.sh`.
''; '';
}; };
@ -287,13 +288,13 @@ in
type = types.nullOr types.str; type = types.nullOr types.str;
default = "3w"; default = "3w";
example = null; example = null;
description = '' description = mdDoc ''
Set the interval how often full repairs are run, i.e. Set the interval how often full repairs are run, i.e.
<literal>nodetool repair --full</literal> is executed. See {command}`nodetool repair --full` is executed. See
https://cassandra.apache.org/doc/latest/operating/repair.html <https://cassandra.apache.org/doc/latest/operating/repair.html>
for more information. for more information.
Set to <literal>null</literal> to disable full repairs. Set to `null` to disable full repairs.
''; '';
}; };
@ -301,7 +302,7 @@ in
type = types.listOf types.str; type = types.listOf types.str;
default = [ ]; default = [ ];
example = [ "--partitioner-range" ]; example = [ "--partitioner-range" ];
description = '' description = mdDoc ''
Options passed through to the full repair command. Options passed through to the full repair command.
''; '';
}; };
@ -310,13 +311,13 @@ in
type = types.nullOr types.str; type = types.nullOr types.str;
default = "3d"; default = "3d";
example = null; example = null;
description = '' description = mdDoc ''
Set the interval how often incremental repairs are run, i.e. Set the interval how often incremental repairs are run, i.e.
<literal>nodetool repair</literal> is executed. See {command}`nodetool repair` is executed. See
https://cassandra.apache.org/doc/latest/operating/repair.html <https://cassandra.apache.org/doc/latest/operating/repair.html>
for more information. for more information.
Set to <literal>null</literal> to disable incremental repairs. Set to `null` to disable incremental repairs.
''; '';
}; };
@ -324,7 +325,7 @@ in
type = types.listOf types.str; type = types.listOf types.str;
default = [ ]; default = [ ];
example = [ "--partitioner-range" ]; example = [ "--partitioner-range" ];
description = '' description = mdDoc ''
Options passed through to the incremental repair command. Options passed through to the incremental repair command.
''; '';
}; };
@ -333,15 +334,15 @@ in
type = types.nullOr types.str; type = types.nullOr types.str;
default = null; default = null;
example = "4G"; example = "4G";
description = '' description = mdDoc ''
Must be left blank or set together with heapNewSize. Must be left blank or set together with {option}`heapNewSize`.
If left blank a sensible value for the available amount of RAM and CPU If left blank a sensible value for the available amount of RAM and CPU
cores is calculated. cores is calculated.
Override to set the amount of memory to allocate to the JVM at Override to set the amount of memory to allocate to the JVM at
start-up. For production use you may wish to adjust this for your start-up. For production use you may wish to adjust this for your
environment. MAX_HEAP_SIZE is the total amount of memory dedicated environment. `MAX_HEAP_SIZE` is the total amount of memory dedicated
to the Java heap. HEAP_NEWSIZE refers to the size of the young to the Java heap. `HEAP_NEWSIZE` refers to the size of the young
generation. generation.
The main trade-off for the young generation is that the larger it The main trade-off for the young generation is that the larger it
@ -354,21 +355,21 @@ in
type = types.nullOr types.str; type = types.nullOr types.str;
default = null; default = null;
example = "800M"; example = "800M";
description = '' description = mdDoc ''
Must be left blank or set together with heapNewSize. Must be left blank or set together with {option}`heapNewSize`.
If left blank a sensible value for the available amount of RAM and CPU If left blank a sensible value for the available amount of RAM and CPU
cores is calculated. cores is calculated.
Override to set the amount of memory to allocate to the JVM at Override to set the amount of memory to allocate to the JVM at
start-up. For production use you may wish to adjust this for your start-up. For production use you may wish to adjust this for your
environment. HEAP_NEWSIZE refers to the size of the young environment. `HEAP_NEWSIZE` refers to the size of the young
generation. generation.
The main trade-off for the young generation is that the larger it The main trade-off for the young generation is that the larger it
is, the longer GC pause times will be. The shorter it is, the more is, the longer GC pause times will be. The shorter it is, the more
expensive GC will be (usually). expensive GC will be (usually).
The example HEAP_NEWSIZE assumes a modern 8-core+ machine for decent pause The example `HEAP_NEWSIZE` assumes a modern 8-core+ machine for decent pause
times. If in doubt, and if you do not particularly want to tweak, go with times. If in doubt, and if you do not particularly want to tweak, go with
100 MB per physical CPU core. 100 MB per physical CPU core.
''; '';
@ -378,7 +379,7 @@ in
type = types.nullOr types.int; type = types.nullOr types.int;
default = null; default = null;
example = 4; example = 4;
description = '' description = mdDoc ''
Set this to control the amount of arenas per-thread in glibc. Set this to control the amount of arenas per-thread in glibc.
''; '';
}; };
@ -386,19 +387,19 @@ in
remoteJmx = mkOption { remoteJmx = mkOption {
type = types.bool; type = types.bool;
default = false; default = false;
description = '' description = mdDoc ''
Cassandra ships with JMX accessible *only* from localhost. Cassandra ships with JMX accessible *only* from localhost.
To enable remote JMX connections set to true. To enable remote JMX connections set to true.
Be sure to also enable authentication and/or TLS. Be sure to also enable authentication and/or TLS.
See: https://wiki.apache.org/cassandra/JmxSecurity See: <https://wiki.apache.org/cassandra/JmxSecurity>
''; '';
}; };
jmxPort = mkOption { jmxPort = mkOption {
type = types.int; type = types.int;
default = 7199; default = 7199;
description = '' description = mdDoc ''
Specifies the default port over which Cassandra will be available for Specifies the default port over which Cassandra will be available for
JMX connections. JMX connections.
For security reasons, you should not expose this port to the internet. For security reasons, you should not expose this port to the internet.
@ -408,11 +409,11 @@ in
jmxRoles = mkOption { jmxRoles = mkOption {
default = [ ]; default = [ ];
description = '' description = mdDoc ''
Roles that are allowed to access the JMX (e.g. nodetool) Roles that are allowed to access the JMX (e.g. {command}`nodetool`)
BEWARE: The passwords will be stored world readable in the nix-store. BEWARE: The passwords will be stored world readable in the nix store.
It's recommended to use your own protected file using It's recommended to use your own protected file using
<literal>jmxRolesFile</literal> {option}`jmxRolesFile`
Doesn't work in versions older than 3.11 because they don't like that Doesn't work in versions older than 3.11 because they don't like that
it's world readable. it's world readable.
@ -437,7 +438,7 @@ in
if versionAtLeast cfg.package.version "3.11" if versionAtLeast cfg.package.version "3.11"
then pkgs.writeText "jmx-roles-file" defaultJmxRolesFile then pkgs.writeText "jmx-roles-file" defaultJmxRolesFile
else null; else null;
defaultText = literalDocBook ''generated configuration file if version is at least 3.11, otherwise <literal>null</literal>''; defaultText = literalMD ''generated configuration file if version is at least 3.11, otherwise `null`'';
example = "/var/lib/cassandra/jmx.password"; example = "/var/lib/cassandra/jmx.password";
description = '' description = ''
Specify your own jmx roles file. Specify your own jmx roles file.