convert ln to ${LN}
[dragonfly.git] / nrelease / root / README
CommitLineData
b816f770
MD
1 DRAGONFLY CDROM README FILE
2
3 This CDROM boots DragonFly BSD. Basically what you get is a full base
4 system on CD with certain critical directories, such as /tmp, remounted
ba5e7b2f 5 read-write using MFS. Your existing hard drive is not affected by
b816f770
MD
6 booting this CDROM.
7
b6a0a5cf
MD
8 NOTE!!! DRAGONFLY IS UNDERGOING DEVELOPMENT AND IS CONSIDERED
9 EXPERIMENTAL! BSD RELATED EXPERIENCE IS RECOMMENDED WHEN USING
10 THIS CDROM.
b816f770
MD
11
12 If you just want to play with DragonFly and not mess with your hard disk,
13 this CDROM boots into a fully operational console-based system, though
14 without swap it should be noted that you are limited by available memory.
87c240fe
MD
15 It is a good idea to test your hardware for compatibility from a CD boot
16 before spending time installing the dist on your hard disk.
17
b816f770
MD
18
19 AUTOMATIC INSTALLATION
20
312e6f1d
CP
21 There are currently two installation tools available - the installer, and
22 rconfig.
89e4f808 23
312e6f1d
CP
24 The installer can be run with a text-based (curses) user interface
25 from the serial console or a VTY, and provides a straightforward method
26 for installing DragonFly on your HD. To start it, just login with the
27 username 'installer'.
28
29 The installer can also be run with a web-based (CGI) user interface.
30 To set this up manually is a bit of work, but much of it can be automated
31 by writing a couple of lines into a configuration file on a floppy disk
32 or USB pendrive, and inserting or attaching that to the computer before
33 booting the CDROM. See the file /etc/defaults/pfi.conf for more info.
89e4f808
MD
34
35 rconfig is a client/server protocol which requires a server (typically on
36 the same network). An example server setup can be found in
87c240fe
MD
37 /usr/share/examples/rconfig. If you have multiple machines you can setup
38 an installation script and run rconfig on a server and then install the
39 clients from CD boot with network connectivity (e.g. dhclient <blah>)
89e4f808 40 and then, typically, 'rconfig -a'.
87c240fe 41
89e4f808
MD
42 You can also just boot from the CD, login as 'root' to get a shell
43 prompt, copy the sample script to /tmp, edit, and run it directly
44 (assuming that blowing away your existing disk is ok).
87c240fe
MD
45
46
47 CONSOLE OPERATION
b816f770 48
87c240fe 49 The second stage boot (boot2) and third stage boot (loader) default
89e4f808
MD
50 to dual serial & video console I/O. The system will also throw a login
51 prompt up on ttyd0 by default. You can direct the boot output
87c240fe
MD
52 to just the serial port by creating the file /boot.config with the
53 line '-h', or to just the screen using '-V'. If you wish to leave
54 boot2 in dual I/O mode but want the third stage to use just one or the
55 other, you can set the 'console' environment variable in /boot/loader.conf
56 to either 'console=vidconsole' or 'console=comconsole'.
b816f770 57
87c240fe
MD
58 The dual serial port operation might have to be disabled if you use
59 the serial port for things like UPSs. Also note that by default
60 the CD will run a login prompt on the serial port after booting is
61 complete. This can be disabled by editing the 'ttyd0' line in /etc/ttys
62 after installation is complete.
63
64 Note that the kernel itself currently only supports one console or the
65 other. If both are enabled, the kernel will use the video console or
66 the last one for which input was received.
67
ba5e7b2f 68
87c240fe
MD
69 MANUAL INSTALLATION
70
71 Manual installation of DragonFly onto an HD involves the following sequence
b816f770
MD
72 of commands. You must be familiar with BSD style UNIX systems to do
73 installations manually. The primary IDE hard drive is typically 'ad0'
dae36ee2
MD
74 and DragonFly is typically installed onto the first free slice
75 (ad0s1 if disk is empty, ad0s2 if your first slice contains
76 another OS, etc). Be careful to substitute the correct partition name
77 in the steps below.
78
79 # OPTIONAL STEP: If your disk is already partitioned and you
80 # have a spare primary partition on which you want to install
81 # Dragonfly, skip this step. However, sometimes old boot
82 # blocks or cruft in the boot area can interfere with the
83 # initialization process. A cure is to zero out the start of
84 # the disk before running fdisk.
85 #
86 # WARNING: This COMPLETELY WIPES and repartitions your hard drive.
572e6852
MD
87 #
88 dd if=/dev/zero of=/dev/ad0 bs=32k count=16
fb017d4e
CP
89 fdisk -I ad0
90 fdisk -B ad0
b816f770 91
dae36ee2 92 # If you didn't zero the disk as above, but have a spare slice
ba5e7b2f 93 # whose partition type you want to change to UFS, use fdisk(8).
dae36ee2 94
b816f770 95 # This installs boot blocks onto the HD and verifies their
b6a0a5cf 96 # installation. See note just above the 'reboot' below for
dae36ee2
MD
97 # things to try if it does not boot from your HD. If you
98 # already have a multi-OS bootloader installed you can skip
99 # this step.
b6a0a5cf 100 #
b816f770
MD
101 boot0cfg -B ad0
102 boot0cfg -v ad0
103
dae36ee2 104 # This creates an initial label on the chosen slice of the HD. If
b816f770 105 # you have problems booting you could try wiping the first 32 blocks
dae36ee2
MD
106 # of the slice with dd and then reinstalling the label. Replace
107 # 'ad0s1' with the chosen slice.
b816f770
MD
108 #
109 # dd if=/dev/zero of=/dev/ad0s1 bs=32k count=16
110 disklabel -B -r -w ad0s1 auto
111
112 # Edit the label. Create various standard partitions. The typical
ba5e7b2f 113 # configuration is:
b816f770
MD
114 #
115 # ad0s1a 256m This will be your /
116 # ad0s1b 1024m This will be your swap
117 # ad0s1c (leave alone)
118 # ad0s1d 256m This will be your /var
119 # ad0s1e 256m This will be your /tmp
120 # ad0s1f 8192m This will be your /usr (min 4096m)
0dab2a93 121 # ad0s1g * All remaining space to your /home
b816f770 122 #
ba5e7b2f 123 # An example disklabel can be found in /etc/disklabel.ad0s1.
4e04bc29 124 #
b816f770
MD
125 disklabel -e ad0s1
126
ed029207
JS
127 # If you are not using ad0s1 as in the previous commands, you will
128 # need to create the device nodes for that slice. Change the
129 # slice number (ad0s2a) to match the disk slice you are using.
130 #
131 # The device nodes are automatically created for ad0s1, so you can
132 # safely skip this step if you are using that disk slice.
133 #
134 cd /dev && MAKEDEV ad0s2a
135
136 # Newfs (format) the various filesystems. Softupdates is not
dae36ee2
MD
137 # normally enabled on the root filesystem because large kernel or
138 # world installs/upgrades can run it out of space due to softupdate's
139 # delayed bitmap freeing code.
b816f770
MD
140 #
141 newfs /dev/ad0s1a
142 newfs -U /dev/ad0s1d
143 newfs -U /dev/ad0s1e
144 newfs -U /dev/ad0s1f
145 newfs -U /dev/ad0s1g
146
ba5e7b2f 147 # Mount the filesystems.
b816f770
MD
148 #
149 mount /dev/ad0s1a /mnt
150 mkdir /mnt/var
151 mkdir /mnt/tmp
152 mkdir /mnt/usr
153 mkdir /mnt/home
154 mount /dev/ad0s1d /mnt/var
155 mount /dev/ad0s1e /mnt/tmp
156 mount /dev/ad0s1f /mnt/usr
157 mount /dev/ad0s1g /mnt/home
158
159 # Copy the CDRom onto the target. cpdup won't cross mount boundaries
160 # on the source (e.g. the MFS remounts) so it takes a few commands.
21aa02d0
CP
161 #
162 # Note that /etc contains the config files used for booting from the
163 # CDROM itself, and /etc.hdd contains those for booting off a
164 # hard disk. So it's the latter that you want to copy to /mnt/etc.
165 #
b816f770
MD
166 cpdup / /mnt
167 cpdup /var /mnt/var
21aa02d0 168 cpdup /etc.hdd /mnt/etc
b816f770 169 cpdup /dev /mnt/dev
a3e78356 170 cpdup /usr /mnt/usr
b816f770 171
7bd4a647 172 # Cleanup. Also, with /tmp a partition it is usually reasonable
ba5e7b2f 173 # to make /var/tmp a softlink to /tmp.
7bd4a647
MD
174 #
175 chmod 1777 /mnt/tmp
176 rm -rf /mnt/var/tmp
177 ln -s /tmp /mnt/var/tmp
178
b816f770
MD
179 # Edit /mnt/etc/fstab to reflect the new mounts. An example fstab
180 # file based on the above parameters exists as /mnt/etc/fstab.example
181 # which you can rename to /mnt/etc/fstab.
182 #
183 mv /mnt/etc/fstab.example /mnt/etc/fstab
184 vi /mnt/etc/fstab
185
ba5e7b2f 186 # Save out your disklabel just in case. It's a good idea to save
4e04bc29 187 # it to /etc so you can get at it from your backups. You do intend
ba5e7b2f 188 # to backup your system, yah? :-) (This isn't critical but it's a
4e04bc29
MD
189 # good idea).
190 #
191 disklabel ad0s1 > /mnt/etc/disklabel.ad0s1
192
87c240fe
MD
193
194 MISC CLEANUPS BEFORE REBOOTING
195
b816f770
MD
196 Once you've duplicated the CD onto your HD you have to make some edits
197 so the system boots properly from your HD. Primarily you must remove
dae36ee2
MD
198 or edit /mnt/boot/loader.conf, which exists on the CD to tell the kernel
199 to mount the CD's root partition.
b816f770 200
87c240fe
MD
201 # Remove or edit /mnt/boot/loader.conf so the kernel does not try
202 # to obtain the root filesystem from the CD, and remove the other
4e04bc29 203 # cruft that was sitting on the CD that you don't need on the HD.
b816f770
MD
204 #
205 rm /mnt/boot/loader.conf
d4cdca3f 206 rm /mnt/README*
0dab2a93
MD
207 rm /mnt/boot.catalog
208 rm -r /mnt/rr_moved
b816f770
MD
209
210 At this point it should be possible to reboot. The CD may be locked
87c240fe
MD
211 since it is currently mounted. To remove the CD, type 'halt' instead
212 of 'reboot', wait for the machine to halt, then the CD door should be
213 unlocked. Remove the CD and hit any key to reboot.
214
215 Be careful of the CD drawer closing on you if you try to remove the CD
216 while the machine is undergoing a reboot or reset.
b816f770 217
ba5e7b2f 218 WARNING: Do not just hit reset; the kernel may not have written out
a3e78356 219 all the pending data to your HD. Either unmount the HD partitions
87c240fe 220 or type halt or reboot.
a3e78356 221
87c240fe
MD
222 # halt
223 (let the machine halt)
b816f770 224 (remove CD when convenient, be careful of the CD drawer closing on you)
87c240fe
MD
225 (hit any key to reboot)
226
227
228 THE ACPI ISSUE
229
230 You will notice in the boot menu that you can choose to boot with or
231 without ACPI. ACPI is an infrastructure designed to allow an operating
ba5e7b2f
CP
232 system to configure hardware devices associated with the system.
233 Unfortunately, as usual, PC BIOS makers have royally screwed up the
234 standard and ACPI is as likely to hurt as it is to help. Worse, some
235 PCs cannot be booted without it, so there is no good 'default' choice.
87c240fe
MD
236
237 The system will use ACPI by default. You can disable it in the default
238 boot by adding the line 'hint.acpi.0.disabled=1' in /boot/loader.conf.
239 If you boot without hitting any menu options the system will boot without
240 ACPI. To boot without ACPI no matter what, place 'unset acpi_load' in
241 our /boot/loader.conf instead. This is not recommended.
242
243
244 IF YOU HAVE PROBLEMS BOOTING FROM HD
b816f770 245
87c240fe 246 There are a couple of things to try. If you can select CHS or LBA mode
ba5e7b2f 247 in your BIOS, try changing the mode to LBA. If that doesn't work, boot
87c240fe
MD
248 from the CD again and use boot0cfg to turn on packet mode (boot0cfg -o
249 packet ad0). Also try booting with and without ACPI (option 1 or 2 in
250 the boot menu).
dae36ee2 251
b816f770
MD
252 Once you have a working HD based system you can clean up /etc/rc.conf
253 to enable things like cron, sendmail, setup your networking, and so
254 forth. If 'ifconfig' does not show your networking device you could
255 try to kldload it from /modules. With a recognized network device
256 you can ifconfig its IP address or, if you have a DHCP server on your
257 network, use 'dhclient <interfacename>' to obtain an IP address from
513aa0c6 258 the network.
b816f770 259
ba5e7b2f 260
9c13f47c
MD
261 USING CVSUP TO OBTAIN A CVS TREE, PORTS, AND DOING BUILDWORLDS
262
263 cvsup can be used to obtain the DragonFly cvs repository, the FreeBSD
264 ports tree, and so on and so forth. 'man cvsup' for more information on
265 its capabilities. cvsup is a port (not part of the base system), but
266 it IS included on the CD. The cvsup example files are in
267 /usr/share/examples/cvsup. You will primarily be interested in the
268 DragonFly CVS repository, DragonFly-supfile, and the FreeBSD ports,
269 FreeBSD-ports-supfile. Once you have done the initial cvsup of the
270 blocks of data that you want you may wish to create a cron job to
271 keep it all up to date. However, please do not run an unattended cvsup
ba5e7b2f 272 more than once a day.
9c13f47c 273
ba5e7b2f 274 # get the CVS repository (it is placed in /home/dcvs)
eda86301 275 cvsup /usr/share/examples/cvsup/DragonFly-supfile
9c13f47c
MD
276 # install the source from the CVS hierarchy
277 cd /usr
278 cvs -R -d /home/dcvs checkout src
279 cvs -R -d /home/dcvs checkout dfports
280
281 # get the FreeBSD ports tree (it is directly broken out into /usr/ports)
eda86301 282 cvsup -h cvsup.freebsd.org /usr/share/examples/cvsup/FreeBSD-ports-supfile
9c13f47c
MD
283
284 # buildworld and installworld examples
285 #
286 cd /usr/src
287 make buildworld
288 make installworld
289
290 # buildkernel and installkernel examples. Create your own custom kernel
291 # config in /usr/src/sys/i386/conf/<YOURKERNEL> and you can build and
292 # install custom kernels.
293 #
294 # WARNING! Always keep a fully working backup kernel in / in case
295 # you blow it. Remember that /kernel.old is overwritten when you
296 # make installkernel. It is usually a good idea to maintain an emergency
297 # kernel as /kernel.GENERIC or /kernel.bak. If all else fails you can
298 # still fall back to booting the CD.
299 #
300 cd /usr/src
301 make buildkernel KERNCONF=GENERIC
302 make installkernel KERNCONF=GENERIC
303
ba5e7b2f 304
9c13f47c
MD
305 EMERGENCY RECOVERY FROM THE CD
306
307 Lets say you blew up your kernel or something else in / and you need to
308 boot the CD to fix it. Remember that you have a fully operational
309 system when booting the CD, but that you have to fsck and mount your
310 hard drive (typically onto /mnt) to get at the contents of your HD.
311
312 Your HD is typically an IDE hard drive, so the device is typically
313 /dev/ad0. DragonFly is typically on the first slice, which is
314 /dev/ad0s1, and the root partition is always in partition 'a',
315 which is /dev/ad0s1a.
316
317 # fsck root before trying to mount it.
318 fsck /dev/ad0s1a
319 # mount root read-write onto /mnt
320 mount /dev/ad0s1a /mnt
321 # copy files from the CD as appropriate to make it possible to boot
322 # from your HD again. Note that /mnt/kernel may be flags-protected.
323 chflags noschg /mnt/kernel
324 cp /kernel /mnt/kernel
325 cp /modules/* /mnt/modules/
326
327 If you want to mount other partitions from your HD but have forgotten
328 what they are, simply cat /mnt/etc/fstab after mounting the root
329 partition.
330
ba5e7b2f 331$DragonFly: src/nrelease/root/README,v 1.19 2005/03/21 04:52:34 cpressey Exp $
9c13f47c 332