/[gentoo]/xml/htdocs/doc/en/gentoo-freebsd.xml
Gentoo

Contents of /xml/htdocs/doc/en/gentoo-freebsd.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.20 - (show annotations) (download) (as text)
Fri May 26 19:29:27 2006 UTC (8 years, 2 months ago) by nightmorph
Branch: MAIN
Changes since 1.19: +8 -7 lines
File MIME type: application/xml
Minor grammar/spelling fixes for this update; no content change

1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/gentoo-freebsd.xml,v 1.19 2006/05/26 19:21:37 nightmorph Exp $ -->
3 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4
5 <guide link="/doc/en/gentoo-freebsd.xml">
6 <title>A short guide to Gentoo/FreeBSD</title>
7
8 <author title="Author">
9 <mail link="ignacio.arquelatour@gmail.com">Ignacio Arque-Latour</mail>
10 </author>
11 <author title="Author">
12 <mail link="citizen428@gentoo.org">Michael Kohl</mail>
13 </author>
14 <author title="Author">
15 <mail link="angusyoung@gentoo.org">Otavio R. Piske</mail>
16 </author>
17 <author title="Author">
18 <mail link="ka0ttic@gentoo.org">Aaron Walker</mail>
19 </author>
20
21 <abstract>
22 This document gives some general information on FreeBSD, as well as
23 installation instructions for Gentoo/FreeBSD. It also includes some reference
24 for people interested in helping out with development.
25 </abstract>
26
27 <!-- The content of this document is licensed under the CC-BY-SA license -->
28 <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
29 <license/>
30
31 <version>2.5</version>
32 <date>2006-05-26</date>
33
34 <chapter>
35 <title>Introduction to FreeBSD</title>
36 <section>
37 <title>What is FreeBSD?</title>
38 <body>
39
40 <p>
41 <uri link="http://www.freebsd.org/">FreeBSD</uri> is a free (<uri
42 link="http://www.freebsd.org/copyright/freebsd-license.html">license</uri>)
43 Unix-like operating system. Back in 1993 when development of <uri
44 link="http://www.386bsd.org/">386BSD</uri> stopped, two projects were born:
45 <uri link="http://www.netbsd.org/">NetBSD</uri>, commonly known to run on a
46 huge number of architectures, and FreeBSD which supports the x86, amd64, ia64,
47 sparc64 and alpha platforms.FreeBSD is renowned for its stability, performance
48 and security, thus being used from small to huge companies all over the world.
49 FreeBSD's current production release version is 6.1, which is also used as the
50 foundation for the Gentoo/FreeBSD project. The previous 5.x branch is being
51 continued by the FreeBSD project as a service release, but is no longer worked
52 on by the Gentoo/FreeBSD developers.
53 </p>
54
55 </body>
56 </section>
57 <section>
58 <title>What is Gentoo/FreeBSD?</title>
59 <body>
60
61 <p>
62 <uri link="/proj/en/gentoo-alt/bsd/fbsd/">Gentoo/FreeBSD</uri> is a subproject
63 of the <uri link="/proj/en/gentoo-alt/">Gentoo/Alt project</uri>, with the
64 goal of providing a fully-capable FreeBSD operating system featuring design
65 sensibilities taken from Gentoo Linux, such as the init system and the Portage
66 package management system.
67 </p>
68
69 </body>
70 </section>
71 <section>
72 <title>FreeBSD and Linux</title>
73 <body>
74
75 <p>
76 Users migrating from Linux to FreeBSD commonly consider the two operating
77 systems "almost the same". In fact, FreeBSD really shares a lot of similarities
78 with Linux distributions in general. Nevertheless, it has some key differences
79 that are worth noting:
80 </p>
81
82 <ul>
83 <li>
84 Contrary to Linux, which actually only refers to the kernel, FreeBSD is a
85 complete operating system, consisting of a C library, userland tools and
86 much more. This development approach makes the overall system very
87 consistent.
88 </li>
89 <li>
90 Contrary to the Linux kernel, FreeBSD development is not led by one person,
91 but instead managed by a small group of people called the <uri
92 link="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributors/staff-core.html">Core
93 Team</uri>.
94 </li>
95 </ul>
96
97 <p>
98 Besides, FreeBSD also has some technical differences which set it apart
99 from Linux. Some of them are very important to know, even if you don't plan on
100 joining the Gentoo/FreeBSD development effort:
101 </p>
102
103 <ul>
104 <li>
105 To get run-time dynamic linking functions like <c>dlopen()</c>, programs do
106 not need to be linked against libdl like on GNU/Linux. Instead they are
107 linked against libc.
108 </li>
109 <li>
110 FreeBSD doesn't have an official tool for kernel compilation, thus you'll
111 have to resolve feature dependencies on your own.
112 </li>
113 <li>
114 FreeBSD uses UFS/UFS-2 as its filesystems and has no official support for
115 e.g. ReiserFS or XFS. However, there are projects for adding read-only
116 support for these filesystems. Accessing ext2/ext3 partitions is already
117 possible, but you cannot install your system on them.
118 </li>
119 </ul>
120
121 </body>
122 </section>
123 </chapter>
124
125 <chapter>
126 <title>Installing Gentoo/FreeBSD</title>
127 <section>
128 <title>Installation instructions</title>
129 <body>
130
131 <p>
132 After this short introduction, it's about time to finally install
133 Gentoo/FreeBSD. Unfortunately, we currently lack our own installation media, so
134 you have to choose between two alternative installation methods. The first
135 would be to use an existing FreeBSD installation to partition your hard drive
136 and use it as a base for installing Gentoo/FreeBSD. Alternatively, you can also
137 use the excellent <uri link="http://www.freesbie.org/">FreeSBIE LiveCD</uri> as
138 an installation medium for Gentoo/FreeBSD.
139 </p>
140
141 <note>
142 If you are intending to use FreeSBIE for installing Gentoo/FreeBSD, please make
143 sure to use a version based on FreeBSD 6.0! Experimental versions can be downloaded
144 from <uri link="http://torrent.freesbie.org/">FreeSBIE's Bittorrent tracker</uri> and
145 version 20060118 has been tested to work for the purposes described in this document.
146 </note>
147
148 <note>
149 We use <c>ee</c> as a default editor in this guide but you can choose
150 <c>vim</c>, <c>nano</c> or any other editor you like to configure your system.
151 </note>
152
153 <p>
154 Before you can begin with the installation, you have to setup a hard disk for
155 use with Gentoo/FreeBSD. This can either be done via <c>sysinstall</c>
156 (available from a current FreeBSD installation as well as from within FreeSBIE)
157 or by manually using the commands <c>fdisk</c>, <c>disklabel</c> and <c>newfs</c>.
158 If you have never set up a FreeBSD system before, <c>sysinstall</c> may be the
159 better option for you. In that case make sure that you don't use the sysinstall
160 launched by FreeBSD's or FreeSBIE's installers, but use the following command instead:
161 </p>
162
163 <pre caption="Partitioning with sysinstall">
164 # <i>sysinstall diskPartitionEditor diskPartitionWrite diskLabelEditor diskLabelCommit</i>
165 </pre>
166
167 <p>
168 If you face difficulties
169 while partitioning or formatting your hard disks, have a look at the great
170 <uri link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/">FreeBSD
171 Handbook</uri> or hop onto <c>#gentoo-bsd</c> on the Freenode IRC server.
172 </p>
173
174 <p>
175 Once you're done setting up your disks, you have to create a mount point for
176 your Gentoo/FreeBSD installation and mount all the necessary partitions.
177 </p>
178
179 <pre caption="Creating a mount point and mounting partitions">
180 # <i>mkdir /mnt/gentoo</i>
181 <comment>(Replace X with the correct numbers for your hard disk.)</comment>
182 # <i>mount /dev/adXsXa /mnt/gentoo</i>
183 </pre>
184
185 <p>
186 If you're using the FreeSBIE LiveCD and you already had an UFS partition on
187 your hard disk, it has already been mounted read-only to <path>/mnt/ufs.1</path>.
188 If you want to use that location for your installation, you'll have to remount it
189 in read-write mode:
190 </p>
191
192 <pre caption="Remounting a partition in read-write mode">
193 # <i>mount -u -o rw /mnt/ufs.1</i>
194 </pre>
195
196 <p>
197 Now that you have mounted the target partition, it is time to fetch and unpack
198 a stage3 tarball.
199 </p>
200
201 <pre caption="Obtaining and unpacking a stage3 tarball">
202 # <i>cd /mnt/gentoo/</i>
203 <comment>(Any other Gentoo mirror which includes the experimental/ directory will also work.)</comment>
204 # <i>wget http://gentoo.osuosl.org/experimental/x86/freebsd/stages/gentoo-freebsd-6.1-stage-20060509.tar.bz2</i>
205 # <i>tar -jxvpf gentoo-freebsd-6.1-stage-20060509.tar.bz2</i>
206 <comment>(You can delete the tarball with the following command if you want to.)</comment>
207 # <i>rm gentoo-freebsd-6.1-stage-20060509.tar.bz2</i>
208 </pre>
209
210 <p>
211 Before chrooting into the newly-extracted stage, you first must obtain an
212 up-to-date copy of the Gentoo/FreeBSD overlay. The easiest way to achieve this
213 is to to get our latest snapshot which you then extract to
214 <path>/mnt/gentoo/usr/local/portage</path>.
215 </p>
216
217 <pre caption="Getting the Gentoo/FreeBSD Portage overlay">
218 # <i>cd /mnt/gentoo/usr/local/portage</i>
219 # <i>wget http://gentoo.osuosl.org/experimental/snapshots/portage-alt-overlay-latest.tar.bz2</i>
220 # <i>tar -xjf portage-alt-overlay-latest.tar.bz2</i>
221 <comment>(You now can safely delete the snapshot with the following command.)</comment>
222 # <i>rm portage-alt-overlay-latest.tar.bz2</i>
223 </pre>
224
225 <p>
226 Alternatively, you can also use Subversion to check out the current version of
227 the overlay. If you are interested in this possibility, please refer to the
228 <uri
229 link="/proj/en/gentoo-alt/contribute/index.xml?part=1&amp;chap=3">Gentoo/ALT
230 overlay documentation</uri>.
231 </p>
232
233 <p>
234 In order for your install to work, you need to mount the <path>/dev</path>
235 filesystem from the currently running system into the Gentoo/FreeBSD mount
236 point before proceeding with the chroot.
237 </p>
238
239 <pre caption="Mounting the /dev filesystem and chrooting">
240 # <i>mount -t devfs none /mnt/gentoo/dev/</i>
241 # <i>cp /etc/resolv.conf /mnt/gentoo/etc</i>
242 # <i>chroot /mnt/gentoo/ /bin/bash</i>
243 # <i>source /etc/profile</i>
244 </pre>
245
246 <p>
247 After you got hold of the Gentoo/FreeBSD overlay, it's time to link
248 <path>/etc/make.profile</path> to the correct profile and add get your
249 <path>/etc/make.conf</path> ready for Gentoo/FreeBSD.
250 </p>
251
252 <p>
253 Now, you have to obtain a copy of the main Gentoo Portage tree, which depending
254 on your connection might take quite a while.
255 </p>
256
257 <pre caption="Obtaining the Portage tree">
258 # <i>emerge --sync</i>
259 <comment>(It's also possible to retrieve the Portage tree in another way:)</comment>
260 # <i>cd /</i>
261 # <i>wget http://gentoo.osuosl.org/snapshots/portage-latest.tar.bz2</i>
262 # <i>tar -xjf portage-latest.tar.bz2 -C /usr/</i>
263 # <i>emerge --metadata</i>
264 </pre>
265
266 <pre caption="Setting up the profile and editing /etc/make.conf">
267 # <i>ln -sf /usr/portage/profiles/default-bsd/fbsd/6.1/x86/ /etc/make.profile</i>
268 <comment>(FreeBSD's standard editor is ee, which is used to edit /etc/make.conf)</comment>
269 # <i>ee /etc/make.conf</i>
270 <comment>(Please make sure you add at least the following entries:)</comment>
271 CHOST="i686-gentoo-freebsd6.1"
272 ACCEPT_KEYWORDS="~x86-fbsd"
273 FEATURES="-sandbox collision-protect"
274 PORTDIR_OVERLAY="/usr/local/portage/portage-alt-overlay"
275 </pre>
276
277 <note>
278 You can have a very limited system by using ~x86-fbsd keyword alone; you might
279 want to put ~x86 in your ACCEPT_KEYWORDS if you want access to more packages
280 but you might find broken dependencies and non-working packages; please rather
281 use package.keywords when testing packages and report working ones on <uri
282 link="http://bugs.gentoo.org">Bugzilla</uri> for the product Gentoo/Alt.
283 </note>
284
285 <p>
286 In order to boot correctly, you will need to create the <path>/proc</path>
287 directory.
288 </p>
289
290 <pre caption="Creating the /proc directory">
291 # <i>mkdir /proc</i>
292 </pre>
293
294 <p>
295 If you want, you can now rebuild the system's core packages.
296 </p>
297
298 <pre caption="Rebuilding the FreeBSD core packages (optional)">
299 # <i>emerge -e system</i>
300 </pre>
301
302 <p>
303 When you did <c>emerge -e system</c>, the sources for the FreeBSD kernel got
304 installed to <path>/usr/src/sys</path>. If you skipped this step, you can get
305 them in the following way:
306 </p>
307
308 <pre caption="Getting the FreeBSD kernel sources">
309 # <i>emerge freebsd-sources</i>
310 </pre>
311
312 <p>
313 Configuring and compiling a custom kernel is really different from compiling
314 Linux, so if you are not familiar with the process we encourage you to have a
315 look at <uri
316 link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html">
317 chapter 8</uri> of the FreeBSD handbook.
318 </p>
319
320 <p>
321 Please note that currently only the "Traditional" way of building the kernel is
322 supported on Gentoo/FreeBSD! Also note that <c>make install</c> will probably
323 ask you for a <path>/boot/device.hints</path> file. A default version can be
324 found in the <path>conf</path> subdirectory of the <c>GENERIC</c> configuration
325 and is called <path>GENERIC.hints</path>.
326 </p>
327
328 <p>
329 Now is the time to do some basic system configuration and settings. First, we
330 are going to setup the filesystem mounting points in <path>/etc/fstab</path>.
331 </p>
332
333 <pre caption="Editing the filesystem in /etc/fstab">
334 # <i>ee /etc/fstab</i>
335 <comment>(This is an example, replace X and Y with the correct numbers for your hard disk.)</comment>
336 #Device Mountpoint Fstype Options Dump Pass
337 /dev/adXsYb none swap sw 0 0
338 /dev/adXsYa / ufs rw 1 1
339 /dev/adXsYe /usr/home ufs rw 2 2
340 /dev/adXsYd /tmp ufs rw 2 2
341 /dev/acdX /cdrom cd9660 ro,noauto 0 0
342 </pre>
343
344 <p>
345 Now would also be a good time to set up your network connection before the final
346 reboot.
347 </p>
348
349 <p>
350 You can find all the information necessary to configure your network in the
351 <uri link="/doc/en/handbook/handbook-x86.xml?part=4&amp;chap=1">Gentoo
352 Handbook</uri>.
353 </p>
354
355 <p>
356 To have your network interface activated at boot time, you have to add it to
357 the default runlevel.
358 </p>
359
360 <pre caption="Adding your network adapter to the default runlevel">
361 # <i>rc-update add net.rl0 default</i>
362 </pre>
363
364 <p>
365 Your system's hostname can be changed in <path>/etc/conf.d/hostname</path>.
366 </p>
367
368 <pre caption="Setting up the machine's hostname">
369 # <i>ee /etc/conf.d/hostname</i>
370 <comment>(Set the HOSTNAME variable to your hostname)</comment>
371 HOSTNAME="tux"
372 </pre>
373
374 <p>
375 You should also configure your domain name, which is done in the
376 <path>/etc/conf.d/domainname</path> file:
377 </p>
378
379 <pre caption="Setting the domainname">
380 # <i>ee /etc/conf.d/domainname</i>
381 <comment>(Set the DNSDOMAIN variable to your domain name)</comment>
382 DNSDOMAIN="homenetwork"
383 </pre>
384
385 <p>
386 If you have a NIS domain, you need to define it in the
387 <path>/etc/conf.d/domainname</path> file:
388 </p>
389
390 <pre caption="Setting the NIS domainname">
391 # <i>ee /etc/conf.d/domainname</i>
392 <comment>(Set the NISDOMAIN variable to your NIS domain name)</comment>
393 NISDOMAIN="my-nisdomain"
394 </pre>
395
396 <p>
397 In case you need to use another keyboard layout for your language, you have to
398 set the correct value in <path>/etc/conf.d/syscons</path>. The following example
399 uses the Spanish layout, so you'll have to adjust it to your need if you want to
400 use another one.
401 </p>
402
403 <pre caption="Changing your keyboard layout (Optional)">
404 # <i>ee /etc/conf.d/syscons</i>
405 KEYMAP="spanish.iso.acc"
406 <comment>(Possible layouts can be found in /usr/share/syscons/keymaps).</comment>
407 </pre>
408
409 <impo>
410 Please make absolutely sure you add your new Gentoo/FreeBSD installation to the
411 configuration of your bootloader, otherwise you won't be able to boot your newly
412 installed system! If you don't have another bootloader installed, you should use
413 <c>boot0</c>, as it is currently the only one supported by FreeBSD. In this case
414 please don't forget to use your other operating systems to <c>boot0</c>'s
415 configuration.
416 </impo>
417
418 <pre caption="Installing and setting up boot0">
419 # <i>emerge boot0</i>
420 <comment>(Leave the chroot environment)</comment>
421 # <i>exit</i>
422 <comment>(Issued from outside the chroot)</comment>
423 # <i>fdisk -B -b /mnt/gentoo/boot/boot0 /dev/adX</i>
424 # <i>chroot /mnt/gentoo /bin/bash</i>
425 # <i>disklabel -B adXsY</i>
426 </pre>
427
428 <p>
429 If you need additional information on setting up <c>boot0</c>, please consult
430 <uri
431 link="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/boot.html">chapter
432 12</uri> of the FreeBSD handbook.
433 </p>
434
435 <p>
436 Now would be a good time to set a password for the <c>root</c> user and to add
437 another user account for your day-to-day work.
438 </p>
439
440 <pre caption="Changing the root password and adding a new user">
441 # <i>passwd</i>
442 <comment>(If you need help in adding a user please consult the FreeBSD handbook).</comment>
443 # <i>adduser</i>
444 </pre>
445
446 <p>
447 Congratulations, you have just finished your Gentoo/FreeBSD installation which
448 you can start exploring after the final reboot. Have fun!
449 </p>
450
451 <pre caption="Rebooting the system">
452 # <i>exit</i>
453 # <i>reboot</i>
454 </pre>
455
456 </body>
457 </section>
458 </chapter>
459
460 <chapter>
461 <title>Developing for Gentoo/FreeBSD</title>
462 <section>
463 <title>How to help</title>
464 <body>
465
466 <p>
467 There are many things you could help with, depending on your skill level and
468 spare time:
469 </p>
470
471 <ul>
472 <li>
473 Working on current ebuilds: this means working closely with ebuild
474 maintainers in order to create patches or modify ebuilds in a way that can
475 be accepted into the main tree.
476 </li>
477 <li>
478 Security: if you are into security, we need you! Although security
479 advisories from the FreeBSD project are tracked and fixed, we can always
480 use help in this area.
481 </li>
482 <li>
483 Contacts: we need people who can get in touch with FreeBSD developers to
484 maintain contacts between us and the original project to exchange patches
485 and discuss various problems and their solutions. Note that this should
486 never involve any kind of spamming of mailing lists or IRC channels.
487 </li>
488 <li>
489 Testing: the more people are actively using Gentoo/FreeBSD, the more bugs
490 will be discovered, which helps us improving the quality of the port. If
491 you are good at describing bugs or problems, we definitely want to hear
492 from you.
493 </li>
494 <li>
495 Other areas where we need help include: system ebuilds, baselayout,
496 creation of installation CDs, documentation, kernel hacking.
497 </li>
498 </ul>
499
500 </body>
501 </section>
502
503 <section>
504 <title>Known issues</title>
505 <body>
506
507 <p>
508 At the moment, there are still quite a lot of known issues. Here are the ones
509 really worth noting:
510 </p>
511
512 <ul>
513 <li>
514 Some init scripts depend on the clock service which we don't provide right
515 now. You can just remove it from the dependencies of the script and report
516 that on our <uri link="http://bugs.gentoo.org/">bugzilla</uri>. Please
517 remember to use the "Gentoo BSD" product for your submission.
518 </li>
519 <li>glib and gnome in general need a lot of fixes to be backported.</li>
520 <li>
521 The init system currently provided by Gentoo/FreeBSD's baselayout package is
522 not the same version used by Gentoo Linux and lacks some of its features. Work
523 on making newer versions working is underway.
524 </li>
525 </ul>
526
527 </body>
528 </section>
529 </chapter>
530
531 <chapter>
532 <title>Contact</title>
533 <section>
534 <body>
535
536 <p>
537 A list of Gentoo/FreeBSD developers can be found at the <uri
538 link="/proj/en/gentoo-alt/bsd/fbsd/">project page</uri>. Other ways to contact
539 Gentoo/FreeBSD developers include our IRC Channel <c>#gentoo-bsd</c> on
540 Freenode, as well as the <uri link="/main/en/lists.xml">gentoo-bsd mailing
541 list</uri>.
542 </p>
543
544 </body>
545 </section>
546 </chapter>
547 </guide>

  ViewVC Help
Powered by ViewVC 1.1.20