nrelease - update README w/ HAMMER instructions etc
[dragonfly.git] / nrelease / root / README
CommitLineData
4a08b684 1 DRAGONFLY 'Live CD' README FILE
b816f770 2
4a08b684
TN
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.
b816f770 12
b6a0a5cf
MD
13 NOTE!!! DRAGONFLY IS UNDERGOING DEVELOPMENT AND IS CONSIDERED
14 EXPERIMENTAL! BSD RELATED EXPERIENCE IS RECOMMENDED WHEN USING
4a08b684 15 THIS CD.
b816f770
MD
16
17 If you just want to play with DragonFly and not mess with your hard disk,
4a08b684 18 this CD boots into a fully operational console-based system, though
b816f770 19 without swap it should be noted that you are limited by available memory.
87c240fe
MD
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
b816f770
MD
23
24 AUTOMATIC INSTALLATION
25
312e6f1d
CP
26 There are currently two installation tools available - the installer, and
27 rconfig.
89e4f808 28
312e6f1d
CP
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
4a08b684 38 booting the CD. See the file /etc/defaults/pfi.conf for more info.
89e4f808
MD
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
87c240fe
MD
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
4a08b684 44 clients from CD boot with network connectivity (e.g. 'dhclient <if>')
89e4f808 45 and then, typically, 'rconfig -a'.
87c240fe 46
89e4f808
MD
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).
87c240fe
MD
50
51
52 CONSOLE OPERATION
b816f770 53
87c240fe 54 The second stage boot (boot2) and third stage boot (loader) default
4a08b684 55 to dual serial & video console I/O. You can direct the boot output
87c240fe
MD
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
4a08b684 60 to either 'vidconsole' or 'comconsole'.
b816f770 61
87c240fe
MD
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
4a08b684
TN
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
87c240fe
MD
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
ba5e7b2f 72
87c240fe
MD
73 MANUAL INSTALLATION
74
75 Manual installation of DragonFly onto an HD involves the following sequence
b816f770 76 of commands. You must be familiar with BSD style UNIX systems to do
4a08b684
TN
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.
dae36ee2
MD
89
90 # OPTIONAL STEP: If your disk is already partitioned and you
91 # have a spare primary partition on which you want to install
4a08b684 92 # DragonFly, skip this step. However, sometimes old boot
dae36ee2
MD
93 # blocks or cruft in the boot area can interfere with the
94 # initialization process. A cure is to zero out the start of
4a08b684 95 # the disk before running fdisk. Replace 'ad0' with the choosen disk.
dae36ee2
MD
96 #
97 # WARNING: This COMPLETELY WIPES and repartitions your hard drive.
572e6852
MD
98 #
99 dd if=/dev/zero of=/dev/ad0 bs=32k count=16
fb017d4e
CP
100 fdisk -I ad0
101 fdisk -B ad0
b816f770 102
dae36ee2 103 # If you didn't zero the disk as above, but have a spare slice
4a08b684 104 # whose partition type you want to change to DragonFly, use fdisk(8).
dae36ee2 105
4a08b684 106 # This installs boot blocks onto the HD and verifies their
b6a0a5cf 107 # installation. See note just above the 'reboot' below for
dae36ee2
MD
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.
b6a0a5cf 111 #
b816f770
MD
112 boot0cfg -B ad0
113 boot0cfg -v ad0
114
dae36ee2 115 # This creates an initial label on the chosen slice of the HD. If
b816f770 116 # you have problems booting you could try wiping the first 32 blocks
dae36ee2
MD
117 # of the slice with dd and then reinstalling the label. Replace
118 # 'ad0s1' with the chosen slice.
b816f770
MD
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
ba5e7b2f 124 # configuration is:
b816f770 125 #
4a08b684
TN
126 # UFS (fstype 4.2BSD):
127 # ad0s1a 768m This will be your /
128 # ad0s1b 4096m This will be your swap
b816f770 129 # ad0s1c (leave alone)
4a08b684
TN
130 # ad0s1d 512m This will be your /var
131 # ad0s1e 512m This will be your /tmp
b816f770 132 # ad0s1f 8192m This will be your /usr (min 4096m)
0dab2a93 133 # ad0s1g * All remaining space to your /home
b816f770 134 #
4a08b684
TN
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 #
ba5e7b2f 140 # An example disklabel can be found in /etc/disklabel.ad0s1.
4e04bc29 141 #
b816f770
MD
142 disklabel -e ad0s1
143
4a08b684
TN
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.
b816f770
MD
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
4a08b684
TN
156 #
157 # HAMMER:
158 newfs /dev/ad0s1a
159 newfs_hammer -L ROOT /dev/ad0s1d
b816f770 160
4a08b684 161 # Mount the file systems.
b816f770 162 #
4a08b684 163 # UFS:
b816f770
MD
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
4a08b684
TN
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.
21aa02d0
CP
211 #
212 # Note that /etc contains the config files used for booting from the
4a08b684 213 # CD itself, and /etc.hdd contains those for booting off a
21aa02d0
CP
214 # hard disk. So it's the latter that you want to copy to /mnt/etc.
215 #
b816f770 216 cpdup / /mnt
4a08b684 217 cpdup /boot /mnt/boot
b816f770 218 cpdup /var /mnt/var
21aa02d0 219 cpdup /etc.hdd /mnt/etc
a3e78356 220 cpdup /usr /mnt/usr
b816f770 221
7bd4a647 222 # Cleanup. Also, with /tmp a partition it is usually reasonable
ba5e7b2f 223 # to make /var/tmp a softlink to /tmp.
7bd4a647
MD
224 #
225 chmod 1777 /mnt/tmp
226 rm -rf /mnt/var/tmp
227 ln -s /tmp /mnt/var/tmp
228
b816f770
MD
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
ba5e7b2f 236 # Save out your disklabel just in case. It's a good idea to save
4e04bc29 237 # it to /etc so you can get at it from your backups. You do intend
ba5e7b2f 238 # to backup your system, yah? :-) (This isn't critical but it's a
4e04bc29 239 # good idea).
4a08b684 240 #
4e04bc29
MD
241 disklabel ad0s1 > /mnt/etc/disklabel.ad0s1
242
87c240fe
MD
243
244 MISC CLEANUPS BEFORE REBOOTING
245
b816f770
MD
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
dae36ee2
MD
248 or edit /mnt/boot/loader.conf, which exists on the CD to tell the kernel
249 to mount the CD's root partition.
b816f770 250
87c240fe 251 # Remove or edit /mnt/boot/loader.conf so the kernel does not try
4a08b684 252 # to obtain the root file system from the CD, and remove the other
4e04bc29 253 # cruft that was sitting on the CD that you don't need on the HD.
b816f770
MD
254 #
255 rm /mnt/boot/loader.conf
e3a14b1f 256 rm /mnt/README* /mnt/autorun* /mnt/index.html /mnt/dflybsd.ico
0dab2a93
MD
257 rm /mnt/boot.catalog
258 rm -r /mnt/rr_moved
b816f770
MD
259
260 At this point it should be possible to reboot. The CD may be locked
87c240fe
MD
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.
b816f770 267
ba5e7b2f 268 WARNING: Do not just hit reset; the kernel may not have written out
a3e78356 269 all the pending data to your HD. Either unmount the HD partitions
87c240fe 270 or type halt or reboot.
a3e78356 271
87c240fe
MD
272 # halt
273 (let the machine halt)
b816f770 274 (remove CD when convenient, be careful of the CD drawer closing on you)
87c240fe
MD
275 (hit any key to reboot)
276
277
278 THE ACPI ISSUE
279
4a08b684 280 You will notice in the boot menu that you can choose to boot with or
87c240fe 281 without ACPI. ACPI is an infrastructure designed to allow an operating
ba5e7b2f
CP
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.
87c240fe
MD
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
b816f770 295
73bc901d
SW
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).
dae36ee2 300
b816f770
MD
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
4a08b684 304 try to kldload it from /boot/kernel. With a recognized network device
b816f770
MD
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
513aa0c6 307 the network.
b816f770 308
ba5e7b2f 309
a700883c
SW
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
9c13f47c
MD
318 cd /usr/src
319 make buildworld
4a08b684
TN
320 make KERNCONF=<KERNELNAME> buildkernel
321 make KERNCONF=<KERNELNAME> installkernel
9c13f47c
MD
322 make installworld
323
a700883c
SW
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.
9c13f47c 339
ba5e7b2f 340
cacc9236
SW
341 OBTAINING A PKGSRC TREE TO BUILD/INSTALL PACKAGES
342
343 In order to obtain a reasonably current snapshot of the pkgsrc tree, use
4a08b684 344 our repo:
cacc9236 345
4a08b684
TN
346 cd /usr
347 make help
348 make pkgsrc-create
cacc9236 349
4a08b684 350 This tree can then be kept up to date with:
cacc9236 351
4a08b684
TN
352 cd /usr
353 make pkgsrc-update
cacc9236
SW
354
355
4a08b684 356 EMERGENCY RECOVERY FROM THE 'Live CD'
9c13f47c
MD
357
358 Lets say you blew up your kernel or something else in / and you need to
4a08b684
TN
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
9c13f47c
MD
361 hard drive (typically onto /mnt) to get at the contents of your HD.
362
4a08b684
TN
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.
9c13f47c 367
4a08b684
TN
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.
9c13f47c
MD
375 fsck /dev/ad0s1a
376 # mount root read-write onto /mnt
377 mount /dev/ad0s1a /mnt
4a08b684
TN
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 #
9c13f47c 387 # copy files from the CD as appropriate to make it possible to boot
4a08b684
TN
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
9c13f47c
MD
392
393 If you want to mount other partitions from your HD but have forgotten
4a08b684 394 what they are, simply cat /mnt/etc/fstab after mounting the root partition.