aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJanik Rabe2020-04-16 15:02:16 +0300
committerJanik Rabe2020-04-16 15:02:16 +0300
commitf469dc7e0ea183cc32d9883588e90922111a8356 (patch)
treee7fd7588ac04b113c2bf69f3c164b661c4166a4c
parent3e63d3c71ae81df238c9cb57bd57b5351ac7b28c (diff)
downloadoidentd-f469dc7e0ea183cc32d9883588e90922111a8356.tar
oidentd-f469dc7e0ea183cc32d9883588e90922111a8356.tar.gz
oidentd-f469dc7e0ea183cc32d9883588e90922111a8356.tar.bz2
oidentd-f469dc7e0ea183cc32d9883588e90922111a8356.tar.xz
oidentd-f469dc7e0ea183cc32d9883588e90922111a8356.zip
[all] Import docs from website
-rw-r--r--doc/Makefile.am1
-rw-r--r--doc/book/_index.md48
-rw-r--r--doc/book/getting-started/_index.md14
-rw-r--r--doc/book/getting-started/capabilities.md103
-rw-r--r--doc/book/getting-started/configuration/_index.md186
-rw-r--r--doc/book/getting-started/configuration/examples.md75
-rw-r--r--doc/book/getting-started/installation.md61
-rw-r--r--doc/book/getting-started/starting-the-server.md52
-rw-r--r--doc/book/getting-started/support.md39
-rw-r--r--doc/book/guides/_index.md14
-rw-r--r--doc/book/guides/using-oidentd-with-quassel.md87
-rw-r--r--doc/book/guides/using-oidentd-with-znc.md65
-rw-r--r--doc/book/nat/_index.md15
-rw-r--r--doc/book/nat/forwarding.md53
-rw-r--r--doc/book/nat/introduction.md34
-rw-r--r--doc/book/nat/static-replies.md48
-rw-r--r--doc/book/security/_index.md14
-rw-r--r--doc/book/security/dropping-privileges.md53
-rw-r--r--doc/book/security/hiding-connections.md58
-rw-r--r--doc/book/security/identification-vs-authentication.md33
20 files changed, 1053 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 852dd48..6c27236 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -7,6 +7,7 @@ DISTCLEANFILES = \
$(man_MANS)
EXTRA_DIST = \
+ book \
$(man_MANS) \
oidentd.8.adoc \
oidentd.conf.5.adoc \
diff --git a/doc/book/_index.md b/doc/book/_index.md
new file mode 100644
index 0000000..b9eab7e
--- /dev/null
+++ b/doc/book/_index.md
@@ -0,0 +1,48 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "About oidentd"
+---
+
+{{% project-detail "description" %}}.
+
+oidentd is a configurable, {{< abbr "RFC" "Request for Comments" >}} 1413
+compliant Ident server.
+It runs on Linux, FreeBSD, OpenBSD, NetBSD, and DragonFly BSD.
+
+The Ident Protocol is used primarily on
+{{< abbr "IRC" "Internet Relay Chat" >}} to detect and prevent abuse and to
+identify users connecting through shared networks.
+
+## Features
+
+* oidentd is highly [configurable][configuration], but configuration is
+ optional and sensible defaults are provided.
+* oidentd provides system administrators with a granular, capability-based
+ [access control][acl] system.
+* [Conditional replies][conditionals] enable users to send replies based on
+ connection information, such as ports and IP addresses.
+* oidentd is capable of sending [hidden][cap-hide], [randomized][cap-random],
+ and [spoofed][cap-spoof] replies.
+* oidentd can optionally handle requests for
+ [{{< abbr "NAT" "Network Address Translation" >}} connections][nat]
+ and is capable of forwarding requests to other Ident servers.
+* Both {{< abbr "IPv4" "Internet Protocol, Version 4" >}} and
+ {{< abbr "IPv6" "Internet Protocol, Version 6" >}} are supported.
+* oidentd is free software licensed under the
+ {{< abbr "GNU" "GNU's Not Unix" >}}
+ {{< abbr "GPLv2" "General Public License, Version 2" >}}.
+
+[acl]: {{% ref "getting-started/configuration#capability-directives" %}}
+[cap-hide]: {{% ref "getting-started/capabilities#hide" %}}
+[cap-random]: {{% ref "getting-started/capabilities#random" %}}
+[cap-spoof]: {{% ref "getting-started/capabilities#spoof" %}}
+[conditionals]: {{% ref "getting-started/configuration#range-specification" %}}
+[configuration]: {{% ref "getting-started/configuration" %}}
+[nat]: {{% ref "nat/introduction" %}}
diff --git a/doc/book/getting-started/_index.md b/doc/book/getting-started/_index.md
new file mode 100644
index 0000000..8e3387f
--- /dev/null
+++ b/doc/book/getting-started/_index.md
@@ -0,0 +1,14 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Getting Started"
+weight: 1
+---
+
+Learn how to install and configure oidentd.
diff --git a/doc/book/getting-started/capabilities.md b/doc/book/getting-started/capabilities.md
new file mode 100644
index 0000000..705df40
--- /dev/null
+++ b/doc/book/getting-started/capabilities.md
@@ -0,0 +1,103 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Capabilities"
+weight: 2
+---
+
+Capabilities allow the system administrator to control the set of features
+users have access to.
+They can be granted or revoked using [capability directives][capdirs].
+No capabilities are granted to users by default.
+
+## `forward`
+
+The `forward` capability allows users to forward Ident queries to another
+server.
+The `host` and `port` arguments specify the host and port of the receiving
+Ident server.
+This server must support forwarding (e.g., oidentd with the `--proxy` option).
+
+Forwarding does not allow users to send replies they otherwise would not be
+able to send.
+For example, if the receiving Ident server replies with the name of another
+user, the reply will be sent back to the client only if the user that owns the
+connection was granted the `spoof` and `spoof_all` capabilities.
+This restriction does not apply to `force forward` statements in the
+system-wide configuration file.
+
+Imperative syntax: `forward <host> <port>`
+
+## `hide`
+
+The `hide` capability allows users to hide their connections.
+When used, oidentd reports a `HIDDEN-USER` error to clients.
+
+Imperative syntax: `hide`
+
+## `numeric`
+
+The `numeric` capability allows users to reply with their user ID (UID) instead
+of their user name.
+
+Imperative syntax: `numeric`
+
+## `random`
+
+The `random` capability allows users to send random alphanumeric Ident replies.
+Replies are logged so that the system administrator can identify the user
+responsible for a particular connection.
+
+Imperative syntax: `random`
+
+## `random_numeric`
+
+The `random_numeric` capability allows users to send random numeric Ident
+replies of the form `userNNNNN`, where `N` represents a digit from 0 to 9.
+Replies are logged so that the system administrator can identify the user
+responsible for a particular connection.
+
+Imperative syntax: `random_numeric`
+
+## `reply`
+
+The `reply` capability cannot be granted or revoked.
+However, using it may require one or more of `spoof`, `spoof_all`, and
+`spoof_privport`, depending on the replies and type of connection.
+
+If more than one reply is given, a random reply is chosen from the list for
+each incoming query.
+At least one reply must be specified.
+
+Imperative syntax: `reply <replies ...>`
+
+## `spoof`
+
+The `spoof` capability allows users to send custom Ident replies, except in
+cases that require the `spoof_all` or `spoof_privport` capabilities.
+
+This capability does not have an imperative syntax.
+
+## `spoof_all`
+
+The `spoof_all` capability allows users to reply with the names of other users
+on the system.
+It only works in conjunction with the `spoof` capability.
+
+This capability does not have an imperative syntax.
+
+## `spoof_privport`
+
+The `spoof_privport` capability allows users to spoof replies for connections
+to privileged foreign ports (port numbers below 1024).
+It only works in conjunction with the `spoof` capability.
+
+This capability does not have an imperative syntax.
+
+[capdirs]: {{% ref "configuration#capability-directives" %}}
diff --git a/doc/book/getting-started/configuration/_index.md b/doc/book/getting-started/configuration/_index.md
new file mode 100644
index 0000000..7bda886
--- /dev/null
+++ b/doc/book/getting-started/configuration/_index.md
@@ -0,0 +1,186 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Configuration"
+weight: 3
+---
+
+When an Ident query is received, oidentd normally replies with the user name of
+the user that owns the corresponding connection.
+Users can override this behavior only if they have been granted permission to
+do so through the system-wide configuration file.
+
+## System-wide Configuration File
+
+The system-wide configuration file is usually found at `/etc/oidentd.conf` or
+`/usr/local/etc/oidentd.conf`, depending on how oidentd was installed.
+It is not necessary for this file to exist.
+
+This file may contain any number of [user directives][user-directives].
+
+## User Configuration File
+
+Each user may also create a user configuration file at `~/.config/oidentd.conf`
+or `~/.oidentd.conf`.
+If both files exist, only the former is used.
+The user configuration file is ignored if oidentd does not have permission to
+read it.
+
+This file may contain one directive of the following form:
+
+{{< code >}}
+global {
+ <capability-statements ...>
+}
+{{< /code >}}
+
+This `global` directive matches all connections.
+If used, it should be the first directive in the file.
+
+The user configuration file may also contain any number of directives of the
+following form:
+
+{{< code >}}
+<range-specification> {
+ <capability-statements ...>
+}
+{{< /code >}}
+
+In this form the directive only applies to connections that match the given
+range specification.
+
+## User Directives
+
+A user directive takes one of the following forms:
+
+{{< code >}}
+default {
+ <range-directives ...>
+}
+{{< /code >}}
+
+This form can be used to specify defaults for users.
+There should be no more than one directive of this form.
+If used, it should be the first user directive.
+
+{{< code >}}
+user "<username>" {
+ <range-directives ...>
+}
+{{< /code >}}
+
+In this form the directive applies only to the specified user.
+
+## Range Directives
+
+A range directive takes one of the following forms:
+
+{{< code >}}
+default {
+ <capability-directives ...>
+}
+{{< /code >}}
+
+In this form the directive matches when no other range directive in its scope
+does.
+There should be no more than one directive of this form.
+If used, it should be the first range directive.
+
+{{< code >}}
+<range-specification> {
+ <capability-directives ...>
+}
+{{< /code >}}
+
+In this form the directive only applies to connections that match the given
+range specification.
+
+## Range Specification
+
+A range specification takes the following form:
+
+{{< code >}}
+[to <host>] [fport <port>] [from <host>] [lport <port>]
+{{< /code >}}
+
+* `to` is the foreign address associated with the connection.
+* `fport` is the foreign port associated with the connection.
+* `from` is the local address associated with the connection.
+* `lport` is the local port associated with the connection.
+
+At least one of the four filters must be specified.
+
+Hosts may be specified by hostname or by
+{{< abbr "IP" "Internet Protocol" >}} address.
+Ports may optionally be specified as a port range of the form `min:max`,
+`min:`, or `:max`.
+
+A range specification matches a connection if all specified filters match.
+
+## Capability Directives
+
+A capability directive takes one of the following forms:
+
+{{< code >}}
+allow <capability>
+{{< /code >}}
+
+In this form the directive grants the specified capability.
+
+{{< code >}}
+deny <capability>
+{{< /code >}}
+
+In this form the directive revokes the specified capability.
+
+{{< code >}}
+force <capability-statement>
+{{< /code >}}
+
+In this form the directive enforces use of the specified capability.
+
+## Capabilities
+
+The following are valid capabilities:
+
+* [`forward`][cap-forward]
+* [`hide`][cap-hide]
+* [`numeric`][cap-numeric]
+* [`random`][cap-random]
+* [`random_numeric`][cap-random_numeric]
+* [`spoof`][cap-spoof]
+* [`spoof_all`][cap-spoof_all]
+* [`spoof_privport`][cap-spoof_privport]
+
+## Capability Statements
+
+The following are valid capability statements:
+
+* [`forward <host> <port>`][cap-forward]
+* [`hide`][cap-hide]
+* [`numeric`][cap-numeric]
+* [`random`][cap-random]
+* [`random_numeric`][cap-random_numeric]
+* [`reply <replies ...>`][cap-reply]
+
+## Further Reading
+
+The `oidentd.conf(5)` manual page contains further information on how to
+configure oidentd, as well as detailed descriptions of all capabilities.
+
+[user-directives]: {{% ref "#user-directives" %}}
+[cap-forward]: {{% ref "capabilities#forward" %}}
+[cap-hide]: {{% ref "capabilities#hide" %}}
+[cap-numeric]: {{% ref "capabilities#numeric" %}}
+[cap-random]: {{% ref "capabilities#random" %}}
+[cap-random_numeric]: {{% ref "capabilities#random-numeric" %}}
+[cap-reply]: {{% ref "capabilities#reply" %}}
+[cap-spoof]: {{% ref "capabilities#spoof" %}}
+[cap-spoof_all]: {{% ref "capabilities#spoof-all" %}}
+[cap-spoof_privport]: {{% ref "capabilities#spoof-privport" %}}
diff --git a/doc/book/getting-started/configuration/examples.md b/doc/book/getting-started/configuration/examples.md
new file mode 100644
index 0000000..fcc954f
--- /dev/null
+++ b/doc/book/getting-started/configuration/examples.md
@@ -0,0 +1,75 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Examples"
+weight: 1
+---
+
+The following examples illustrate how capabilities and conditional directives
+can be used in system-wide and user configuration files.
+
+Lines stating with `#` are comments.
+They are ignored by oidentd.
+
+## System-wide Configuration File
+
+This configuration allows `ryan` to send spoofed and random Ident replies,
+except in response to lookups for connections to `example.net`.
+Other users' connections are hidden so that no user information is disclosed.
+
+{{< code >}}
+default { # User defaults
+ default { # Connection defaults
+ # Hide all connections from users not
+ # explicitly listed in this file.
+ force hide
+ }
+}
+
+user ryan { # Settings for user "ryan"
+
+ default { # Connection defaults
+ # Allow ryan to send custom Ident replies,
+ # except for the names of other users.
+ allow spoof
+
+ # Allow ryan to send random Ident replies.
+ allow random
+ }
+
+ to example.net { # Connections to example.net
+ # Do not allow ryan to spoof Ident replies.
+ force reply "ryan"
+ }
+}
+{{< /code >}}
+
+## User Configuration File
+
+This user configuration file instructs oidentd to reply to Ident queries for
+connections to foreign ports `6667` through `6697` with the name of a random
+Greek letter.
+This requires the `spoof` capability.
+It also requires the `spoof_all` capability if there is a local user named
+"alpha", "beta", or "gamma".
+
+A random alphanumeric Ident reply is sent in response to all other queries.
+This requires the `random` capability.
+
+{{< code >}}
+global { # Connection defaults
+ # Send random Ident replies by default.
+ random
+}
+
+fport 6667:6697 { # Foreign ports from 6667 to 6697
+ # Choose one of three Greek letters at random.
+ reply "alpha" "beta" "gamma"
+}
+{{< /code >}}
diff --git a/doc/book/getting-started/installation.md b/doc/book/getting-started/installation.md
new file mode 100644
index 0000000..dce5eb8
--- /dev/null
+++ b/doc/book/getting-started/installation.md
@@ -0,0 +1,61 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Installation"
+weight: 1
+---
+
+{{% alert "primary" "Looking for the download link?" %}}
+You can download oidentd from the
+[project website]({{% ref "/projects/oidentd" %}}).
+{{% /alert %}}
+
+Most popular operating system distributions include a recent version of oidentd
+in their package repositories.
+Installing oidentd using a package manager is recommended in most cases.
+
+In some cases, however, it may be desirable to install oidentd from source.
+This may be useful if your distribution does not package a recent version of
+oidentd, or if there are any compile-time features you would like to enable.
+
+More detailed instructions for compiling and installing oidentd can be found in
+the `INSTALL` file included in all releases.
+
+### Configuring the Build
+
+After downloading, verifying and extracting oidentd, enter the directory you
+extracted and run `./configure` to configure the build.
+
+On many modern Linux systems, you may have to install libnetfilter\_conntrack
+before running `./configure`.
+More information can be found in the `INSTALL` file in the source tree.
+
+The `./configure` script supports a number of optional flags:
+
+* `--disable-ipv6` disables support for
+ {{< abbr "IPv6" "Internet Protocol, Version 6" >}}.
+* `--disable-libnfct` disables support for libnetfilter\_conntrack.
+* `--disable-nat` disables support for
+ {{< abbr "NAT" "Network Address Translation" >}}.
+* `--enable-debug` compiles oidentd with the `--debug` option.
+* `--enable-warn` is intended for developers and enables additional warning
+ messages during compilation.
+
+### Compile oidentd
+
+Run `make` to compile oidentd.
+
+You can run `src/oidentd --version` to verify that the compilation succeeded.
+
+### Install oidentd
+
+Run `make install` as root to install oidentd.
+
+To uninstall oidentd later on, run `make uninstall` as root in the same
+directory.
diff --git a/doc/book/getting-started/starting-the-server.md b/doc/book/getting-started/starting-the-server.md
new file mode 100644
index 0000000..b2c5f8f
--- /dev/null
+++ b/doc/book/getting-started/starting-the-server.md
@@ -0,0 +1,52 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Starting the Server"
+weight: 4
+---
+
+oidentd can be run as a standalone server or started by a service manager.
+By default, oidentd forks to the background after starting up.
+
+If you installed oidentd from your distribution's package repositories, an
+initialization script or [systemd service][systemd] may already have been
+included in the package.
+Consult your distribution's documentation for more information.
+
+oidentd needs to be started as root on most systems, but normally drops its
+privileges automatically after starting up.
+See [Dropping Privileges][drop-privs] for details.
+
+Run `oidentd` to start the server.
+
+oidentd accepts a large number of command-line options.
+Some commonly used options are:
+
+* `-a`, `--address`: bind to the specified address (may be specified multiple
+ times)
+* `-d`, `--debug`: show messages that may be useful for debugging
+* `-i`, `--foreground`: do not run as a background process
+* `-p`, `--port`: listen on the specified port instead of port 113
+
+The `oidentd(8)` manual page contains a complete list of options with detailed
+explanations.
+`oidentd --help` prints a list with more concise descriptions.
+
+## systemd Service
+
+Many systemd-based distributions include service files for oidentd.
+On these distributions, oidentd can be started and enabled with the following
+command:
+
+{{< code >}}
+systemctl enable --now oidentd
+{{< /code >}}
+
+[drop-privs]: {{% ref dropping-privileges %}}
+[systemd]: {{% ref "#systemd-service" %}}
diff --git a/doc/book/getting-started/support.md b/doc/book/getting-started/support.md
new file mode 100644
index 0000000..ae3a67d
--- /dev/null
+++ b/doc/book/getting-started/support.md
@@ -0,0 +1,39 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Support"
+weight: 5
+---
+
+If you need help or have any questions about oidentd, feel free to use any of
+the following resources.
+
+## Documentation
+
+Documentation for oidentd can be found in the `oidentd(8)`, `oidentd.conf(5)`,
+and `oidentd_masq.conf(5)` manual pages.
+
+Additional documentation for developers and package maintainers is available in
+the `INSTALL` and `HACKING` files in the oidentd source tree.
+
+## {{< abbr "IRC" "Internet Relay Chat" >}} Channel
+
+You can find us in `#oidentd` on `ircs://chat.freenode.net`.
+Please be patient; it may take a while for someone to see your message.
+
+## Contact the Maintainer
+
+Feel free to [contact the project maintainer][contact-maint] if you have any
+questions or need help with oidentd.
+
+This is also the best way to share any feedback you may have.
+We're always looking for ways to make oidentd better, and we'd appreciate your
+help.
+
+[contact-maint]: {{% ref "/contact" %}}
diff --git a/doc/book/guides/_index.md b/doc/book/guides/_index.md
new file mode 100644
index 0000000..81cf0d0
--- /dev/null
+++ b/doc/book/guides/_index.md
@@ -0,0 +1,14 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Guides"
+weight: 2
+---
+
+Learn how to use oidentd with other software.
diff --git a/doc/book/guides/using-oidentd-with-quassel.md b/doc/book/guides/using-oidentd-with-quassel.md
new file mode 100644
index 0000000..fc02cd2
--- /dev/null
+++ b/doc/book/guides/using-oidentd-with-quassel.md
@@ -0,0 +1,87 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Using oidentd with Quassel"
+weight: 1
+---
+
+You can use oidentd to spoof Ident replies so that they match Idents configured
+within Quassel.
+
+## Forwarding to Quassel
+
+oidentd can forward incoming queries for connections owned by the Quassel user
+directly to Quassel's built-in Ident server.
+This is the recommended method.
+
+Append the following to your [system-wide configuration file][sys-conf]:
+
+{{< code >}}
+user "<username>" {
+ default {
+ allow spoof
+
+ # Add the next line if Quassel needs to
+ # reply with the name of a local user.
+ allow spoof_all
+
+ force forward <host> <port>
+ }
+}
+{{< /code >}}
+
+Replace `<username>` with the user name of the Quassel user (e.g.,
+`quasselcore`).
+
+Replace `<host>` with the {{< abbr "IP" "Internet Protocol" >}} address or
+hostname Quassel's built-in Ident server is configured to listen on (e.g.,
+`::1`).
+
+Replace `<port>` with the port Quassel's built-in Ident server is configured to
+listen on (e.g., `10113`).
+
+## Using Quassel's oidentd Configuration Generator
+
+Quassel can automatically write to an oidentd user configuration file when
+establishing a new connection.
+
+Use of this feature is discouraged as of oidentd 2.3.0.
+Some {{< abbr "IRC" "Internet Relay Chat" >}} servers send Ident queries before
+the connection's local port is known to Quassel, which may cause lookups to
+fail.
+
+Append the following to your [system-wide configuration file][sys-conf]:
+
+{{< code >}}
+user "<username>" {
+ default {
+ allow spoof
+
+ # Use this only if Quassel needs to spoof local user names
+ allow spoof_all
+ }
+}
+{{< /code >}}
+
+Replace `<username>` with the user name of the Quassel user (e.g.,
+`quasselcore`).
+
+Ensure that the Quassel home directory (typically `~quasselcore`) is
+world-executable (mode `0711`) so that oidentd can read the user configuration
+file:
+
+{{< code >}}
+chmod 0711 ~quasselcore
+{{< /code >}}
+
+Finally, make sure Quassel is run with the `--oidentd` flag.
+
+Your changes will take effect after you reload oidentd and restart Quassel.
+
+[sys-conf]: {{% ref "../getting-started/configuration#system-wide-configuration-file" %}}
diff --git a/doc/book/guides/using-oidentd-with-znc.md b/doc/book/guides/using-oidentd-with-znc.md
new file mode 100644
index 0000000..97283f7
--- /dev/null
+++ b/doc/book/guides/using-oidentd-with-znc.md
@@ -0,0 +1,65 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Using oidentd with ZNC"
+weight: 2
+---
+
+You can use oidentd to spoof Ident replies so that they match Idents configured
+within ZNC.
+
+Append the following to your [system-wide configuration file][sys-conf]:
+
+{{< code >}}
+user "<username>" {
+ default {
+ allow spoof
+
+ # Add the next line if ZNC needs to
+ # reply with the name of a local user.
+ allow spoof_all
+ }
+}
+{{< /code >}}
+
+Replace `<username>` with the user name of the ZNC user (e.g., `znc`).
+
+Change to the user running ZNC (e.g., using `su znc -ls "$SHELL"`), and use the
+following commands to create an empty [user configuration file][usr-conf]:
+
+{{< code >}}
+touch ~/.oidentd.conf
+chmod 0644 ~/.oidentd.conf
+{{< /code >}}
+
+Ensure that the ZNC home directory (typically `~znc`) is world-executable (mode
+`0711`) so that oidentd can read the user configuration file:
+
+{{< code >}}
+chmod 0711 ~
+{{< /code >}}
+
+Ensure that ZNC's *identfile* module is loaded and configured correctly:
+
+{{< code >}}
+/MSG *status LoadMod identfile
+/MSG *identfile SetFile ~/.oidentd.conf
+/MSG *identfile SetFormat global { reply "%user%" }
+/MSG *status SaveConfig
+{{< /code >}}
+
+Note that `%user%` expands to the name of the ZNC user that initiated the
+connection.
+Another popular choice is `%ident%`, which allows users to specify any Ident.
+
+Your changes will take effect after you reload oidentd and reconnect to
+{{< abbr "IRC" "Internet Relay Chat" >}}.
+
+[sys-conf]: {{% ref "../getting-started/configuration#system-wide-configuration-file" %}}
+[usr-conf]: {{% ref "../getting-started/configuration#user-configuration-file" %}}
diff --git a/doc/book/nat/_index.md b/doc/book/nat/_index.md
new file mode 100644
index 0000000..d4b12c7
--- /dev/null
+++ b/doc/book/nat/_index.md
@@ -0,0 +1,15 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "NAT"
+weight: 3
+---
+
+Learn how to use oidentd for
+{{< abbr "NAT" "Network Address Translation" >}} connections.
diff --git a/doc/book/nat/forwarding.md b/doc/book/nat/forwarding.md
new file mode 100644
index 0000000..4a05801
--- /dev/null
+++ b/doc/book/nat/forwarding.md
@@ -0,0 +1,53 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Forwarding"
+weight: 3
+---
+
+oidentd can forward Ident queries to the host they were intended for, provided
+that this host is connecting through the machine oidentd is running on.
+
+When forwarding is enabled, the default behavior is to forward immediately and
+only fall back to using the configured [static replies][static-replies] if
+forwarding fails.
+This can be changed by using the `--masquerade-first` (`-M`) flag, in which
+case oidentd only forwards requests if no matching static reply was found.
+
+## Configuring the Gateway
+
+Forwarding can be enabled on the device performing network address translation
+by running oidentd with the `--forward` (`-f`) option.
+Optionally, a target port may be specified using `--forward=port`.
+If no port is specified, port `113` is used.
+
+## Configuring the Servers
+
+All machines that need to receive forwarded queries must be running an Ident
+server capable of handling these queries, such as oidentd with the `--proxy`
+(`-P`) option.
+For example, oidentd can be run on a machine behind {{< abbr "NAT"
+"Network Address Translation" >}} with the following command:
+
+{{< code >}}
+oidentd -P 10.0.0.1
+{{< /code >}}
+
+This allows `10.0.0.1` to forward queries to the current oidentd instance.
+
+If you specified a custom target port for forwarding, make sure the target
+server is configured to listen on that port:
+
+{{< code >}}
+oidentd -P 10.0.0.1 -p 113
+{{< /code >}}
+
+Port `113` is the default and does not need to be specified explicitly.
+
+[static-replies]: {{% ref "static-replies" %}}
diff --git a/doc/book/nat/introduction.md b/doc/book/nat/introduction.md
new file mode 100644
index 0000000..c60a8ac
--- /dev/null
+++ b/doc/book/nat/introduction.md
@@ -0,0 +1,34 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Introduction"
+weight: 1
+---
+
+oidentd can handle Ident queries for other machines connecting through the
+server it is running on.
+This is especially useful when the server running oidentd performs Network
+Address Translation (NAT).
+
+Before configuring oidentd to use {{< abbr "NAT" "Network Address Translation"
+>}}, please take a look at the `KERNEL_SUPPORT.md` file in the source tree to
+find out whether {{< abbr "NAT" "Network Address Translation" >}} is supported
+on your system.
+
+oidentd supports two features that may be useful in combination with {{< abbr
+"NAT" "Network Address Translation" >}}:
+
+- [Static replies][static] instruct oidentd to send a certain reply in response
+ to every Ident query intended for a particular host or subnetwork.
+- [Forwarding][forwarding] allows Ident queries to be forwarded through {{<
+ abbr "NAT" "Network Address Translation" >}} to the host that established a
+ connection.
+
+[static]: {{% ref "static-replies" %}}
+[forwarding]: {{% ref "forwarding" %}}
diff --git a/doc/book/nat/static-replies.md b/doc/book/nat/static-replies.md
new file mode 100644
index 0000000..c5ad905
--- /dev/null
+++ b/doc/book/nat/static-replies.md
@@ -0,0 +1,48 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Static Replies"
+weight: 2
+---
+
+oidentd can send different Ident replies for each host connecting through the
+machine it is running on.
+
+To enable this functionality, oidentd must be run with the `--masquerade`
+(`-m`) flag.
+
+## Configuring Replies
+
+Replies can be configured in the masquerading configuration file, which is
+usually found in `/etc/oidentd_masq.conf` or in
+`/usr/local/etc/oidentd_masq.conf`, depending on how oidentd was installed.
+
+This file should consist of lines of the following form:
+
+{{< code >}}
+<host>[/subnet] ident_reply system_type
+{{< /code >}}
+
+The masquerading configuration file is read from top to bottom, so more
+specific rules should be placed before more general ones.
+For example:
+
+{{< code >}}
+10.0.0.1 user1 UNIX
+10.0.0.2 user2 FREEBSD
+10.0.0.0/24 user3 OTHER
+{{< /code >}}
+
+In this example, a `user1` reply is sent in response to all requests for
+`10.0.0.1`.
+A `user2` reply is sent for all requests for `10.0.0.2`.
+Finally, `user3` is sent in response to requests for other machines in the
+`10.0.0.0/24` subnetwork.
+
+Detailed information can be found in the `oidentd_masq.conf(5)` manual page.
diff --git a/doc/book/security/_index.md b/doc/book/security/_index.md
new file mode 100644
index 0000000..00caed8
--- /dev/null
+++ b/doc/book/security/_index.md
@@ -0,0 +1,14 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Security"
+weight: 4
+---
+
+Improve the security of your oidentd instance.
diff --git a/doc/book/security/dropping-privileges.md b/doc/book/security/dropping-privileges.md
new file mode 100644
index 0000000..a34e1f9
--- /dev/null
+++ b/doc/book/security/dropping-privileges.md
@@ -0,0 +1,53 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Dropping Privileges"
+weight: 1
+---
+
+It is highly recommended not to run internet-facing services as root.
+For this reason, oidentd attempts to switch to an unprivileged user
+automatically after starting up.
+
+Please note that oidentd needs to run as root on a small number of systems.
+On these systems, a warning is printed at startup and privileges are not
+dropped automatically.
+Your system is affected by this limitation if `oidentd --version` prints "Needs
+root access: Yes".
+
+## Default User
+
+By default, oidentd attempts to run as one of the following users, in order of
+preference.
+If a user does not exist, oidentd tries to use the next one.
+
+* oidentd
+* nobody
+
+If neither of the above users exists, oidentd switches to user ID 65534.
+
+## Default Group
+
+By default, oidentd attempts to run as one of the following groups, in order of
+preference.
+If a group does not exist, oidentd tries to use the next one.
+
+* oidentd
+* nobody
+* nogroup
+
+If none of the above groups exist, oidentd switches to group ID 65534.
+
+## Changing This Behavior
+
+The `--user` and `--group` options can be used to run oidentd as another user
+or group.
+oidentd refuses to start up if the user or group specified by either of these
+options does not exist, or if privileges cannot be dropped for some other
+reason.
diff --git a/doc/book/security/hiding-connections.md b/doc/book/security/hiding-connections.md
new file mode 100644
index 0000000..23f843d
--- /dev/null
+++ b/doc/book/security/hiding-connections.md
@@ -0,0 +1,58 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Hiding Connections"
+weight: 2
+---
+
+It is recommended to hide connections to any servers running on your machine to
+avoid disclosing unnecessary information.
+
+The recommended way to accomplish this is to hide all connections and only
+respond to queries for certain user accounts:
+
+{{< code >}}
+default {
+ default {
+ force hide
+ }
+}
+
+user "ryan" {
+ default {
+ force reply "ryan"
+ }
+}
+{{< /code >}}
+
+It is also possible to hide individual users' connections:
+
+{{< code >}}
+user "root" {
+ default {
+ force hide
+ }
+}
+
+user "http" {
+ default {
+ force hide
+ }
+}
+{{< /code >}}
+
+Alternatively, the [`random`][cap_random] and
+[`random_numeric`][cap_random_numeric] capabilities may be used to conceal
+users' real login names while still allowing the system administrator to
+identify who was responsible for a particular connection.
+See the [list of capabilities][caps] for more information.
+
+[caps]: {{% ref "../getting-started/capabilities" %}}
+[cap_random]: {{% ref "../getting-started/capabilities#random" %}}
+[cap_random_numeric]: {{% ref "../getting-started/capabilities#random-numeric" %}}
diff --git a/doc/book/security/identification-vs-authentication.md b/doc/book/security/identification-vs-authentication.md
new file mode 100644
index 0000000..2f62f40
--- /dev/null
+++ b/doc/book/security/identification-vs-authentication.md
@@ -0,0 +1,33 @@
+---
+# Copyright (c) 2018-2020 Janik Rabe
+#
+# Permission is granted to copy, distribute and/or modify this document
+# under the terms of the GNU Free Documentation License, Version 1.3
+# or any later version published by the Free Software Foundation;
+# with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+# A copy of the license is included in the file 'COPYING.DOC'
+
+title: "Identification vs. Authentication"
+weight: 3
+---
+
+The Ident protocol was designed for identification, not authentication.
+Please don't use it for access control.
+
+The primary purpose of the Ident protocol is to serve as an auditing and abuse
+prevention mechanism.
+For example, many {{< abbr "IRC" "Internet Relay Chat" >}} servers act as Ident
+clients, querying and publicly displaying users' Ident replies.
+This allows providers of {{< abbr "IRC" "Internet Relay Chat" >}} bouncers,
+shell accounts and other services to identify users abusing their systems and
+enables channel operators and network operators to remove individual users
+without excluding their entire host or network.
+
+Ident queries and replies are sent as plain text, with no encryption or
+authentication, and can be intercepted or modified by an attacker.
+In addition, it is not possible to prevent compromised or malicious hosts from
+[sending arbitrary Ident replies][cap-spoof].
+For these reasons, the Ident protocol is not suitable for authentication or
+access control.
+
+[cap-spoof]: {{% ref "../getting-started/capabilities#spoof" %}}