2 files changed, 37 insertions, 0 deletions
diff --git a/nixos/doc/manual/development/debugging-nixos-tests.xml b/nixos/doc/manual/development/debugging-nixos-tests.xml
new file mode 100644
index 000000000000..0adf1293f7a3
--- /dev/null
+++ b/nixos/doc/manual/development/debugging-nixos-tests.xml
@@ -0,0 +1,36 @@
+<section xmlns="http://docbook.org/ns/docbook"
+        xmlns:xlink="http://www.w3.org/1999/xlink"
+        xmlns:xi="http://www.w3.org/2001/XInclude"
+        version="5.0"
+        xml:id="sec-debugging-nixos-tests">
+ <title>Debugging NixOS tests</title>
+
+ <para>
+  Tests may fail and infrastructure offers access to inspect machine state.
+ </para>
+
+ <para>
+  To prevent test from stopping and cleaning up, insert a sleep command:
+ </para>
+
+<programlisting>
+$machine->succeed("sleep 84000");
+</programlisting>
+
+ <para>
+  As soon as machine starts run as root:
+ </para>
+
+<programlisting>
+nix-shell -p socat --run "socat STDIO,raw,echo=0,escape=0x11 UNIX:/tmp/nix-build-vm-test-run-*.drv-0/vm-state-machine/backdoor"
+</programlisting>
+
+ <para>
+  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.
+ </para>
+ 
+</section>
diff --git a/nixos/doc/manual/development/nixos-tests.xml b/nixos/doc/manual/development/nixos-tests.xml
index 2695082e3867..d068887200a9 100644
--- a/nixos/doc/manual/development/nixos-tests.xml
+++ b/nixos/doc/manual/development/nixos-tests.xml
@@ -16,4 +16,5 @@ xlink:href="https://github.com/NixOS/nixpkgs/tree/master/nixos/tests">nixos/test
  <xi:include href="writing-nixos-tests.xml" />
  <xi:include href="running-nixos-tests.xml" />
  <xi:include href="running-nixos-tests-interactively.xml" />
+ <xi:include href="debugging-nixos-tests.xml" />
 </chapter>