nrelease - update README w/ HAMMER instructions etc
[dragonfly.git] / nrelease / root / README
1                             DRAGONFLY 'Live CD' README FILE
2
3     This CD/DVD/USB stick boots DragonFly BSD.  Basically what you get is a
4     full base system on the media with certain critical directories, such as
5     /tmp, remounted read-write using TMPFS.  Your existing hard drive is not
6     affected by booting this media.
7
8     DragonFly 'Live CD' can be used from either CD, DVD or USB stick, in the
9     following the media is called 'CD' for brevity (nothing is specific to the
10     CD media).  The DragonFly 'Live CD' is used for both trying out DragonFly,
11     installing DragonFly and for emergency repair of DragonFly systems.
12
13     NOTE!!! DRAGONFLY IS UNDERGOING DEVELOPMENT AND IS CONSIDERED
14     EXPERIMENTAL!  BSD RELATED EXPERIENCE IS RECOMMENDED WHEN USING
15     THIS CD.
16
17     If you just want to play with DragonFly and not mess with your hard disk,
18     this CD boots into a fully operational console-based system, though
19     without swap it should be noted that you are limited by available memory.
20     It is a good idea to test your hardware for compatibility from a CD boot
21     before spending time installing the dist on your hard disk.
22
23
24                             AUTOMATIC INSTALLATION
25
26     There are currently two installation tools available - the installer, and
27     rconfig.
28
29     The installer can be run with a text-based (curses) user interface
30     from the serial console or a VTY, and provides a straightforward method
31     for installing DragonFly on your HD.  To start it, just login with the
32     username 'installer'.
33
34     The installer can also be run with a web-based (CGI) user interface.
35     To set this up manually is a bit of work, but much of it can be automated
36     by writing a couple of lines into a configuration file on a floppy disk
37     or USB pendrive, and inserting or attaching that to the computer before
38     booting the CD.  See the file /etc/defaults/pfi.conf for more info.
39
40     rconfig is a client/server protocol which requires a server (typically on
41     the same network).  An example server setup can be found in
42     /usr/share/examples/rconfig.  If you have multiple machines you can setup
43     an installation script and run rconfig on a server and then install the
44     clients from CD boot with network connectivity (e.g. 'dhclient <if>')
45     and then, typically, 'rconfig -a'.
46
47     You can also just boot from the CD, login as 'root' to get a shell
48     prompt, copy the sample script to /tmp, edit, and run it directly
49     (assuming that blowing away your existing disk is ok).
50
51
52                                   CONSOLE OPERATION
53
54     The second stage boot (boot2) and third stage boot (loader) default
55     to dual serial & video console I/O.  You can direct the boot output
56     to just the serial port by creating the file /boot.config with the
57     line '-h', or to just the screen using '-V'.  If you wish to leave
58     boot2 in dual I/O mode but want the third stage to use just one or the
59     other, you can set the 'console' environment variable in /boot/loader.conf
60     to either 'vidconsole' or 'comconsole'.
61
62     The dual serial port operation might have to be disabled if you use
63     the serial port for things like UPSs.  Also note that by default
64     the CD will not run a login prompt on the serial port after booting is
65     complete.  This can be enabled by editing the 'ttyd0' line in /etc/ttys
66     after installation is complete.
67
68     Note that the kernel itself currently only supports one console or the
69     other.  If both are enabled, the kernel will use the video console or
70     the last one for which input was received.
71
72
73                                 MANUAL INSTALLATION
74
75     Manual installation of DragonFly onto an HD involves the following sequence
76     of commands.  You must be familiar with BSD style UNIX systems to do
77     installations manually.  The primary IDE hard drive is typically 'ad0',
78     if using AHCI, SILI or SCSI HD controller it is typically 'da0', and if
79     using USB HD controller it is typically 'da8'.
80     DragonFly is typically installed onto the first free slice (ad0s1 if disk
81     is empty, ad0s2 if your first slice contains another OS, etc).  Be careful
82     to substitute the correct disk and partition name in the steps below.
83
84     You need to decide which file system to use for DragonFly install: UFS or
85     HAMMER.  UFS is the classical BSD file system and HAMMER is a newer and
86     more feature rich file system, HAMMER needs 50GB space at minimum, see
87     'man HAMMER'.  The installation is somewhat different depending on the
88     file system used.
89
90         # OPTIONAL STEP: If your disk is already partitioned and you
91         # have a spare primary partition on which you want to install
92         # DragonFly, skip this step.  However, sometimes old boot
93         # blocks or cruft in the boot area can interfere with the
94         # initialization process.  A cure is to zero out the start of
95         # the disk before running fdisk.  Replace 'ad0' with the choosen disk.
96         #
97         # WARNING: This COMPLETELY WIPES and repartitions your hard drive.
98         #
99         dd if=/dev/zero of=/dev/ad0 bs=32k count=16
100         fdisk -I ad0
101         fdisk -B ad0
102
103         # If you didn't zero the disk as above, but have a spare slice
104         # whose partition type you want to change to DragonFly, use fdisk(8).
105
106         # This installs boot blocks onto the HD and verifies their
107         # installation.  See note just above the 'reboot' below for
108         # things to try if it does not boot from your HD.  If you
109         # already have a multi-OS bootloader installed you can skip
110         # this step.
111         #
112         boot0cfg -B ad0
113         boot0cfg -v ad0
114
115         # This creates an initial label on the chosen slice of the HD.  If
116         # you have problems booting you could try wiping the first 32 blocks
117         # of the slice with dd and then reinstalling the label.  Replace
118         # 'ad0s1' with the chosen slice.
119         #
120         # dd if=/dev/zero of=/dev/ad0s1 bs=32k count=16
121         disklabel -B -r -w ad0s1 auto
122
123         # Edit the label.  Create various standard partitions.  The typical
124         # configuration is:
125         #
126         # UFS (fstype 4.2BSD):
127         #       ad0s1a  768m            This will be your /
128         #       ad0s1b  4096m           This will be your swap
129         #       ad0s1c                  (leave alone)
130         #       ad0s1d  512m            This will be your /var
131         #       ad0s1e  512m            This will be your /tmp
132         #       ad0s1f  8192m           This will be your /usr (min 4096m)
133         #       ad0s1g  *               All remaining space to your /home
134         #
135         # HAMMER (fstype HAMMER):
136         #       ad0s1a  768m            This will be your /boot; UFS
137         #       ad0s1b  4096m           This will be your swap
138         #       ad0s1d  *               All remaining space to your /; HAMMER
139         #
140         # An example disklabel can be found in /etc/disklabel.ad0s1.
141         #
142         disklabel -e ad0s1
143
144         # Newfs (format) the various file systems.
145         #
146         # UFS:
147         # Softupdates is not normally enabled on the root file system because
148         # large kernel or world installs/upgrades can run it out of space due
149         # to softupdate's delayed bitmap freeing code.
150         #
151         newfs /dev/ad0s1a
152         newfs -U /dev/ad0s1d
153         newfs -U /dev/ad0s1e
154         newfs -U /dev/ad0s1f
155         newfs -U /dev/ad0s1g
156         #
157         # HAMMER:
158         newfs /dev/ad0s1a
159         newfs_hammer -L ROOT /dev/ad0s1d
160
161         # Mount the file systems.
162         #
163         # UFS:
164         mount /dev/ad0s1a /mnt
165         mkdir /mnt/var
166         mkdir /mnt/tmp
167         mkdir /mnt/usr
168         mkdir /mnt/home
169         mount /dev/ad0s1d /mnt/var
170         mount /dev/ad0s1e /mnt/tmp
171         mount /dev/ad0s1f /mnt/usr
172         mount /dev/ad0s1g /mnt/home
173         #
174         # HAMMER:
175         mount -t hammer /dev/ad0s1d /mnt
176         mkdir /mnt/boot
177         mount /dev/ad0s1a /mnt/boot
178         # Make HAMMER pseudo file systems (PFSs), and NULL mount them.
179         # All PFSs share all space in a HAMMER file system, but policy on how
180         # often to make snapshots, how long to keep them and general ability to
181         # delete them is per PFS.  Also mirroring (e.g. for backup) is done
182         # per PFS.  Typical setup is:
183         #
184         mkdir /mnt/pfs
185         hammer pfs-master /mnt/pfs/var
186         hammer pfs-master /mnt/pfs/var.crash
187         hammer pfs-master /mnt/pfs/tmp
188         hammer pfs-master /mnt/pfs/usr
189         hammer pfs-master /mnt/pfs/usr.obj
190         hammer pfs-master /mnt/pfs/home
191         mkdir /mnt/var
192         mkdir /mnt/tmp
193         mkdir /mnt/usr
194         mkdir /mnt/home
195         mount -t null /mnt/pfs/var /mnt/var
196         mount -t null /mnt/pfs/tmp /mnt/tmp
197         mount -t null /mnt/pfs/usr /mnt/usr
198         mount -t null /mnt/pfs/home /mnt/home
199         mkdir /mnt/var/crash
200         mkdir /mnt/usr/obj
201         mount -t null /mnt/pfs/var.crash /mnt/var/crash
202         mount -t null /mnt/pfs/usr.obj /mnt/usr/obj
203         # add root file system to /boot/loader.conf
204         echo 'vfs.root.mountfrom="hammer:ad0s1d"' >> /mnt/boot/loader.conf
205
206
207         # UFS & HAMMER:
208         # Copy the CD onto the target.  cpdup won't cross mount boundaries
209         # on the source (e.g. the TMPFS remounts) or destination, so it takes
210         # a few commands.
211         #
212         # Note that /etc contains the config files used for booting from the
213         # CD itself, and /etc.hdd contains those for booting off a
214         # hard disk.  So it's the latter that you want to copy to /mnt/etc.
215         #
216         cpdup / /mnt
217         cpdup /boot /mnt/boot
218         cpdup /var /mnt/var
219         cpdup /etc.hdd /mnt/etc
220         cpdup /usr /mnt/usr
221
222         # Cleanup.  Also, with /tmp a partition it is usually reasonable
223         # to make /var/tmp a softlink to /tmp.
224         #
225         chmod 1777 /mnt/tmp
226         rm -rf /mnt/var/tmp
227         ln -s /tmp /mnt/var/tmp
228
229         # Edit /mnt/etc/fstab to reflect the new mounts.  An example fstab
230         # file based on the above parameters exists as /mnt/etc/fstab.example
231         # which you can rename to /mnt/etc/fstab.
232         #
233         mv /mnt/etc/fstab.example /mnt/etc/fstab
234         vi /mnt/etc/fstab
235
236         # Save out your disklabel just in case.  It's a good idea to save
237         # it to /etc so you can get at it from your backups.  You do intend
238         # to backup your system, yah? :-)  (This isn't critical but it's a
239         # good idea).
240         #
241         disklabel ad0s1 > /mnt/etc/disklabel.ad0s1
242
243
244                         MISC CLEANUPS BEFORE REBOOTING
245
246     Once you've duplicated the CD onto your HD you have to make some edits
247     so the system boots properly from your HD.  Primarily you must remove
248     or edit /mnt/boot/loader.conf, which exists on the CD to tell the kernel
249     to mount the CD's root partition.
250
251         # Remove or edit /mnt/boot/loader.conf so the kernel does not try
252         # to obtain the root file system from the CD, and remove the other
253         # cruft that was sitting on the CD that you don't need on the HD.
254         #
255         rm /mnt/boot/loader.conf
256         rm /mnt/README* /mnt/autorun* /mnt/index.html /mnt/dflybsd.ico
257         rm /mnt/boot.catalog
258         rm -r /mnt/rr_moved
259
260     At this point it should be possible to reboot.  The CD may be locked
261     since it is currently mounted.  To remove the CD, type 'halt' instead
262     of 'reboot', wait for the machine to halt, then the CD door should be
263     unlocked.  Remove the CD and hit any key to reboot.
264
265     Be careful of the CD drawer closing on you if you try to remove the CD
266     while the machine is undergoing a reboot or reset.
267
268     WARNING: Do not just hit reset; the kernel may not have written out
269     all the pending data to your HD.  Either unmount the HD partitions
270     or type halt or reboot.
271
272         # halt
273         (let the machine halt)
274         (remove CD when convenient, be careful of the CD drawer closing on you)
275         (hit any key to reboot)
276
277
278                                     THE ACPI ISSUE
279
280     You will notice in the boot menu that you can choose to boot with or
281     without ACPI.  ACPI is an infrastructure designed to allow an operating
282     system to configure hardware devices associated with the system.
283     Unfortunately, as usual, PC BIOS makers have royally screwed up the
284     standard and ACPI is as likely to hurt as it is to help.  Worse, some
285     PCs cannot be booted without it, so there is no good 'default' choice.
286
287     The system will use ACPI by default.  You can disable it in the default
288     boot by adding the line 'hint.acpi.0.disabled=1' in /boot/loader.conf.
289     If you boot without hitting any menu options the system will boot without
290     ACPI.  To boot without ACPI no matter what, place 'unset acpi_load' in
291     our /boot/loader.conf instead.  This is not recommended.
292
293
294                         IF YOU HAVE PROBLEMS BOOTING FROM HD
295
296     There are a couple of things to try.  Try booting from the CD again and
297     use boot0cfg to turn off packet mode (boot0cfg -o nopacket ad0).  If you
298     can select CHS or LBA mode in your BIOS, try changing the mode to LBA.
299     Also try booting with and without ACPI (option 1 or 2 in the boot menu).
300
301     Once you have a working HD based system you can clean up /etc/rc.conf
302     to enable things like cron, sendmail, setup your networking, and so
303     forth.  If 'ifconfig' does not show your networking device you could
304     try to kldload it from /boot/kernel.  With a recognized network device
305     you can ifconfig its IP address or, if you have a DHCP server on your
306     network, use 'dhclient <interfacename>' to obtain an IP address from
307     the network.
308
309
310             USING GIT TO OBTAIN A SOURCE TREE AND DOING BUILDWORLDS
311
312     Instructions on how to obtain and maintain DragonFly source code using
313     git are in the development(7) manual page.
314
315     To upgrade a DragonFly system from sources you run the following
316     sequence:
317
318     cd /usr/src
319     make buildworld
320     make KERNCONF=<KERNELNAME> buildkernel
321     make KERNCONF=<KERNELNAME> installkernel
322     make installworld
323
324     You will also want to run the 'upgrade' target to upgrade your /etc
325     and the rest of your system.  The upgrade target is aware of stale
326     files created by older DragonFly installations and should delete them
327     automatically.
328
329     make upgrade
330
331     See the build(7) manual page for further information.
332
333     Once you've done a full build of the world and kernel you can do
334     incremental upgrades of either by using the 'quickworld' and
335     'quickkernel' targets instead of 'buildworld' and 'buildkernel'.  If
336     you have any problems with the quick targets, try updating your repo
337     first, and then a full buildworld and buildkernel as shown above, before
338     asking for help.
339
340
341                 OBTAINING A PKGSRC TREE TO BUILD/INSTALL PACKAGES
342
343     In order to obtain a reasonably current snapshot of the pkgsrc tree, use
344     our repo:
345
346     cd /usr
347     make help
348     make pkgsrc-create
349
350     This tree can then be kept up to date with:
351
352     cd /usr
353     make pkgsrc-update
354
355
356                         EMERGENCY RECOVERY FROM THE 'Live CD'
357
358     Lets say you blew up your kernel or something else in / and you need to
359     boot the 'Live CD' to fix it.  Remember that you have a fully operational
360     system when booting the 'Live CD', but that you have to fsck and mount your
361     hard drive (typically onto /mnt) to get at the contents of your HD.
362
363     Your HD is typically an IDE hard drive, so the device is typically 'ad0',
364     if using AHCI, SILI or SCSI HD controller it is typically 'da0', and if
365     using USB HD controller it is typically 'da8'.  Steps below will use 'ad0',
366     be careful to substitute the correct disk name below.
367
368     DragonFly is typically on the first slice, which is /dev/ad0s1.  For UFS
369     setup the root partition is always in partition 'a', which is /dev/ad0s1a.
370     For HAMMER setup the typical setup is that boot partition is partition 'a',
371     and root partition is partition 'd'.
372
373     # UFS:
374     # fsck root before trying to mount it.
375     fsck /dev/ad0s1a
376     # mount root read-write onto /mnt
377     mount /dev/ad0s1a /mnt
378     #
379     # HAMMER:
380     # fsck boot before trying to mount it.
381     fsck /dev/ad0s1a
382     # mount root read-write onto /mnt
383     mount -t hammer /dev/ad0s1d /mnt
384     # mount boot read-write onto /mnt/boot
385     mount /dev/ad0s1a /mnt/boot
386     #
387     # copy files from the CD as appropriate to make it possible to boot
388     # from your HD again.  Note that /mnt/boot/kernel/kernel may be
389     # flags-protected.
390     chflags noschg /mnt/boot/kernel/kernel
391     cp /boot/kernel/* /mnt/boot/kernel
392
393     If you want to mount other partitions from your HD but have forgotten
394     what they are, simply cat /mnt/etc/fstab after mounting the root partition.