diff --git a/doc/manual/installation.xml b/doc/manual/installation.xml new file mode 100644 index 00000000000..fe3a1a7e72e --- /dev/null +++ b/doc/manual/installation.xml @@ -0,0 +1,241 @@ + + +Installation + + + + +
+ +Building the installation CD + +Instead of building an installation CD, you could just download +one from . If you want +(or need) to build it yourself: + + + + Make sure that you have a very + recent pre-release version of Nix installed (). + The NixOS Nix expressions frequently use bleading-edge features. If + you get any kind of expression evaluation error, try to upgrade your + Nix. + + Optional but strongly recommended (and currently + required for building the + x86_64 ISO): subscribe/pull from the Nixpkgs + channel to speed up building, i.e., + + +$ nix-channel --add http://nix.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable +$ nix-channel --update + + + + Check out NixOS from as + nixos. + + If you don’t already have Nixpkgs checkout, Check + out Nixpkgs from as + nixpkgs. + + In the directory nixos, make a + symbolic link pkgs to the pkgs + directory of the Nixpkgs tree, e.g., + + +$ ln -s nixpkgs/pkgs nixos/ + + + + Build the ISO image: + + +$ nix-build configuration/rescue-cd.nix -A rescueCD + + If everything goes well, you’ll end up with an ISO image in + ./result/iso/nixos.iso. + + Burn the ISO image + ./result/iso/nixos.iso onto a CD or DVD or + attach it to a CD-ROM drive in VMware. + + + + + +
+ + + + +
+ +Installation + + + + Boot from the CD. + + The CD contains a basic 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, since it will download + lots of stuff (such as source tarballs or Nixpkgs channel binaries). + 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 the following + commands: + + + + For partitioning: + fdisk. + + For initialising Ext2/Ext3 partitions: + mke2fs. Ext3 is recommended; use the + to create a journalled file system. It is + also recommended that you assign a unique symbolic label to the + file system using the option . This will make the + file system configuration independent from device + changes. + + For creating swap partitions: + mkswap. Again it’s recommended to assign a + label to the swap partition: . + + For creating LVM volumes, the LVM commands, e.g., + + +$ pvcreate /dev/sda1 /dev/sdb1 +$ vgcreate MyVolGroup /dev/sda1 /dev/sdb1 +$ lvcreate --size 2G --name bigdisk MyVolGroup +$ lvcreate --size 1G --name smalldisk MyVolGroup + + Possibly you’ll need to do initctl start + lvm after this (TODO: check whether this is + needed). + + For creating software RAID devices: + mdadm. + + Mount the target file system on + /mnt. + + The installation is declarative; you need to write + a description of the configuration that you want to be built and + activated. The configuration is specified in a Nix expression and + should be stored in + /etc/nixos/configuration.nix. See + /etc/nixos/nixos/configuration/examples for + example machine configurations. You can copy and edit one of + those (e.g., copy + /etc/nixos/nixos/configuration/examples/basic.nix + to /etc/nixos/configuration.nix). See for a list of the available configuration + options. The text editor nano is + available. + + In particular you need to specify a root file system in + and the target device for the Grub + boot loader in . + + More examples of NixOS configurations for some actual + machines can be found at . + + + + Do the installation: + + +$ nixos-install + + Cross fingers. + + If everything went well: + + +$ reboot + + You should now be able to boot into the installed NixOS. The Grub + boot menu shows a list of available + configurations (initially just one). Every time you + change the NixOS configuration, a new item appears in the menu. + This allows you to go back easily to another configuration if + something goes wrong. + + You should log in and change the root + password with passwd. + + + + + + + +
+ + + + + +
+ +Changing the configuration + +The file /etc/nixos/configuration.nix +contains the current configuration of your machine. Whenever you’ve +changed something to that file, or to the NixOS/Nixpkgs sources in +/etc/nixos/nixos and +/etc/nixos/nixpkgs, respectively, you should do + + +$ nixos-rebuild switch + +to build the new configuration, make it the default configuration for +booting, and try to effect the configuration in the running system +(e.g., by restarting system services). + +You can also do + + +$ nixos-rebuild test + +to build the configuration and switch the running system to it, but +without making it the boot default. So if (say) the configuration +locks up your machine, you can just reboot to get back to a working +configuration. + +There is also + + +$ nixos-rebuild boot + +to build the configuration and make it the boot default, but not +switch to it now (so it will only take effect after the next +reboot). + +Finally, you can do + + +$ nixos-rebuild build + +to build the configuration but nothing more. This is useful to see +whether everything compiles cleanly. + +
+ + + \ No newline at end of file diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml index 96368ed6876..51834234fb8 100644 --- a/doc/manual/manual.xml +++ b/doc/manual/manual.xml @@ -1,4 +1,5 @@ @@ -19,6 +20,21 @@ + + + Preface + + 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 + nix-dev@cs.uu.nl mailing list or on . + + + + diff --git a/doc/manual/options-to-docbook.xsl b/doc/manual/options-to-docbook.xsl index 71844cbd2b7..5f83cca474b 100644 --- a/doc/manual/options-to-docbook.xsl +++ b/doc/manual/options-to-docbook.xsl @@ -13,7 +13,7 @@ - + List of Options