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 chosen 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 DPORTS TREE TO BUILD/INSTALL PACKAGES
342
343 In order to obtain a reasonably current snapshot of the dports tree, use
344 our repo:
345
346 cd /usr
347 make help
348 make dports-create
349
350 This tree can then be kept up to date with:
351
352 cd /usr
353 make dports-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.
395
1
2 DRAGONFLY 'Live CD' README.USB
3
4 When booting from 'Live CD', the USB subsystem is activated by the
5 default boot. This includes the primary USB, OHCI, EHCI and XHCI
6 drivers. On some systems it might be needed to not start the EHCI
7 driver (for USB 2.0) or XHCI driver (for USB 3.0) to be able to run
8 DragonFly. This is done by:
9
10 For EHCI
11 ========
12
13 - 'unset ehci_load' in loader prompt, or
14 - choosing 'safe mode' in boot prompt, or
15 - 'set hint.ehci.0.disabled=0' in /boot/loader.conf
16
17 For XHCI
18 ========
19
20 - 'unset xhci_load' in loader prompt, or
21 - choosing 'safe mode' in boot prompt, or
22 - 'set hint.xhci.0.disabled=0' in /boot/loader.conf
23