From d848daad94ea1750f7ec653a38f74c69ca8423d1 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Tue, 20 Aug 2013 17:11:22 +0200
Subject: [PATCH] Manual: Document how to deal with binary cache issues

---
 doc/manual/troubleshooting.xml | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
index fd43ff6b5611..c6e0a3a7888c 100644
--- a/doc/manual/troubleshooting.xml
+++ b/doc/manual/troubleshooting.xml
@@ -164,4 +164,35 @@ binary cache; otherwise, they cannot be repaired.</para>
 </section>
 
 
+<!--===============================================================-->
+
+<section><title>Nix network issues</title>
+
+<para>Nix uses a so-called <emphasis>binary cache</emphasis> to
+optimise building a package from source into downloading it as a
+pre-built binary.  That is, whenever a command like
+<command>nixos-rebuild</command> needs a path in the Nix store, Nix
+will try to download that path from the Internet rather than build it
+from source.  The default binary cache is
+<uri>http://cache.nixos.org/</uri>.  If this cache is unreachable, Nix
+operations may take a long time due to HTTP connection timeouts.  You
+can disable the use of the binary cache by adding <option>--option
+use-binary-caches false</option>, e.g.
+
+<screen>
+$ nixos-rebuild switch --option use-binary-caches false
+</screen>
+
+If you have an alternative binary cache at your disposal, you can use
+it instead:
+
+<screen>
+$ nixos-rebuild switch --option binary-caches http://my-cache.example.org/
+</screen>
+
+</para>
+
+</section>
+
+
 </chapter>