/[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.19 - (show annotations) (download) (as text)
Fri May 26 19:21:37 2006 UTC (8 years, 4 months ago) by nightmorph
Branch: MAIN
Changes since 1.18: +15 -15 lines
File MIME type: application/xml
Updated freebsd profile & stage instructions for bug 134444. thanks to flameeyes for reporting

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

  ViewVC Help
Powered by ViewVC 1.1.20