doc/manual/known-issues: init

We start this section with shortcomings of unsandboxed builds.

Fixes #1018.

Co-authored-by: eldritch horrors <pennae@lix.systems>
Change-Id: Ieb17e4340beab0c1197951813ae602de453a3fd9
Signed-off-by: Raito Bezarius <raito@lix.systems>

doc/manual/src/SUMMARY.md

@@ -40,6 +40,8 @@
   - [Verifying Build Reproducibility](advanced-topics/diff-hook.md)
   - [Using the `post-build-hook`](advanced-topics/post-build-hook.md)
   - [Pasta](advanced-topics/pasta.md)
+- [Known Issues](known-issues/known-issues.md)
+  - [Limitations around non-isolated builds](known-issues/non-isolated-build-limits.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/known-issues/known-issues.md

@@ -0,0 +1 @@
+This section lists known issues around Lix.

doc/manual/src/known-issues/non-isolated-build-limits.md

@@ -0,0 +1,21 @@
+# Limitations of non-isolated builds
+
+## What are non-isolated builds?
+
+In Lix, only builds done on Linux with `sandbox = true` and a functioning
+`pasta-path` are isolated from the rest of the system, all other builds are
+considered non-isolated to some degree.
+
+For example, running Lix with [Pasta](@docroot@/advanced-topics/pasta.md)
+disabled makes the host network visible to fixed-output derivations, reducing
+isolation somewhat.
+
+## Clean termination of non-isolated builds
+
+Non-isolated builds may not terminate cleanly in all cases due to limitations in Lix's process management.
+
+This occurs when a build keeps the build log file descriptor open past the end of the actual build. A common cause of this are background tasks that aren't properly terminated before the main build process exits, for example: HTTP servers run as part of a test suite.
+
+See [issue #1018](https://git.lix.systems/lix-project/lix/issues/1018) for an example.
+
+The only solution is to manually terminate leftover processes in your derivation, including during failure scenarios.