* Readme is obsolete now.

svn path=/nixos/trunk/; revision=7870
This commit is contained in:
Eelco Dolstra 2007-02-06 21:38:59 +00:00
parent 5aed111620
commit 56f813a0fe
3 changed files with 78 additions and 143 deletions

142
README
View File

@ -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.

View File

@ -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" />

View File

@ -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>