ilyakooo0/nixpkgs
1
0
Fork 0
mirror of https://github.com/ilyakooo0/nixpkgs.git synced 2024-12-26 04:43:09 +03:00
Code Issues Projects Releases Wiki Activity

docs: format

Browse Source
This commit is contained in:
Graham Christensen 2018-09-29 20:51:11 -04:00
parent 9622cd3b38
commit 8413f22bb3
No known key found for this signature in database
GPG Key ID: ACA1C1D120C83D5C
24 changed files with 1784 additions and 1533 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
nixos/doc/manual/configuration/linux-kernel.xml
View File

@ -84,18 +84,17 @@ nixpkgs.config.packageOverrides = pkgs:
allowImportFromDerivation = true;
};
]]></screen>
You can edit the config with this snippet (by default <command>make menuconfig</command> won't work
out of the box on nixos):
<screen><![CDATA[
You can edit the config with this snippet (by default <command>make
menuconfig</command> won't work out of the box on nixos):
<screen><![CDATA[
nix-shell -E 'with import <nixpkgs> {}; kernelToOverride.overrideAttrs (o: {nativeBuildInputs=o.nativeBuildInputs ++ [ pkgconfig ncurses ];})'
]]></screen>
or you can let nixpkgs generate the configuration.
Nixpkgs generates it via answering the interactive kernel utility <command>make config</command>.
The answers depend on parameters passed to <filename>pkgs/os-specific/linux/kernel/generic.nix</filename>
(which you can influence by overriding <literal>extraConfig, autoModules, modDirVersion, preferBuiltin, extraConfig</literal>).
or you can let nixpkgs generate the configuration. Nixpkgs generates it via
answering the interactive kernel utility <command>make config</command>. The
answers depend on parameters passed to
<filename>pkgs/os-specific/linux/kernel/generic.nix</filename> (which you
can influence by overriding <literal>extraConfig, autoModules,
modDirVersion, preferBuiltin, extraConfig</literal>).
<screen><![CDATA[
mptcp93.override ({

7
nixos/doc/manual/development/debugging-nixos-tests.xml
View File

@ -26,11 +26,12 @@ nix-shell -p socat --run "socat STDIO,raw,echo=0,escape=0x11 UNIX:/tmp/nix-build
</programlisting>
<para>
You may need to find the correct path, replacing <literal>/tmp</literal>, <literal>*</literal> or <literal>machine</literal>.
You may need to find the correct path, replacing <literal>/tmp</literal>,
<literal>*</literal> or <literal>machine</literal>.
</para>
<para>
Press "enter" to open up console and login as "root". After you're done, press "ctrl-q" to exit the console.
Press "enter" to open up console and login as "root". After you're done,
press "ctrl-q" to exit the console.
</para>
</section>

47
nixos/doc/manual/installation/installing-behind-a-proxy.xml
View File

@ -5,28 +5,29 @@
xml:id="sec-installing-behind-proxy">
<title>Installing behind a proxy</title>
<para>
<para>
To install NixOS behind a proxy, do the following before running
<literal>nixos-install</literal>.
</para>
<orderedlist numeration="arabic">
</para>
<orderedlist numeration="arabic">
<listitem>
<para>
Update proxy configuration in
<literal>/mnt/etc/nixos/configuration.nix</literal> to keep the
internet accessible after reboot.
</para>
<programlisting>
<para>
Update proxy configuration in
<literal>/mnt/etc/nixos/configuration.nix</literal> to keep the internet
accessible after reboot.
</para>
<programlisting>
networking.proxy.default = &quot;http://user:password@proxy:port/&quot;;
networking.proxy.noProxy = &quot;127.0.0.1,localhost,internal.domain&quot;;
</programlisting>
</listitem>
<listitem>
<para>
Setup the proxy environment variables in the shell where you are
running <literal>nixos-install</literal>.
</para>
<programlisting>
<para>
Setup the proxy environment variables in the shell where you are running
<literal>nixos-install</literal>.
</para>
<programlisting>
# proxy_url=&quot;http://user:password@proxy:port/&quot;
# export http_proxy=&quot;$proxy_url&quot;
# export HTTP_PROXY=&quot;$proxy_url&quot;
@ -34,14 +35,14 @@ networking.proxy.noProxy = &quot;127.0.0.1,localhost,internal.domain&quot;;
# export HTTPS_PROXY=&quot;$proxy_url&quot;
</programlisting>
</listitem>
</orderedlist>
</orderedlist>
<note>
<para>
If you are switching networks with different proxy configurations, use the
<literal>nesting.clone</literal> option in
<literal>configuration.nix</literal> to switch proxies at runtime.
Refer to <xref linkend="ch-options" /> for more information.
</para>
</note>
<note>
<para>
If you are switching networks with different proxy configurations, use the
<literal>nesting.clone</literal> option in
<literal>configuration.nix</literal> to switch proxies at runtime. Refer to
<xref linkend="ch-options" /> for more information.
</para>
</note>
</section>

4
nixos/doc/manual/installation/installing.xml
View File

@ -327,8 +327,8 @@ Retype new UNIX password: ***
<note>
<para>
For unattended installations, it is possible to use
<command>nixos-install --no-root-passwd</command>
in order to disable the password prompt entirely.
<command>nixos-install --no-root-passwd</command> in order to disable the
password prompt entirely.
</para>
</note>
</para>

4
nixos/doc/manual/manual.xml
View File

@ -17,8 +17,8 @@
<para>
If you encounter problems, please report them on the
<literal
xlink:href="https://discourse.nixos.org">Discourse</literal>
or on the <link
xlink:href="https://discourse.nixos.org">Discourse</literal> or
on the <link
xlink:href="irc://irc.freenode.net/#nixos">
<literal>#nixos</literal> channel on Freenode</link>. Bugs should be
reported in

10
nixos/doc/manual/release-notes/rl-1509.xml
View File

@ -435,11 +435,11 @@ system.autoUpgrade.enable = true;
<programlisting>
system.stateVersion = "14.12";
</programlisting>
The new option <option>system.stateVersion</option> ensures that
certain configuration changes that could break existing systems (such as
the <command>sshd</command> host key setting) will maintain compatibility
with the specified NixOS release. NixOps sets the state version of
existing deployments automatically.
The new option <option>system.stateVersion</option> ensures that certain
configuration changes that could break existing systems (such as the
<command>sshd</command> host key setting) will maintain compatibility with
the specified NixOS release. NixOps sets the state version of existing
deployments automatically.
</para>
</listitem>
<listitem>

266
nixos/doc/manual/release-notes/rl-1809.xml
View File

@ -19,13 +19,13 @@
<itemizedlist>
<listitem>
<para>
Support for wrapping binaries using <literal>firejail</literal> has been
added through <varname>programs.firejail.wrappedBinaries</varname>.
</para>
<para>
For example
</para>
<para>
Support for wrapping binaries using <literal>firejail</literal> has been
added through <varname>programs.firejail.wrappedBinaries</varname>.
</para>
<para>
For example
</para>
<programlisting>
programs.firejail = {
enable = true;
@ -35,9 +35,10 @@ programs.firejail = {
};
};
</programlisting>
<para>
This will place <literal>firefox</literal> and <literal>mpv</literal> binaries in the global path wrapped by firejail.
</para>
<para>
This will place <literal>firefox</literal> and <literal>mpv</literal>
binaries in the global path wrapped by firejail.
</para>
</listitem>
<listitem>
<para>
@ -75,16 +76,20 @@ $ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
<itemizedlist>
<listitem>
<para>
The <varname>services.cassandra</varname> module has been reworked and
was rewritten from scratch. The service has succeeding tests for
the versions 2.1, 2.2, 3.0 and 3.11 of <link
xlink:href="https://cassandra.apache.org/">Apache Cassandra</link>.
The <varname>services.cassandra</varname> module has been reworked and was
rewritten from scratch. The service has succeeding tests for the versions
2.1, 2.2, 3.0 and 3.11 of
<link
xlink:href="https://cassandra.apache.org/">Apache
Cassandra</link>.
</para>
</listitem>
<listitem>
<para>
There is a new <varname>services.foundationdb</varname> module for deploying
<link xlink:href="https://www.foundationdb.org">FoundationDB</link> clusters.
There is a new <varname>services.foundationdb</varname> module for
deploying
<link xlink:href="https://www.foundationdb.org">FoundationDB</link>
clusters.
</para>
</listitem>
<listitem>
@ -97,24 +102,26 @@ $ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
</listitem>
<listitem>
<para>
<varname>services.strongswan-swanctl</varname>
is a modern replacement for <varname>services.strongswan</varname>.
You can use either one of them to setup IPsec VPNs but not both at the same time.
<varname>services.strongswan-swanctl</varname> is a modern replacement for
<varname>services.strongswan</varname>. You can use either one of them to
setup IPsec VPNs but not both at the same time.
</para>
<para>
<varname>services.strongswan-swanctl</varname> uses the
<link xlink:href="https://wiki.strongswan.org/projects/strongswan/wiki/swanctl">swanctl</link>
command which uses the modern
<link xlink:href="https://github.com/strongswan/strongswan/blob/master/src/libcharon/plugins/vici/README.md">vici</link>
<emphasis>Versatile IKE Configuration Interface</emphasis>.
The deprecated <literal>ipsec</literal> command used in <varname>services.strongswan</varname> is using the legacy
<link xlink:href="https://github.com/strongswan/strongswan/blob/master/README_LEGACY.md">stroke configuration interface</link>.
<varname>services.strongswan-swanctl</varname> uses the
<link xlink:href="https://wiki.strongswan.org/projects/strongswan/wiki/swanctl">swanctl</link>
command which uses the modern
<link xlink:href="https://github.com/strongswan/strongswan/blob/master/src/libcharon/plugins/vici/README.md">vici</link>
<emphasis>Versatile IKE Configuration Interface</emphasis>. The deprecated
<literal>ipsec</literal> command used in
<varname>services.strongswan</varname> is using the legacy
<link xlink:href="https://github.com/strongswan/strongswan/blob/master/README_LEGACY.md">stroke
configuration interface</link>.
</para>
</listitem>
<listitem>
<para>
The new <varname>services.elasticsearch-curator</varname> service
periodically curates or manages, your Elasticsearch indices and snapshots.
The new <varname>services.elasticsearch-curator</varname> service
periodically curates or manages, your Elasticsearch indices and snapshots.
</para>
</listitem>
</itemizedlist>
@ -135,8 +142,8 @@ $ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
<itemizedlist>
<listitem>
<para>
The deprecated <varname>services.cassandra</varname> module has
seen a complete rewrite. (See above.)
The deprecated <varname>services.cassandra</varname> module has seen a
complete rewrite. (See above.)
</para>
</listitem>
<listitem>
@ -186,41 +193,44 @@ $ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
</listitem>
<listitem>
<para>
<varname>services.munge</varname> now runs as user (and group) <literal>munge</literal> instead of root.
Make sure the key file is accessible to the daemon.
<varname>services.munge</varname> now runs as user (and group)
<literal>munge</literal> instead of root. Make sure the key file is
accessible to the daemon.
</para>
</listitem>
<listitem>
<para>
<varname>dockerTools.buildImage</varname> now uses <literal>null</literal> as default value for <varname>tag</varname>,
which indicates that the nix output hash will be used as tag.
<varname>dockerTools.buildImage</varname> now uses <literal>null</literal>
as default value for <varname>tag</varname>, which indicates that the nix
output hash will be used as tag.
</para>
</listitem>
<listitem>
<para>
The ELK stack: <varname>elasticsearch</varname>, <varname>logstash</varname> and <varname>kibana</varname>
has been upgraded from 2.* to 6.3.*.
The 2.* versions have been <link xlink:href="https://www.elastic.co/support/eol">unsupported since last year</link>
so they have been removed. You can still use the 5.* versions under the names
<varname>elasticsearch5</varname>, <varname>logstash5</varname> and
<varname>kibana5</varname>.
The ELK stack: <varname>elasticsearch</varname>,
<varname>logstash</varname> and <varname>kibana</varname> has been
upgraded from 2.* to 6.3.*. The 2.* versions have been
<link xlink:href="https://www.elastic.co/support/eol">unsupported since
last year</link> so they have been removed. You can still use the 5.*
versions under the names <varname>elasticsearch5</varname>,
<varname>logstash5</varname> and <varname>kibana5</varname>.
</para>
<para>
The elastic beats:
<varname>filebeat</varname>, <varname>heartbeat</varname>,
<varname>metricbeat</varname> and <varname>packetbeat</varname>
have had the same treatment: they now target 6.3.* as well.
The 5.* versions are available under the names:
The elastic beats: <varname>filebeat</varname>,
<varname>heartbeat</varname>, <varname>metricbeat</varname> and
<varname>packetbeat</varname> have had the same treatment: they now target
6.3.* as well. The 5.* versions are available under the names:
<varname>filebeat5</varname>, <varname>heartbeat5</varname>,
<varname>metricbeat5</varname> and <varname>packetbeat5</varname>
</para>
<para>
The ELK-6.3 stack now comes with
<link xlink:href="https://www.elastic.co/products/x-pack/open">X-Pack by default</link>.
Since X-Pack is licensed under the
<link xlink:href="https://github.com/elastic/elasticsearch/blob/master/licenses/ELASTIC-LICENSE.txt">Elastic License</link>
the ELK packages now have an unfree license. To use them you need to specify
<literal>allowUnfree = true;</literal> in your nixpkgs configuration.
<link xlink:href="https://www.elastic.co/products/x-pack/open">X-Pack by
default</link>. Since X-Pack is licensed under the
<link xlink:href="https://github.com/elastic/elasticsearch/blob/master/licenses/ELASTIC-LICENSE.txt">Elastic
License</link> the ELK packages now have an unfree license. To use them
you need to specify <literal>allowUnfree = true;</literal> in your nixpkgs
configuration.
</para>
<para>
Fortunately there is also a free variant of the ELK stack without X-Pack.
@ -231,20 +241,23 @@ $ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
</listitem>
<listitem>
<para>
Options
<literal>boot.initrd.luks.devices.<replaceable>name</replaceable>.yubikey.ramfsMountPoint</literal>
<literal>boot.initrd.luks.devices.<replaceable>name</replaceable>.yubikey.storage.mountPoint</literal>
were removed. <literal>luksroot.nix</literal> module never supported more than one YubiKey at
a time anyway, hence those options never had any effect. You should be able to remove them
from your config without any issues.
Options
<literal>boot.initrd.luks.devices.<replaceable>name</replaceable>.yubikey.ramfsMountPoint</literal>
<literal>boot.initrd.luks.devices.<replaceable>name</replaceable>.yubikey.storage.mountPoint</literal>
were removed. <literal>luksroot.nix</literal> module never supported more
than one YubiKey at a time anyway, hence those options never had any
effect. You should be able to remove them from your config without any
issues.
</para>
</listitem>
<listitem>
<para>
<literal>stdenv.system</literal> and <literal>system</literal> in nixpkgs now refer to the host platform instead of the build platform.
For native builds this is not change, let alone a breaking one.
For cross builds, it is a breaking change, and <literal>stdenv.buildPlatform.system</literal> can be used instead for the old behavior.
They should be using that anyways for clarity.
<literal>stdenv.system</literal> and <literal>system</literal> in nixpkgs
now refer to the host platform instead of the build platform. For native
builds this is not change, let alone a breaking one. For cross builds, it
is a breaking change, and <literal>stdenv.buildPlatform.system</literal>
can be used instead for the old behavior. They should be using that
anyways for clarity.
</para>
</listitem>
</itemizedlist>
@ -298,26 +311,33 @@ $ nix-instantiate -E '(import &lt;nixpkgsunstable&gt; {}).gitFull'
</listitem>
<listitem>
<para>
The <literal>pkgs</literal> argument to NixOS modules can now be set directly using <literal>nixpkgs.pkgs</literal>. Previously, only the <literal>system</literal>, <literal>config</literal> and <literal>overlays</literal> arguments could be used to influence <literal>pkgs</literal>.
The <literal>pkgs</literal> argument to NixOS modules can now be set
directly using <literal>nixpkgs.pkgs</literal>. Previously, only the
<literal>system</literal>, <literal>config</literal> and
<literal>overlays</literal> arguments could be used to influence
<literal>pkgs</literal>.
</para>
</listitem>
<listitem>
<para>
A NixOS system can now be constructed more easily based on a preexisting invocation of Nixpkgs. For example:
<programlisting>
A NixOS system can now be constructed more easily based on a preexisting
invocation of Nixpkgs. For example:
<programlisting>
inherit (pkgs.nixos {
boot.loader.grub.enable = false;
fileSystems."/".device = "/dev/xvda1";
}) toplevel kernel initialRamdisk manual;
</programlisting>
This benefits evaluation performance, lets you write Nixpkgs packages that depend on NixOS images and is consistent with a deployment architecture that would be centered around Nixpkgs overlays.
This benefits evaluation performance, lets you write Nixpkgs packages that
depend on NixOS images and is consistent with a deployment architecture
that would be centered around Nixpkgs overlays.
</para>
</listitem>
<listitem>
<para>
<literal>lib.traceValIfNot</literal> has been deprecated. Use
<literal>if/then/else</literal> and <literal>lib.traceValSeq</literal> instead.
<literal>lib.traceValIfNot</literal> has been deprecated. Use
<literal>if/then/else</literal> and <literal>lib.traceValSeq</literal>
instead.
</para>
</listitem>
<listitem>
@ -336,9 +356,9 @@ inherit (pkgs.nixos {
</listitem>
<listitem>
<para>
<literal>lib.recursiveUpdateUntil</literal> was not acting according to its
specification. It has been fixed to act according to the docstring, and a
test has been added.
<literal>lib.recursiveUpdateUntil</literal> was not acting according to
its specification. It has been fixed to act according to the docstring,
and a test has been added.
</para>
</listitem>
<listitem>
@ -408,11 +428,11 @@ inherit (pkgs.nixos {
</para>
</listitem>
<listitem>
<para>
The Kubernetes package has been bumped to major version 1.11.
Please consult the
<link xlink:href="https://github.com/kubernetes/kubernetes/blob/release-1.11/CHANGELOG-1.11.md">release notes</link>
for details on new features and api changes.
<para>
The Kubernetes package has been bumped to major version 1.11. Please
consult the
<link xlink:href="https://github.com/kubernetes/kubernetes/blob/release-1.11/CHANGELOG-1.11.md">release
notes</link> for details on new features and api changes.
</para>
</listitem>
<listitem>
@ -432,8 +452,8 @@ inherit (pkgs.nixos {
</listitem>
<listitem>
<para>
The option <varname>services.kubernetes.apiserver.address</varname>
was renamed to <varname>services.kubernetes.apiserver.bindAddress</varname>.
The option <varname>services.kubernetes.apiserver.address</varname> was
renamed to <varname>services.kubernetes.apiserver.bindAddress</varname>.
Note that the default value has changed from 127.0.0.1 to 0.0.0.0.
</para>
</listitem>
@ -445,76 +465,86 @@ inherit (pkgs.nixos {
</listitem>
<listitem>
<para>
The option <varname>services.kubernetes.addons.dashboard.enableRBAC</varname>
was renamed to <varname>services.kubernetes.addons.dashboard.rbac.enable</varname>.
The option
<varname>services.kubernetes.addons.dashboard.enableRBAC</varname> was
renamed to
<varname>services.kubernetes.addons.dashboard.rbac.enable</varname>.
</para>
</listitem>
<listitem>
<para>
The Kubernetes Dashboard now has only minimal RBAC permissions by default.
If dashboard cluster-admin rights are desired,
set <varname>services.kubernetes.addons.dashboard.rbac.clusterAdmin</varname> to true.
On existing clusters, in order for the revocation of privileges to take effect,
the current ClusterRoleBinding for kubernetes-dashboard must be manually removed:
<literal>kubectl delete clusterrolebinding kubernetes-dashboard</literal>
If dashboard cluster-admin rights are desired, set
<varname>services.kubernetes.addons.dashboard.rbac.clusterAdmin</varname>
to true. On existing clusters, in order for the revocation of privileges
to take effect, the current ClusterRoleBinding for kubernetes-dashboard
must be manually removed: <literal>kubectl delete clusterrolebinding
kubernetes-dashboard</literal>
</para>
</listitem>
<listitem>
<para>
The <varname>programs.screen</varname> module provides allows to configure
<literal>/etc/screenrc</literal>, however the module behaved fairly counterintuitive as
the config exists, but the package wasn't available. Since 18.09 <literal>pkgs.screen</literal>
will be added to <literal>environment.systemPackages</literal>.
<literal>/etc/screenrc</literal>, however the module behaved fairly
counterintuitive as the config exists, but the package wasn't available.
Since 18.09 <literal>pkgs.screen</literal> will be added to
<literal>environment.systemPackages</literal>.
</para>
</listitem>
<listitem>
<para>
The module <option>services.networking.hostapd</option> now uses WPA2 by default.
The module <option>services.networking.hostapd</option> now uses WPA2 by
default.
</para>
</listitem>
<listitem>
<para>
<varname>s6Dns</varname>, <varname>s6Networking</varname>,
<varname>s6LinuxUtils</varname> and <varname>s6PortableUtils</varname>
renamed to
<varname>s6-dns</varname>, <varname>s6-networking</varname>,
<varname>s6-linux-utils</varname> and <varname>s6-portable-utils</varname> respectively.
<varname>s6Dns</varname>, <varname>s6Networking</varname>,
<varname>s6LinuxUtils</varname> and <varname>s6PortableUtils</varname>
renamed to <varname>s6-dns</varname>, <varname>s6-networking</varname>,
<varname>s6-linux-utils</varname> and <varname>s6-portable-utils</varname>
respectively.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
The module option <option>nix.useSandbox</option> is now defaulted to <literal>true</literal>.
The module option <option>nix.useSandbox</option> is now defaulted to
<literal>true</literal>.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
The config activation script of <literal>nixos-rebuild</literal> now
<link xlink:href="https://www.freedesktop.org/software/systemd/man/systemctl.html#Manager%20Lifecycle%20Commands">reloads</link>
all user units for each authenticated user.
The config activation script of <literal>nixos-rebuild</literal> now
<link xlink:href="https://www.freedesktop.org/software/systemd/man/systemctl.html#Manager%20Lifecycle%20Commands">reloads</link>
all user units for each authenticated user.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
The default display manager is now LightDM.
To use SLiM set <literal>services.xserver.displayManager.slim.enable</literal>
to <literal>true</literal>.
The default display manager is now LightDM. To use SLiM set
<literal>services.xserver.displayManager.slim.enable</literal> to
<literal>true</literal>.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
NixOS option descriptions are now automatically broken up into individual
paragraphs if the text contains two consecutive newlines, so it's no
longer necessary to use <code>&lt;/para&gt;&lt;para&gt;</code> to start
a new paragraph.
NixOS option descriptions are now automatically broken up into individual
paragraphs if the text contains two consecutive newlines, so it's no
longer necessary to use <code>&lt;/para&gt;&lt;para&gt;</code> to start a
new paragraph.
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
Top-level <literal>buildPlatform</literal>, <literal>hostPlatform</literal>, and <literal>targetPlatform</literal> in Nixpkgs are deprecated.
Please use their equivalents in <literal>stdenv</literal> instead:
<literal>stdenv.buildPlatform</literal>, <literal>stdenv.hostPlatform</literal>, and <literal>stdenv.targetPlatform</literal>.
Top-level <literal>buildPlatform</literal>,
<literal>hostPlatform</literal>, and <literal>targetPlatform</literal> in
Nixpkgs are deprecated. Please use their equivalents in
<literal>stdenv</literal> instead:
<literal>stdenv.buildPlatform</literal>,
<literal>stdenv.hostPlatform</literal>, and
<literal>stdenv.targetPlatform</literal>.
</para>
</listitem>
</listitem>
</itemizedlist>
</section>
</section>

7
nixos/doc/manual/release-notes/rl-1903.xml
View File

@ -100,9 +100,10 @@
</itemizedlist>
</listitem>
<listitem>
<para>
Package <varname>rabbitmq_server</varname> is renamed to <varname>rabbitmq-server</varname>.
</para>
<para>
Package <varname>rabbitmq_server</varname> is renamed to
<varname>rabbitmq-server</varname>.
</para>
</listitem>
</itemizedlist>
</section>

295
nixos/modules/i18n/input-method/default.xml
View File

@ -3,32 +3,50 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-services-input-methods">
<title>Input Methods</title>
<para>
Input methods are an operating system component that allows any data, such as
keyboard strokes or mouse movements, to be received as input. In this way
users can enter characters and symbols not found on their input devices.
Using an input method is obligatory for any language that has more graphemes
than there are keys on the keyboard.
</para>
<para>
The following input methods are available in NixOS:
</para>
<itemizedlist>
<listitem>
<para>
IBus: The intelligent input bus.
</para>
</listitem>
<listitem>
<para>
Fcitx: A customizable lightweight input method.
</para>
</listitem>
<listitem>
<para>
Nabi: A Korean input method based on XIM.
</para>
</listitem>
<listitem>
<para>
Uim: The universal input method, is a library with a XIM bridge.
</para>
</listitem>
</itemizedlist>
<section xml:id="module-services-input-methods-ibus">
<title>IBus</title>
<title>Input Methods</title>
<para>
IBus is an Intelligent Input Bus. It provides full featured and user
friendly input method user interface.
</para>
<para>Input methods are an operating system component that allows any data, such
as keyboard strokes or mouse movements, to be received as input. In this way
users can enter characters and symbols not found on their input devices. Using
an input method is obligatory for any language that has more graphemes than
there are keys on the keyboard.</para>
<para>The following input methods are available in NixOS:</para>
<itemizedlist>
<listitem><para>IBus: The intelligent input bus.</para></listitem>
<listitem><para>Fcitx: A customizable lightweight input
method.</para></listitem>
<listitem><para>Nabi: A Korean input method based on XIM.</para></listitem>
<listitem><para>Uim: The universal input method, is a library with a XIM
bridge.</para></listitem>
</itemizedlist>
<section xml:id="module-services-input-methods-ibus"><title>IBus</title>
<para>IBus is an Intelligent Input Bus. It provides full featured and user
friendly input method user interface.</para>
<para>The following snippet can be used to configure IBus:</para>
<para>
The following snippet can be used to configure IBus:
</para>
<programlisting>
i18n.inputMethod = {
@ -37,57 +55,89 @@ i18n.inputMethod = {
};
</programlisting>
<para><literal>i18n.inputMethod.ibus.engines</literal> is optional and can be
used to add extra IBus engines.</para>
<para>
<literal>i18n.inputMethod.ibus.engines</literal> is optional and can be used
to add extra IBus engines.
</para>
<para>Available extra IBus engines are:</para>
<para>
Available extra IBus engines are:
</para>
<itemizedlist>
<listitem><para>Anthy (<literal>ibus-engines.anthy</literal>): Anthy is a
system for Japanese input method. It converts Hiragana text to Kana Kanji
mixed text.</para></listitem>
<listitem><para>Hangul (<literal>ibus-engines.hangul</literal>): Korean input
method.</para></listitem>
<listitem><para>m17n (<literal>ibus-engines.m17n</literal>): m17n is an input
method that uses input methods and corresponding icons in the m17n
database.</para></listitem>
<listitem><para>mozc (<literal>ibus-engines.mozc</literal>): A Japanese input
method from Google.</para></listitem>
<listitem><para>Table (<literal>ibus-engines.table</literal>): An input method
that load tables of input methods.</para></listitem>
<listitem><para>table-others (<literal>ibus-engines.table-others</literal>):
Various table-based input methods. To use this, and any other table-based
input methods, it must appear in the list of engines along with
<literal>table</literal>. For example:
<itemizedlist>
<listitem>
<para>
Anthy (<literal>ibus-engines.anthy</literal>): Anthy is a system for
Japanese input method. It converts Hiragana text to Kana Kanji mixed text.
</para>
</listitem>
<listitem>
<para>
Hangul (<literal>ibus-engines.hangul</literal>): Korean input method.
</para>
</listitem>
<listitem>
<para>
m17n (<literal>ibus-engines.m17n</literal>): m17n is an input method that
uses input methods and corresponding icons in the m17n database.
</para>
</listitem>
<listitem>
<para>
mozc (<literal>ibus-engines.mozc</literal>): A Japanese input method from
Google.
</para>
</listitem>
<listitem>
<para>
Table (<literal>ibus-engines.table</literal>): An input method that load
tables of input methods.
</para>
</listitem>
<listitem>
<para>
table-others (<literal>ibus-engines.table-others</literal>): Various
table-based input methods. To use this, and any other table-based input
methods, it must appear in the list of engines along with
<literal>table</literal>. For example:
<programlisting>
ibus.engines = with pkgs.ibus-engines; [ table table-others ];
</programlisting>
</para></listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
<para>To use any input method, the package must be added in the configuration,
as shown above, and also (after running <literal>nixos-rebuild</literal>) the
input method must be added from IBus' preference dialog.</para>
<para>
To use any input method, the package must be added in the configuration, as
shown above, and also (after running <literal>nixos-rebuild</literal>) the
input method must be added from IBus' preference dialog.
</para>
<simplesect xml:id="module-services-input-methods-troubleshooting">
<title>Troubleshooting</title>
<para>If IBus works in some applications but not others, a likely cause of
this is that IBus is depending on a different version of
<literal>glib</literal> to what the applications are depending on. This can
be checked by running <literal>nix-store -q --requisites &lt;path&gt; | grep
glib</literal>, where <literal>&lt;path&gt;</literal> is the path of either
IBus or an application in the Nix store. The <literal>glib</literal>
packages must match exactly. If they do not, uninstalling and reinstalling
the application is a likely fix.</para>
</simplesect>
</section>
<simplesect xml:id="module-services-input-methods-troubleshooting">
<title>Troubleshooting</title>
<para>
If IBus works in some applications but not others, a likely cause of this
is that IBus is depending on a different version of <literal>glib</literal>
to what the applications are depending on. This can be checked by running
<literal>nix-store -q --requisites &lt;path&gt; | grep glib</literal>,
where <literal>&lt;path&gt;</literal> is the path of either IBus or an
application in the Nix store. The <literal>glib</literal> packages must
match exactly. If they do not, uninstalling and reinstalling the
application is a likely fix.
</para>
</simplesect>
</section>
<section xml:id="module-services-input-methods-fcitx">
<title>Fcitx</title>
<section xml:id="module-services-input-methods-fcitx"><title>Fcitx</title>
<para>
Fcitx is an input method framework with extension support. It has three
built-in Input Method Engine, Pinyin, QuWei and Table-based input methods.
</para>
<para>Fcitx is an input method framework with extension support. It has three
built-in Input Method Engine, Pinyin, QuWei and Table-based input
methods.</para>
<para>The following snippet can be used to configure Fcitx:</para>
<para>
The following snippet can be used to configure Fcitx:
</para>
<programlisting>
i18n.inputMethod = {
@ -96,51 +146,89 @@ i18n.inputMethod = {
};
</programlisting>
<para><literal>i18n.inputMethod.fcitx.engines</literal> is optional and can be
used to add extra Fcitx engines.</para>
<para>
<literal>i18n.inputMethod.fcitx.engines</literal> is optional and can be
used to add extra Fcitx engines.
</para>
<para>Available extra Fcitx engines are:</para>
<para>
Available extra Fcitx engines are:
</para>
<itemizedlist>
<listitem><para>Anthy (<literal>fcitx-engines.anthy</literal>): Anthy is a
system for Japanese input method. It converts Hiragana text to Kana Kanji
mixed text.</para></listitem>
<listitem><para>Chewing (<literal>fcitx-engines.chewing</literal>): Chewing is
an intelligent Zhuyin input method. It is one of the most popular input
methods among Traditional Chinese Unix users.</para></listitem>
<listitem><para>Hangul (<literal>fcitx-engines.hangul</literal>): Korean input
method.</para></listitem>
<listitem><para>Unikey (<literal>fcitx-engines.unikey</literal>): Vietnamese input
method.</para></listitem>
<listitem><para>m17n (<literal>fcitx-engines.m17n</literal>): m17n is an input
method that uses input methods and corresponding icons in the m17n
database.</para></listitem>
<listitem><para>mozc (<literal>fcitx-engines.mozc</literal>): A Japanese input
method from Google.</para></listitem>
<listitem><para>table-others (<literal>fcitx-engines.table-others</literal>):
Various table-based input methods.</para></listitem>
</itemizedlist>
</section>
<itemizedlist>
<listitem>
<para>
Anthy (<literal>fcitx-engines.anthy</literal>): Anthy is a system for
Japanese input method. It converts Hiragana text to Kana Kanji mixed text.
</para>
</listitem>
<listitem>
<para>
Chewing (<literal>fcitx-engines.chewing</literal>): Chewing is an
intelligent Zhuyin input method. It is one of the most popular input
methods among Traditional Chinese Unix users.
</para>
</listitem>
<listitem>
<para>
Hangul (<literal>fcitx-engines.hangul</literal>): Korean input method.
</para>
</listitem>
<listitem>
<para>
Unikey (<literal>fcitx-engines.unikey</literal>): Vietnamese input method.
</para>
</listitem>
<listitem>
<para>
m17n (<literal>fcitx-engines.m17n</literal>): m17n is an input method that
uses input methods and corresponding icons in the m17n database.
</para>
</listitem>
<listitem>
<para>
mozc (<literal>fcitx-engines.mozc</literal>): A Japanese input method from
Google.
</para>
</listitem>
<listitem>
<para>
table-others (<literal>fcitx-engines.table-others</literal>): Various
table-based input methods.
</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="module-services-input-methods-nabi">
<title>Nabi</title>
<section xml:id="module-services-input-methods-nabi"><title>Nabi</title>
<para>
Nabi is an easy to use Korean X input method. It allows you to enter
phonetic Korean characters (hangul) and pictographic Korean characters
(hanja).
</para>
<para>Nabi is an easy to use Korean X input method. It allows you to enter
phonetic Korean characters (hangul) and pictographic Korean characters
(hanja).</para>
<para>The following snippet can be used to configure Nabi:</para>
<para>
The following snippet can be used to configure Nabi:
</para>
<programlisting>
i18n.inputMethod = {
<link linkend="opt-i18n.inputMethod.enabled">enabled</link> = "nabi";
};
</programlisting>
</section>
</section>
<section xml:id="module-services-input-methods-uim">
<title>Uim</title>
<section xml:id="module-services-input-methods-uim"><title>Uim</title>
<para>
Uim (short for "universal input method") is a multilingual input method
framework. Applications can use it through so-called bridges.
</para>
<para>Uim (short for "universal input method") is a multilingual input method
framework. Applications can use it through so-called bridges.</para>
<para>The following snippet can be used to configure uim:</para>
<para>
The following snippet can be used to configure uim:
</para>
<programlisting>
i18n.inputMethod = {
@ -148,8 +236,9 @@ i18n.inputMethod = {
};
</programlisting>
<para>Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"/> option can be
used to choose uim toolbar.</para>
</section>
<para>
Note: The <xref linkend="opt-i18n.inputMethod.uim.toolbar"/> option can be
used to choose uim toolbar.
</para>
</section>
</chapter>

97
nixos/modules/programs/digitalbitbox/doc.xml
View File

@ -3,75 +3,64 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-programs-digitalbitbox">
<title>Digital Bitbox</title>
<para>
Digital Bitbox is a hardware wallet and second-factor authenticator.
</para>
<para>
The <literal>digitalbitbox</literal> programs module may be
installed by setting <literal>programs.digitalbitbox</literal>
to <literal>true</literal> in a manner similar to
<title>Digital Bitbox</title>
<para>
Digital Bitbox is a hardware wallet and second-factor authenticator.
</para>
<para>
The <literal>digitalbitbox</literal> programs module may be installed by
setting <literal>programs.digitalbitbox</literal> to <literal>true</literal>
in a manner similar to
<programlisting>
<xref linkend="opt-programs.digitalbitbox.enable"/> = true;
</programlisting>
and bundles the <literal>digitalbitbox</literal> package (see <xref
and bundles the <literal>digitalbitbox</literal> package (see
<xref
linkend="sec-digitalbitbox-package" />), which contains the
<literal>dbb-app</literal> and <literal>dbb-cli</literal> binaries,
along with the hardware module (see <xref
<literal>dbb-app</literal> and <literal>dbb-cli</literal> binaries, along
with the hardware module (see
<xref
linkend="sec-digitalbitbox-hardware-module" />) which sets up the
necessary udev rules to access the device.
</para>
necessary udev rules to access the device.
</para>
<para>
Enabling the digitalbitbox module is pretty much the easiest way to get a
Digital Bitbox device working on your system.
</para>
<para>
For more information, see
<link xlink:href="https://digitalbitbox.com/start_linux" />.
</para>
<section xml:id="sec-digitalbitbox-package">
<title>Package</title>
<para>
Enabling the digitalbitbox module is pretty much the easiest way to
get a Digital Bitbox device working on your system.
</para>
<para>
For more information, see
<link xlink:href="https://digitalbitbox.com/start_linux" />.
</para>
<section xml:id="sec-digitalbitbox-package">
<title>Package</title>
<para>
The binaries, <literal>dbb-app</literal> (a GUI tool) and
<literal>dbb-cli</literal> (a CLI tool), are available through the
<literal>digitalbitbox</literal> package which could be installed
as follows:
The binaries, <literal>dbb-app</literal> (a GUI tool) and
<literal>dbb-cli</literal> (a CLI tool), are available through the
<literal>digitalbitbox</literal> package which could be installed as
follows:
<programlisting>
<xref linkend="opt-environment.systemPackages"/> = [
pkgs.digitalbitbox
];
</programlisting>
</para>
</section>
<section xml:id="sec-digitalbitbox-hardware-module">
<title>Hardware</title>
<para>
The digitalbitbox hardware package enables the udev rules for
Digital Bitbox devices and may be installed as follows:
</para>
</section>
<section xml:id="sec-digitalbitbox-hardware-module">
<title>Hardware</title>
<para>
The digitalbitbox hardware package enables the udev rules for Digital Bitbox
devices and may be installed as follows:
<programlisting>
<xref linkend="opt-hardware.digitalbitbox.enable"/> = true;
</programlisting>
</para>
<para>
In order to alter the udev rules, one may provide different values for
the <literal>udevRule51</literal> and <literal>udevRule52</literal>
attributes by means of overriding as follows:
</para>
<para>
In order to alter the udev rules, one may provide different values for the
<literal>udevRule51</literal> and <literal>udevRule52</literal> attributes
by means of overriding as follows:
<programlisting>
programs.digitalbitbox = {
<link linkend="opt-programs.digitalbitbox.enable">enable</link> = true;
@ -80,6 +69,6 @@ programs.digitalbitbox = {
};
};
</programlisting>
</para>
</section>
</para>
</section>
</chapter>

37
nixos/modules/programs/plotinus.xml
View File

@ -3,23 +3,28 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-program-plotinus">
<title>Plotinus</title>
<para><emphasis>Source:</emphasis> <filename>modules/programs/plotinus.nix</filename></para>
<para><emphasis>Upstream documentation:</emphasis> <link xlink:href="https://github.com/p-e-w/plotinus"/></para>
<para>Plotinus is a searchable command palette in every modern GTK+ application.</para>
<para>When in a GTK+3 application and Plotinus is enabled, you can press <literal>Ctrl+Shift+P</literal> to open the command palette. The command palette provides a searchable list of of all menu items in the application.</para>
<para>To enable Plotinus, add the following to your <filename>configuration.nix</filename>:
<title>Plotinus</title>
<para>
<emphasis>Source:</emphasis>
<filename>modules/programs/plotinus.nix</filename>
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://github.com/p-e-w/plotinus"/>
</para>
<para>
Plotinus is a searchable command palette in every modern GTK+ application.
</para>
<para>
When in a GTK+3 application and Plotinus is enabled, you can press
<literal>Ctrl+Shift+P</literal> to open the command palette. The command
palette provides a searchable list of of all menu items in the application.
</para>
<para>
To enable Plotinus, add the following to your
<filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-programs.plotinus.enable"/> = true;
</programlisting>
</para>
</para>
</chapter>

164
nixos/modules/programs/zsh/oh-my-zsh.xml
View File

@ -3,18 +3,20 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-programs-zsh-ohmyzsh">
<title>Oh my ZSH</title>
<para>
<literal><link xlink:href="https://ohmyz.sh/">oh-my-zsh</link></literal> is a
framework to manage your <link xlink:href="https://www.zsh.org/">ZSH</link>
configuration including completion scripts for several CLI tools or custom
prompt themes.
</para>
<section xml:id="module-programs-oh-my-zsh-usage">
<title>Basic usage</title>
<title>Oh my ZSH</title>
<para><literal><link xlink:href="https://ohmyz.sh/">oh-my-zsh</link></literal> is a framework
to manage your <link xlink:href="https://www.zsh.org/">ZSH</link> configuration
including completion scripts for several CLI tools or custom prompt themes.</para>
<section xml:id="module-programs-oh-my-zsh-usage"><title>Basic usage</title>
<para>The module uses the <literal>oh-my-zsh</literal> package with all available features. The
initial setup using Nix expressions is fairly similar to the configuration format
of <literal>oh-my-zsh</literal>.
<para>
The module uses the <literal>oh-my-zsh</literal> package with all available
features. The initial setup using Nix expressions is fairly similar to the
configuration format of <literal>oh-my-zsh</literal>.
<programlisting>
{
programs.ohMyZsh = {
@ -24,39 +26,50 @@ of <literal>oh-my-zsh</literal>.
};
}
</programlisting>
For a detailed explanation of these arguments please refer to the
<link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal>
docs</link>.
</para>
For a detailed explanation of these arguments please refer to the
<link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki"><literal>oh-my-zsh</literal> docs</link>.
</para>
<para>The expression generates the needed
configuration and writes it into your <literal>/etc/zshrc</literal>.
</para></section>
<para>
The expression generates the needed configuration and writes it into your
<literal>/etc/zshrc</literal>.
</para>
</section>
<section xml:id="module-programs-oh-my-zsh-additions">
<title>Custom additions</title>
<section xml:id="module-programs-oh-my-zsh-additions"><title>Custom additions</title>
<para>Sometimes third-party or custom scripts such as a modified theme may be needed.
<literal>oh-my-zsh</literal> provides the
<link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link>
environment variable for this which points to a directory with additional scripts.</para>
<para>The module can do this as well:
<para>
Sometimes third-party or custom scripts such as a modified theme may be
needed. <literal>oh-my-zsh</literal> provides the
<link xlink:href="https://github.com/robbyrussell/oh-my-zsh/wiki/Customization#overriding-internals"><literal>ZSH_CUSTOM</literal></link>
environment variable for this which points to a directory with additional
scripts.
</para>
<para>
The module can do this as well:
<programlisting>
{
programs.ohMyZsh.custom = "~/path/to/custom/scripts";
}
</programlisting>
</para></section>
</para>
</section>
<section xml:id="module-programs-oh-my-zsh-environments">
<title>Custom environments</title>
<section xml:id="module-programs-oh-my-zsh-environments"><title>Custom environments</title>
<para>There are several extensions for <literal>oh-my-zsh</literal> packaged in <literal>nixpkgs</literal>.
One of them is <link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link>
which bundles completion scripts and a plugin for <literal>oh-my-zsh</literal>.</para>
<para>Rather than using a single mutable path for <literal>ZSH_CUSTOM</literal>, it's also possible to
generate this path from a list of Nix packages:
<para>
There are several extensions for <literal>oh-my-zsh</literal> packaged in
<literal>nixpkgs</literal>. One of them is
<link xlink:href="https://github.com/spwhitt/nix-zsh-completions">nix-zsh-completions</link>
which bundles completion scripts and a plugin for
<literal>oh-my-zsh</literal>.
</para>
<para>
Rather than using a single mutable path for <literal>ZSH_CUSTOM</literal>,
it's also possible to generate this path from a list of Nix packages:
<programlisting>
{ pkgs, ... }:
{
@ -66,42 +79,59 @@ generate this path from a list of Nix packages:
];
}
</programlisting>
Internally a single store path will be created using
<literal>buildEnv</literal>. Please refer to the docs of
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link>
for further reference.
</para>
Internally a single store path will be created using <literal>buildEnv</literal>.
Please refer to the docs of
<link xlink:href="https://nixos.org/nixpkgs/manual/#sec-building-environment"><literal>buildEnv</literal></link>
for further reference.</para>
<para>
<emphasis>Please keep in mind that this is not compatible with
<literal>programs.ohMyZsh.custom</literal> as it requires an immutable store
path while <literal>custom</literal> shall remain mutable! An evaluation
failure will be thrown if both <literal>custom</literal> and
<literal>customPkgs</literal> are set.</emphasis>
</para>
</section>
<section xml:id="module-programs-oh-my-zsh-packaging-customizations">
<title>Package your own customizations</title>
<para><emphasis>Please keep in mind that this is not compatible with <literal>programs.ohMyZsh.custom</literal>
as it requires an immutable store path while <literal>custom</literal> shall remain mutable! An evaluation failure
will be thrown if both <literal>custom</literal> and <literal>customPkgs</literal> are set.</emphasis>
</para></section>
<para>
If third-party customizations (e.g. new themes) are supposed to be added to
<literal>oh-my-zsh</literal> there are several pitfalls to keep in mind:
</para>
<section xml:id="module-programs-oh-my-zsh-packaging-customizations"><title>Package your own customizations</title>
<para>If third-party customizations (e.g. new themes) are supposed to be added to <literal>oh-my-zsh</literal>
there are several pitfalls to keep in mind:</para>
<itemizedlist>
<listitem>
<para>To comply with the default structure of <literal>ZSH</literal> the entire output needs to be written to
<literal>$out/share/zsh.</literal></para>
</listitem>
<listitem>
<para>Completion scripts are supposed to be stored at <literal>$out/share/zsh/site-functions</literal>. This directory
is part of the <literal><link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html">fpath</link></literal>
and the package should be compatible with pure <literal>ZSH</literal> setups. The module will automatically link
the contents of <literal>site-functions</literal> to completions directory in the proper store path.</para>
</listitem>
<listitem>
<para>The <literal>plugins</literal> directory needs the structure <literal>pluginname/pluginname.plugin.zsh</literal>
as structured in the <link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream repo.</link>
<itemizedlist>
<listitem>
<para>
To comply with the default structure of <literal>ZSH</literal> the entire
output needs to be written to <literal>$out/share/zsh.</literal>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>
Completion scripts are supposed to be stored at
<literal>$out/share/zsh/site-functions</literal>. This directory is part
of the
<literal><link xlink:href="http://zsh.sourceforge.net/Doc/Release/Functions.html">fpath</link></literal>
and the package should be compatible with pure <literal>ZSH</literal>
setups. The module will automatically link the contents of
<literal>site-functions</literal> to completions directory in the proper
store path.
</para>
</listitem>
<listitem>
<para>
The <literal>plugins</literal> directory needs the structure
<literal>pluginname/pluginname.plugin.zsh</literal> as structured in the
<link xlink:href="https://github.com/robbyrussell/oh-my-zsh/tree/91b771914bc7c43dd7c7a43b586c5de2c225ceb7/plugins">upstream
repo.</link>
</para>
</listitem>
</itemizedlist>
<para>
A derivation for <literal>oh-my-zsh</literal> may look like this:
<para>
A derivation for <literal>oh-my-zsh</literal> may look like this:
<programlisting>
{ stdenv, fetchFromGitHub }:
@ -120,6 +150,6 @@ stdenv.mkDerivation rec {
'';
}
</programlisting>
</para>
</section>
</para>
</section>
</chapter>

92
nixos/modules/security/acme.xml
View File

@ -3,23 +3,25 @@
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 &amp; 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 xml:id="module-security-acme-prerequisites">
<title>Prerequisites</title>
<title>SSL/TLS Certificates with ACME</title>
<para>NixOS supports automatic domain validation &amp; 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 xml:id="module-security-acme-prerequisites"><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:
<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 {
@ -37,43 +39,47 @@ http {
}
}
</programlisting>
</para>
</section>
<section xml:id="module-security-acme-configuring"><title>Configuring</title>
<para>To enable ACME certificate retrieval &amp; renewal for a certificate for
<literal>foo.example.com</literal>, add the following in your
<filename>configuration.nix</filename>:
</para>
</section>
<section xml:id="module-security-acme-configuring">
<title>Configuring</title>
<para>
To enable ACME certificate retrieval &amp; renewal for a certificate for
<literal>foo.example.com</literal>, add the following in your
<filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-security.acme.certs"/>."foo.example.com" = {
<link linkend="opt-security.acme.certs._name_.webroot">webroot</link> = "/var/www/challenges";
<link linkend="opt-security.acme.certs._name_.email">email</link> = "foo@example.com";
};
</programlisting>
</para>
</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 <xref linkend="opt-security.acme.directory"/>.
</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 <xref linkend="opt-security.acme.directory"/>.
</para>
<para>Refer to <xref linkend="ch-options" /> for all available configuration
options for the <link linkend="opt-security.acme.certs">security.acme</link> module.</para>
<para>
Refer to <xref linkend="ch-options" /> for all available configuration
options for the <link linkend="opt-security.acme.certs">security.acme</link>
module.
</para>
</section>
<section xml:id="module-security-acme-nginx">
<title>Using ACME certificates in Nginx</title>
</section>
<section xml:id="module-security-acme-nginx"><title>Using ACME certificates in Nginx</title>
<para>NixOS supports fetching ACME certificates for you by setting
<literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link> = true;</literal> in a virtualHost config. We
first create self-signed placeholder certificates in place of the
real ACME certs. The placeholder certs are overwritten when the ACME
certs arrive. For <literal>foo.example.com</literal> the config would
look like.
</para>
<para>
NixOS supports fetching ACME certificates for you by setting
<literal><link linkend="opt-services.nginx.virtualHosts._name_.enableACME">enableACME</link>
= true;</literal> in a virtualHost config. We first create self-signed
placeholder certificates in place of the real ACME certs. The placeholder
certs are overwritten when the ACME certs arrive. For
<literal>foo.example.com</literal> the config would look like.
</para>
<programlisting>
services.nginx = {
@ -89,5 +95,5 @@ services.nginx = {
};
}
</programlisting>
</section>
</section>
</chapter>

37
nixos/modules/security/hidepid.xml
View File

@ -3,31 +3,26 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-hidepid">
<title>Hiding process information</title>
<para>
Setting
<title>Hiding process information</title>
<para>
Setting
<programlisting>
<xref linkend="opt-security.hideProcessInformation"/> = true;
</programlisting>
ensures that access to process information is restricted to the
owning user. This implies, among other things, that command-line
arguments remain private. Unless your deployment relies on unprivileged
users being able to inspect the process information of other users, this
option should be safe to enable.
</para>
<para>
Members of the <literal>proc</literal> group are exempt from process
information hiding.
</para>
<para>
To allow a service <replaceable>foo</replaceable> to run without process information hiding, set
ensures that access to process information is restricted to the owning user.
This implies, among other things, that command-line arguments remain private.
Unless your deployment relies on unprivileged users being able to inspect the
process information of other users, this option should be safe to enable.
</para>
<para>
Members of the <literal>proc</literal> group are exempt from process
information hiding.
</para>
<para>
To allow a service <replaceable>foo</replaceable> to run without process
information hiding, set
<programlisting>
<link linkend="opt-systemd.services._name_.serviceConfig">systemd.services.<replaceable>foo</replaceable>.serviceConfig</link>.SupplementaryGroups = [ "proc" ];
</programlisting>
</para>
</para>
</chapter>

549
nixos/modules/services/databases/foundationdb.xml
View File

@ -3,42 +3,50 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-services-foundationdb">
<title>FoundationDB</title>
<para>
<emphasis>Source:</emphasis>
<filename>modules/services/databases/foundationdb.nix</filename>
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://apple.github.io/foundationdb/"/>
</para>
<para>
<emphasis>Maintainer:</emphasis> Austin Seipp
</para>
<para>
<emphasis>Available version(s):</emphasis> 5.1.x, 5.2.x, 6.0.x
</para>
<para>
FoundationDB (or "FDB") is an open source, distributed, transactional
key-value store.
</para>
<section xml:id="module-services-foundationdb-configuring">
<title>Configuring and basic setup</title>
<title>FoundationDB</title>
<para><emphasis>Source:</emphasis> <filename>modules/services/databases/foundationdb.nix</filename></para>
<para><emphasis>Upstream documentation:</emphasis> <link xlink:href="https://apple.github.io/foundationdb/"/></para>
<para><emphasis>Maintainer:</emphasis> Austin Seipp</para>
<para><emphasis>Available version(s):</emphasis> 5.1.x, 5.2.x, 6.0.x</para>
<para>FoundationDB (or "FDB") is an open source, distributed, transactional
key-value store.</para>
<section xml:id="module-services-foundationdb-configuring"><title>Configuring and basic setup</title>
<para>To enable FoundationDB, add the following to your
<filename>configuration.nix</filename>:
<para>
To enable FoundationDB, add the following to your
<filename>configuration.nix</filename>:
<programlisting>
services.foundationdb.enable = true;
services.foundationdb.package = pkgs.foundationdb52; # FoundationDB 5.2.x
</programlisting>
</para>
</para>
<para>The <option>services.foundationdb.package</option> option is required,
and must always be specified. Due to the fact FoundationDB network protocols and
on-disk storage formats may change between (major) versions, and upgrades must
be explicitly handled by the user, you must always manually specify this
yourself so that the NixOS module will use the proper version. Note that minor,
bugfix releases are always compatible.</para>
<para>After running <command>nixos-rebuild</command>, you can verify whether
FoundationDB is running by executing <command>fdbcli</command> (which is added
to <option>environment.systemPackages</option>):
<para>
The <option>services.foundationdb.package</option> option is required, and
must always be specified. Due to the fact FoundationDB network protocols and
on-disk storage formats may change between (major) versions, and upgrades
must be explicitly handled by the user, you must always manually specify
this yourself so that the NixOS module will use the proper version. Note
that minor, bugfix releases are always compatible.
</para>
<para>
After running <command>nixos-rebuild</command>, you can verify whether
FoundationDB is running by executing <command>fdbcli</command> (which is
added to <option>environment.systemPackages</option>):
<programlisting>
$ sudo -u foundationdb fdbcli
Using cluster file `/etc/foundationdb/fdb.cluster'.
@ -66,14 +74,14 @@ Cluster:
fdb>
</programlisting>
</para>
<para>You can also write programs using the available client libraries.
For example, the following Python program can be run in order to grab the
cluster status, as a quick example. (This example uses
<command>nix-shell</command> shebang support to automatically supply the
necessary Python modules).
</para>
<para>
You can also write programs using the available client libraries. For
example, the following Python program can be run in order to grab the
cluster status, as a quick example. (This example uses
<command>nix-shell</command> shebang support to automatically supply the
necessary Python modules).
<programlisting>
a@link> cat fdb-status.py
#! /usr/bin/env nix-shell
@ -100,255 +108,336 @@ a@link> ./fdb-status.py
FoundationDB available: True
a@link>
</programlisting>
</para>
</para>
<para>FoundationDB is run under the <command>foundationdb</command> user and
group by default, but this may be changed in the NixOS configuration. The
systemd unit <command>foundationdb.service</command> controls the
<command>fdbmonitor</command> process.</para>
<para>
FoundationDB is run under the <command>foundationdb</command> user and group
by default, but this may be changed in the NixOS configuration. The systemd
unit <command>foundationdb.service</command> controls the
<command>fdbmonitor</command> process.
</para>
<para>By default, the NixOS module for FoundationDB creates a single
SSD-storage based database for development and basic usage. This storage engine
is designed for SSDs and will perform poorly on HDDs; however it can handle far
more data than the alternative "memory" engine and is a better default choice
for most deployments. (Note that you can change the storage backend on-the-fly
for a given FoundationDB cluster using <command>fdbcli</command>.)</para>
<para>
By default, the NixOS module for FoundationDB creates a single SSD-storage
based database for development and basic usage. This storage engine is
designed for SSDs and will perform poorly on HDDs; however it can handle far
more data than the alternative "memory" engine and is a better default
choice for most deployments. (Note that you can change the storage backend
on-the-fly for a given FoundationDB cluster using
<command>fdbcli</command>.)
</para>
<para>Furthermore, only 1 server process and 1 backup agent are started in the
default configuration. See below for more on scaling to increase this.</para>
<para>FoundationDB stores all data for all server processes under
<filename>/var/lib/foundationdb</filename>. You can override this using
<option>services.foundationdb.dataDir</option>, e.g.
<para>
Furthermore, only 1 server process and 1 backup agent are started in the
default configuration. See below for more on scaling to increase this.
</para>
<para>
FoundationDB stores all data for all server processes under
<filename>/var/lib/foundationdb</filename>. You can override this using
<option>services.foundationdb.dataDir</option>, e.g.
<programlisting>
services.foundationdb.dataDir = "/data/fdb";
</programlisting>
</para>
</para>
<para>
Similarly, logs are stored under <filename>/var/log/foundationdb</filename>
by default, and there is a corresponding
<option>services.foundationdb.logDir</option> as well.
</para>
</section>
<section xml:id="module-services-foundationdb-scaling">
<title>Scaling processes and backup agents</title>
<para>Similarly, logs are stored under
<filename>/var/log/foundationdb</filename> by default, and there is a
corresponding <option>services.foundationdb.logDir</option> as well.</para>
<para>
Scaling the number of server processes is quite easy; simply specify
<option>services.foundationdb.serverProcesses</option> to be the number of
FoundationDB worker processes that should be started on the machine.
</para>
</section>
<para>
FoundationDB worker processes typically require 4GB of RAM per-process at
minimum for good performance, so this option is set to 1 by default since
the maximum amount of RAM is unknown. You're advised to abide by this
restriction, so pick a number of processes so that each has 4GB or more.
</para>
<section xml:id="module-services-foundationdb-scaling"><title>Scaling processes and backup agents</title>
<para>
A similar option exists in order to scale backup agent processes,
<option>services.foundationdb.backupProcesses</option>. Backup agents are
not as performance/RAM sensitive, so feel free to experiment with the number
of available backup processes.
</para>
</section>
<section xml:id="module-services-foundationdb-clustering">
<title>Clustering</title>
<para>Scaling the number of server processes is quite easy; simply specify
<option>services.foundationdb.serverProcesses</option> to be the number of
FoundationDB worker processes that should be started on the machine.</para>
<para>
FoundationDB on NixOS works similarly to other Linux systems, so this
section will be brief. Please refer to the full FoundationDB documentation
for more on clustering.
</para>
<para>FoundationDB worker processes typically require 4GB of RAM per-process at
minimum for good performance, so this option is set to 1 by default since the
maximum amount of RAM is unknown. You're advised to abide by this restriction,
so pick a number of processes so that each has 4GB or more.</para>
<para>
FoundationDB organizes clusters using a set of
<emphasis>coordinators</emphasis>, which are just specially-designated
worker processes. By default, every installation of FoundationDB on NixOS
will start as its own individual cluster, with a single coordinator: the
first worker process on <command>localhost</command>.
</para>
<para>A similar option exists in order to scale backup agent processes,
<option>services.foundationdb.backupProcesses</option>. Backup agents are not
as performance/RAM sensitive, so feel free to experiment with the number of
available backup processes.</para>
<para>
Coordinators are specified globally using the
<command>/etc/foundationdb/fdb.cluster</command> file, which all servers and
client applications will use to find and join coordinators. Note that this
file <emphasis>can not</emphasis> be managed by NixOS so easily:
FoundationDB is designed so that it will rewrite the file at runtime for all
clients and nodes when cluster coordinators change, with clients
transparently handling this without intervention. It is fundamentally a
mutable file, and you should not try to manage it in any way in NixOS.
</para>
</section>
<para>
When dealing with a cluster, there are two main things you want to do:
</para>
<section xml:id="module-services-foundationdb-clustering"><title>Clustering</title>
<itemizedlist>
<listitem>
<para>
Add a node to the cluster for storage/compute.
</para>
</listitem>
<listitem>
<para>
Promote an ordinary worker to a coordinator.
</para>
</listitem>
</itemizedlist>
<para>FoundationDB on NixOS works similarly to other Linux systems, so this
section will be brief. Please refer to the full FoundationDB documentation for
more on clustering.</para>
<para>
A node must already be a member of the cluster in order to properly be
promoted to a coordinator, so you must always add it first if you wish to
promote it.
</para>
<para>FoundationDB organizes clusters using a set of
<emphasis>coordinators</emphasis>, which are just specially-designated worker
processes. By default, every installation of FoundationDB on NixOS will start
as its own individual cluster, with a single coordinator: the first worker
process on <command>localhost</command>.</para>
<para>
To add a machine to a FoundationDB cluster:
</para>
<para>Coordinators are specified globally using the
<command>/etc/foundationdb/fdb.cluster</command> file, which all servers and
client applications will use to find and join coordinators. Note that this file
<emphasis>can not</emphasis> be managed by NixOS so easily: FoundationDB is
designed so that it will rewrite the file at runtime for all clients and nodes
when cluster coordinators change, with clients transparently handling this
without intervention. It is fundamentally a mutable file, and you should not
try to manage it in any way in NixOS.</para>
<itemizedlist>
<listitem>
<para>
Choose one of the servers to start as the initial coordinator.
</para>
</listitem>
<listitem>
<para>
Copy the <command>/etc/foundationdb/fdb.cluster</command> file from this
server to all the other servers. Restart FoundationDB on all of these
other servers, so they join the cluster.
</para>
</listitem>
<listitem>
<para>
All of these servers are now connected and working together in the
cluster, under the chosen coordinator.
</para>
</listitem>
</itemizedlist>
<para>When dealing with a cluster, there are two main things you want to
do:</para>
<para>
At this point, you can add as many nodes as you want by just repeating the
above steps. By default there will still be a single coordinator: you can
use <command>fdbcli</command> to change this and add new coordinators.
</para>
<itemizedlist>
<listitem><para>Add a node to the cluster for storage/compute.</para></listitem>
<listitem><para>Promote an ordinary worker to a coordinator.</para></listitem>
</itemizedlist>
<para>
As a convenience, FoundationDB can automatically assign coordinators based
on the redundancy mode you wish to achieve for the cluster. Once all the
nodes have been joined, simply set the replication policy, and then issue
the <command>coordinators auto</command> command
</para>
<para>A node must already be a member of the cluster in order to properly be
promoted to a coordinator, so you must always add it first if you wish to
promote it.</para>
<para>To add a machine to a FoundationDB cluster:</para>
<itemizedlist>
<listitem><para>Choose one of the servers to start as the initial coordinator.
</para></listitem>
<listitem><para>Copy the <command>/etc/foundationdb/fdb.cluster</command> file
from this server to all the other servers. Restart FoundationDB on all of
these other servers, so they join the cluster.</para></listitem>
<listitem><para>All of these servers are now connected and working together
in the cluster, under the chosen coordinator.</para></listitem>
</itemizedlist>
<para>At this point, you can add as many nodes as you want by just repeating
the above steps. By default there will still be a single coordinator: you can
use <command>fdbcli</command> to change this and add new coordinators.</para>
<para>As a convenience, FoundationDB can automatically assign coordinators
based on the redundancy mode you wish to achieve for the cluster. Once all the
nodes have been joined, simply set the replication policy, and then issue the
<command>coordinators auto</command> command</para>
<para>For example, assuming we have 3 nodes available, we can enable double
redundancy mode, then auto-select coordinators. For double redundancy, 3
coordinators is ideal: therefore FoundationDB will make
<emphasis>every</emphasis> node a coordinator automatically:</para>
<para>
For example, assuming we have 3 nodes available, we can enable double
redundancy mode, then auto-select coordinators. For double redundancy, 3
coordinators is ideal: therefore FoundationDB will make
<emphasis>every</emphasis> node a coordinator automatically:
</para>
<programlisting>
fdbcli> configure double ssd
fdbcli> coordinators auto
</programlisting>
<para>This will transparently update all the servers within seconds, and
appropriately rewrite the <command>fdb.cluster</command> file, as well as
informing all client processes to do the same.</para>
<para>
This will transparently update all the servers within seconds, and
appropriately rewrite the <command>fdb.cluster</command> file, as well as
informing all client processes to do the same.
</para>
</section>
<section xml:id="module-services-foundationdb-connectivity">
<title>Client connectivity</title>
</section>
<para>
By default, all clients must use the current <command>fdb.cluster</command>
file to access a given FoundationDB cluster. This file is located by default
in <command>/etc/foundationdb/fdb.cluster</command> on all machines with the
FoundationDB service enabled, so you may copy the active one from your
cluster to a new node in order to connect, if it is not part of the cluster.
</para>
</section>
<section xml:id="module-services-foundationdb-authorization">
<title>Client authorization and TLS</title>
<section xml:id="module-services-foundationdb-connectivity"><title>Client connectivity</title>
<para>
By default, any user who can connect to a FoundationDB process with the
correct cluster configuration can access anything. FoundationDB uses a
pluggable design to transport security, and out of the box it supports a
LibreSSL-based plugin for TLS support. This plugin not only does in-flight
encryption, but also performs client authorization based on the given
endpoint's certificate chain. For example, a FoundationDB server may be
configured to only accept client connections over TLS, where the client TLS
certificate is from organization <emphasis>Acme Co</emphasis> in the
<emphasis>Research and Development</emphasis> unit.
</para>
<para>By default, all clients must use the current
<command>fdb.cluster</command> file to access a given FoundationDB cluster.
This file is located by default in
<command>/etc/foundationdb/fdb.cluster</command> on all machines with the
FoundationDB service enabled, so you may copy the active one from your cluster
to a new node in order to connect, if it is not part of the cluster.</para>
<para>
Configuring TLS with FoundationDB is done using the
<option>services.foundationdb.tls</option> options in order to control the
peer verification string, as well as the certificate and its private key.
</para>
</section>
<para>
Note that the certificate and its private key must be accessible to the
FoundationDB user account that the server runs under. These files are also
NOT managed by NixOS, as putting them into the store may reveal private
information.
</para>
<section xml:id="module-services-foundationdb-authorization"><title>Client authorization and TLS</title>
<para>By default, any user who can connect to a FoundationDB process with the
correct cluster configuration can access anything. FoundationDB uses a
pluggable design to transport security, and out of the box it supports a
LibreSSL-based plugin for TLS support. This plugin not only does in-flight
encryption, but also performs client authorization based on the given
endpoint's certificate chain. For example, a FoundationDB server may be
configured to only accept client connections over TLS, where the client TLS
certificate is from organization <emphasis>Acme Co</emphasis> in the
<emphasis>Research and Development</emphasis> unit.</para>
<para>Configuring TLS with FoundationDB is done using the
<option>services.foundationdb.tls</option> options in order to control the peer
verification string, as well as the certificate and its private key.</para>
<para>Note that the certificate and its private key must be accessible to the
FoundationDB user account that the server runs under. These files are also NOT
managed by NixOS, as putting them into the store may reveal private
information.</para>
<para>After you have a key and certificate file in place, it is not enough to
simply set the NixOS module options -- you must also configure the
<command>fdb.cluster</command> file to specify that a given set of coordinators
use TLS. This is as simple as adding the suffix <command>:tls</command> to your
cluster coordinator configuration, after the port number. For example, assuming
you have a coordinator on localhost with the default configuration, simply
specifying:</para>
<para>
After you have a key and certificate file in place, it is not enough to
simply set the NixOS module options -- you must also configure the
<command>fdb.cluster</command> file to specify that a given set of
coordinators use TLS. This is as simple as adding the suffix
<command>:tls</command> to your cluster coordinator configuration, after the
port number. For example, assuming you have a coordinator on localhost with
the default configuration, simply specifying:
</para>
<programlisting>
XXXXXX:XXXXXX@127.0.0.1:4500:tls
</programlisting>
<para>will configure all clients and server processes to use TLS from now
on.</para>
<para>
will configure all clients and server processes to use TLS from now on.
</para>
</section>
<section xml:id="module-services-foundationdb-disaster-recovery">
<title>Backups and Disaster Recovery</title>
</section>
<para>
The usual rules for doing FoundationDB backups apply on NixOS as written in
the FoundationDB manual. However, one important difference is the security
profile for NixOS: by default, the <command>foundationdb</command> systemd
unit uses <emphasis>Linux namespaces</emphasis> to restrict write access to
the system, except for the log directory, data directory, and the
<command>/etc/foundationdb/</command> directory. This is enforced by default
and cannot be disabled.
</para>
<section xml:id="module-services-foundationdb-disaster-recovery"><title>Backups and Disaster Recovery</title>
<para>
However, a side effect of this is that the <command>fdbbackup</command>
command doesn't work properly for local filesystem backups: FoundationDB
uses a server process alongside the database processes to perform backups
and copy the backups to the filesystem. As a result, this process is put
under the restricted namespaces above: the backup process can only write to
a limited number of paths.
</para>
<para>The usual rules for doing FoundationDB backups apply on NixOS as written
in the FoundationDB manual. However, one important difference is the security
profile for NixOS: by default, the <command>foundationdb</command> systemd unit
uses <emphasis>Linux namespaces</emphasis> to restrict write access to the
system, except for the log directory, data directory, and the
<command>/etc/foundationdb/</command> directory. This is enforced by default
and cannot be disabled.</para>
<para>
In order to allow flexible backup locations on local disks, the FoundationDB
NixOS module supports a
<option>services.foundationdb.extraReadWritePaths</option> option. This
option takes a list of paths, and adds them to the systemd unit, allowing
the processes inside the service to write (and read) the specified
directories.
</para>
<para>However, a side effect of this is that the <command>fdbbackup</command>
command doesn't work properly for local filesystem backups: FoundationDB uses a
server process alongside the database processes to perform backups and copy the
backups to the filesystem. As a result, this process is put under the
restricted namespaces above: the backup process can only write to a limited
number of paths.</para>
<para>In order to allow flexible backup locations on local disks, the
FoundationDB NixOS module supports a
<option>services.foundationdb.extraReadWritePaths</option> option. This option
takes a list of paths, and adds them to the systemd unit, allowing the
processes inside the service to write (and read) the specified
directories.</para>
<para>For example, to create backups in <command>/opt/fdb-backups</command>,
first set up the paths in the module options:</para>
<para>
For example, to create backups in <command>/opt/fdb-backups</command>, first
set up the paths in the module options:
</para>
<programlisting>
services.foundationdb.extraReadWritePaths = [ "/opt/fdb-backups" ];
</programlisting>
<para>Restart the FoundationDB service, and it will now be able to write to
this directory (even if it does not yet exist.) Note: this path
<emphasis>must</emphasis> exist before restarting the unit. Otherwise, systemd
will not include it in the private FoundationDB namespace (and it will not add
it dynamically at runtime).</para>
<para>
Restart the FoundationDB service, and it will now be able to write to this
directory (even if it does not yet exist.) Note: this path
<emphasis>must</emphasis> exist before restarting the unit. Otherwise,
systemd will not include it in the private FoundationDB namespace (and it
will not add it dynamically at runtime).
</para>
<para>You can now perform a backup:</para>
<para>
You can now perform a backup:
</para>
<programlisting>
$ sudo -u foundationdb fdbbackup start -t default -d file:///opt/fdb-backups
$ sudo -u foundationdb fdbbackup status -t default
</programlisting>
</section>
<section xml:id="module-services-foundationdb-limitations">
<title>Known limitations</title>
</section>
<para>
The FoundationDB setup for NixOS should currently be considered beta.
FoundationDB is not new software, but the NixOS compilation and integration
has only undergone fairly basic testing of all the available functionality.
</para>
<section xml:id="module-services-foundationdb-limitations"><title>Known limitations</title>
<itemizedlist>
<listitem>
<para>
There is no way to specify individual parameters for individual
<command>fdbserver</command> processes. Currently, all server processes
inherit all the global <command>fdbmonitor</command> settings.
</para>
</listitem>
<listitem>
<para>
Ruby bindings are not currently installed.
</para>
</listitem>
<listitem>
<para>
Go bindings are not currently installed.
</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="module-services-foundationdb-options">
<title>Options</title>
<para>The FoundationDB setup for NixOS should currently be considered beta.
FoundationDB is not new software, but the NixOS compilation and integration has
only undergone fairly basic testing of all the available functionality.</para>
<itemizedlist>
<listitem><para>There is no way to specify individual parameters for
individual <command>fdbserver</command> processes. Currently, all server
processes inherit all the global <command>fdbmonitor</command> settings.
</para></listitem>
<listitem><para>Ruby bindings are not currently installed.</para></listitem>
<listitem><para>Go bindings are not currently installed.</para></listitem>
</itemizedlist>
</section>
<section xml:id="module-services-foundationdb-options"><title>Options</title>
<para>NixOS's FoundationDB module allows you to configure all of the most
relevant configuration options for <command>fdbmonitor</command>, matching it
quite closely. A complete list of options for the FoundationDB module may be
found <link linkend="opt-services.foundationdb.enable">here</link>. You should
also read the FoundationDB documentation as well.</para>
</section>
<section xml:id="module-services-foundationdb-full-docs"><title>Full documentation</title>
<para>FoundationDB is a complex piece of software, and requires careful
administration to properly use. Full documentation for administration can be
found here: <link xlink:href="https://apple.github.io/foundationdb/"/>.</para>
</section>
<para>
NixOS's FoundationDB module allows you to configure all of the most relevant
configuration options for <command>fdbmonitor</command>, matching it quite
closely. A complete list of options for the FoundationDB module may be found
<link linkend="opt-services.foundationdb.enable">here</link>. You should
also read the FoundationDB documentation as well.
</para>
</section>
<section xml:id="module-services-foundationdb-full-docs">
<title>Full documentation</title>
<para>
FoundationDB is a complex piece of software, and requires careful
administration to properly use. Full documentation for administration can be
found here: <link xlink:href="https://apple.github.io/foundationdb/"/>.
</para>
</section>
</chapter>

88
nixos/modules/services/databases/postgresql.xml
View File

@ -3,36 +3,39 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-postgresql">
<title>PostgreSQL</title>
<title>PostgreSQL</title>
<!-- FIXME: render nicely -->
<!-- FIXME: source can be added automatically -->
<para><emphasis>Source:</emphasis> <filename>modules/services/databases/postgresql.nix</filename></para>
<para><emphasis>Upstream documentation:</emphasis> <link xlink:href="http://www.postgresql.org/docs/"/></para>
<para>
<emphasis>Source:</emphasis>
<filename>modules/services/databases/postgresql.nix</filename>
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="http://www.postgresql.org/docs/"/>
</para>
<!-- FIXME: more stuff, like maintainer? -->
<para>
PostgreSQL is an advanced, free relational database.
<!-- MORE -->
</para>
<section xml:id="module-services-postgres-configuring">
<title>Configuring</title>
<para>PostgreSQL is an advanced, free relational database.<!-- MORE --></para>
<section xml:id="module-services-postgres-configuring"><title>Configuring</title>
<para>To enable PostgreSQL, add the following to your
<filename>configuration.nix</filename>:
<para>
To enable PostgreSQL, add the following to your
<filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-services.postgresql.enable"/> = true;
<xref linkend="opt-services.postgresql.package"/> = pkgs.postgresql94;
</programlisting>
Note that you are required to specify the desired version of
PostgreSQL (e.g. <literal>pkgs.postgresql94</literal>). Since
upgrading your PostgreSQL version requires a database dump and reload
(see below), NixOS cannot provide a default value for
<xref linkend="opt-services.postgresql.package"/> such as the most recent
release of PostgreSQL.</para>
Note that you are required to specify the desired version of PostgreSQL
(e.g. <literal>pkgs.postgresql94</literal>). Since upgrading your PostgreSQL
version requires a database dump and reload (see below), NixOS cannot
provide a default value for
<xref linkend="opt-services.postgresql.package"/> such as the most recent
release of PostgreSQL.
</para>
<!--
<para>After running <command>nixos-rebuild</command>, you can verify
@ -47,31 +50,28 @@ alice=>
</screen>
-->
<para>By default, PostgreSQL stores its databases in
<filename>/var/db/postgresql</filename>. You can override this using
<xref linkend="opt-services.postgresql.dataDir"/>, e.g.
<para>
By default, PostgreSQL stores its databases in
<filename>/var/db/postgresql</filename>. You can override this using
<xref linkend="opt-services.postgresql.dataDir"/>, e.g.
<programlisting>
<xref linkend="opt-services.postgresql.dataDir"/> = "/data/postgresql";
</programlisting>
</para>
</section>
<section xml:id="module-services-postgres-upgrading">
<title>Upgrading</title>
</para>
</section>
<section xml:id="module-services-postgres-upgrading"><title>Upgrading</title>
<para>FIXME: document dump/upgrade/load cycle.</para>
</section>
<section xml:id="module-services-postgres-options"><title>Options</title>
<para>A complete list of options for the PostgreSQL module may be found <link linkend="opt-services.postgresql.enable">here</link>.</para>
</section>
<para>
FIXME: document dump/upgrade/load cycle.
</para>
</section>
<section xml:id="module-services-postgres-options">
<title>Options</title>
<para>
A complete list of options for the PostgreSQL module may be found
<link linkend="opt-services.postgresql.enable">here</link>.
</para>
</section>
</chapter>

71
nixos/modules/services/desktops/flatpak.xml
View File

@ -3,51 +3,54 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-services-flatpak">
<title>Flatpak</title>
<para><emphasis>Source:</emphasis> <filename>modules/services/desktop/flatpak.nix</filename></para>
<para><emphasis>Upstream documentation:</emphasis> <link xlink:href="https://github.com/flatpak/flatpak/wiki"/></para>
<para>Flatpak is a system for building, distributing, and running sandboxed desktop applications on Linux.</para>
<para>
To enable Flatpak, add the following to your <filename>configuration.nix</filename>:
<programlisting>
<title>Flatpak</title>
<para>
<emphasis>Source:</emphasis>
<filename>modules/services/desktop/flatpak.nix</filename>
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://github.com/flatpak/flatpak/wiki"/>
</para>
<para>
Flatpak is a system for building, distributing, and running sandboxed desktop
applications on Linux.
</para>
<para>
To enable Flatpak, add the following to your
<filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-services.flatpak.enable"/> = true;
</programlisting>
</para>
<para>
For the sandboxed apps to work correctly, desktop integration portals need to be installed. If you run GNOME, this will be handled automatically for you; in other cases, you will need to add something like the following to your <filename>configuration.nix</filename>:
<programlisting>
</para>
<para>
For the sandboxed apps to work correctly, desktop integration portals need to
be installed. If you run GNOME, this will be handled automatically for you;
in other cases, you will need to add something like the following to your
<filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-services.flatpak.extraPortals"/> = [ pkgs.xdg-desktop-portal-gtk ];
</programlisting>
</para>
<para>
Then, you will need to add a repository, for example, <link xlink:href="https://github.com/flatpak/flatpak/wiki">Flathub</link>, either using the following commands:
<programlisting>
</para>
<para>
Then, you will need to add a repository, for example,
<link xlink:href="https://github.com/flatpak/flatpak/wiki">Flathub</link>,
either using the following commands:
<programlisting>
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak update
</programlisting>
or by opening the <link xlink:href="https://flathub.org/repo/flathub.flatpakrepo">repository file</link> in GNOME Software.
</para>
<para>
or by opening the
<link xlink:href="https://flathub.org/repo/flathub.flatpakrepo">repository
file</link> in GNOME Software.
</para>
<para>
Finally, you can search and install programs:
<programlisting>
<programlisting>
flatpak search bustle
flatpak install flathub org.freedesktop.Bustle
flatpak run org.freedesktop.Bustle
</programlisting>
Again, GNOME Software offers graphical interface for these tasks.
</para>
</para>
</chapter>

787
nixos/modules/services/editors/emacs.xml
View File

@ -3,150 +3,148 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-services-emacs">
<title>Emacs</title>
<!--
<title>Emacs</title>
<!--
Documentation contributors:
Damien Cassou @DamienCassou
Thomas Tuegel @ttuegel
Rodney Lorrimar @rvl
-->
<para>
<link xlink:href="http://www.gnu.org/software/emacs/">Emacs</link> is an
extensible, customizable, self-documenting real-time display editor — and
more. At its core is an interpreter for Emacs Lisp, a dialect of the Lisp
programming language with extensions to support text editing.
</para>
<para>
Emacs runs within a graphical desktop environment using the X Window System,
but works equally well on a text terminal. Under
<productname>macOS</productname>, a "Mac port" edition is available, which
uses Apple's native GUI frameworks.
</para>
<para>
<productname>Nixpkgs</productname> provides a superior environment for
running <application>Emacs</application>. It's simple to create custom builds
by overriding the default packages. Chaotic collections of Emacs Lisp code
and extensions can be brought under control using declarative package
management. <productname>NixOS</productname> even provides a
<command>systemd</command> user service for automatically starting the Emacs
daemon.
</para>
<section xml:id="module-services-emacs-installing">
<title>Installing <application>Emacs</application></title>
<para>
<link xlink:href="http://www.gnu.org/software/emacs/">Emacs</link>
is an extensible, customizable, self-documenting real-time display
editor — and more. At its core is an interpreter for Emacs Lisp, a
dialect of the Lisp programming language with extensions to
support text editing.
Emacs can be installed in the normal way for Nix (see
<xref linkend="sec-package-management" />). In addition, a NixOS
<emphasis>service</emphasis> can be enabled.
</para>
<para>
Emacs runs within a graphical desktop environment using the X
Window System, but works equally well on a text terminal. Under
<productname>macOS</productname>, a "Mac port" edition is
available, which uses Apple's native GUI frameworks.
</para>
<section xml:id="module-services-emacs-releases">
<title>The Different Releases of Emacs</title>
<para>
<productname>Nixpkgs</productname> provides a superior environment
for running <application>Emacs</application>. It's simple to
create custom builds by overriding the default packages. Chaotic
collections of Emacs Lisp code and extensions can be brought under
control using declarative package
management. <productname>NixOS</productname> even provides a
<command>systemd</command> user service for automatically
starting the Emacs daemon.
</para>
<para>
<productname>Nixpkgs</productname> defines several basic Emacs packages.
The following are attributes belonging to the <varname>pkgs</varname> set:
<variablelist>
<varlistentry>
<term>
<varname>emacs</varname>
</term>
<term>
<varname>emacs25</varname>
</term>
<listitem>
<para>
The latest stable version of Emacs 25 using the
<link
xlink:href="http://www.gtk.org">GTK+ 2</link>
widget toolkit.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>emacs25-nox</varname>
</term>
<listitem>
<para>
Emacs 25 built without any dependency on X11 libraries.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<varname>emacsMacport</varname>
</term>
<term>
<varname>emacs25Macport</varname>
</term>
<listitem>
<para>
Emacs 25 with the "Mac port" patches, providing a more native look and
feel under macOS.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<section xml:id="module-services-emacs-installing">
<title>Installing <application>Emacs</application></title>
<para>
If those aren't suitable, then the following imitation Emacs editors are
also available in Nixpkgs:
<link xlink:href="https://www.gnu.org/software/zile/">Zile</link>,
<link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>,
<link xlink:href="http://yi-editor.github.io/">Yi</link>.
</para>
</section>
<para>
Emacs can be installed in the normal way for Nix (see
<xref linkend="sec-package-management" />).
In addition, a NixOS <emphasis>service</emphasis>
can be enabled.
</para>
<section xml:id="module-services-emacs-adding-packages">
<title>Adding Packages to Emacs</title>
<section xml:id="module-services-emacs-releases">
<title>The Different Releases of Emacs</title>
<para>
Emacs includes an entire ecosystem of functionality beyond text editing,
including a project planner, mail and news reader, debugger interface,
calendar, and more.
</para>
<para>
<productname>Nixpkgs</productname> defines several basic Emacs
packages. The following are attributes belonging to the
<varname>pkgs</varname> set:
<variablelist>
<varlistentry>
<term><varname>emacs</varname></term>
<term><varname>emacs25</varname></term>
<listitem>
<para>
The latest stable version of Emacs 25 using the <link
xlink:href="http://www.gtk.org">GTK+ 2</link> widget
toolkit.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>emacs25-nox</varname></term>
<listitem>
<para>
Emacs 25 built without any dependency on X11
libraries.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><varname>emacsMacport</varname></term>
<term><varname>emacs25Macport</varname></term>
<listitem>
<para>
Emacs 25 with the "Mac port" patches, providing a more
native look and feel under macOS.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
If those aren't suitable, then the following imitation Emacs
editors are also available in Nixpkgs:
<link xlink:href="https://www.gnu.org/software/zile/">Zile</link>,
<link xlink:href="http://homepage.boetes.org/software/mg/">mg</link>,
<link xlink:href="http://yi-editor.github.io/">Yi</link>.
</para>
</section>
<section xml:id="module-services-emacs-adding-packages">
<title>Adding Packages to Emacs</title>
<para>
Emacs includes an entire ecosystem of functionality beyond
text editing, including a project planner, mail and news
reader, debugger interface, calendar, and more.
</para>
<para>
Most extensions are gotten with the Emacs packaging system
(<filename>package.el</filename>) from <link
<para>
Most extensions are gotten with the Emacs packaging system
(<filename>package.el</filename>) from
<link
xlink:href="https://elpa.gnu.org/">Emacs Lisp Package Archive
(<acronym>ELPA</acronym>)</link>,
<link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>,
<link xlink:href="https://stable.melpa.org/">MELPA Stable</link>,
and <link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>.
Nixpkgs is regularly updated to mirror all these archives.
</para>
(<acronym>ELPA</acronym>)</link>,
<link xlink:href="https://melpa.org/"><acronym>MELPA</acronym></link>,
<link xlink:href="https://stable.melpa.org/">MELPA Stable</link>, and
<link xlink:href="http://orgmode.org/elpa.html">Org ELPA</link>. Nixpkgs is
regularly updated to mirror all these archives.
</para>
<para>
Under NixOS, you can continue to use
<function>package-list-packages</function> and
<function>package-install</function> to install packages. You
can also declare the set of Emacs packages you need using the
derivations from Nixpkgs. The rest of this section discusses
declarative installation of Emacs packages through nixpkgs.
</para>
<para>
Under NixOS, you can continue to use
<function>package-list-packages</function> and
<function>package-install</function> to install packages. You can also
declare the set of Emacs packages you need using the derivations from
Nixpkgs. The rest of this section discusses declarative installation of
Emacs packages through nixpkgs.
</para>
<note>
<para>
This documentation describes the new Emacs packages
framework in NixOS 16.03
(<varname>emacsPackagesNg</varname>) which should not be
confused with the previous and deprecated framework
(<varname>emacs24Packages</varname>).
</para>
</note>
<note>
<para>
This documentation describes the new Emacs packages framework in NixOS
16.03 (<varname>emacsPackagesNg</varname>) which should not be confused
with the previous and deprecated framework
(<varname>emacs24Packages</varname>).
</para>
</note>
<para>
The first step to declare the list of packages you want in
your Emacs installation is to create a dedicated
derivation. This can be done in a dedicated
<filename>emacs.nix</filename> file such as:
<example xml:id="ex-emacsNix">
<title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title>
<programlisting language="nix">
<para>
The first step to declare the list of packages you want in your Emacs
installation is to create a dedicated derivation. This can be done in a
dedicated <filename>emacs.nix</filename> file such as:
<example xml:id="ex-emacsNix">
<title>Nix expression to build Emacs with packages (<filename>emacs.nix</filename>)</title>
<programlisting language="nix">
/*
This is a nix expression to build Emacs and some Emacs packages I like
from source on any distribution where Nix is installed. This will install
@ -181,119 +179,104 @@ in
pkgs.notmuch # From main packages set <co xml:id="ex-emacsNix-7" />
])
</programlisting>
</example>
<calloutlist>
<callout arearefs="ex-emacsNix-1">
<para>
The first non-comment line in this file
(<literal>{ pkgs ? ... }</literal>)
indicates that the whole file represents a function.
</para>
</callout>
<callout arearefs="ex-emacsNix-2">
<para>
The <varname>let</varname> expression below defines a
<varname>myEmacs</varname> binding pointing to the current
stable version of Emacs. This binding is here to separate the
choice of the Emacs binary from the specification of the
required packages.
</para>
</callout>
<callout arearefs="ex-emacsNix-3">
<para>
This generates an <varname>emacsWithPackages</varname>
function. It takes a single argument: a function from a
package set to a list of packages (the packages that will
be available in Emacs).
</para>
</callout>
<callout arearefs="ex-emacsNix-4">
<para>
The rest of the file specifies the list of packages to
install. In the example, two packages
(<varname>magit</varname> and
<varname>zerodark-theme</varname>) are taken from MELPA
stable.
</para>
</callout>
<callout arearefs="ex-emacsNix-5">
<para>
Two packages (<varname>undo-tree</varname> and
<varname>zoom-frm</varname>) are taken from MELPA.
</para>
</callout>
<callout arearefs="ex-emacsNix-6">
<para>Three packages are taken from GNU ELPA.</para>
</callout>
<callout arearefs="ex-emacsNix-7">
<para>
<varname>notmuch</varname> is taken from a nixpkgs derivation
which contains an Emacs mode.
</para>
</callout>
</calloutlist>
</para>
</example>
<calloutlist>
<callout arearefs="ex-emacsNix-1">
<para>
The result of this configuration will be an
<command>emacs</command> command which launches Emacs with all
of your chosen packages in the <varname>load-path</varname>.
The first non-comment line in this file (<literal>{ pkgs ? ...
}</literal>) indicates that the whole file represents a function.
</para>
</callout>
<callout arearefs="ex-emacsNix-2">
<para>
You can check that it works by executing this in a terminal:
The <varname>let</varname> expression below defines a
<varname>myEmacs</varname> binding pointing to the current stable
version of Emacs. This binding is here to separate the choice of the
Emacs binary from the specification of the required packages.
</para>
</callout>
<callout arearefs="ex-emacsNix-3">
<para>
This generates an <varname>emacsWithPackages</varname> function. It
takes a single argument: a function from a package set to a list of
packages (the packages that will be available in Emacs).
</para>
</callout>
<callout arearefs="ex-emacsNix-4">
<para>
The rest of the file specifies the list of packages to install. In the
example, two packages (<varname>magit</varname> and
<varname>zerodark-theme</varname>) are taken from MELPA stable.
</para>
</callout>
<callout arearefs="ex-emacsNix-5">
<para>
Two packages (<varname>undo-tree</varname> and
<varname>zoom-frm</varname>) are taken from MELPA.
</para>
</callout>
<callout arearefs="ex-emacsNix-6">
<para>
Three packages are taken from GNU ELPA.
</para>
</callout>
<callout arearefs="ex-emacsNix-7">
<para>
<varname>notmuch</varname> is taken from a nixpkgs derivation which
contains an Emacs mode.
</para>
</callout>
</calloutlist>
</para>
<para>
The result of this configuration will be an <command>emacs</command>
command which launches Emacs with all of your chosen packages in the
<varname>load-path</varname>.
</para>
<para>
You can check that it works by executing this in a terminal:
<screen>
$ nix-build emacs.nix
$ ./result/bin/emacs -q
</screen>
and then typing <literal>M-x package-initialize</literal>. Check that you
can use all the packages you want in this Emacs instance. For example, try
switching to the zerodark theme through <literal>M-x load-theme &lt;RET&gt;
zerodark &lt;RET&gt; y</literal>.
</para>
and then typing <literal>M-x package-initialize</literal>.
Check that you can use all the packages you want in this
Emacs instance. For example, try switching to the zerodark
theme through
<literal>M-x load-theme &lt;RET&gt; zerodark &lt;RET&gt; y</literal>.
</para>
<tip>
<para>
A few popular extensions worth checking out are: auctex, company,
edit-server, flycheck, helm, iedit, magit, multiple-cursors, projectile,
and yasnippet.
</para>
</tip>
<tip>
<para>
A few popular extensions worth checking out are: auctex,
company, edit-server, flycheck, helm, iedit, magit,
multiple-cursors, projectile, and yasnippet.
</para>
</tip>
<para>
The list of available packages in the various ELPA
repositories can be seen with the following commands:
<example xml:id="module-services-emacs-querying-packages">
<title>Querying Emacs packages</title>
<programlisting><![CDATA[
<para>
The list of available packages in the various ELPA repositories can be seen
with the following commands:
<example xml:id="module-services-emacs-querying-packages">
<title>Querying Emacs packages</title>
<programlisting><![CDATA[
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.elpaPackages
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaPackages
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.melpaStablePackages
nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.orgPackages
]]></programlisting>
</example>
</para>
</example>
</para>
<para>
If you are on NixOS, you can install this particular Emacs for
all users by adding it to the list of system packages
(see <xref linkend="sec-declarative-package-mgmt" />). Simply
modify your file <filename>configuration.nix</filename> to
make it contain:
<example xml:id="module-services-emacs-configuration-nix">
<title>Custom Emacs in <filename>configuration.nix</filename></title>
<programlisting><![CDATA[
<para>
If you are on NixOS, you can install this particular Emacs for all users by
adding it to the list of system packages (see
<xref linkend="sec-declarative-package-mgmt" />). Simply modify your file
<filename>configuration.nix</filename> to make it contain:
<example xml:id="module-services-emacs-configuration-nix">
<title>Custom Emacs in <filename>configuration.nix</filename></title>
<programlisting><![CDATA[
{
environment.systemPackages = [
# [...]
@ -301,60 +284,59 @@ nix-env -f "<nixpkgs>" -qaP -A emacsPackagesNg.orgPackages
];
}
]]></programlisting>
</example>
</para>
</example>
</para>
<para>
In this case, the next <command>nixos-rebuild switch</command>
will take care of adding your <command>emacs</command> to the
<varname>PATH</varname> environment variable
(see <xref linkend="sec-changing-config" />).
</para>
<para>
In this case, the next <command>nixos-rebuild switch</command> will take
care of adding your <command>emacs</command> to the <varname>PATH</varname>
environment variable (see <xref linkend="sec-changing-config" />).
</para>
<!-- fixme: i think the following is better done with config.nix
https://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides
-->
<para>
If you are not on NixOS or want to install this particular
Emacs only for yourself, you can do so by adding it to your
<filename>~/.config/nixpkgs/config.nix</filename>
(see <link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs manual</link>):
<example xml:id="module-services-emacs-config-nix">
<title>Custom Emacs in <filename>~/.config/nixpkgs/config.nix</filename></title>
<programlisting><![CDATA[
<para>
If you are not on NixOS or want to install this particular Emacs only for
yourself, you can do so by adding it to your
<filename>~/.config/nixpkgs/config.nix</filename> (see
<link xlink:href="http://nixos.org/nixpkgs/manual/#sec-modify-via-packageOverrides">Nixpkgs
manual</link>):
<example xml:id="module-services-emacs-config-nix">
<title>Custom Emacs in <filename>~/.config/nixpkgs/config.nix</filename></title>
<programlisting><![CDATA[
{
packageOverrides = super: let self = super.pkgs; in {
myemacs = import /path/to/emacs.nix { pkgs = self; };
};
}
]]></programlisting>
</example>
</para>
</example>
</para>
<para>
In this case, the next
<literal>nix-env -f '&lt;nixpkgs&gt;' -iA myemacs</literal>
will take care of adding your emacs to the
<varname>PATH</varname> environment variable.
</para>
</section>
<para>
In this case, the next <literal>nix-env -f '&lt;nixpkgs&gt;' -iA
myemacs</literal> will take care of adding your emacs to the
<varname>PATH</varname> environment variable.
</para>
</section>
<section xml:id="module-services-emacs-advanced">
<title>Advanced Emacs Configuration</title>
<section xml:id="module-services-emacs-advanced">
<title>Advanced Emacs Configuration</title>
<para>
If you want, you can tweak the Emacs package itself from your
<filename>emacs.nix</filename>. For example, if you want to
have a GTK+3-based Emacs instead of the default GTK+2-based
binary and remove the automatically generated
<filename>emacs.desktop</filename> (useful is you only use
<command>emacsclient</command>), you can change your file
<filename>emacs.nix</filename> in this way:
</para>
<para>
If you want, you can tweak the Emacs package itself from your
<filename>emacs.nix</filename>. For example, if you want to have a
GTK+3-based Emacs instead of the default GTK+2-based binary and remove the
automatically generated <filename>emacs.desktop</filename> (useful is you
only use <command>emacsclient</command>), you can change your file
<filename>emacs.nix</filename> in this way:
</para>
<example xml:id="ex-emacsGtk3Nix">
<title>Custom Emacs build</title>
<programlisting><![CDATA[
<example xml:id="ex-emacsGtk3Nix">
<title>Custom Emacs build</title>
<programlisting><![CDATA[
{ pkgs ? import <nixpkgs> {} }:
let
myEmacs = (pkgs.emacs.override {
@ -370,161 +352,143 @@ let
});
in [...]
]]></programlisting>
</example>
</example>
<para>
After building this file as shown in <xref linkend="ex-emacsNix" />,
you will get an GTK3-based Emacs binary pre-loaded with your
favorite packages.
</para>
</section>
<para>
After building this file as shown in <xref linkend="ex-emacsNix" />, you
will get an GTK3-based Emacs binary pre-loaded with your favorite packages.
</para>
</section>
<section xml:id="module-services-emacs-running">
</section>
<section xml:id="module-services-emacs-running">
<title>Running Emacs as a Service</title>
<para>
<productname>NixOS</productname> provides an optional
<command>systemd</command> service which launches
<link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">
Emacs daemon
</link>
with the user's login session.
<productname>NixOS</productname> provides an optional
<command>systemd</command> service which launches
<link xlink:href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Emacs-Server.html">
Emacs daemon </link> with the user's login session.
</para>
<para>
<emphasis>Source:</emphasis>
<filename>modules/services/editors/emacs.nix</filename>
<emphasis>Source:</emphasis>
<filename>modules/services/editors/emacs.nix</filename>
</para>
<section xml:id="module-services-emacs-enabling">
<title>Enabling the Service</title>
<para>
To install and enable the <command>systemd</command>
user service for Emacs daemon, add the following to your
<filename>configuration.nix</filename>:
<title>Enabling the Service</title>
<para>
To install and enable the <command>systemd</command> user service for Emacs
daemon, add the following to your <filename>configuration.nix</filename>:
<programlisting>
<xref linkend="opt-services.emacs.enable"/> = true;
<xref linkend="opt-services.emacs.package"/> = import /home/cassou/.emacs.d { pkgs = pkgs; };
</programlisting>
</para>
</para>
<para>
The <varname>services.emacs.package</varname> option allows a
custom derivation to be used, for example, one created by
<function>emacsWithPackages</function>.
</para>
<para>
The <varname>services.emacs.package</varname> option allows a custom
derivation to be used, for example, one created by
<function>emacsWithPackages</function>.
</para>
<para>
Ensure that the Emacs server is enabled for your user's Emacs
configuration, either by customizing the
<varname>server-mode</varname> variable, or by adding
<literal>(server-start)</literal> to
<filename>~/.emacs.d/init.el</filename>.
</para>
<para>
To start the daemon, execute the following:
<para>
Ensure that the Emacs server is enabled for your user's Emacs
configuration, either by customizing the <varname>server-mode</varname>
variable, or by adding <literal>(server-start)</literal> to
<filename>~/.emacs.d/init.el</filename>.
</para>
<para>
To start the daemon, execute the following:
<screen>
$ nixos-rebuild switch # to activate the new configuration.nix
$ systemctl --user daemon-reload # to force systemd reload
$ systemctl --user start emacs.service # to start the Emacs daemon
</screen>
The server should now be ready to serve Emacs clients.
</para>
The server should now be ready to serve Emacs clients.
</para>
</section>
<section xml:id="module-services-emacs-starting-client">
<title>Starting the client</title>
<para>
Ensure that the emacs server is enabled, either by customizing
the <varname>server-mode</varname> variable, or by adding
<literal>(server-start)</literal> to
<filename>~/.emacs</filename>.
</para>
<title>Starting the client</title>
<para>
To connect to the emacs daemon, run one of the following:
<programlisting><![CDATA[
<para>
Ensure that the emacs server is enabled, either by customizing the
<varname>server-mode</varname> variable, or by adding
<literal>(server-start)</literal> to <filename>~/.emacs</filename>.
</para>
<para>
To connect to the emacs daemon, run one of the following:
<programlisting><![CDATA[
emacsclient FILENAME
emacsclient --create-frame # opens a new frame (window)
emacsclient --create-frame --tty # opens a new frame on the current terminal
]]></programlisting>
</para>
</para>
</section>
<section xml:id="module-services-emacs-editor-variable">
<title>Configuring the <varname>EDITOR</varname> variable</title>
<!--<title><command>emacsclient</command> as the Default Editor</title>-->
<title>Configuring the <varname>EDITOR</varname> variable</title>
<para>
If <xref linkend="opt-services.emacs.defaultEditor"/> is
<literal>true</literal>, the <varname>EDITOR</varname> variable
will be set to a wrapper script which launches
<command>emacsclient</command>.
</para>
<!--<title><command>emacsclient</command> as the Default Editor</title>-->
<para>
Any setting of <varname>EDITOR</varname> in the shell config
files will override
<varname>services.emacs.defaultEditor</varname>.
To make sure <varname>EDITOR</varname> refers to the Emacs
wrapper script, remove any existing <varname>EDITOR</varname>
assignment from <filename>.profile</filename>,
<filename>.bashrc</filename>, <filename>.zshenv</filename> or
any other shell config file.
</para>
<para>
If <xref linkend="opt-services.emacs.defaultEditor"/> is
<literal>true</literal>, the <varname>EDITOR</varname> variable will be set
to a wrapper script which launches <command>emacsclient</command>.
</para>
<para>
If you have formed certain bad habits when editing files,
these can be corrected with a shell alias to the wrapper
script:
<programlisting>alias vi=$EDITOR</programlisting>
</para>
<para>
Any setting of <varname>EDITOR</varname> in the shell config files will
override <varname>services.emacs.defaultEditor</varname>. To make sure
<varname>EDITOR</varname> refers to the Emacs wrapper script, remove any
existing <varname>EDITOR</varname> assignment from
<filename>.profile</filename>, <filename>.bashrc</filename>,
<filename>.zshenv</filename> or any other shell config file.
</para>
<para>
If you have formed certain bad habits when editing files, these can be
corrected with a shell alias to the wrapper script:
<programlisting>alias vi=$EDITOR</programlisting>
</para>
</section>
<section xml:id="module-services-emacs-per-user">
<title>Per-User Enabling of the Service</title>
<para>
In general, <command>systemd</command> user services
are globally enabled by symlinks in
<filename>/etc/systemd/user</filename>. In the case where
Emacs daemon is not wanted for all users, it is possible to
install the service but not globally enable it:
<title>Per-User Enabling of the Service</title>
<para>
In general, <command>systemd</command> user services are globally enabled
by symlinks in <filename>/etc/systemd/user</filename>. In the case where
Emacs daemon is not wanted for all users, it is possible to install the
service but not globally enable it:
<programlisting>
<xref linkend="opt-services.emacs.enable"/> = false;
<xref linkend="opt-services.emacs.install"/> = true;
</programlisting>
</para>
</para>
<para>
To enable the <command>systemd</command> user service for just
the currently logged in user, run:
<programlisting>systemctl --user enable emacs</programlisting>
This will add the symlink
<filename>~/.config/systemd/user/emacs.service</filename>.
</para>
<para>
To enable the <command>systemd</command> user service for just the
currently logged in user, run:
<programlisting>systemctl --user enable emacs</programlisting>
This will add the symlink
<filename>~/.config/systemd/user/emacs.service</filename>.
</para>
</section>
</section>
<section xml:id="module-services-emacs-configuring">
</section>
<section xml:id="module-services-emacs-configuring">
<title>Configuring Emacs</title>
<para>
The Emacs init file should be changed to load the extension
packages at startup:
<example xml:id="module-services-emacs-package-initialisation">
<title>Package initialization in <filename>.emacs</filename></title>
<programlisting><![CDATA[
The Emacs init file should be changed to load the extension packages at
startup:
<example xml:id="module-services-emacs-package-initialisation">
<title>Package initialization in <filename>.emacs</filename></title>
<programlisting><![CDATA[
(require 'package)
;; optional. makes unpure packages archives unavailable
@ -533,66 +497,71 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
(setq package-enable-at-startup nil)
(package-initialize)
]]></programlisting>
</example>
</example>
</para>
<para>
After the declarative emacs package configuration has been
tested, previously downloaded packages can be cleaned up by
removing <filename>~/.emacs.d/elpa</filename> (do make a backup
first, in case you forgot a package).
After the declarative emacs package configuration has been tested,
previously downloaded packages can be cleaned up by removing
<filename>~/.emacs.d/elpa</filename> (do make a backup first, in case you
forgot a package).
</para>
<!--
<!--
todo: is it worth documenting customizations for
server-switch-hook, server-done-hook?
-->
<section xml:id="module-services-emacs-major-mode">
<title>A Major Mode for Nix Expressions</title>
<title>A Major Mode for Nix Expressions</title>
<para>
Of interest may be <varname>melpaPackages.nix-mode</varname>,
which provides syntax highlighting for the Nix language. This is
particularly convenient if you regularly edit Nix files.
</para>
<para>
Of interest may be <varname>melpaPackages.nix-mode</varname>, which
provides syntax highlighting for the Nix language. This is particularly
convenient if you regularly edit Nix files.
</para>
</section>
<section xml:id="module-services-emacs-man-pages">
<title>Accessing man pages</title>
<para>
You can use <function>woman</function> to get completion of all
available man pages. For example, type <literal>M-x woman
&lt;RET&gt; nixos-rebuild &lt;RET&gt;.</literal>
</para>
<title>Accessing man pages</title>
<para>
You can use <function>woman</function> to get completion of all available
man pages. For example, type <literal>M-x woman &lt;RET&gt; nixos-rebuild
&lt;RET&gt;.</literal>
</para>
</section>
<section xml:id="sec-emacs-docbook-xml">
<title>Editing DocBook 5 XML Documents</title>
<para>
Emacs includes <link
<title>Editing DocBook 5 XML Documents</title>
<para>
Emacs includes
<link
xlink:href="https://www.gnu.org/software/emacs/manual/html_node/nxml-mode/Introduction.html">nXML</link>,
a major-mode for validating and editing XML documents.
When editing DocBook 5.0 documents, such as
<link linkend="book-nixos-manual">this one</link>,
nXML needs to be configured with the relevant schema, which is
not included.
</para>
a major-mode for validating and editing XML documents. When editing DocBook
5.0 documents, such as <link linkend="book-nixos-manual">this one</link>,
nXML needs to be configured with the relevant schema, which is not
included.
</para>
<para>
To install the DocBook 5.0 schemas, either add
<varname>pkgs.docbook5</varname> to
<xref linkend="opt-environment.systemPackages"/> (<link
<para>
To install the DocBook 5.0 schemas, either add
<varname>pkgs.docbook5</varname> to
<xref linkend="opt-environment.systemPackages"/>
(<link
linkend="sec-declarative-package-mgmt">NixOS</link>), or run
<literal>nix-env -i pkgs.docbook5</literal>
(<link linkend="sec-ad-hoc-packages">Nix</link>).
</para>
<literal>nix-env -i pkgs.docbook5</literal>
(<link linkend="sec-ad-hoc-packages">Nix</link>).
</para>
<para>
Then customize the variable <varname>rng-schema-locating-files</varname> to include <filename>~/.emacs.d/schemas.xml</filename> and put the following text into that file:
<example xml:id="ex-emacs-docbook-xml">
<title>nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)</title>
<programlisting language="xml"><![CDATA[
<para>
Then customize the variable <varname>rng-schema-locating-files</varname> to
include <filename>~/.emacs.d/schemas.xml</filename> and put the following
text into that file:
<example xml:id="ex-emacs-docbook-xml">
<title>nXML Schema Configuration (<filename>~/.emacs.d/schemas.xml</filename>)</title>
<programlisting language="xml"><![CDATA[
<?xml version="1.0"?>
<!--
To let emacs find this file, evaluate:
@ -612,9 +581,7 @@ emacsclient --create-frame --tty # opens a new frame on the current terminal
</locatingRules>
]]></programlisting>
</example>
</para>
</para>
</section>
</section>
</section>
</chapter>

106
nixos/modules/services/misc/gitlab.xml
View File

@ -3,20 +3,22 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-services-gitlab">
<title>Gitlab</title>
<para>
Gitlab is a feature-rich git hosting service.
</para>
<section xml:id="module-services-gitlab-prerequisites">
<title>Prerequisites</title>
<title>Gitlab</title>
<para>Gitlab is a feature-rich git hosting service.</para>
<section xml:id="module-services-gitlab-prerequisites"><title>Prerequisites</title>
<para>The gitlab service exposes only an Unix socket at
<literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to configure a
webserver to proxy HTTP requests to the socket.</para>
<para>For instance, the following configuration could be used to use nginx as
frontend proxy:
<para>
The gitlab service exposes only an Unix socket at
<literal>/run/gitlab/gitlab-workhorse.socket</literal>. You need to
configure a webserver to proxy HTTP requests to the socket.
</para>
<para>
For instance, the following configuration could be used to use nginx as
frontend proxy:
<programlisting>
<link linkend="opt-services.nginx.enable">services.nginx</link> = {
<link linkend="opt-services.nginx.enable">enable</link> = true;
@ -31,21 +33,24 @@ webserver to proxy HTTP requests to the socket.</para>
};
};
</programlisting>
</para>
</para>
</section>
<section xml:id="module-services-gitlab-configuring">
<title>Configuring</title>
</section>
<para>
Gitlab depends on both PostgreSQL and Redis and will automatically enable
both services. In the case of PostgreSQL, a database and a role will be
created.
</para>
<section xml:id="module-services-gitlab-configuring"><title>Configuring</title>
<para>Gitlab depends on both PostgreSQL and Redis and will automatically enable
both services. In the case of PostgreSQL, a database and a role will be created.
</para>
<para>The default state dir is <literal>/var/gitlab/state</literal>. This is where
all data like the repositories and uploads will be stored.</para>
<para>A basic configuration with some custom settings could look like this:
<para>
The default state dir is <literal>/var/gitlab/state</literal>. This is where
all data like the repositories and uploads will be stored.
</para>
<para>
A basic configuration with some custom settings could look like this:
<programlisting>
services.gitlab = {
<link linkend="opt-services.gitlab.enable">enable</link> = true;
@ -105,40 +110,41 @@ services.gitlab = {
};
};
</programlisting>
</para>
</para>
<para>If you're setting up a new Gitlab instance, generate new secrets. You
for instance use <literal>tr -dc A-Za-z0-9 &lt; /dev/urandom | head -c 128</literal>
to generate a new secret. Gitlab encrypts sensitive data stored in the database.
If you're restoring an existing Gitlab instance, you must specify the secrets
secret from <literal>config/secrets.yml</literal> located in your Gitlab state
folder.</para>
<para>
If you're setting up a new Gitlab instance, generate new secrets. You for
instance use <literal>tr -dc A-Za-z0-9 &lt; /dev/urandom | head -c
128</literal> to generate a new secret. Gitlab encrypts sensitive data
stored in the database. If you're restoring an existing Gitlab instance, you
must specify the secrets secret from <literal>config/secrets.yml</literal>
located in your Gitlab state folder.
</para>
<para>Refer to <xref linkend="ch-options" /> for all available configuration
options for the <link linkend="opt-services.gitlab.enable">services.gitlab</link> module.</para>
<para>
Refer to <xref linkend="ch-options" /> for all available configuration
options for the
<link linkend="opt-services.gitlab.enable">services.gitlab</link> module.
</para>
</section>
<section xml:id="module-services-gitlab-maintenance">
<title>Maintenance</title>
</section>
<section xml:id="module-services-gitlab-maintenance"><title>Maintenance</title>
<para>You can run Gitlab's rake tasks with <literal>gitlab-rake</literal>
which will be available on the system when gitlab is enabled. You will
have to run the command as the user that you configured to run gitlab
with.</para>
<para>For example, to backup a Gitlab instance:
<para>
You can run Gitlab's rake tasks with <literal>gitlab-rake</literal> which
will be available on the system when gitlab is enabled. You will have to run
the command as the user that you configured to run gitlab with.
</para>
<para>
For example, to backup a Gitlab instance:
<programlisting>
$ sudo -u git -H gitlab-rake gitlab:backup:create
</programlisting>
A list of all availabe rake tasks can be obtained by running:
A list of all availabe rake tasks can be obtained by running:
<programlisting>
$ sudo -u git -H gitlab-rake -T
</programlisting>
</para>
</section>
</para>
</section>
</chapter>

209
nixos/modules/services/misc/taskserver/doc.xml
View File

@ -2,101 +2,93 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="module-taskserver">
<title>Taskserver</title>
<title>Taskserver</title>
<para>
Taskserver is the server component of
<link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and
open source todo list application.
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://taskwarrior.org/docs/#taskd"/>
</para>
<section xml:id="module-services-taskserver-configuration">
<title>Configuration</title>
<para>
Taskserver is the server component of
<link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a free and
open source todo list application.
Taskserver does all of its authentication via TLS using client certificates,
so you either need to roll your own CA or purchase a certificate from a
known CA, which allows creation of client certificates. These certificates
are usually advertised as <quote>server certificates</quote>.
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://taskwarrior.org/docs/#taskd"/>
So in order to make it easier to handle your own CA, there is a helper tool
called <command>nixos-taskserver</command> which manages the custom CA along
with Taskserver organisations, users and groups.
</para>
<section xml:id="module-services-taskserver-configuration">
<title>Configuration</title>
<para>
While the client certificates in Taskserver only authenticate whether a user
is allowed to connect, every user has its own UUID which identifies it as an
entity.
</para>
<para>
Taskserver does all of its authentication via TLS using client
certificates, so you either need to roll your own CA or purchase a
certificate from a known CA, which allows creation of client
certificates.
<para>
With <command>nixos-taskserver</command> the client certificate is created
along with the UUID of the user, so it handles all of the credentials needed
in order to setup the Taskwarrior client to work with a Taskserver.
</para>
</section>
<section xml:id="module-services-taskserver-nixos-taskserver-tool">
<title>The nixos-taskserver tool</title>
These certificates are usually advertised as
<quote>server certificates</quote>.
</para>
<para>
Because Taskserver by default only provides scripts to setup users
imperatively, the <command>nixos-taskserver</command> tool is used for
addition and deletion of organisations along with users and groups defined
by <xref linkend="opt-services.taskserver.organisations"/> and as well for
imperative set up.
</para>
<para>
So in order to make it easier to handle your own CA, there is a helper
tool called <command>nixos-taskserver</command> which manages the custom
CA along with Taskserver organisations, users and groups.
</para>
<para>
The tool is designed to not interfere if the command is used to manually set
up some organisations, users or groups.
</para>
<para>
While the client certificates in Taskserver only authenticate whether a
user is allowed to connect, every user has its own UUID which identifies
it as an entity.
</para>
<para>
For example if you add a new organisation using <command>nixos-taskserver
org add foo</command>, the organisation is not modified and deleted no
matter what you define in
<option>services.taskserver.organisations</option>, even if you're adding
the same organisation in that option.
</para>
<para>
With <command>nixos-taskserver</command> the client certificate is created
along with the UUID of the user, so it handles all of the credentials
needed in order to setup the Taskwarrior client to work with a Taskserver.
</para>
</section>
<para>
The tool is modelled to imitate the official <command>taskd</command>
command, documentation for each subcommand can be shown by using the
<option>--help</option> switch.
</para>
</section>
<section xml:id="module-services-taskserver-declarative-ca-management">
<title>Declarative/automatic CA management</title>
<section xml:id="module-services-taskserver-nixos-taskserver-tool">
<title>The nixos-taskserver tool</title>
<para>
Everything is done according to what you specify in the module options,
however in order to set up a Taskwarrior client for synchronisation with a
Taskserver instance, you have to transfer the keys and certificates to the
client machine.
</para>
<para>
Because Taskserver by default only provides scripts to setup users
imperatively, the <command>nixos-taskserver</command> tool is used for
addition and deletion of organisations along with users and groups defined
by <xref linkend="opt-services.taskserver.organisations"/> and as well for
imperative set up.
</para>
<para>
This is done using <command>nixos-taskserver user export $orgname
$username</command> which is printing a shell script fragment to stdout
which can either be used verbatim or adjusted to import the user on the
client machine.
</para>
<para>
The tool is designed to not interfere if the command is used to manually
set up some organisations, users or groups.
</para>
<para>
For example if you add a new organisation using
<command>nixos-taskserver org add foo</command>, the organisation is not
modified and deleted no matter what you define in
<option>services.taskserver.organisations</option>, even if you're adding
the same organisation in that option.
</para>
<para>
The tool is modelled to imitate the official <command>taskd</command>
command, documentation for each subcommand can be shown by using the
<option>--help</option> switch.
</para>
</section>
<section xml:id="module-services-taskserver-declarative-ca-management">
<title>Declarative/automatic CA management</title>
<para>
Everything is done according to what you specify in the module options,
however in order to set up a Taskwarrior client for synchronisation with a
Taskserver instance, you have to transfer the keys and certificates to the
client machine.
</para>
<para>
This is done using
<command>nixos-taskserver user export $orgname $username</command> which
is printing a shell script fragment to stdout which can either be used
verbatim or adjusted to import the user on the client machine.
</para>
<para>
For example, let's say you have the following configuration:
<para>
For example, let's say you have the following configuration:
<screen>
{
<xref linkend="opt-services.taskserver.enable"/> = true;
@ -105,40 +97,39 @@
<link linkend="opt-services.taskserver.organisations._name_.users">services.taskserver.organisations.my-company.users</link> = [ "alice" ];
}
</screen>
This creates an organisation called <literal>my-company</literal> with the
user <literal>alice</literal>.
</para>
This creates an organisation called <literal>my-company</literal> with the
user <literal>alice</literal>.
</para>
<para>
Now in order to import the <literal>alice</literal> user to another
machine <literal>alicebox</literal>, all we need to do is something like
this:
<para>
Now in order to import the <literal>alice</literal> user to another machine
<literal>alicebox</literal>, all we need to do is something like this:
<screen>
$ ssh server nixos-taskserver user export my-company alice | sh
</screen>
Of course, if no SSH daemon is available on the server you can also copy
&amp; paste it directly into a shell.
</para>
Of course, if no SSH daemon is available on the server you can also copy
&amp; paste it directly into a shell.
</para>
<para>
After this step the user should be set up and you can start synchronising
your tasks for the first time with <command>task sync init</command> on
<literal>alicebox</literal>.
</para>
<para>
After this step the user should be set up and you can start synchronising
your tasks for the first time with <command>task sync init</command> on
<literal>alicebox</literal>.
</para>
<para>
Subsequent synchronisation requests merely require the command
<command>task sync</command> after that stage.
</para>
</section>
<section xml:id="module-services-taskserver-manual-ca-management">
<title>Manual CA management</title>
<para>
Subsequent synchronisation requests merely require the command <command>task
sync</command> after that stage.
</para>
</section>
<section xml:id="module-services-taskserver-manual-ca-management">
<title>Manual CA management</title>
<para>
If you set any options within
<link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,
<command>nixos-taskserver</command> won't issue certificates, but you can
still use it for adding or removing user accounts.
</para>
</section>
<para>
If you set any options within
<link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,
<command>nixos-taskserver</command> won't issue certificates, but you can
still use it for adding or removing user accounts.
</para>
</section>
</chapter>

73
nixos/modules/services/misc/weechat.xml
View File

@ -3,22 +3,24 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-services-weechat">
<title>WeeChat</title>
<para>
<link xlink:href="https://weechat.org/">WeeChat</link> is a fast and
extensible IRC client.
</para>
<section>
<title>Basic Usage</title>
<title>WeeChat</title>
<para><link xlink:href="https://weechat.org/">WeeChat</link> is a fast and extensible IRC client.</para>
<section><title>Basic Usage</title>
<para>
By default, the module creates a
<literal><link xlink:href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</link></literal> unit
which runs the chat client in a detached
<literal><link xlink:href="https://www.gnu.org/software/screen/">screen</link></literal> session.
</para>
<para>
This can be done by enabling the <literal>weechat</literal> service:
<para>
By default, the module creates a
<literal><link xlink:href="https://www.freedesktop.org/wiki/Software/systemd/">systemd</link></literal>
unit which runs the chat client in a detached
<literal><link xlink:href="https://www.gnu.org/software/screen/">screen</link></literal>
session.
</para>
<para>
This can be done by enabling the <literal>weechat</literal> service:
<programlisting>
{ ... }:
@ -26,19 +28,22 @@ This can be done by enabling the <literal>weechat</literal> service:
<link linkend="opt-services.weechat.enable">services.weechat.enable</link> = true;
}
</programlisting>
</para>
<para>
The service is managed by a dedicated user
named <literal>weechat</literal> in the state directory
<literal>/var/lib/weechat</literal>.
</para>
</section>
<section><title>Re-attaching to WeeChat</title>
<para>
WeeChat runs in a screen session owned by a dedicated user. To explicitly
allow your another user to attach to this session, the <literal>screenrc</literal> needs to be tweaked
by adding <link xlink:href="https://www.gnu.org/software/screen/manual/html_node/Multiuser.html#Multiuser">multiuser</link> support:
</para>
<para>
The service is managed by a dedicated user named <literal>weechat</literal>
in the state directory <literal>/var/lib/weechat</literal>.
</para>
</section>
<section>
<title>Re-attaching to WeeChat</title>
<para>
WeeChat runs in a screen session owned by a dedicated user. To explicitly
allow your another user to attach to this session, the
<literal>screenrc</literal> needs to be tweaked by adding
<link xlink:href="https://www.gnu.org/software/screen/manual/html_node/Multiuser.html#Multiuser">multiuser</link>
support:
<programlisting>
{
<link linkend="opt-programs.screen.screenrc">programs.screen.screenrc</link> = ''
@ -47,15 +52,15 @@ by adding <link xlink:href="https://www.gnu.org/software/screen/manual/html_node
'';
}
</programlisting>
Now, the session can be re-attached like this:
Now, the session can be re-attached like this:
<programlisting>
screen -r weechat-screen
</programlisting>
</para>
<para>
<emphasis>The session name can be changed using <link linkend="opt-services.weechat.sessionName">services.weechat.sessionName.</link></emphasis>
</para>
</section>
</para>
<para>
<emphasis>The session name can be changed using
<link linkend="opt-services.weechat.sessionName">services.weechat.sessionName.</link></emphasis>
</para>
</section>
</chapter>

148
nixos/modules/services/monitoring/prometheus/exporters.xml
View File

@ -3,13 +3,19 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-services-prometheus-exporters">
<title>Prometheus exporters</title>
<para>
Prometheus exporters provide metrics for the
<link xlink:href="https://prometheus.io">prometheus monitoring system</link>.
</para>
<section xml:id="module-services-prometheus-exporters-configuration">
<title>Configuration</title>
<title>Prometheus exporters</title>
<para>Prometheus exporters provide metrics for the <link xlink:href="https://prometheus.io">prometheus monitoring system</link>.</para>
<section xml:id="module-services-prometheus-exporters-configuration"><title>Configuration</title>
<para>One of the most common exporters is the <link xlink:href="https://github.com/prometheus/node_exporter">node exporter</link>, it provides hardware and OS metrics from the host it's running on. The exporter could be configured as follows:
<para>
One of the most common exporters is the
<link xlink:href="https://github.com/prometheus/node_exporter">node
exporter</link>, it provides hardware and OS metrics from the host it's
running on. The exporter could be configured as follows:
<programlisting>
services.promtheus.exporters.node = {
enable = true;
@ -24,43 +30,88 @@
firewallFilter = "-i br0 -p tcp -m tcp --dport 9100";
};
</programlisting>
It should now serve all metrics from the collectors
that are explicitly enabled and the ones that are
<link xlink:href="https://github.com/prometheus/node_exporter#enabled-by-default">enabled by default</link>, via http under <literal>/metrics</literal>. In this example the firewall should just
allow incoming connections to the exporter's port on the bridge interface <literal>br0</literal>
(this would have to be configured seperately of course).
For more information about configuration see <literal>man configuration.nix</literal> or
search through the <link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available options</link>.
</para>
</section>
<section xml:id="module-services-prometheus-exporters-new-exporter"><title>Adding a new exporter</title>
<para>To add a new exporter, it has to be packaged first (see <literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for examples), then a module can be added. The postfix exporter is used in this example:</para>
<itemizedlist>
<listitem>
It should now serve all metrics from the collectors that are explicitly
enabled and the ones that are
<link xlink:href="https://github.com/prometheus/node_exporter#enabled-by-default">enabled
by default</link>, via http under <literal>/metrics</literal>. In this
example the firewall should just allow incoming connections to the
exporter's port on the bridge interface <literal>br0</literal> (this would
have to be configured seperately of course). For more information about
configuration see <literal>man configuration.nix</literal> or search through
the
<link xlink:href="https://nixos.org/nixos/options.html#prometheus.exporters">available
options</link>.
</para>
</section>
<section xml:id="module-services-prometheus-exporters-new-exporter">
<title>Adding a new exporter</title>
<para>
To add a new exporter, it has to be packaged first (see
<literal>nixpkgs/pkgs/servers/monitoring/prometheus/</literal> for
examples), then a module can be added. The postfix exporter is used in this
example:
</para>
<itemizedlist>
<listitem>
<para>
Some default options for all exporters are provided by
<literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>:
Some default options for all exporters are provided by
<literal>nixpkgs/nixos/modules/services/monitoring/prometheus/exporters.nix</literal>:
</para>
</listitem>
<listitem override='none'>
</listitem>
<listitem override='none'>
<itemizedlist>
<listitem><para><literal>enable</literal></para></listitem>
<listitem><para><literal>port</literal></para></listitem>
<listitem><para><literal>listenAddress</literal></para></listitem>
<listitem><para><literal>extraFlags</literal></para></listitem>
<listitem><para><literal>openFirewall</literal></para></listitem>
<listitem><para><literal>firewallFilter</literal></para></listitem>
<listitem><para><literal>user</literal></para></listitem>
<listitem><para><literal>group</literal></para></listitem>
<listitem>
<para>
<literal>enable</literal>
</para>
</listitem>
<listitem>
<para>
<literal>port</literal>
</para>
</listitem>
<listitem>
<para>
<literal>listenAddress</literal>
</para>
</listitem>
<listitem>
<para>
<literal>extraFlags</literal>
</para>
</listitem>
<listitem>
<para>
<literal>openFirewall</literal>
</para>
</listitem>
<listitem>
<para>
<literal>firewallFilter</literal>
</para>
</listitem>
<listitem>
<para>
<literal>user</literal>
</para>
</listitem>
<listitem>
<para>
<literal>group</literal>
</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>As there is already a package available, the module can now be added.
This is accomplished by adding a new file to the
<literal>nixos/modules/services/monitoring/prometheus/exporters/</literal> directory,
which will be called postfix.nix and contains all exporter specific options
and configuration:
<programlisting>
</listitem>
<listitem>
<para>
As there is already a package available, the module can now be added. This
is accomplished by adding a new file to the
<literal>nixos/modules/services/monitoring/prometheus/exporters/</literal>
directory, which will be called postfix.nix and contains all exporter
specific options and configuration:
<programlisting>
# nixpgs/nixos/modules/services/prometheus/exporters/postfix.nix
{ config, lib, pkgs }:
@ -121,15 +172,16 @@ search through the <link xlink:href="https://nixos.org/nixos/options.html#promet
}
</programlisting>
</para>
</listitem>
<listitem>
</listitem>
<listitem>
<para>
This should already be enough for the postfix exporter. Additionally one could
now add assertions and conditional default values. This can be done in the
'meta-module' that combines all exporter definitions and generates the submodules:
<literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal>
This should already be enough for the postfix exporter. Additionally one
could now add assertions and conditional default values. This can be done
in the 'meta-module' that combines all exporter definitions and generates
the submodules:
<literal>nixpkgs/nixos/modules/services/prometheus/exporters.nix</literal>
</para>
</listitem>
</itemizedlist>
</section>
</listitem>
</itemizedlist>
</section>
</chapter>

69
nixos/modules/services/networking/dnscrypt-proxy.xml
View File

@ -3,67 +3,64 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="sec-dnscrypt-proxy">
<title>DNSCrypt client proxy</title>
<title>DNSCrypt client proxy</title>
<para>
The DNSCrypt client proxy relays DNS queries to a DNSCrypt enabled upstream
resolver. The traffic between the client and the upstream resolver is
encrypted and authenticated, mitigating the risk of MITM attacks, DNS
poisoning attacks, and third-party snooping (assuming the upstream is
trustworthy).
</para>
<sect1 xml:id="sec-dnscrypt-proxy-configuration">
<title>Basic configuration</title>
<para>
The DNSCrypt client proxy relays DNS queries to a DNSCrypt enabled
upstream resolver. The traffic between the client and the upstream
resolver is encrypted and authenticated, mitigating the risk of MITM
attacks, DNS poisoning attacks, and third-party snooping (assuming the
upstream is trustworthy).
</para>
<sect1 xml:id="sec-dnscrypt-proxy-configuration"><title>Basic configuration</title>
<para>
To enable the client proxy, set
<programlisting>
To enable the client proxy, set
<programlisting>
<xref linkend="opt-services.dnscrypt-proxy.enable"/> = true;
</programlisting>
</para>
<para>
Enabling the client proxy does not alter the system nameserver; to
relay local queries, prepend <literal>127.0.0.1</literal> to
<option>networking.nameservers</option>.
Enabling the client proxy does not alter the system nameserver; to relay
local queries, prepend <literal>127.0.0.1</literal> to
<option>networking.nameservers</option>.
</para>
</sect1>
<sect1 xml:id="sec-dnscrypt-proxy-forwarder"><title>As a forwarder for another DNS client</title>
</sect1>
<sect1 xml:id="sec-dnscrypt-proxy-forwarder">
<title>As a forwarder for another DNS client</title>
<para>
To run the DNSCrypt proxy client as a forwarder for another
DNS client, change the default proxy listening port to a
non-standard value and point the other client to it:
<programlisting>
To run the DNSCrypt proxy client as a forwarder for another DNS client,
change the default proxy listening port to a non-standard value and point
the other client to it:
<programlisting>
<xref linkend="opt-services.dnscrypt-proxy.localPort"/> = 43;
</programlisting>
</para>
<sect2 xml:id="sec-dnscrypt-proxy-forwarder-dsnmasq"><title>dnsmasq</title>
<para>
<programlisting>
<sect2 xml:id="sec-dnscrypt-proxy-forwarder-dsnmasq">
<title>dnsmasq</title>
<para>
<programlisting>
{
<xref linkend="opt-services.dnsmasq.enable"/> = true;
<xref linkend="opt-services.dnsmasq.servers"/> = [ "127.0.0.1#43" ];
}
</programlisting>
</para>
</para>
</sect2>
<sect2 xml:id="sec-dnscrypt-proxy-forwarder-unbound"><title>unbound</title>
<para>
<programlisting>
<sect2 xml:id="sec-dnscrypt-proxy-forwarder-unbound">
<title>unbound</title>
<para>
<programlisting>
{
<xref linkend="opt-services.unbound.enable"/> = true;
<xref linkend="opt-services.unbound.forwardAddresses"/> = [ "127.0.0.1@43" ];
}
</programlisting>
</para>
</para>
</sect2>
</sect1>
</sect1>
</chapter>

131
nixos/modules/services/web-apps/matomo-doc.xml
View File

@ -3,28 +3,24 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-services-matomo">
<title>Matomo</title>
<para>
Matomo is a real-time web analytics application.
This module configures php-fpm as backend for Matomo, optionally configuring an nginx vhost as well.
</para>
<title>Matomo</title>
<para>
Matomo is a real-time web analytics application. This module configures
php-fpm as backend for Matomo, optionally configuring an nginx vhost as well.
</para>
<para>
An automatic setup is not suported by Matomo, so you need to configure Matomo
itself in the browser-based Matomo setup.
</para>
<section xml:id="module-services-matomo-database-setup">
<title>Database Setup</title>
<para>
An automatic setup is not suported by Matomo, so you need to configure Matomo itself in the browser-based Matomo setup.
</para>
<section xml:id="module-services-matomo-database-setup">
<title>Database Setup</title>
<para>
You also need to configure a MariaDB or MySQL database and -user for Matomo yourself,
and enter those credentials in your browser.
You can use passwordless database authentication via the UNIX_SOCKET authentication plugin
with the following SQL commands:
<programlisting>
You also need to configure a MariaDB or MySQL database and -user for Matomo
yourself, and enter those credentials in your browser. You can use
passwordless database authentication via the UNIX_SOCKET authentication
plugin with the following SQL commands:
<programlisting>
# For MariaDB
INSTALL PLUGIN unix_socket SONAME 'auth_socket';
CREATE DATABASE matomo;
@ -37,59 +33,58 @@
CREATE USER 'matomo'@'localhost' IDENTIFIED WITH auth_socket;
GRANT ALL PRIVILEGES ON matomo.* TO 'matomo'@'localhost';
</programlisting>
Then fill in <literal>matomo</literal> as database user and database name,
and leave the password field blank. This authentication works by allowing
only the <literal>matomo</literal> unix user to authenticate as the
<literal>matomo</literal> database user (without needing a password), but no
other users. For more information on passwordless login, see
<link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/" />.
</para>
Then fill in <literal>matomo</literal> as database user and database name, and leave the password field blank.
This authentication works by allowing only the <literal>matomo</literal> unix user to authenticate as the
<literal>matomo</literal> database user (without needing a password), but no other users.
For more information on passwordless login, see
<link xlink:href="https://mariadb.com/kb/en/mariadb/unix_socket-authentication-plugin/" />.
</para>
<para>
Of course, you can use password based authentication as well, e.g. when the
database is not on the same host.
</para>
</section>
<section xml:id="module-services-matomo-backups">
<title>Backup</title>
<para>
You only need to take backups of your MySQL database and the
<filename>/var/lib/matomo/config/config.ini.php</filename> file. Use a user
in the <literal>matomo</literal> group or root to access the file. For more
information, see
<link xlink:href="https://matomo.org/faq/how-to-install/faq_138/" />.
</para>
</section>
<section xml:id="module-services-matomo-issues">
<title>Issues</title>
<itemizedlist>
<listitem>
<para>
Of course, you can use password based authentication as well, e.g. when the database is not on the same host.
Matomo's file integrity check will warn you. This is due to the patches
necessary for NixOS, you can safely ignore this.
</para>
</section>
<section xml:id="module-services-matomo-backups">
<title>Backup</title>
</listitem>
<listitem>
<para>
You only need to take backups of your MySQL database and the
<filename>/var/lib/matomo/config/config.ini.php</filename> file.
Use a user in the <literal>matomo</literal> group or root to access the file.
For more information, see <link xlink:href="https://matomo.org/faq/how-to-install/faq_138/" />.
Matomo will warn you that the JavaScript tracker is not writable. This is
because it's located in the read-only nix store. You can safely ignore
this, unless you need a plugin that needs JavaScript tracker access.
</para>
</section>
</listitem>
</itemizedlist>
</section>
<section xml:id="module-services-matomo-other-web-servers">
<title>Using other Web Servers than nginx</title>
<section xml:id="module-services-matomo-issues">
<title>Issues</title>
<itemizedlist>
<listitem>
<para>
Matomo's file integrity check will warn you.
This is due to the patches necessary for NixOS, you can safely ignore this.
</para>
</listitem>
<listitem>
<para>
Matomo will warn you that the JavaScript tracker is not writable.
This is because it's located in the read-only nix store.
You can safely ignore this, unless you need a plugin that needs JavaScript tracker access.
</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="module-services-matomo-other-web-servers">
<title>Using other Web Servers than nginx</title>
<para>
You can use other web servers by forwarding calls for <filename>index.php</filename> and
<filename>piwik.php</filename> to the <literal>/run/phpfpm-matomo.sock</literal> fastcgi unix socket.
You can use the nginx configuration in the module code as a reference to what else should be configured.
</para>
</section>
<para>
You can use other web servers by forwarding calls for
<filename>index.php</filename> and <filename>piwik.php</filename> to the
<literal>/run/phpfpm-matomo.sock</literal> fastcgi unix socket. You can use
the nginx configuration in the module code as a reference to what else
should be configured.
</para>
</section>
</chapter>