* Troubleshooting information on fixing a b0rked Berkeley DB database.

3 files changed, 45 insertions, 13 deletions

diff --git a/doc/manual/bugs.xml b/doc/manual/bugs.xml
index d21603559ddc..aa87e4b57048 100644
--- a/doc/manual/bugs.xml
+++ b/doc/manual/bugs.xml
@@ -15,18 +15,6 @@ generation 43 is created which is a descendant of 39, not 42.  So a
 rollback from 43 ought to go back to 39.  This is not currently
 implemented; generations form a linear sequence.</para></listitem>
 
-<listitem><para><emphasis>Build management.</emphasis> In principle it
-is already possible to do build management using Nix (by writing
-builders that perform appropriate build steps), but the Nix expression
-language is not yet powerful enough to make this pleasant (?).  The
-language should be extended with features from the <link
-xlink:href='http://www.cs.uu.nl/~eelco/maak/'>Maak build
-manager</link>.  Another interesting idea is to write a
-<command>make</command> implementation that uses Nix as a back-end to
-support <link
-xlink:href='http://www.research.att.com/~bs/bs_faq.html#legacy'>legacy</link>
-build files.</para></listitem>
-
 <listitem><para>For security, <command>nix-push</command> manifests
 should be digitally signed, and <command>nix-pull</command> should
 verify the signatures.  The actual NAR archives in the cache do not
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index 0a7ecdf0676d..5edc1cdaa2f7 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -681,7 +681,7 @@ deployment.</para>
 
 <!--######################################################################-->
 
-<refsection><title>Operation <option>--verify</option></title>
+<refsection xml:id='refsec-nix-store-verify'><title>Operation <option>--verify</option></title>
 
 <refsection>
   <title>Synopsis</title>
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
index 9a61205b7334..c0add7fddadc 100644
--- a/doc/manual/troubleshooting.xml
+++ b/doc/manual/troubleshooting.xml
@@ -33,6 +33,50 @@ $ rm __db.00*</screen>
 </section>
 
 
+<section><title>Berkeley DB gives weird error messages</title>
+
+<para>Symptom: you get error messages such as
+
+<screen>
+Berkeley DB message: Finding last valid log LSN: file: 1 offset 28
+Berkeley DB error: file validpaths (meta pgno = 0) has LSN [483][34721].
+Berkeley DB error: end of log is [1][28]
+Berkeley DB error: /nix/var/nix/db/validpaths: unexpected file type or format</screen>
+
+or other weird Berkeley DB errors, and they don’t away (i.e.,
+automatic recovery doesn’t work).  This may be the case after a system crash.</para>
+
+<para>Solution: first try to run <command>db_recover</command> and
+then <link linkend='refsec-nix-store-verify'><command>nix-store
+--verify</command></link>:
+
+<screen>
+$ db_recover -h /nix/var/nix/db
+$ nix-store --verify</screen>
+
+(Make sure that you have the right version of
+<command>db_recover</command>, namely, Berkeley DB 4.4 for Nix 0.10,
+and 4.5 for Nix 0.11.)</para>
+
+<para>If that doesn’t work, it’s time to bring out the big guns:
+
+<screen>
+$ cd /nix/var/nix
+$ cp -pr db db-backup  <lineannotation>(making a backup just in case)</lineannotation>
+$ cd db
+$ rm __db.* log*  <lineannotation>(removing the Berkeley DB environment)</lineannotation>
+$ mkdir tmp
+$ for i in *; do db_dump $i | (cd tmp &amp;&amp; db_load $i); done 
+<lineannotation>(ignore error messages about non-database files like “reserved”)</lineannotation>
+$ mv tmp/* .
+$ nix-store --verify</screen>
+
+</para>
+
+</section>
+
+
+
 <section><title>Collisions in <command>nix-env</command></title>
 
 <para>Symptom: when installing or upgrading, you get an error message such as