* Readme is obsolete now.

svn path=/nixos/trunk/; revision=7870

3 files changed, 78 insertions, 143 deletions

diff --git a/README b/README
index ecb67a871ae..acb8af73c4d 100644
--- a/README
+++ b/README
@@ -1,139 +1,5 @@
-*** Building the installation CD ***
-
-(Or just grab an ISO from http://nix.cs.uu.nl/dist/nix/.)
-
-- Make sure that you have a very recent Nix.
-
-- Pull from the Nixpkgs channel to speed up building.
-
-- Check out https://svn.cs.uu.nl:12443/repos/trace/nixos/trunk/.
-
-- Make a symbolic link called "pkgs" to the location of Nixpkgs.
-
-- Build the ISO image:
-
-  $ nix-build configuration/rescue-cd.nix -A rescueCD
-
-  This gives you an image in result/iso/nixos.iso.
-
-- Burn the ISO image or attach it to a CD-ROM drive in VMware.
-
-
-*** Installation ***
-
-- Boot from the CD.
-
-- The CD contains a pretty complete NixOS installation.  When it's
-  finished booting, it should have detected most of your hardware and
-  brought up networking (check ifconfig).  Networking is necessary for
-  the installer.  It's best if you have a DHCP server on your
-  network.  Otherwise configure manually.
-
-- Login as "root", empty password.
-
-- The NixOS installer doesn't do any partitioning or formatting yet,
-  so you need to that yourself.  Use "fdisk", "mkfs.ext2" and "tune2fs".
-
-- Mount the target root device, e.g., under /mnt.
-
-- Unpack the NixOS and Nixpkgs sources:
-
-  $ tar xf /nixos.tar.bz2
-  $ tar xf /nixpkgs.tar.bz2
-  $ ln -s nixpkgs-*/pkgs .
-
-  (TODO: do this automatically.)
-
-- The installation is declarative; you need to make a description of
-  the configuration that is to be built and activated.  The
-  configuration is specified in a Nix expression.  See
-  configuration/examples for example machine configurations.  You can
-  copy and edit one of those (e.g., configuration/examples/basic.nix
-  to my-config.nix).  See system/options.nix for available
-  configuration settings.  The text editor "nano" is available.
-
-  In particular you need to specify boot.rootDevice and
-  boot.grubDevice for the devices where the OS and Grub are to be
-  installed, respectively.
-
-- Do the installation:
-
-  $ nixos-install.sh ROOTDIR . my-config.nix
-
-  where ROOTDIR is the mount point of the target root device (i.e.,
-  boot.rootDevice in your configuration).
-
-- If everything went well:
-
-  $ reboot
-
-  You should now be able to boot into the installed NixOS.
-
-
-*** Updating NixOS ***
-
-- In NixOS, login as root, then do
-
-  $ checkout-nixos.sh  # !!! should be added to the installation
-
-  This gives you a working copy of NixOS and NixPkgs in nixos/ and
-  nixpkgs/, respectively.  You only need to do this once; you can use
-  "svn up" afterwards.
-
-- The system configuration is in /etc/nixos/configuration.nix.
-
-- To upgrade to a new configuration:
-
-  $ cd nixos
-  $ ./upgrade.sh
-
-  The new configuration is activated immediately (e.g., services may
-  be restarted if necessary), but some changes may require a reboot.
-
-- You can also test a new configuration:
-
-  $ cd nixos
-  $ ./test.sh
-
-  This is like ./upgrade.sh, only the new configuration won't be
-  installed in the system profile so the system will continue to boot
-  from the previous configuration.
-
-
-
-*** Troubleshooting ***        
-
-
-To get a Stage 1 shell:
-
-- Add "debug1" to the kernel command line.
-
-
-To switch to maintenance mode:
-
-  $ shutdown now
-
-To get out of maintenance mode:
-
-  $ initctl emit startup 
-
-
-
-*** Development ***
-
-- Building specific parts of NixOS:
-
-  $ nix-build system/system.nix \
-      --arg configuration "import /etc/nixos/configuration.nix" \
-      -A ATTR
-
-  where ATTR is an attribute in system/system.nix (e.g., bootStage1).
-
-- Testing the installer:
-
-  $ nix-build configuration/rescue-cd.nix -A system.nixosInstall
-  $ dd if=/dev/zero of=diskimage seek=2G count=0 bs=1
-  $ yes | mke2fs -j diskimage
-  $ mount -o loop diskimage /mnt
-  $ ./result/bin/nixos-install
+*** NixOS ***
 
+NixOS is a Linux distribution based on the purely functional package
+management system Nix.  More information can be found at
+http://nix.cs.uu.nl/nixos and in the manual in doc/manual.
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 52313de1d8d..65c2a81bb90 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -24,11 +24,15 @@
   <preface>
     <title>Preface</title>
 
-    <para>This manual is very sketchy.  It gives basic information on
-    how to get NixOS up and running, but since NixOS is very much a
-    work in progress, you are likely to encounter problems here and
-    there.  Extensive familiarity with Linux is recommended.  If you
-    encounter problems, please report them on the
+    <para>This manual describes NixOS, a Linux distribution based on
+    the purely functional package management system Nix.</para>
+    
+    <para>NixOS is rather bleeding edge, and this manual is
+    correspondingly sketchy and quite possibly out of date.  It gives
+    basic information on how to get NixOS up and running, but since
+    NixOS is very much a work in progress, you are likely to encounter
+    problems here and there.  Extensive familiarity with Linux is
+    recommended.  If you encounter problems, please report them on the
     <literal>nix-dev@cs.uu.nl</literal> mailing list or on <link
     xlink:href="irc://irc.freenode.net/#trace" />.</para>
     
@@ -36,6 +40,7 @@
   
 
   <xi:include href="installation.xml" />
+  <xi:include href="troubleshooting.xml" />
   <xi:include href="development.xml" />
   <xi:include href="options-db.xml" />
 
diff --git a/doc/manual/troubleshooting.xml b/doc/manual/troubleshooting.xml
new file mode 100644
index 00000000000..66de9795b59
--- /dev/null
+++ b/doc/manual/troubleshooting.xml
@@ -0,0 +1,64 @@
+<chapter xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<title>Troubleshooting</title>
+
+
+<section>
+  
+<title>Debugging the boot process</title>
+
+<para>To get a Stage 1 shell (i.e., a shell in the initial ramdisk),
+add <literal>debug1</literal> to the kernel command line.  The shell
+gets started before anything useful has been done.  That is, no
+modules have been loaded and no file systems have been mounted, except
+for <filename>/proc</filename> and <filename>/sys</filename>.</para>
+
+<para>To get a Stage 2 shell (i.e., a shell in the actual root file
+system), add <literal>debug2</literal> to the kernel command
+line.  This shell is started right after stage 1 calls the stage 2
+<literal>init</literal> script, so the root file system is there but
+no services have been started.</para>
+
+</section>
+
+
+
+<section>
+  
+<title>Safe mode</title>
+
+<para>If the hardware autodetection (in
+<filename>upstart-jobs/hardware-scan</filename>) causes problems, add
+<literal>safemode</literal> to the kernel command line.  This will
+disable auto-loading of modules for your PCI devices.  However, you
+will probably need to explicitly add modules to
+<option>boot.extraKernelModules</option> to get network support
+etc.</para>
+
+</section>
+
+
+<section>
+  
+<title>Maintenance mode</title>
+
+<para>You can go to maintenance mode by doing
+
+<screen>
+$ shutdown now</screen>
+
+This will eventually give you a single-user root shell.
+
+To get out of maintenance mode, do
+
+<screen>
+$ initctl emit startup</screen>
+
+</para>
+
+</section>
+
+
+
+</chapter>