doc/manual: provide more information about Pasta and its shortcomings

As we saw actual users running into them throughout the debugging of
#920 and #1014.

It's best to document and point end users to this so they can take
measures for themselves.

Change-Id: I7d08407f4354055bf65fc6dd7d1624c5a9304402
Signed-off-by: Raito Bezarius <raito@lix.systems>

doc/manual/src/SUMMARY.md

@@ -39,6 +39,7 @@
   - [Tuning Cores and Jobs](advanced-topics/cores-vs-jobs.md)
   - [Verifying Build Reproducibility](advanced-topics/diff-hook.md)
   - [Using the `post-build-hook`](advanced-topics/post-build-hook.md)
+  - [Pasta](advanced-topics/pasta.md)
 - [Command Reference](command-ref/command-ref.md)
   - [Common Options](command-ref/opt-common.md)
   - [Common Environment Variables](command-ref/env-common.md)

doc/manual/src/advanced-topics/pasta.md

@@ -0,0 +1,19 @@
+# [Pasta](https://passt.top/passt/about/): a network sandbox for fixed-output derivations
+
+## Introduction
+
+This section only applies to **Linux systems** as Pasta is a Linux-only measure.
+
+Since [CVE-2025-46416](https://lix.systems/blog/2025-06-24-lix-cves/), the Lix project decided to adopt [Pasta](https://passt.top/passt/about/) for all fixed-output derivations, protecting against various attack vectors such as UNIX abstract domain sockets or more manipulation at the network layer from a malicious fixed-output derivation code.
+
+Pasta acts as a translation layer between a layer-2 network interface and layer-4 sockets (TCP, UDP, ICMP/ICMPv6 echo) on the host. It requires no special privileges and can serve as a alternative to [SLiRP](https://en.wikipedia.org/wiki/Slirp) which was used [by Guix to mitigate the same problem](https://codeberg.org/guix/guix/commit/fb42611b8f27960304db5a1c0d33b8371dcde2a8).
+
+## How to disable Pasta?
+
+It's sufficient to pass `pasta-path = ""` in your `/etc/nix/nix.conf` or on the command line `--pasta-path ""` of a Lix invocation.
+
+## Known issues surrounding Pasta
+
+- Only the first DNS server in `/etc/resolv.conf` is considered: failover is not possible.
+- [Reduced feature set compared to the Linux kernel](https://passt.top/passt/about/#features)
+- [Performance overhead in multi-gigabits contexts and IMIX MTUs](https://passt.top/passt/about/#performance_1)

doc/manual/src/installation/installing-docker.md

@@ -60,3 +60,10 @@ Then:
 ```console
 $ docker run -ti lix
 ```
+
+# Known issues
+
+Lix in Docker is very sensitive to **functional** DNS resolution if you are running with [Pasta protections](../advanced-topics/pasta.md) which are enabled by default since Lix 2.93.0 on most distributions.
+If you notice failure to download things, double check whether your **first** DNS entry in `/etc/resolv.conf` is functional.
+
+Lix with [Pasta protections](../advanced-topics/pasta.md) does not support failing over the next entries.