Commit | Line | Data |
---|---|---|
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 | |
bbb35c81 | 95 | # the disk before running fdisk. Replace 'ad0' with the chosen 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 | |
45fa0bf8 | 341 | OBTAINING A DPORTS TREE TO BUILD/INSTALL PACKAGES |
cacc9236 | 342 | |
45fa0bf8 | 343 | In order to obtain a reasonably current snapshot of the dports tree, use |
4a08b684 | 344 | our repo: |
cacc9236 | 345 | |
4a08b684 TN |
346 | cd /usr |
347 | make help | |
45fa0bf8 | 348 | make dports-create |
cacc9236 | 349 | |
4a08b684 | 350 | This tree can then be kept up to date with: |
cacc9236 | 351 | |
4a08b684 | 352 | cd /usr |
45fa0bf8 | 353 | make dports-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. |