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