diff options
| author | Li-Wen Hsu <lwhsu@FreeBSD.org> | 2014-05-29 16:48:07 +0000 |
|---|---|---|
| committer | Li-Wen Hsu <lwhsu@FreeBSD.org> | 2014-05-29 16:48:07 +0000 |
| commit | 163ba6b752e2d1b900f88ba29324ed5998b14551 (patch) | |
| tree | 3010592efec60252103b5e76eab918b0491bb533 /zh_TW.UTF-8/books/handbook | |
| parent | 536050cea8f16998f8fbddf6b4aff8469e149ec0 (diff) | |
| download | doc-163ba6b752e2d1b900f88ba29324ed5998b14551.tar.gz doc-163ba6b752e2d1b900f88ba29324ed5998b14551.zip | |
Convert zh_TW from Big5 to UTF-8.
Approved by: bcr
Notes
Notes:
svn path=/head/; revision=44974
Diffstat (limited to 'zh_TW.UTF-8/books/handbook')
81 files changed, 74440 insertions, 0 deletions
diff --git a/zh_TW.UTF-8/books/handbook/Makefile b/zh_TW.UTF-8/books/handbook/Makefile new file mode 100644 index 0000000000..6dee2d0433 --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/Makefile @@ -0,0 +1,269 @@ +# +# $FreeBSD$ +# Original revision: 1.108 +# +# Build the FreeBSD Handbook. +# + +.PATH: ${.CURDIR}/../../share/xml/glossary + +MAINTAINER= doc@FreeBSD.org + +DOC?= book + +FORMATS?= html-split + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +IMAGES_EN = advanced-networking/isdn-bus.eps +IMAGES_EN+= advanced-networking/isdn-twisted-pair.eps +IMAGES_EN+= advanced-networking/natd.eps +IMAGES_EN+= advanced-networking/net-routing.pic +IMAGES_EN+= advanced-networking/static-routes.pic +IMAGES_EN+= geom/striping.pic +IMAGES_EN+= install/adduser1.scr +IMAGES_EN+= install/adduser2.scr +IMAGES_EN+= install/adduser3.scr +IMAGES_EN+= install/boot-loader-menu.scr +IMAGES_EN+= install/boot-mgr.scr +IMAGES_EN+= install/config-country.scr +IMAGES_EN+= install/console-saver1.scr +IMAGES_EN+= install/console-saver2.scr +IMAGES_EN+= install/console-saver3.scr +IMAGES_EN+= install/console-saver4.scr +IMAGES_EN+= install/disklabel-auto.scr +IMAGES_EN+= install/disklabel-ed1.scr +IMAGES_EN+= install/disklabel-ed2.scr +IMAGES_EN+= install/disklabel-fs.scr +IMAGES_EN+= install/disklabel-root1.scr +IMAGES_EN+= install/disklabel-root2.scr +IMAGES_EN+= install/disklabel-root3.scr +IMAGES_EN+= install/disk-layout.eps +IMAGES_EN+= install/dist-set.scr +IMAGES_EN+= install/dist-set2.scr +IMAGES_EN+= install/docmenu1.scr +IMAGES_EN+= install/ed0-conf.scr +IMAGES_EN+= install/ed0-conf2.scr +IMAGES_EN+= install/edit-inetd-conf.scr +IMAGES_EN+= install/fdisk-drive1.scr +IMAGES_EN+= install/fdisk-drive2.scr +IMAGES_EN+= install/fdisk-edit1.scr +IMAGES_EN+= install/fdisk-edit2.scr +IMAGES_EN+= install/ftp-anon1.scr +IMAGES_EN+= install/ftp-anon2.scr +IMAGES_EN+= install/hdwrconf.scr +IMAGES_EN+= install/keymap.scr +IMAGES_EN+= install/main1.scr +IMAGES_EN+= install/mainexit.scr +IMAGES_EN+= install/main-std.scr +IMAGES_EN+= install/main-options.scr +IMAGES_EN+= install/main-doc.scr +IMAGES_EN+= install/main-keymap.scr +IMAGES_EN+= install/media.scr +IMAGES_EN+= install/mouse1.scr +IMAGES_EN+= install/mouse2.scr +IMAGES_EN+= install/mouse3.scr +IMAGES_EN+= install/mouse4.scr +IMAGES_EN+= install/mouse5.scr +IMAGES_EN+= install/mouse6.scr +IMAGES_EN+= install/mta-main.scr +IMAGES_EN+= install/net-config-menu1.scr +IMAGES_EN+= install/net-config-menu2.scr +IMAGES_EN+= install/nfs-server-edit.scr +IMAGES_EN+= install/ntp-config.scr +IMAGES_EN+= install/options.scr +IMAGES_EN+= install/pkg-cat.scr +IMAGES_EN+= install/pkg-confirm.scr +IMAGES_EN+= install/pkg-install.scr +IMAGES_EN+= install/pkg-sel.scr +IMAGES_EN+= install/probstart.scr +IMAGES_EN+= install/routed.scr +IMAGES_EN+= install/security.scr +IMAGES_EN+= install/sysinstall-exit.scr +IMAGES_EN+= install/timezone1.scr +IMAGES_EN+= install/timezone2.scr +IMAGES_EN+= install/timezone3.scr +IMAGES_EN+= install/userconfig.scr +IMAGES_EN+= install/userconfig2.scr +IMAGES_EN+= mail/mutt1.scr +IMAGES_EN+= mail/mutt2.scr +IMAGES_EN+= mail/mutt3.scr +IMAGES_EN+= mail/pine1.scr +IMAGES_EN+= mail/pine2.scr +IMAGES_EN+= mail/pine3.scr +IMAGES_EN+= mail/pine4.scr +IMAGES_EN+= mail/pine5.scr + +IMAGES_EN+= install/example-dir1.eps +IMAGES_EN+= install/example-dir2.eps +IMAGES_EN+= install/example-dir3.eps +IMAGES_EN+= install/example-dir4.eps +IMAGES_EN+= install/example-dir5.eps +IMAGES_EN+= security/ipsec-network.pic +IMAGES_EN+= security/ipsec-crypt-pkt.pic +IMAGES_EN+= security/ipsec-encap-pkt.pic +IMAGES_EN+= security/ipsec-out-pkt.pic +IMAGES_EN+= vinum/vinum-concat.pic +IMAGES_EN+= vinum/vinum-mirrored-vol.pic +IMAGES_EN+= vinum/vinum-raid10-vol.pic +IMAGES_EN+= vinum/vinum-raid5-org.pic +IMAGES_EN+= vinum/vinum-simple-vol.pic +IMAGES_EN+= vinum/vinum-striped-vol.pic +IMAGES_EN+= vinum/vinum-striped.pic +IMAGES_EN+= virtualization/parallels-freebsd1.png +IMAGES_EN+= virtualization/parallels-freebsd2.png +IMAGES_EN+= virtualization/parallels-freebsd3.png +IMAGES_EN+= virtualization/parallels-freebsd4.png +IMAGES_EN+= virtualization/parallels-freebsd5.png +IMAGES_EN+= virtualization/parallels-freebsd6.png +IMAGES_EN+= virtualization/parallels-freebsd7.png +IMAGES_EN+= virtualization/parallels-freebsd8.png +IMAGES_EN+= virtualization/parallels-freebsd9.png +IMAGES_EN+= virtualization/parallels-freebsd10.png +IMAGES_EN+= virtualization/parallels-freebsd11.png +IMAGES_EN+= virtualization/parallels-freebsd12.png +IMAGES_EN+= virtualization/parallels-freebsd13.png +IMAGES_EN+= virtualization/virtualpc-freebsd1.png +IMAGES_EN+= virtualization/virtualpc-freebsd2.png +IMAGES_EN+= virtualization/virtualpc-freebsd3.png +IMAGES_EN+= virtualization/virtualpc-freebsd4.png +IMAGES_EN+= virtualization/virtualpc-freebsd5.png +IMAGES_EN+= virtualization/virtualpc-freebsd6.png +IMAGES_EN+= virtualization/virtualpc-freebsd7.png +IMAGES_EN+= virtualization/virtualpc-freebsd8.png +IMAGES_EN+= virtualization/virtualpc-freebsd9.png +IMAGES_EN+= virtualization/virtualpc-freebsd10.png +IMAGES_EN+= virtualization/virtualpc-freebsd11.png +IMAGES_EN+= virtualization/virtualpc-freebsd12.png +IMAGES_EN+= virtualization/virtualpc-freebsd13.png +IMAGES_EN+= virtualization/vmware-freebsd01.png +IMAGES_EN+= virtualization/vmware-freebsd02.png +IMAGES_EN+= virtualization/vmware-freebsd03.png +IMAGES_EN+= virtualization/vmware-freebsd04.png +IMAGES_EN+= virtualization/vmware-freebsd05.png +IMAGES_EN+= virtualization/vmware-freebsd06.png +IMAGES_EN+= virtualization/vmware-freebsd07.png +IMAGES_EN+= virtualization/vmware-freebsd08.png +IMAGES_EN+= virtualization/vmware-freebsd09.png +IMAGES_EN+= virtualization/vmware-freebsd10.png +IMAGES_EN+= virtualization/vmware-freebsd11.png +IMAGES_EN+= virtualization/vmware-freebsd12.png + +# Images from the cross-document image library +IMAGES_LIB= callouts/1.png +IMAGES_LIB+= callouts/2.png +IMAGES_LIB+= callouts/3.png +IMAGES_LIB+= callouts/4.png +IMAGES_LIB+= callouts/5.png +IMAGES_LIB+= callouts/6.png +IMAGES_LIB+= callouts/7.png +IMAGES_LIB+= callouts/8.png +IMAGES_LIB+= callouts/9.png +IMAGES_LIB+= callouts/10.png +IMAGES_LIB+= callouts/11.png +IMAGES_LIB+= callouts/12.png +IMAGES_LIB+= callouts/13.png +IMAGES_LIB+= callouts/14.png +IMAGES_LIB+= callouts/15.png + +# +# SRCS lists the individual XML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# XML content +SRCS+= audit/chapter.xml +SRCS+= book.xml +SRCS+= colophon.xml +SRCS+= advanced-networking/chapter.xml +SRCS+= basics/chapter.xml +SRCS+= bibliography/chapter.xml +SRCS+= boot/chapter.xml +SRCS+= config/chapter.xml +SRCS+= cutting-edge/chapter.xml +SRCS+= desktop/chapter.xml +SRCS+= disks/chapter.xml +SRCS+= eresources/chapter.xml +SRCS+= firewalls/chapter.xml +SRCS+= geom/chapter.xml +SRCS+= install/chapter.xml +SRCS+= introduction/chapter.xml +SRCS+= jails/chapter.xml +SRCS+= kernelconfig/chapter.xml +SRCS+= l10n/chapter.xml +SRCS+= linuxemu/chapter.xml +SRCS+= mac/chapter.xml +SRCS+= mail/chapter.xml +SRCS+= mirrors/chapter.xml +SRCS+= multimedia/chapter.xml +SRCS+= network-servers/chapter.xml +SRCS+= pgpkeys/chapter.xml +SRCS+= ports/chapter.xml +SRCS+= ppp-and-slip/chapter.xml +SRCS+= preface/preface.xml +SRCS+= printing/chapter.xml +SRCS+= security/chapter.xml +SRCS+= serialcomms/chapter.xml +SRCS+= users/chapter.xml +SRCS+= vinum/chapter.xml +SRCS+= virtualization/chapter.xml +SRCS+= x11/chapter.xml + +# Entities +SRCS+= chapters.ent + +SYMLINKS= ${DESTDIR} index.html handbook.html + +# Turn on all the chapters. +CHAPTERS?= ${SRCS:M*chapter.xml} + +XMLFLAGS+= ${CHAPTERS:S/\/chapter.xml//:S/^/-i chap./} +XMLFLAGS+= -i chap.freebsd-glossary + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +# +# rules generating lists of mirror site from XML database. +# +XMLDOCS= lastmod:::mirrors.lastmod.inc \ + mirrors-ftp-index:::mirrors.xml.ftp.index.inc \ + mirrors-ftp:::mirrors.xml.ftp.inc \ + mirrors-cvsup-index:::mirrors.xml.cvsup.index.inc \ + mirrors-cvsup:::mirrors.xml.cvsup.inc \ + eresources-index:::eresources.xml.www.index.inc \ + eresources:::eresources.xml.www.inc +DEPENDSET.DEFAULT= transtable mirror +XSLT.DEFAULT= ${XSL_MIRRORS} +XML.DEFAULT= ${XML_MIRRORS} + +PARAMS.lastmod+= --param 'target' "'lastmod'" +PARAMS.mirrors-ftp-index+= --param 'type' "'ftp'" \ + --param 'proto' "'ftp'" \ + --param 'target' "'index'" +PARAMS.mirrors-ftp+= --param 'type' "'ftp'" \ + --param 'proto' "'ftp'" \ + --param 'target' "'handbook/mirrors/chapter.xml'" +PARAMS.mirrors-cvsup-index+= --param 'type' "'cvsup'" \ + --param 'proto' "'cvsup'" \ + --param 'target' "'index'" +PARAMS.mirrors-cvsup+= --param 'type' "'cvsup'" \ + --param 'proto' "'cvsup'" \ + --param 'target' "'handbook/mirrors/chapter.xml'" +PARAMS.eresources-index+= --param 'type' "'www'" \ + --param 'proto' "'http'" \ + --param 'target' "'index'" +PARAMS.eresources+= --param 'type' "'www'" \ + --param 'proto' "'http'" \ + --param 'target' "'handbook/eresources/chapter.xml'" + +SRCS+= mirrors.lastmod.inc \ + mirrors.xml.ftp.inc \ + mirrors.xml.ftp.index.inc \ + mirrors.xml.cvsup.inc \ + mirrors.xml.cvsup.index.inc \ + eresources.xml.www.inc \ + eresources.xml.www.index.inc + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/zh_TW.UTF-8/books/handbook/advanced-networking/Makefile b/zh_TW.UTF-8/books/handbook/advanced-networking/Makefile new file mode 100644 index 0000000000..6bce63bf94 --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/advanced-networking/Makefile @@ -0,0 +1,16 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# Original revision: 1.2 +# + +CHAPTERS= advanced-networking/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/zh_TW.UTF-8/books/handbook/advanced-networking/chapter.xml b/zh_TW.UTF-8/books/handbook/advanced-networking/chapter.xml new file mode 100644 index 0000000000..4773be660f --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/advanced-networking/chapter.xml @@ -0,0 +1,5438 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ + Original revision: 1.402 +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="advanced-networking"> + <title>網路進階練功房</title> + + <sect1 xml:id="advanced-networking-synopsis"> + <title>概述</title> + + <para>本章將介紹一些進階的網路設定主題。</para> + + <para>讀完這章，您將了解：</para> + + <itemizedlist> + <listitem> + <para>gateway(閘道)及 route(路由)的概念。</para> + </listitem> + + <listitem> + <para>如何設定 IEEE 802.11 以及藍芽(&bluetooth;)設備。</para> + </listitem> + + <listitem> + <para>如何以 FreeBSD 作為 bridge(橋接)。</para> + </listitem> + + <listitem> + <para>如何為無碟系統設定網路開機。</para> + </listitem> + + <listitem> + <para>如何設定 NAT(Network Address Translation)。</para> + </listitem> + + <listitem> + <para>如何透過 PLIP 方式來連接兩台電腦。</para> + </listitem> + + <listitem> + <para>如何在 FreeBSD 內設定 IPv6。</para> + </listitem> + + <listitem> + <para>如何設定 ATM。</para> + </listitem> + + <listitem> + <para>如何去善用 &os; 的 CARP(Common Access Redundancy Protocol)功能 + 。</para> + </listitem> + </itemizedlist> + + <para>在開始閱讀這章之前，您需要︰</para> + + <itemizedlist> + <listitem> + <para>瞭解 <filename>/etc/rc</filename> 相關 script 的概念。</para> + </listitem> + + <listitem> + <para>熟悉基本常用的網路術語。</para> + </listitem> + + <listitem> + <para>知道如何設定、安裝新的 FreeBSD kernel (<xref linkend="kernelconfig"/>)。</para> + </listitem> + + <listitem> + <para>知道如何透過 port/package 安裝軟體 (<xref linkend="ports"/>) + 。</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1 xml:id="network-routing"> + <info><title>Gateways and Routes</title> + <authorgroup> + <author><personname><firstname>Coranth</firstname><surname>Gryphon</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + <indexterm><primary>routing</primary></indexterm> + <indexterm><primary>gateway</primary></indexterm> + <indexterm><primary>subnet</primary></indexterm> + <para>為了讓一部電腦能找到另一部電腦，因此必需要有一種機制， + 讓這部電腦知道該怎麼做，這個機制就是路由選擇 + (<firstterm>routing</firstterm>)。 + 一條路由(<quote>route</quote>)是由一對位址所定義的：一個是 + <quote>目的地(destination)</quote>以及另一個則是閘道 + (<quote>gateway</quote>)。 + 這對位址表示要送到<emphasis>目的地</emphasis>的封包， + 必須經過<emphasis>閘道</emphasis>。 + 目的地分為三種類型：主機、子網路(subnet)、預設路由( + <quote>default route</quote>。 若都沒有其它的路由可以使用， + 這時就會使用預設路由，稍後我們會對預設路由作進一步的說明。 此外， + 閘道也可分為三種類型：主機、傳輸介面(interface，也稱為 + <quote>links</quote>)、乙太網路硬體位址(MAC addresses)。</para> + + <sect2> + <title>範例</title> + + <para>為了方便說明不同類型的路由選擇(routing)，以下使用 + <command>netstat</command> 指令的結果作為介紹範例：</para> + + <screen>&prompt.user; <userinput>netstat -r</userinput> +Routing tables + +Destination Gateway Flags Refs Use Netif Expire + +default outside-gw UGSc 37 418 ppp0 +localhost localhost UH 0 181 lo0 +test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77 +10.20.30.255 link#1 UHLW 1 2421 +example.com link#1 UC 0 0 +host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0 +host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 => +host2.example.com link#1 UC 0 0 +224 link#1 UC 0 0</screen> + + <indexterm><primary>default route</primary></indexterm> + <para>The first two lines specify the default route (which we + will cover in the <link linkend="network-routing-default">next + section</link>) and the <systemitem>localhost</systemitem> route.</para> + + <indexterm><primary>loopback device</primary></indexterm> + <para>The interface (<literal>Netif</literal> column) that this + routing table specifies to use for + <literal>localhost</literal> is <filename>lo0</filename>, + also known as the loopback device. This says to keep all + traffic for this destination internal, rather than sending it + out over the LAN, since it will only end up back where it + started.</para> + + <indexterm> + <primary>Ethernet</primary> + <secondary>MAC address</secondary> + </indexterm> + <para>The next thing that stands out are the addresses beginning + with <systemitem class="etheraddress">0:e0:</systemitem>. These are Ethernet + hardware addresses, which are also known as MAC addresses. + FreeBSD will automatically identify any hosts + (<systemitem>test0</systemitem> in the example) on the local Ethernet + and add a route for that host, directly to it over the + Ethernet interface, <filename>ed0</filename>. There is + also a timeout (<literal>Expire</literal> column) associated + with this type of route, which is used if we fail to hear from + the host in a specific amount of time. When this happens, the + route to this host will be automatically deleted. These hosts + are identified using a mechanism known as RIP (Routing + Information Protocol), which figures out routes to local hosts + based upon a shortest path determination.</para> + + <indexterm><primary>subnet</primary></indexterm> + <para>FreeBSD will also add subnet routes for the local subnet (<systemitem class="ipaddress">10.20.30.255</systemitem> is the broadcast address for the + subnet <systemitem class="ipaddress">10.20.30</systemitem>, and <systemitem class="fqdomainname">example.com</systemitem> is the domain name associated + with that subnet). The designation <literal>link#1</literal> refers + to the first Ethernet card in the machine. You will notice no + additional interface is specified for those.</para> + + <para>Both of these groups (local network hosts and local subnets) have + their routes automatically configured by a daemon called + <application>routed</application>. If this is not run, then only + routes which are statically defined (i.e. entered explicitly) will + exist.</para> + + <para>The <literal>host1</literal> line refers to our host, which it + knows by Ethernet address. Since we are the sending host, FreeBSD + knows to use the loopback interface (<filename>lo0</filename>) + rather than sending it out over the Ethernet interface.</para> + + <para>The two <literal>host2</literal> lines are an example of + what happens when we use an &man.ifconfig.8; alias (see the + section on Ethernet for reasons why we would do this). The + <literal>=></literal> symbol after the + <filename>lo0</filename> interface says that not only are + we using the loopback (since this address also refers to the + local host), but specifically it is an alias. Such routes + only show up on the host that supports the alias; all other + hosts on the local network will simply have a + <literal>link#1</literal> line for such routes.</para> + + <para>The final line (destination subnet <systemitem class="ipaddress">224</systemitem>) deals + with multicasting, which will be covered in another section.</para> + + <para>Finally, various attributes of each route can be seen in + the <literal>Flags</literal> column. Below is a short table + of some of these flags and their meanings:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="4*"/> + + <tbody> + <row> + <entry>U</entry> + <entry>Up: The route is active.</entry> + </row> + + <row> + <entry>H</entry> + <entry>Host: The route destination is a single host.</entry> + </row> + + <row> + <entry>G</entry> + <entry>Gateway: Send anything for this destination on to this + remote system, which will figure out from there where to send + it.</entry> + </row> + + <row> + <entry>S</entry> + <entry>Static: This route was configured manually, not + automatically generated by the system.</entry> + </row> + + <row> + <entry>C</entry> + <entry>Clone: Generates a new route based upon this route for + machines we connect to. This type of route is normally used + for local networks.</entry> + </row> + + <row> + <entry>W</entry> + <entry>WasCloned: Indicated a route that was auto-configured + based upon a local area network (Clone) route.</entry> + </row> + + <row> + <entry>L</entry> + <entry>Link: Route involves references to Ethernet + hardware.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + + <sect2 xml:id="network-routing-default"> + <title>Default Routes</title> + + <indexterm><primary>default route</primary></indexterm> + <para>When the local system needs to make a connection to a remote host, + it checks the routing table to determine if a known path exists. If + the remote host falls into a subnet that we know how to reach (Cloned + routes), then the system checks to see if it can connect along that + interface.</para> + + <para>If all known paths fail, the system has one last option: the + <quote>default</quote> route. This route is a special type of gateway + route (usually the only one present in the system), and is always + marked with a <literal>c</literal> in the flags field. For hosts on a + local area network, this gateway is set to whatever machine has a + direct connection to the outside world (whether via PPP link, + DSL, cable modem, T1, or another network interface).</para> + + <para>If you are configuring the default route for a machine which + itself is functioning as the gateway to the outside world, then the + default route will be the gateway machine at your Internet Service + Provider's (ISP) site.</para> + + <para>Let us look at an example of default routes. This is a common + configuration:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="advanced-networking/net-routing"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> +[Local2] <--ether--> [Local1] <--PPP--> [ISP-Serv] <--ether--> [T1-GW] + </literallayout> + </textobject> + </mediaobject> + + <para>The hosts <systemitem>Local1</systemitem> and + <systemitem>Local2</systemitem> are at your site. + <systemitem>Local1</systemitem> is connected to an ISP via a dial up + PPP connection. This PPP server computer is connected through + a local area network to another gateway computer through an + external interface to the ISPs Internet feed.</para> + + <para>The default routes for each of your machines will be:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>Host</entry> + <entry>Default Gateway</entry> + <entry>Interface</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Local2</entry> + <entry>Local1</entry> + <entry>Ethernet</entry> + </row> + + <row> + <entry>Local1</entry> + <entry>T1-GW</entry> + <entry>PPP</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>A common question is <quote>Why (or how) would we set + the <systemitem>T1-GW</systemitem> to be the default gateway for + <systemitem>Local1</systemitem>, rather than the ISP server it is + connected to?</quote>.</para> + + <para>Remember, since the PPP interface is using an address on the ISP's + local network for your side of the connection, routes for any other + machines on the ISP's local network will be automatically generated. + Hence, you will already know how to reach the <systemitem>T1-GW</systemitem> + machine, so there is no need for the intermediate step + of sending traffic to the ISP server.</para> + + <para>It is common to use the address <systemitem class="ipaddress">X.X.X.1</systemitem> as the gateway address for your local + network. So (using the same example), if your local class-C address + space was <systemitem class="ipaddress">10.20.30</systemitem> and your ISP was + using <systemitem class="ipaddress">10.9.9</systemitem> then the default routes + would be:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Host</entry> + <entry>Default Route</entry> + </row> + </thead> + <tbody> + <row> + <entry>Local2 (10.20.30.2)</entry> + <entry>Local1 (10.20.30.1)</entry> + </row> + <row> + <entry>Local1 (10.20.30.1, 10.9.9.30)</entry> + <entry>T1-GW (10.9.9.1)</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>You can easily define the default route via the + <filename>/etc/rc.conf</filename> file. In our example, on the + <systemitem>Local2</systemitem> machine, we added the following line + in <filename>/etc/rc.conf</filename>:</para> + + <programlisting>defaultrouter="10.20.30.1"</programlisting> + + <para>It is also possible to do it directly from the command + line with the &man.route.8; command:</para> + + <screen>&prompt.root; <userinput>route add default 10.20.30.1</userinput></screen> + + <para>For more information on manual manipulation of network + routing tables, consult &man.route.8; manual page.</para> + </sect2> + + <sect2> + <title>Dual Homed Hosts</title> + <indexterm><primary>dual homed hosts</primary></indexterm> + <para>There is one other type of configuration that we should cover, and + that is a host that sits on two different networks. Technically, any + machine functioning as a gateway (in the example above, using a PPP + connection) counts as a dual-homed host. But the term is really only + used to refer to a machine that sits on two local-area + networks.</para> + + <para>In one case, the machine has two Ethernet cards, each + having an address on the separate subnets. Alternately, the + machine may only have one Ethernet card, and be using + &man.ifconfig.8; aliasing. The former is used if two + physically separate Ethernet networks are in use, the latter + if there is one physical network segment, but two logically + separate subnets.</para> + + <para>Either way, routing tables are set up so that each subnet knows + that this machine is the defined gateway (inbound route) to the other + subnet. This configuration, with the machine acting as a router + between the two subnets, is often used when we need to implement + packet filtering or firewall security in either or both + directions.</para> + + <para>If you want this machine to actually forward packets + between the two interfaces, you need to tell FreeBSD to enable + this ability. See the next section for more details on how + to do this.</para> + </sect2> + + <sect2 xml:id="network-dedicated-router"> + <title>Building a Router</title> + + <indexterm><primary>router</primary></indexterm> + + <para>A network router is simply a system that forwards packets + from one interface to another. Internet standards and good + engineering practice prevent the FreeBSD Project from enabling + this by default in FreeBSD. You can enable this feature by + changing the following variable to <literal>YES</literal> in + &man.rc.conf.5;:</para> + + <programlisting>gateway_enable=YES # Set to YES if this host will be a gateway</programlisting> + + <para>This option will set the &man.sysctl.8; variable + <varname>net.inet.ip.forwarding</varname> to + <literal>1</literal>. If you should need to stop routing + temporarily, you can reset this to <literal>0</literal> temporarily.</para> + + <para>Your new router will need routes to know where to send the + traffic. If your network is simple enough you can use static + routes. FreeBSD also comes with the standard BSD routing + daemon &man.routed.8;, which speaks RIP (both version 1 and + version 2) and IRDP. Support for BGP v4, OSPF v2, and other + sophisticated routing protocols is available with the + <package>net/zebra</package> package. + Commercial products such as <application>&gated;</application> are also available for more + complex network routing solutions.</para> + +<indexterm><primary>BGP</primary></indexterm> +<indexterm><primary>RIP</primary></indexterm> +<indexterm><primary>OSPF</primary></indexterm> + </sect2> + + <sect2> + <info><title>Setting Up Static Routes</title> + <authorgroup> + <author><personname><firstname>Al</firstname><surname>Hoang</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + <!-- Feb 2004 --> + + + <sect3> + <title>Manual Configuration</title> + + <para>Let us assume we have a network as follows:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="advanced-networking/static-routes"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> + INTERNET + | (10.0.0.1/24) Default Router to Internet + | + |Interface xl0 + |10.0.0.10/24 + +------+ + | | RouterA + | | (FreeBSD gateway) + +------+ + | Interface xl1 + | 192.168.1.1/24 + | + +--------------------------------+ + Internal Net 1 | 192.168.1.2/24 + | + +------+ + | | RouterB + | | + +------+ + | 192.168.2.1/24 + | + Internal Net 2 + </literallayout> + </textobject> + </mediaobject> + + <para>In this scenario, <systemitem>RouterA</systemitem> is our &os; + machine that is acting as a router to the rest of the + Internet. It has a default route set to <systemitem class="ipaddress">10.0.0.1</systemitem> which allows it to connect + with the outside world. We will assume that + <systemitem>RouterB</systemitem> is already configured properly and + knows how to get wherever it needs to go. (This is simple + in this picture. Just add a default route on + <systemitem>RouterB</systemitem> using <systemitem class="ipaddress">192.168.1.1</systemitem> as the gateway.)</para> + + <para>If we look at the routing table for + <systemitem>RouterA</systemitem> we would see something like the + following:</para> + + <screen>&prompt.user; <userinput>netstat -nr</userinput> +Routing tables + +Internet: +Destination Gateway Flags Refs Use Netif Expire +default 10.0.0.1 UGS 0 49378 xl0 +127.0.0.1 127.0.0.1 UH 0 6 lo0 +10.0.0/24 link#1 UC 0 0 xl0 +192.168.1/24 link#2 UC 0 0 xl1</screen> + + <para>With the current routing table <systemitem>RouterA</systemitem> + will not be able to reach our Internal Net 2. It does not + have a route for <systemitem class="ipaddress">192.168.2.0/24</systemitem>. One way to alleviate + this is to manually add the route. The following command + would add the Internal Net 2 network to + <systemitem>RouterA</systemitem>'s routing table using <systemitem class="ipaddress">192.168.1.2</systemitem> as the next hop:</para> + + <screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen> + + <para>Now <systemitem>RouterA</systemitem> can reach any hosts on the + <systemitem class="ipaddress">192.168.2.0/24</systemitem> + network.</para> + </sect3> + + <sect3> + <title>Persistent Configuration</title> + + <para>The above example is perfect for configuring a static + route on a running system. However, one problem is that the + routing information will not persist if you reboot your &os; + machine. The way to handle the addition of a static route + is to put it in your <filename>/etc/rc.conf</filename> + file:</para> + + <programlisting># Add Internal Net 2 as a static route +static_routes="internalnet2" +route_internalnet2="-net 192.168.2.0/24 192.168.1.2"</programlisting> + + <para>The <literal>static_routes</literal> configuration + variable is a list of strings separated by a space. Each + string references to a route name. In our above example we + only have one string in <literal>static_routes</literal>. + This string is <replaceable>internalnet2</replaceable>. We + then add a configuration variable called + <literal>route_internalnet2</literal> + where we put all of the configuration parameters we would + give to the &man.route.8; command. For our example above we + would have used the command:</para> + + <screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen> + + <para>so we need <literal>"-net 192.168.2.0/24 192.168.1.2"</literal>.</para> + + <para>As said above, we can have more than one string in + <literal>static_routes</literal>. This allows us to + create multiple static routes. The following lines shows + an example of adding static routes for the <systemitem class="ipaddress">192.168.0.0/24</systemitem> and <systemitem class="ipaddress">192.168.1.0/24</systemitem> networks on an imaginary + router:</para> + + <programlisting>static_routes="net1 net2" +route_net1="-net 192.168.0.0/24 192.168.0.1" +route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting> + </sect3> + </sect2> + + <sect2> + <title>Routing Propagation</title> + <indexterm><primary>routing propagation</primary></indexterm> + <para>We have already talked about how we define our routes to the + outside world, but not about how the outside world finds us.</para> + + <para>We already know that routing tables can be set up so that all + traffic for a particular address space (in our examples, a class-C + subnet) can be sent to a particular host on that network, which will + forward the packets inbound.</para> + + <para>When you get an address space assigned to your site, your service + provider will set up their routing tables so that all traffic for your + subnet will be sent down your PPP link to your site. But how do sites + across the country know to send to your ISP?</para> + + <para>There is a system (much like the distributed DNS information) that + keeps track of all assigned address-spaces, and defines their point of + connection to the Internet Backbone. The <quote>Backbone</quote> are + the main trunk lines that carry Internet traffic across the country, + and around the world. Each backbone machine has a copy of a master + set of tables, which direct traffic for a particular network to a + specific backbone carrier, and from there down the chain of service + providers until it reaches your network.</para> + + <para>It is the task of your service provider to advertise to the + backbone sites that they are the point of connection (and thus the + path inward) for your site. This is known as route + propagation.</para> + </sect2> + + <sect2> + <title>Troubleshooting</title> + <indexterm> + <primary><command>traceroute</command></primary> + </indexterm> + <para>Sometimes, there is a problem with routing propagation, and some + sites are unable to connect to you. Perhaps the most useful command + for trying to figure out where routing is breaking down is the + &man.traceroute.8; command. It is equally useful if you cannot seem + to make a connection to a remote machine (i.e. &man.ping.8; + fails).</para> + + <para>The &man.traceroute.8; command is run with the name of the remote + host you are trying to connect to. It will show the gateway hosts + along the path of the attempt, eventually either reaching the target + host, or terminating because of a lack of connection.</para> + + <para>For more information, see the manual page for + &man.traceroute.8;.</para> + </sect2> + + <sect2> + <title>Multicast Routing</title> + <indexterm> + <primary>multicast routing</primary> + </indexterm> + <indexterm> + <primary>kernel options</primary> + <secondary>MROUTING</secondary> + </indexterm> + <para>FreeBSD supports both multicast applications and multicast + routing natively. Multicast applications do not require any + special configuration of FreeBSD; applications will generally + run out of the box. Multicast routing + requires that support be compiled into the kernel:</para> + + <programlisting>options MROUTING</programlisting> + + <para>In addition, the multicast routing daemon, &man.mrouted.8; + must be configured to set up tunnels and <acronym>DVMRP</acronym> via + <filename>/etc/mrouted.conf</filename>. More details on + multicast configuration may be found in the manual page for + &man.mrouted.8;.</para> + </sect2> + </sect1> + + <sect1 xml:id="network-wireless"> + <info><title>Wireless Networking</title> + <authorgroup> + <author><personname><othername>Loader</othername></personname></author> + + <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname></author> + + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname></author> + </authorgroup> + </info> + + + <indexterm><primary>wireless networking</primary></indexterm> + <indexterm> + <primary>802.11</primary> + <see>wireless networking</see> + </indexterm> + + <sect2> + <title>Wireless Networking Basics</title> + + <para>Most wireless networks are based on the IEEE 802.11 + standards. A basic wireless network consists of multiple + stations communicating with radios that broadcast in either + the 2.4GHz or 5GHz band (though this varies according to the + locale and is also changing to enable communication in the + 2.3GHz and 4.9GHz ranges).</para> + + <para>802.11 networks are organized in two ways: in + <emphasis>infrastructure mode</emphasis> one station acts as a + master with all the other stations associating to it; the + network is known as a BSS and the master station is termed an + access point (AP). In a BSS all communication passes through + the AP; even when one station wants to communicate with + another wireless station messages must go through the AP. In + the second form of network there is no master and stations + communicate directly. This form of network is termed an IBSS + and is commonly known as an <emphasis>ad-hoc + network</emphasis>.</para> + + <para>802.11 networks were first deployed in the 2.4GHz band + using protocols defined by the IEEE 802.11 and 802.11b + standard. These specifications include the operating + frequencies, MAC layer characteristics including framing and + transmission rates (communication can be done at various + rates). Later the 802.11a standard defined operation in the + 5GHz band, including different signalling mechanisms and + higher transmission rates. Still later the 802.11g standard + was defined to enable use of 802.11a signalling and + transmission mechanisms in the 2.4GHz band in such a way as to + be backwards compatible with 802.11b networks.</para> + + <para>Separate from the underlying transmission techniques + 802.11 networks have a variety of security mechanisms. The + original 802.11 specifications defined a simple security + protocol called WEP. This protocol uses a fixed pre-shared key + and the RC4 cryptographic cipher to encode data transmitted on + a network. Stations must all agree on the fixed key in order + to communicate. This scheme was shown to be easily broken and + is now rarely used except to discourage transient users from + joining networks. Current security practice is given by the + IEEE 802.11i specification that defines new cryptographic + ciphers and an additional protocol to authenticate stations to + an access point and exchange keys for doing data + communication. Further, cryptographic keys are periodically + refreshed and there are mechanisms for detecting intrusion + attempts (and for countering intrusion attempts). Another + security protocol specification commonly used in wireless + networks is termed WPA. This was a precursor to 802.11i + defined by an industry group as an interim measure while + waiting for 802.11i to be ratified. WPA specifies a subset of + the requirements found in 802.11i and is designed for + implementation on legacy hardware. Specifically WPA requires + only the TKIP cipher that is derived from the original WEP + cipher. 802.11i permits use of TKIP but also requires support + for a stronger cipher, AES-CCM, for encrypting data. (The AES + cipher was not required in WPA because it was deemed too + computationally costly to be implemented on legacy + hardware.)</para> + + <para>Other than the above protocol standards the other + important standard to be aware of is 802.11e. This defines + protocols for deploying multi-media applications such as + streaming video and voice over IP (VoIP) in an 802.11 network. + Like 802.11i, 802.11e also has a precursor specification + termed WME (later renamed WMM) that has been defined by an + industry group as a subset of 802.11e that can be deployed now + to enable multi-media applications while waiting for the final + ratification of 802.11e. The most important thing to know + about 802.11e and WME/WMM is that it enables prioritized + traffic use of a wireless network through Quality of Service + (QoS) protocols and enhanced media access protocols. Proper + implementation of these protocols enable high speed bursting + of data and prioritized traffic flow.</para> + + <para>Since the 6.0 version, &os; supports networks that operate + using 802.11a, 802.11b, and 802.11g. The WPA and 802.11i + security protocols are likewise supported (in conjunction with + any of 11a, 11b, and 11g) and QoS and traffic prioritization + required by the WME/WMM protocols are supported for a limited + set of wireless devices.</para> + </sect2> + + <sect2 xml:id="network-wireless-basic"> + <title>Basic Setup</title> + + <sect3> + <title>Kernel Configuration</title> + + <para>To use wireless networking you need a wireless + networking card and to configure the kernel with the + appropriate wireless networking support. The latter is + separated into multiple modules so that you only need to + configure the software you are actually going to use.</para> + + <para>The first thing you need is a wireless device. The most + commonly used devices are those that use parts made by + Atheros. These devices are supported by the &man.ath.4; + driver and require the following line to be added to the + <filename>/boot/loader.conf</filename> file:</para> + + <programlisting>if_ath_load="YES"</programlisting> + + <para>The Atheros driver is split up into three separate + pieces: the driver proper (&man.ath.4;), the hardware + support layer that handles chip-specific functions + (&man.ath.hal.4;), and an algorithm for selecting which of + several possible rates for transmitting frames + (ath_rate_sample here). When you load this support as + modules these dependencies are automatically handled for + you. If instead of an Atheros device you had another device + you would select the module for that device; e.g.:</para> + + <programlisting>if_wi_load="YES"</programlisting> + + <para>for devices based on the Intersil Prism parts + (&man.wi.4; driver).</para> + + <note> + <para>In the rest of this document, we will use an + &man.ath.4; device, the device name in the examples must + be changed according to your configuration. A list of + available wireless drivers can be found at the beginning + of the &man.wlan.4; manual page. If a native &os; driver + for your wireless device does not exist, it may be + possible to directly use the &windows; driver with the + help of the <link linkend="config-network-ndis">NDIS</link> driver + wrapper.</para> + </note> + + <para>With a device driver configured you need to also bring + in the 802.11 networking support required by the driver. + For the &man.ath.4; driver this is at least the &man.wlan.4; + module; this module is automatically loaded with the + wireless device driver. With that you will need the modules + that implement cryptographic support for the security + protocols you intend to use. These are intended to be + dynamically loaded on demand by the &man.wlan.4; module but + for now they must be manually configured. The following + modules are available: &man.wlan.wep.4;, &man.wlan.ccmp.4; + and &man.wlan.tkip.4;. Both &man.wlan.ccmp.4; and + &man.wlan.tkip.4; drivers are only needed if you intend to + use the WPA and/or 802.11i security protocols. If your + network is to run totally open (i.e., with no encryption) + then you do not even need the &man.wlan.wep.4; support. To + load these modules at boot time, add the following lines to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>wlan_wep_load="YES" +wlan_ccmp_load="YES" +wlan_tkip_load="YES"</programlisting> + + <para>With this information in the system bootstrap + configuration file (i.e., + <filename>/boot/loader.conf</filename>), you have to reboot + your &os; box. If you do not want to reboot your machine + for the moment, you can just load the modules by hand using + &man.kldload.8;.</para> + + <note> + <para>If you do not want to use modules, it is possible to + compile these drivers into the kernel by adding the + following lines to your kernel configuration file:</para> + + <programlisting>device ath # Atheros IEEE 802.11 wireless network driver +device ath_hal # Atheros Hardware Access Layer +device ath_rate_sample # John Bicket's SampleRate control algorithm. +device wlan # 802.11 support (Required) +device wlan_wep # WEP crypto support for 802.11 devices +device wlan_ccmp # AES-CCMP crypto support for 802.11 devices +device wlan_tkip # TKIP and Michael crypto support for 802.11 devices</programlisting> + + <para>With this information in the kernel configuration + file, recompile the kernel and reboot your &os; + machine.</para> + </note> + + <para>When the system is up, we could find some information + about the wireless device in the boot messages, like + this:</para> + + <screen>ath0: <Atheros 5212> mem 0xff9f0000-0xff9fffff irq 17 at device 2.0 on pci2 +ath0: Ethernet address: 00:11:95:d5:43:62 +ath0: mac 7.9 phy 4.5 radio 5.6</screen> + </sect3> + </sect2> + + <sect2> + <title>Infrastructure Mode</title> + + <para>The infrastructure mode or BSS mode is the mode that is + typically used. In this mode, a number of wireless access + points are connected to a wired network. Each wireless + network has its own name, this name is called the SSID of the + network. Wireless clients connect to the wireless access + points.</para> + + <sect3> + <title>&os; Clients</title> + + <sect4> + <title>How to Find Access Points</title> + + <para>To scan for networks, use the + <command>ifconfig</command> command. This request may + take a few moments to complete as it requires that the + system switches to each available wireless frequency and + probes for available access points. Only the super-user + can initiate such a scan:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 up scan</userinput> +SSID BSSID CHAN RATE S:N INT CAPS +dlinkap 00:13:46:49:41:76 6 54M 29:0 100 EPS WPA WME +freebsdap 00:11:95:c3:0d:ac 1 54M 22:0 100 EPS WPA</screen> + + <note> + <para>You must mark the interface <option>up</option> + before you can scan. Subsequent scan requests do not + require you to mark the interface up again.</para> + </note> + + <para>The output of a scan request lists each BSS/IBSS + network found. Beside the name of the network, + <literal>SSID</literal>, we find the + <literal>BSSID</literal> which is the MAC address of the + access point. The <literal>CAPS</literal> field + identifies the type of each network and the capabilities + of the stations operating there:</para> + + <variablelist> + <varlistentry> + <term><literal>E</literal></term> + + <listitem> + <para>Extended Service Set (ESS). Indicates that the + station is part of an infrastructure network (in + contrast to an IBSS/ad-hoc network).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>I</literal></term> + + <listitem> + <para>IBSS/ad-hoc network. Indicates that the station + is part of an ad-hoc network (in contrast to an ESS + network).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>P</literal></term> + + <listitem> + <para>Privacy. Data confidentiality is required for + all data frames exchanged within the BSS. This means + that this BSS requires the station to use + cryptographic means such as WEP, TKIP or AES-CCMP to + encrypt/decrypt data frames being exchanged with + others.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>S</literal></term> + + <listitem> + <para>Short Preamble. Indicates that the network is + using short preambles (defined in 802.11b High + Rate/DSSS PHY, short preamble utilizes a 56 bit sync + field in contrast to a 128 bit field used in long + preamble mode).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>s</literal></term> + + <listitem> + <para>Short slot time. Indicates that the 802.11g + network is using a short slot time because there are + no legacy (802.11b) stations present.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>One can also display the current list of known + networks with:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 list scan</userinput></screen> + + <para>This information may be updated automatically by the + adapter or manually with a <option>scan</option> request. + Old data is automatically removed from the cache, so over + time this list may shrink unless more scans are + done.</para> + </sect4> + + <sect4> + <title>Basic Settings</title> + + <para>This section provides a simple example of how to make + the wireless network adapter work in &os; without + encryption. After you are familiar with these concepts, + we strongly recommend using <link linkend="network-wireless-wpa">WPA</link> to set up your + wireless network.</para> + + <para>There are three basic steps to configure a wireless + network: selecting an access point, authenticating your + station, and configuring an IP address. The following + sections discuss each step.</para> + + <sect5> + <title>Selecting an Access Point</title> + + <para>Most of time it is sufficient to let the system + choose an access point using the builtin heuristics. + This is the default behaviour when you mark an interface + up or otherwise configure an interface by listing it in + <filename>/etc/rc.conf</filename>, e.g.:</para> + + <programlisting>ifconfig_ath0="DHCP"</programlisting> + + <para>If there are multiple access points and you want to + select a specific one, you can select it by its + SSID:</para> + + <programlisting>ifconfig_ath0="ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting> + + <para>In an environment where there are multiple access + points with the same SSID (often done to simplify + roaming) it may be necessary to associate to one + specific device. In this case you can also specify the + BSSID of the access point (you can also leave off the + SSID):</para> + + <programlisting>ifconfig_ath0="ssid <replaceable>your_ssid_here</replaceable> bssid <replaceable>xx:xx:xx:xx:xx:xx</replaceable> DHCP"</programlisting> + + <para>There are other ways to constrain the choice of an + access point such as limiting the set of frequencies the + system will scan on. This may be useful if you have a + multi-band wireless card as scanning all the possible + channels can be time-consuming. To limit operation to a + specific band you can use the <option>mode</option> + parameter; e.g.:</para> + + <programlisting>ifconfig_ath0="mode <replaceable>11g</replaceable> ssid <replaceable>your_ssid_here</replaceable> DHCP"</programlisting> + + <para>will force the card to operate in 802.11g which is + defined only for 2.4GHz frequencies so any 5GHz channels + will not be considered. Other ways to do this are the + <option>channel</option> parameter, to lock operation to + one specific frequency, and the + <option>chanlist</option> parameter, to specify a list + of channels for scanning. More information about these + parameters can be found in the &man.ifconfig.8; manual + page.</para> + </sect5> + + <sect5> + <title>Authentication</title> + + <para>Once you have selected an access point your station + needs to authenticate before it can pass data. + Authentication can happen in several ways. The most + common scheme used is termed open authentication and + allows any station to join the network and communicate. + This is the authentication you should use for test + purpose the first time you set up a wireless network. + Other schemes require cryptographic handshakes be + completed before data traffic can flow; either using + pre-shared keys or secrets, or more complex schemes that + involve backend services such as RADIUS. Most users + will use open authentication which is the default + setting. Next most common setup is WPA-PSK, also known + as WPA Personal, which is described <link linkend="network-wireless-wpa-wpa-psk">below</link>.</para> + + <note> + <para>If you have an &apple; &airport; Extreme base + station for an access point you may need to configure + shared-key authentication together with a WEP key. + This can be done in the + <filename>/etc/rc.conf</filename> file or using the + &man.wpa.supplicant.8; program. If you have a single + &airport; base station you can setup access with + something like:</para> + + <programlisting>ifconfig_ath0="authmode shared wepmode on weptxkey <replaceable>1</replaceable> wepkey <replaceable>01234567</replaceable> DHCP"</programlisting> + + <para>In general shared key authentication is to be + avoided because it uses the WEP key material in a + highly-constrained manner making it even easier to + crack the key. If WEP must be used (e.g., for + compatibility with legacy devices) it is better to use + WEP with <literal>open</literal> authentication. More + information regarding WEP can be found in the <xref linkend="network-wireless-wep"/>.</para> + </note> + </sect5> + + <sect5> + <title>Getting an IP Address with DHCP</title> + + <para>Once you have selected an access point and set the + authentication parameters, you will have to get an IP + address to communicate. Most of time you will obtain + your wireless IP address via DHCP. To achieve that, + simply edit <filename>/etc/rc.conf</filename> and add + <literal>DHCP</literal> to the configuration for your + device as shown in various examples above:</para> + + <programlisting>ifconfig_ath0="DHCP"</programlisting> + + <para>At this point, you are ready to bring up the + wireless interface:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput></screen> + + <para>Once the interface is running, use + <command>ifconfig</command> to see the status of the + interface <filename>ath0</filename>:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0</userinput> +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/54Mbps) + status: associated + ssid dlinkap channel 6 bssid 00:13:46:49:41:76 + authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen> + + <para>The <literal>status: associated</literal> means you + are connected to the wireless network (to the + <literal>dlinkap</literal> network in our case). The + <literal>bssid 00:13:46:49:41:76</literal> part is the + MAC address of your access point; the + <literal>authmode</literal> line informs you that the + communication is not encrypted + (<literal>OPEN</literal>).</para> + </sect5> + + <sect5> + <title>Static IP Address</title> + + <para>In the case you cannot obtain an IP address from a + DHCP server, you can set a fixed IP address. Replace + the <literal>DHCP</literal> keyword shown above with the + address information. Be sure to retain any other + parameters you have set up for selecting an access + point:</para> + + <programlisting>ifconfig_ath0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>your_ssid_here</replaceable>"</programlisting> + </sect5> + </sect4> + + <sect4 xml:id="network-wireless-wpa"> + <title>WPA</title> + + <para>WPA (Wi-Fi Protected Access) is a security protocol + used together with 802.11 networks to address the lack of + proper authentication and the weakness of <link linkend="network-wireless-wep">WEP</link>. WPA leverages + the 802.1X authentication protocol and uses one of several + ciphers instead of WEP for data integrity. The only + cipher required by WPA is TKIP (Temporary Key Integrity + Protocol) which is a cipher that extends the basic RC4 + cipher used by WEP by adding integrity checking, tamper + detection, and measures for responding to any detected + intrusions. TKIP is designed to work on legacy hardware + with only software modification; it represents a + compromise that improves security but is still not + entirely immune to attack. WPA also specifies the + AES-CCMP cipher as an alternative to TKIP and that is + preferred when possible; for this specification the term + WPA2 (or RSN) is commonly used.</para> + + <para>WPA defines authentication and encryption protocols. + Authentication is most commonly done using one of two + techniques: by 802.1X and a backend authentication service + such as RADIUS, or by a minimal handshake between the + station and the access point using a pre-shared secret. + The former is commonly termed WPA Enterprise with the + latter known as WPA Personal. Since most people will not + set up a RADIUS backend server for wireless network, + WPA-PSK is by far the most commonly encountered + configuration for WPA.</para> + + <para>The control of the wireless connection and the + authentication (key negotiation or authentication with a + server) is done with the &man.wpa.supplicant.8; utility. + This program requires a configuration file, + <filename>/etc/wpa_supplicant.conf</filename>, to run. + More information regarding this file can be found in the + &man.wpa.supplicant.conf.5; manual page.</para> + + <sect5 xml:id="network-wireless-wpa-wpa-psk"> + <title>WPA-PSK</title> + + <para>WPA-PSK also known as WPA-Personal is based on a + pre-shared key (PSK) generated from a given password and + that will be used as the master key in the wireless + network. This means every wireless user will share the + same key. WPA-PSK is intended for small networks where + the use of an authentication server is not possible or + desired.</para> + + <warning> + <para>Always use strong passwords that are + sufficiently long and made from a rich alphabet so + they will not be guessed and/or attacked.</para> + </warning> + + <para>The first step is the configuration of the + <filename>/etc/wpa_supplicant.conf</filename> file with + the SSID and the pre-shared key of your network:</para> + + <programlisting>network={ + ssid="freebsdap" + psk="freebsdmall" +}</programlisting> + + <para>Then, in <filename>/etc/rc.conf</filename>, we + indicate that the wireless device configuration will be + done with WPA and the IP address will be obtained with + DHCP:</para> + + <programlisting>ifconfig_ath0="WPA DHCP"</programlisting> + + <para>Then, we can bring up the interface:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput> +Starting wpa_supplicant. +DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 5 +DHCPDISCOVER on ath0 to 255.255.255.255 port 67 interval 6 +DHCPOFFER from 192.168.0.1 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.1 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36 + protmode CTS roaming MANUAL bintval 100</screen> + + <para>Or you can try to configure it manually using the + same <filename>/etc/wpa_supplicant.conf</filename> <link linkend="network-wireless-wpa-wpa-psk">above</link>, and + run:</para> + + <screen>&prompt.root; <userinput>wpa_supplicant -i ath0 -c /etc/wpa_supplicant.conf</userinput> +Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz) +Associated with 00:11:95:c3:0d:ac +WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=TKIP GTK=TKIP]</screen> + + <para>The next operation is the launch of the + <command>dhclient</command> command to get the IP + address from the DHCP server:</para> + + <screen>&prompt.root; <userinput>dhclient ath0</userinput> +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.1 +bound to 192.168.0.254 -- renewal in 300 seconds. +&prompt.root; <userinput>ifconfig ath0</userinput> +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/48Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36 + protmode CTS roaming MANUAL bintval 100</screen> + + <note> + <para>If the <filename>/etc/rc.conf</filename> is set up + with the line <literal>ifconfig_ath0="DHCP"</literal> + then it is no need to run the + <command>dhclient</command> command manually, + <command>dhclient</command> will be launched after + <command>wpa_supplicant</command> plumbs the + keys.</para> + </note> + + <para>In the case where the use of DHCP is not possible, + you can set a static IP address after + <command>wpa_supplicant</command> has authenticated the + station:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 inet 192.168.0.100 netmask 255.255.255.0</userinput> +&prompt.root; <userinput>ifconfig ath0</userinput> +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/36Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA privacy ON deftxkey UNDEF TKIP 2:128-bit txpowmax 36 + protmode CTS roaming MANUAL bintval 100</screen> + + <para>When DHCP is not used, you also have to manually set + up the default gateway and the nameserver:</para> + + <screen>&prompt.root; <userinput>route add default your_default_router</userinput> +&prompt.root; <userinput>echo "nameserver your_DNS_server" >> /etc/resolv.conf</userinput></screen> + </sect5> + + <sect5 xml:id="network-wireless-wpa-eap-tls"> + <title>WPA with EAP-TLS</title> + + <para>The second way to use WPA is with an 802.1X backend + authentication server, in this case WPA is called + WPA-Enterprise to make difference with the less secure + WPA-Personal with its pre-shared key. The + authentication in WPA-Enterprise is based on EAP + (Extensible Authentication Protocol).</para> + + <para>EAP does not come with an encryption method, it was + decided to embed EAP inside an encrypted tunnel. Many + types of EAP authentication methods have been designed, + the most common methods are EAP-TLS, EAP-TTLS and + EAP-PEAP.</para> + + <para>EAP-TLS (EAP with Transport Layer Security) is a + very well-supported authentication protocol in the + wireless world since it was the first EAP method to be + certified by the <link xlink:href="http://www.wi-fi.org/">Wi-Fi alliance</link>. + EAP-TLS will require three certificates to run: the CA + certificate (installed on all machines), the server + certificate for your authentication server, and one + client certificate for each wireless client. In this + EAP method, both authentication server and wireless + client authenticate each other in presenting their + respective certificates, and they verify that these + certificates were signed by your organization's + certificate authority (CA).</para> + + <para>As previously, the configuration is done via + <filename>/etc/wpa_supplicant.conf</filename>:</para> + + <programlisting>network={ + ssid="freebsdap" <co xml:id="co-tls-ssid"/> + proto=RSN <co xml:id="co-tls-proto"/> + key_mgmt=WPA-EAP <co xml:id="co-tls-kmgmt"/> + eap=TLS <co xml:id="co-tls-eap"/> + identity="loader" <co xml:id="co-tls-id"/> + ca_cert="/etc/certs/cacert.pem" <co xml:id="co-tls-cacert"/> + client_cert="/etc/certs/clientcert.pem" <co xml:id="co-tls-clientcert"/> + private_key="/etc/certs/clientkey.pem" <co xml:id="co-tls-pkey"/> + private_key_passwd="freebsdmallclient" <co xml:id="co-tls-pwd"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-tls-ssid"> + <para>This field indicates the network name + (SSID).</para> + </callout> + + <callout arearefs="co-tls-proto"> + <para>Here, we use RSN (IEEE 802.11i) protocol, i.e., + WPA2.</para> + </callout> + + <callout arearefs="co-tls-kmgmt"> + <para>The <literal>key_mgmt</literal> line refers to + the key management protocol we use. In our case it + is WPA using EAP authentication: + <literal>WPA-EAP</literal>.</para> + </callout> + + <callout arearefs="co-tls-eap"> + <para>In this field, we mention the EAP method for our + connection.</para> + </callout> + + <callout arearefs="co-tls-id"> + <para>The <literal>identity</literal> field contains + the identity string for EAP.</para> + </callout> + + <callout arearefs="co-tls-cacert"> + <para>The <literal>ca_cert</literal> field indicates + the pathname of the CA certificate file. This file + is needed to verify the server certificat.</para> + </callout> + + <callout arearefs="co-tls-clientcert"> + <para>The <literal>client_cert</literal> line gives + the pathname to the client certificate file. This + certificate is unique to each wireless client of the + network.</para> + </callout> + + <callout arearefs="co-tls-pkey"> + <para>The <literal>private_key</literal> field is the + pathname to the client certificate private key + file.</para> + </callout> + + <callout arearefs="co-tls-pwd"> + <para>The <literal>private_key_passwd</literal> field + contains the passphrase for the private key.</para> + </callout> + </calloutlist> + + <para>Then add the following line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_ath0="WPA DHCP"</programlisting> + + <para>The next step is to bring up the interface with the + help of the <filename>rc.d</filename> facility:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput> +Starting wpa_supplicant. +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit + txpowmax 36 protmode CTS roaming MANUAL bintval 100</screen> + + <para>As previously shown, it is also possible to bring up + the interface manually with both + <command>wpa_supplicant</command> and + <command>ifconfig</command> commands.</para> + </sect5> + + <sect5 xml:id="network-wireless-wpa-eap-ttls"> + <title>WPA with EAP-TTLS</title> + + <para>With EAP-TLS both the authentication server and the + client need a certificate, with EAP-TTLS (EAP-Tunneled + Transport Layer Security) a client certificate is + optional. This method is close to what some secure web + sites do , where the web server can create a secure SSL + tunnel even if the visitors do not have client-side + certificates. EAP-TTLS will use the encrypted TLS + tunnel for safe transport of the authentication + data.</para> + + <para>The configuration is done via the + <filename>/etc/wpa_supplicant.conf</filename> + file:</para> + + <programlisting>network={ + ssid="freebsdap" + proto=RSN + key_mgmt=WPA-EAP + eap=TTLS <co xml:id="co-ttls-eap"/> + identity="test" <co xml:id="co-ttls-id"/> + password="test" <co xml:id="co-ttls-passwd"/> + ca_cert="/etc/certs/cacert.pem" <co xml:id="co-ttls-cacert"/> + phase2="auth=MD5" <co xml:id="co-ttls-pha2"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-ttls-eap"> + <para>In this field, we mention the EAP method for our + connection.</para> + </callout> + + <callout arearefs="co-ttls-id"> + <para>The <literal>identity</literal> field contains + the identity string for EAP authentication inside + the encrypted TLS tunnel.</para> + </callout> + + <callout arearefs="co-ttls-passwd"> + <para>The <literal>password</literal> field contains + the passphrase for the EAP authentication.</para> + </callout> + + <callout arearefs="co-ttls-cacert"> + <para>The <literal>ca_cert</literal> field indicates + the pathname of the CA certificate file. This file + is needed to verify the server certificat.</para> + </callout> + + <callout arearefs="co-ttls-pha2"> + <para>In this field, we mention the authentication + method used in the encrypted TLS tunnel. In our + case, EAP with MD5-Challenge has been used. The + <quote>inner authentication</quote> phase is often + called <quote>phase2</quote>.</para> + </callout> + </calloutlist> + + <para>You also have to add the following line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_ath0="WPA DHCP"</programlisting> + + <para>The next step is to bring up the interface:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput> +Starting wpa_supplicant. +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit + txpowmax 36 protmode CTS roaming MANUAL bintval 100</screen> + </sect5> + + <sect5 xml:id="network-wireless-wpa-eap-peap"> + <title>WPA with EAP-PEAP</title> + + <para>PEAP (Protected EAP) has been designed as an + alternative to EAP-TTLS. There are two types of PEAP + methods, the most common one is PEAPv0/EAP-MSCHAPv2. In + the rest of this document, we will use the PEAP term to + refer to that EAP method. PEAP is the most used EAP + standard after EAP-TLS, in other words if you have a + network with mixed OSes, PEAP should be the most + supported standard after EAP-TLS.</para> + + <para>PEAP is similar to EAP-TTLS: it uses a server-side + certificate to authenticate clients by creating an + encrypted TLS tunnel between the client and the + authentication server, which protects the ensuing + exchange of authentication information. In term of + security the difference between EAP-TTLS and PEAP is + that PEAP authentication broadcasts the username in + clear, only the password is sent in the encrypted TLS + tunnel. EAP-TTLS will use the TLS tunnel for both + username and password.</para> + + <para>We have to edit the + <filename>/etc/wpa_supplicant.conf</filename> file and + add the EAP-PEAP related settings:</para> + + <programlisting>network={ + ssid="freebsdap" + proto=RSN + key_mgmt=WPA-EAP + eap=PEAP <co xml:id="co-peap-eap"/> + identity="test" <co xml:id="co-peap-id"/> + password="test" <co xml:id="co-peap-passwd"/> + ca_cert="/etc/certs/cacert.pem" <co xml:id="co-peap-cacert"/> + phase1="peaplabel=0" <co xml:id="co-peap-pha1"/> + phase2="auth=MSCHAPV2" <co xml:id="co-peap-pha2"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-peap-eap"> + <para>In this field, we mention the EAP method for our + connection.</para> + </callout> + + <callout arearefs="co-peap-id"> + <para>The <literal>identity</literal> field contains + the identity string for EAP authentication inside + the encrypted TLS tunnel.</para> + </callout> + + <callout arearefs="co-peap-passwd"> + <para>The <literal>password</literal> field contains + the passphrase for the EAP authentication.</para> + </callout> + + <callout arearefs="co-peap-cacert"> + <para>The <literal>ca_cert</literal> field indicates + the pathname of the CA certificate file. This file + is needed to verify the server certificat.</para> + </callout> + + <callout arearefs="co-peap-pha1"> + <para>This field contains the parameters for the + first phase of the authentication (the TLS + tunnel). According to the authentication server + used, you will have to specify a specific label + for the authentication. Most of time, the label + will be <quote>client EAP encryption</quote> which + is set by using <literal>peaplabel=0</literal>. + More information can be found in the + &man.wpa.supplicant.conf.5; manual page.</para> + </callout> + + <callout arearefs="co-peap-pha2"> + <para>In this field, we mention the authentication + protocol used in the encrypted TLS tunnel. In the + case of PEAP, it is + <literal>auth=MSCHAPV2</literal>.</para> + </callout> + </calloutlist> + + <para>The following must be added to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_ath0="WPA DHCP"</programlisting> + + <para>Then, we can bring up the interface:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/netif start</userinput> +Starting wpa_supplicant. +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPREQUEST on ath0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (DS/11Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy ON deftxkey UNDEF TKIP 2:128-bit + txpowmax 36 protmode CTS roaming MANUAL bintval 100</screen> + </sect5> + </sect4> + + <sect4 xml:id="network-wireless-wep"> + <title>WEP</title> + + <para>WEP (Wired Equivalent Privacy) is part of the original + 802.11 standard. There is no authentication mechanism, + only a weak form of access control, and it is easily to be + cracked.</para> + + <para>WEP can be set up with + <command>ifconfig</command>:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 inet 192.168.1.100 netmask 255.255.255.0 ssid my_net \ + wepmode on weptxkey 3 wepkey 3:0x3456789012</userinput></screen> + + <itemizedlist> + <listitem> + <para>The <literal>weptxkey</literal> means which WEP + key will be used in the transmission. Here we used the + third key. This must match the setting in the access + point.</para> + </listitem> + + <listitem> + <para>The <literal>wepkey</literal> means setting the + selected WEP key. It should in the format + <replaceable>index:key</replaceable>, if the index is + not given, key <literal>1</literal> is set. That is + to say we need to set the index if we use keys other + than the first key.</para> + + <note> + <para>You must replace + the <literal>0x3456789012</literal> with the key + configured for use on the access point.</para> + </note> + </listitem> + </itemizedlist> + + <para>You are encouraged to read &man.ifconfig.8; manual + page for further information.</para> + + <para>The <command>wpa_supplicant</command> facility also + can be used to configure your wireless interface with WEP. + The example above can be set up by adding the following + lines to + <filename>/etc/wpa_supplicant.conf</filename>:</para> + + <programlisting>network={ + ssid="my_net" + key_mgmt=NONE + wep_key3=3456789012 + wep_tx_keyidx=3 +}</programlisting> + + <para>Then:</para> + + <screen>&prompt.root; <userinput>wpa_supplicant -i ath0 -c /etc/wpa_supplicant.conf</userinput> +Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz) +Associated with 00:13:46:49:41:76</screen> + </sect4> + </sect3> + </sect2> + + <sect2> + <title>Ad-hoc Mode</title> + + <para>IBSS mode, also called ad-hoc mode, is designed for point + to point connections. For example, to establish an ad-hoc + network between the machine <systemitem>A</systemitem> and the machine + <systemitem>B</systemitem> we will just need to choose two IP adresses + and a SSID.</para> + + <para>On the box <systemitem>A</systemitem>:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap mediaopt adhoc</userinput> +&prompt.root; <userinput>ifconfig ath0</userinput> + ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4 + ether 00:11:95:c3:0d:ac + media: IEEE 802.11 Wireless Ethernet autoselect <adhoc> (autoselect <adhoc>) + status: associated + ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac + authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen> + + <para>The <literal>adhoc</literal> parameter indicates the + interface is running in the IBSS mode.</para> + + <para>On <systemitem>B</systemitem>, we should be able to detect + <systemitem>A</systemitem>:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 up scan</userinput> + SSID BSSID CHAN RATE S:N INT CAPS + freebsdap 02:11:95:c3:0d:ac 2 54M 19:0 100 IS</screen> + + <para>The <literal>I</literal> in the output confirms the + machine <systemitem>A</systemitem> is in ad-hoc mode. We just have to + configure <systemitem>B</systemitem> with a different IP + address:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 inet 192.168.0.2 netmask 255.255.255.0 ssid freebsdap mediaopt adhoc</userinput> +&prompt.root; <userinput>ifconfig ath0</userinput> + ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect <adhoc> (autoselect <adhoc>) + status: associated + ssid freebsdap channel 2 bssid 02:11:95:c3:0d:ac + authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen> + + <para>Both <systemitem>A</systemitem> and <systemitem>B</systemitem> are now + ready to exchange informations.</para> + </sect2> + + <sect2 xml:id="network-wireless-ap"> + <title>&os; Host Access Points</title> + + <para>&os; can act as an Access Point (AP) which eliminates the + need to buy a hardware AP or run an ad-hoc network. This can be + particularly useful when your &os; machine is acting as a + gateway to another network (e.g., the Internet).</para> + + <sect3 xml:id="network-wireless-ap-basic"> + <title>Basic Settings</title> + + <para>Before configuring your &os; machine as an AP, the + kernel must be configured with the appropriate wireless + networking support for your wireless card. You also have to + add the support for the security protocols you intend to + use. For more details, see <xref linkend="network-wireless-basic"/>.</para> + + <note> + <para>The use of the NDIS driver wrapper and the &windows; + drivers do not allow currently the AP operation. Only + native &os; wireless drivers support AP mode.</para> + </note> + + <para>Once the wireless networking support is loaded, you can + check if your wireless device supports the host-based access + point mode (also know as hostap mode):</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 list caps</userinput> +ath0=783ed0f<WEP,TKIP,AES,AES_CCM,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,TKIPMIC,WPA1,WPA2,BURST,WME></screen> + + <para>This output displays the card capabilities; the + <literal>HOSTAP</literal> word confirms this wireless card + can act as an Access Point. Various supported ciphers are + also mentioned: WEP, TKIP, WPA2, etc., these informations + are important to know what security protocols could be set + on the Access Point.</para> + + <para>The wireless device can now be put into hostap mode and + configured with the correct SSID and IP address:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 ssid freebsdap mode 11g mediaopt hostap</userinput> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable></screen> + + <para>Use again <command>ifconfig</command> to see the status + of the <filename>ath0</filename> interface:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0</userinput> + ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4 + ether 00:11:95:c3:0d:ac + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode OPEN privacy OFF txpowmax 38 bmiss 7 protmode CTS burst dtimperiod 1 bintval 100</screen> + + <para>The <literal>hostap</literal> parameter indicates the + interface is running in the host-based access point + mode.</para> + + <para>The interface configuration can be done automatically at + boot time by adding the following line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_ath0="ssid <replaceable>freebsdap</replaceable> mode 11g mediaopt hostap inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable>"</programlisting> + </sect3> + + <sect3> + <title>Host-based Access Point without Authentication or + Encryption</title> + + <para>Although it is not recommended to run an AP without any + authentication or encryption, this is a simple way to check + if your AP is working. This configuration is also important + for debugging client issues.</para> + + <para>Once the AP configured as previously shown, it is + possible from another wireless machine to initiate a scan to + find the AP:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 up scan</userinput> +SSID BSSID CHAN RATE S:N INT CAPS +freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 ES</screen> + + <para>The client machine found the Access Point and can be + associated with it:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 ssid freebsdap inet 192.168.0.2 netmask 255.255.255.0</userinput> +&prompt.root; <userinput>ifconfig ath0</userinput> + ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet6 fe80::211:95ff:fed5:4362%ath0 prefixlen 64 scopeid 0x1 + inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 + ether 00:11:95:d5:43:62 + media: IEEE 802.11 Wireless Ethernet autoselect (OFDM/54Mbps) + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode OPEN privacy OFF txpowmax 36 protmode CTS bintval 100</screen> + </sect3> + + <sect3> + <title>WPA Host-based Access Point</title> + + <para>This section will focus on setting up &os; Access Point + using the WPA security protocol. More details regarding WPA + and the configuration of WPA-based wireless clients can be + found in the <xref linkend="network-wireless-wpa"/>.</para> + + <para>The <application>hostapd</application> daemon is used to + deal with client authentication and keys management on the + WPA enabled Access Point.</para> + + <para>In the following, all the configuration operations will + be performed on the &os; machine acting as AP. Once the + AP is correctly working, <application>hostapd</application> + should be automatically enabled at boot with the following + line in <filename>/etc/rc.conf</filename>:</para> + + <programlisting>hostapd_enable="YES"</programlisting> + + <para>Before trying to configure + <application>hostapd</application>, be sure you have done + the basic settings introduced in the <xref linkend="network-wireless-ap-basic"/>.</para> + + <sect4> + <title>WPA-PSK</title> + + <para>WPA-PSK is intended for small networks where the use + of an backend authentication server is not possible or + desired.</para> + + <para>The configuration is done in the + <filename>/etc/hostapd.conf</filename> file:</para> + + <programlisting>interface=ath0 <co xml:id="co-ap-wpapsk-iface"/> +debug=1 <co xml:id="co-ap-wpapsk-dbug"/> +ctrl_interface=/var/run/hostapd <co xml:id="co-ap-wpapsk-ciface"/> +ctrl_interface_group=wheel <co xml:id="co-ap-wpapsk-cifacegrp"/> +ssid=freebsdap <co xml:id="co-ap-wpapsk-ssid"/> +wpa=1 <co xml:id="co-ap-wpapsk-wpa"/> +wpa_passphrase=freebsdmall <co xml:id="co-ap-wpapsk-pass"/> +wpa_key_mgmt=WPA-PSK <co xml:id="co-ap-wpapsk-kmgmt"/> +wpa_pairwise=CCMP TKIP <co xml:id="co-ap-wpapsk-pwise"/></programlisting> + + <calloutlist> + <callout arearefs="co-ap-wpapsk-iface"> + <para>This field indicates the wireless interface used + for the Access Point.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-dbug"> + <para>This field sets the level of verbosity during the + execution of <application>hostapd</application>. A + value of <literal>1</literal> represents the minimal + level.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-ciface"> + <para>The <literal>ctrl_interface</literal> field gives + the pathname of the directory used by + <application>hostapd</application> to stores its + domain socket files for the communication with + external programs such as &man.hostapd.cli.8;. The + default value is used here.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-cifacegrp"> + <para>The <literal>ctrl_interface_group</literal> line + sets the group (here, it is the + <systemitem class="groupname">wheel</systemitem> group) allowed to access + to the control interface files.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-ssid"> + <para>This field sets the network name.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-wpa"> + <para>The <literal>wpa</literal> field enables WPA and + specifies which WPA authentication protocol will be + required. A value of <literal>1</literal> configures the + AP for WPA-PSK.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-pass"> + <para>The <literal>wpa_passphrase</literal> field + contains the ASCII passphrase for the WPA + authentication.</para> + + <warning> + <para>Always use strong passwords that are + sufficiently long and made from a rich alphabet so + they will not be guessed and/or attacked.</para> + </warning> + </callout> + + <callout arearefs="co-ap-wpapsk-kmgmt"> + <para>The <literal>wpa_key_mgmt</literal> line refers to + the key management protocol we use. In our case it is + WPA-PSK.</para> + </callout> + + <callout arearefs="co-ap-wpapsk-pwise"> + <para>The <literal>wpa_pairwise</literal> field + indicates the set of accepted encryption algorithms by + the Access Point. Here both TKIP (WPA) and CCMP + (WPA2) ciphers are accepted. CCMP cipher is an + alternative to TKIP and that is strongly preferred + when possible; TKIP should be used solely for stations + incapable of doing CCMP.</para> + </callout> + </calloutlist> + + <para>The next step is to start + <application>hostapd</application>:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/hostapd forcestart</userinput></screen> + + <screen>&prompt.root; <userinput>ifconfig ath0</userinput> + ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 2290 + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4 + ether 00:11:95:c3:0d:ac + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode WPA2/802.11i privacy MIXED deftxkey 2 TKIP 2:128-bit txpowmax 36 protmode CTS dtimperiod 1 bintval 100</screen> + + <para>The Access Point is running, the clients can now be + associated with it, see <xref linkend="network-wireless-wpa"/> for more details. It is + possible to see the stations associated with the AP using + the <command>ifconfig ath0 list + sta</command> command.</para> + </sect4> + </sect3> + + <sect3> + <title>WEP Host-based Access Point</title> + + <para>It is not recommended to use WEP for setting up an + Access Point since there is no authentication mechanism and + it is easily to be cracked. Some legacy wireless cards only + support WEP as security protocol, these cards will only + allow to set up AP without authentication or encryption or + using the WEP protocol.</para> + + <para>The wireless device can now be put into hostap mode and + configured with the correct SSID and IP address:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 ssid freebsdap wepmode on weptxkey 3 wepkey 3:0x3456789012 mode 11g mediaopt hostap \ + inet 192.168.0.1 netmask 255.255.255.0</userinput></screen> + + <itemizedlist> + <listitem> + <para>The <literal>weptxkey</literal> means which WEP + key will be used in the transmission. Here we used the + third key (note that the key numbering starts with + <literal>1</literal>). This parameter must be specified + to really encrypt the data.</para> + </listitem> + + <listitem> + <para>The <literal>wepkey</literal> means setting the + selected WEP key. It should in the format + <replaceable>index:key</replaceable>, if the index is + not given, key <literal>1</literal> is set. That is + to say we need to set the index if we use keys other + than the first key.</para> + </listitem> + </itemizedlist> + + <para>Use again <command>ifconfig</command> to see the status + of the <filename>ath0</filename> interface:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0</userinput> + ath0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4 + ether 00:11:95:c3:0d:ac + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> + status: associated + ssid freebsdap channel 1 bssid 00:11:95:c3:0d:ac + authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit txpowmax 36 protmode CTS dtimperiod 1 bintval 100</screen> + + <para>From another wireless machine, it is possible to initiate + a scan to find the AP:</para> + + <screen>&prompt.root; <userinput>ifconfig ath0 up scan</userinput> +SSID BSSID CHAN RATE S:N INT CAPS +freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen> + + <para>The client machine found the Access Point and can be + associated with it using the correct parameters (key, etc.), + see <xref linkend="network-wireless-wep"/> for more + details.</para> + </sect3> + </sect2> + + <sect2> + <title>Troubleshooting</title> + + <para>If you are having trouble with wireless networking, there + are a number of steps you can take to help troubleshoot the + problem.</para> + + <itemizedlist> + <listitem> + <para>If you do not see the access point listed when + scanning be sure you have not configured your wireless + device to a limited set of channels.</para> + </listitem> + + <listitem> + <para>If you cannot associate to an access point verify the + configuration of your station matches the one of the + access point. This includes the authentication scheme and + any security protocols. Simplify your configuration as + much as possible. If you are using a security protocol + such as WPA or WEP configure the access point for open + authentication and no security to see if you can get + traffic to pass.</para> + </listitem> + + <listitem> + <para>Once you can associate to the access point diagnose + any security configuration using simple tools like + &man.ping.8;.</para> + + <para>The <command>wpa_supplicant</command> has much + debugging support; try running it manually with the + <option>-dd</option> option and look at the system + logs.</para> + </listitem> + + <listitem> + <para>There are also many lower-level debugging tools. You + can enable debugging messages in the 802.11 protocol + support layer using the <command>wlandebug</command> + program found in + <filename>/usr/src/tools/tools/net80211</filename>. For + example:</para> + + <screen>&prompt.root; <userinput>wlandebug -i ath0 +scan+auth+debug+assoc</userinput> + net.wlan.0.debug: 0 => 0xc80000<assoc,auth,scan></screen> + + <para>can be used to enable console messages related to + scanning for access points and doing the 802.11 protocol + handshakes required to arrange communication.</para> + + <para>There are also many useful statistics maintained by + the 802.11 layer; the <command>wlanstats</command> tool + will dump these informations. These statistics should + identify all errors identified by the 802.11 layer. + Beware however that some errors are identified in the + device drivers that lie below the 802.11 layer so they may + not show up. To diagnose device-specific problems you + need to refer to the drivers' documentation.</para> + </listitem> + </itemizedlist> + + <para>If the above information does not help to clarify the + problem, please submit a problem report and include output + from the above tools.</para> + </sect2> + </sect1> + + <sect1 xml:id="network-bluetooth"> + <info><title>Bluetooth</title> + <authorgroup> + <author><personname><firstname>Pav</firstname><surname>Lucistnik</surname></personname><contrib>Written by </contrib><affiliation> + <address><email>pav@FreeBSD.org</email></address> + </affiliation></author> + </authorgroup> + </info> + + + <indexterm><primary>Bluetooth</primary></indexterm> + <sect2> + <title>Introduction</title> + <para>Bluetooth is a wireless technology for creating personal networks + operating in the 2.4 GHz unlicensed band, with a range of 10 meters. + Networks are usually formed ad-hoc from portable devices such as + cellular phones, handhelds and laptops. Unlike the other popular + wireless technology, Wi-Fi, Bluetooth offers higher level service + profiles, e.g. FTP-like file servers, file pushing, voice transport, + serial line emulation, and more.</para> + + <para>The Bluetooth stack in &os; is implemented using the Netgraph + framework (see &man.netgraph.4;). A broad variety of Bluetooth USB + dongles is supported by the &man.ng.ubt.4; driver. The Broadcom BCM2033 + chip based Bluetooth devices are supported via the &man.ubtbcmfw.4; and + &man.ng.ubt.4; drivers. The 3Com Bluetooth PC Card 3CRWB60-A is + supported by the &man.ng.bt3c.4; driver. Serial and UART based + Bluetooth devices are supported via &man.sio.4;, &man.ng.h4.4; + and &man.hcseriald.8;. This section describes the use of the USB + Bluetooth dongle.</para> + </sect2> + + <sect2> + <title>Plugging in the Device</title> + <para>By default Bluetooth device drivers are available as kernel modules. + Before attaching a device, you will need to load the driver into the + kernel:</para> + + <screen>&prompt.root; <userinput>kldload ng_ubt</userinput></screen> + + <para>If the Bluetooth device is present in the system during system + startup, load the module from + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>ng_ubt_load="YES"</programlisting> + + <para>Plug in your USB dongle. The output similar to the following will + appear on the console (or in syslog):</para> + + <screen>ubt0: vendor 0x0a12 product 0x0001, rev 1.10/5.25, addr 2 +ubt0: Interface 0 endpoints: interrupt=0x81, bulk-in=0x82, bulk-out=0x2 +ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3, + wMaxPacketSize=49, nframes=6, buffer size=294</screen> + + <note> + <para>The Bluetooth stack has to be started manually on &os; 6.0, and + on &os; 5.X before 5.5. It is done automatically from &man.devd.8; + on &os; 5.5, 6.1 and newer.</para> + + <para>Copy + <filename>/usr/share/examples/netgraph/bluetooth/rc.bluetooth</filename> + into some convenient place, like <filename>/etc/rc.bluetooth</filename>. + This script is used to start and stop the Bluetooth stack. It is a good + idea to stop the stack before unplugging the device, but it is not + (usually) fatal. When starting the stack, you will receive output similar + to the following:</para> + + <screen>&prompt.root; <userinput>/etc/rc.bluetooth start ubt0</userinput> +BD_ADDR: 00:02:72:00:d4:1a +Features: 0xff 0xff 0xf 00 00 00 00 00 +<3-Slot> <5-Slot> <Encryption> <Slot offset> +<Timing accuracy> <Switch> <Hold mode> <Sniff mode> +<Park mode> <RSSI> <Channel quality> <SCO link> +<HV2 packets> <HV3 packets> <u-law log> <A-law log> <CVSD> +<Paging scheme> <Power control> <Transparent SCO data> +Max. ACL packet size: 192 bytes +Number of ACL packets: 8 +Max. SCO packet size: 64 bytes +Number of SCO packets: 8</screen> + </note> + + </sect2> + + <sect2> + <title>Host Controller Interface (HCI)</title> + + <indexterm><primary>HCI</primary></indexterm> + + <para>Host Controller Interface (HCI) provides a command interface to the + baseband controller and link manager, and access to hardware status and + control registers. This interface provides a uniform method of accessing + the Bluetooth baseband capabilities. HCI layer on the Host exchanges + data and commands with the HCI firmware on the Bluetooth hardware. + The Host Controller Transport Layer (i.e. physical bus) driver provides + both HCI layers with the ability to exchange information with each + other.</para> + + <para>A single Netgraph node of type <emphasis>hci</emphasis> is + created for a single Bluetooth device. The HCI node is normally + connected to the Bluetooth device driver node (downstream) and + the L2CAP node (upstream). All HCI operations must be performed + on the HCI node and not on the device driver node. Default name + for the HCI node is <quote>devicehci</quote>. + For more details refer to the &man.ng.hci.4; manual page.</para> + + <para>One of the most common tasks is discovery of Bluetooth devices in + RF proximity. This operation is called <emphasis>inquiry</emphasis>. + Inquiry and other HCI related operations are done with the + &man.hccontrol.8; utility. The example below shows how to find out + which Bluetooth devices are in range. You should receive the list of + devices in a few seconds. Note that a remote device will only answer + the inquiry if it put into <emphasis>discoverable</emphasis> + mode.</para> + + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci inquiry</userinput> +Inquiry result, num_responses=1 +Inquiry result #0 + BD_ADDR: 00:80:37:29:19:a4 + Page Scan Rep. Mode: 0x1 + Page Scan Period Mode: 00 + Page Scan Mode: 00 + Class: 52:02:04 + Clock offset: 0x78ef +Inquiry complete. Status: No error [00]</screen> + + <para><literal>BD_ADDR</literal> is unique address of a Bluetooth + device, similar to MAC addresses of a network card. This address + is needed for further communication with a device. It is possible + to assign human readable name to a BD_ADDR. + The <filename>/etc/bluetooth/hosts</filename> file contains information + regarding the known Bluetooth hosts. The following example shows how + to obtain human readable name that was assigned to the remote + device:</para> + + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci remote_name_request 00:80:37:29:19:a4</userinput> +BD_ADDR: 00:80:37:29:19:a4 +Name: Pav's T39</screen> + + <para>If you perform an inquiry on a remote Bluetooth device, it will + find your computer as <quote>your.host.name (ubt0)</quote>. The name + assigned to the local device can be changed at any time.</para> + + <para>The Bluetooth system provides a point-to-point connection (only two + Bluetooth units involved), or a point-to-multipoint connection. In the + point-to-multipoint connection the connection is shared among several + Bluetooth devices. The following example shows how to obtain the list + of active baseband connections for the local device:</para> + + <screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput> +Remote BD_ADDR Handle Type Mode Role Encrypt Pending Queue State +00:80:37:29:19:a4 41 ACL 0 MAST NONE 0 0 OPEN</screen> + + <para>A <emphasis>connection handle</emphasis> is useful when termination + of the baseband connection is required. Note, that it is normally not + required to do it by hand. The stack will automatically terminate + inactive baseband connections.</para> + + <screen>&prompt.root; <userinput>hccontrol -n ubt0hci disconnect 41</userinput> +Connection handle: 41 +Reason: Connection terminated by local host [0x16]</screen> + + <para>Refer to <command>hccontrol help</command> for a complete listing + of available HCI commands. Most of the HCI commands do not require + superuser privileges.</para> + + </sect2> + + <sect2> + <title>Logical Link Control and Adaptation Protocol (L2CAP)</title> + + <indexterm><primary>L2CAP</primary></indexterm> + + <para>Logical Link Control and Adaptation Protocol (L2CAP) provides + connection-oriented and connectionless data services to upper layer + protocols with protocol multiplexing capability and segmentation and + reassembly operation. L2CAP permits higher level protocols and + applications to transmit and receive L2CAP data packets up to 64 + kilobytes in length.</para> + + <para>L2CAP is based around the concept of <emphasis>channels</emphasis>. + Channel is a logical connection on top of baseband connection. Each + channel is bound to a single protocol in a many-to-one fashion. Multiple + channels can be bound to the same protocol, but a channel cannot be + bound to multiple protocols. Each L2CAP packet received on a channel is + directed to the appropriate higher level protocol. Multiple channels + can share the same baseband connection.</para> + + <para>A single Netgraph node of type <emphasis>l2cap</emphasis> is + created for a single Bluetooth device. The L2CAP node is normally + connected to the Bluetooth HCI node (downstream) and Bluetooth sockets + nodes (upstream). Default name for the L2CAP node is + <quote>devicel2cap</quote>. For more details refer to the + &man.ng.l2cap.4; manual page.</para> + + <para>A useful command is &man.l2ping.8;, which can be used to ping + other devices. Some Bluetooth implementations might not return all of + the data sent to them, so <literal>0 bytes</literal> in the following + example is normal.</para> + + <screen>&prompt.root; <userinput>l2ping -a 00:80:37:29:19:a4</userinput> +0 bytes from 0:80:37:29:19:a4 seq_no=0 time=48.633 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=1 time=37.551 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=2 time=28.324 ms result=0 +0 bytes from 0:80:37:29:19:a4 seq_no=3 time=46.150 ms result=0</screen> + + <para>The &man.l2control.8; utility is used to perform various operations + on L2CAP nodes. This example shows how to obtain the list of logical + connections (channels) and the list of baseband connections for the + local device:</para> + + <screen>&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_channel_list</userinput> +L2CAP channels: +Remote BD_ADDR SCID/ DCID PSM IMTU/ OMTU State +00:07:e0:00:0b:ca 66/ 64 3 132/ 672 OPEN +&prompt.user; <userinput>l2control -a 00:02:72:00:d4:1a read_connection_list</userinput> +L2CAP connections: +Remote BD_ADDR Handle Flags Pending State +00:07:e0:00:0b:ca 41 O 0 OPEN</screen> + + <para>Another diagnostic tool is &man.btsockstat.1;. It does a job + similar to as &man.netstat.1; does, but for Bluetooth network-related + data structures. The example below shows the same logical connection as + &man.l2control.8; above.</para> + + <screen>&prompt.user; <userinput>btsockstat</userinput> +Active L2CAP sockets +PCB Recv-Q Send-Q Local address/PSM Foreign address CID State +c2afe900 0 0 00:02:72:00:d4:1a/3 00:07:e0:00:0b:ca 66 OPEN +Active RFCOMM sessions +L2PCB PCB Flag MTU Out-Q DLCs State +c2afe900 c2b53380 1 127 0 Yes OPEN +Active RFCOMM sockets +PCB Recv-Q Send-Q Local address Foreign address Chan DLCI State +c2e8bc80 0 250 00:02:72:00:d4:1a 00:07:e0:00:0b:ca 3 6 OPEN</screen> + + </sect2> + + <sect2> + <title>RFCOMM Protocol</title> + + <indexterm><primary>RFCOMM</primary></indexterm> + + <para>The RFCOMM protocol provides emulation of serial ports over the + L2CAP protocol. The protocol is based on the ETSI standard TS 07.10. + RFCOMM is a simple transport protocol, with additional provisions for + emulating the 9 circuits of RS-232 (EIATIA-232-E) serial ports. The + RFCOMM protocol supports up to 60 simultaneous connections (RFCOMM + channels) between two Bluetooth devices.</para> + + <para>For the purposes of RFCOMM, a complete communication path involves + two applications running on different devices (the communication + endpoints) with a communication segment between them. RFCOMM is intended + to cover applications that make use of the serial ports of the devices + in which they reside. The communication segment is a Bluetooth link from + one device to another (direct connect).</para> + + <para>RFCOMM is only concerned with the connection between the devices in + the direct connect case, or between the device and a modem in the + network case. RFCOMM can support other configurations, such as modules + that communicate via Bluetooth wireless technology on one side and + provide a wired interface on the other side.</para> + + <para>In &os; the RFCOMM protocol is implemented at the Bluetooth sockets + layer.</para> + </sect2> + + <sect2> + <title>Pairing of Devices</title> + + <indexterm><primary>pairing</primary></indexterm> + + <para>By default, Bluetooth communication is not authenticated, and any + device can talk to any other device. A Bluetooth device (for example, + cellular phone) may choose to require authentication to provide a + particular service (for example, Dial-Up service). Bluetooth + authentication is normally done with <emphasis>PIN codes</emphasis>. + A PIN code is an ASCII string up to 16 characters in length. User is + required to enter the same PIN code on both devices. Once user has + entered the PIN code, both devices will generate a + <emphasis>link key</emphasis>. After that the link key can be stored + either in the devices themselves or in a persistent storage. Next time + both devices will use previously generated link key. The described + above procedure is called <emphasis>pairing</emphasis>. Note that if + the link key is lost by any device then pairing must be repeated.</para> + + <para>The &man.hcsecd.8; daemon is responsible for handling of all + Bluetooth authentication requests. The default configuration file is + <filename>/etc/bluetooth/hcsecd.conf</filename>. An example section for + a cellular phone with the PIN code arbitrarily set to + <quote>1234</quote> is shown below:</para> + + <programlisting>device { + bdaddr 00:80:37:29:19:a4; + name "Pav's T39"; + key nokey; + pin "1234"; + }</programlisting> + + <para>There is no limitation on PIN codes (except length). Some devices + (for example Bluetooth headsets) may have a fixed PIN code built in. + The <option>-d</option> switch forces the &man.hcsecd.8; daemon to stay + in the foreground, so it is easy to see what is happening. Set the + remote device to receive pairing and initiate the Bluetooth connection + to the remote device. The remote device should say that pairing was + accepted, and request the PIN code. Enter the same PIN code as you + have in <filename>hcsecd.conf</filename>. Now your PC and the remote + device are paired. Alternatively, you can initiate pairing on the remote + device.</para> + + <para>On &os; 5.5, 6.1 and newer, the following line can be added to the + <filename>/etc/rc.conf</filename> file to have + <application>hcsecd</application> started automatically on system + start:</para> + + <programlisting>hcsecd_enable="YES"</programlisting> + + <para>The following is a sample of the + <application>hcsecd</application> daemon output:</para> + +<programlisting>hcsecd[16484]: Got Link_Key_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', link key doesn't exist +hcsecd[16484]: Sending Link_Key_Negative_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Got PIN_Code_Request event from 'ubt0hci', remote bdaddr 0:80:37:29:19:a4 +hcsecd[16484]: Found matching entry, remote bdaddr 0:80:37:29:19:a4, name 'Pav's T39', PIN code exists +hcsecd[16484]: Sending PIN_Code_Reply to 'ubt0hci' for remote bdaddr 0:80:37:29:19:a4</programlisting> + + </sect2> + + <sect2> + <title>Service Discovery Protocol (SDP)</title> + + <indexterm><primary>SDP</primary></indexterm> + + <para>The Service Discovery Protocol (SDP) provides the means for client + applications to discover the existence of services provided by server + applications as well as the attributes of those services. The attributes + of a service include the type or class of service offered and the + mechanism or protocol information needed to utilize the service.</para> + + <para>SDP involves communication between a SDP server and a SDP client. + The server maintains a list of service records that describe the + characteristics of services associated with the server. Each service + record contains information about a single service. A client may + retrieve information from a service record maintained by the SDP server + by issuing a SDP request. If the client, or an application associated + with the client, decides to use a service, it must open a separate + connection to the service provider in order to utilize the service. + SDP provides a mechanism for discovering services and their attributes, + but it does not provide a mechanism for utilizing those services.</para> + + <para>Normally, a SDP client searches for services based on some desired + characteristics of the services. However, there are times when it is + desirable to discover which types of services are described by an SDP + server's service records without any a priori information about the + services. This process of looking for any offered services is called + <emphasis>browsing</emphasis>.</para> + + <para>The Bluetooth SDP server &man.sdpd.8; and command line client + &man.sdpcontrol.8; are included in the standard &os; installation. + The following example shows how to perform a SDP browse query.</para> + + <screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec browse</userinput> +Record Handle: 00000000 +Service Class ID List: + Service Discovery Server (0x1000) +Protocol Descriptor List: + L2CAP (0x0100) + Protocol specific parameter #1: u/int/uuid16 1 + Protocol specific parameter #2: u/int/uuid16 1 + +Record Handle: 0x00000001 +Service Class ID List: + Browse Group Descriptor (0x1001) + +Record Handle: 0x00000002 +Service Class ID List: + LAN Access Using PPP (0x1102) +Protocol Descriptor List: + L2CAP (0x0100) + RFCOMM (0x0003) + Protocol specific parameter #1: u/int8/bool 1 +Bluetooth Profile Descriptor List: + LAN Access Using PPP (0x1102) ver. 1.0 +</screen> + + <para>... and so on. Note that each service has a list of attributes + (RFCOMM channel for example). Depending on the service you might need to + make a note of some of the attributes. Some Bluetooth implementations do + not support service browsing and may return an empty list. In this case + it is possible to search for the specific service. The example below + shows how to search for the OBEX Object Push (OPUSH) service:</para> + + <screen>&prompt.user; <userinput>sdpcontrol -a 00:01:03:fc:6e:ec search OPUSH</userinput></screen> + + <para>Offering services on &os; to Bluetooth clients is done with the + &man.sdpd.8; server. On &os; 5.5, 6.1 and newer, the following line can + be added to the <filename>/etc/rc.conf</filename> file:</para> + + <programlisting>sdpd_enable="YES"</programlisting> + + <para>Then the <application>sdpd</application> daemon can be started with:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/sdpd start</userinput></screen> + + <para>On &os; 6.0, and on &os; 5.X before 5.5, + <application>sdpd</application> is not integrated into the system + startup scripts. It has to be started manually with:</para> + + <screen>&prompt.root; <userinput>sdpd</userinput></screen> + + <para>The local server application that wants to provide Bluetooth + service to the remote clients will register service with the local + SDP daemon. The example of such application is &man.rfcomm.pppd.8;. + Once started it will register Bluetooth LAN service with the local + SDP daemon.</para> + + <para>The list of services registered with the local SDP server can be + obtained by issuing SDP browse query via local control channel:</para> + + <screen>&prompt.root; <userinput>sdpcontrol -l browse</userinput></screen> + + </sect2> + + <sect2> + <title>Dial-Up Networking (DUN) and Network Access with PPP (LAN) + Profiles</title> + + <para>The Dial-Up Networking (DUN) profile is mostly used with modems + and cellular phones. The scenarios covered by this profile are the + following:</para> + + <itemizedlist> + <listitem><para>use of a cellular phone or modem by a computer as + a wireless modem for connecting to a dial-up Internet access server, + or using other dial-up services;</para></listitem> + + <listitem><para>use of a cellular phone or modem by a computer to + receive data calls.</para></listitem> + </itemizedlist> + + <para>Network Access with PPP (LAN) profile can be used in the following + situations:</para> + + <itemizedlist> + <listitem><para>LAN access for a single Bluetooth device; + </para></listitem> + + <listitem><para>LAN access for multiple Bluetooth devices; + </para></listitem> + + <listitem><para>PC to PC (using PPP networking over serial cable + emulation).</para></listitem> + </itemizedlist> + + <para>In &os; both profiles are implemented with &man.ppp.8; and + &man.rfcomm.pppd.8; - a wrapper that converts RFCOMM Bluetooth + connection into something PPP can operate with. Before any profile + can be used, a new PPP label in the <filename>/etc/ppp/ppp.conf</filename> + must be created. Consult &man.rfcomm.pppd.8; manual page for examples. + </para> + + <para>In the following example &man.rfcomm.pppd.8; will be used to open + RFCOMM connection to remote device with BD_ADDR 00:80:37:29:19:a4 on + DUN RFCOMM channel. The actual RFCOMM channel number will be obtained + from the remote device via SDP. It is possible to specify RFCOMM channel + by hand, and in this case &man.rfcomm.pppd.8; will not perform SDP + query. Use &man.sdpcontrol.8; to find out RFCOMM + channel on the remote device.</para> + + <screen>&prompt.root; <userinput>rfcomm_pppd -a 00:80:37:29:19:a4 -c -C dun -l rfcomm-dialup</userinput></screen> + + <para>In order to provide Network Access with PPP (LAN) service the + &man.sdpd.8; server must be running. A new entry for LAN clients must + be created in the <filename>/etc/ppp/ppp.conf</filename> file. Consult + &man.rfcomm.pppd.8; manual page for examples. Finally, start RFCOMM PPP + server on valid RFCOMM channel number. The RFCOMM PPP server will + automatically register Bluetooth LAN service with the local SDP daemon. + The example below shows how to start RFCOMM PPP server.</para> + + <screen>&prompt.root; <userinput>rfcomm_pppd -s -C 7 -l rfcomm-server</userinput></screen> + + </sect2> + + <sect2> + <title>OBEX Object Push (OPUSH) Profile</title> + + <indexterm><primary>OBEX</primary></indexterm> + + <para>OBEX is a widely used protocol for simple file transfers between + mobile devices. Its main use is in infrared communication, where it is + used for generic file transfers between notebooks or PDAs, + and for sending business cards or calendar entries between cellular + phones and other devices with PIM applications.</para> + + <para>The OBEX server and client are implemented as a third-party package + <application>obexapp</application>, which is available as + <package>comms/obexapp</package> port.</para> + + <para>OBEX client is used to push and/or pull objects from the OBEX server. + An object can, for example, be a business card or an appointment. + The OBEX client can obtain RFCOMM channel number from the remote device + via SDP. This can be done by specifying service name instead of RFCOMM + channel number. Supported service names are: IrMC, FTRN and OPUSH. + It is possible to specify RFCOMM channel as a number. Below is an + example of an OBEX session, where device information object is pulled + from the cellular phone, and a new object (business card) is pushed + into the phone's directory.</para> + + <screen>&prompt.user; <userinput>obexapp -a 00:80:37:29:19:a4 -C IrMC</userinput> +obex> get telecom/devinfo.txt devinfo-t39.txt +Success, response: OK, Success (0x20) +obex> put new.vcf +Success, response: OK, Success (0x20) +obex> di +Success, response: OK, Success (0x20)</screen> + + <para>In order to provide OBEX Object Push service, + &man.sdpd.8; server must be running. A root folder, where all incoming + objects will be stored, must be created. The default path to the root + folder is <filename>/var/spool/obex</filename>. Finally, start OBEX + server on valid RFCOMM channel number. The OBEX server will + automatically register OBEX Object Push service with the local SDP + daemon. The example below shows how to start OBEX server.</para> + + <screen>&prompt.root; <userinput>obexapp -s -C 10</userinput></screen> + </sect2> + + <sect2> + <title>Serial Port Profile (SPP)</title> + <para>The Serial Port Profile (SPP) allows Bluetooth devices to perform + RS232 (or similar) serial cable emulation. The scenario covered by this + profile deals with legacy applications using Bluetooth as a cable + replacement, through a virtual serial port abstraction.</para> + + <para>The &man.rfcomm.sppd.1; utility implements the Serial Port profile. + A pseudo tty is used as a virtual serial port abstraction. The example + below shows how to connect to a remote device Serial Port service. + Note that you do not have to specify a RFCOMM channel - + &man.rfcomm.sppd.1; can obtain it from the remote device via SDP. + If you would like to override this, specify a RFCOMM channel on the + command line.</para> + + <screen>&prompt.root; <userinput>rfcomm_sppd -a 00:07:E0:00:0B:CA -t /dev/ttyp6</userinput> +rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen> + + <para>Once connected, the pseudo tty can be used as serial port:</para> + + <screen>&prompt.root; <userinput>cu -l ttyp6</userinput></screen> + + </sect2> + + <sect2> + <title>Troubleshooting</title> + + <sect3> + <title>A remote device cannot connect</title> + <para>Some older Bluetooth devices do not support role switching. + By default, when &os; is accepting a new connection, it tries to + perform a role switch and become master. Devices, which do not + support this will not be able to connect. Note that role switching is + performed when a new connection is being established, so it is not + possible to ask the remote device if it does support role switching. + There is a HCI option to disable role switching on the local + side:</para> + + <screen>&prompt.root; <userinput>hccontrol -n ubt0hci write_node_role_switch 0</userinput></screen> + + </sect3> + + <sect3> + <title>Something is going wrong, can I see what exactly is happening?</title> + <para>Yes, you can. Use the third-party package + <application>hcidump</application>, which is available as + <package>comms/hcidump</package> port. + The <application>hcidump</application> utility is similar to + &man.tcpdump.1;. It can be used to display the content of the Bluetooth + packets on the terminal and to dump the Bluetooth packets to a + file.</para> + </sect3> + + </sect2> + + </sect1> + + <sect1 xml:id="network-bridging"> + <info><title>Bridging</title> + <authorgroup> + <author><personname><firstname>Andrew</firstname><surname>Thompson</surname></personname><contrib>Written by </contrib></author> + </authorgroup> + </info> + + + <sect2> + <title>Introduction</title> + <indexterm><primary>IP subnet</primary></indexterm> + <indexterm><primary>bridge</primary></indexterm> + <para>It is sometimes useful to divide one physical network + (such as an Ethernet segment) into two separate network + segments without having to create IP subnets and use a router + to connect the segments together. A device that connects two + networks together in this fashion is called a + <quote>bridge</quote>. A FreeBSD system with two network + interface cards can act as a bridge.</para> + + <para>The bridge works by learning the MAC layer addresses + (Ethernet addresses) of the devices on each of its network interfaces. + It forwards traffic between two networks only when its source and + destination are on different networks.</para> + + <para>In many respects, a bridge is like an Ethernet switch with very + few ports.</para> + </sect2> + + <sect2> + <title>Situations Where Bridging Is Appropriate</title> + + <para>There are many common situations in which a bridge is used + today.</para> + + <sect3> + <title>Connecting Networks</title> + + <para>The basic operation of a bridge is to join two or more + network segments together. There are many reasons to use a + host based bridge over plain networking equipment such as + cabling constraints, firewalling or connecting pseudo + networks such as a Virtual Machine interface. A bridge can + also connect a wireless interface running in hostap mode to + a wired network and act as an access point.</para> + </sect3> + + <sect3> + <title>Filtering/Traffic Shaping Firewall</title> + <indexterm><primary>firewall</primary></indexterm> + <indexterm><primary>NAT</primary></indexterm> + + <para>A common situation is where firewall functionality is + needed without routing or network address translation (NAT).</para> + + <para>An example is a small company that is connected via DSL + or ISDN to their ISP. They have a 13 globally-accessible IP + addresses from their ISP and have 10 PCs on their network. + In this situation, using a router-based firewall is + difficult because of subnetting issues.</para> + + <indexterm><primary>router</primary></indexterm> + <indexterm><primary>DSL</primary></indexterm> + <indexterm><primary>ISDN</primary></indexterm> + <para>A bridge-based firewall can be configured and dropped into the + path just downstream of their DSL/ISDN router without any IP + numbering issues.</para> + </sect3> + + <sect3> + <title>Network Tap</title> + + <para>A bridge can join two network segments and be used to + inspect all Ethernet frames that pass between them. This can + either be from using &man.bpf.4;/&man.tcpdump.1; on the + bridge interface or by sending a copy of all frames out an + additional interface (span port).</para> + </sect3> + + <sect3> + <title>Layer 2 VPN</title> + + <para>Two Ethernet networks can be joined across an IP link by + bridging the networks to an EtherIP tunnel or a &man.tap.4; + based solution such as OpenVPN.</para> + </sect3> + + <sect3> + <title>Layer 2 Redundancy</title> + + <para>A network can be connected together with multiple links + and use the Spanning Tree Protocol to block redundant paths. + For an Ethernet network to function properly only one active + path can exist between two devices, Spanning Tree will + detect loops and put the redundant links into a blocked + state. Should one of the active links fail then the + protocol will calculate a different tree and reenable one of + the blocked paths to restore connectivity to all points in + the network.</para> + </sect3> + </sect2> + + <sect2> + <title>Kernel Configuration</title> + + <para>This section covers &man.if.bridge.4; bridge + implementation, a netgraph bridging driver is also available, + for more information see &man.ng.bridge.4; manual page.</para> + + <para>The bridge driver is a kernel module and will be + automatically loaded by &man.ifconfig.8; when creating a + bridge interface. It is possible to compile the bridge in to + the kernel by adding <literal>device if_bridge</literal> to + your kernel configuration file.</para> + + <para>Packet filtering can be used with any firewall package + that hooks in via the &man.pfil.9; framework. The firewall + can be loaded as a module or compiled into the kernel.</para> + + <para>The bridge can be used as a traffic shaper with + &man.altq.4; or &man.dummynet.4;.</para> + </sect2> + + <sect2> + <title>Enabling the Bridge</title> + + <para>The bridge is created using interface cloning. To create + a bridge use &man.ifconfig.8;, if the bridge driver is not + present in the kernel then it will be loaded + automatically.</para> + + <screen>&prompt.root; <userinput>ifconfig bridge create</userinput> +bridge0 +&prompt.root; <userinput>ifconfig bridge0</userinput> +bridge0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 96:3d:4b:f1:79:7a + id 00:00:00:00:00:00 priority 32768 hellotime 2 fwddelay 15 + maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 + root id 00:00:00:00:00:00 priority 0 ifcost 0 port 0</screen> + + <para>A bridge interface is created and is automatically + assigned a randomly generated Ethernet address. The + <literal>maxaddr</literal> and <literal>timeout</literal> + parameters control how many MAC addresses the bridge will keep + in its forwarding table and how many seconds before each entry + is removed after it is last seen. The other parameters + control how Spanning Tree operates.</para> + + <para>Add the member network interfaces to the bridge. For the + bridge to forward packets all member interfaces and the bridge + need to be up:</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 up</userinput> +&prompt.root; <userinput>ifconfig fxp0 up</userinput> +&prompt.root; <userinput>ifconfig fxp1 up</userinput></screen> + + <para>The bridge is now forwarding Ethernet frames between + <filename>fxp0</filename> and + <filename>fxp1</filename>. The equivalent configuration + in <filename>/etc/rc.conf</filename> so the bridge is created + at startup is:</para> + + <programlisting>cloned_interfaces="bridge0" +ifconfig_bridge0="addm fxp0 addm fxp1 up" +ifconfig_fxp0="up" +ifconfig_fxp1="up"</programlisting> + + <para>If the bridge host needs an IP address then the correct + place to set this is on the bridge interface itself rather + than one of the member interfaces. This can be set statically + or via DHCP:</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen> + + <para>It is also possible to assign an IPv6 address to a bridge + interface.</para> + </sect2> + + <sect2> + <title>Firewalling</title> + <indexterm><primary>firewall</primary></indexterm> + + <para>When packet filtering is enabled, bridged packets will + pass through the filter inbound on the originating interface, + on the bridge interface and outbound on the appropriate + interfaces. Either stage can be disabled. When direction of + the packet flow is important it is best to firewall on the + member interfaces rather than the bridge itself.</para> + + <para>The bridge has several configurable settings for passing + non-IP and ARP packets, and layer2 firewalling with IPFW. See + &man.if.bridge.4; for more information.</para> + </sect2> + + <sect2> + <title>Spanning Tree</title> + + <para>The bridge driver implements the Rapid Spanning Tree + Protocol (RSTP or 802.1w) with backwards compatibility with + the legacy Spanning Tree Protocol (STP). Spanning Tree is + used to detect and remove loops in a network topology. RSTP + provides faster Spanning Tree convergence than legacy STP, the + protocol will exchange information with neighbouring switches + to quickly transition to forwarding without creating + loops.</para> + + <para>The following table shows the supported operating + modes:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>OS Version</entry> + <entry>STP Modes</entry> + <entry>Default Mode</entry> + </row> + </thead> + + <tbody> + <row> + <entry>&os; 5.4—&os; 6.2</entry> + <entry>STP</entry> + <entry>STP</entry> + </row> + + <row> + <entry>&os; 6.3+</entry> + <entry>RSTP or STP</entry> + <entry>STP</entry> + </row> + + <row> + <entry>&os; 7.0+</entry> + <entry>RSTP or STP</entry> + <entry>RSTP</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Spanning Tree can be enabled on member interfaces using + the <literal>stp</literal> command. For a bridge with + <filename>fxp0</filename> and + <filename>fxp1</filename> as the current interfaces, + enable STP with the following:</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 stp fxp0 stp fxp1</userinput> +bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether d6:cf:d5:a0:94:6d + id 00:01:02:4b:d4:50 priority 32768 hellotime 2 fwddelay 15 + maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 + root id 00:01:02:4b:d4:50 priority 32768 ifcost 0 port 0 + member: fxp0 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> + port 3 priority 128 path cost 200000 proto rstp + role designated state forwarding + member: fxp1 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> + port 4 priority 128 path cost 200000 proto rstp + role designated state forwarding</screen> + + <para>This bridge has a spanning tree ID of + <literal>00:01:02:4b:d4:50</literal> and a priority of + <literal>32768</literal>. As the <literal>root id</literal> + is the same it indicates that this is the root bridge for the + tree.</para> + + <para>Another bridge on the network also has spanning tree + enabled:</para> + + <screen>bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 96:3d:4b:f1:79:7a + id 00:13:d4:9a:06:7a priority 32768 hellotime 2 fwddelay 15 + maxage 20 holdcnt 6 proto rstp maxaddr 100 timeout 1200 + root id 00:01:02:4b:d4:50 priority 32768 ifcost 400000 port 4 + member: fxp0 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> + port 4 priority 128 path cost 200000 proto rstp + role root state forwarding + member: fxp1 flags=1c7<LEARNING,DISCOVER,STP,AUTOEDGE,PTP,AUTOPTP> + port 5 priority 128 path cost 200000 proto rstp + role designated state forwarding</screen> + + <para>The line <literal>root id 00:01:02:4b:d4:50 priority 32768 + ifcost 400000 port 4</literal> shows that the root bridge is + <literal>00:01:02:4b:d4:50</literal> as above and has a path + cost of <literal>400000</literal> from this bridge, the path + to the root bridge is via <literal>port 4</literal> which is + <filename>fxp0</filename>.</para> + </sect2> + + <sect2> + <title>Advanced Bridging</title> + + <sect3> + <title>Reconstruct Traffic Flows</title> + + <para>The bridge supports monitor mode, where the packets are + discarded after &man.bpf.4; processing, and are not + processed or forwarded further. This can be used to + multiplex the input of two or more interfaces into a single + &man.bpf.4; stream. This is useful for reconstructing the + traffic for network taps that transmit the RX/TX signals out + through two separate interfaces.</para> + + <para>To read the input from four network interfaces as one + stream:</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 addm fxp0 addm fxp1 addm fxp2 addm fxp3 monitor up</userinput> +&prompt.root; <userinput>tcpdump -i bridge0</userinput></screen> + </sect3> + + <sect3> + <title>Span Ports</title> + + <para>A copy of every Ethernet frame received by the bridge + will be transmitted out a designated span port. The number + of span ports configured on a bridge is unlimited, if an + interface is designated as a span port then it may not also + be used as a regular bridge port. This is most useful for + snooping a bridged network passively on another host + connected to one of the span ports of the bridge.</para> + + <para>To send a copy of all frames out the interface named + <filename>fxp4</filename>:</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 span fxp4</userinput></screen> + </sect3> + + <sect3> + <title>Private Interfaces</title> + + <para>A private interface does not forward any traffic to any + other port that is also a private interface. The traffic is + blocked unconditionally so no Ethernet frames will be + forwarded, including ARP. If traffic needs to be + selectively blocked then a firewall should be used + instead.</para> + </sect3> + + <sect3> + <title>Sticky Interfaces</title> + + <para>If a bridge member interface is marked as sticky then + dynamically learned address entries are treated at static once + entered into the forwarding cache. Sticky entries are never + aged out of the cache or replaced, even if the address is seen + on a different interface. This gives the benefit of static + address entries without the need to pre-populate the + forwarding table, clients learnt on a particular segment of + the bridge can not roam to another segment.</para> + + <para>Another example of using sticky addresses would be to + combine the bridge with VLANs to create a router where + customer networks are isolated without wasting IP address + space. Consider that <systemitem class="fqdomainname">CustomerA</systemitem> is on + <literal>vlan100</literal> and <systemitem class="fqdomainname">CustomerB</systemitem> is on + <literal>vlan101</literal>. The bridge has the address + <systemitem class="ipaddress">192.168.0.1</systemitem> and is also an + internet router.</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 addm vlan100 sticky vlan100 addm vlan101 sticky vlan101</userinput> +&prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen> + + <para>Both clients see <systemitem class="ipaddress">192.168.0.1</systemitem> as their default gateway + and since the bridge cache is sticky they can not spoof the + MAC address of the other customer to intercept their + traffic.</para> + + <para>Any communication between the VLANs can be blocked using + private interfaces (or a firewall):</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 private vlan100 private vlan101</userinput></screen> + + <para>The customers are completely isolated from each other, + the full <systemitem class="netmask">/24</systemitem> address range + can be allocated without subnetting.</para> + </sect3> + + <sect3> + <title>SNMP Monitoring</title> + + <para>The bridge interface and STP parameters can be monitored + via the SNMP daemon which is included in the &os; base + system. The exported bridge MIBs conform to the IETF + standards so any SNMP client or monitoring package can be + used to retrieve the data.</para> + + <para>On the bridge machine uncomment the + <literal>begemotSnmpdModulePath."bridge" = + "/usr/lib/snmp_bridge.so"</literal> line from + <filename>/etc/snmp.config</filename> and start the + <application>bsnmpd</application> daemon. Other + configuration such as community names and access lists may + need to be modified. See &man.bsnmpd.1; and + &man.snmp.bridge.3; for more information.</para> + + <para>The following examples use the + <application>Net-SNMP</application> software (<package>net-mgmt/net-snmp</package>) to query a + bridge, the <package>net-mgmt/bsnmptools</package> port can also + be used. From the SNMP client host add to + <filename>$HOME/.snmp/snmp.conf</filename> the following + lines to import the bridge MIB definitions in to + <application>Net-SNMP</application>:</para> + + <programlisting>mibdirs +/usr/share/snmp/mibs +mibs +BRIDGE-MIB:RSTP-MIB:BEGEMOT-MIB:BEGEMOT-BRIDGE-MIB</programlisting> + + <para>To monitor a single bridge via the IETF BRIDGE-MIB + (RFC4188) do</para> + + <screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com mib-2.dot1dBridge</userinput> +BRIDGE-MIB::dot1dBaseBridgeAddress.0 = STRING: 66:fb:9b:6e:5c:44 +BRIDGE-MIB::dot1dBaseNumPorts.0 = INTEGER: 1 ports +BRIDGE-MIB::dot1dStpTimeSinceTopologyChange.0 = Timeticks: (189959) 0:31:39.59 centi-seconds +BRIDGE-MIB::dot1dStpTopChanges.0 = Counter32: 2 +BRIDGE-MIB::dot1dStpDesignatedRoot.0 = Hex-STRING: 80 00 00 01 02 4B D4 50 +... +BRIDGE-MIB::dot1dStpPortState.3 = INTEGER: forwarding(5) +BRIDGE-MIB::dot1dStpPortEnable.3 = INTEGER: enabled(1) +BRIDGE-MIB::dot1dStpPortPathCost.3 = INTEGER: 200000 +BRIDGE-MIB::dot1dStpPortDesignatedRoot.3 = Hex-STRING: 80 00 00 01 02 4B D4 50 +BRIDGE-MIB::dot1dStpPortDesignatedCost.3 = INTEGER: 0 +BRIDGE-MIB::dot1dStpPortDesignatedBridge.3 = Hex-STRING: 80 00 00 01 02 4B D4 50 +BRIDGE-MIB::dot1dStpPortDesignatedPort.3 = Hex-STRING: 03 80 +BRIDGE-MIB::dot1dStpPortForwardTransitions.3 = Counter32: 1 +RSTP-MIB::dot1dStpVersion.0 = INTEGER: rstp(2)</screen> + + <para>The <literal>dot1dStpTopChanges.0</literal> value is two + which means that the STP bridge topology has changed twice, + a topology change means that one or more links in the + network have changed or failed and a new tree has been + calculated. The + <literal>dot1dStpTimeSinceTopologyChange.0</literal> value + will show when this happened.</para> + + <para>To monitor multiple bridge interfaces one may use the + private BEGEMOT-BRIDGE-MIB:</para> + + <screen>&prompt.user; <userinput>snmpwalk -v 2c -c public bridge1.example.com</userinput> +enterprises.fokus.begemot.begemotBridge +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge0" = STRING: bridge0 +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseName."bridge2" = STRING: bridge2 +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge0" = STRING: e:ce:3b:5a:9e:13 +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseAddress."bridge2" = STRING: 12:5e:4d:74:d:fc +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge0" = INTEGER: 1 +BEGEMOT-BRIDGE-MIB::begemotBridgeBaseNumPorts."bridge2" = INTEGER: 1 +... +BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge0" = Timeticks: (116927) 0:19:29.27 centi-seconds +BEGEMOT-BRIDGE-MIB::begemotBridgeStpTimeSinceTopologyChange."bridge2" = Timeticks: (82773) 0:13:47.73 centi-seconds +BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge0" = Counter32: 1 +BEGEMOT-BRIDGE-MIB::begemotBridgeStpTopChanges."bridge2" = Counter32: 1 +BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge0" = Hex-STRING: 80 00 00 40 95 30 5E 31 +BEGEMOT-BRIDGE-MIB::begemotBridgeStpDesignatedRoot."bridge2" = Hex-STRING: 80 00 00 50 8B B8 C6 A9</screen> + + <para>To change the bridge interface being monitored via the + <literal>mib-2.dot1dBridge</literal> subtree do:</para> + + <screen>&prompt.user; <userinput>snmpset -v 2c -c private bridge1.example.com</userinput> +BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="network-aggregation"> + <info><title>Link Aggregation and Failover</title> + <authorgroup> + <author><personname><firstname>Andrew</firstname><surname>Thompson</surname></personname><contrib>Written by </contrib></author> + </authorgroup> + </info> + + + <indexterm><primary>lagg</primary></indexterm> + <indexterm><primary>failover</primary></indexterm> + <indexterm><primary>fec</primary></indexterm> + <indexterm><primary>lacp</primary></indexterm> + <indexterm><primary>loadbalance</primary></indexterm> + <indexterm><primary>roundrobin</primary></indexterm> + + <sect2> + <title>Introduction</title> + <para>The &man.lagg.4; interface allows aggregation of multiple network + interfaces as one virtual interface for the purpose of providing + fault-tolerance and high-speed links.</para> + </sect2> + + <sect2> + <title>Operating Modes</title> + + <variablelist> + + <varlistentry><term>failover</term> + + <listitem> + <para>Sends and receives traffic only through the master port. If the + master port becomes unavailable, the next active port is used. The + first interface added is the master port; any interfaces added after + that are used as failover devices.</para> + </listitem> + </varlistentry> + + <varlistentry><term>fec</term> + + <listitem> + <para>Supports Cisco EtherChannel. This is a static setup and does not + negotiate aggregation with the peer or exchange frames to monitor the + link, if the switch supports LACP then that should be used + instead.</para> + + <para>Balances outgoing traffic across the active ports based on hashed + protocol header information and accepts incoming traffic from any + active port. The hash includes the Ethernet source and destination + address, and, if available, the VLAN tag, and the IPv4/IPv6 source + and destination address.</para> + </listitem> + </varlistentry> + + <varlistentry><term>lacp</term> + + <listitem> + <para>Supports the IEEE 802.3ad Link Aggregation Control Protocol + (LACP) and the Marker Protocol. LACP will negotiate a set of + aggregable links with the peer in to one or more Link Aggregated + Groups. Each LAG is composed of ports of the same speed, set to + full-duplex operation. The traffic will be balanced across the ports + in the LAG with the greatest total speed, in most cases there will + only be one LAG which contains all ports. In the event of changes in + physical connectivity, Link Aggregation will quickly converge to a + new configuration.</para> + + <para>Balances outgoing traffic across the active ports based on hashed + protocol header information and accepts incoming traffic from any + active port. The hash includes the Ethernet source and destination + address, and, if available, the VLAN tag, and the IPv4/IPv6 source + and destination address.</para> + </listitem> + </varlistentry> + + <varlistentry><term>loadbalance</term> + + <listitem> + <para>This is an alias of <emphasis>fec</emphasis> mode.</para> + </listitem> + </varlistentry> + + <varlistentry><term>roundrobin</term> + + <listitem> + <para>Distributes outgoing traffic using a round-robin scheduler + through all active ports and accepts incoming traffic from any active + port. This mode will violate Ethernet frame ordering and should be + used with caution.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2> + <title>Examples</title> + + <example xml:id="networking-lacp-aggregation-cisco"> + <title>LACP aggregation with a Cisco switch</title> + + <para>This example connects two interfaces on a &os; machine to the + switch as a single load balanced and fault tolerant link. More interfaces + can be added to increase throughput and fault tolerance. Since frame + ordering is mandatory on Ethernet links then any traffic between two + stations always flows over the same physical link limiting the maximum + speed to that of one interface. The transmit algorithm attempts to use as + much information as it can to distinguish different traffic flows and + balance across the available interfaces.</para> + + <para>On the Cisco switch add the interfaces to the channel group.</para> + + <screen>interface FastEthernet0/1 + channel-group 1 mode active + channel-protocol lacp +! +interface FastEthernet0/2 + channel-group 1 mode active + channel-protocol lacp +!</screen> + + <para>On the &os; machine create the lagg interface.</para> + + <screen>&prompt.root; <userinput>ifconfig lagg0 create</userinput> +&prompt.root; <userinput>ifconfig lagg0 up laggproto lacp laggport fxp0 laggport fxp1</userinput></screen> + + <para>View the interface status from ifconfig; ports marked as + <emphasis>ACTIVE</emphasis> are part of the active aggregation group + that has been negotiated with the remote switch and traffic will be + transmitted and received. Use the verbose output of &man.ifconfig.8; + to view the LAG identifiers.</para> + + <screen>lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=8<VLAN_MTU> + ether 00:05:5d:71:8d:b8 + media: Ethernet autoselect + status: active + laggproto lacp + laggport: fxp1 flags=1c<ACTIVE,COLLECTING,DISTRIBUTING> + laggport: fxp0 flags=1c<ACTIVE,COLLECTING,DISTRIBUTING></screen> + + <para>The switch will show which ports are active. For more detail use + <userinput>show lacp neighbor detail</userinput>.</para> + + <screen>switch# show lacp neighbor +Flags: S - Device is requesting Slow LACPDUs + F - Device is requesting Fast LACPDUs + A - Device is in Active mode P - Device is in Passive mode + +Channel group 1 neighbors + +Partner's information: + + LACP port Oper Port Port +Port Flags Priority Dev ID Age Key Number State +Fa0/1 SA 32768 0005.5d71.8db8 29s 0x146 0x3 0x3D +Fa0/2 SA 32768 0005.5d71.8db8 29s 0x146 0x4 0x3D</screen> + + </example> + <example xml:id="networking-lagg-failover"> + <title>Failover mode</title> + + <para>Failover mode can be used to switch over to another interface if + the link is lost on the master.</para> + + <screen>&prompt.root; <userinput>ifconfig lagg0 create</userinput> +&prompt.root; <userinput>ifconfig lagg0 up laggproto failover laggport fxp0 laggport fxp1</userinput></screen> + + <screen>lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=8<VLAN_MTU> + ether 00:05:5d:71:8d:b8 + media: Ethernet autoselect + status: active + laggproto failover + laggport: fxp1 flags=0<> + laggport: fxp0 flags=5<MASTER,ACTIVE></screen> + + <para>Traffic will be transmitted and received on + <filename>fxp0</filename>. If the link is lost on + <filename>fxp0</filename> then <filename>fxp1</filename> will + become the active link. If the link is restored on the master + interface then it will once again become the active link.</para> + </example> + </sect2> + </sect1> + + <sect1 xml:id="network-diskless"> + <info><title>Diskless Operation</title> + <authorgroup> + <author><personname><firstname>Jean-François</firstname><surname>Dockès</surname></personname><contrib>Updated by </contrib></author> + </authorgroup> + <authorgroup> + <author><personname><firstname>Alex</firstname><surname>Dupre</surname></personname><contrib>Reorganized and enhanced by </contrib></author> + </authorgroup> + </info> + + + <indexterm><primary>diskless workstation</primary></indexterm> + <indexterm><primary>diskless operation</primary></indexterm> + + <para>A FreeBSD machine can boot over the network and operate without a + local disk, using file systems mounted from an <acronym>NFS</acronym> server. No system + modification is necessary, beyond standard configuration files. + Such a system is relatively easy to set up because all the necessary elements + are readily available:</para> + <itemizedlist> + <listitem> + <para>There are at least two possible methods to load the kernel over + the network:</para> + <itemizedlist> + <listitem> + <para><acronym>PXE</acronym>: The &intel; Preboot eXecution + Environment system is a form of smart boot ROM built into some + networking cards or motherboards. See &man.pxeboot.8; for more + details.</para> + </listitem> + <listitem> + <para>The <application>Etherboot</application> + port (<package>net/etherboot</package>) produces + ROM-able code to boot kernels over the network. The + code can be either burnt into a boot PROM on a network + card, or loaded from a local floppy (or hard) disk + drive, or from a running &ms-dos; system. Many network + cards are supported.</para> + </listitem> + </itemizedlist> + </listitem> + + <listitem> + <para>A sample script + (<filename>/usr/share/examples/diskless/clone_root</filename>) eases + the creation and maintenance of the workstation's root file system + on the server. The script will probably require a little + customization but it will get you started very quickly.</para> + </listitem> + + <listitem> + <para>Standard system startup files exist in <filename>/etc</filename> + to detect and support a diskless system startup.</para> + </listitem> + + <listitem> + <para>Swapping, if needed, can be done either to an <acronym>NFS</acronym> file or to + a local disk.</para> + </listitem> + </itemizedlist> + + <para>There are many ways to set up diskless workstations. Many + elements are involved, and most can be customized to suit local + taste. The following will describe variations on the setup of a complete system, + emphasizing simplicity and compatibility with the + standard FreeBSD startup scripts. The system described has the + following characteristics:</para> + + <itemizedlist> + <listitem> + <para>The diskless workstations use a shared + read-only <filename>/</filename> file system, and a shared + read-only <filename>/usr</filename>.</para> + <para>The root file system is a copy of a + standard FreeBSD root (typically the server's), with some + configuration files overridden by ones specific to diskless + operation or, possibly, to the workstation they belong to.</para> + <para>The parts of the root which have to be + writable are overlaid with &man.md.4; file systems. Any changes + will be lost when the system reboots.</para> + </listitem> + <listitem> + <para>The kernel is transferred and loaded either with + <application>Etherboot</application> or <acronym>PXE</acronym> + as some situations may mandate the use of either method.</para> + </listitem> + </itemizedlist> + + <caution><para>As described, this system is insecure. It should + live in a protected area of a network, and be untrusted by + other hosts.</para> + </caution> + + <para>All the information in this section has been tested + using &os; 5.2.1-RELEASE.</para> + + <sect2> + <title>Background Information</title> + + <para>Setting up diskless workstations is both relatively + straightforward and prone to errors. These are sometimes + difficult to diagnose for a number of reasons. For example:</para> + + <itemizedlist> + <listitem> + <para>Compile time options may determine different behaviors at + runtime.</para> + </listitem> + + <listitem> + <para>Error messages are often cryptic or totally absent.</para> + </listitem> + </itemizedlist> + + <para>In this context, having some knowledge of the background + mechanisms involved is very useful to solve the problems that + may arise.</para> + + <para>Several operations need to be performed for a successful + bootstrap:</para> + + <itemizedlist> + <listitem> + <para>The machine needs to obtain initial parameters such as its IP + address, executable filename, server name, root path. This is + done using the <acronym>DHCP</acronym> or BOOTP protocols. + <acronym>DHCP</acronym> is a compatible extension of BOOTP, and + uses the same port numbers and basic packet format.</para> + + <para>It is possible to configure a system to use only BOOTP. + The &man.bootpd.8; server program is included in the base &os; + system.</para> + + <para>However, <acronym>DHCP</acronym> has a number of advantages + over BOOTP (nicer configuration files, possibility of using + <acronym>PXE</acronym>, plus many others not directly related to + diskless operation), and we will describe mainly a + <acronym>DHCP</acronym> configuration, with equivalent examples + using &man.bootpd.8; when possible. The sample configuration will + use the <application>ISC DHCP</application> software package + (release 3.0.1.r12 was installed on the test server).</para> + </listitem> + + <listitem> + <para>The machine needs to transfer one or several programs to local + memory. Either <acronym>TFTP</acronym> or <acronym>NFS</acronym> + are used. The choice between <acronym>TFTP</acronym> and + <acronym>NFS</acronym> is a compile time option in several places. + A common source of error is to specify filenames for the wrong + protocol: <acronym>TFTP</acronym> typically transfers all files from + a single directory on the server, and would expect filenames + relative to this directory. <acronym>NFS</acronym> needs absolute + file paths.</para> + </listitem> + + <listitem> + <para>The possible intermediate bootstrap programs and the kernel + need to be initialized and executed. There are several important + variations in this area:</para> + + <itemizedlist> + <listitem> + <para><acronym>PXE</acronym> will load &man.pxeboot.8;, which is + a modified version of the &os; third stage loader. The + &man.loader.8; will obtain most parameters necessary to system + startup, and leave them in the kernel environment before + transferring control. It is possible to use a + <filename>GENERIC</filename> kernel in this case.</para> + </listitem> + + <listitem> + <para><application>Etherboot</application>, will directly + load the kernel, with less preparation. You will need to + build a kernel with specific options.</para> + </listitem> + </itemizedlist> + + <para><acronym>PXE</acronym> and <application>Etherboot</application> + work equally well; however, because kernels + normally let the &man.loader.8; do more work for them, + <acronym>PXE</acronym> is the preferred method.</para> + + <para>If your <acronym>BIOS</acronym> and network cards support + <acronym>PXE</acronym>, you should probably use it.</para> + </listitem> + + <listitem> + <para>Finally, the machine needs to access its file systems. + <acronym>NFS</acronym> is used in all cases.</para> + </listitem> + </itemizedlist> + + <para>See also &man.diskless.8; manual page.</para> + </sect2> + + <sect2> + <title>Setup Instructions</title> + + <sect3> + <title>Configuration Using <application>ISC DHCP</application></title> + <indexterm> + <primary>DHCP</primary> + <secondary>diskless operation</secondary> + </indexterm> + + <para>The <application>ISC DHCP</application> server can answer + both BOOTP and <acronym>DHCP</acronym> requests.</para> + + <para><application>ISC DHCP + 3.0</application> is not part of the base + system. You will first need to install the + <package>net/isc-dhcp3-server</package> port or the + corresponding package.</para> + + <para>Once <application>ISC DHCP</application> is installed, it + needs a configuration file to run (normally named + <filename>/usr/local/etc/dhcpd.conf</filename>). Here follows + a commented example, where host <systemitem>margaux</systemitem> + uses <application>Etherboot</application> and host + <systemitem>corbieres</systemitem> uses <acronym>PXE</acronym>:</para> + + <programlisting> +default-lease-time 600; +max-lease-time 7200; +authoritative; + +option domain-name "example.com"; +option domain-name-servers 192.168.4.1; +option routers 192.168.4.1; + +subnet 192.168.4.0 netmask 255.255.255.0 { + use-host-decl-names on; <co xml:id="co-dhcp-host-name"/> + option subnet-mask 255.255.255.0; + option broadcast-address 192.168.4.255; + + host margaux { + hardware ethernet 01:23:45:67:89:ab; + fixed-address margaux.example.com; + next-server 192.168.4.4; <co xml:id="co-dhcp-next-server"/> + filename "/data/misc/kernel.diskless"; <co xml:id="co-dhcp-filename"/> + option root-path "192.168.4.4:/data/misc/diskless"; <co xml:id="co-dhcp-root-path"/> + } + host corbieres { + hardware ethernet 00:02:b3:27:62:df; + fixed-address corbieres.example.com; + next-server 192.168.4.4; + filename "pxeboot"; + option root-path "192.168.4.4:/data/misc/diskless"; + } +} + </programlisting> + + <calloutlist> + <callout arearefs="co-dhcp-host-name"><para>This option tells + <application>dhcpd</application> to send the value in the + <literal>host</literal> declarations as the hostname for the + diskless host. An alternate way would be to add an + <literal>option host-name + margaux</literal> inside the + <literal>host</literal> declarations.</para> + </callout> + + <callout arearefs="co-dhcp-next-server"><para>The + <literal>next-server</literal> directive designates + the <acronym>TFTP</acronym> or <acronym>NFS</acronym> server to + use for loading loader or kernel file (the default is to use + the same host as the + <acronym>DHCP</acronym> server).</para> + </callout> + + <callout arearefs="co-dhcp-filename"><para>The + <literal>filename</literal> directive defines the file that + <application>Etherboot</application> or <acronym>PXE</acronym> + will load for the next execution step. It must be specified + according to the transfer method used. + <application>Etherboot</application> can be compiled to use + <acronym>NFS</acronym> or <acronym>TFTP</acronym>. The &os; + port configures <acronym>NFS</acronym> by default. + <acronym>PXE</acronym> uses <acronym>TFTP</acronym>, which is + why a relative filename is used here (this may depend on the + <acronym>TFTP</acronym> server configuration, but would be + fairly typical). Also, <acronym>PXE</acronym> loads + <filename>pxeboot</filename>, not the kernel. There are other + interesting possibilities, like loading + <filename>pxeboot</filename> from a &os; CD-ROM + <filename>/boot</filename> directory (as + &man.pxeboot.8; can load a <filename>GENERIC</filename> kernel, + this makes it possible to use <acronym>PXE</acronym> to boot + from a remote CD-ROM).</para> + </callout> + + <callout arearefs="co-dhcp-root-path"><para>The + <literal>root-path</literal> option defines the path to + the root file system, in usual <acronym>NFS</acronym> notation. + When using <acronym>PXE</acronym>, it is possible to leave off + the host's IP as long as you do not enable the kernel option + BOOTP. The <acronym>NFS</acronym> server will then be + the same as the <acronym>TFTP</acronym> one.</para> + </callout> + </calloutlist> + + </sect3> + <sect3> + <title>Configuration Using BOOTP</title> + <indexterm> + <primary>BOOTP</primary> + <secondary>diskless operation</secondary> + </indexterm> + + <para>Here follows an equivalent <application>bootpd</application> + configuration (reduced to one client). This would be found in + <filename>/etc/bootptab</filename>.</para> + + <para>Please note that <application>Etherboot</application> + must be compiled with the non-default option + <literal>NO_DHCP_SUPPORT</literal> in order to use BOOTP, + and that <acronym>PXE</acronym> <emphasis>needs</emphasis> <acronym>DHCP</acronym>. The only + obvious advantage of <application>bootpd</application> is + that it exists in the base system.</para> + + <programlisting> +.def100:\ + :hn:ht=1:sa=192.168.4.4:vm=rfc1048:\ + :sm=255.255.255.0:\ + :ds=192.168.4.1:\ + :gw=192.168.4.1:\ + :hd="/tftpboot":\ + :bf="/kernel.diskless":\ + :rp="192.168.4.4:/data/misc/diskless": + +margaux:ha=0123456789ab:tc=.def100 + </programlisting> + </sect3> + + <sect3> + <title>Preparing a Boot Program with + <application>Etherboot</application></title> + + <indexterm> + <primary>Etherboot</primary> + </indexterm> + + <para><link xlink:href="http://etherboot.sourceforge.net">Etherboot's Web + site</link> contains + <link xlink:href="http://etherboot.sourceforge.net/doc/html/userman/t1.html"> + extensive documentation</link> mainly intended for Linux + systems, but nonetheless containing useful information. The + following will just outline how you would use + <application>Etherboot</application> on a FreeBSD + system.</para> + + <para>You must first install the <package>net/etherboot</package> package or port.</para> + + <para>You can change the <application>Etherboot</application> + configuration (i.e. to use <acronym>TFTP</acronym> instead of + <acronym>NFS</acronym>) by editing the <filename>Config</filename> + file in the <application>Etherboot</application> source + directory.</para> + + <para>For our setup, we shall use a boot floppy. For other methods + (PROM, or &ms-dos; program), please refer to the + <application>Etherboot</application> documentation.</para> + + <para>To make a boot floppy, insert a floppy in the drive on the + machine where you installed <application>Etherboot</application>, + then change your current directory to the <filename>src</filename> + directory in the <application>Etherboot</application> tree and + type:</para> + + <screen> +&prompt.root; <userinput>gmake bin32/devicetype.fd0</userinput> + </screen> + + <para><replaceable>devicetype</replaceable> depends on the type of + the Ethernet card in the diskless workstation. Refer to the + <filename>NIC</filename> file in the same directory to determine the + right <replaceable>devicetype</replaceable>.</para> + + </sect3> + + <sect3> + <title>Booting with <acronym>PXE</acronym></title> + + <para>By default, the &man.pxeboot.8; loader loads the kernel via + <acronym>NFS</acronym>. It can be compiled to use + <acronym>TFTP</acronym> instead by specifying the + <literal>LOADER_TFTP_SUPPORT</literal> option in + <filename>/etc/make.conf</filename>. See the comments in + <filename>/usr/share/examples/etc/make.conf</filename> + for instructions.</para> + + <para>There are two other <filename>make.conf</filename> + options which may be useful for setting up a serial console diskless + machine: <literal>BOOT_PXELDR_PROBE_KEYBOARD</literal>, and + <literal>BOOT_PXELDR_ALWAYS_SERIAL</literal>.</para> + + <para>To use <acronym>PXE</acronym> when the machine starts, you will + usually need to select the <literal>Boot from network</literal> + option in your <acronym>BIOS</acronym> setup, or type a function key + during the PC initialization.</para> + </sect3> + + <sect3> + <title>Configuring the <acronym>TFTP</acronym> and <acronym>NFS</acronym> Servers</title> + + <indexterm> + <primary>TFTP</primary> + <secondary>diskless operation</secondary> + </indexterm> + <indexterm> + <primary>NFS</primary> + <secondary>diskless operation</secondary> + </indexterm> + + <para>If you are using <acronym>PXE</acronym> or + <application>Etherboot</application> configured to use + <acronym>TFTP</acronym>, you need to enable + <application>tftpd</application> on the file server:</para> + <procedure> + <step> + <para>Create a directory from which <application>tftpd</application> + will serve the files, e.g. <filename>/tftpboot</filename>.</para> + </step> + + <step> + <para>Add this line to your + <filename>/etc/inetd.conf</filename>:</para> + + <programlisting>tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /tftpboot</programlisting> + + <note><para>It appears that at least some <acronym>PXE</acronym> versions want + the <acronym>TCP</acronym> version of <acronym>TFTP</acronym>. In this case, add a second line, + replacing <literal>dgram udp</literal> with <literal>stream + tcp</literal>.</para> + </note> + </step> + <step> + <para>Tell <application>inetd</application> to reread its configuration + file. The <option>inetd_enable="YES"</option> must be in + the <filename>/etc/rc.conf</filename> file for this + command to execute correctly:</para> + <screen>&prompt.root; <userinput>/etc/rc.d/inetd restart</userinput></screen> + </step> + </procedure> + + <para>You can place the <filename>tftpboot</filename> + directory anywhere on the server. Make sure that the + location is set in both <filename>inetd.conf</filename> and + <filename>dhcpd.conf</filename>.</para> + + <para>In all cases, you also need to enable <acronym>NFS</acronym> and export the + appropriate file system on the <acronym>NFS</acronym> server.</para> + + <procedure> + <step> + <para>Add this to <filename>/etc/rc.conf</filename>:</para> + <programlisting>nfs_server_enable="YES"</programlisting> + </step> + + <step> + <para>Export the file system where the diskless root directory + is located by adding the following to + <filename>/etc/exports</filename> (adjust the volume mount + point and replace <replaceable>margaux corbieres</replaceable> + with the names of the diskless workstations):</para> + + <programlisting><replaceable>/data/misc</replaceable> -alldirs -ro <replaceable>margaux corbieres</replaceable></programlisting> + </step> + <step> + <para>Tell <application>mountd</application> to reread its configuration + file. If you actually needed to enable <acronym>NFS</acronym> in + <filename>/etc/rc.conf</filename> + at the first step, you probably want to reboot instead.</para> + <screen>&prompt.root; <userinput>/etc/rc.d/mountd restart</userinput></screen> + </step> + </procedure> + + </sect3> + + <sect3> + <title>Building a Diskless Kernel</title> + + <indexterm> + <primary>diskless operation</primary> + <secondary>kernel configuration</secondary> + </indexterm> + + <para>If using <application>Etherboot</application>, you need to + create a kernel configuration file for the diskless client + with the following options (in addition to the usual ones):</para> + + <programlisting> +options BOOTP # Use BOOTP to obtain IP address/hostname +options BOOTP_NFSROOT # NFS mount root file system using BOOTP info + </programlisting> + + <para>You may also want to use <literal>BOOTP_NFSV3</literal>, + <literal>BOOT_COMPAT</literal> and <literal>BOOTP_WIRED_TO</literal> + (refer to <filename>NOTES</filename>).</para> + + <para>These option names are historical and slightly misleading as + they actually enable indifferent use of <acronym>DHCP</acronym> and + BOOTP inside the kernel (it is also possible to force strict BOOTP + or <acronym>DHCP</acronym> use).</para> + + <para>Build the kernel (see <xref linkend="kernelconfig"/>), + and copy it to the place specified + in <filename>dhcpd.conf</filename>.</para> + + <note> + <para>When using <acronym>PXE</acronym>, building a kernel with the + above options is not strictly necessary (though suggested). + Enabling them will cause more <acronym>DHCP</acronym> requests to be + issued during kernel startup, with a small risk of inconsistency + between the new values and those retrieved by &man.pxeboot.8; in some + special cases. The advantage of using them is that the host name + will be set as a side effect. Otherwise you will need to set the + host name by another method, for example in a client-specific + <filename>rc.conf</filename> file.</para> + </note> + + <note> + <para>In order to be loadable with + <application>Etherboot</application>, a kernel needs to have + the device hints compiled in. You would typically set the + following option in the configuration file (see the + <filename>NOTES</filename> configuration comments file):</para> + + <programlisting>hints "GENERIC.hints"</programlisting> + </note> + + </sect3> + + <sect3> + <title>Preparing the Root Filesystem</title> + + <indexterm> + <primary>root file system</primary> + <secondary>diskless operation</secondary> + </indexterm> + + <para>You need to create a root file system for the diskless + workstations, in the location listed as + <literal>root-path</literal> in + <filename>dhcpd.conf</filename>.</para> + + <sect4> + <title>Using <command>make world</command> to populate root</title> + + <para>This method is quick and + will install a complete virgin system (not only the root file system) + into <envar>DESTDIR</envar>. + All you have to do is simply execute the following script:</para> + + <programlisting>#!/bin/sh +export DESTDIR=/data/misc/diskless +mkdir -p ${DESTDIR} +cd /usr/src; make buildworld && make buildkernel +cd /usr/src/etc; make distribution</programlisting> + + <para>Once done, you may need to customize your + <filename>/etc/rc.conf</filename> and + <filename>/etc/fstab</filename> placed into + <envar>DESTDIR</envar> according to your needs.</para> + </sect4> + </sect3> + + <sect3> + <title>Configuring Swap</title> + + <para>If needed, a swap file located on the server can be + accessed via <acronym>NFS</acronym>.</para> + + <sect4> + <title><acronym>NFS</acronym> Swap</title> + + <para>The kernel does not support enabling <acronym>NFS</acronym> + swap at boot time. Swap must be enabled by the startup scripts, + by mounting a writable file system and creating and enabling a + swap file. To create a swap file of appropriate size, you can do + like this:</para> + + <screen>&prompt.root; <userinput>dd if=/dev/zero of=/path/to/swapfile bs=1k count=1 oseek=100000</userinput></screen> + + <para>To enable it you have to add the following line to your + <filename>rc.conf</filename>:</para> + + <programlisting>swapfile=<replaceable>/path/to/swapfile</replaceable></programlisting> + </sect4> + </sect3> + + <sect3> + <title>Miscellaneous Issues</title> + + + <sect4> + <title>Running with a Read-only <filename>/usr</filename></title> + + <indexterm> + <primary>diskless operation</primary> + <secondary>/usr read-only</secondary> + </indexterm> + + <para>If the diskless workstation is configured to run X, you + will have to adjust the <application>XDM</application> configuration file, which puts + the error log on <filename>/usr</filename> by default.</para> + </sect4> + <sect4> + <title>Using a Non-FreeBSD Server</title> + + <para>When the server for the root file system is not running FreeBSD, + you will have to create the root file system on a + FreeBSD machine, then copy it to its destination, using + <command>tar</command> or <command>cpio</command>.</para> + <para>In this situation, there are sometimes + problems with the special files in <filename>/dev</filename>, + due to differing major/minor integer sizes. A solution to this + problem is to export a directory from the non-FreeBSD server, + mount this directory onto a FreeBSD machine, and + use &man.devfs.5; to allocate device nodes transparently for + the user.</para> + + </sect4> + + </sect3> + + </sect2> + </sect1> + + <sect1 xml:id="network-isdn"> + <title>ISDN</title> + + <indexterm> + <primary>ISDN</primary> + </indexterm> + + <para>A good resource for information on ISDN technology and hardware is + <link xlink:href="http://www.alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN + Page</link>.</para> + + <para>A quick simple road map to ISDN follows:</para> + + <itemizedlist> + <listitem> + <para>If you live in Europe you might want to investigate the ISDN card + section.</para> + </listitem> + + <listitem> + <para>If you are planning to use ISDN primarily to connect to the + Internet with an Internet Provider on a dial-up non-dedicated basis, + you might look into Terminal Adapters. This will give you the + most flexibility, with the fewest problems, if you change + providers.</para> + </listitem> + + <listitem> + <para>If you are connecting two LANs together, or connecting to the + Internet with a dedicated ISDN connection, you might consider + the stand alone router/bridge option.</para> + </listitem> + </itemizedlist> + + <para>Cost is a significant factor in determining what solution you will + choose. The following options are listed from least expensive to most + expensive.</para> + + <sect2 xml:id="network-isdn-cards"> + <info><title>ISDN Cards</title> + <authorgroup> + <author><personname><firstname>Hellmuth</firstname><surname>Michaelis</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + <indexterm> + <primary>ISDN</primary> + <secondary>cards</secondary> + </indexterm> + + <para>FreeBSD's ISDN implementation supports only the DSS1/Q.931 + (or Euro-ISDN) standard using passive cards. Some active cards + are supported where the firmware + also supports other signaling protocols; this also includes the + first supported Primary Rate (PRI) ISDN card.</para> + + <para>The <application>isdn4bsd</application> software allows you to connect + to other ISDN routers using either IP over raw HDLC or by using + synchronous PPP: either by using kernel PPP with <literal>isppp</literal>, a + modified &man.sppp.4; driver, or by using userland &man.ppp.8;. By using + userland &man.ppp.8;, channel bonding of two or more ISDN + B-channels is possible. A telephone answering machine + application is also available as well as many utilities such as + a software 300 Baud modem.</para> + + <para>Some growing number of PC ISDN cards are supported under + FreeBSD and the reports show that it is successfully used all + over Europe and in many other parts of the world.</para> + + <para>The passive ISDN cards supported are mostly the ones with + the Infineon (formerly Siemens) ISAC/HSCX/IPAC ISDN chipsets, + but also ISDN cards with chips from Cologne Chip (ISA bus only), + PCI cards with Winbond W6692 chips, some cards with the + Tiger300/320/ISAC chipset combinations and some vendor specific + chipset based cards such as the AVM Fritz!Card PCI V.1.0 and the + AVM Fritz!Card PnP.</para> + + <para>Currently the active supported ISDN cards are the AVM B1 + (ISA and PCI) BRI cards and the AVM T1 PCI PRI cards.</para> + + <para>For documentation on <application>isdn4bsd</application>, + have a look at <filename>/usr/share/examples/isdn/</filename> + directory on your FreeBSD system or at the <link xlink:href="http://www.freebsd-support.de/i4b/">homepage of + isdn4bsd</link> which also has pointers to hints, erratas and + much more documentation such as the <link xlink:href="http://people.FreeBSD.org/~hm/">isdn4bsd + handbook</link>.</para> + + <para>In case you are interested in adding support for a + different ISDN protocol, a currently unsupported ISDN PC card or + otherwise enhancing <application>isdn4bsd</application>, please + get in touch with &a.hm;.</para> + + <para>For questions regarding the installation, configuration + and troubleshooting <application>isdn4bsd</application>, a + &a.isdn.name; mailing list is available.</para> + </sect2> + + <sect2> + <title>ISDN Terminal Adapters</title> + + <para>Terminal adapters (TA), are to ISDN what modems are to regular + phone lines.</para> + <indexterm><primary>modem</primary></indexterm> + <para>Most TA's use the standard Hayes modem AT command set, and can be + used as a drop in replacement for a modem.</para> + + <para>A TA will operate basically the same as a modem except connection + and throughput speeds will be much faster than your old modem. You + will need to configure <link linkend="ppp">PPP</link> exactly the same + as for a modem setup. Make sure you set your serial speed as high as + possible.</para> + <indexterm><primary>PPP</primary></indexterm> + <para>The main advantage of using a TA to connect to an Internet + Provider is that you can do Dynamic PPP. As IP address space becomes + more and more scarce, most providers are not willing to provide you + with a static IP anymore. Most stand-alone routers are not able to + accommodate dynamic IP allocation.</para> + + <para>TA's completely rely on the PPP daemon that you are running for + their features and stability of connection. This allows you to + upgrade easily from using a modem to ISDN on a FreeBSD machine, if you + already have PPP set up. However, at the same time any problems you + experienced with the PPP program and are going to persist.</para> + + <para>If you want maximum stability, use the kernel <link linkend="ppp">PPP</link> option, not the <link linkend="userppp">userland PPP</link>.</para> + + <para>The following TA's are known to work with FreeBSD:</para> + + <itemizedlist> + <listitem> + <para>Motorola BitSurfer and Bitsurfer Pro</para> + </listitem> + + <listitem> + <para>Adtran</para> + </listitem> + </itemizedlist> + + <para>Most other TA's will probably work as well, TA vendors try to make + sure their product can accept most of the standard modem AT command + set.</para> + + <para>The real problem with external TA's is that, like modems, + you need a good serial card in your computer.</para> + + <para>You should read the <link xlink:href="&url.articles.serial-uart;/index.html">FreeBSD Serial + Hardware</link> tutorial for a detailed understanding of + serial devices, and the differences between asynchronous and + synchronous serial ports.</para> + + <para>A TA running off a standard PC serial port (asynchronous) limits + you to 115.2 Kbs, even though you have a 128 Kbs connection. + To fully utilize the 128 Kbs that ISDN is capable of, + you must move the TA to a synchronous serial card.</para> + + <para>Do not be fooled into buying an internal TA and thinking you have + avoided the synchronous/asynchronous issue. Internal TA's simply have + a standard PC serial port chip built into them. All this will do is + save you having to buy another serial cable and find another empty + electrical socket.</para> + + <para>A synchronous card with a TA is at least as fast as a stand-alone + router, and with a simple 386 FreeBSD box driving it, probably more + flexible.</para> + + <para>The choice of synchronous card/TA v.s. stand-alone router is largely a + religious issue. There has been some discussion of this in + the mailing lists. We suggest you search the <link xlink:href="&url.base;/search/index.html">archives</link> for + the complete discussion.</para> + </sect2> + + <sect2> + <title>Stand-alone ISDN Bridges/Routers</title> + <indexterm> + <primary>ISDN</primary> + <secondary>stand-alone bridges/routers</secondary> + </indexterm> + <para>ISDN bridges or routers are not at all specific to FreeBSD + or any other operating system. For a more complete + description of routing and bridging technology, please refer + to a networking reference book.</para> + + <para>In the context of this section, the terms router and bridge will + be used interchangeably.</para> + + <para>As the cost of low end ISDN routers/bridges comes down, it + will likely become a more and more popular choice. An ISDN + router is a small box that plugs directly into your local + Ethernet network, and manages its own connection to the other + bridge/router. It has built in software to communicate via + PPP and other popular protocols.</para> + + <para>A router will allow you much faster throughput than a + standard TA, since it will be using a full synchronous ISDN + connection.</para> + + <para>The main problem with ISDN routers and bridges is that + interoperability between manufacturers can still be a problem. + If you are planning to connect to an Internet provider, you + should discuss your needs with them.</para> + + <para>If you are planning to connect two LAN segments together, + such as your home LAN to the office LAN, this is the simplest + lowest + maintenance solution. Since you are buying the equipment for + both sides of the connection you can be assured that the link + will work.</para> + + <para>For example to connect a home computer or branch office + network to a head office network the following setup could be + used:</para> + + <example> + <title>Branch Office or Home Network</title> + + <indexterm><primary>10 base 2</primary></indexterm> + <para>Network uses a bus based topology with 10 base 2 + Ethernet (<quote>thinnet</quote>). Connect router to network cable with + AUI/10BT transceiver, if necessary.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="advanced-networking/isdn-bus"/> + </imageobject> + + <textobject> + <literallayout class="monospaced">---Sun workstation +| +---FreeBSD box +| +---Windows 95 +| +Stand-alone router + | +ISDN BRI line</literallayout> + </textobject> + + <textobject> + <phrase>10 Base 2 Ethernet</phrase> + </textobject> + </mediaobject> + + <para>If your home/branch office is only one computer you can use a + twisted pair crossover cable to connect to the stand-alone router + directly.</para> + </example> + + <example> + <title>Head Office or Other LAN</title> + + <indexterm><primary>10 base T</primary></indexterm> + <para>Network uses a star topology with 10 base T Ethernet + (<quote>Twisted Pair</quote>).</para> + + <mediaobject> + <imageobject> + <imagedata fileref="advanced-networking/isdn-twisted-pair"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> -------Novell Server + | H | + | ---Sun + | | + | U ---FreeBSD + | | + | ---Windows 95 + | B | + |___---Stand-alone router + | + ISDN BRI line</literallayout> + </textobject> + + <textobject> + <phrase>ISDN Network Diagram</phrase> + </textobject> + </mediaobject> + </example> + + <para>One large advantage of most routers/bridges is that they allow you + to have 2 <emphasis>separate independent</emphasis> PPP connections to + 2 separate sites at the <emphasis>same</emphasis> time. This is not + supported on most TA's, except for specific (usually expensive) models + that + have two serial ports. Do not confuse this with channel bonding, MPP, + etc.</para> + + <para>This can be a very useful feature if, for example, you + have an dedicated ISDN connection at your office and would + like to tap into it, but do not want to get another ISDN line + at work. A router at the office location can manage a + dedicated B channel connection (64 Kbps) to the Internet + and use the other B channel for a separate data connection. + The second B channel can be used for dial-in, dial-out or + dynamically bonding (MPP, etc.) with the first B channel for + more bandwidth.</para> + + <indexterm><primary>IPX/SPX</primary></indexterm> + <para>An Ethernet bridge will also allow you to transmit more than just + IP traffic. You can also send IPX/SPX or whatever other protocols you + use.</para> + </sect2> + </sect1> + + <sect1 xml:id="network-natd"> + <info><title>Network Address Translation</title> + <authorgroup> + <author><personname><firstname>Chern</firstname><surname>Lee</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + <sect2 xml:id="network-natoverview"> + <title>Overview</title> + <indexterm> + <primary><application>natd</application></primary> + </indexterm> + <para>FreeBSD's Network Address Translation daemon, commonly known as + &man.natd.8; is a daemon that accepts incoming raw IP packets, + changes the source to the local machine and re-injects these packets + back into the outgoing IP packet stream. &man.natd.8; does this by changing + the source IP address and port such that when data is received back, + it is able to determine the original location of the data and forward + it back to its original requester.</para> + <indexterm><primary>Internet connection sharing</primary></indexterm> + <indexterm><primary>NAT</primary></indexterm> + <para>The most common use of NAT is to perform what is commonly known as + Internet Connection Sharing.</para> + </sect2> + + <sect2 xml:id="network-natsetup"> + <title>Setup</title> + <para>Due to the diminishing IP space in IPv4, and the increased number + of users on high-speed consumer lines such as cable or DSL, people are + increasingly in need of an Internet Connection Sharing solution. The + ability to connect several computers online through one connection and + IP address makes &man.natd.8; a reasonable choice.</para> + + <para>Most commonly, a user has a machine connected to a cable or DSL + line with one IP address and wishes to use this one connected computer to + provide Internet access to several more over a LAN.</para> + + <para>To do this, the FreeBSD machine on the Internet must act as a + gateway. This gateway machine must have two NICs—one for connecting + to the Internet router, the other connecting to a LAN. All the + machines on the LAN are connected through a hub or switch.</para> + + <note> + <para>There are many ways to get a LAN connected to the Internet + through a &os; gateway. This example will only cover a + gateway with at least two NICs.</para> + </note> + + <mediaobject> + <imageobject> + <imagedata fileref="advanced-networking/natd"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> _______ __________ ________ + | | | | | | + | Hub |-----| Client B |-----| Router |----- Internet + |_______| |__________| |________| + | + ____|_____ +| | +| Client A | +|__________|</literallayout> + </textobject> + + <textobject> + <phrase>Network Layout</phrase> + </textobject> + </mediaobject> + + <para>A setup like this is commonly used to share an Internet + connection. One of the <acronym>LAN</acronym> machines is + connected to the Internet. The rest of the machines access + the Internet through that <quote>gateway</quote> + machine.</para> + </sect2> + + <sect2 xml:id="network-natdkernconfiguration"> + <title>Configuration</title> + + <indexterm> + <primary>kernel</primary> + <secondary>configuration</secondary> + </indexterm> + + <para>The following options must be in the kernel configuration + file:</para> + <programlisting>options IPFIREWALL +options IPDIVERT</programlisting> + + <para>Additionally, at choice, the following may also be suitable:</para> + <programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT +options IPFIREWALL_VERBOSE</programlisting> + + <para>The following must be in <filename>/etc/rc.conf</filename>:</para> + + <programlisting>gateway_enable="YES" <co xml:id="co-natd-gateway-enable"/> +firewall_enable="YES" <co xml:id="co-natd-firewall-enable"/> +firewall_type="OPEN" <co xml:id="co-natd-firewall-type"/> +natd_enable="YES" +natd_interface="<replaceable>fxp0</replaceable>" <co xml:id="co-natd-natd-interface"/> +natd_flags="" <co xml:id="co-natd-natd-flags"/></programlisting> + + <calloutlist> + <callout arearefs="co-natd-gateway-enable"> + <para>Sets up the machine to act as a gateway. Running + <command>sysctl net.inet.ip.forwarding=1</command> would + have the same effect.</para> + </callout> + + <callout arearefs="co-natd-firewall-enable"> + <para>Enables the firewall rules in + <filename>/etc/rc.firewall</filename> at boot.</para> + </callout> + + <callout arearefs="co-natd-firewall-type"> + <para>This specifies a predefined firewall ruleset that + allows anything in. See + <filename>/etc/rc.firewall</filename> for additional + types.</para> + </callout> + + <callout arearefs="co-natd-natd-interface"> + <para>Indicates which interface to forward packets through + (the interface connected to the Internet).</para> + </callout> + + <callout arearefs="co-natd-natd-flags"> + <para>Any additional configuration options passed to + &man.natd.8; on boot.</para> + </callout> + </calloutlist> + + <para>Having the previous options defined in + <filename>/etc/rc.conf</filename> would run + <command>natd -interface fxp0</command> at boot. This can also + be run manually.</para> + + <note> + <para>It is also possible to use a configuration file for + &man.natd.8; when there are too many options to pass. In this + case, the configuration file must be defined by adding the + following line to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>natd_flags="-f /etc/natd.conf"</programlisting> + + <para>The <filename>/etc/natd.conf</filename> file will + contain a list of configuration options, one per line. For + example the next section case would use the following + file:</para> + + <programlisting>redirect_port tcp 192.168.0.2:6667 6667 +redirect_port tcp 192.168.0.3:80 80</programlisting> + + <para>For more information about the configuration file, + consult the &man.natd.8; manual page about the + <option>-f</option> option.</para> + </note> + + <para>Each machine and interface behind the LAN should be + assigned IP address numbers in the private network space as + defined by <link xlink:href="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC 1918</link> + and have a default gateway of the <application>natd</application> machine's internal IP + address.</para> + + <para>For example, client <systemitem>A</systemitem> and + <systemitem>B</systemitem> behind the LAN have IP addresses of <systemitem class="ipaddress">192.168.0.2</systemitem> and <systemitem class="ipaddress">192.168.0.3</systemitem>, while the natd machine's + LAN interface has an IP address of <systemitem class="ipaddress">192.168.0.1</systemitem>. Client <systemitem>A</systemitem> + and <systemitem>B</systemitem>'s default gateway must be set to that + of the <application>natd</application> machine, <systemitem class="ipaddress">192.168.0.1</systemitem>. The <application>natd</application> machine's + external, or Internet interface does not require any special + modification for &man.natd.8; to work.</para> + </sect2> + + <sect2 xml:id="network-natdport-redirection"> + <title>Port Redirection</title> + + <para>The drawback with &man.natd.8; is that the LAN clients are not accessible + from the Internet. Clients on the LAN can make outgoing connections to + the world but cannot receive incoming ones. This presents a problem + if trying to run Internet services on one of the LAN client machines. + A simple way around this is to redirect selected Internet ports on the + <application>natd</application> machine to a LAN client. + </para> + + <para>For example, an IRC server runs on client <systemitem>A</systemitem>, and a web server runs + on client <systemitem>B</systemitem>. For this to work properly, connections received on ports + 6667 (IRC) and 80 (web) must be redirected to the respective machines. + </para> + + <para>The <option>-redirect_port</option> must be passed to + &man.natd.8; with the proper options. The syntax is as follows:</para> + <programlisting> -redirect_port proto targetIP:targetPORT[-targetPORT] + [aliasIP:]aliasPORT[-aliasPORT] + [remoteIP[:remotePORT[-remotePORT]]]</programlisting> + + <para>In the above example, the argument should be:</para> + + <programlisting> -redirect_port tcp 192.168.0.2:6667 6667 + -redirect_port tcp 192.168.0.3:80 80</programlisting> + + <para> + This will redirect the proper <emphasis>tcp</emphasis> ports to the + LAN client machines. + </para> + + <para>The <option>-redirect_port</option> argument can be used to indicate port + ranges over individual ports. For example, <replaceable>tcp + 192.168.0.2:2000-3000 2000-3000</replaceable> would redirect + all connections received on ports 2000 to 3000 to ports 2000 + to 3000 on client <systemitem>A</systemitem>.</para> + + <para>These options can be used when directly running + &man.natd.8;, placed within the + <literal>natd_flags=""</literal> option in + <filename>/etc/rc.conf</filename>, + or passed via a configuration file.</para> + + <para>For further configuration options, consult &man.natd.8;</para> + </sect2> + + <sect2 xml:id="network-natdaddress-redirection"> + <title>Address Redirection</title> + <indexterm><primary>address redirection</primary></indexterm> + <para>Address redirection is useful if several IP addresses are + available, yet they must be on one machine. With this, + &man.natd.8; can assign each LAN client its own external IP address. + &man.natd.8; then rewrites outgoing packets from the LAN clients + with the proper external IP address and redirects + all traffic incoming on that particular IP address back to + the specific LAN client. This is also known as static NAT. + For example, the IP addresses <systemitem class="ipaddress">128.1.1.1</systemitem>, + <systemitem class="ipaddress">128.1.1.2</systemitem>, and + <systemitem class="ipaddress">128.1.1.3</systemitem> belong to the <application>natd</application> gateway + machine. <systemitem class="ipaddress">128.1.1.1</systemitem> can be used + as the <application>natd</application> gateway machine's external IP address, while + <systemitem class="ipaddress">128.1.1.2</systemitem> and + <systemitem class="ipaddress">128.1.1.3</systemitem> are forwarded back to LAN + clients <systemitem>A</systemitem> and <systemitem>B</systemitem>.</para> + + <para>The <option>-redirect_address</option> syntax is as follows:</para> + + <programlisting>-redirect_address localIP publicIP</programlisting> + + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <tbody> + <row> + <entry>localIP</entry> + <entry>The internal IP address of the LAN client.</entry> + </row> + <row> + <entry>publicIP</entry> + <entry>The external IP address corresponding to the LAN client.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>In the example, this argument would read:</para> + + <programlisting>-redirect_address 192.168.0.2 128.1.1.2 +-redirect_address 192.168.0.3 128.1.1.3</programlisting> + + <para>Like <option>-redirect_port</option>, these arguments are also placed within + the <literal>natd_flags=""</literal> option of <filename>/etc/rc.conf</filename>, or passed via a configuration file. With address + redirection, there is no need for port redirection since all data + received on a particular IP address is redirected.</para> + + <para>The external IP addresses on the <application>natd</application> machine must be active and aliased + to the external interface. Look at &man.rc.conf.5; to do so.</para> + + </sect2> + </sect1> + + <sect1 xml:id="network-plip"> + <title>Parallel Line IP (PLIP)</title> + + <indexterm><primary>PLIP</primary></indexterm> + <indexterm> + <primary>Parallel Line IP</primary> + <see>PLIP</see> + </indexterm> + + <para>PLIP lets us run TCP/IP between parallel ports. It is + useful on machines without network cards, or to install on + laptops. In this section, we will discuss:</para> + + <itemizedlist> + <listitem> + <para>Creating a parallel (laplink) cable.</para> + </listitem> + + <listitem> + <para>Connecting two computers with PLIP.</para> + </listitem> + </itemizedlist> + + <sect2 xml:id="network-create-parallel-cable"> + <title>Creating a Parallel Cable</title> + + <para>You can purchase a parallel cable at most computer supply + stores. If you cannot do that, or you just want to know how + it is done, the following table shows how to make one out of a normal parallel + printer cable.</para> + + <table frame="none"> + <title>Wiring a Parallel Cable for Networking</title> + + <tgroup cols="5"> + <thead> + <row> + <entry>A-name</entry> + + <entry>A-End</entry> + + <entry>B-End</entry> + + <entry>Descr.</entry> + + <entry>Post/Bit</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literallayout>DATA0 +-ERROR</literallayout></entry> + + <entry><literallayout>2 +15</literallayout></entry> + + <entry><literallayout>15 +2</literallayout></entry> + + <entry>Data</entry> + + <entry><literallayout>0/0x01 +1/0x08</literallayout></entry> + </row> + + <row> + <entry><literallayout>DATA1 ++SLCT</literallayout></entry> + + <entry><literallayout>3 +13</literallayout></entry> + + <entry><literallayout>13 +3</literallayout></entry> + + <entry>Data</entry> + + <entry><literallayout>0/0x02 +1/0x10</literallayout></entry> + </row> + + <row> + <entry><literallayout>DATA2 ++PE</literallayout></entry> + + <entry><literallayout>4 +12</literallayout></entry> + + <entry><literallayout>12 +4</literallayout></entry> + + <entry>Data</entry> + + <entry><literallayout>0/0x04 +1/0x20</literallayout></entry> + </row> + + <row> + <entry><literallayout>DATA3 +-ACK</literallayout></entry> + + <entry><literallayout>5 +10</literallayout></entry> + + <entry><literallayout>10 +5</literallayout></entry> + + <entry>Strobe</entry> + + <entry><literallayout>0/0x08 +1/0x40</literallayout></entry> + </row> + + <row> + <entry><literallayout>DATA4 +BUSY</literallayout></entry> + + <entry><literallayout>6 +11</literallayout></entry> + + <entry><literallayout>11 +6</literallayout></entry> + + <entry>Data</entry> + + <entry><literallayout>0/0x10 +1/0x80</literallayout></entry> + </row> + + <row> + <entry>GND</entry> + + <entry>18-25</entry> + + <entry>18-25</entry> + + <entry>GND</entry> + + <entry>-</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2 xml:id="network-plip-setup"> + <title>Setting Up PLIP</title> + + <para>First, you have to get a laplink cable. + Then, confirm that both computers have a kernel with &man.lpt.4; driver + support:</para> + + <screen>&prompt.root; <userinput>grep lp /var/run/dmesg.boot</userinput> +lpt0: <Printer> on ppbus0 +lpt0: Interrupt-driven port</screen> + + <para>The parallel port must be an interrupt driven port, + you should have lines similar to the + following in your in the + <filename>/boot/device.hints</filename> file:</para> + + <programlisting>hint.ppc.0.at="isa" +hint.ppc.0.irq="7"</programlisting> + + <para>Then check if the kernel configuration file has a + <literal>device plip</literal> line or if the + <filename>plip.ko</filename> kernel module is loaded. In both + cases the parallel networking interface should appear when you + use the &man.ifconfig.8; command to display it:</para> + + <screen>&prompt.root; <userinput>ifconfig plip0</userinput> +plip0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500</screen> + + <para>Plug the laplink cable into the parallel interface on + both computers.</para> + + <para>Configure the network interface parameters on both + sites as <systemitem class="username">root</systemitem>. For example, if you want to connect + the host <systemitem>host1</systemitem> with another machine <systemitem>host2</systemitem>:</para> + + <programlisting> host1 <-----> host2 +IP Address 10.0.0.1 10.0.0.2</programlisting> + + <para>Configure the interface on <systemitem>host1</systemitem> by doing:</para> + + <screen>&prompt.root; <userinput>ifconfig plip0 10.0.0.1 10.0.0.2</userinput></screen> + + <para>Configure the interface on <systemitem>host2</systemitem> by doing:</para> + + <screen>&prompt.root; <userinput>ifconfig plip0 10.0.0.2 10.0.0.1</userinput></screen> + + + <para>You now should have a working connection. Please read the + manual pages &man.lp.4; and &man.lpt.4; for more details.</para> + + <para>You should also add both hosts to + <filename>/etc/hosts</filename>:</para> + + <programlisting>127.0.0.1 localhost.my.domain localhost +10.0.0.1 host1.my.domain host1 +10.0.0.2 host2.my.domain</programlisting> + + <para>To confirm the connection works, go to each host and ping + the other. For example, on <systemitem>host1</systemitem>:</para> + + <screen>&prompt.root; <userinput>ifconfig plip0</userinput> +plip0: flags=8851<UP,POINTOPOINT,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 10.0.0.1 --> 10.0.0.2 netmask 0xff000000 +&prompt.root; <userinput>netstat -r</userinput> +Routing tables + +Internet: +Destination Gateway Flags Refs Use Netif Expire +host2 host1 UH 0 0 plip0 +&prompt.root; <userinput>ping -c 4 host2</userinput> +PING host2 (10.0.0.2): 56 data bytes +64 bytes from 10.0.0.2: icmp_seq=0 ttl=255 time=2.774 ms +64 bytes from 10.0.0.2: icmp_seq=1 ttl=255 time=2.530 ms +64 bytes from 10.0.0.2: icmp_seq=2 ttl=255 time=2.556 ms +64 bytes from 10.0.0.2: icmp_seq=3 ttl=255 time=2.714 ms + +--- host2 ping statistics --- +4 packets transmitted, 4 packets received, 0% packet loss +round-trip min/avg/max/stddev = 2.530/2.643/2.774/0.103 ms</screen> + + </sect2> + </sect1> + + <sect1 xml:id="network-ipv6"> + <info><title>IPv6</title> + <authorgroup> + <author><personname><firstname>Aaron</firstname><surname>Kaplan</surname></personname><contrib>Originally Written by </contrib></author> + </authorgroup> + <authorgroup> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Restructured and Added by </contrib></author> + </authorgroup> + <authorgroup> + <author><personname><firstname>Brad</firstname><surname>Davis</surname></personname><contrib>Extended by </contrib></author> + </authorgroup> + + </info> + + + <para>IPv6 (also known as IPng <quote>IP next generation</quote>) is + the new version of the well known IP protocol (also known as + <acronym>IPv4</acronym>). Like the other current *BSD systems, + FreeBSD includes the KAME IPv6 reference implementation. + So your FreeBSD system comes with all you will need to experiment with IPv6. + This section focuses on getting IPv6 configured and running.</para> + + <para>In the early 1990s, people became aware of the rapidly + diminishing address space of IPv4. Given the expansion rate of the + Internet there were two major concerns:</para> + + <itemizedlist> + <listitem> + <para>Running out of addresses. Today this is not so much of a concern + anymore since RFC1918 private address space + (<systemitem class="ipaddress">10.0.0.0/8</systemitem>, + <systemitem class="ipaddress">172.16.0.0/12</systemitem>, and + <systemitem class="ipaddress">192.168.0.0/16</systemitem>) + and Network Address Translation (<acronym>NAT</acronym>) are + being employed.</para> + </listitem> + + <listitem> + <para>Router table entries were getting too large. This is + still a concern today.</para> + </listitem> + </itemizedlist> + + <para>IPv6 deals with these and many other issues:</para> + + <itemizedlist> + <listitem> + <para>128 bit address space. In other words theoretically there are + 340,282,366,920,938,463,463,374,607,431,768,211,456 addresses + available. This means there are approximately + 6.67 * 10^27 IPv6 addresses per square meter on our planet.</para> + </listitem> + + <listitem> + <para>Routers will only store network aggregation addresses in their routing + tables thus reducing the average space of a routing table to 8192 + entries.</para> + </listitem> + </itemizedlist> + + <para>There are also lots of other useful features of IPv6 such as:</para> + + <itemizedlist> + <listitem> + <para>Address autoconfiguration (<link xlink:href="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</link>)</para> + </listitem> + + <listitem> + <para>Anycast addresses (<quote>one-out-of many</quote>)</para> + </listitem> + + <listitem> + <para>Mandatory multicast addresses</para> + </listitem> + + <listitem> + <para>IPsec (IP security)</para> + </listitem> + + <listitem> + <para>Simplified header structure</para> + </listitem> + + <listitem> + <para>Mobile <acronym>IP</acronym></para> + </listitem> + + <listitem> + <para>IPv6-to-IPv4 transition mechanisms</para> + </listitem> + </itemizedlist> + + + <para>For more information see:</para> + + <itemizedlist> + <listitem> + <para>IPv6 overview at <link xlink:href="http://playground.sun.com/pub/ipng/html/ipng-main.html">playground.sun.com</link></para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.kame.net">KAME.net</link></para> + </listitem> + </itemizedlist> + + <sect2> + <title>Background on IPv6 Addresses</title> + <para>There are different types of IPv6 addresses: Unicast, Anycast and + Multicast.</para> + + <para>Unicast addresses are the well known addresses. A packet sent + to a unicast address arrives exactly at the interface belonging to + the address.</para> + + <para>Anycast addresses are syntactically indistinguishable from unicast + addresses but they address a group of interfaces. The packet destined for + an anycast address will arrive at the nearest (in router metric) + interface. Anycast addresses may only be used by routers.</para> + + <para>Multicast addresses identify a group of interfaces. A packet destined + for a multicast address will arrive at all interfaces belonging to the + multicast group.</para> + + <note><para>The IPv4 broadcast address (usually <systemitem class="ipaddress">xxx.xxx.xxx.255</systemitem>) is expressed + by multicast addresses in IPv6.</para></note> + + <table frame="none"> + <title>Reserved IPv6 addresses</title> + + <tgroup cols="4"> + <thead> + <row> + <entry>IPv6 address</entry> + <entry>Prefixlength (Bits)</entry> + <entry>Description</entry> + <entry>Notes</entry> + </row> + </thead> + + <tbody> + <row> + <entry><systemitem>::</systemitem></entry> + <entry>128 bits</entry> + <entry>unspecified</entry> + <entry>cf. <systemitem class="ipaddress">0.0.0.0</systemitem> in + IPv4</entry> + </row> + + <row> + <entry><systemitem>::1</systemitem></entry> + <entry>128 bits</entry> + <entry>loopback address</entry> + <entry>cf. <systemitem class="ipaddress">127.0.0.1</systemitem> in + IPv4</entry> + </row> + + <row> + <entry><systemitem>::00:xx:xx:xx:xx</systemitem></entry> + <entry>96 bits</entry> + <entry>embedded IPv4</entry> + <entry>The lower 32 bits are the IPv4 address. Also + called <quote>IPv4 compatible IPv6 + address</quote></entry> + </row> + + <row> + <entry><systemitem>::ff:xx:xx:xx:xx</systemitem></entry> + <entry>96 bits</entry> + <entry>IPv4 mapped IPv6 address</entry> + <entry>The lower 32 bits are the IPv4 address. + For hosts which do not support IPv6.</entry> + </row> + + <row> + <entry><systemitem>fe80::</systemitem> - <systemitem>feb::</systemitem></entry> + <entry>10 bits</entry> + <entry>link-local</entry> + <entry>cf. loopback address in IPv4</entry> + </row> + + <row> + <entry><systemitem>fec0::</systemitem> - <systemitem>fef::</systemitem></entry> + <entry>10 bits</entry> + <entry>site-local</entry> + <entry> </entry> + </row> + + <row> + <entry><systemitem>ff::</systemitem></entry> + <entry>8 bits</entry> + <entry>multicast</entry> + <entry> </entry> + </row> + + <row> + <entry><systemitem>001</systemitem> (base + 2)</entry> + <entry>3 bits</entry> + <entry>global unicast</entry> + <entry>All global unicast addresses are assigned from + this pool. The first 3 bits are + <quote>001</quote>.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + + <sect2> + <title>Reading IPv6 Addresses</title> + <para>The canonical form is represented as: <systemitem>x:x:x:x:x:x:x:x</systemitem>, each + <quote>x</quote> being a 16 Bit hex value. For example + <systemitem>FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</systemitem></para> + + <para>Often an address will have long substrings of all zeros + therefore one such substring per address can be abbreviated by <quote>::</quote>. + Also up to three leading <quote>0</quote>s per hexquad can be omitted. + For example <systemitem>fe80::1</systemitem> + corresponds to the canonical form + <systemitem>fe80:0000:0000:0000:0000:0000:0000:0001</systemitem>.</para> + + <para>A third form is to write the last 32 Bit part in the + well known (decimal) IPv4 style with dots <quote>.</quote> + as separators. For example + <systemitem>2002::10.0.0.1</systemitem> + corresponds to the (hexadecimal) canonical representation + <systemitem>2002:0000:0000:0000:0000:0000:0a00:0001</systemitem> + which in turn is equivalent to + writing <systemitem>2002::a00:1</systemitem>.</para> + + <para>By now the reader should be able to understand the following:</para> + + <screen>&prompt.root; <userinput>ifconfig</userinput></screen> + + <programlisting>rl0: flags=8943<UP,BROADCAST,RUNNING,PROMISC,SIMPLEX,MULTICAST> mtu 1500 + inet 10.0.0.10 netmask 0xffffff00 broadcast 10.0.0.255 + inet6 fe80::200:21ff:fe03:8e1%rl0 prefixlen 64 scopeid 0x1 + ether 00:00:21:03:08:e1 + media: Ethernet autoselect (100baseTX ) + status: active</programlisting> + + <para><systemitem>fe80::200:21ff:fe03:8e1%rl0</systemitem> + is an auto configured link-local address. It is generated from the MAC + address as part of the auto configuration.</para> + + <para>For further information on the structure of IPv6 addresses + see <link xlink:href="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</link>.</para> + </sect2> + + <sect2> + <title>Getting Connected</title> + + <para>Currently there are four ways to connect to other IPv6 hosts and networks:</para> + + <itemizedlist> + <listitem> + <para>Getting an IPv6 network from your upstream provider. Talk to your + Internet provider for instructions.</para> + </listitem> + + <listitem> + <para>Tunnel via 6-to-4 (<link xlink:href="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</link>)</para> + </listitem> + + <listitem> + <para>Use the <package>net/freenet6</package> port if you are on a dial-up connection.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>DNS in the IPv6 World</title> + + <para>There used to be two types of DNS records for IPv6. The IETF + has declared A6 records obsolete. AAAA records are the standard + now.</para> + + <para>Using AAAA records is straightforward. Assign your hostname to the new + IPv6 address you just received by adding:</para> + + <programlisting>MYHOSTNAME AAAA MYIPv6ADDR</programlisting> + + <para>To your primary zone DNS file. In case you do not serve your own + <acronym>DNS</acronym> zones ask your <acronym>DNS</acronym> provider. + Current versions of <application>bind</application> (version 8.3 and 9) + and <package>dns/djbdns</package> (with the IPv6 patch) + support AAAA records.</para> + </sect2> + + <sect2> + <title>Applying the needed changes to <filename>/etc/rc.conf</filename></title> + + <sect3> + <title>IPv6 Client Settings</title> + + <para>These settings will help you configure a machine that will be on + your LAN and act as a client, not a router. To have &man.rtsol.8; + autoconfigure your interface on boot all you need to add is:</para> + + <programlisting>ipv6_enable="YES"</programlisting> + + <para>To statically assign an IP address such as <systemitem> + 2001:471:1f11:251:290:27ff:fee0:2093</systemitem>, to your + <filename>fxp0</filename> interface, add:</para> + + <programlisting>ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093"</programlisting> + + <para>To assign a default router of + <systemitem>2001:471:1f11:251::1</systemitem> + add the following to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ipv6_defaultrouter="2001:471:1f11:251::1"</programlisting> + + </sect3> + + <sect3> + <title>IPv6 Router/Gateway Settings</title> + + <para>This will help you take the directions that your tunnel provider has + given you and convert it into settings that will persist through reboots. + To restore your tunnel on startup use something like the following in + <filename>/etc/rc.conf</filename>:</para> + + <para>List the Generic Tunneling interfaces that will be configured, for + example <filename>gif0</filename>:</para> + + <programlisting>gif_interfaces="gif0"</programlisting> + + <para>To configure the interface with a local endpoint of + <replaceable>MY_IPv4_ADDR</replaceable> to a remote endpoint of + <replaceable>REMOTE_IPv4_ADDR</replaceable>:</para> + + <programlisting>gifconfig_gif0="<replaceable>MY_IPv4_ADDR REMOTE_IPv4_ADDR</replaceable>"</programlisting> + + <para>To apply the IPv6 address you have been assigned for use as your + IPv6 tunnel endpoint, add:</para> + + <programlisting>ipv6_ifconfig_gif0="<replaceable>MY_ASSIGNED_IPv6_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting> + + <para>Then all you have to do is set the default route for IPv6. This is + the other side of the IPv6 tunnel:</para> + + <programlisting>ipv6_defaultrouter="<replaceable>MY_IPv6_REMOTE_TUNNEL_ENDPOINT_ADDR</replaceable>"</programlisting> + + </sect3> + + <sect3> + <title>IPv6 Tunnel Settings</title> + + <para>If the server is to route IPv6 between the rest of your network + and the world, the following <filename>/etc/rc.conf</filename> + setting will also be needed:</para> + + <programlisting>ipv6_gateway_enable="YES"</programlisting> + + </sect3> + </sect2> + + <sect2> + <title>Router Advertisement and Host Auto Configuration</title> + + <para>This section will help you setup &man.rtadvd.8; to advertise the + IPv6 default route.</para> + + <para>To enable &man.rtadvd.8; you will need the following in your + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>rtadvd_enable="YES"</programlisting> + + <para>It is important that you specify the interface on which to do + IPv6 router solicitation. For example to tell &man.rtadvd.8; to use + <filename>fxp0</filename>:</para> + + <programlisting>rtadvd_interfaces="fxp0"</programlisting> + + <para>Now we must create the configuration file, + <filename>/etc/rtadvd.conf</filename>. Here is an example:</para> + + <programlisting>fxp0:\ + :addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether:</programlisting> + + <para>Replace <filename>fxp0</filename> with the interface you + are going to be using.</para> + + <para>Next, replace <systemitem>2001:471:1f11:246::</systemitem> + with the prefix of your allocation.</para> + + <para>If you are dedicated a <systemitem class="netmask">/64</systemitem> subnet + you will not need to change anything else. Otherwise, you will need to + change the <literal>prefixlen#</literal> to the correct value.</para> + + </sect2> + </sect1> + + <sect1 xml:id="network-atm"> + <info><title>Asynchronous Transfer Mode (ATM)</title> + <authorgroup> + <author><personname><firstname>Harti</firstname><surname>Brandt</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + + <sect2> + <title>Configuring classical IP over ATM (PVCs)</title> + + <para>Classical IP over ATM (<acronym>CLIP</acronym>) is the + simplest method to use Asynchronous Transfer Mode (ATM) + with IP. It can be used with + switched connections (SVCs) and with permanent connections + (PVCs). This section describes how to set up a network based + on PVCs.</para> + + <sect3> + <title>Fully meshed configurations</title> + + <para>The first method to set up a <acronym>CLIP</acronym> with + PVCs is to connect each machine to each other machine in the + network via a dedicated PVC. While this is simple to + configure it tends to become impractical for a larger number + of machines. The example supposes that we have four + machines in the network, each connected to the <acronym role="Asynchronous Transfer Mode">ATM</acronym> network + with an <acronym role="Asynchronous Transfer Mode">ATM</acronym> adapter card. The first step is the planning of + the IP addresses and the <acronym role="Asynchronous Transfer Mode">ATM</acronym> connections between the + machines. We use the following:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="1*"/> + <thead> + <row> + <entry>Host</entry> + <entry>IP Address</entry> + </row> + </thead> + + <tbody> + <row> + <entry><systemitem>hostA</systemitem></entry> + <entry><systemitem class="ipaddress">192.168.173.1</systemitem></entry> + </row> + + <row> + <entry><systemitem>hostB</systemitem></entry> + <entry><systemitem class="ipaddress">192.168.173.2</systemitem></entry> + </row> + + <row> + <entry><systemitem>hostC</systemitem></entry> + <entry><systemitem class="ipaddress">192.168.173.3</systemitem></entry> + </row> + + <row> + <entry><systemitem>hostD</systemitem></entry> + <entry><systemitem class="ipaddress">192.168.173.4</systemitem></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>To build a fully meshed net we need one ATM connection + between each pair of machines:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="1*"/> + <thead> + <row> + <entry>Machines</entry> + <entry>VPI.VCI couple</entry> + </row> + </thead> + + <tbody> + <row> + <entry><systemitem>hostA</systemitem> - <systemitem>hostB</systemitem></entry> + <entry>0.100</entry> + </row> + + <row> + <entry><systemitem>hostA</systemitem> - <systemitem>hostC</systemitem></entry> + <entry>0.101</entry> + </row> + + <row> + <entry><systemitem>hostA</systemitem> - <systemitem>hostD</systemitem></entry> + <entry>0.102</entry> + </row> + + <row> + <entry><systemitem>hostB</systemitem> - <systemitem>hostC</systemitem></entry> + <entry>0.103</entry> + </row> + + <row> + <entry><systemitem>hostB</systemitem> - <systemitem>hostD</systemitem></entry> + <entry>0.104</entry> + </row> + + <row> + <entry><systemitem>hostC</systemitem> - <systemitem>hostD</systemitem></entry> + <entry>0.105</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>The VPI and VCI values at each end of the connection may + of course differ, but for simplicity we assume that they are + the same. Next we need to configure the ATM interfaces on + each host:</para> + + <screen>hostA&prompt.root; <userinput>ifconfig hatm0 192.168.173.1 up</userinput> +hostB&prompt.root; <userinput>ifconfig hatm0 192.168.173.2 up</userinput> +hostC&prompt.root; <userinput>ifconfig hatm0 192.168.173.3 up</userinput> +hostD&prompt.root; <userinput>ifconfig hatm0 192.168.173.4 up</userinput></screen> + + <para>assuming that the ATM interface is + <filename>hatm0</filename> on all hosts. Now the PVCs + need to be configured on <systemitem>hostA</systemitem> (we assume that + they are already configured on the ATM switches, you need to + consult the manual for the switch on how to do this).</para> + + <screen>hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 100 llc/snap ubr</userinput> +hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 101 llc/snap ubr</userinput> +hostA&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 102 llc/snap ubr</userinput> + +hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 100 llc/snap ubr</userinput> +hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 103 llc/snap ubr</userinput> +hostB&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 104 llc/snap ubr</userinput> + +hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 101 llc/snap ubr</userinput> +hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 103 llc/snap ubr</userinput> +hostC&prompt.root; <userinput>atmconfig natm add 192.168.173.4 hatm0 0 105 llc/snap ubr</userinput> + +hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.1 hatm0 0 102 llc/snap ubr</userinput> +hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.2 hatm0 0 104 llc/snap ubr</userinput> +hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 105 llc/snap ubr</userinput></screen> + + <para>Of course other traffic contracts than UBR can be used + given the ATM adapter supports those. In this case the name + of the traffic contract is followed by the parameters of the + traffic. Help for the &man.atmconfig.8; tool can be + obtained with:</para> + + <screen>&prompt.root; <userinput>atmconfig help natm add</userinput></screen> + + <para>or in the &man.atmconfig.8; manual page.</para> + + <para>The same configuration can also be done via + <filename>/etc/rc.conf</filename>. + For <systemitem>hostA</systemitem> this would look like:</para> + +<programlisting>network_interfaces="lo0 hatm0" +ifconfig_hatm0="inet 192.168.173.1 up" +natm_static_routes="hostB hostC hostD" +route_hostB="192.168.173.2 hatm0 0 100 llc/snap ubr" +route_hostC="192.168.173.3 hatm0 0 101 llc/snap ubr" +route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting> + + <para>The current state of all <acronym>CLIP</acronym> routes + can be obtained with:</para> + + <screen>hostA&prompt.root; <userinput>atmconfig natm show</userinput></screen> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="carp"> + <info><title>Common Access Redundancy Protocol (CARP)</title> + <authorgroup> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + <indexterm><primary>CARP</primary></indexterm> + <indexterm><primary>Common Access Redundancy Protocol</primary></indexterm> + + <para>The Common Access Redundancy Protocol, or + <acronym>CARP</acronym> allows multiple hosts to share the same + <acronym>IP</acronym> address. In some configurations, this may + be used for availability or load balancing. Hosts may use separate + <acronym>IP</acronym> addresses as well, as in the example provided + here.</para> + + <para>To enable support for <acronym>CARP</acronym>, the &os; + kernel must be rebuilt with the following option:</para> + + <programlisting>device carp</programlisting> + + <para><acronym>CARP</acronym> functionality should now be available + and may be tuned via several <command>sysctl</command> + <acronym>OID</acronym>s. Devices themselves may be loaded via + the <command>ifconfig</command> command:</para> + + <screen>&prompt.root; <userinput>ifconfig carp0 create</userinput></screen> + + <para>In a real environment, these interfaces will need unique + identification numbers known as a <acronym>VHID</acronym>. This + <acronym>VHID</acronym> or Virtual Host Identification will be + used to distinguish the host on the network.</para> + + <sect2> + <title>Using CARP For Server Availability (CARP)</title> + + <para>One use of <acronym>CARP</acronym>, as noted above, is for + server availability. This example will provide failover support + for three hosts, all with unique <acronym>IP</acronym> + addresses and providing the same web content. These machines will + act in conjunction with a Round Robin <acronym>DNS</acronym> + configuration. The failover machine will have two additional + <acronym>CARP</acronym> interfaces, one for each of the content + server's <acronym>IP</acronym>s. When a failure occurs, the + failover server should pick up the failed machine's + <acronym>IP</acronym> address. This means the failure should + go completely unnoticed to the user. The failover server + requires identical content and services as the other content + servers it is expected to pick up load for.</para> + + <para>The two machines should be configured identically other + than their issued hostnames and <acronym>VHID</acronym>s. + This example calls these machines + <systemitem>hosta.example.org</systemitem> and + <systemitem>hostb.example.org</systemitem> respectively. First, the + required lines for a <acronym>CARP</acronym> configuration have + to be added to <filename>rc.conf</filename>. For + <systemitem>hosta.example.org</systemitem>, the + <filename>rc.conf</filename> file should contain the following + lines:</para> + + <programlisting>hostname="hosta.example.org" +ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0" +cloned_interfaces="carp0" +ifconfig_carp0="vhid 1 pass testpast 192.168.1.50/24"</programlisting> + + <para>On <systemitem>hostb.example.org</systemitem> the following lines + should be in <filename>rc.conf</filename>:</para> + + <programlisting>hostname="hostb.example.org" +ifconfig_fxp0="inet 192.168.1.4 netmask 255.255.255.0" +cloned_interfaces="carp0" +ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24"</programlisting> + + <note> + <para>It is very important that the passwords, specified by the + <option>pass</option> option to <command>ifconfig</command>, + are identical. The <filename>carp</filename> devices will + only listen to and accept advertisements from machines with the + correct password. The <acronym>VHID</acronym> must also be + different for each machine.</para> + </note> + + <para>The third machine, + <systemitem>provider.example.org</systemitem>, should be prepared so that + it may handle failover from either host. This machine will require + two <filename>carp</filename> devices, one to handle each + host. The appropriate <filename>rc.conf</filename> + configuration lines will be similar to the following:</para> + + <programlisting>hostname="provider.example.org" +ifconfig_fxp0="inet 192.168.1.5 netmask 255.255.255.0" +cloned_interfaces="carp0 carp1" +ifconfig_carp0="vhid 1 advskew 100 pass testpass 192.168.1.50/24" +ifconfig_carp1="vhid 2 advskew 100 pass testpass 192.168.1.51/24"</programlisting> + + <para>Having the two <filename>carp</filename> devices will + allow <systemitem>provider.example.org</systemitem> to notice and pick + up the <acronym>IP</acronym> address of either machine should + it stop responding.</para> + + <note> + <para>The default &os; kernel <emphasis>may</emphasis> have + preemption enabled. If so, + <systemitem>provider.example.org</systemitem> may not relinquish the + <acronym>IP</acronym> address back to the original content + server. In this case, an administrator may + <quote>nudge</quote> the interface. The following command + should be issued on + <systemitem>provider.example.org</systemitem>:</para> + + <screen>&prompt.root; <userinput>ifconfig carp0 down && ifconfig carp0 up</userinput></screen> + + <para>This should be done on the <filename>carp</filename> + interface which corresponds to the correct host.</para> + </note> + + <para>At this point, <acronym>CARP</acronym> should be completely + enabled and available for testing. For testing, either networking has + to be restarted or the machines need to be rebooted.</para> + + <para>More information is always available in the &man.carp.4; + manual page.</para> + </sect2> + </sect1> +</chapter> diff --git a/zh_TW.UTF-8/books/handbook/audit/Makefile b/zh_TW.UTF-8/books/handbook/audit/Makefile new file mode 100644 index 0000000000..2d71ed91f5 --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/audit/Makefile @@ -0,0 +1,16 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# Original revision: 1.1 +# + +CHAPTERS= audit/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/zh_TW.UTF-8/books/handbook/audit/chapter.xml b/zh_TW.UTF-8/books/handbook/audit/chapter.xml new file mode 100644 index 0000000000..5e899c5b88 --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/audit/chapter.xml @@ -0,0 +1,567 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + The FreeBSD Documentation Project + $FreeBSD$ + Original revision: 1.13 +--> +<!-- Need more documentation on praudit, auditreduce, etc. Plus more info +on the triggers from the kernel (log rotation, out of space, etc). +And the /dev/audit special file if we choose to support that. Could use +some coverage of integrating MAC with Event auditing and perhaps discussion +on how some companies or organizations handle auditing and auditing +requirements. --> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="audit"> + <info><title>Security Event Auditing</title> + <authorgroup> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> + </authorgroup> + </info> + + + + <sect1 xml:id="audit-synopsis"> + <title>Synopsis</title> + + <indexterm><primary>AUDIT</primary></indexterm> + <indexterm> + <primary>Security Event Auditing</primary> + <see>MAC</see> + </indexterm> + + <para>The &os; 7-CURRENT development branch includes + support for Event Auditing based on the &posix;.1e draft and + Sun's published <acronym>BSM</acronym> API and file format. + Event auditing permits the selective logging of security-relevant + system events for the purposes of post-mortem analysis, system + monitoring, and intrusion detection. After some settling time in + &os; 7-CURRENT, this support will be merged to &os; 6-STABLE + and appear in subsequent releases.</para> + + <warning> + <para>The audit facility in FreeBSD is considered experimental, and + production deployment should occur only after careful consideration + of the risks of deploying experimental software.</para> + </warning> + + <para>This chapter will focus mainly on the installation and + configuration of Event Auditing. Explanation of audit policies, + and an example configuration will be provided for the + convenience of the reader.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>What Event Auditing is and how it works.</para> + </listitem> + + <listitem> + <para>How to configure Event Auditing on &os; for users + and processes.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand &unix; and &os; basics + (<xref linkend="basics"/>).</para> + </listitem> + + <listitem> + <para>Be familiar with the basics of kernel + configuration/compilation + (<xref linkend="kernelconfig"/>).</para> + </listitem> + + <listitem> + <para>Have some familiarity with security and how it + pertains to &os; (<xref linkend="security"/>).</para> + </listitem> + </itemizedlist> + + <warning> + <para>Event auditing can generate a great deal of log file + data, exceeding gigabytes a week in some configurations. An + administrator should read this chapter in its entirety to avoid + possible self-inflicted <acronym>DoS</acronym> attacks due to + improper configuration.</para> + </warning> + + <para>The implementation of Event Auditing in &os; is similar to + that of the &sun; Basic Security Module, or <acronym>BSM</acronym> + library. Thus, the configuration is almost completely + interchangeable with &solaris; and Mac OS X/Darwin operating + systems.</para> + </sect1> + + <sect1 xml:id="audit-inline-glossary"> + <title>Key Terms - Words to Know</title> + + <para>Before reading this chapter, a few key terms must be + explained. This is intended to clear up any confusion that + may occur and to avoid the abrupt introduction of new terms + and information.</para> + + <itemizedlist> + <listitem> + <para><emphasis>event</emphasis>: An auditable event is + an event that can be logged using the audit subsystem. The + administrator can configure which events will be audited. + Examples of security-relevant events include the creation of + a file, the building of a network connection, or the logging + in of a user. Events are either <quote>attributable</quote>, + meaning that they can be traced back to a user + authentication, or <quote>non-attributable</quote>. Examples + of non-attributable events are any events that occur before + authentication has succeeded in the login process, such as + failed authentication attempts.</para> + </listitem> + + <listitem> + <para><emphasis>class</emphasis>: Events may be assigned to + one or more classes, usually based on the general category + of the events, such as <quote>file creation</quote>, + <quote>file access</quote>, or <quote>network</quote>. Login + and logout events are assigned to the <literal>lo</literal> + class. The use of classes allows the administrator to + specify high level auditing rules without having to specify + whether each individual auditable operation will be logged.</para> + </listitem> + + <listitem> + <para><emphasis>record</emphasis>: A record is a log entry + describing a security event. Records typically have a + record event type, information on the subject (user) associated + with the event, time information, information on any objects, + such as files, and information on whether the event corresponded + to a successful operation.</para> + </listitem> + + <listitem> + <para><emphasis>trail</emphasis>: An audit trail, or log file, + consists of a series of audit records describing security + events. Typically, trails are in roughly chronological + order with respect to the time events completed. Only + authorized processes are allowed to commit records to the + audit trail.</para> + </listitem> + + <listitem> + <para><emphasis>prefix</emphasis>: A prefix is considered to + be the configuration element used to toggle auditing for + success and failed events.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="audit-install"> + <title>Installing Audit Support</title> + + <para>Support for Event Auditing is installed with + the normal <buildtarget>installworld</buildtarget> process. An + administrator may confirm this by viewing the contents + of <filename>/etc/security</filename>. Files + beginning with the word <emphasis>audit</emphasis> should be present. + For example, <filename>audit_event</filename>.</para> + + <para>In-kernel support for the framework must also exist. This + may be done by adding the following lines to the local kernel + configuration file:</para> + + <programlisting>options AUDIT</programlisting> + + <para>Rebuild and reinstall + the kernel via the normal process explained in + <xref linkend="kernelconfig"/>.</para> + + <para>Once completed, enable the audit daemon by adding the + following line to &man.rc.conf.5;:</para> + + <programlisting>auditd_enable="YES"</programlisting> + + <para>Functionality not provided by the default may be added + here with the <option>auditd_flags</option> option.</para> + </sect1> + + <sect1 xml:id="audit-config"> + <title>Audit Configuration</title> + + <para>All configuration files for security audit are found in + <filename>/etc/security</filename>. The following + files must be present before the audit daemon is started:</para> + + <itemizedlist> + <listitem> + <para><filename>audit_class</filename> - Contains the + definitions of the audit classes.</para> + </listitem> + + <listitem> + <para><filename>audit_control</filename> - Controls aspects + of the audit subsystem, such as default audit classes, + minimum disk space to leave on the audit log volume, + etc.</para> + </listitem> + + <listitem> + <para><filename>audit_event</filename> - Defines the kernel + audit events. These map, mostly, to system calls.</para> + </listitem> + + <listitem> + <para><filename>audit_user</filename> - The events to audit + for individual users. Users not appearing here will be + subject to the default configuration in the control + configuration file.</para> + </listitem> + + <listitem> + <para><filename>audit_warn</filename> - A shell script + used by auditd to generate warning messages in + exceptional situations, such as when space for audit + records is running low.</para> + </listitem> + </itemizedlist> + + <sect2> + <title>Audit File Syntax</title> + + <para>The configuration file syntax is rather arcane, albeit easy + to work with. One thing an administrator must be leery about + is overriding system defaults. This could create potential + openings for audit data to not be collected properly.</para> + + <para>The audit subsystem will accept both the short name and + long name with regards to configuration syntax. A syntax + map has been included below.</para> + + <para>The following list contains all supported audit + classes:</para> + + <itemizedlist> + <listitem> + <para><option>all</option> - <literal>all</literal> - All + audit flags set.</para> + </listitem> + + <listitem> + <para><option>ad</option> - <literal>administrative</literal> + - Administrative actions performed on the system as a + whole.</para> + </listitem> + + <listitem> + <para><option>ap</option> - <literal>application</literal> - + Application defined action.</para> + </listitem> + + <listitem> + <para><option>cl</option> - <literal>file_close</literal> - + Audit calls to the <function>close</function> system + call.</para> + </listitem> + + <listitem> + <para><option>ex</option> - <literal>exec</literal> - Audit + program or utility execution.</para> + </listitem> + + <listitem> + <para><option>fa</option> - <literal>file_attr_acc</literal> + - Audit the access of object attributes such as + &man.stat.1;, &man.pathconf.2; and similar events.</para> + </listitem> + + <listitem> + <para><option>fc</option> - <literal>file_creation</literal> + - Audit events where a file is created as a result.</para> + </listitem> + + <listitem> + <para><option>fd</option> - <literal>file_deletion</literal> + - Audit events where file deletion occurs.</para> + </listitem> + + <listitem> + <para><option>fm</option> - <literal>file_attr_mod</literal> + - Audit events where file attribute modification occurs, + such as &man.chown.8;, &man.chflags.1;, &man.flock.2;, + etc.</para> + </listitem> + + <listitem> + <para><option>fr</option> - <literal>file_read</literal> + - Audit events in which data is read, files are opened for + reading, etc.</para> + </listitem> + + <listitem> + <para><option>fw</option> - <literal>file_write</literal> - + Audit events in which data is written, files are written + or modified, etc.</para> + </listitem> + + <listitem> + <para><option>io</option> - <literal>ioctl</literal> - Audit + use of the &man.ioctl.2; system call.</para> + </listitem> + + <listitem> + <para><option>ip</option> - <literal>ipc</literal> - Audit + various forms of Inter-Process Communication, including POSIX + pipes and System V <acronym>IPC</acronym> operations.</para> + </listitem> + + <listitem> + <para><option>lo</option> - <literal>login_logout</literal> - + Audit &man.login.1; and &man.logout.1; events occurring + on the system.</para> + </listitem> + + <listitem> + <para><option>na</option> - <literal>non_attrib</literal> - + Audit non-attributable events.</para> + </listitem> + + <listitem> + <para><option>no</option> - <literal>no_class</literal> - + Null class used to disable event auditing.</para> + </listitem> + + <listitem> + <para><option>nt</option> - <literal>network</literal> - + Audit events related to network actions, such as + &man.connect.2; and &man.accept.2;.</para> + </listitem> + + <listitem> + <para><option>ot</option> - <literal>other</literal> - + Audit miscellaneous events.</para> + </listitem> + + <listitem> + <para><option>pc</option> - <literal>process</literal> - + Audit process operations, such as &man.exec.3; and + &man.exit.3;.</para> + </listitem> + </itemizedlist> + + <para>Following is a list of all supported audit prefixes:</para> + + <itemizedlist> + <listitem> + <para><literal>none</literal> - Audit both the success + or failure of an event. For example, just listing a + class will result in the auditing of both success and + failure.</para> + </listitem> + + <listitem> + <para><literal>+</literal> - Audit successful events + only.</para> + </listitem> + + <listitem> + <para><literal>-</literal> - Audit failed events + only.</para> + </listitem> + </itemizedlist> + + <warning> + <para>Using the <option>all</option> class with either the + positive or negative prefix can generate a large amount + of data at an extremely rapid rate.</para> + </warning> + + <para>Extra prefixes used to modify the default configuration + values:</para> +<!-- XXX: Perhaps a variable listing here. --> + <itemizedlist> + <listitem> + <para>^- - Disable auditing of failed events.</para> + </listitem> + + <listitem> + <para>^+ - Enable auditing of successful events.</para> + </listitem> + + <listitem> + <para>^ - Disable auditing of both successful and failed + events.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Configuration Files</title> + + <para>In most cases, administrators will need to modify only two files + when configuring the audit system: <filename>audit_control</filename> + and <filename>audit_user</filename>. The first controls system-wide + audit paramaters and defaults for both attributable and + non-attributable events. The second may be used to tune the level + and nature of auditing for individual users.</para> + + <sect3 xml:id="audit-auditcontrol"> + <title>The <filename>audit_control</filename> File</title> + + <para>The <filename>audit_control</filename> file contains some basic + defaults that the administrator may wish to modify. Perhaps + even set some new ones. Viewing the contents of this file, + we see the following:</para> + + <programlisting>dir:/var/audit +flags:lo +minfree:20 +naflags:lo</programlisting> + + <para>The <option>dir</option> option is used to set the default + directory where audit logs are stored. Audit is frequently + configured so that audit logs are stored on a dedicated file + system, so as to prevent interference between the audit + subsystem and other subsystems when file systems become full. + </para> + + <para>The <option>flags</option> option is used to set the + system-wide defaults. The current setting, <option>lo</option> + configures the auditing of all &man.login.1; and &man.logout.1; + actions. A more complex example, + <option>lo,ad,-all,^-fa,^-fc,^-cl</option> audits all system + &man.login.1; and &man.logout.1; actions, all administrator + actions, all failed events in the system, and finally disables + auditing of failed attempts for <option>fa</option>, + <option>fc</option>, and <option>cl</option>. Even though + the <option>-all</option> turned on the auditing of all + failed attempts, the <option>^-</option> prefix will override + that for the latter options.</para> + + <para>Notice that the previous paragraph shows the file is + read from left to right. As such, values further on the + right side may override a previous value specified to + its left.</para> + + <para>The <option>minfree</option> option defines the minimum + percentage of free space for audit file systems. This + relates to the file system where audit logs are stored. + For example, if the <option>dir</option> specifies + <filename>/var/audit</filename> and + <option>minfree</option> is set to twenty (20), warning + messages will be generated when the + <filename>/var</filename> file system grows + to eighty (80) percent full.</para> + + <para>The <option>naflags</option> option specifies audit + classes to be audited for non-attributed events — + that is, events for which there is no authenticated user. + </para> + </sect3> + + <sect3 xml:id="audit-audituser"> + <title>The <filename>audit_user</filename> File</title> + + <para>The <filename>audit_user</filename> file permits the + administrator to determine which classes of audit events + should be logged for which system users.</para> + + <para>The following is the defaults currently placed in + the <filename>audit_user</filename> file:</para> + + <programlisting>root:lo:no +audit:fc:no</programlisting> + + <para>Notice how the default is to audit all cases of + <command>login</command>/<command>logout</command> + and disable auditing of all other actions for + <systemitem class="username">root</systemitem>. This configuration + also audits all file creation and disables all + other auditing for the <systemitem class="username">audit</systemitem> + user. While event auditing does not require a special + user exist, some configurations, specifically environments + making use of <acronym>MAC</acronym>, may require it.</para> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="audit-administration"> + <title>Event Audit Administration</title> + + <para>Events written by the kernel audit subsystem cannot + be altered or read in plain text. Data is stored and accessed + in a method similar to that of &man.ktrace.1; and &man.kdump.1;, + that is, they may only be viewed by dumping them using the + <command>praudit</command> command; audit trails may be reduced + using the <command>auditreduce</command> command, which selects + records from an audit trail based on properties of interest, such + as the user, time of the event, and type of operation.</para> + + <para>For example, the <command>praudit</command> utility will dump the + entire contents of a specified audit log in plain text. To dump an + audit log in its entirety, use:</para> + + <screen>&prompt.root; <userinput>praudit /var/audit/AUDITFILE</userinput></screen> + + <para>Where <replaceable>AUDITFILE</replaceable> is the audit log + of viewing choice. Since audit logs may contain enormous + amounts of data, an administrator may prefer to select records + for specific users. This is made possible with the following + command, where <systemitem class="username">trhodes</systemitem> is the user of + choice:</para> + + <screen>&prompt.root; <userinput>auditreduce -e trhodes /var/audit/AUDITFILE | praudit</userinput></screen> + + <para>This will select all audit records produced by the user + <systemitem class="username">trhodes</systemitem> stored in the + <replaceable>AUDITFILE</replaceable> file.</para> + + <para>There are several other options available for reading audit + records, see the aforementioned command's manual pages for + a more in depth explanation.</para> + + <sect2> + <title>Rotating Audit Log Files</title> + + <para>Due to log reliability requirements, audit trails + are written to only by the kernel, and managed only by + <command>auditd</command>. Administrators should not + attempt to use &man.newsyslog.conf.5; or other tools to + directly rotate audit logs. Instead, the <command>audit</command> + management tool should be used to shut down auditing, + reconfigure the audit system, and perform log rotation. + The following command causes the audit daemon to create a + new audit log and signal the kernel to switch to using the + new log. The old log will be terminated and renamed, at + which point it may then be manipulated by the administrator.</para> + + <screen>&prompt.root; <userinput>audit -n</userinput></screen> + + <warning> + <para>If the <command>auditd</command> daemon is not currently + running, the previous command will fail and an error message + will be produced.</para> + </warning> + + <para>Adding the following line to + <filename>/etc/crontab</filename> will force the rotation + every twelve hours from &man.cron.8;:</para> + + <programlisting>* */12 * * * root /usr/sbin/audit -n</programlisting> + + <para>The change will take effect once you have saved the + new <filename>/etc/crontab</filename>.</para> + </sect2> + + <sect2> + <title>Delegating Audit Review Rights</title> + + <para>By default, only the root user has the right to read system audit + logs. However, that right may be delegated to members of the + <literal>audit</literal> group, as the audit directory and audit + trail files are assigned to that group, and made group-readable. As + the ability to track audit log contents provides significant insight + into the behavior of users and processes, it is recommended that the + delegation of audit review rights be performed with caution.</para> + </sect2> + </sect1> +</chapter> diff --git a/zh_TW.UTF-8/books/handbook/basics/Makefile b/zh_TW.UTF-8/books/handbook/basics/Makefile new file mode 100644 index 0000000000..69b6b899ac --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/basics/Makefile @@ -0,0 +1,16 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# Original revision: 1.1 +# + +CHAPTERS= basics/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/zh_TW.UTF-8/books/handbook/basics/chapter.xml b/zh_TW.UTF-8/books/handbook/basics/chapter.xml new file mode 100644 index 0000000000..3ddf7df0aa --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/basics/chapter.xml @@ -0,0 +1,2366 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ + Original revision: 1.152 +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="basics"> + <info><title>UNIX 基礎概念</title> + <authorgroup> + <author><personname><firstname>Chris</firstname><surname>Shumway</surname></personname><contrib>Rewritten by </contrib></author> + </authorgroup> + + </info> + + + + <sect1 xml:id="basics-synopsis"> + <title>概述</title> + + <para>接下來的這一章將涵蓋 FreeBSD 作業系統的基本指令及功能。 + 大部份的內容在 &unix;-like 作業系統中都是相通的。 + 如果您對這些內容熟悉的話，可以放心的跳過。 + 如果您剛接觸 FreeBSD，那您一定要仔細的讀完這章。</para> + + <para>讀完這章，您將了解：</para> + + <itemizedlist> + <listitem> + <para>如何使用 FreeBSD 的<quote>virtual consoles</quote>。</para> + </listitem> + <listitem> + <para>&unix; 檔案權限運作的方式以及 &os; 中檔案的 flags。</para> + </listitem> + <listitem> + <para>預設的 &os; 檔案系統配置。</para> + </listitem> + <listitem> + <para>&os; 的磁碟結構。</para> + </listitem> + <listitem> + <para>如何掛載(mount)、卸載(umount)檔案系統</para> + </listitem> + <listitem> + <para>什麼是processes、daemons 以及 signals 。</para> + </listitem> + <listitem> + <para>什麼是 shell ，以及如何變更您預設的登入環境。</para> + </listitem> + <listitem> + <para>如何使用基本的文字編輯器。</para> + </listitem> + <listitem> + <para>什麼是 devices 和 device nodes 。</para> + </listitem> + <listitem> + <para>&os; 下使用的 binary 格式。</para> + </listitem> + <listitem> + <para>如何閱讀 manual pages 以獲得更多的資訊。</para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1 xml:id="consoles"> + <title>Virtual Consoles 和終端機</title> + <indexterm><primary>virtual consoles</primary></indexterm> + <indexterm><primary>terminals</primary></indexterm> + + <para>有很多方法可以操作 FreeBSD ，其中一種就是在文字終端機上打字。 + 如此使用 FreeBSD 即可輕易的體會到 &unix; 作業系統的威力和彈性。 + 這一節描述什麼是<quote>終端機</quote>和 <quote>console</quote> + ，以及可以如何在 FreeBSD 中運用它們。</para> + + <sect2 xml:id="consoles-intro"> + <title>The Console</title> + <indexterm><primary>console</primary></indexterm> + + <para>如果您沒有將 FreeBSD 設定成開機時自動進入圖形化模式，系統會在啟動的 + script 跑完之後顯示登入的提示符號。 您將會看到像是這樣的東西：</para> + + <screen>Additional ABI support:. +Local package initialization:. +Additional TCP options:. + +Fri Sep 20 13:01:06 EEST 2002 + +FreeBSD/i386 (pc3.example.org) (ttyv0) + +login:</screen> + + <para>這個訊息在您的系統上會有些許的不同，但是應該會看到類似的東西。 + 我們感興趣的是最後兩行，最後兩行是：</para> + + <programlisting>FreeBSD/i386 (pc3.example.org) (ttyv0)</programlisting> + + <para>這行包含了剛開機完系統的資訊。 您看到的是在 Intel 或相容處理器的 + x86 架構上執行的 <quote>FreeBSD</quote>的 console<footnote> + <para>這就是 <literal>i386</literal> 的意義。 注意即使您不是在 + Intel 的 386 處理器上執行 FreeBSD ，一樣是<literal>i386</literal>。 + 這不是指你的處理器的型號，這裡顯示的是你處理器的<quote>架構</quote> + </para> + </footnote>。 這台機器的名字(每台 &unix; 機器都有一個名字)是 + <systemitem>pc3.example.org</systemitem>，而您現在看到的是它的系統 + console— <filename>ttyv0</filename>終端機。</para> + + <para>最後的一行應該都會是：</para> + + <programlisting>login:</programlisting> + + <para>這是您應該要輸入您的<quote>帳號名稱</quote>的地方。 + 下一小節將告訴您如何登入 FreeBSD。</para> + </sect2> + + <sect2 xml:id="consoles-login"> + <title>登入 FreeBSD</title> + + <para>FreeBSD 是一個 multiuser、multiprocessing 的系統。 + 這是一個正式的名稱，指的是在單一機器上可以同時被不同人使用， + 但同時可以執行很多程式的系統。</para> + + <para>每一種多使用者系統都需要可以分辨不同<quote>使用者</quote>的方法。 + 在 FreeBSD (以及所有的 &unix;-like 作業系統) + 中，所有的使用者在執行程式之前必須先<quote>登入</quote>系統。 + 每個使用者都有一組獨特的帳號名稱 + (<quote>username</quote>)及密碼(<quote>password</quote>)。 + FreeBSD 在允許使用者執行程式前將會先問這兩個問題。</para> + + <indexterm><primary>startup scripts</primary></indexterm> + <para>在 FreeBSD 開機並跑完啟動的 script 之後<footnote> + <para>這些啟動的 script 是在開機的時候 FreeBSD 會自動執行的程式。 + 他們主要的功能是將所有該執行的東西設定好， + 並將您設定成背景執行的服務啟動。</para> + </footnote>，它將會印出提示字元要求您輸入正確的帳號名稱：</para> + + <screen>login:</screen> + + <para>在這個範例裡，我們假設您的帳號是<systemitem class="username">john</systemitem>。 + 在提示字元處輸入 <literal>john</literal> 並按下 <keycap>Enter</keycap> + 。 接著您應該會看到另一個提示字元要您輸入<quote>密碼</quote>：</para> + + <screen>login: <userinput>john</userinput> +Password:</screen> + + <para>輸入 <systemitem class="username">john</systemitem> 的密碼，再按下 + <keycap>Enter</keycap>。 輸入的密碼 + <emphasis>不會顯示在螢幕上</emphasis>。 + 您不需要為此擔心，這樣做是為了安全上的問題。</para> + + <para>如果您輸入了正確的密碼，您應該已經登入 FreeBSD。 + 現在就可以嘗試所有可用的指令了。</para> + + <para>您應該會看到<acronym>MOTD</acronym> + (即今日訊息、Messages Of The Day)，後面接著命令提示字元 + (一個 <literal>#</literal>,<literal>$</literal>, 或是 + <literal>%</literal> 字元)。 這就表示您已經成功登入 + FreeBSD 了。</para> + </sect2> + + <sect2 xml:id="consoles-virtual"> + <title>多重 Console</title> + + <para>在一個 Console 下執行 &unix; 當然是沒有問題，然而 FreeBSD + 是可以同時執行很多程式的。 像 FreeBSD + 這樣可以同時執行一大堆程式的作業系統，只有一個 + console 可以輸入指令實在是有點浪費。 因此 + <quote>virtual consoles</quote> 就顯得相當好用。</para> + + <para>可以設定讓 FreeBSD 同時有很多 virtual console， + 用幾個按鍵的組合就可以從一個 virtual console 跳到別的 virtual console + 。 每一個 console 都有自已不同的輸出頻道，當從某一個 virtual console + 切換到下一個的時候，FreeBSD 會自動處理鍵盤輸入及螢幕輸出。</para> + + <para>FreeBSD 保留了特別的按鍵組合來切換 console <footnote> + <para>在 &man.syscons.4;、&man.atkbd.4;、&man.vidcontrol.1;、以及 + &man.kbdcontrol.1;等 manual page 中，對於 FreeBSD 的 console + 及鍵盤驅動程式有詳細的技術說明。 我們在這裡不討論細節， + 有興趣的讀者隨時可以在 manual pages + 中查到關於運作方式的更詳細且完整的解釋。</para></footnote>。 + 您可以用 <keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo>、 + <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo>、到 + <keycombo><keycap>Alt</keycap><keycap>F8</keycap></keycombo> + 來切換 FreeBSD 的不同 console。</para> + + <para>當您從一個 console 切換到下一個的時候，FreeBSD + 會處理螢幕輸出的儲存及回復。 + 這就<quote>好像</quote>有很多<quote>虛擬</quote>的螢幕和鍵盤， + 可以讓您輸入指令到 FreeBSD 執行。 在某一個 console + 上執行的程式並不會因為切到別的 console 而停止執行，切換到另一個 + console 時，它們仍會繼續執行。</para> + </sect2> + + <sect2 xml:id="consoles-ttys"> + <title><filename>/etc/ttys</filename> 檔</title> + + <para>FreeBSD 預設的虛擬 console 總共有 8 個， + 但這並非硬性規定，您可輕鬆設定這些虛擬 console 的數量增減。 + 有關虛擬 console 的編號跟設定都在 + <filename>/etc/ttys</filename> 這檔案內設定。</para> + + <para>可以用 <filename>/etc/ttys</filename> 檔案來設定 + FreeBSD 的虛擬 console。 檔案內每行非註解文字(該行開頭沒有 + <literal>#</literal> 這字)都是設定終端機或虛擬 console。 + FreeBSD 預設有 9 個虛擬 console 但只啟動 8 個，也就是以下以 + <literal>ttyv</literal> 開頭的那幾行設定。</para> + + <programlisting># name getty type status comments +# +ttyv0 "/usr/libexec/getty Pc" cons25 on secure +# Virtual terminals +ttyv1 "/usr/libexec/getty Pc" cons25 on secure +ttyv2 "/usr/libexec/getty Pc" cons25 on secure +ttyv3 "/usr/libexec/getty Pc" cons25 on secure +ttyv4 "/usr/libexec/getty Pc" cons25 on secure +ttyv5 "/usr/libexec/getty Pc" cons25 on secure +ttyv6 "/usr/libexec/getty Pc" cons25 on secure +ttyv7 "/usr/libexec/getty Pc" cons25 on secure +ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure</programlisting> + + <para>有關各欄位的設定以及其他選項，請參閱 &man.ttys.5; 說明。</para> + </sect2> + + <sect2 xml:id="consoles-singleuser"> + <title>Single User 模式的 Console</title> + + <para>有關 <quote>single user 模式</quote> 的介紹在 + <xref linkend="boot-singleuser"/> + 這邊有詳盡介紹。 在 single user 模式時，能夠使用的 console + 只有一個，並無虛擬 console 可用。 而 single user 模式相關設定值可以在 + <filename>/etc/ttys</filename> 檔做調整。 下面以 + <literal>console</literal> 開頭的那行，就是了：</para> + + <programlisting># name getty type status comments +# +# If console is marked "insecure", then init will ask for the root password +# when going to single-user mode. +console none unknown off secure</programlisting> + + <note> + <para>在 <literal>console</literal> 那行前面的註解有提到，可以把那行的 + <literal>secure</literal> 改為 <literal>insecure</literal>， + 如此一來，即使 FreeBSD 進入 single user 模式， + 仍會要求您輸入 <systemitem class="username">root</systemitem> 的密碼。</para> + + <para><emphasis>請審慎考慮是否要改為 + <literal>insecure</literal></emphasis>。 因為萬一忘記 + <systemitem class="username">root</systemitem> 密碼的話，若要登入 single user + 模式就有些麻煩了。儘管還有其他方式可以登入，但對不熟 FreeBSD + 開機程序的人而言，就會相當棘手。</para> + </note> + </sect2> + + <sect2 xml:id="consoles-vidcontrol"> + <title>更改 console 的顯示畫面</title> + + <para>FreeBSD console 預設顯示大小可以調整為 1024x768、1280x1024 + 或其他顯示卡與螢幕有支援的解析度大小。 要切換顯示大小，必須要重新編譯 + kernel 並加入下面這兩項設定：</para> + + <programlisting>options VESA +options SC_PIXEL_MODE</programlisting> + + <para>一旦 kernel 有加入這兩項並重新編譯完畢，就可以用 &man.vidcontrol.1; + 來偵測目前所支援的模式有哪些。 若要查看支援的模式，可以打：</para> + + <screen>&prompt.root; <userinput>vidcontrol -i mode</userinput></screen> + + <para>該指令會顯示該機器所支援的顯示模式清單。 然後可以在 + <systemitem class="username">root</systemitem> console 內透過 &man.vidcontrol.1; 指令， + 來更改顯示模式：</para> + + <screen>&prompt.root; <userinput>vidcontrol MODE_279</userinput></screen> + + <para>若對新的顯示模式覺得還不錯，可以在 <filename>/etc/rc.conf</filename> + 設定之，以讓每次重開機後會自動生效。 以上面這情況為例，就是：</para> + + <programlisting>allscreens_flags="MODE_279"</programlisting> + </sect2> + </sect1> + + <sect1 xml:id="permissions"> + <title>權限</title> + <indexterm><primary>UNIX</primary></indexterm> + + <para>FreeBSD 源自於 BSD &unix;，繼承了幾個重要的 &unix; 概念。 + 首先也最明顯，它是一款 multi-user 作業系統。 它可以同時處理多人多工， + 負責徹底的分享與管理來自每位使用者對硬碟裝置、週邊設備、記憶體及 + CPU 時間的要求。</para> + + <para>也因為系統能夠支援多使用者， + 所以系統管理的一切都有權限來決定誰可以讀取、寫入或執行資源。 + 這些權限分別使用三組八進位的數字儲存，一組代表檔案的所有者， + 一組代表檔案所屬的群組，而最後一組則代表其他所有人。 + 表示這些數字的方式如下:</para> + + <indexterm><primary>permissions</primary></indexterm> + <indexterm> + <primary>file permissions</primary> + </indexterm> + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>值</entry> + <entry>權限</entry> + <entry>目錄顯示</entry> + </row> + </thead> + + <tbody> + <row> + <entry>0</entry> + <entry>不可讀取, 不可寫入, 不可執行</entry> + <entry><literal>---</literal></entry> + </row> + + <row> + <entry>1</entry> + <entry>不可讀取, 不可寫入, 可執行</entry> + <entry><literal>--x</literal></entry> + </row> + + <row> + <entry>2</entry> + <entry>不可讀取, 可寫入, 不可執行</entry> + <entry><literal>-w-</literal></entry> + </row> + + <row> + <entry>3</entry> + <entry>不可讀取, 可寫入, 可執行</entry> + <entry><literal>-wx</literal></entry> + </row> + + <row> + <entry>4</entry> + <entry>可讀取, 不可寫入, 不可執行</entry> + <entry><literal>r--</literal></entry> + </row> + + <row> + <entry>5</entry> + <entry>可讀取, 不可寫入, 可執行</entry> + <entry><literal>r-x</literal></entry> + </row> + + <row> + <entry>6</entry> + <entry>可讀取, 可寫入, 不可執行</entry> + <entry><literal>rw-</literal></entry> + </row> + + <row> + <entry>7</entry> + <entry>可讀取, 可寫入, 可執行</entry> + <entry><literal>rwx</literal></entry> + </row> + </tbody> + </tgroup> + </informaltable> + <indexterm> + <primary><command>ls</command></primary> + </indexterm> + <indexterm><primary>directories</primary></indexterm> + + <para>使用 &man.ls.1; 指令時，可以加上 <option>-l</option> 參數， + 來檢視詳細的目錄清單。 + 清單中欄位的資訊包含檔案對所有者、群組及其他人的權限。 + 在任一個目錄底下執行 <command>ls -l</command>，會顯示如下的結果: + </para> + + <screen>&prompt.user; <userinput>ls -l</userinput> +total 530 +-rw-r--r-- 1 root wheel 512 Sep 5 12:31 myfile +-rw-r--r-- 1 root wheel 512 Sep 5 12:31 otherfile +-rw-r--r-- 1 root wheel 7680 Sep 5 12:31 email.txt +...</screen> + + <para>在這裡告所您該如何區分 <command>ls -l</command> + 第一欄當中的資訊:</para> + + <screen>-rw-r--r--</screen> + + <para>第一個 (最左邊) 的字元用來表示這個檔案的類型為何， + 除標準檔案以外，尚有目錄、特殊字元裝置 (Special character device)、 + Socket 及其他特殊虛擬檔案裝置 (Special pseudo-file device)， + 在此例當中，<literal>-</literal> 表示該檔案為一個標準的檔案。 + 範例中接下來的三個字元中，<literal>rw-</literal> + 代表所有者對檔案擁有的權限。 再接下來的三個字元， + <literal>r--</literal> 則代表群組對檔案擁有的權限， + 最後三個字元，<literal>r--</literal> 則代表其他人對檔案擁有的權限。 + 破折號 (-) 表示沒有權限，範例中的這個檔案的權限， + 只允許所有者讀取、寫入檔案，群組以及其他人僅能讀取檔案。 + 根據以上的表格，此種權限的檔案可以使用 <literal>644</literal> 來表示， + 每組數字分別代表檔案的三種權限。</para> + + <para>以上是不錯的方式，但系統該如何控制裝置的權限？ 實際上 FreeBSD + 對大多的硬碟裝置就如同檔案，程式可以開啟、讀取以及寫入資料如一般檔案。 + 這些特殊裝置檔案 (Special device file) 都儲存於 <filename>/dev</filename> + 目錄中。</para> + + <para> + 目錄也同如檔案，擁有讀取、寫入及執行的權限， + 但在執行權限上與檔案有明顯的差異。 當目錄被標示為可執行時，代表可以使用 + <quote>cd</quote> (更改目錄) 進入該目錄。 + 也代表能夠存取在此目錄之中的已知檔名的檔案 + (當然，檔案仍擁有自己的權限)</para> + + <para>尤其，要能夠列出目錄內容，必須擁有目錄的讀取權限。 + 而當要刪除已知檔名的檔案時，也必須擁有檔案所在目錄的寫入 + <emphasis>以及</emphasis> 執行的權限。</para> + + <para>還有一些權限，但這些權限主要在特殊情況使用，如 + setuid binaries 及 sticky directories。 + 如果您還想知道更多檔案權限的資訊及使用方法，請務必參閱 + &man.chmod.1; 說明文件。</para> + + <sect2> + <info><title>權限符號</title> + <authorgroup> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + <indexterm><primary>permissions</primary><secondary>symbolic</secondary></indexterm> + + <para>權限符號可稱做符號表示， + 使用字元的方式來取代使用數值來設定檔案或目錄的權限。 + 符號表示的格式依序為 (某人)(動作)(權限)，可使用的符號如下:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>項目</entry> + <entry>字母</entry> + <entry>意義</entry> + </row> + </thead> + + <tbody> + <row> + <entry>(某人)</entry> + <entry>u</entry> + <entry>使用者</entry> + </row> + + <row> + <entry>(某人)</entry> + <entry>g</entry> + <entry>群組所有者</entry> + </row> + + <row> + <entry>(某人)</entry> + <entry>o</entry> + <entry>其他</entry> + </row> + + <row> + <entry>(某人)</entry> + <entry>a</entry> + <entry>全部(<quote>world</quote>)</entry> + </row> + + <row> + <entry>(動作)</entry> + <entry>+</entry> + <entry>增加權限</entry> + </row> + + <row> + <entry>(動作)</entry> + <entry>-</entry> + <entry>移除權限</entry> + </row> + + <row> + <entry>(動作)</entry> + <entry>=</entry> + <entry>指定權限</entry> + </row> + + <row> + <entry>(權限)</entry> + <entry>r</entry> + <entry>讀取</entry> + </row> + + <row> + <entry>(權限)</entry> + <entry>w</entry> + <entry>寫入</entry> + </row> + + <row> + <entry>(權限)</entry> + <entry>x</entry> + <entry>執行</entry> + </row> + + <row> + <entry>(權限)</entry> + <entry>t</entry> + <entry>Sticky bit</entry> + </row> + + <row> + <entry>(權限)</entry> + <entry>s</entry> + <entry>Set UID 或 GID</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>如先前同樣使用 &man.chmod.1; 指令來設定，但使用的參數為這些字元。 + 例如，您可以使用下列指令禁止其他使用者存取檔案 + <replaceable>FILE</replaceable>:</para> + + <screen>&prompt.user; <userinput>chmod go= FILE</userinput></screen> + + <para>若有兩個以上的符號表示可以使用逗號 (,) 區隔。 + 例如，下列指令將會移除群組及其他人對檔案 + <replaceable>FILE</replaceable> 的寫入權限， + 並使全部人(<quote>world</quote>)對該檔有執行權限。</para> + + <screen>&prompt.user; <userinput>chmod go-w,a+x FILE</userinput></screen> + +<!-- + <para>Most users will not notice this, but it should be pointed out + that using the octal method will only set or assign permissions to + a file; it does not add or delete them.</para> +--> + </sect2> + + <sect2> + <info><title>&os; 檔案旗標(Flag)</title> + <authorgroup> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + + <para>除了前面提到的檔案權限外，&os; 支援使用 <quote>檔案旗標</quote>。 + 這些旗標增加了檔案的安全性及管理性，但不包含目錄。</para> + + <para>檔案旗標增加了管理性，確保在某些時候 <systemitem class="username">root</systemitem> + 不會意外將檔案修改或移除。</para> + + <para>修改的檔案 flag 僅需要使用擁有簡易的介面的 &man.chflags.1; 工具。 + 例如，標示系統禁止刪除的旗標於檔案 + <filename>file1</filename>，使用下列指令：</para> + + <screen>&prompt.root; <userinput>chflags sunlink file1</userinput></screen> + + <para>若要移除系統禁止刪除的旗標，只需要簡單在 <option>sunlink</option> + 前加上 <quote>no</quote>，例如：</para> + + <screen>&prompt.root; <userinput>chflags nosunlink file1</userinput></screen> + + <para>使用 &man.ls.1; 及參數 <option>-lo</option> + 可檢視檔案目前的旗標：</para> + + <screen>&prompt.root; <userinput>ls -lo file1 + </userinput></screen> + + <para>輸出的結果如下:</para> + + <programlisting>-rw-r--r-- 1 trhodes trhodes sunlnk 0 Mar 1 05:54 file1</programlisting> + + <para>多數的旗標僅能由 <systemitem class="username">root</systemitem> + 使用者來標示或移除，而部份旗標可由檔案所有者設定。 + 我們建議系統管理者可閱讀 &man.chflags.1; 及 &man.chflags.2; + 說明以瞭解相關細節。</para> + </sect2> + </sect1> + + <sect1 xml:id="dirstructure"> + <title>目錄結構</title> + <indexterm><primary>directory hierarchy</primary></indexterm> + + <para>認識 FreeBSD 的目錄架構，就可對系統有概略的基礎理解。 + 最重要的莫過於整個目錄的根目錄，就是 <quote>/</quote> 目錄， + 該目錄會在開機時最先掛載 (mount)，裡面會有開機所會用到必備檔案。 + 此外，根目錄還有紀錄其他檔案系統的掛載點相關設定。</para> + + <para>「掛載點」就是讓新增的檔案系統，能接到上層的檔案系統 + (通常就是「根目錄」檔案系統) 的目錄。 + 在 <xref linkend="disk-organization"/> 這邊對此有更詳細介紹。 + 標準的掛載點包括了 <filename>/usr</filename>、<filename>/var</filename>、 + <filename>/tmp</filename>、<filename>/mnt</filename> 以及 + <filename>/cdrom</filename>。 這些目錄通常會記錄在 + <filename>/etc/fstab</filename> 設定檔內。 + <filename>/etc/fstab</filename> 是記錄各檔案系統及相關掛載點的表格。 + 大部分在 <filename>/etc/fstab</filename> 有記錄的檔案系統，會在開機時由 + &man.rc.8; script 來自動掛載，除非它們有設定 <option>noauto</option> + 選項。 其中細節說明可參閱 <xref linkend="disks-fstab"/>。</para> + + <para>有關檔案系統架構的完整說明可參閱 &man.hier.7;。 + 現在呢，讓我們大致先一窺常見的目錄有哪些吧。</para> + + <para> + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>目錄</entry> + <entry>說明</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><filename>/</filename></entry> + <entry>檔案系統的根目錄。</entry> + </row> + + <row> + <entry><filename>/bin/</filename></entry> + <entry>single-user、multi-user 兩種模式皆可使用的基本工具 + 。</entry> + </row> + + <row> + <entry><filename>/boot/</filename></entry> + <entry>作業系統開機過程會用到的程式、設定檔。</entry> + </row> + + <row> + <entry><filename>/boot/defaults/</filename></entry> + <entry>預設的開機啟動設定檔，詳情請參閱 &man.loader.conf.5; + 。</entry> + </row> + + <row> + <entry><filename>/dev/</filename></entry> + <entry>Device nodes，詳情請參閱 &man.intro.4;。</entry> + </row> + + <row> + <entry><filename>/etc/</filename></entry> + <entry>系統設定檔及一些 script 檔。</entry> + </row> + + <row> + <entry><filename>/etc/defaults/</filename></entry> + <entry>預設的系統設定檔，詳情請參閱 &man.rc.8;。</entry> + </row> + + <row> + <entry><filename>/etc/mail/</filename></entry> + <entry>MTA(Mail Transport Agent)的相關設定檔，像是 + &man.sendmail.8;。</entry> + </row> + + <row> + <entry><filename>/etc/namedb/</filename></entry> + <entry><command>named</command> 設定檔，詳情請參閱 + &man.named.8;。</entry> + </row> + + <row> + <entry><filename>/etc/periodic/</filename></entry> + <entry>每日、每週、每月透過 &man.cron.8;; 執行的定期排程 script， + 詳情請參閱 &man.periodic.8;。</entry> + </row> + + <row> + <entry><filename>/etc/ppp/</filename></entry> + <entry><command>ppp</command> 設定檔，詳情請參閱 + &man.ppp.8;。</entry> + </row> + + <row> + <entry><filename>/mnt/</filename></entry> + <entry>系統管理者慣用充當臨時掛載點的空目錄。</entry> + </row> + + <row> + <entry><filename>/proc/</filename></entry> + <entry>Process 檔案系統，詳情請參閱 &man.procfs.5; 及 + &man.mount.procfs.8;。</entry> + </row> + + <row> + <entry><filename>/rescue/</filename></entry> + <entry>緊急救援用途的一些 statically linked 程式，詳情請參閱 + &man.rescue.8;。</entry> + </row> + + <row> + <entry><filename>/root/</filename></entry> + <entry><systemitem class="username">root</systemitem> 帳號的家目錄。</entry> + </row> + + <row> + <entry><filename>/sbin/</filename></entry> + <entry>供 single-user 及 multi-user 環境使用的系統程式及管理工具 + 。</entry> + </row> + + <row> + <entry><filename>/tmp/</filename></entry> + <entry>臨時檔案。 一般而言，重開機之後 + <filename>/tmp</filename> 內的東西會被清除掉。 + 而通常會將 memory-based 檔案系統掛載在 + <filename>/tmp</filename> 上。 + 這些瑣事可透過 tmpmfs 相關的 &man.rc.conf.5; 環境變數來自動完成 + 。(或是在 <filename>/etc/fstab</filename> 內做設定， + 詳情請參閱 &man.mdmfs.8;。)</entry> + </row> + + <row> + <entry><filename>/usr/</filename></entry> + <entry>主要是使用者所安裝的工具程式、應用程式存放處。</entry> + </row> + + <row> + <entry><filename>/usr/bin/</filename></entry> + <entry>常用工具、開發工具、應用軟體。</entry> + </row> + + <row> + <entry><filename>/usr/include/</filename></entry> + <entry>標準 C include 的相關 header 檔案庫。</entry> + </row> + + <row> + <entry><filename>/usr/lib/</filename></entry> + <entry>函式庫存放處。</entry> + </row> + + <row> + <entry><filename>/usr/libdata/</filename></entry> + <entry>其他各式工具的資料檔。</entry> + </row> + + <row> + <entry><filename>/usr/libexec/</filename></entry> + <entry>系統 daemons 及系統工具程式(透過其他程式來執行)。</entry> + </row> + + <row> + <entry><filename>/usr/local/</filename></entry> + + <entry>存放一些自行安裝的執行檔、函式庫等等。 同時，也是 FreeBSD + ports 架構的預設安裝目錄。 <filename>/usr/local</filename> + 內的目錄架構大致與 <filename>/usr</filename> 相同，詳情請參閱 + &man.hier.7; 說明。 但 man 目錄例外，它們是直接放在 + <filename>/usr/local</filename> 底下，而非 + <filename>/usr/local/share</filename>，而 ports + 所安裝的說明文件則在 + <filename>share/doc/port</filename>。 + </entry> + </row> + + <row> + <entry><filename>/usr/obj/</filename></entry> + <entry>在編譯 <filename>/usr/src</filename> + 目錄時所產生的相關架構 object 檔案。</entry> + </row> + + <row> + <entry><filename>/usr/ports</filename></entry> + <entry>FreeBSD Ports Collection (optional)。</entry> + </row> + + <row> + <entry><filename>/usr/sbin/</filename></entry> + <entry>系統 daemon 及系統工具(直接由使用者執行)。</entry> + </row> + + <row> + <entry><filename>/usr/share/</filename></entry> + <entry>各架構皆共通的檔案。</entry> + </row> + + <row> + <entry><filename>/usr/src/</filename></entry> + <entry>BSD 本身的原始碼(或自行新增的)。</entry> + </row> + + <row> + <entry><filename>/usr/X11R6/</filename></entry> + <entry>X11R6 相關套件的執行檔、函式庫等(optional)。</entry> + </row> + + <row> + <entry><filename>/var/</filename></entry> + <entry>存放各種用途的 log 檔、臨時或暫時存放、列印或郵件的 + spool 檔案。有時候，memory-based 檔案系統也會掛載在 + <filename>/var</filename>。 + 這些瑣事可透過 varmfs 相關的 &man.rc.conf.5; + 環境變數來自動完成。(或是在 + <filename>/etc/fstab</filename> 內做設定，相關細節請參閱 + &man.mdmfs.8;。)</entry> + </row> + + + <row> + <entry><filename>/var/log/</filename></entry> + <entry>各項系統記錄的 log 檔案。</entry> + </row> + + <row> + <entry><filename>/var/mail/</filename></entry> + <entry>各使用者的 mailbox 檔案。</entry> + </row> + + <row> + <entry><filename>/var/spool/</filename></entry> + <entry>各種印表機、郵件系統的 spool 目錄。</entry> + </row> + + <row> + <entry><filename>/var/tmp/</filename></entry> + <entry>臨時檔案。 + 這些檔案在重開機後通常仍會保留，除非 + <filename>/var</filename> + 是屬於 memory-based 檔案系統。</entry> + </row> + + <row> + <entry><filename>/var/yp</filename></entry> + <entry>記錄 NIS maps。</entry> + </row> + + </tbody> + </tgroup> + </informaltable> + </para> + + </sect1> + + <sect1 xml:id="disk-organization"> + <title>磁碟組織</title> + + <para>FreeBSD 用來尋找檔案的最小單位就是檔案的名稱了。 + 檔案的名稱有大小寫之分，所以說 <filename>readme.txt</filename> + 和 <filename>README.TXT</filename> 是兩個不同的檔案。 + FreeBSD 並不使用副檔名 (<filename>.txt</filename>) + 來判別這是一個程式檔、文件檔或是其他類型的檔案。</para> + + <para>檔案存在目錄裡面。 + 一個目錄中可能沒有任何檔案，也可能有好幾百個檔案。 + 目錄之中也可以包含其他的目錄； + 您可以建立階層式的目錄以便資料的管理。</para> + + <para>檔案或目錄的對應是藉由給定的檔案或目錄名稱，然後加上正斜線符號 + (<literal>/</literal>)；之後再視需要加上其他的目錄名稱。 + 如果您有一個目錄 <filename>foo</filename> ，裡面有一個目錄叫作 + <filename>bar</filename>，這個目錄中又包含了一個叫 + <filename>readme.txt</filename> + 的檔案，那麼這個檔案的全名，或者說檔案的<firstterm>路徑</firstterm>就是 + <filename>foo/bar/readme.txt</filename>。</para> + + <para>目錄及檔案儲存在檔案系統之中。 + 每個檔案系統都有唯一一個最上層的目錄，叫做<firstterm>根目錄 + (root directory)</firstterm>。 + 然後在這個根目錄下面才能有其他的目錄。</para> + + <para>到目前為止大概和其他您用過的的作業系統都差不多。 + 還是有些不一樣的地方就是了，例如 &ms-dos; 用 <literal>\</literal> + 當檔案和目錄名稱的分隔符號，而 &macos; 則是用 <literal>:</literal> + 符號。</para> + + <para>FreeBSD 的路徑中並沒有使用磁碟機代號或其他的磁碟名稱。 + 因此，您不可以使用像 <filename>c:/foo/bar/readme.txt</filename> + 這樣子的檔案名稱。</para> + + <para>相對的，在 FreeBSD + 系統中有一個檔案系統被指定為<firstterm>根檔案系統</firstterm>。 + 根檔案系統的根目錄由 <literal>/</literal> 表示。 + 然後其他的檔案系統再<firstterm>掛載 (mount)</firstterm> + 在根檔案系統之下。因此無論您的 FreeBSD + 系統上有多少顆硬碟，每一個目錄看起來就像在同一個磁碟上。</para> + + <para>假設您有三個檔案系統，分別叫作 <literal>A</literal>、 + <literal>B</literal> 及 <literal>C</literal>。 + 每個檔案系統都包含兩個目錄，叫做 + <literal>A1</literal>、<literal>A2</literal> (依此類推得 + <literal>B1</literal>、<literal>B2</literal> 及 + <literal>C1</literal>、<literal>C2</literal>)。</para> + + <para>稱 <literal>A</literal> 為主要的檔案系統；如果您用 + <command>ls</command> 指令查看此目錄的內容，您會看到兩個子目錄： + <literal>A1</literal> 及 <literal>A2</literal>，如下所示：</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/example-dir1"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> / + | + +--- A1 + | + `--- A2</literallayout> + </textobject> + </mediaobject> + + <para>一個檔案系統必須以目錄形式掛載於另一個檔案系統上。 + 因此，假設您將 <literal>B</literal> 掛載於 <literal>A1</literal> + 之上，則 <literal>B</literal> 的根目錄就變成了 + <literal>A1</literal>，而在 <literal>B</literal> + 之下的任何目錄的路徑也隨之改變:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/example-dir2"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> / + | + +--- A1 + | | + | +--- B1 + | | + | `--- B2 + | + `--- A2</literallayout> + </textobject> + </mediaobject> + + <para>在 <literal>B1</literal> 或 <literal>B2</literal> + 目錄中的任何檔案必須經由路徑 <filename>/A1/B1</filename> + 或 <filename>/A1/B2</filename> 才能達到。 + 所有原來在 <filename>/A1</filename> 中的檔案會暫時被隱藏起來，直到 + <literal>B</literal> 被「<firstterm>移除 + (unmounted)</firstterm>」後才會再顯現出來。</para> + + <para>如果 <literal>B</literal> 掛載在 <literal>A2</literal> + 之上，則會變成：</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/example-dir3"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> / + | + +--- A1 + | + `--- A2 + | + +--- B1 + | + `--- B2</literallayout> + </textobject> + </mediaobject> + + <para>上面的路徑分別為 <filename>/A2/B1</filename> 及 + <filename>/A2/B2</filename>。</para> + + <para>檔案系統可以掛在其他檔案系統的目錄之上。 + 延續之前的例子，<literal>C</literal> 檔案系統可以掛在檔案系統 + <literal>B</literal> 的 <literal>B1</literal> + 目錄之上，如圖所示：</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/example-dir4"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> / + | + +--- A1 + | + `--- A2 + | + +--- B1 + | | + | +--- C1 + | | + | `--- C2 + | + `--- B2</literallayout> + </textobject> + </mediaobject> + + <para>或者 <literal>C</literal> 直接掛載於 <literal>A</literal> 的 + <literal>A1</literal> 目錄之上：</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/example-dir5"/> + </imageobject> + + <textobject> + <literallayout class="monospaced"> / + | + +--- A1 + | | + | +--- C1 + | | + | `--- C2 + | + `--- A2 + | + +--- B1 + | + `--- B2</literallayout> + </textobject> + </mediaobject> + + <para>如果您熟悉 &ms-dos; 的話，這和 <command>join</command> + 指令很類似 (雖然不儘相同)。</para> + + <para>一般情況下您不需要擔心這些東西。 + 除非您要安裝新的磁碟，不然通常在您安裝 FreeBSD + 時建立好檔案系統並決定好要掛載在何處之後就不會再做任何更動了。</para> + + <para>您完全可以使用單一的一個大的根檔案系統 (root file system) + 而不建立其他的檔案系統。 這樣有好處也有有壞處。</para> + + <itemizedlist> + <title>使用多個檔案系統的好處</title> + + <listitem> + <para>不同的檔案系統在掛上的時候可以有不同的 + <firstterm>掛載參數</firstterm>。 + 舉例來說，為求謹慎您可以將根檔案系統設成唯讀， + 以避免不小心刪除或修改掉重要的檔案。 + 將使用者可寫入的檔案系統 (例如 <filename>/home</filename>) + 獨立出來也可以讓他們用 <firstterm>nosuid</firstterm> + 的參數掛載，此選項可以讓在這個檔案系統中執行檔的 + <firstterm>suid</firstterm>/<firstterm>guid</firstterm> + bits 失效，也許可以讓系統更安全。</para> + </listitem> + + <listitem> + <para>FreeBSD 會自動根據您檔案系統的使用方式來做最佳的檔案配置方式。 + 因此，一個有很多小檔案、 + 常常寫入的檔案系統跟只有幾個較大的檔案的檔案系統配置是不一樣的。 + 如果您只有單一一個大的檔案系統，這部分就沒用了。</para> + </listitem> + + <listitem> + <para>FreeBSD 的檔案系統在停電的時候很穩固。 + 然而，在某些重要的時候停電仍然會對檔案系統結構造成損害。 + 分割成許多個檔案系統的話在系統在停電後比較能夠正常啟動， + 以便您在需要的時候將備份資料回存回來。</para> + </listitem> + </itemizedlist> + + <itemizedlist> + <title>使用單一檔案系統的好處</title> + + <listitem> + <para>檔案系統的大小是固定的。 + 您當初安裝 FreeBSD + 的時候應該會給定一個大小，可是後來您可能會想把空間加大。 + 如果沒有備份的話是很難達成的； + 您必須將檔案系統重新建立為您需要的大小，然後將備份回存回來。</para> + + <important> + <para>FreeBSD 的 &man.growfs.8; + 指令可以突破此限制直接變更檔案系統的大小。</para> + </important> + </listitem> + </itemizedlist> + + <para>檔案系統包含在分割區裡面。 + 因為 &os; 承襲 &unix; 架構，這邊講的分割區和一般提到的分割區 + (例如 &ms-dos; 分割區) 不同。 每一個分割區由一個代號(字母)表示，從 + <literal>a</literal> 到 <literal>h</literal>。 + 每個分割區只能包含一個檔案系統。 + 因此除了說常見到用檔案系統同的掛載點來表示檔案系統外， + 也可以用包含他的分割區代號來表示。</para> + + <para>FreeBSD 也會拿磁碟空間來當 <firstterm>swap space</firstterm>。 + Swap space 給 FreeBSD 當作<firstterm>虛擬記憶體</firstterm>用。 + 這讓您的電腦好像擁有比實際更多的記憶體。 + 當 FreeBSD 的記憶體用完的時候，它會把一些目前沒用到的資料移到 + swap space，然後在用到的時候移回去 (同時移出部份沒用到的)。</para> + + <para>某些分割區有慣例的使用方式如下：</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="5*"/> + + <thead> + <row> + <entry>分割區</entry> + + <entry>慣例</entry> + </row> + </thead> + + <tbody valign="top"> + <row> + <entry><literal>a</literal></entry> + + <entry>通常包含根檔案系統 (root file system)</entry> + </row> + + <row> + <entry><literal>b</literal></entry> + + <entry>通常是 swap space</entry> + </row> + + <row> + <entry><literal>c</literal></entry> + + <entry>通常和整個 slice 的大小一樣，給一些會用到整個 slice + 的工具程式 (例如硬碟壞軌檢查工具) 來使用。 + 一般來說您應該不會把檔案系統建立在這個分割區。</entry> + </row> + + <row> + <entry><literal>d</literal></entry> + + <entry>分割區 <literal>d</literal> + 曾經有代表特殊意義，但是已經不再使用。 + 所以現在 <literal>d</literal> + 就和其他一般的分割區相同了。</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>每個包含有檔案系統的分割區是存在所謂的 + <firstterm>slice</firstterm> 裡面。 + FreeBSD 的 slice 就是指平常我們稱為分割區 (partition) 的東西。 + 同樣地，會這樣子稱呼也是因為 FreeBSD 的 &unix; 色彩。 + 而 slice 是有編號的，從 1 號編到 4 號。</para> + + <indexterm><primary>slices</primary></indexterm> + <indexterm><primary>partitions</primary></indexterm> + <indexterm><primary>dangerously dedicated</primary></indexterm> + + <para>slice 號碼跟在裝置名稱後面，先接一個字母 + <literal>s</literal>，然後從 1 號開始編下去。 + 因此 <quote>da0<emphasis>s1</emphasis></quote> 就是指第一個 SCSI + 硬碟的第一個 slice。 一個磁碟上只能有四個實體的 slice，但是在實體的 + slice 中您可以塞進適當類型的邏輯 slice。 這些延伸的 slice 編號從 5 + 開始，所以 <quote>ad0<emphasis>s5</emphasis></quote> 是第一個 IDE + 硬碟上的第一個延伸 slice。 檔案系統在裝置 (device) 裡就是在一個 slice + 之中。</para> + + <para>Slices、<quote>dangerously dedicated</quote> + 模式的實體磁碟機，以及其他包含<firstterm>分割區(partition)</firstterm> + 的磁碟都是以字母 <literal>a</literal> 到 <literal>h</literal> + 的編號來表示。 編號是接在裝置名稱的後面的，因此 + <quote>da0<emphasis>a</emphasis></quote> 是磁碟機 da 上的第一個 + <quote>dangerously dedicated</quote>模式之分割區。 + 而 <quote>ad1s3<emphasis>e</emphasis></quote> + 則是第二顆 IDE 硬碟上第三個 slice 的第五個分割區。</para> + + <para>最後，我們就可以把系統上的每個磁碟都區分出來了。 + 一個磁碟的名稱會有一個代碼來表示這個磁碟的類型，接著是一個數字， + 表示這是哪一個磁碟。 這邊跟 slice 每個磁碟編號從 0 開始不一樣。 + 常見的代碼可以參考 <xref linkend="basics-dev-codes"/>。</para> + + <para>當要參照一個分割區的時候，FreeBSD 會要您一併輸入包含這個分割區的 + slice 及磁碟機名稱；當要參照一個 slice 的時候，也必須輸入包含這個 + slice 的磁碟名稱。 怎麼做呢？首先先列出磁碟名稱，然後 + <literal>s</literal> 加上 slice 編號，最後再輸入分割區字母代號。 + 範例可以參考 <xref linkend="basics-disk-slice-part"/>.</para> + + <para><xref linkend="basics-concept-disk-model"/> + 示範了一個基本的磁碟分布模式，相信對您有些幫助。</para> + + <para>要安裝 FreeBSD，您必須先建置磁碟的 slice，接著於 slice 中建立要給 + FreeBSD 用的分割區。 最後在這些分割區中建立檔案系統 (或 swap space) + 並決定要將這些檔案系統掛載於哪裡。</para> + + <table frame="none" pgwide="1" xml:id="basics-dev-codes"> + <title>磁碟機代號</title> + + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="5*"/> + + <thead> + <row> + <entry>代號</entry> + + <entry>意義</entry> + </row> + </thead> + + <tbody> + <row> + <entry><filename>ad</filename></entry> + + <entry>ATAPI(IDE) 磁碟機</entry> + </row> + + <row> + <entry><filename>da</filename></entry> + + <entry>SCSI 直接存取磁碟機</entry> + </row> + + <row> + <entry><filename>acd</filename></entry> + + <entry>ATAPI(IDE) 光碟機</entry> + </row> + + <row> + <entry><filename>cd</filename></entry> + + <entry>SCSI 光碟機</entry> + </row> + + <row> + <entry><filename>fd</filename></entry> + + <entry>軟碟機</entry> + </row> + </tbody> + </tgroup> + </table> + + <example xml:id="basics-disk-slice-part"> + <title>磁碟、slice 及分割區命名範例</title> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="5*"/> + + <thead> + <row> + <entry>名稱</entry> + + <entry>意義</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>ad0s1a</literal></entry> + + <entry>第一個 IDE 硬碟 (<literal>ad0</literal>) 上第一個 slice + (<literal>s1</literal>)的第一個分割區(<literal>a</literal>) + 。</entry> + </row> + + <row> + <entry><literal>da1s2e</literal></entry> + <entry>第二個 SCSI 硬碟 (<literal>da1</literal>) 上第二個 slice + (<literal>s2</literal>) 的第五個分割區 (<literal>e</literal>) + 。</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + + <example xml:id="basics-concept-disk-model"> + <title>磁碟的概念模型</title> + + <para>此圖顯示 FreeBSD 中接到系統的第一個 IDE 磁碟機內部配置圖。 + 假設這個磁碟的容量是 4 GB，並且包含了兩個 2 GB 的 + slice (&ms-dos; 的分割區)。 第一個 slice 是 DOS 的 + <filename>C:</filename> 磁碟機，第二個則安裝了 FreeBSD。 + 本範例的 FreeBSD 有三個分割區以及一個 swap 分割區。</para> + + <para>這三個分割區每個都是一個檔案系統。 + <literal>a</literal> 分割是根 (root) 檔案系統；分割 + <literal>e</literal> 是 <filename>/var</filename>；而 + <literal>f</literal> 分割是 <filename>/usr</filename> + 目錄結構。</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/disk-layout"/> + </imageobject> + + <textobject> + <literallayout class="monospaced">.-----------------. --. +| | | +| DOS / Windows | | +: : > First slice, ad0s1 +: : | +| | | +:=================: ==: --. +| | | Partition a, mounted as / | +| | > referred to as ad0s2a | +| | | | +:-----------------: ==: | +| | | Partition b, used as swap | +| | > referred to as ad0s2b | +| | | | +:-----------------: ==: | Partition c, no +| | | Partition e, used as /var > file system, all +| | > referred to as ad0s2e | of FreeBSD slice, +| | | | ad0s2c +:-----------------: ==: | +| | | | +: : | Partition f, used as /usr | +: : > referred to as ad0s2f | +: : | | +| | | | +| | --' | +`-----------------' --'</literallayout> + </textobject> + </mediaobject> + </example> + </sect1> + + + + <sect1 xml:id="mount-unmount"> + <title>掛載與卸載檔案系統</title> + + <para>檔案系統就像一顆樹。<filename>/</filename> + 就像是樹根，而 <filename>/dev</filename>，<filename>/usr</filename> + 以及其他在根目錄下的目錄就像是樹枝，而這些樹枝上面又還有分支，像是 + <filename>/usr/local</filename> 等。</para> + + <indexterm><primary>根檔案系統</primary></indexterm> + <para>因為某些原因，我們會將一些目錄分別放在不同的檔案系統上。 + 如 <filename>/var</filename> 包含了可能會滿出來的 + <filename>log/</filename>，<filename>spool/</filename> + 等目錄以及各式各樣的暫存檔。 + 把根檔案系統塞到滿出來顯然不是個好主意，所以我們往往會比較傾向把 + <filename>/var</filename> 從 <filename>/</filename> 中拉出來。</para> + + <para>另一個常見到把某些目錄放在不同檔案系統上的理由是： + 這些檔案在不同的實體或虛擬磁碟機上。 + 像是<link linkend="network-nfs">網路檔案系統</link> + (Network File System) 或是光碟機。</para> + + <sect2 xml:id="disks-fstab"> + <title> <filename>fstab</filename> 檔</title> + <indexterm> + <primary>檔案系統 file systems</primary> + <secondary>由fstab掛載 mounted with fstab</secondary> + </indexterm> + + <para>在 <filename>/etc/fstab</filename> + 裡面有設定的檔案系統會在<link linkend="boot">開機</link> + 的過程中自動地被掛載 + (除非該檔案系統有被加上 <option>noauto</option> 參數)。</para> + + <para><filename>/etc/fstab</filename> 檔案內容的格式如下：</para> + + <programlisting><replaceable>device</replaceable> <replaceable>/mount-point</replaceable> <replaceable>fstype</replaceable> <replaceable>options</replaceable> <replaceable>dumpfreq</replaceable> <replaceable>passno</replaceable></programlisting> + + <variablelist> + <varlistentry> + <term><literal>device</literal></term> + <listitem> + <para>裝置名稱 (該裝置必須真的存在)。 詳情請參閱 + <xref linkend="disks-naming"/>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>mount-point</literal></term> + + <listitem><para>檔案系統要掛載到的目錄 (該目錄必須真的存在)。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>fstype</literal></term> + + <listitem> + <para>檔案系統類型，這是要傳給 &man.mount.8; 的參數。 + FreeBSD 預設的檔案系統是 <literal>ufs</literal>。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>options</literal></term> + + <listitem> + <para>可讀可寫的檔案系統用 + <option>rw</option>，而唯讀的檔案系統則是用 + <option>ro</option>，後面視需要還可以加其他選項。 + 常見的選項如 <option>noauto</option> + 是用在不要於開機過程中自動的掛載的檔案系統。 + 其他選項可參閱 &man.mount.8; 說明。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>dumpfreq</literal></term> + + <listitem> + <para>&man.dump.8; 由此項目決定那些檔案系統需要傾印。 + 如果這格空白則以零為預設值。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>passno</literal></term> + + <listitem> + <para>這個項目決定檔案系統檢查的順序。 + 對於要跳過檢查的檔案系統，它們的 <literal>passno</literal> + 值要設為零。 根檔案系統的 <literal>passno</literal> 值應設為一 + (因為需要比所有其他的還要先檢查)，而其他的檔案系統的 + <literal>passno</literal> 值應該要設得比一大。 + 若有多個檔案系統具有相同的 <literal>passno</literal> 值，則 + &man.fsck.8; 會試著平行地(如果可能的話)檢查這些檔案系統。</para> + </listitem> + </varlistentry> + </variablelist> + + <para>更多關於 <filename>/etc/fstab</filename> + 檔案格式及選項的資訊請參閱 &man.fstab.5; 說明文件。</para> + </sect2> + + <sect2 xml:id="disks-mount"> + <title><command>mount</command> 指令</title> + <indexterm> + <primary>檔案系統 file systems</primary> + <secondary>掛載 mounting</secondary> + </indexterm> + + <para>&man.mount.8; 指令是拿來掛載檔案系統用的。</para> + + <para>基本的操作指令格式如下:</para> + + <informalexample> + <screen>&prompt.root; <userinput>mount device mountpoint</userinput></screen> + </informalexample> + + <para>在 &man.mount.8; + 裡面有提到一大堆的選項，不過最常用的就是這些：</para> + + <variablelist> + <title>掛載選項</title> + + <varlistentry> + <term><option>-a</option></term> + + <listitem> + <para>把 <filename>/etc/fstab</filename> + 裡面所有還沒有被掛載、沒有被標記成 <quote>noauto</quote> + 而且沒有用 <option>-t</option> 排除的檔案系統掛載起來。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + + <listitem> + <para>執行所有的動作，但是不真的去呼叫掛載的 system call。 + 這個選項和 <option>-v</option> 搭配拿來推測 &man.mount.8; + 將要做什麼動作時很好用。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-f</option></term> + + <listitem> + <para>強迫掛載不乾淨的檔案系統 (危險)，或是用來強制取消寫入權限 + (把檔案系統的掛載狀態從可存取變成唯讀)。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-r</option></term> + + <listitem> + <para>用唯讀的方式掛載檔案系統。 這個選項和在 <option>-o</option> + 選項中指定 <option>ro</option> (在 &os; 5.2之前的版本是用 + <option>rdonly</option>) 參數是一樣的。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-t</option> + <replaceable>fstype</replaceable></term> + + <listitem> + <para>用指定的檔案系統型態 (fstype) + 來掛載指定的檔案系統，或是在有 <option>-a</option> + 選項時只掛載指定型態的檔案系統。</para> + + <para>預設的檔案系統是 <quote>ufs</quote>。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-u</option></term> + + <listitem> + <para>更新檔案系統的掛載選項。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-v</option></term> + + <listitem> + <para>顯示較詳細資訊。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-w</option></term> + + <listitem> + <para>以可存取的模式掛載檔案系統。</para> + </listitem> + </varlistentry> + </variablelist> + + <para><option>-o</option> 選項後面會接著以逗號分隔的參數，例如：</para> + <variablelist> + <varlistentry> + <term>noexec</term> + + <listitem> + <para>不允許在這個檔案系統上執行二進位程式碼， + 這也是一個蠻有用的安全選項。</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>nosuid</term> + + <listitem> + <para>不解析檔案系統上的 setuid 或 setgid 旗標， + 這也是一個蠻有用的安全選項。</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 xml:id="disks-umount"> + <title><command>umount</command> 指令</title> + <indexterm> + <primary>檔案系統 file systems</primary> + <secondary>卸載 unmounting</secondary> + </indexterm> + + <para>&man.umount.8; 指令的參數可以是掛載點 + (mountpoint)，裝置名稱，以及 <option>-a</option> 或是 + <option>-A</option> 等選項。</para> + + <para>加上 <option>-f</option> 可以強制卸載，加上 <option>-v</option> + 則是會顯示詳細資訊。 要注意的是一般來說用 <option>-f</option> + 並不是個好主意，強制卸載檔案系統有可能會造成電腦當機， + 或者損壞檔案系統內的資料。</para> + + <para><option>-a</option> 和 <option>-A</option> + 是用來卸載所有已掛載的檔案系統，另外還可以用 <option>-t</option> + 來指定要卸載的是哪些種類的檔案系統。 要注意的是 <option>-A</option> + 並不會試圖卸載根檔案系統。</para> + + </sect2> + </sect1> + + <sect1 xml:id="basics-processes"> + <title>程序</title> + + <para>FreeBSD 是一個多工的作業系統，也就是說在同一時間內可以跑超過一個程式。 + 每一個正在花時間跑的程式就叫做 <firstterm>程序 (process)</firstterm>。 + 您下的每個指令都至少會開啟一個新的程序， + 而有些系統程序是一直在跑以維持系統正常運作的。</para> + + <para>每一個程序都有一個不重覆的數字叫做 <firstterm>process ID + </firstterm>，或稱為 <firstterm>PID + </firstterm>，而且就像檔案一樣，每一個程序也有擁有者及群組。 + 擁有者及群組的資訊是用來決定什麼檔案或裝置是這個程序可以開啟的 + (前面有提到過檔案權限)。 大部份的程序都有父程序。 + 父程序是開啟這個程序的程序，例如：您對 shell 輸入指令，shell + 本身就是一個程序，而您執行的指令也是程序。 + 每一個您用這種方式跑的程序的父程序都是 shell。 + 有一個特別的程序叫做 &man.init.8; 是個例外。<command>init</command> + 永遠是第一個程序，所以他的 PID 一直都會是 1。 在 FreeBSD 開機的時候 + <command>init</command> 會自動地被 kernel 開啟。</para> + + <para>要看系統執行中的程序，有兩個相當有用的指令可用： + &man.ps.1; 以及 &man.top.1;。<command>ps</command> + 指令是用來列出正在執行之程序，而且可以秀它們的 + PID、用了多少記憶體、執行的指令名稱及其後之參數是什麼等等。 + <command>top</command> 指令則是顯示所有正在執行的程序， + 並且數秒鐘更新一次。因此您可以互動式的觀看您的電腦正在做什麼。</para> + + <para>在預設的情況下，<command>ps</command> + 指令只會顯示您所擁有的的程序。 例如：</para> + + <screen>&prompt.user; <userinput>ps</userinput> + PID TT STAT TIME COMMAND + 298 p0 Ss 0:01.10 tcsh + 7078 p0 S 2:40.88 xemacs mdoc.xsl (xemacs-21.1.14) +37393 p0 I 0:03.11 xemacs freebsd.dsl (xemacs-21.1.14) +48630 p0 S 2:50.89 /usr/local/lib/netscape-linux/navigator-linux-4.77.bi +48730 p0 IW 0:00.00 (dns helper) (navigator-linux-) +72210 p0 R+ 0:00.00 ps + 390 p1 Is 0:01.14 tcsh + 7059 p2 Is+ 1:36.18 /usr/local/bin/mutt -y + 6688 p3 IWs 0:00.00 tcsh +10735 p4 IWs 0:00.00 tcsh +20256 p5 IWs 0:00.00 tcsh + 262 v0 IWs 0:00.00 -tcsh (tcsh) + 270 v0 IW+ 0:00.00 /bin/sh /usr/X11R6/bin/startx -- -bpp 16 + 280 v0 IW+ 0:00.00 xinit /home/nik/.xinitrc -- -bpp 16 + 284 v0 IW 0:00.00 /bin/sh /home/nik/.xinitrc + 285 v0 S 0:38.45 /usr/X11R6/bin/sawfish</screen> + + <para>在這個範例裡可以看到 &man.ps.1; 的輸出分成好幾個欄位。 + <literal>PID</literal> 就是前面有提到的 process ID。 PID 的分配是從 + 1 開始一直到 99999，如果用完的話又會繞回來重頭開始分配 + (若該 PID 已經在用了，則 PID 不會重新分配)。 + <literal>TT</literal> 欄位是指這個程式在哪個 tty + 上執行，在這裡可以先忽略不管。<literal>STAT</literal> + 是程式的狀態，也可以先不要管。<literal>TIME</literal> 是這個程式在 + CPU 上執行的時間—這通常不是程式總共花的時間， + 因為當您開始執行程式後，大部份的程式在 CPU 上執行前會先花上不少時間等待 + 。 最後，<literal>COMMAND</literal> 是執行這個程式的命令列。</para> + + <para>&man.ps.1; + 有幾個不同的選項組合可以用來變更顯示出來的資訊，其中一個最有用的組合是 + <literal>auxww</literal>。 + <option>a</option> 可以顯示所有正在跑的程序的指令，不只是您自已的。 + <option>u</option> 則是顯示程序的擁有者名稱以及記憶體使用情況。 + <option>x</option> 可以把 daemon 程序顯示出來， + 而 <option>ww</option> 可讓 &man.ps.1; 顯示出每個程序完整的內容， + 而不致因過長而被螢幕截掉了。</para> + + <para>&man.top.1; 也有類似的輸出。 一般的情況看像是這樣：</para> + + <screen>&prompt.user; <userinput>top</userinput> +last pid: 72257; load averages: 0.13, 0.09, 0.03 up 0+13:38:33 22:39:10 +47 processes: 1 running, 46 sleeping +CPU states: 12.6% user, 0.0% nice, 7.8% system, 0.0% interrupt, 79.7% idle +Mem: 36M Active, 5256K Inact, 13M Wired, 6312K Cache, 15M Buf, 408K Free +Swap: 256M Total, 38M Used, 217M Free, 15% Inuse + + PID USERNAME PRI NICE SIZE RES STATE TIME WCPU CPU COMMAND +72257 nik 28 0 1960K 1044K RUN 0:00 14.86% 1.42% top + 7078 nik 2 0 15280K 10960K select 2:54 0.88% 0.88% xemacs-21.1.14 + 281 nik 2 0 18636K 7112K select 5:36 0.73% 0.73% XF86_SVGA + 296 nik 2 0 3240K 1644K select 0:12 0.05% 0.05% xterm +48630 nik 2 0 29816K 9148K select 3:18 0.00% 0.00% navigator-linu + 175 root 2 0 924K 252K select 1:41 0.00% 0.00% syslogd + 7059 nik 2 0 7260K 4644K poll 1:38 0.00% 0.00% mutt +...</screen> + + <para>輸出的資訊分成兩個部份。開頭 (前五行) 秀出最近一個程序的 + PID、系統平均負載 (系統有多忙錄的測試)、系統的開機時間 + (從上次重開算起) 以及現在的時間等。 + 在開頭裡面的其他數字分別是在講有多少程序正在執行 + (在本例中為47)、有多少記憶體及 swap space + 被占用了，還有就是系統分別花了多少時間在不同的 CPU 狀態上。</para> + + <para>接下來的部份是由好幾個欄位所構成，和 &man.ps.1; 輸出的資訊類似。 + 就如同前例，您可以看到 PID、使用者名稱、CPU + 花費的時間以及正在執行的指令。 &man.top.1; + 在預設的情況下還會告訴您程序用掉了多少的記憶體空間。 + 在這邊會分成兩欄，一個是總用量 (total size)，另一個是實際用量 + (resident size)—總用量是指這個應用程式需要的記憶體空間， + 而實際用量則是指實際上該程式的記憶體使用量。 + 在這個例子裡面您可以看到 <application>&netscape;</application> + 要了幾乎到 30 MB 的 RAM，但是只有用到 9 MB。</para> + + <para>&man.top.1; 每隔 2 秒鐘會自動更新顯示內容，可用 <option>s</option> + 選項來改變間隔的時間。</para> + + </sect1> + + <sect1 xml:id="basics-daemons"> + <title>Daemon、信號及終止程序</title> + + <para>當在執行文書編輯器時，您可以很容易地使用它，叫它讀取檔案或是什麼的。 + 可以這樣做是因為編輯器有提供這些功能， + 還有就是編輯器依附在一個<firstterm>終端機 (Terminal) </firstterm>之上。 + 有些程式並不是設計成一直在接收使用者的輸入的， + 所以它們在一開始執行的時候就從終端機斷開了。 例如說， + 網頁伺服器整天都在回應網頁方面的要求，它通常不需要您輸入任何東西。 + 另外，像是把信從一個站傳送到另一個站的程式，也是這種類型的應用程式。 + </para> + + <para>我們把這種程式稱作 <firstterm>daemon</firstterm>。 + Daemon (惡魔、守護神) + 是希臘神話中的角色：祂們不屬於善良陣營或邪惡陣營，是守護的小精靈。 + 大致上來說祂們就是在替人類做一些有用的事情， + 跟今天的網頁伺服器或是郵件伺服器很像。 這也就是為何 BSD + 的吉祥物，長期以來都是一隻穿著帆布鞋拿著三叉耙的快樂小惡魔的原因。</para> + + <para>通常來說 deamon 程式的名字後面都會加一個字母 <quote>d</quote>。 + <application>BIND</application> 是 Berkeley Internet Name Domain + 的縮寫 (但實際上執行的程式名稱是 <command>named</command>)、Apache + 網頁伺服器的程式名稱是 <command>httpd</command>、印表機服務程式是 + <command>lpd</command>，依此類推。 + 這是習慣用法，並沒有硬性規定，例如 <application>Sendmail</application> + 主要的寄信 daemon 是叫做 <command>sendmail</command> 而不是 + <command>maild</command>，跟您想像的不一樣。</para> + + <para>有些時候會需要跟某個 daemon 程序溝通， + 這些溝通是透過所謂的<firstterm>信號(signal)</firstterm>來傳遞給該 daemon + 程序(或是其他執行中的程序)。 + 藉由送出信號，您可以和一個 daemon (或是任何一個正在跑的程序) 溝通。 + 信號有很多種—有些有特定的意義，有些則是會由應用程式來解讀。 + 應用程式的說明文件會告訴您該程式是如何解讀信號的。 + 您只能送信號給您擁有的程序，送 &man.kill.1; 或 &man.kill.2; + 的信號給別人的程序是不被允許的。 不過 <systemitem class="username"> root </systemitem> + 不受此限制，他可以送信號給任何人的程序。</para> + + <para>FreeBSD 本身在某些情況也會送信號給應用程式。 + 假設有個應用程式寫得很爛，然後企圖要存取它不該碰的記憶體的時候，FreeBSD + 會送一個 <firstterm>Segmentation Violation</firstterm> 信號 + (<literal>SIGSEGV</literal>) 給這個程序。 + 又如果有一個應用程式用了 &man.alarm.3; 的 system call + 要求系統在過一段時間之後叫他一下，時間到了的時候鬧鐘的信號 + (<literal>SIGALRM</literal>) 就會被送出了，其他的依此類推。</para> + + <para><literal>SIGTERM</literal> and <literal>SIGKILL</literal> + 這兩個信號可以拿來終止程序。 用 <literal>SIGTERM</literal> + 結束程序是比較有禮貌的方式，該程序會<emphasis>捕捉 (catch) </emphasis> + 這個信號而了解到您想要把他關掉。 接著下來它會把它自已開的記錄檔通通關掉， + 然後在關掉程序之前結束掉手邊的工作。 在某些情況下程序有可能會裝作沒看見 + <literal>SIGTERM</literal>，假如它正在做一些不能中斷的工作的話。</para> + + <para><literal>SIGKILL</literal> 就沒有辦法被程序忽略了。 + 這是一個<quote>我管你正在幹嘛，現在就給我停下來</quote>的信號。 + 如果您送了 <literal>SIGKILL</literal> 信號給某個程序，FreeBSD + 將會把它停掉<footnote> + <para>不完全正確—還是有少數東西不能被中斷。 + 例如有個程序正在從網路上的別的電腦讀一個檔案， + 而那部電腦因為某些理由連不到 (機器被關掉，或是網路爛掉了)， + 那這個程序我們就說他是一個<quote>不能中斷的</quote>程序。 + 通常在經過兩分鐘左右之後這個程序會逾時。 + 當發生逾時的時候這個程序就會被結束掉了。</para> + </footnote>。</para> + + <para>這些是其他您有可能會要用到的信號： + <literal>SIGHUP</literal>，<literal>SIGUSR1</literal>，以及 + <literal>SIGUSR2</literal>。 + 這些是通用的信號，當送出時不同的應用程式會有不同的反應。</para> + + <para>假設您更動了您的網頁伺服器的設定檔— + 您想要叫網頁伺服器去重新讀取設定值。 您可以關閉後再重新啟動 + <command>httpd</command>，但是這麼做會造成網頁伺服器暫停服務一段時間， + 這樣子可能不太好。 + 大部份的 daemon 都寫成會去回應 <literal>SIGHUP</literal>。 + 當收到這個信號之後，它們會去重新讀取自已的設定檔。 + 因此您可以用送 <literal>SIGHUP</literal> 信號來取代關掉重開。 + 又因為沒有標準在規範如何回應這些信號，不同的 daemon + 可能會有不同的行為，所以有疑問的話請先確認並翻閱 deamon + 的說明文件。</para> + + <para>信號是由 &man.kill.1; 指令送出的，如範例所示：</para> + + <procedure> + <title>送信號給程序</title> + + <para>這個範例將會示範如何送一個信號給 &man.inetd.8;。 + <command>inetd</command> 的設定檔是 + <filename>/etc/inetd.conf</filename>，而 <command>inetd</command> + 會在收到 <literal>SIGHUP</literal> 的時候重新讀取這個設定檔。</para> + + <step> + <para>找出您想要送信號的那個程序的 ID。 您會用到 &man.ps.1; 以及 + &man.grep.1; 這兩個指令。 &man.grep.1; 是用來在輸出中搜尋， + 找出您指定的字串。 這個指令是由一般使用者執行，而 &man.inetd.8; + 是由 <systemitem class="username">root</systemitem> 執行，所以在使用 &man.ps.1; 時需要加上 + <option>ax</option> 選項。</para> + + <screen>&prompt.user; <userinput>ps -ax | grep inetd</userinput> + 198 ?? IWs 0:00.00 inetd -wW</screen> + + <para>因此可知 &man.inetd.8; 的 PID 為 198。 在某些情況下 + <literal>grep inetd</literal> 這個指令本身也會出現在輸出裡。 + 這是因為 &man.ps.1; 乃是找所有執行中的程序的方式造成的。</para> + </step> + + <step> + <para>用 &man.kill.1; 來送信號。 又因為 &man.inetd.8; 是由 + <systemitem class="username">root</systemitem> 執行的，您必須用 &man.su.1; 切換成 + <systemitem class="username">root</systemitem>先。</para> + + <screen>&prompt.user; <userinput>su</userinput> +<prompt>Password:</prompt> +&prompt.root; <userinput>/bin/kill -s HUP 198</userinput></screen> + + <para>一般情況對大多數 &unix; 指令來講，當 &man.kill.1; + 執行成功時並不會輸出任何訊息。 + 假設您送一個信號給某個不是您所擁有的程序， + 那麼您就會吃到這個錯誤訊息： <errorname>kill: + <replaceable>PID</replaceable>: Operation not permitted</errorname>。 + 而如果您打錯 PID 的話，那就會把信號送給錯誤的程序。 這樣可能會很糟， + 不過如果您夠幸運的話，可能剛好就只是把信號送給一個非使用中的 + PID，那您就只會看到 <errorname>kill: + <replaceable>PID</replaceable>: No such process</errorname> 而已。 + </para> + + <note> + <title>為什麼用 <command>/bin/kill</command>？</title> + + <para>很多 shell 有提供內建的 <command>kill</command> 指令。 + 也就是說這種 shell 會直接送信號，而不是執行 + <filename>/bin/kill</filename>。 + 這樣是蠻方便的沒錯啦，但是不同的 shell + 會有不同的語法來指定信號的名稱等。 + 與其嘗試去把它們通通學會，不如就單純的直接用 <command>/bin/kill + ...</command> 吧。</para> + </note> + </step> + </procedure> + + <para>要送其他的信號的話也是非常類似，就視需要把指令中的 + <literal>TERM</literal> 或 <literal>KILL</literal> + 替換掉即可。</para> + + <important> + <para>隨便抓一個系統中的程序然後把他砍掉並不是個好主意。 + 特別是 &man.init.8;， process ID 1，一個非常特別的程序。 + 執行 <command>/bin/kill -s KILL 1</command> + 的結果就是系統立刻關機。 因此在您按下 <keycap>Return</keycap> + 要執行 &man.kill.1;<emphasis>之前</emphasis>， + 請<emphasis>一定</emphasis>要記得再次確認您下的參數。</para> + </important> + </sect1> + + <sect1 xml:id="shells"> + <title>Shells</title> + <indexterm><primary>shells</primary></indexterm> + <indexterm><primary>命令列 command line</primary></indexterm> + + <para>在 FreeBSD 中，很多日常的工作是在一個叫做 shell + 的文字介面中完成的。 + Shell 的主要工作就是從輸入中收到命令並執行它們。 + 許多 shell 也有內建一些有助於日常工作的指令， + 像是檔案管理、檔案比對、命令列編輯、指令巨集以及環境變數等。 + FreeBSD 有內附了幾個 shell，像是 <command>sh</command>， + Bourne Shell，以及 <command>tcsh</command>，改良版的 C-shell。 + 還有許多其他的 shell 可以從 FreeBSD Ports Collection + 中取得，像是 <command>zsh</command> 以及 <command>bash</command> + 等。</para> + + <para>您用哪個 shell 呢？ 其實每個人的喜好都不一樣。 + 如果您是一個 C 程式設計師，那對於使用像是 <command>tcsh</command> + 這種 C-like 的 shell 可能會感到相當愉快。 如果你是從 Linux + 跳過來的，或者您是一個 &unix; 新手，那您也許會想要用 + <command>bash</command> 來當作文字介面。 + 每一個 shell 都有自已獨特之處，至於這些特點能不能配合您的工作環境？ + 那就是您選擇 shell 的重點了。</para> + + <para>檔名自動補齊就是常見的 shell 功能。 + 首先輸入指令或檔案的前幾個字母，這時通常您只需要按下 <keycap>Tab</keycap> + 鍵，接下來 shell 就會自動把指令或是檔案名稱剩餘的部份補齊。 + 假設您有兩個檔案分別叫作 <filename>foobar</filename> 及 + <filename>foo.bar</filename>。 現在要刪掉 + <filename>foo.bar</filename>，那麼可以輸入： + <command>rm fo[Tab].[Tab]</command> + </para> + + <para>Shell 會印出這個： <command>rm foo[嗶].bar</command>。</para> + + <para>[嗶] 是 console 的響鈴，這嗶的一聲是 shell + 在告訴我說它沒有辦法完全自動補齊檔名，因為有不只一個檔名符合條件。 + <filename>foobar</filename> 和 <filename>foo.bar</filename> 都是 + <literal>fo</literal> 開頭的檔名，不過它至少可以補齊到 <literal>foo</literal>。 + 如果您接著輸入 <literal>.</literal> 然後再按 <keycap>Tab</keycap> + 一次，那 shell 就能夠替您把剩下的檔名填滿了。</para> + + <indexterm><primary>environment variables</primary></indexterm> + + <para>Shell 的另一項特點是使用了環境變數。 + 環境變數是以變數與鍵值（variable/key）的對應關係儲存於 shell + 的環境空間中，任何由 shell 所產生的程序都可以讀取此空間， + 因此這個空間儲存了許多程序的設定組態。 在此附上 + 一份常見環境變數與其涵義的列表：</para> + <indexterm><primary>environment variables</primary></indexterm> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>變數</entry> + <entry>詳細說明</entry> + </row> + </thead> + + <tbody> + <row> + <entry><envar>USER</envar></entry> + <entry>目前登入的使用者名稱。</entry> + </row> + + <row> + <entry><envar>PATH</envar></entry> + <entry>以冒號（:）隔開的目錄列表，用以搜尋執行檔的路徑。</entry> + </row> + + <row> + <entry><envar>DISPLAY</envar></entry> + <entry>若存在這個環境變數，則代表 X11 連結顯示器的網路名稱。</entry> + </row> + + <row> + <entry><envar>SHELL</envar></entry> + <entry>目前使用的 shell。</entry> + </row> + + <row> + <entry><envar>TERM</envar></entry> + <entry>使用者終端機的名稱，能藉由此變數判斷終端機的能力。</entry> + </row> + + <row> + <entry><envar>TERMCAP</envar></entry> + <entry>Database entry of the terminal escape codes to perform + various terminal functions.</entry> + </row> + + <row> + <entry><envar>OSTYPE</envar></entry> + <entry>作業系統的種類，如：FreeBSD。</entry> + </row> + + <row> + <entry><envar>MACHTYPE</envar></entry> + <entry>目前系統所用的 CPU 架構。</entry> + </row> + + <row> + <entry><envar>EDITOR</envar></entry> + <entry>使用者偏好的文字編輯器。</entry> + </row> + + <row> + <entry><envar>PAGER</envar></entry> + <entry>使用者偏好的文字分頁器（text pager）。</entry> + </row> + + <row> + <entry><envar>MANPATH</envar></entry> + <entry>以冒號（:）隔開的目錄列表，用以搜尋 manual pages 的路徑。</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <indexterm><primary>Bourne shells</primary></indexterm> + <para>在不同的 shell 底下設定環境變數的方式也有所不同。 + 舉例來說，在 C-Style 的 shell 底下，像是 + <command>tcsh</command> 和 <command>csh</command>，你必須使用 + <command>setenv</command> 來設定環境變數。 + 但在 Bourne shells 底下，像是 <command>sh</command> 和 + <command>bash</command>，你則必須使用 + <command>export</command> 來設定你所使用的環境變數。 + 再舉個例子來說，若要設定或是修改 + <envar>EDITOR</envar> 這個環境變數，在 <command>csh</command> 或 + <command>tcsh</command> 下設定 <envar>EDITOR</envar> 這個環境變數為 + <filename>/usr/local/bin/emacs</filename> 的指令是：</para> + + <screen>&prompt.user; <userinput>setenv EDITOR /usr/local/bin/emacs</userinput></screen> + + <para>在 Bourne shells 下則是：</para> + + <screen>&prompt.user; <userinput>export EDITOR="/usr/local/bin/emacs"</userinput></screen> + + <para>大多數的 shell 都支援使用者在命令列中將 + <literal>$</literal> 字元放在變數之前，以取得環境變數的值。 + 舉例來說，<command>echo $TERM</command> 會 + 顯示出 <envar>$TERM</envar> 的設定值，這是因為 shell 取得了 + <envar>$TERM</envar> 的設定值， + 並將其傳給 <command>echo</command> 顯示出來。</para> + + <para>Shell 中有某些特別的字元是來表示特殊的資料，我們將其稱作 + meta-characters。 其中最常見的是 + <literal>*</literal> 字元，他代表了檔名中的任意字元。 + 這些特殊字元可以用在檔名展開（filename globbing）上，舉例來說，輸入 + <command>echo *</command> 會和輸入 + <command>ls</command> 得到幾乎相同的結果，這是因為 shell 會將所有符合 + <literal>*</literal> 字元的檔案傳到命令列上，再由 + <command>echo</command> 顯示出來。</para> + + <para>為了避免 shell 轉譯這些特殊字元，我們可以在這些特殊字元前放一個反斜線 + (<literal>\</literal>) 字元使他們跳脫(escape) shell 的轉譯。舉例來說， + <command>echo $TERM</command> 會印出你目前設定的終端機格式， + <command>echo \$TERM</command> 則會直接印出 <envar>$TERM</envar> + 這幾個字。</para> + + <sect2 xml:id="changing-shells"> + <title>變更你的 Shell</title> + + <para>變更 shell 最簡單的方法就是透過 <command>chsh</command> 命令。 + 執行 <command>chsh</command> 將會呼叫環境變數中 <envar>EDITOR</envar> + 指定的文字編輯器。 如果沒有設定，則預設是 <command>vi</command>。 + 請依照需求去修改 <quote>Shell:</quote> 的值。</para> + + <para>你也可以透過 <command>chsh</command> 的參數 <option>-s</option>， + 這可以直接設定你的 shell 而不需要透過任何文字編輯器。 例如， + 假設想把所用的 shell 改為 <command>bash</command>， + 可以透過下列的方式：</para> + + <screen>&prompt.user; <userinput>chsh -s /usr/local/bin/bash</userinput></screen> + + <note> + <para>你所使用的 shell <emphasis>必須</emphasis> 列於 + <filename>/etc/shells</filename> 裡頭。 如果是由 + <link linkend="ports">Ports Collection</link> 來裝 shell， + 那這個步驟已經完成了。 但若是手動安裝了一個 shell， + 那麼就必須為新安裝的 shell 進行設定。</para> + + <para>舉例來說，若手動安裝了 <command>bash</command> 並將它置於 + <filename>/usr/local/bin</filename> 底下，你還得：</para> + + <screen>&prompt.root; <userinput>echo "/usr/local/bin/bash" >> /etc/shells</userinput></screen> + + <para>然後再重新執行 <command>chsh</command>。</para> + </note> + </sect2> + </sect1> + + <sect1 xml:id="editors"> + <title>文字編輯器</title> + <indexterm><primary>text editors</primary></indexterm> + <indexterm><primary>editors</primary></indexterm> + + <para>在 FreeBSD 中有許多設定必須透過編輯文字檔完成。 + 因此，若能熟悉文字編輯器是再好不過的。 + FreeBSD 本身（指 base system）就附有幾種文字編輯器， + 此外，你也可以透過 Ports Collection 來安裝其他的文字編輯器。</para> + + <indexterm> + <primary><command>ee</command></primary> + </indexterm> + <indexterm> + <primary>editors</primary> + <secondary><command>ee</command></secondary> + </indexterm> + <para>最簡單易學的文字編輯器叫做 <application>ee</application>， + 代表了其全名 easy editor。 要開始使用 <application>ee</application>， + 必須在命令列上輸入 + <command>ee filename</command>， + 這邊的 <replaceable>filename</replaceable> 代表你想要編輯的檔案名稱。 + 舉例來說，要編輯 <filename>/etc/rc.conf</filename>，就要輸入 + <command>ee /etc/rc.conf</command>。 + 而在 <command>ee</command> 的操作介面下， + 所有編輯器的功能與操作都會顯示在螢幕的正上方。 + 其中的插入符號(<literal>^</literal>)代表鍵盤上的 <keycap>Ctrl</keycap> + 鍵，所以 <literal>^e</literal> 就等同於 + <keycombo action="simul"><keycap>Ctrl</keycap><keycap>e</keycap></keycombo> + 。 若要結束 <application>ee</application>，請按下 <keycap>Esc</keycap> + 鍵，接著選擇 leave editor 即可。 + 此時如果該檔案有修改過，編輯器會提醒你是否要存檔。</para> + + <indexterm> + <primary><command>vi</command></primary> + </indexterm> + <indexterm> + <primary>editors</primary> + <secondary><command>vi</command></secondary> + </indexterm> + <indexterm> + <primary><command>emacs</command></primary> + </indexterm> + <indexterm> + <primary>editors</primary> + <secondary><command>emacs</command></secondary> + </indexterm> + + <para>此外，FreeBSD 也內附了幾個好用的文字編輯器，像是 base system 的 + <application>vi</application> 及 FreeBSD Ports Collection 內的其他編輯器， + 比如 <application>Emacs</application> 及 <application>vim</application> + (<package>editors/emacs</package> 及 + <package>editors/vim</package>)。 + 這些文字編輯器提供更強的功能，但是也比較難學習。 + 然而若要從事大量文字編輯工作， + 那麼花點時間來學習這些好用的編輯器， + 會在日後為您省下更多的時間。</para> + </sect1> + + <sect1 xml:id="basics-devices"> + <title>設備及設備節點</title> + + <para>設備(device)主要是指跟硬體比較有關的術語， + 包括磁碟、印表機、顯示卡和鍵盤。 FreeBSD 開機過程當中， + 大多數硬體通常都能偵測到並顯示出來，也可以查閱 + <filename>/var/run/dmesg.boot</filename> 內有開機的相關訊息。</para> + + <para>舉例來說，<filename>acd0</filename>即為第一台 IDE 光碟機的代號， + 而 <filename>kbd0</filename> 則代表鍵盤。</para> + + <para>在 &unix; 作業系統， + 大部分的設備都是透過叫做 device nodes(設備節點)的特殊檔案來作存取， + 而這些檔案都位於 <filename>/dev</filename> 目錄。</para> + + <sect2> + <title>建立設備節點</title> + <para>若要在系統上建立新節點，或者是要編譯某些新硬體的支援軟體， + 那麼就要先新增設備節點。</para> + + <sect3> + <title><literal>DEVFS</literal> (DEVice File System)</title> + + <para>設備檔案系統(或稱為 <literal>DEVFS</literal>) 是指在整體檔案系統 + namespace 提供 kernel 的設備 namespace。 <literal>DEVFS</literal> + 乃是維護這些檔案系統，而不能新增或修改這些設備節點。</para> + + <para>細節請參閱 &man.devfs.5; 說明。</para> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="binary-formats"> + <title>Binary 的格式</title> + + <para>若要知道為何 &os; 是採用 &man.elf.5; 格式，必先瞭解當前 &unix; + 系統中三種<quote>影響最為重大</quote>的可執行檔相關背景：</para> + + <itemizedlist> + <listitem> + <para>&man.a.out.5;</para> + + <para>最古老、<quote>經典</quote> 的 &unix; object 檔格式。 + It uses a short and compact header with a magic + number at the beginning that is often used to characterize + the format (see &man.a.out.5; for more details). It + contains three loaded segments: .text, .data, and .bss plus + a symbol table and a string table.</para> + </listitem> + + <listitem> + <para><acronym>COFF</acronym></para> + + <para>The SVR3 object format. The header now comprises a + section table, so you can have more than just .text, .data, + and .bss sections.</para> + </listitem> + + <listitem> + <para>&man.elf.5;</para> + + <para>The successor to <acronym>COFF</acronym>, featuring + multiple sections and 32-bit or 64-bit possible values. One + major drawback: <acronym>ELF</acronym> was also designed + with the assumption that there would be only one ABI per + system architecture. That assumption is actually quite + incorrect, and not even in the commercial SYSV world (which + has at least three ABIs: SVR4, Solaris, SCO) does it hold + true.</para> + + <para>FreeBSD tries to work around this problem somewhat by + providing a utility for <emphasis>branding</emphasis> a + known <acronym>ELF</acronym> executable with information + about the ABI it is compliant with. See the manual page for + &man.brandelf.1; for more information.</para> + </listitem> + </itemizedlist> + + <para>FreeBSD comes from the <quote>classic</quote> camp and used + the &man.a.out.5; format, a technology tried and proven through + many generations of BSD releases, until the beginning of the 3.X + branch. Though it was possible to build and run native + <acronym>ELF</acronym> binaries (and kernels) on a FreeBSD + system for some time before that, FreeBSD initially resisted the + <quote>push</quote> to switch to <acronym>ELF</acronym> as the + default format. Why? Well, when the Linux camp made their + painful transition to <acronym>ELF</acronym>, it was not so much + to flee the <filename>a.out</filename> executable format as it + was their inflexible jump-table based shared library mechanism, + which made the construction of shared libraries very difficult + for vendors and developers alike. Since the + <acronym>ELF</acronym> tools available offered a solution to the + shared library problem and were generally seen as <quote>the way + forward</quote> anyway, the migration cost was accepted as + necessary and the transition made. FreeBSD's shared library + mechanism is based more closely on Sun's + &sunos; style shared library mechanism + and, as such, is very easy to use.</para> + + <para>So, why are there so many different formats?</para> + + <para>Back in the dim, dark past, there was simple hardware. This + simple hardware supported a simple, small system. <filename>a.out</filename> was + completely adequate for the job of representing binaries on this + simple system (a PDP-11). As people ported &unix; from this simple + system, they retained the <filename>a.out</filename> format because it was sufficient + for the early ports of &unix; to architectures like the Motorola + 68k, VAXen, etc.</para> + + <para>Then some bright hardware engineer decided that if he could + force software to do some sleazy tricks, then he would be able + to shave a few gates off the design and allow his CPU core to + run faster. While it was made to work with this new kind of + hardware (known these days as <acronym>RISC</acronym>), <filename>a.out</filename> + was ill-suited for this hardware, so many formats were developed + to get to a better performance from this hardware than the + limited, simple <filename>a.out</filename> format could + offer. Things like <acronym>COFF</acronym>, + <acronym>ECOFF</acronym>, and a few obscure others were invented + and their limitations explored before things seemed to settle on + <acronym>ELF</acronym>.</para> + + <para>In addition, program sizes were getting huge and disks (and + physical memory) were still relatively small so the concept of a + shared library was born. The VM system also became more + sophisticated. While each one of these advancements was done + using the <filename>a.out</filename> format, its usefulness was + stretched more and more with each new feature. In addition, + people wanted to dynamically load things at run time, or to junk + parts of their program after the init code had run to save in + core memory and swap space. Languages became more sophisticated + and people wanted code called before main automatically. Lots of + hacks were done to the <filename>a.out</filename> format to + allow all of these things to happen, and they basically worked + for a time. In time, <filename>a.out</filename> was not up to + handling all these problems without an ever increasing overhead + in code and complexity. While <acronym>ELF</acronym> solved many + of these problems, it would be painful to switch from the system + that basically worked. So <acronym>ELF</acronym> had to wait + until it was more painful to remain with + <filename>a.out</filename> than it was to migrate to + <acronym>ELF</acronym>.</para> + + <para>However, as time passed, the build tools that FreeBSD + derived their build tools from (the assembler and loader + especially) evolved in two parallel trees. The FreeBSD tree + added shared libraries and fixed some bugs. The GNU folks that + originally wrote these programs rewrote them and added simpler + support for building cross compilers, plugging in different + formats at will, and so on. Since many people wanted to build cross + compilers targeting FreeBSD, they were out of luck since the + older sources that FreeBSD had for <application>as</application> and <application>ld</application> were not up to the + task. The new GNU tools chain (<application>binutils</application>) does support cross + compiling, <acronym>ELF</acronym>, shared libraries, C++ + extensions, etc. In addition, many vendors are releasing + <acronym>ELF</acronym> binaries, and it is a good thing for + FreeBSD to run them.</para> + + <para><acronym>ELF</acronym> is more expressive than <filename>a.out</filename> and + allows more extensibility in the base system. The + <acronym>ELF</acronym> tools are better maintained, and offer + cross compilation support, which is important to many people. + <acronym>ELF</acronym> may be a little slower than <filename>a.out</filename>, but + trying to measure it can be difficult. There are also numerous + details that are different between the two in how they map + pages, handle init code, etc. None of these are very important, + but they are differences. In time support for + <filename>a.out</filename> will be moved out of the <filename>GENERIC</filename> + kernel, and eventually removed from the kernel once the need to + run legacy <filename>a.out</filename> programs is past.</para> + </sect1> + + <sect1 xml:id="basics-more-information"> + <title>更多資訊</title> + + <sect2 xml:id="basics-man"> + <title>Manual 線上說明</title> + <indexterm><primary>manual pages</primary></indexterm> + + <para>在使用 FreeBSD 時，最詳細的使用說明莫過於 man 線上說明。 + 幾乎各程式都會有附上簡短說明，以介紹該程式的基本功能跟相關參數用法。 + 可以透過 <command>man</command> 指令來閱讀這些說明，而 + <command>man</command> 指令的使用相當簡單易懂：</para> + + <screen>&prompt.user; <userinput>man command</userinput></screen> + + <para><literal>command</literal> 處就是想要知道的指令。 舉個例子， + 若要知道 <command>ls</command> 的詳細用法，就可以打：</para> + + <screen>&prompt.user; <userinput>man ls</userinput></screen> + + <para>而各線上說明因為性質不同，而區分為下列的數字章節：</para> + + <orderedlist> + <listitem> + <para>使用者指令。</para> + </listitem> + + <listitem> + <para>系統呼叫(System call) 及錯誤代號。</para> + </listitem> + + <listitem> + <para>C 語言函式庫。</para> + </listitem> + + <listitem> + <para>各設備的驅動程式。</para> + </listitem> + + <listitem> + <para>檔案格式。</para> + </listitem> + + <listitem> + <para>小遊戲程式及其他娛樂程式。</para> + </listitem> + + <listitem> + <para>雜項工具、其他資訊。</para> + </listitem> + + <listitem> + <para>系統維護、操作的指令。</para> + </listitem> + + <listitem> + <para>Kernel 開發用途。</para> + </listitem> + </orderedlist> + + <para>有些情況會有同樣主題但不同章節。 舉個例子，系統內會有 + <command>chmod</command> 指令，但也有 <function>chmod()</function> + 系統呼叫。 在這種情況，<command>man</command> + 應該要指定所要查詢的章節：</para> + + <screen>&prompt.user; <userinput>man 1 chmod</userinput></screen> + + <para>如此一來就會查 <command>chmod</command> 指令部分。 + 通常在寫文件時會把有參考到某特定章節的 man 號碼也一併寫在括號內。 + 所以 &man.chmod.1; 就是指 <command>chmod</command> 指令，而 + &man.chmod.2; 則是指系統呼叫的部分。</para> + + <para>如果您已經知道命令的名稱，只是不知道要怎樣使用的話，那就比較好辦。 + 但若不知道要用哪個指令時，該怎麼辦呢？ 這個時候，就可以利用 + <command>man</command> 的搜尋關鍵字功能， + 以在各說明的介紹部分搜尋相關字眼。，它的選項是 <option>-k</option>： + </para> + + <screen>&prompt.user; <userinput>man -k mail</userinput></screen> + + <para>如此一來會看到一堆有 <quote>mail</quote> 關鍵字的說明， + 事實上該功能與 <command>apropos</command> 指令是一樣的。</para> + + <para>而有時你會看到像是 <filename>/usr/bin</filename> + 有許多看起來頗炫的指令，但不知其用途？ 只要簡單輸入：</para> + + <screen>&prompt.user; <userinput>cd /usr/bin</userinput> +&prompt.user; <userinput>man -f *</userinput></screen> + + <para>或者是</para> + + <screen>&prompt.user; <userinput>cd /usr/bin</userinput> +&prompt.user; <userinput>whatis *</userinput></screen> + + <para>這兩者的指令效果是一樣的。</para> + </sect2> + + <sect2 xml:id="basics-info"> + <title>GNU Info 檔案</title> + <indexterm><primary>Free Software Foundation</primary></indexterm> + + <para>FreeBSD 有許多程式跟工具來自於自由軟體基金會(FSF)。 除了 man + 線上說明之外，這些程式提供了另外一種更具有彈性的 hypertext 格式文件， + 叫做 <literal>info</literal>。 可以用 <command>info</command> + 指令來閱讀，或者若有裝 <application>emacs</application> 亦可透過 + <application>emacs</application> 的 info 模式閱讀。</para> + + <para>要用 &man.info.1; 指令，只需打：</para> + + <screen>&prompt.user; <userinput>info</userinput></screen> + + <para>按 <literal>h</literal> 會有簡單說明，而若要快速查閱相關操作方式， + 則請按 <literal>?</literal>。</para> + </sect2> + </sect1> +</chapter> diff --git a/zh_TW.UTF-8/books/handbook/basics/example-dir1.dot b/zh_TW.UTF-8/books/handbook/basics/example-dir1.dot new file mode 100644 index 0000000000..f259e8377d --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/basics/example-dir1.dot @@ -0,0 +1,7 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/"; +} diff --git a/zh_TW.UTF-8/books/handbook/basics/example-dir2.dot b/zh_TW.UTF-8/books/handbook/basics/example-dir2.dot new file mode 100644 index 0000000000..b846c82399 --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/basics/example-dir2.dot @@ -0,0 +1,8 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/" -> "B1/"; + "A1/" -> "B2/"; + root -> "A2/"; +} diff --git a/zh_TW.UTF-8/books/handbook/basics/example-dir3.dot b/zh_TW.UTF-8/books/handbook/basics/example-dir3.dot new file mode 100644 index 0000000000..178a3a91bb --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/basics/example-dir3.dot @@ -0,0 +1,8 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/" -> "B1/"; + "A2/" -> "B2/"; +} diff --git a/zh_TW.UTF-8/books/handbook/basics/example-dir4.dot b/zh_TW.UTF-8/books/handbook/basics/example-dir4.dot new file mode 100644 index 0000000000..82d12b421a --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/basics/example-dir4.dot @@ -0,0 +1,9 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/" -> "B1/" -> "C1/"; + "B1/" -> "C2/"; + "A2/" -> "B2/"; +} diff --git a/zh_TW.UTF-8/books/handbook/basics/example-dir5.dot b/zh_TW.UTF-8/books/handbook/basics/example-dir5.dot new file mode 100644 index 0000000000..f5aa6e01dc --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/basics/example-dir5.dot @@ -0,0 +1,9 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/" -> "C1/"; + "A1/" -> "C2/"; + root -> "A2/" -> "B1/"; + "A2/" -> "B2/"; +} diff --git a/zh_TW.UTF-8/books/handbook/bibliography/Makefile b/zh_TW.UTF-8/books/handbook/bibliography/Makefile new file mode 100644 index 0000000000..e1ac7fd2e2 --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/bibliography/Makefile @@ -0,0 +1,16 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# Original revision: 1.1 +# + +CHAPTERS= bibliography/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/zh_TW.UTF-8/books/handbook/bibliography/chapter.xml b/zh_TW.UTF-8/books/handbook/bibliography/chapter.xml new file mode 100644 index 0000000000..2cbfa7068a --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/bibliography/chapter.xml @@ -0,0 +1,630 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ + Original revision: 1.85 +--> +<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="bibliography"> + <title>參考文獻</title> + + <para>雖然線上說明(manual pages)有提供 &os; 各個特定部分明確的說明， + 但它們卻難免有「小學而大遺」之憾，像是如何讓整個系統運作順暢。 因此， + 身邊有 &unix; 系統管理的好書以及好的使用手冊是不可或缺的。</para> + + <sect1 xml:id="bibliography-freebsd"> + <title>FreeBSD 相關的書籍、雜誌</title> + + <para><emphasis>非英語的書籍、雜誌：</emphasis></para> + + <itemizedlist> + <listitem> + <para><link xlink:href="http://jdli.tw.FreeBSD.org/publication/book/freebsd2/index.htm">FreeBSD 入門與應用(光碟豪華版)</link> (繁體中文)， + <link xlink:href="http://www.drmaster.com.tw/">博碩文化</link> + ，1997。 ISBN 9-578-39435-7</para> + </listitem> + + <listitem> + <para>FreeBSD 技術內幕 (FreeBSD Unleashed 簡體中譯版)， + <link xlink:href="http://www.hzbook.com/">機械工業出版社</link> + 。 ISBN 7-111-10201-0 + </para> + </listitem> + + <listitem> + <para>FreeBSD 使用大全第一版 (簡體中文)， + 機械工業出版社。 ISBN 7-111-07482-3 + </para> + </listitem> + + <listitem> + <para>FreeBSD 使用大全第二版 (簡體中文)， + 機械工業出版社。 ISBN 7-111-10286-X + </para> + </listitem> + + <listitem> + <para>FreeBSD Handbook 第二版 (簡體中譯版)， + <link xlink:href="http://www.ptpress.com.cn/">人民郵電出版社</link> + 。 ISBN 7-115-10541-3 + </para> + </listitem> + + <listitem> + <para>FreeBSD 3.x Internet 高級服務器的架設與管理 (簡體中文)， + <link xlink:href="http://www.tup.tsinghua.edu.cn/">清華大學出版社</link> + 。 ISBN 7-900625-66-6</para> + </listitem> + + <listitem> + <para>FreeBSD & Windows 集成組網實務 (簡體中文)， + <link xlink:href="http://www.tdpress.com/">中國鐵道出版社</link> + 。 ISBN 7-113-03845-X</para> + </listitem> + + <listitem> + <para>FreeBSD 網站架設實務 (簡體中文)，中國鐵道出版社 + 。 ISBN 7-113-03423-3</para> + </listitem> + + <listitem> + <para>FreeBSD for PC 98'ers (日文)，SHUWA SystemCo, LTD + 。 ISBN 4-87966-468-5 C3055 定價 2900 日圓。</para> + </listitem> + + <listitem> + <para>FreeBSD (日文)，CUTT。 ISBN 4-906391-22-2 + C3055 定價 2400 日圓。</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.shoeisha.com/book/Detail.asp?bid=650">Complete Introduction to FreeBSD</link> (日文)，<link xlink:href="http://www.shoeisha.co.jp/">Shoeisha Co., Ltd</link>。 ISBN 4-88135-473-6 定價 3600 日圓。</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.ascii.co.jp/pb/book1/shinkan/detail/1322785.html">Personal UNIX Starter Kit FreeBSD</link> (日文)， <link xlink:href="http://www.ascii.co.jp/">ASCII</link>。 ISBN 4-7561-1733-3 定價 3000 日圓。</para> + </listitem> + + <listitem> + <para>FreeBSD Handbook (日文譯版)， <link xlink:href="http://www.ascii.co.jp/">ASCII</link>。 ISBN 4-7561-1580-2 + 定價 3800 日圓。</para> + </listitem> + + <listitem> + <para>FreeBSD mit Methode (德文)，<link xlink:href="http://www.cul.de">Computer und + Literatur Verlag</link>/Vertrieb Hanser，1998。 ISBN 3-932311-31-0</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.cul.de/freebsd.html">FreeBSD 4 - Installieren, Konfigurieren, Administrieren</link> + (德文)，<link xlink:href="http://www.cul.de">Computer und Literatur Verlag</link>，2001。 + ISBN 3-932311-88-4</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.cul.de/freebsd.html">FreeBSD 5 - Installieren, Konfigurieren, Administrieren</link> + (德文)，<link xlink:href="http://www.cul.de">Computer und Literatur Verlag</link>，2003。 + ISBN 3-936546-06-1</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.mitp.de/vmi/mitp/detail/pWert/1343/"> + FreeBSD de Luxe</link> (德文)， + <link xlink:href="http://www.mitp.de">Verlag Modere Industrie</link>， + 2003。 ISBN 3-8266-1343-0</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.pc.mycom.co.jp/FreeBSD/install-manual.html">FreeBSD + Install and Utilization Manual</link> (日文)，<link xlink:href="http://www.pc.mycom.co.jp/">Mainichi Communications Inc.</link> + ，1998。 ISBN 4-8399-0112-0</para> + </listitem> + + <listitem> + <para>Onno W Purbo, Dodi Maryanto, Syahrial Hubbany, Widjil Widodo + <emphasis><link xlink:href="http://maxwell.itb.ac.id/"> + Building Internet Server with + FreeBSD</link></emphasis> (印尼文)，<link xlink:href="http://www.elexmedia.co.id/">Elex Media Komputindo</link>。</para> + </listitem> + + <listitem> + <para>FreeBSD 完全探索 (Absolute BSD: The Ultimate Guide to FreeBSD + 繁體中文譯版)，<link xlink:href="http://www.grandtech.com.tw/">上奇</link>，2003。 + ISBN 986-7944-92-5</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.twbsd.org/cht/book/">FreeBSD 6.0架設管理與應用</link> + (繁體中文)，博碩，2006。ISBN 9-575-27878-X</para> + </listitem> + + </itemizedlist> + + <para><emphasis>英文的書籍、雜誌：</emphasis></para> + + <itemizedlist> + <listitem> + <para><link xlink:href="http://www.AbsoluteBSD.com/">Absolute + BSD: The Ultimate Guide to FreeBSD</link>， + <link xlink:href="http://www.nostarch.com/">No Starch Press</link>，2002。 + ISBN: 1886411743</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.freebsdmall.com/cgi-bin/fm/bsdcomp"> + The Complete FreeBSD</link>， + <link xlink:href="http://www.oreilly.com/">O'Reilly</link>，2003。 + ISBN: 0596005164</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.freebsd-corp-net-guide.com/">The + FreeBSD Corporate Networker's Guide</link>， + <link xlink:href="http://www.awl.com/aw/">Addison-Wesley</link>，2000。 + ISBN: 0201704811</para> + </listitem> + + <listitem> + <para><link xlink:href="http://andrsn.stanford.edu/FreeBSD/introbook/"> + FreeBSD: An Open-Source Operating System for Your Personal + Computer</link>，The Bit Tree Press，2001。 + ISBN: 0971204500</para> + </listitem> + + <listitem> + <para>Teach Yourself FreeBSD in 24 Hours， + <link xlink:href="http://www.samspublishing.com/">Sams</link>，2002。 + ISBN: 0672324245</para> + </listitem> + + <listitem> + <para>FreeBSD 6 Unleashed， + <link xlink:href="http://www.samspublishing.com/">Sams</link>，2006。 + ISBN: 0672328755</para> + </listitem> + + <listitem> + <para>FreeBSD: The Complete Reference， + <link xlink:href="http://books.mcgraw-hill.com">McGrawHill</link>，2003。 + ISBN: 0072224096 </para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1 xml:id="bibliography-userguides"> + <title>使用說明手冊</title> + + <itemizedlist> + <listitem> + <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD + User's Reference Manual</emphasis>. O'Reilly & Associates, + Inc., 1994. ISBN 1-56592-075-9</para> + </listitem> + + <listitem> + <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD + User's Supplementary Documents</emphasis>. O'Reilly & + Associates, Inc., 1994. ISBN 1-56592-076-7</para> + </listitem> + + <listitem> + <para><emphasis>UNIX in a Nutshell</emphasis>. O'Reilly & + Associates, Inc., 1990. ISBN 093717520X</para> + </listitem> + + <listitem> + <para>Mui, Linda. <emphasis>What You Need To Know When You Can't Find + Your UNIX System Administrator</emphasis>. O'Reilly & + Associates, Inc., 1995. ISBN 1-56592-104-6</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.osu.edu/">Ohio State University</link> + 有撰寫 <link xlink:href="http://8help.osu.edu/wks/unix_course/index.html">UNIX + 介紹的課程</link>，並提供 HTML 或 PostScript 兩種格式供人瀏覽。 + </para> + + <para>UNIX 介紹的<link xlink:href="&url.doc.base;/it_IT.ISO8859-15/books/unix-introduction/index.html">義大利文翻譯版</link> + ，同時本文件也是 FreeBSD Italian Documentation Project 之一。</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.jp.FreeBSD.org/">Jpman Project, Japan + FreeBSD Users Group</link>. <link xlink:href="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD User's + Reference Manual</link> (日文翻譯)。 <link xlink:href="http://www.pc.mycom.co.jp/">Mainichi Communications + Inc.</link>, 1998. ISBN4-8399-0088-4 P3800E.</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.ed.ac.uk/">Edinburgh + University</link> 為 UNIX 新手所撰寫的 <link xlink:href="http://unixhelp.ed.ac.uk/">Online Guide</link> 指引說明。</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="bibliography-adminguides"> + <title>系統管理指南</title> + + <itemizedlist> + <listitem> + <para>Albitz, Paul and Liu, Cricket. <emphasis>DNS and + BIND</emphasis>, 4th Ed. O'Reilly & Associates, Inc., 2001. + ISBN 1-59600-158-4</para> + </listitem> + + <listitem> + <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD + System Manager's Manual</emphasis>. O'Reilly & Associates, + Inc., 1994. ISBN 1-56592-080-5</para> + </listitem> + + <listitem> + <para>Costales, Brian, et al. <emphasis>Sendmail</emphasis>, 2nd Ed. + O'Reilly & Associates, Inc., 1997. ISBN 1-56592-222-0</para> + </listitem> + + <listitem> + <para>Frisch, Æleen. <emphasis>Essential System + Administration</emphasis>, 2nd Ed. O'Reilly & Associates, + Inc., 1995. ISBN 1-56592-127-5</para> + </listitem> + + <listitem> + <para>Hunt, Craig. <emphasis>TCP/IP Network + Administration</emphasis>, 2nd Ed. O'Reilly & Associates, Inc., + 1997. ISBN 1-56592-322-7</para> + </listitem> + + <listitem> + <para>Nemeth, Evi. <emphasis>UNIX System Administration + Handbook</emphasis>. 3rd Ed. Prentice Hall, 2000. ISBN + 0-13-020601-6</para> + </listitem> + + <listitem> + <para>Stern, Hal <emphasis>Managing NFS and NIS</emphasis> O'Reilly + & Associates, Inc., 1991. ISBN 0-937175-75-7</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.jp.FreeBSD.org/">Jpman Project, Japan + FreeBSD Users Group</link>. <link xlink:href="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD System + Administrator's Manual</link> (日文翻譯)。 <link xlink:href="http://www.pc.mycom.co.jp/">Mainichi Communications + Inc.</link>, 1998. ISBN4-8399-0109-0 P3300E.</para> + </listitem> + + <listitem> + <para>Dreyfus, Emmanuel. <link xlink:href="http://www.eyrolles.com/Informatique/Livre/9782212114638/">Cahiers + de l'Admin: BSD</link> 2nd Ed. (法文), Eyrolles, 2004. + ISBN 2-212-11463-X</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="bibliography-programmers"> + <title>程式設計師指南</title> + + <itemizedlist> + <listitem> + <para>Asente, Paul, Converse, Diana, and Swick, Ralph. + <emphasis>X Window System Toolkit</emphasis>. Digital Press, + 1998. ISBN 1-55558-178-1</para> + </listitem> + + <listitem> + <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD + Programmer's Reference Manual</emphasis>. O'Reilly & + Associates, Inc., 1994. ISBN 1-56592-078-3</para> + </listitem> + + <listitem> + <para>Computer Systems Research Group, UC Berkeley. <emphasis>4.4BSD + Programmer's Supplementary Documents</emphasis>. O'Reilly & + Associates, Inc., 1994. ISBN 1-56592-079-1</para> + </listitem> + + <listitem> + <para>Harbison, Samuel P. and Steele, Guy L. Jr. <emphasis>C: A + Reference Manual</emphasis>. 4th ed. Prentice Hall, 1995. + ISBN 0-13-326224-3</para> + </listitem> + + <listitem> + <para>Kernighan, Brian and Dennis M. Ritchie. <emphasis>The C + Programming Language</emphasis>. 2nd Ed. PTR Prentice Hall, 1988. + ISBN 0-13-110362-8</para> + </listitem> + + <listitem> + <para>Lehey, Greg. <emphasis>Porting UNIX Software</emphasis>. + O'Reilly & Associates, Inc., 1995. ISBN 1-56592-126-7</para> + </listitem> + + <listitem> + <para>Plauger, P. J. <emphasis>The Standard C Library</emphasis>. + Prentice Hall, 1992. ISBN 0-13-131509-9</para> + </listitem> + + <listitem> + <para>Spinellis, Diomidis. <link xlink:href="http://www.spinellis.gr/codereading/"><emphasis>Code + Reading: The Open Source Perspective</emphasis></link>. + Addison-Wesley, 2003. ISBN 0-201-79940-5</para> + </listitem> + + <listitem> + <para>Spinellis, Diomidis. <link xlink:href="http://www.spinellis.gr/codequality/"><emphasis>Code + Quality: The Open Source Perspective</emphasis></link>. + Addison-Wesley, 2006. ISBN 0-321-16607-8</para> + </listitem> + + <listitem> + <para>Stevens, W. Richard and Stephen A. Rago. + <emphasis>Advanced Programming in the UNIX + Environment</emphasis>. 2nd Ed. + Reading, Mass. : Addison-Wesley, 2005. + ISBN 0-201-43307-9</para> + </listitem> + + <listitem> + <para>Stevens, W. Richard. <emphasis>UNIX Network + Programming</emphasis>. 2nd Ed, PTR Prentice Hall, 1998. ISBN + 0-13-490012-X</para> + </listitem> + + <listitem> + <para>Wells, Bill. <quote>Writing Serial Drivers for UNIX</quote>. + <emphasis>Dr. Dobb's Journal</emphasis>. 19(15), December 1994. + pp68-71, 97-99.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="bibliography-osinternals"> + <title>深入作業系統</title> + + <itemizedlist> + <listitem> + <para>Andleigh, Prabhat K. <emphasis>UNIX System + Architecture</emphasis>. Prentice-Hall, Inc., 1990. ISBN + 0-13-949843-5</para> + </listitem> + + <listitem> + <para>Jolitz, William. <quote>Porting UNIX to the 386</quote>. + <emphasis>Dr. Dobb's Journal</emphasis>. January 1991-July + 1992.</para> + </listitem> + + <listitem> + <para>Leffler, Samuel J., Marshall Kirk McKusick, Michael J Karels and + John Quarterman <emphasis>The Design and Implementation of the + 4.3BSD UNIX Operating System</emphasis>. Reading, Mass. : + Addison-Wesley, 1989. ISBN 0-201-06196-1</para> + </listitem> + + <listitem> + <para>Leffler, Samuel J., Marshall Kirk McKusick, <emphasis>The Design + and Implementation of the 4.3BSD UNIX Operating System: Answer + Book</emphasis>. Reading, Mass. : Addison-Wesley, 1991. ISBN + 0-201-54629-9</para> + </listitem> + + <listitem> + <para>McKusick, Marshall Kirk, Keith Bostic, Michael J Karels, and + John Quarterman. <emphasis>The Design and Implementation of the + 4.4BSD Operating System</emphasis>. Reading, Mass. : + Addison-Wesley, 1996. ISBN 0-201-54979-4</para> + + <para>(本書第二章的 <link xlink:href="&url.books.design-44bsd;/book.html">網路版</link> 是 + FreeBSD 文件計劃的一部份，以及第九章的部分可以在 <link xlink:href="http://www.netapp.com/tech_library/nfsbook.html"> + 這邊</link>找到)</para> + </listitem> + + <listitem> + <para>Marshall Kirk McKusick, George V. Neville-Neil <emphasis>The + Design and Implementation of the FreeBSD Operating System</emphasis>. + Boston, Mass. : Addison-Wesley, 2004. ISBN 0-201-70245-2</para> + </listitem> + + <listitem> + <para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 1: + The Protocols</emphasis>. Reading, Mass. : Addison-Wesley, + 1996. ISBN 0-201-63346-9</para> + </listitem> + + <listitem> + <para>Schimmel, Curt. <emphasis>Unix Systems for Modern + Architectures</emphasis>. Reading, Mass. : Addison-Wesley, 1994. + ISBN 0-201-63338-8</para> + </listitem> + + <listitem> + <para>Stevens, W. Richard. <emphasis>TCP/IP Illustrated, Volume 3: + TCP for Transactions, HTTP, NNTP and the UNIX Domain + Protocols</emphasis>. Reading, Mass. : Addison-Wesley, 1996. + ISBN 0-201-63495-3</para> + </listitem> + + <listitem> + <para>Vahalia, Uresh. <emphasis>UNIX Internals -- The New + Frontiers</emphasis>. Prentice Hall, 1996. ISBN + 0-13-101908-2</para> + </listitem> + + <listitem> + <para>Wright, Gary R. and W. Richard Stevens. <emphasis>TCP/IP + Illustrated, Volume 2: The Implementation</emphasis>. Reading, + Mass. : Addison-Wesley, 1995. ISBN 0-201-63354-X</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="bibliography-security"> + <title>資安領域的參考文獻</title> + + <itemizedlist> + <listitem> + <para>Cheswick, William R. and Steven M. Bellovin. <emphasis>Firewalls + and Internet Security: Repelling the Wily Hacker</emphasis>. + Reading, Mass. : Addison-Wesley, 1995. ISBN + 0-201-63357-4</para> + </listitem> + + <listitem> + <para>Garfinkel, Simson and Gene Spafford. + <emphasis>Practical UNIX & Internet Security</emphasis>. + 2nd Ed. O'Reilly & Associates, Inc., 1996. ISBN + 1-56592-148-8</para> + </listitem> + + <listitem> + <para>Garfinkel, Simson. <emphasis>PGP Pretty Good + Privacy</emphasis> O'Reilly & Associates, Inc., 1995. ISBN + 1-56592-098-8</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="bibliography-hardware"> + <title>硬體方面的參考文獻</title> + + <itemizedlist> + <listitem> + <para>Anderson, Don and Tom Shanley. <emphasis>Pentium Processor + System Architecture</emphasis>. 2nd Ed. Reading, Mass. : + Addison-Wesley, 1995. ISBN 0-201-40992-5</para> + </listitem> + + <listitem> + <para>Ferraro, Richard F. <emphasis>Programmer's Guide to the EGA, + VGA, and Super VGA Cards</emphasis>. 3rd ed. Reading, Mass. : + Addison-Wesley, 1995. ISBN 0-201-62490-7</para> + </listitem> + + <listitem> + <para>Intel Corporation 通常會以 PDF 格式在 <link xlink:href="http://developer.intel.com/">developer web site</link> + 網站放他們的 CPU、晶片組、相關標準的規格書文件。</para> + </listitem> + + <listitem> + <para>Shanley, Tom. <emphasis>80486 System Architecture</emphasis>. + 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN + 0-201-40994-1</para> + </listitem> + + <listitem> + <para>Shanley, Tom. <emphasis>ISA System Architecture</emphasis>. + 3rd ed. Reading, Mass. : Addison-Wesley, 1995. ISBN + 0-201-40996-8</para> + </listitem> + + <listitem> + <para>Shanley, Tom. <emphasis>PCI System Architecture</emphasis>. + 4th ed. Reading, Mass. : Addison-Wesley, 1999. ISBN + 0-201-30974-2</para> + </listitem> + + <listitem> + <para>Van Gilluwe, Frank. <emphasis>The Undocumented PC</emphasis>, + 2nd Ed. Reading, Mass: Addison-Wesley Pub. Co., 1996. ISBN + 0-201-47950-8</para> + </listitem> + + <listitem> + <para>Messmer, Hans-Peter. <emphasis>The Indispensable PC Hardware + Book</emphasis>, 4th Ed. + Reading, Mass: Addison-Wesley Pub. Co., 2002. ISBN + 0-201-59616-4</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1 xml:id="bibliography-history"> + <title>&unix; 歷史淵源</title> + + <itemizedlist> + <listitem> + <para>Lion, John <emphasis>Lion's Commentary on UNIX, 6th Ed. With + Source Code</emphasis>. ITP Media Group, 1996. ISBN + 1573980137</para> + </listitem> + + <listitem> + <para>Raymond, Eric S. <emphasis>The New Hacker's Dictionary, 3rd + edition</emphasis>. MIT Press, 1996. ISBN + 0-262-68092-0. Also known as the <link xlink:href="http://www.catb.org/~esr/jargon/html/index.html">Jargon + File</link></para> + </listitem> + + <listitem> + <para>Salus, Peter H. <emphasis>A quarter century of UNIX</emphasis>. + Addison-Wesley Publishing Company, Inc., 1994. ISBN + 0-201-54777-5</para> + </listitem> + + <listitem> + <para>Simon Garfinkel, Daniel Weise, Steven Strassmann. <emphasis>The + UNIX-HATERS Handbook</emphasis>. IDG Books Worldwide, Inc., + 1994. ISBN 1-56884-203-1. Out of print, but available <link xlink:href="http://research.microsoft.com/~daniel/unix-haters.html"> + online</link>.</para> + </listitem> + + <listitem> + <para>Don Libes, Sandy Ressler <emphasis>Life with UNIX</emphasis> + — special edition. Prentice-Hall, Inc., 1989. ISBN + 0-13-536657-7</para> + </listitem> + + <listitem> + <para><emphasis>BSD 族譜</emphasis>： + <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/share/misc/bsd-family-tree">http://www.FreeBSD.org/cgi/cvsweb.cgi/src/share/misc/bsd-family-tree</uri> + 或 FreeBSD 機器內的 <link xlink:href="file://localhost/usr/share/misc/bsd-family-tree"><filename>/usr/share/misc/bsd-family-tree</filename></link> + 。</para> + </listitem> + + <listitem> + <para><emphasis>The BSD Release Announcements collection</emphasis>. + 1997. <uri xlink:href="http://www.de.FreeBSD.org/de/ftp/releases/">http://www.de.FreeBSD.org/de/ftp/releases/</uri></para> + </listitem> + + <listitem> + <para><emphasis>Networked Computer Science Technical Reports + Library</emphasis>. <uri xlink:href="http://www.ncstrl.org/">http://www.ncstrl.org/</uri></para> + </listitem> + + <listitem> + <para><emphasis>Old BSD releases from the Computer Systems Research + group (CSRG)</emphasis>. + <uri xlink:href="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</uri>: + The 4CD set covers all BSD versions from 1BSD to 4.4BSD and + 4.4BSD-Lite2 (but not 2.11BSD, unfortunately). The last + disk also holds the final sources plus the SCCS files.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="bibliography-journals"> + <title>雜誌、期刊</title> + + <itemizedlist> + <listitem> + <para><emphasis>The C/C++ Users Journal</emphasis>. R&D + Publications Inc. ISSN 1075-2838</para> + </listitem> + + <listitem> + <para><emphasis>Sys Admin — The Journal for UNIX System + Administrators</emphasis> Miller Freeman, Inc., ISSN + 1061-2688</para> + </listitem> + + <listitem> + <para><emphasis>freeX — Das Magazin für Linux - BSD - UNIX</emphasis> + (德文) Computer- und Literaturverlag GmbH, ISSN 1436-7033</para> + </listitem> + + </itemizedlist> + </sect1> +</appendix> diff --git a/zh_TW.UTF-8/books/handbook/book.xml b/zh_TW.UTF-8/books/handbook/book.xml new file mode 100644 index 0000000000..b6fa191bcf --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/book.xml @@ -0,0 +1,274 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd" [ +<!ENTITY % chapters SYSTEM "chapters.ent"> +%chapters; +<!ENTITY % txtfiles SYSTEM "txtfiles.ent"> +%txtfiles; +]> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ + Original revision: 1.163 +--> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="zh_TW"> + <info><title>FreeBSD 使用手冊</title> + + + <author><orgname>FreeBSD 文件計畫</orgname></author> + + <pubdate>February 1999</pubdate> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <copyright> + <year>1995</year> + <year>1996</year> + <year>1997</year> + <year>1998</year> + <year>1999</year> + <year>2000</year> + <year>2001</year> + <year>2002</year> + <year>2003</year> + <year>2004</year> + <year>2005</year> + <year>2006</year> + <year>2007</year> + <year>2008</year> + <holder>FreeBSD 文件計畫</holder> + </copyright> + + &legalnotice; + + <legalnotice xml:id="trademarks" role="trademarks"> + &tm-attrib.freebsd; + &tm-attrib.3com; + &tm-attrib.3ware; + &tm-attrib.arm; + &tm-attrib.adaptec; + &tm-attrib.adobe; + &tm-attrib.apple; + &tm-attrib.corel; + &tm-attrib.creative; + &tm-attrib.cvsup; + &tm-attrib.heidelberger; + &tm-attrib.ibm; + &tm-attrib.ieee; + &tm-attrib.intel; + &tm-attrib.intuit; + &tm-attrib.linux; + &tm-attrib.lsilogic; + &tm-attrib.m-systems; + &tm-attrib.macromedia; + &tm-attrib.microsoft; + &tm-attrib.netscape; + &tm-attrib.nexthop; + &tm-attrib.opengroup; + &tm-attrib.oracle; + &tm-attrib.powerquest; + &tm-attrib.realnetworks; + &tm-attrib.redhat; + &tm-attrib.sap; + &tm-attrib.sun; + &tm-attrib.symantec; + &tm-attrib.themathworks; + &tm-attrib.thomson; + &tm-attrib.usrobotics; + &tm-attrib.vmware; + &tm-attrib.waterloomaple; + &tm-attrib.wolframresearch; + &tm-attrib.xfree86; + &tm-attrib.xiph; + &tm-attrib.general; + </legalnotice> + + <abstract> + <para>歡迎使用FreeBSD！ 本使用手冊涵蓋範圍包括了 + <emphasis>FreeBSD &rel2.current;-RELEASE</emphasis> 和 + <emphasis>FreeBSD &rel.current;-RELEASE</emphasis> 的安裝和日常使用。 + 這份使用手冊是很多人的集體創作，而且仍然『持續不斷』的進行中。 + 許多章節仍未完成，已完成的部份也有些需要更新。 + 如果您有興趣協助本計畫的話，請寄 e-mail 到 &a.doc;。 + 在 <link xlink:href="http://www.FreeBSD.org/">FreeBSD 網站</link> + 可以找到這份文件的最新版本(舊版文件可從 <uri xlink:href="http://docs.FreeBSD.org/doc/">http://docs.FreeBSD.org/doc/</uri> 取得)，也可以從 <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP 伺服器</link> + 或是眾多 <link linkend="mirrors-ftp">mirror 站臺</link> + 下載不同格式的資料。 + 如果比較偏好實體書面資料，那可以在 + <link xlink:href="http://www.freebsdmall.com/">FreeBSD Mall</link> 購買。 + 此外，也可以在 <link xlink:href="&url.base;/search/index.html">使用手冊</link> + 中搜尋資料。 + </para> + </abstract> + </info> + + &chap.preface; + + <part xml:id="getting-started"> + <title>開始使用 FreeBSD </title> + + <partintro> + <para>這部份是提供給初次使用 FreeBSD 的使用者和系統管理者。 + 這些章節包括：</para> + + <itemizedlist> + <listitem> + <para>介紹 FreeBSD 給您。 </para> + </listitem> + + <listitem> + <para>在安裝過程給您指引。 </para> + </listitem> + + <listitem> + <para>教您 &unix; 的基礎及原理。 </para> + </listitem> + + <listitem> + <para>展示給您看如何安裝豐富的 FreeBSD 的應用軟體</para> + </listitem> + + <listitem> + <para>向您介紹 X， &unix; 的視窗系統以及詳細的桌面環境設定，讓您更有生產力。 + </para> + </listitem> + </itemizedlist> + + <para>我們試著儘可能的讓這段文字的參考連結數目降到最低，讓您在讀使用手冊的這部份時可以不太需要常常前後翻頁。 + </para> + </partintro> + + &chap.introduction; + &chap.install; + &chap.basics; + &chap.ports; + &chap.x11; + </part> + + <part xml:id="common-tasks"> + <title>一般性工作</title> + + <partintro> + <para>既然基礎的部分已經提過了，接下來的這個部分將會討論一些常會用到的 FreeBSD + 的特色，這些章節包括：</para> + + <itemizedlist> + <listitem> + <para>介紹給您常見且實用的桌面應用軟體：網頁瀏覽器、生產力工具、文件檢視程式等。</para> + </listitem> + + <listitem> + <para>介紹給您眾多 FreeBSD 上可用的多媒體工具。</para> + </listitem> + + <listitem> + <para>解釋如何編譯自訂 FreeBSD 核心以增加額外系統功能的流程。</para> + </listitem> + + <listitem> + <para>詳細描述列印系統，包含桌上型印表機及網路印表機的設定。</para> + </listitem> + + <listitem> + <para>展示給您看如何在您的 FreeBSD 系統中執行 Linux 應用軟體。</para> + </listitem> + + </itemizedlist> + + <para>這些章節中有些需要您預先閱讀些相關文件，在各章節開頭的概要內會提及。</para> + + </partintro> + + &chap.desktop; + &chap.multimedia; + &chap.kernelconfig; + &chap.printing; + &chap.linuxemu; + </part> + + <part xml:id="system-administration"> + <title>系統管理</title> + + <partintro> + <para>FreeBSD 使用手冊剩下的這些章節涵蓋了全方位的 FreeBSD 系統管理。 + 每個章節的開頭會先描述在該您讀完該章節後您會學到什麼，也會詳述在您在看這些資料時應該要有的一些背景知識。 + </para> + + <para>這些章節是讓您在需要查資料的時候翻閱用的。 + 您不需要依照特定的順序來讀，也不需要將這些章節全部過讀之後才開始用 FreeBSD。 + </para> + </partintro> + + &chap.config; + &chap.boot; + &chap.users; + &chap.security; + &chap.jails; + &chap.mac; + &chap.audit; + &chap.disks; + &chap.geom; + &chap.vinum; + &chap.virtualization; + &chap.l10n; + &chap.cutting-edge; + </part> + + <part xml:id="network-communication"> + <title>網路通訊</title> + + <partintro> + <para>FreeBSD 是一種廣泛的被使用在高效能的網路伺服器中的作業系統，這些章節包含了：</para> + + <itemizedlist> + <listitem> + <para>序列埠通訊</para> + </listitem> + + <listitem> + <para>PPP 和 PPPoE</para> + </listitem> + + <listitem> + <para>電子郵件</para> + </listitem> + + <listitem> + <para>執行網路伺服程式</para> + </listitem> + + <listitem> + <para>防火牆</para> + </listitem> + + <listitem> + <para>其他的進階網路主題</para> + </listitem> + </itemizedlist> + + <para>這些章節是讓您在需要查資料的時候翻閱用的。 + 您不需要依照特定的順序來讀，也不需要將這些章節全部讀過之後才將 FreeBSD 用在網路環境下。</para> + </partintro> + + &chap.serialcomms; + &chap.ppp-and-slip; + &chap.mail; + &chap.network-servers; + &chap.firewalls; + &chap.advanced-networking; + + </part> + + <part xml:id="appendices"> + <title>附錄</title> + + &chap.mirrors; + &chap.bibliography; + &chap.eresources; + &chap.pgpkeys; + </part> + &chap.freebsd-glossary; + &chap.index; + &chap.colophon; +</book> diff --git a/zh_TW.UTF-8/books/handbook/boot/Makefile b/zh_TW.UTF-8/books/handbook/boot/Makefile new file mode 100644 index 0000000000..c405bb50c6 --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/boot/Makefile @@ -0,0 +1,16 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# Original revision: 1.1 +# + +CHAPTERS= boot/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/zh_TW.UTF-8/books/handbook/boot/chapter.xml b/zh_TW.UTF-8/books/handbook/boot/chapter.xml new file mode 100644 index 0000000000..ae4ce38477 --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/boot/chapter.xml @@ -0,0 +1,802 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ + Original revision: 1.62 +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="boot"> + <title>FreeBSD 開機流程篇</title> + + <sect1 xml:id="boot-synopsis"> + <title>概述</title> + <indexterm><primary>booting</primary></indexterm> + <indexterm><primary>bootstrap</primary></indexterm> + + <para>The process of starting a computer and loading the operating system + is referred to as <quote>the bootstrap process</quote>, or simply + <quote>booting</quote>. FreeBSD's boot process provides a great deal of + flexibility in customizing what happens when you start the system, + allowing you to select from different operating systems installed on the + same computer, or even different versions of the same operating system + or installed kernel.</para> + + <para>This chapter details the configuration options you can set and how + to customize the FreeBSD boot process. This includes everything that + happens until the FreeBSD kernel has started, probed for devices, and + started &man.init.8;. If you are not quite sure when this happens, it + occurs when the text color changes from bright white to grey.</para> + + <para>讀完這章，您將了解：</para> + + <itemizedlist> + <listitem> + <para>What the components of the FreeBSD bootstrap system are, and how + they interact.</para> + </listitem> + + <listitem> + <para>The options you can give to the components in the FreeBSD + bootstrap to control the boot process.</para> + </listitem> + + <listitem> + <para>&man.device.hints.5; 的基本概念。</para> + </listitem> + </itemizedlist> + + <note> + <title>x86 Only</title> + + <para>This chapter only describes the boot process for FreeBSD running + on Intel x86 systems.</para> + </note> + </sect1> + + <sect1 xml:id="boot-introduction"> + <title>Booting 問題</title> + + <para>Turning on a computer and starting the operating system poses an + interesting dilemma. By definition, the computer does not know how to + do anything until the operating system is started. This includes + running programs from the disk. So if the computer can not run a + program from the disk without the operating system, and the operating + system programs are on the disk, how is the operating system + started?</para> + + <para>This problem parallels one in the book <citetitle>The Adventures of + Baron Munchausen</citetitle>. A character had fallen part way down a + manhole, and pulled himself out by grabbing his bootstraps, and + lifting. In the early days of computing the term + <firstterm>bootstrap</firstterm> was applied to the mechanism used to + load the operating system, which has become shortened to + <quote>booting</quote>.</para> + + <indexterm><primary>BIOS</primary></indexterm> + + <indexterm><primary>Basic Input/Output System</primary><see>BIOS</see></indexterm> + + <para>On x86 hardware the Basic Input/Output System (BIOS) is responsible + for loading the operating system. To do this, the BIOS looks on the + hard disk for the Master Boot Record (MBR), which must be located on a + specific place on the disk. The BIOS has enough knowledge to load and + run the MBR, and assumes that the MBR can then carry out the rest of the + tasks involved in loading the operating system, + possibly with the help of the BIOS.</para> + + <indexterm><primary>Master Boot Record (MBR)</primary></indexterm> + + <indexterm><primary>Boot Manager</primary></indexterm> + + <indexterm><primary>Boot Loader</primary></indexterm> + + <para>The code within the MBR is usually referred to as a <emphasis>boot + manager</emphasis>, especially when it interacts with the user. In this case + the boot manager usually has more code in the first + <emphasis>track</emphasis> of the disk or within some OS's file system. (A + boot manager is sometimes also called a <emphasis>boot loader</emphasis>, + but FreeBSD uses that term for a later stage of booting.) Popular boot + managers include <application>boot0</application> (a.k.a. <application>Boot + Easy</application>, the standard &os; boot manager), + <application>Grub</application>, <application>GAG</application>, and + <application>LILO</application>. + (Only <application>boot0</application> fits within the MBR.)</para> + + <para>If you have only one operating system installed on your disks then + a standard PC MBR will suffice. This MBR searches for the first bootable + (a.k.a. active) slice on the disk, and then runs the code on that slice to + load the remainder of the operating system. The MBR installed by + &man.fdisk.8;, by default, is such an MBR. It is based on + <filename>/boot/mbr</filename>.</para> + + <para>If you have installed multiple operating systems on your disks then + you can install a different boot manager, one that can display a list of + different operating systems, and allows you to choose the one to boot + from. Two of these are discussed in the next subsection.</para> + + <para>The remainder of the FreeBSD bootstrap system is divided into three + stages. The first stage is run by the MBR, which knows just enough to + get the computer into a specific state and run the second stage. The + second stage can do a little bit more, before running the third stage. + The third stage finishes the task of loading the operating system. The + work is split into these three stages because the PC standards put + limits on the size of the programs that can be run at stages one and + two. Chaining the tasks together allows FreeBSD to provide a more + flexible loader.</para> + + <indexterm><primary>kernel</primary></indexterm> + <indexterm><primary><command>init</command></primary></indexterm> + + <para>The kernel is then started and it begins to probe for devices + and initialize them for use. Once the kernel boot + process is finished, the kernel passes control to the user process + &man.init.8;, which then makes sure the disks are in a usable state. + &man.init.8; then starts the user-level resource configuration which + mounts file systems, sets up network cards to communicate on the + network, and generally starts all the processes that usually + are run on a FreeBSD system at startup.</para> + </sect1> + + <sect1 xml:id="boot-blocks"> + <title>The Boot Manager and Boot Stages</title> + + <indexterm><primary>Boot Manager</primary></indexterm> + + <sect2 xml:id="boot-boot0"> + <title>The Boot Manager</title> + <indexterm><primary>Master Boot Record (MBR)</primary></indexterm> + + <para>The code in the MBR or boot manager is sometimes referred to as + <emphasis>stage zero</emphasis> of the boot process. This subsection + discusses two of the boot managers previously mentioned: + <application>boot0</application> and <application>LILO</application>.</para> + + <formalpara><title>The <application>boot0</application> Boot Manager:</title> + <para>The MBR installed by FreeBSD's installer or &man.boot0cfg.8;, by + default, is based on <filename>/boot/boot0</filename>. + (The <application>boot0</application> program is very simple, since the + program in the <abbrev>MBR</abbrev> can only be 446 bytes long because of the slice + table and 0x55AA identifier at the end of the MBR.) + If you have installed <application>boot0</application> and + multiple operating systems on your hard disks, then you will see a + display similar to this one at boot time:</para></formalpara> + + <example xml:id="boot-boot0-example"> + <title><filename>boot0</filename> Screenshot</title> + + <screen>F1 DOS +F2 FreeBSD +F3 Linux +F4 ?? +F5 Drive 1 + +Default: F2</screen> + </example> + + <para>Other operating systems, in particular &windows;, have been known + to overwrite an existing MBR with their own. If this happens to you, + or you want to replace your existing MBR with the FreeBSD MBR then use + the following command:</para> + + <screen>&prompt.root; <userinput>fdisk -B -b /boot/boot0 device</userinput></screen> + + <para>where <replaceable>device</replaceable> is the device that you + boot from, such as <filename>ad0</filename> for the first IDE + disk, <filename>ad2</filename> for the first IDE disk on a second + IDE controller, <filename>da0</filename> for the first SCSI disk, + and so on. Or, if you want a custom configuration of the MBR, + use &man.boot0cfg.8;.</para> + + <formalpara><title>The LILO Boot Manager:</title> + + <para>To install this boot manager so it will also boot FreeBSD, first + start Linux and add the following to your existing + <filename>/etc/lilo.conf</filename> configuration file:</para></formalpara> + + <programlisting>other=/dev/hdXY +table=/dev/hdX +loader=/boot/chain.b +label=FreeBSD</programlisting> + + <para>In the above, specify FreeBSD's primary partition and drive using + Linux specifiers, replacing <replaceable>X</replaceable> with the Linux + drive letter and <replaceable>Y</replaceable> with the Linux primary + partition number. If you are using a <acronym>SCSI</acronym> drive, you + will need to change <replaceable>/dev/hd</replaceable> to read something + similar to <replaceable>/dev/sd</replaceable>. The + <option>loader=/boot/chain.b</option> line can be omitted if you have + both operating systems on the same drive. Now run + <command>/sbin/lilo -v</command> to commit your new changes to the + system; this should be verified by checking its screen messages.</para> + </sect2> + + <sect2 xml:id="boot-boot1"> + <title>Stage One, <filename>/boot/boot1</filename>, and Stage Two, + <filename>/boot/boot2</filename></title> + + <para>Conceptually the first and second stages are part of the same + program, on the same area of the disk. Because of space constraints + they have been split into two, but you would always install them + together. They are copied from the combined file + <filename>/boot/boot</filename> by the installer or + <application>disklabel</application> (see below).</para> + + <para>They are located outside file systems, in the first track of + the boot slice, starting with the first sector. This is where <link linkend="boot-boot0">boot0</link>, or any other boot manager, + expects to find a program to run which will + continue the boot process. The number of sectors used is easily + determined from the size of <filename>/boot/boot</filename>.</para> + + <para><filename>boot1</filename> is very simple, since it + can only be 512 bytes + in size, and knows just enough about the FreeBSD + <firstterm>disklabel</firstterm>, which stores information + about the slice, to find and execute <filename>boot2</filename>.</para> + + <para><filename>boot2</filename> is slightly more sophisticated, and understands + the FreeBSD file system enough to find files on it, and can + provide a simple interface to choose the kernel or loader to + run.</para> + + <para>Since the <link linkend="boot-loader">loader</link> is + much more sophisticated, and provides a nice easy-to-use + boot configuration, <filename>boot2</filename> usually runs + it, but previously it + was tasked to run the kernel directly.</para> + + <example xml:id="boot-boot2-example"> + <title><filename>boot2</filename> Screenshot</title> + + <screen>>> FreeBSD/i386 BOOT +Default: 0:ad(0,a)/kernel +boot:</screen> + </example> + + <para>If you ever need to replace the installed + <filename>boot1</filename> and <filename>boot2</filename> use + &man.disklabel.8;:</para> + + <screen>&prompt.root; <userinput>disklabel -B diskslice</userinput></screen> + + <para>where <replaceable>diskslice</replaceable> is the disk and slice + you boot from, such as <filename>ad0s1</filename> for the first + slice on the first IDE disk.</para> + + <warning> + <title>Dangerously Dedicated Mode</title> + + <para>If you use just the disk name, such as + <filename>ad0</filename>, in the &man.disklabel.8; command you + will create a dangerously dedicated disk, without slices. This is + almost certainly not what you want to do, so make sure you double + check the &man.disklabel.8; command before you press + <keycap>Return</keycap>.</para> + </warning> + </sect2> + + <sect2 xml:id="boot-loader"> + <title>Stage Three, <filename>/boot/loader</filename></title> + + <indexterm><primary>boot-loader</primary></indexterm> + <para>The loader is the final stage of the three-stage + bootstrap, and is located on the file system, usually as + <filename>/boot/loader</filename>.</para> + + <para>The loader is intended as a user-friendly method for + configuration, using an easy-to-use built-in command set, + backed up by a more powerful interpreter, with a more complex + command set.</para> + + <sect3 xml:id="boot-loader-flow"> + <title>Loader Program Flow</title> + + <para>During initialization, the loader will probe for a + console and for disks, and figure out what disk it is + booting from. It will set variables accordingly, and an + interpreter is started where user commands can be passed from + a script or interactively.</para> + <indexterm><primary>loader</primary></indexterm> + <indexterm><primary>loader configuration</primary></indexterm> + + <para>The loader will then read + <filename>/boot/loader.rc</filename>, which by default reads + in <filename>/boot/defaults/loader.conf</filename> which + sets reasonable defaults for variables and reads + <filename>/boot/loader.conf</filename> for local changes to + those variables. <filename>loader.rc</filename> then acts + on these variables, loading whichever modules and kernel are + selected.</para> + + <para>Finally, by default, the loader issues a 10 second wait + for key presses, and boots the kernel if it is not interrupted. + If interrupted, the user is presented with a prompt which + understands the easy-to-use command set, where the user may + adjust variables, unload all modules, load modules, and then + finally boot or reboot.</para> + + </sect3> + + <sect3 xml:id="boot-loader-commands"> + <title>Loader Built-In Commands</title> + + <para>These are the most commonly used loader commands. For a + complete discussion of all available commands, please see + &man.loader.8;.</para> + + <variablelist> + <varlistentry> + <term>autoboot <replaceable>seconds</replaceable></term> + + <listitem> + <para>Proceeds to boot the kernel if not interrupted + within the time span given, in seconds. It displays a + countdown, and the default time span is 10 + seconds.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>boot + <optional>-options</optional> + <optional>kernelname</optional></term> + + <listitem> + <para>Immediately proceeds to boot the kernel, with the + given options, if any, and with the kernel name given, + if it is.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>boot-conf</term> + + <listitem> + <para>Goes through the same automatic configuration of + modules based on variables as what happens at boot. + This only makes sense if you use + <command>unload</command> first, and change some + variables, most commonly <envar>kernel</envar>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>help + <optional>topic</optional></term> + + <listitem> + <para>Shows help messages read from + <filename>/boot/loader.help</filename>. If the topic + given is <literal>index</literal>, then the list of + available topics is given.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>include <replaceable>filename</replaceable> + …</term> + + <listitem> + <para>Processes the file with the given filename. The + file is read in, and interpreted line by line. An + error immediately stops the include command.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>load <optional>-t + type</optional> + <replaceable>filename</replaceable></term> + + <listitem> + <para>Loads the kernel, kernel module, or file of the + type given, with the filename given. Any arguments + after filename are passed to the file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>ls <optional>-l</optional> + <optional>path</optional></term> + + <listitem> + <para>Displays a listing of files in the given path, or + the root directory, if the path is not specified. If + <option>-l</option> is specified, file sizes will be + shown too.</para> + </listitem> + </varlistentry> + <varlistentry> + <term>lsdev <optional>-v</optional></term> + + <listitem> + <para>Lists all of the devices from which it may be + possible to load modules. If <option>-v</option> is + specified, more details are printed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>lsmod <optional>-v</optional></term> + + <listitem> + <para>Displays loaded modules. If <option>-v</option> is + specified, more details are shown.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>more <replaceable>filename</replaceable></term> + + <listitem> + <para>Displays the files specified, with a pause at each + <varname>LINES</varname> displayed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>reboot</term> + + <listitem> + <para>Immediately reboots the system.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>set <replaceable>variable</replaceable></term> + <term>set + <replaceable>variable</replaceable>=<replaceable>value</replaceable></term> + + <listitem> + <para>Sets the loader's environment variables.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>unload</term> + + <listitem> + <para>Removes all loaded modules.</para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 xml:id="boot-loader-examples"> + <title>Loader Examples</title> + + <para>Here are some practical examples of loader usage:</para> + + <itemizedlist> + <listitem> + <para>To simply boot your usual kernel, but in single-user + mode:<indexterm><primary>single-user mode</primary></indexterm></para> + + <screen><userinput>boot -s</userinput></screen> + </listitem> + + <listitem> + <para>To unload your usual kernel and modules, and then + load just your old (or another) kernel:</para> + + <screen><userinput>unload</userinput> +<userinput>load kernel.old</userinput></screen> + + <para>You can use <filename>kernel.GENERIC</filename> to + refer to the generic kernel that comes on the install + disk, or <filename>kernel.old</filename><indexterm><primary><filename>kernel.old</filename></primary></indexterm> to refer to + your previously installed kernel (when you have upgraded + or configured your own kernel, for example).</para> + + <note> + <para>Use the following to load your usual modules with + another kernel:</para> + + <screen><userinput>unload</userinput> +<userinput>set kernel="kernel.old"</userinput> +<userinput>boot-conf</userinput></screen></note> + </listitem> + + <listitem> + <para>To load a kernel configuration script (an automated + script which does the things you would normally do in the + kernel boot-time configurator):</para> + + <screen><userinput>load -t userconfig_script /boot/kernel.conf</userinput></screen> + </listitem> + </itemizedlist> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="boot-kernel"> + <title>Kernel Interaction During Boot</title> + <indexterm> + <primary>kernel</primary> + <secondary>boot interaction</secondary> + </indexterm> + + <para>Once the kernel is loaded by either <link linkend="boot-loader">loader</link> (as usual) or <link linkend="boot-boot1">boot2</link> (bypassing the loader), it + examines its boot flags, if any, and adjusts its behavior as + necessary.</para> + + <sect2 xml:id="boot-kernel-bootflags"> + <title>Kernel Boot Flags</title> + + <indexterm> + <primary>kernel</primary> + <secondary>bootflags</secondary> + </indexterm> + + <para>Here are the more common boot flags:</para> + + <variablelist xml:id="boot-kernel-bootflags-list"> + <varlistentry> + <term><option>-a</option></term> + + <listitem> + <para>during kernel initialization, ask for the device + to mount as the root file system.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-C</option></term> + + <listitem> + <para>boot from CDROM.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-c</option></term> + + <listitem> + <para>run UserConfig, the boot-time kernel + configurator</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-s</option></term> + + <listitem> + <para>boot into single-user mode</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-v</option></term> + + <listitem> + <para>be more verbose during kernel startup</para> + </listitem> + </varlistentry> + </variablelist> + + <note> + <para>There are other boot flags, read &man.boot.8; for more + information on them.</para></note> + </sect2> + +<!-- <sect2 id="boot-kernel-userconfig"> + <title>UserConfig: the Boot-time Kernel Configurator</title> + + <para> </para> + </sect2> --> + </sect1> + + <sect1 xml:id="device-hints"> + <info><title>Device Hints</title> + <authorgroup> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + + </info> + + + + <indexterm> + <primary>device.hints</primary> + </indexterm> + + <note><para>This is a FreeBSD 5.0 and later feature which does not + exist in earlier versions.</para></note> + + <para>During initial system startup, the boot &man.loader.8; will read the + &man.device.hints.5; file. This file stores kernel boot information + known as variables, sometimes referred to as <quote>device hints</quote>. + These <quote>device hints</quote> are used by device drivers for device + configuration.</para> + + <para>Device hints may also be specified at the <link linkend="boot-loader"> + Stage 3 boot loader</link> prompt. Variables can be added using + <command>set</command>, removed with <command>unset</command>, and viewed + with the <command>show</command> commands. Variables set in the + <filename>/boot/device.hints</filename> file can be overridden here also. Device hints entered at + the boot loader are not permanent and will be forgotten on the next + reboot.</para> + + <para>Once the system is booted, the &man.kenv.1; command can be used to + dump all of the variables.</para> + + <para>The syntax for the <filename>/boot/device.hints</filename> file is one variable per line, using + the standard hash <quote>#</quote> as comment markers. Lines are + constructed as follows:</para> + + <screen><userinput>hint.driver.unit.keyword="value"</userinput></screen> + + <para>The syntax for the Stage 3 boot loader is:</para> + <screen><userinput>set hint.driver.unit.keyword=value</userinput></screen> + + <para><literal>driver</literal> is the device driver name, <literal>unit</literal> + is the device driver unit number, and <literal>keyword</literal> is the hint + keyword. The keyword may consist of the following options:</para> + + <itemizedlist> + <listitem> + <para><literal>at</literal>: specifies the bus which the device is attached to.</para> + </listitem> + + <listitem> + <para><literal>port</literal>: specifies the start address of the <acronym>I/O</acronym> + to be used.</para> + </listitem> + + <listitem> + <para><literal>irq</literal>: specifies the interrupt request number to be used.</para> + </listitem> + + <listitem> + <para><literal>drq</literal>: specifies the DMA channel number.</para> + </listitem> + + <listitem> + <para><literal>maddr</literal>: specifies the physical memory address occupied by the + device.</para> + </listitem> + + <listitem> + <para><literal>flags</literal>: sets various flag bits for the device.</para> + </listitem> + + <listitem> + <para><literal>disabled</literal>: if set to <literal>1</literal> the device is disabled.</para> + </listitem> + </itemizedlist> + + <para>Device drivers may accept (or require) more hints not listed here, viewing + their manual page is recommended. For more information, consult the + &man.device.hints.5;, &man.kenv.1;, &man.loader.conf.5;, and &man.loader.8; + manual pages.</para> + </sect1> + + <sect1 xml:id="boot-init"> + <title>Init: Process Control Initialization</title> + + <indexterm> + <primary><command>init</command></primary> + </indexterm> + + <para>Once the kernel has finished booting, it passes control to + the user process &man.init.8;, which is located at + <filename>/sbin/init</filename>, or the program path specified + in the <envar>init_path</envar> variable in + <command>loader</command>.</para> + + <sect2 xml:id="boot-autoreboot"> + <title>Automatic Reboot Sequence</title> + + <para>The automatic reboot sequence makes sure that the + file systems available on the system are consistent. If they + are not, and &man.fsck.8; cannot fix the + inconsistencies, &man.init.8; drops the system + into <link linkend="boot-singleuser">single-user mode</link> + for the system administrator to take care of the problems + directly.</para> + </sect2> + + <sect2 xml:id="boot-singleuser"> + <title>Single-User Mode</title> + <indexterm><primary>single-user mode</primary></indexterm> + <indexterm><primary>console</primary></indexterm> + + <para>This mode can be reached through the <link linkend="boot-autoreboot">automatic reboot + sequence</link>, or by the user booting with the + <option>-s</option> option or setting the + <envar>boot_single</envar> variable in + <command>loader</command>.</para> + + <para>It can also be reached by calling + &man.shutdown.8; without the reboot + (<option>-r</option>) or halt (<option>-h</option>) options, + from <link linkend="boot-multiuser">multi-user + mode</link>.</para> + + <para>If the system <literal>console</literal> is set + to <literal>insecure</literal> in <filename>/etc/ttys</filename>, + then the system prompts for the <systemitem class="username">root</systemitem> password + before initiating single-user mode.</para> + + <example xml:id="boot-insecure-console"> + <title>An Insecure Console in <filename>/etc/ttys</filename></title> + + <programlisting># name getty type status comments +# +# If console is marked "insecure", then init will ask for the root password +# when going to single-user mode. +console none unknown off insecure</programlisting> + </example> + + <note> + <para>An <literal>insecure</literal> console means that you + consider your physical security to the console to be + insecure, and want to make sure only someone who knows the + <systemitem class="username">root</systemitem> password may use single-user mode, and it + does not mean that you want to run your console insecurely. Thus, + if you want security, choose <literal>insecure</literal>, + not <literal>secure</literal>.</para> + </note> + </sect2> + + <sect2 xml:id="boot-multiuser"> + <title>Multi-User Mode</title> + <indexterm><primary>multi-user mode</primary></indexterm> + + <para>If &man.init.8; finds your file systems to be + in order, or once the user has finished in <link linkend="boot-singleuser">single-user mode</link>, the + system enters multi-user mode, in which it starts the + resource configuration of the system.</para> + + <sect3 xml:id="boot-rc"> + <title>Resource Configuration (rc)</title> + + <indexterm><primary>rc files</primary></indexterm> + + <para>The resource configuration system reads in + configuration defaults from + <filename>/etc/defaults/rc.conf</filename>, and + system-specific details from + <filename>/etc/rc.conf</filename>, and then proceeds to + mount the system file systems mentioned in + <filename>/etc/fstab</filename>, start up networking + services, start up miscellaneous system daemons, and + finally runs the startup scripts of locally installed + packages.</para> + + <para>The &man.rc.8; manual page is a good reference to the resource + configuration system, as is examining the scripts + themselves.</para> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="boot-shutdown"> + <title>Shutdown Sequence</title> + <indexterm> + <primary><command>shutdown</command></primary> + </indexterm> + + <para>Upon controlled shutdown, via &man.shutdown.8;, + &man.init.8; will attempt to run the script + <filename>/etc/rc.shutdown</filename>, and then proceed to send + all processes the <literal>TERM</literal> signal, and subsequently + the <literal>KILL</literal> signal to any that do not terminate + timely.</para> + + <para>To power down a FreeBSD machine on architectures and systems + that support power management, simply use the command + <command>shutdown -p now</command> to turn the power off + immediately. To just reboot a FreeBSD system, just use + <command>shutdown -r now</command>. You need to be + <systemitem class="username">root</systemitem> or a member of + <systemitem class="groupname">operator</systemitem> group to run &man.shutdown.8;. + The &man.halt.8; and &man.reboot.8; commands can also be used, + please refer to their manual pages and to &man.shutdown.8;'s one + for more information.</para> + + <note> + <para>Power management requires &man.acpi.4; support in the kernel + or loaded as module for FreeBSD 5.X and &man.apm.4; + support for FreeBSD 4.X.</para> + </note> + + </sect1> +</chapter> diff --git a/zh_TW.UTF-8/books/handbook/chapters.ent b/zh_TW.UTF-8/books/handbook/chapters.ent new file mode 100644 index 0000000000..fc0c4577d0 --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/chapters.ent @@ -0,0 +1,71 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + Creates entities for each chapter in the FreeBSD Handbook. Each entity + is named chap.foo, where foo is the value of the id attribute on that + chapter, and corresponds to the name of the directory in which that + chapter's .xml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $FreeBSD$ + Original revision: 1.33 +--> + +<!ENTITY chap.preface SYSTEM "preface/preface.xml"> +<!ENTITY % pgpkeys SYSTEM "../../../share/pgpkeys/pgpkeys.ent"> %pgpkeys; + +<!-- Part One --> + <!ENTITY chap.introduction SYSTEM "introduction/chapter.xml"> + <!ENTITY chap.install SYSTEM "install/chapter.xml"> + <!ENTITY chap.basics SYSTEM "basics/chapter.xml"> + <!ENTITY chap.ports SYSTEM "ports/chapter.xml"> + <!ENTITY chap.x11 SYSTEM "x11/chapter.xml"> + +<!-- Part Two --> + <!ENTITY chap.desktop SYSTEM "desktop/chapter.xml"> + <!ENTITY chap.multimedia SYSTEM "multimedia/chapter.xml"> + <!ENTITY chap.kernelconfig SYSTEM "kernelconfig/chapter.xml"> + <!ENTITY chap.printing SYSTEM "printing/chapter.xml"> + <!ENTITY chap.linuxemu SYSTEM "linuxemu/chapter.xml"> + +<!-- Part Three --> + <!ENTITY chap.config SYSTEM "config/chapter.xml"> + <!ENTITY chap.boot SYSTEM "boot/chapter.xml"> + <!ENTITY chap.users SYSTEM "users/chapter.xml"> + <!ENTITY chap.security SYSTEM "security/chapter.xml"> + <!ENTITY chap.jails SYSTEM "jails/chapter.xml"> + <!ENTITY chap.mac SYSTEM "mac/chapter.xml"> + <!ENTITY chap.audit SYSTEM "audit/chapter.xml"> + <!ENTITY chap.disks SYSTEM "disks/chapter.xml"> + <!ENTITY chap.geom SYSTEM "geom/chapter.xml"> + <!ENTITY chap.filesystems SYSTEM "filesystems/chapter.xml"> + <!ENTITY chap.vinum SYSTEM "vinum/chapter.xml"> + <!ENTITY chap.virtualization SYSTEM "virtualization/chapter.xml"> + <!ENTITY chap.l10n SYSTEM "l10n/chapter.xml"> + <!ENTITY chap.cutting-edge SYSTEM "cutting-edge/chapter.xml"> + <!ENTITY chap.dtrace SYSTEM "dtrace/chapter.xml"> + +<!-- Part Four --> + <!ENTITY chap.serialcomms SYSTEM "serialcomms/chapter.xml"> + <!ENTITY chap.ppp-and-slip SYSTEM "ppp-and-slip/chapter.xml"> + <!ENTITY chap.mail SYSTEM "mail/chapter.xml"> + <!ENTITY chap.network-servers SYSTEM "network-servers/chapter.xml"> + <!ENTITY chap.firewalls SYSTEM "firewalls/chapter.xml"> + <!ENTITY chap.advanced-networking SYSTEM "advanced-networking/chapter.xml"> + +<!-- Part Five (appendices) --> + <!ENTITY chap.mirrors SYSTEM "mirrors/chapter.xml"> + <!ENTITY chap.mirrors.lastmod.inc SYSTEM "mirrors.lastmod.inc"> + <!ENTITY chap.mirrors.ftp.index.inc SYSTEM "mirrors.xml.ftp.index.inc"> + <!ENTITY chap.mirrors.ftp.inc SYSTEM "mirrors.xml.ftp.inc"> + <!ENTITY chap.mirrors.cvsup.index.inc SYSTEM "mirrors.xml.cvsup.index.inc"> + <!ENTITY chap.mirrors.cvsup.inc SYSTEM "mirrors.xml.cvsup.inc"> + <!ENTITY chap.bibliography SYSTEM "bibliography/chapter.xml"> + <!ENTITY chap.eresources SYSTEM "eresources/chapter.xml"> + <!ENTITY chap.eresources.www.index.inc SYSTEM "eresources.xml.www.index.inc"> + <!ENTITY chap.eresources.www.inc SYSTEM "eresources.xml.www.inc"> + <!ENTITY chap.pgpkeys SYSTEM "pgpkeys/chapter.xml"> + <!ENTITY chap.freebsd-glossary SYSTEM "../../share/xml/glossary.ent"> + <!ENTITY chap.index "<index xmlns='http://docbook.org/ns/docbook'/>"> + +<!ENTITY chap.colophon SYSTEM "colophon.xml"> diff --git a/zh_TW.UTF-8/books/handbook/colophon.xml b/zh_TW.UTF-8/books/handbook/colophon.xml new file mode 100644 index 0000000000..0ded28baa5 --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/colophon.xml @@ -0,0 +1,21 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<colophon xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="colophon"> + <para>This book is the combined work of hundreds of contributors to + <quote>The FreeBSD Documentation Project</quote>. The text is + authored in SGML + according to the DocBook DTD and is formatted from SGML into many + different presentation formats using <application>Jade</application>, + an open source DSSSL + engine. Norm Walsh's DSSSL stylesheets were used with an + additional customization layer to provide the presentation + instructions for <application>Jade</application>. The printed + version of this document would not be possible without Donald + Knuth's &tex; typesetting language, + Leslie Lamport's <application>LaTeX</application>, or Sebastian + Rahtz's <application>JadeTeX</application> macro package.</para> +</colophon> diff --git a/zh_TW.UTF-8/books/handbook/config/Makefile b/zh_TW.UTF-8/books/handbook/config/Makefile new file mode 100644 index 0000000000..2d81feca5e --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/config/Makefile @@ -0,0 +1,16 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# Original revision: 1.1 +# + +CHAPTERS= config/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/zh_TW.UTF-8/books/handbook/config/chapter.xml b/zh_TW.UTF-8/books/handbook/config/chapter.xml new file mode 100644 index 0000000000..07b0409d8b --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/config/chapter.xml @@ -0,0 +1,3095 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ + Original revision: 1.213 + Chased revision: 1.221 +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="config-tuning"> + <info><title>設定與效能調校(Tuning)</title> + <authorgroup> + <author><personname><firstname>Chern</firstname><surname>Lee</surname></personname><contrib>Written by </contrib></author> + </authorgroup> + <authorgroup> + <author><personname><firstname>Mike</firstname><surname>Smith</surname></personname><contrib>Based on a tutorial written by </contrib></author> + </authorgroup> + <authorgroup> + <author><personname><firstname>Matt</firstname><surname>Dillon</surname></personname><contrib>Also based on tuning(7) written by </contrib></author> + </authorgroup> + </info> + + + + <sect1 xml:id="config-synopsis"> + <title>概述</title> + + <indexterm><primary>system configuration</primary></indexterm> + <indexterm><primary>system optimization</primary></indexterm> + + <para>在 &os; 使用過程中，相當重要的環節之一就是系統設定部分。 + 正確的系統設定，可以讓你減輕日後升級的頭痛壓力。 + 本章著重於介紹 &os; 的相關重要設定上，包括一些可以調整 &os; 效能的參數設定。 + </para> + + <para>讀完這章，您將了解：</para> + + <itemizedlist> + <listitem> + <para>如何有效運用檔案系統以及 swap 分割區。</para> + </listitem> + <listitem> + <para><filename>rc.conf</filename> 的設定與 <filename>/usr/local/etc/rc.d</filename> 的啟動架構。</para> + </listitem> + <listitem> + <para>如何設定、測試網路卡。</para> + </listitem> + <listitem> + <para>如何設定 virtual hosts。</para> + </listitem> + <listitem> + <para>如何設定 <filename>/etc</filename> 內的各種設定檔。</para> + </listitem> + <listitem> + <para>如何以 <command>sysctl</command> 來調整 &os; 的系統效能。</para> + </listitem> + <listitem> + <para>如何調整硬碟效能，以及更改 kernel 限制。</para> + </listitem> + </itemizedlist> + + <para>在開始閱讀這章之前，您需要︰</para> + + <itemizedlist> + <listitem> + <para>瞭解 &unix; 及 &os; 相關基本概念(<xref linkend="basics"/>)。</para> + </listitem> + <listitem> + <para>要有設定、編譯 kernel 的基礎概念(<xref linkend="kernelconfig"/>)。</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="configtuning-initial"> + <title>一開始的規劃</title> + + <sect2> + <title>規劃分割區(Partition)</title> + + <indexterm><primary>partition layout</primary></indexterm> + <indexterm> + <primary><filename>/etc</filename></primary> + </indexterm> + <indexterm> + <primary><filename>/var</filename></primary> + </indexterm> + <indexterm> + <primary><filename>/usr</filename></primary> + </indexterm> + + <sect3> + <title>Base Partitions</title> + + <para>用 &man.bsdlabel.8; 或 &man.sysinstall.8; 來規劃檔案系統時，請記住： + 硬碟在傳輸資料方面，(由於結構為碟片因素)外圈會比內圈來得快些。 + 因此，建議把較小、常會存取的分割區儘量放外圈，而較大的分割區像是 + <filename>/usr</filename> 則應放在較內圈。 + 建議建立分割區的順序，以像是：root, swap, + <filename>/var</filename>, <filename>/usr</filename> 這樣順序來建立會較妥。</para> + + <para><filename>/var</filename> 的大小要視機器的用途而定。 + <filename>/var</filename> 是用來放 + 信箱、log 紀錄檔以及印表機佇列(spools)。 信箱以及記錄檔的成長幅度可能無法預估， + 因為這些成長幅度乃是取決於多少用戶、要放多久等管理原則而定。 + 通常這些使用者並沒有用到 1 GB 以上，但請切記：至少要保留一定空間給 <filename>/var/tmp</filename> + 以便存放 packages。 + </para> + + <para>而 <filename>/usr</filename> 分割區主要是用來放系統運作時所需的檔案、工具程式等，例如： + &man.ports.7; collection(建議安裝)跟 source tree(optional)。 + 在安裝 FreeBSD 時，這兩者都是可選擇裝與不裝的。 + 不過，這個分割區建議至少要有 2 GB 空間以上才夠用。</para> + + <para>規劃分割區大小時，記得多保留些成長空間。 + 否則若某個分割區滿了，但另一個分割區卻還剩很多空間，就會相當困窘。</para> + + <note><para>有些人可能會發現 &man.sysinstall.8; 的 + <literal>Auto-defaults(自動預設值)</literal> 所做的分割區大小， + 有時候會把 <filename>/var</filename> 以及 <filename>/</filename> 分割區設太小了。 + 我們建議是：請依使用情況以及需求，來手動調整相關分割區大小。</para></note> + + </sect3> + + <sect3 xml:id="swap-design"> + <title>Swap 分割區</title> + + <indexterm><primary>swap sizing</primary></indexterm> + <indexterm><primary>swap partition</primary></indexterm> + + <para>根據經驗法則，通常 swap 分割區應該設為系統記憶體(RAM)大小的兩倍即可。 + 舉例來說：若機器有 128 MB RAM 的話，那麼 + swap 則應該設為 256 MB。 記憶體較少的機器，可以透過增加更多 swap 空間來提昇效能。 + 我們建議 swap 空間不要設低於 256 MB，而且該考慮增加記憶體才是良策。 + 當 swap 最少為記憶體的兩倍大時，kernel 的 VM paging 演算法會把效能調整到最佳狀態。 + 但若是機器記憶體很大，但 swap 卻劃分太少的話，會導致 VM page 掃瞄的效率過低， + 此外日後若增加更多記憶體時，也會導致一些異常狀況發生。</para> + + <para>在較大型的機器內，通常會有多顆 SCSI 磁碟(或多顆 IDE 磁碟接在不同 IDE 匯流排上)， + 建議在每顆磁碟上都建立 swap(最多到四顆)。 + 而這些 swap 應該都大約一樣大小， + Kernel 可接受任意大小的 swap，但內部資料結構則是最大塊 swap 的 4 倍。 + 若有保持 swap 為同樣大小的話，則可讓 kernel 最佳化運用各磁碟之中的 swap 空間。 + 即使不太常會用到，分配大的 swap 也都還可接受， + 因為它可在強制重開機之前讓你更容易從當掉的程式中恢復正常。</para> + </sect3> + + <sect3> + <title>為何要規劃 Partition？</title> + + <para>有些人覺得把硬碟就直接劃分一個大分割區就好了， + 但是事實上有些原因會證明為何這是個爛點子， + 首先，每個分割區都有不同的運作特性，把它們分開的話可以讓檔案系統來調整。 + 比如： <filename>/</filename> 以及 <filename>/usr</filename> 分割區大多只是讀取而已， + 比較少在寫入。 而讀寫都很頻繁的則是 <filename>/var</filename> 及 + <filename>/var/tmp</filename>。</para> + + <para>By properly partitioning a system, fragmentation + introduced in the smaller write heavy partitions + will not bleed over into the mostly-read partitions. + Keeping the write-loaded partitions closer to + the disk's edge, + will + increase I/O performance in the partitions where it occurs + the most. Now while I/O + performance in the larger partitions may be needed, + shifting them more toward the edge of the disk will not + lead to a significant performance improvement over moving + <filename>/var</filename> to the edge. + Finally, there are safety concerns. A smaller, neater root + partition which is mostly read-only has a greater + chance of surviving a bad crash.</para> + </sect3> + </sect2> + + </sect1> + + <sect1 xml:id="configtuning-core-configuration"> + <title>最主要的設定檔</title> + + <indexterm> + <primary>rc files</primary> + <secondary><filename>rc.conf</filename></secondary> + </indexterm> + + <para>The principal location for system configuration information + is within <filename>/etc/rc.conf</filename>. This file + contains a wide range of configuration information, principally + used at system startup to configure the system. Its name + directly implies this; it is configuration information for the + <filename>rc*</filename> files.</para> + + <para>An administrator should make entries in the + <filename>rc.conf</filename> file to + override the default settings from + <filename>/etc/defaults/rc.conf</filename>. The defaults file + should not be copied verbatim to <filename>/etc</filename> - it + contains default values, not examples. All system-specific + changes should be made in the <filename>rc.conf</filename> + file itself.</para> + + <para>A number of strategies may be applied in clustered + applications to separate site-wide configuration from + system-specific configuration in order to keep administration + overhead down. The recommended approach is to place site-wide + configuration into another file, + such as <filename>/etc/rc.conf.site</filename>, and then include + this file into <filename>/etc/rc.conf</filename>, which will + contain only system-specific information.</para> + + <para>As <filename>rc.conf</filename> is read by &man.sh.1; it is + trivial to achieve this. For example:</para> + + <itemizedlist> + <listitem><para>rc.conf:</para> +<programlisting> . /etc/rc.conf.site + hostname="node15.example.com" + network_interfaces="fxp0 lo0" + ifconfig_fxp0="inet 10.1.1.1"</programlisting></listitem> + <listitem><para>rc.conf.site:</para> +<programlisting> defaultrouter="10.1.1.254" + saver="daemon" + blanktime="100"</programlisting></listitem> + </itemizedlist> + + <para>The <filename>rc.conf.site</filename> file can then be + distributed to every system using <command>rsync</command> or a + similar program, while the <filename>rc.conf</filename> file + remains unique.</para> + + <para>Upgrading the system using &man.sysinstall.8; + or <command>make world</command> will not overwrite the + <filename>rc.conf</filename> + file, so system configuration information will not be lost.</para> + + </sect1> + + <sect1 xml:id="configtuning-appconfig"> + <title>各式應用程式的設定檔</title> + + <para>原則上，安裝的軟體都會有其自有的設定檔，也會有自己的格式及語法。 + 因此，將其與系統分開獨立是件非常重要的事情。如此一來，套件管理工具將可以 + 很輕易的找出這些設定檔並管理這些設定檔。</para> + + <indexterm><primary>/usr/local/etc</primary></indexterm> + + <para>原則上，設定檔會被放置在 <filename>/usr/local/etc</filename>。 + 若某軟體的設定檔為數眾多，那將會其下建立一個目錄以供放置</para> + + <para>通常，當一個 port 或 package 被安裝的同時，一些基本的設定範例 + 也會一併被安裝至此。這些範例通常會被用 <filename>.default</filename> 做為副檔名。 + 若安裝時沒有自行撰寫的軟體設定檔，那麼將會複製一份 <filename>.default</filename> 設定 + 做為預設設定檔</para> + + <para>舉個例子，我們來看看 <filename>/usr/local/etc/apache</filename>：</para> + +<literallayout class="monospaced">-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf +-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf.default +-rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf +-rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf.default +-rw-r--r-- 1 root wheel 12205 May 20 1998 magic +-rw-r--r-- 1 root wheel 12205 May 20 1998 magic.default +-rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types +-rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types.default +-rw-r--r-- 1 root wheel 7980 May 20 1998 srm.conf +-rw-r--r-- 1 root wheel 7933 May 20 1998 srm.conf.default</literallayout> + + <para><filename>srm.conf</filename> 的檔案被修改過了，爾後 <application>Apache</application> 的更新 + 將不會對這個已修改過的設定檔做任何變動。</para> + + </sect1> + + <sect1 xml:id="configtuning-starting-services"> + <info><title>各種 Services 的啟動方式</title> + <authorgroup> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + + <indexterm><primary>services</primary></indexterm> + + <para>Many users choose to install third party software on &os; + from the Ports Collection. In many of these situations it + may be necessary to configure the software in a manner which + will allow it to be started upon system initialization. Services, + such as <package>mail/postfix</package> or + <package>www/apache13</package> are just two + of the many software packages which may be started during system + initialization. This section explains the procedures available + for starting third party software.</para> + + <para>In &os;, most included services, such as &man.cron.8;, are + started through the system start up scripts. These scripts may + differ depending on &os; or vendor version; however, the most + important aspect to consider is that their start up configuration + can be handled through simple startup scripts.</para> + + <para>Before the advent of <filename>rc.d</filename>, applications would drop a + simple start up script into the + <filename>/usr/local/etc/rc.d</filename> + directory which would be read by the system initialization + scripts. These scripts would then be executed during the latter + stages of system start up.</para> + + <para>While many individuals have spent hours trying to merge the + old configuration style into the new system, the fact remains + that some third party utilities still require a script simply + dropped into the aforementioned directory. The subtle differences + in the scripts depend whether or not <filename>rc.d</filename> is being used. Prior + to &os; 5.1 the old configuration style is used and in + almost all cases a new style script would do just fine.</para> + + <para>While every script must meet some minimal requirements, most + of the time these requirements are &os; version + agnostic. Each script must have a <filename>.sh</filename> + extension appended to the end and every script must be + executable by the system. The latter may be achieved by using + the <command>chmod</command> command and setting the unique permissions + of <literal>755</literal>. There should also be, at minimal, + an option to <literal>start</literal> the application and an + option to <literal>stop</literal> the application.</para> + + <para>The simplest start up script would probably look a little + bit like this one:</para> + + <programlisting>#!/bin/sh +echo -n ' utility' + +case "$1" in +start) + /usr/local/bin/utility + ;; +stop) + kill -9 `cat /var/run/utility.pid` + ;; +*) + echo "Usage: `basename $0` {start|stop}" >&2 + exit 64 + ;; +esac + +exit 0</programlisting> + + <para>This script provides for a <literal>stop</literal> and + <literal>start</literal> option for + the application hereto referred simply as + <literal>utility</literal>.</para> + + <para>Could be started manually with:</para> + + <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/utility.sh start</userinput></screen> + + <para>While not all third party software requires the line in + <filename>rc.conf</filename>, almost every day a new port will + be modified to accept this configuration. Check the final output + of the installation for more information on a specific + application. Some third party software will provide start up + scripts which permit the application to be used with + <filename>rc.d</filename>; although, this will be discussed in the next section.</para> + + <sect2> + <title>Extended Application Configuration</title> + + <para>Now that &os; includes <filename>rc.d</filename>, configuration + of application startup has become easier, and more + featureful. Using the key words discussed in the + <link linkend="configtuning-rcd">rc.d</link> section, + applications may now be set to start after certain other + services for example <acronym>DNS</acronym>; may permit extra + flags to be passed through <filename>rc.conf</filename> in + place of hard coded flags in the start up script, etc. A + basic script may look similar to the following:</para> + + <programlisting>#!/bin/sh +# +# PROVIDE: utility +# REQUIRE: DAEMON +# KEYWORD: shutdown + +. /etc/rc.subr + +name=utility +rcvar=utility_pidfile + +command="/usr/local/sbin/utility" + +load_rc_config $name + +# +# DO NOT CHANGE THESE DEFAULT VALUES HERE +# SET THEM IN THE /etc/rc.conf FILE +# +utility_enable=${utility_enable-"NO"} +pidfile=${utility_pidfile-"/var/run/utility.pid"} + +run_rc_command "$1"</programlisting> + + <para>This script will ensure that the provided + <application>utility</application> will be started after the + <literal>daemon</literal> service. It also provides a method + for setting and tracking the <acronym>PID</acronym>, or process + <acronym>ID</acronym> file.</para> + + <para>This application could then have the following line placed + in <filename>/etc/rc.conf</filename>:</para> + + <programlisting>utility_enable="YES"</programlisting> + + <para>This new method also allows for easier manipulation of the + command line arguments, inclusion of the default functions + provided in <filename>/etc/rc.subr</filename>, compatibility + with the &man.rcorder.8; utility and provides for easier + configuration via the <filename>rc.conf</filename> file.</para> + </sect2> + + <sect2> + <title>以 Services 來啟動各式 Services</title> + + <para>Other services, such as <acronym>POP</acronym>3 server + daemons, <acronym>IMAP</acronym>, etc. could be started using + the &man.inetd.8;. This involves installing the service + utility from the Ports Collection with a configuration line + appended to the <filename>/etc/inetd.conf</filename> file, + or uncommenting one of the current configuration lines. Working + with <application>inetd</application> and its configuration is + described in depth in the + <link linkend="network-inetd">inetd</link> section.</para> + + <para>In some cases, it may be more plausible to use the + &man.cron.8; daemon to start system services. This approach + has a number of advantages because <command>cron</command> runs + these processes as the <filename>crontab</filename>'s file + owner. This allows regular users to start and maintain some + applications.</para> + + <para>The <command>cron</command> utility provides a unique + feature, <literal>@reboot</literal>, which may be used in place + of the time specification. This will cause the job to be run + when &man.cron.8; is started, normally during system + initialization.</para> + + </sect2> + </sect1> + + <sect1 xml:id="configtuning-cron"> + <info><title>設定 <command>cron</command></title> + <authorgroup> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + <indexterm><primary>cron</primary> + <secondary>configuration</secondary></indexterm> + + <para>&os; 最好用的工具之一就是 &man.cron.8;。 + <command>cron</command> 會在背景下運作，並不斷檢查 + <filename>/etc/crontab</filename> 檔以及 <filename>/var/cron/tabs</filename> 目錄，來搜尋是否有新 <filename>crontab</filename> 檔案。 + 這些 <filename>crontab</filename> 檔會存放一些排程工作的設定，來給 <command>cron</command> 執行。</para> + + <para><command>cron</command> 程式，可同時採用兩種不同類型的設定檔：系統本身的 crontab + 及使用者本身的 crontab。而兩種格式唯一差別在於第六欄的不同；In the + system crontab, the sixth field is the name of a user for the command + to run as. This gives the system crontab the ability to run commands + as any user. In a user crontab, the sixth field is the command to run, + and all commands run as the user who created the crontab; this is an + important security feature.</para> + + <note> + <para>User crontabs allow individual users to schedule tasks without the + need for <systemitem class="username">root</systemitem> privileges. Commands in a user's crontab run with the + permissions of the user who owns the crontab.</para> + + <para>The <systemitem class="username">root</systemitem> user can have a user crontab just like + any other user. This one is different from + <filename>/etc/crontab</filename> (the system crontab). Because of the + system crontab, there is usually no need to create a user crontab + for <systemitem class="username">root</systemitem>.</para> + </note> + + <para>Let us take a look at the <filename>/etc/crontab</filename> file + (the system crontab):</para> + + + <programlisting># /etc/crontab - root's crontab for &os; +# +# $&os;: src/etc/crontab,v 1.32 2002/11/22 16:13:39 tom Exp $ +# <co xml:id="co-comments"/> +# +SHELL=/bin/sh +PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co xml:id="co-env"/> +HOME=/var/log +# +# +#minute hour mday month wday who command <co xml:id="co-field-descr"/> +# +# +*/5 * * * * root /usr/libexec/atrun <co xml:id="co-main"/> +</programlisting> + + <calloutlist> + <callout arearefs="co-comments"> + <para>Like most &os; configuration files, the <literal>#</literal> + character represents a comment. A comment can be placed in + the file as a reminder of what and why a desired action is performed. + Comments cannot be on the same line as a command or else they will + be interpreted as part of the command; they must be on a new line. + Blank lines are ignored.</para> + </callout> + + <callout arearefs="co-env"> + <para>First, the environment must be defined. The equals + (<literal>=</literal>) character is used to define any environment + settings, as with this example where it is used for the <envar>SHELL</envar>, + <envar>PATH</envar>, and <envar>HOME</envar> options. If the shell line is + omitted, <command>cron</command> will use the default, which is + <command>sh</command>. If the <envar>PATH</envar> variable is + omitted, no default will be used and file locations will need to + be absolute. If <envar>HOME</envar> is omitted, <command>cron</command> + will use the invoking users home directory.</para> + </callout> + + <callout arearefs="co-field-descr"> + <para>This line defines a total of seven fields. Listed here are the + values <literal>minute</literal>, <literal>hour</literal>, + <literal>mday</literal>, <literal>month</literal>, <literal>wday</literal>, + <literal>who</literal>, and <literal>command</literal>. These + are almost all self explanatory. <literal>minute</literal> is the time in minutes the + command will be run. <literal>hour</literal> is similar to the <literal>minute</literal> option, just in + hours. <literal>mday</literal> stands for day of the month. <literal>month</literal> is similar to <literal>hour</literal> + and <literal>minute</literal>, as it designates the month. The <literal>wday</literal> option stands for + day of the week. All these fields must be numeric values, and follow + the twenty-four hour clock. The <literal>who</literal> field is special, + and only exists in the <filename>/etc/crontab</filename> file. + This field specifies which user the command should be run as. + When a user installs his or her <filename>crontab</filename> file, they + will not have this option. Finally, the <literal>command</literal> option is listed. + This is the last field, so naturally it should designate the command + to be executed.</para> + </callout> + + <callout arearefs="co-main"> + <para>This last line will define the values discussed above. Notice here + we have a <literal>*/5</literal> listing, followed by several more + <literal>*</literal> characters. These <literal>*</literal> characters + mean <quote>first-last</quote>, and can be interpreted as + <emphasis>every</emphasis> time. So, judging by this line, + it is apparent that the <command>atrun</command> command is to be invoked by + <systemitem class="username">root</systemitem> every five minutes regardless of what + day or month it is. For more information on the <command>atrun</command> command, + see the &man.atrun.8; manual page.</para> + + <para>Commands can have any number of flags passed to them; however, + commands which extend to multiple lines need to be broken with the backslash + <quote>\</quote> continuation character.</para> + </callout> + </calloutlist> + + <para>This is the basic set up for every + <filename>crontab</filename> file, although there is one thing + different about this one. Field number six, where we specified + the username, only exists in the system + <filename>/etc/crontab</filename> file. This field should be + omitted for individual user <filename>crontab</filename> + files.</para> + + + <sect2 xml:id="configtuning-installcrontab"> + <title>工作排程(Crontab)的排定與管理</title> + + <important> + <para>You must not use the procedure described here to + edit/install the system crontab. Simply use your favorite + editor: the <command>cron</command> utility will notice that the file + has changed and immediately begin using the updated version. + See + <link xlink:href="&url.books.faq;/admin.html#ROOT-NOT-FOUND-CRON-ERRORS"> + this FAQ entry </link> for more information.</para> + </important> + + <para>To install a freshly written user + <filename>crontab</filename>, first use your favorite editor to create + a file in the proper format, and then use the + <command>crontab</command> utility. The most common usage + is:</para> + + <screen>&prompt.user; <userinput>crontab crontab-file</userinput></screen> + + <para>In this example, <filename>crontab-file</filename> is the filename + of a <filename>crontab</filename> that was previously created.</para> + + <para>There is also an option to list installed + <filename>crontab</filename> files: just pass the + <option>-l</option> option to <command>crontab</command> and look + over the output.</para> + + <para>For users who wish to begin their own crontab file from scratch, + without the use of a template, the <command>crontab -e</command> + option is available. This will invoke the selected editor + with an empty file. When the file is saved, it will be + automatically installed by the <command>crontab</command> command. + </para> + + <para>If you later want to remove your user <filename>crontab</filename> + completely, use <command>crontab</command> with the <option>-r</option> + option. + </para> + + </sect2> + </sect1> + + <sect1 xml:id="configtuning-rcd"> + <info><title>在 &os; 使用 rc</title> + <authorgroup> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + + <para>從 2002 年起，&os; 整合了 NetBSD 的 <filename>rc.d</filename> 機制來作為系統服務啟動機制。 + 可以到 <filename>/etc/rc.d</filename> 目錄下去看，很多檔案都是基本服務，可以用 <option>start</option>, <option>stop</option> + 及 <option>restart</option> 作為使用時的選項。 + 舉個例子，可以用下列指令來重新啟動 &man.sshd.8;：</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/sshd restart</userinput></screen> + + <para>其他服務也是類似作法。當然， + 服務通常只要在 &man.rc.conf.5; 內有指定的話，都會在開機時就自動啟動。舉例來說，若要開機時啟動 NAT(Network Address + Translation) daemon 的話，只要在 <filename>/etc/rc.conf</filename> 內加上下列這行即可：</para> + + <programlisting>natd_enable="YES"</programlisting> + + <para>若原本寫的是 <option>natd_enable="NO"</option> 那麼只要把 <option>NO</option> 改為 + <option>YES</option> 就好了。rc scripts 會在下次重開機時，自動載入相關(有相依)的服務，以下我們會講到這部分。</para> + + <para>Since the <filename>rc.d</filename> system is primarily + intended to start/stop services at system startup/shutdown time, + the standard <option>start</option>, + <option>stop</option> and <option>restart</option> options will only + perform their action if the appropriate + <filename>/etc/rc.conf</filename> variables are set. For + instance the above <command>sshd restart</command> command will + only work if <varname>sshd_enable</varname> is set to + <option>YES</option> in <filename>/etc/rc.conf</filename>. To + <option>start</option>, <option>stop</option> or + <option>restart</option> a service regardless of the settings in + <filename>/etc/rc.conf</filename>, the commands should be + prefixed with <quote>force</quote>. For instance to restart + <command>sshd</command> regardless of the current + <filename>/etc/rc.conf</filename> setting, execute the following + command:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/sshd forcerestart</userinput></screen> + + <para>It is easy to check if a service is enabled in + <filename>/etc/rc.conf</filename> by running the appropriate + <filename>rc.d</filename> script with the option + <option>rcvar</option>. Thus, an administrator can check that + <command>sshd</command> is in fact enabled in + <filename>/etc/rc.conf</filename> by running:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/sshd rcvar</userinput> +# sshd +$sshd_enable=YES</screen> + + <note> + <para>The second line (<literal># sshd</literal>) is the output + from the <command>sshd</command> command, not a <systemitem class="username">root</systemitem> + console.</para> + </note> + + <para>若要檢查服務是否有在運作，可以用 <option>status</option> 選項來查詢。比如：若要確認 + <command>sshd</command> 是否真的有啟動的話，那麼打：</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/sshd status</userinput> +sshd is running as pid 433.</screen> + + <para>In some cases it is also possible to <option>reload</option> a service. + This will attempt to send a signal to an individual service, forcing the + service to reload its configuration files. In most cases this + means sending the service a <literal>SIGHUP</literal> + signal. Support for this feature is not included for every service.</para> + + <para>The <filename>rc.d</filename> system is not only used for network services, it also + contributes to most of the system initialization. For + instance, consider the <filename>bgfsck</filename> file. When + this script is executed, it will print out the following + message:</para> + + <screen>Starting background file system checks in 60 seconds.</screen> + + <para>Therefore this file is used for background file system + checks, which are done only during system initialization.</para> + + <para>Many system services depend on other services to function + properly. For example, NIS and other RPC-based services may + fail to start until after the <command>rpcbind</command> + (portmapper) service has started. To resolve this issue, + information about dependencies and other meta-data is included + in the comments at the top of each startup script. The + &man.rcorder.8; program is then used to parse these comments + during system initialization to determine the order in which + system services should be invoked to satisfy the dependencies. + The following words may be included at the top of each startup + file:</para> + + <itemizedlist> + <listitem> + <para><literal>PROVIDE</literal>: Specifies the services this file provides.</para> + </listitem> + + <listitem> + <para><literal>REQUIRE</literal>: Lists services which are required for this + service. This file will run <emphasis>after</emphasis> + the specified services.</para> + </listitem> + + <listitem> + <para><literal>BEFORE</literal>: Lists services which depend on this service. + This file will run <emphasis>before</emphasis> + the specified services.</para> + </listitem> + </itemizedlist> + + <para>By using this method, an administrator can easily control system + services without the hassle of <quote>runlevels</quote> like + some other &unix; operating systems.</para> + + <para>Additional information about the + <filename>rc.d</filename> system can be found in the &man.rc.8; + and &man.rc.subr.8; manual pages.</para> + </sect1> + + <sect1 xml:id="config-network-setup"> + <info><title>設定網路卡</title> + <authorgroup> + <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + + <indexterm> + <primary>network cards</primary> + <secondary>configuration</secondary> + </indexterm> + + <para>Nowadays we can not think about a computer without thinking + about a network connection. Adding and configuring a network + card is a common task for any &os; administrator.</para> + + <sect2> + <title>選擇正確、可用的驅動程式(Driver)</title> + + <indexterm> + <primary>network cards</primary> + <secondary>driver</secondary> + </indexterm> + + <para>Before you begin, you should know the model of the card + you have, the chip it uses, and whether it is a PCI or ISA card. + &os; supports a wide variety of both PCI and ISA cards. + Check the Hardware Compatibility List for your release to see + if your card is supported.</para> + + <para>Once you are sure your card is supported, you need + to determine the proper driver for the card. + <filename>/usr/src/sys/conf/NOTES</filename> and + <filename>/usr/src/sys/arch/conf/NOTES</filename> will give you + the list of network interface drivers with some information + about the supported chipsets/cards. If you have doubts about + which driver is the correct one, read the manual page of the + driver. The manual page will give you more information about + the supported hardware and even the possible problems that + could occur.</para> + + <para>If you own a common card, most of the time you will not + have to look very hard for a driver. Drivers for common + network cards are present in the <filename>GENERIC</filename> + kernel, so your card should show up during boot, like so:</para> + +<screen>dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38 +000ff irq 15 at device 11.0 on pci0 +dc0: Ethernet address: 00:a0:cc:da:da:da +miibus0: <MII bus> on dc0 +ukphy0: <Generic IEEE 802.3u media interface> on miibus0 +ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto +dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30 +000ff irq 11 at device 12.0 on pci0 +dc1: Ethernet address: 00:a0:cc:da:da:db +miibus1: <MII bus> on dc1 +ukphy1: <Generic IEEE 802.3u media interface> on miibus1 +ukphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto</screen> + + <para>In this example, we see that two cards using the &man.dc.4; + driver are present on the system.</para> + + <para>If the driver for your NIC is not present in + <filename>GENERIC</filename>, you will need to load the proper + driver to use your NIC. This may be accomplished in one of + two ways:</para> + + <itemizedlist> + <listitem> + <para>The easiest way is to simply load a kernel module for + your network card with &man.kldload.8;, or automatically at boot time by adding the appropriate line to the file <filename>/boot/loader.conf</filename>. Not all NIC + drivers are available as modules; notable examples of + devices for which modules do not exist are ISA cards.</para> + </listitem> + + <listitem> + <para>Alternatively, you may statically compile the support + for your card into your kernel. Check + <filename>/usr/src/sys/conf/NOTES</filename>, + <filename>/usr/src/sys/arch/conf/NOTES</filename> + and the manual page of the driver to know what to add in + your kernel configuration file. For more information + about recompiling your kernel, please see <xref linkend="kernelconfig"/>. If your card was detected at + boot by your kernel (<filename>GENERIC</filename>) you do + not have to build a new kernel.</para> + </listitem> + </itemizedlist> + + <sect3 xml:id="config-network-ndis"> + <title>Using &windows; NDIS Drivers</title> + + <indexterm><primary>NDIS</primary></indexterm> + <indexterm><primary>NDISulator</primary></indexterm> + <indexterm><primary>&windows; drivers</primary></indexterm> + <indexterm><primary>Microsoft Windows</primary></indexterm> + <indexterm><primary>Microsoft Windows</primary> + <secondary>device drivers</secondary></indexterm> + <indexterm><primary>KLD (kernel loadable + object)</primary></indexterm> +<!-- We should probably omit the expanded name, and add a <see> entry +for it. Whatever is done must also be done to the same indexterm in +linuxemu/chapter.xml --> + + <para>Unfortunately, there are still many vendors that do not + provide schematics for their drivers to the open source + community because they regard such information as trade + secrets. Consequently, the developers of &os; and other + operating systems are left two choices: develop the drivers + by a long and pain-staking process of reverse engineering or + using the existing driver binaries available for the + µsoft.windows; platforms. Most developers, including + those involved with &os;, have taken the latter + approach.</para> + + <para>Thanks to the contributions of Bill Paul (wpaul), as of + &os; 5.3-RELEASE there is <quote>native</quote> support + for the Network Driver Interface Specification (NDIS). The + &os; NDISulator (otherwise known as Project Evil) takes a + &windows; driver binary and basically tricks it into + thinking it is running on &windows;. Because the + &man.ndis.4; driver is using a &windows; binary, it is only + usable on &i386; and amd64 systems.</para> + + <note> + <para>The &man.ndis.4; driver is designed to support mainly + PCI, CardBus and PCMCIA devices, USB devices are not yet + supported.</para> + </note> + + <para>In order to use the NDISulator, you need three + things:</para> + + <orderedlist> + <listitem> + <para>Kernel sources</para> + </listitem> + <listitem> + <para>&windowsxp; driver binary + (<filename>.SYS</filename> extension)</para> + </listitem> + <listitem> + <para>&windowsxp; driver configuration file + (<filename>.INF</filename> extension)</para> + </listitem> + </orderedlist> + + <para>Locate the files for your specific card. Generally, + they can be found on the included CDs or at the vendors' + websites. In the following examples, we will use + <filename>W32DRIVER.SYS</filename> and + <filename>W32DRIVER.INF</filename>.</para> + + <note> + <para>You can not use a &windows;/i386 driver with + &os;/amd64, you must get a &windows;/amd64 driver to make it + work properly.</para> + </note> + + <para>The next step is to compile the driver binary into a + loadable kernel module. To accomplish this, as + <systemitem class="username">root</systemitem>, use &man.ndisgen.8;:</para> + + <screen>&prompt.root; <userinput>ndisgen /path/to/W32DRIVER.INF /path/to/W32DRIVER.SYS</userinput></screen> + + <para>The &man.ndisgen.8; utility is interactive and will + prompt for any extra information it requires; it will + produce a kernel module in the current directory which can + be loaded as follows:</para> + + <screen>&prompt.root; <userinput>kldload ./W32DRIVER.ko</userinput></screen> + + <para>In addition to the generated kernel module, you must + load the <filename>ndis.ko</filename> and + <filename>if_ndis.ko</filename> modules. This should be + automatically done when you load any module that depends on + &man.ndis.4;. If you want to load them manually, use the + following commands:</para> + + <screen>&prompt.root; <userinput>kldload ndis</userinput> +&prompt.root; <userinput>kldload if_ndis</userinput></screen> + + <para>The first command loads the NDIS miniport driver + wrapper, the second loads the actual network + interface.</para> + + <para>Now, check &man.dmesg.8; to see if there were any errors + loading. If all went well, you should get output resembling + the following:</para> + + <screen>ndis0: <Wireless-G PCI Adapter> mem 0xf4100000-0xf4101fff irq 3 at device 8.0 on pci1 +ndis0: NDIS API version: 5.0 +ndis0: Ethernet address: 0a:b1:2c:d3:4e:f5 +ndis0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps +ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps</screen> + + <para>From here you can treat the + <filename>ndis0</filename> device like any other network + interface (e.g., <filename>dc0</filename>).</para> + + <para>You can configure the system to load the NDIS modules at + boot time in the same way as with any other module. First, + copy the generated module, + <filename>W32DRIVER.ko</filename>, to the <filename>/boot/modules</filename> directory. Then, + add the following line to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>W32DRIVER_load="YES"</programlisting> + </sect3> + </sect2> + + <sect2> + <title>設定網路卡</title> + + <indexterm> + <primary>network cards</primary> + <secondary>configuration</secondary> + </indexterm> + + <para>Once the right driver is loaded for the network card, the + card needs to be configured. As with many other things, the + network card may have been configured at installation time by + <application>sysinstall</application>.</para> + + <para>To display the configuration for the network interfaces on + your system, enter the following command:</para> + +<screen>&prompt.user; <userinput>ifconfig</userinput> +dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255 + ether 00:a0:cc:da:da:da + media: Ethernet autoselect (100baseTX <full-duplex>) + status: active +dc1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255 + ether 00:a0:cc:da:da:db + media: Ethernet 10baseT/UTP + status: no carrier +lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 +lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 + inet 127.0.0.1 netmask 0xff000000 +tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500</screen> + + <note> + <para>Old versions of &os; may require the <option>-a</option> + option following &man.ifconfig.8;, for more details about the + correct syntax of &man.ifconfig.8;, please refer to the manual + page. Note also that entries concerning IPv6 + (<literal>inet6</literal> etc.) were omitted in this + example.</para> + </note> + + <para>In this example, the following devices were + displayed:</para> + + <itemizedlist> + <listitem> + <para><filename>dc0</filename>: The first Ethernet + interface</para> + </listitem> + + <listitem> + <para><filename>dc1</filename>: The second Ethernet + interface</para> + </listitem> + + <listitem> + <para><filename>lp0</filename>: The parallel port + interface</para> + </listitem> + + <listitem> + <para><filename>lo0</filename>: The loopback device</para> + </listitem> + + <listitem> + <para><filename>tun0</filename>: The tunnel device used by + <application>ppp</application></para> + </listitem> + </itemizedlist> + + <para>&os; uses the driver name followed by the order in + which one the card is detected at the kernel boot to name the + network card. For example <filename>sis2</filename> would + be the third network card on the system using the &man.sis.4; + driver.</para> + + <para>In this example, the <filename>dc0</filename> device is + up and running. The key indicators are:</para> + + <orderedlist> + <listitem> + <para><literal>UP</literal> means that the card is configured + and ready.</para> + </listitem> + + <listitem> + <para>The card has an Internet (<literal>inet</literal>) + address (in this case + <systemitem class="ipaddress">192.168.1.3</systemitem>).</para> + </listitem> + + <listitem> + <para>It has a valid subnet mask (<literal>netmask</literal>; + <systemitem class="netmask">0xffffff00</systemitem> is the same as + <systemitem class="netmask">255.255.255.0</systemitem>).</para> + </listitem> + + <listitem> + <para>It has a valid broadcast address (in this case, + <systemitem class="ipaddress">192.168.1.255</systemitem>).</para> + </listitem> + + <listitem> + <para>The MAC address of the card (<literal>ether</literal>) + is <systemitem class="etheraddress">00:a0:cc:da:da:da</systemitem></para> + </listitem> + + <listitem> + <para>The physical media selection is on autoselection mode + (<literal>media: Ethernet autoselect (100baseTX + <full-duplex>)</literal>). We see that + <filename>dc1</filename> was configured to run with + <literal>10baseT/UTP</literal> media. For more + information on available media types for a driver, please + refer to its manual page.</para> + </listitem> + + <listitem> + <para>The status of the link (<literal>status</literal>) + is <literal>active</literal>, i.e. the carrier is detected. + For <filename>dc1</filename>, we see + <literal>status: no carrier</literal>. This is normal when + an Ethernet cable is not plugged into the card.</para> + </listitem> + </orderedlist> + + <para>If the &man.ifconfig.8; output had shown something similar + to:</para> + +<screen>dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> mtu 1500 + ether 00:a0:cc:da:da:da</screen> + + <para>it would indicate the card has not been configured.</para> + + <para>To configure your card, you need <systemitem class="username">root</systemitem> + privileges. The network card configuration can be done from the + command line with &man.ifconfig.8; but you would have to do it + after each reboot of the system. The file + <filename>/etc/rc.conf</filename> is where to add the network + card's configuration.</para> + + <para>Open <filename>/etc/rc.conf</filename> in your favorite + editor. You need to add a line for each network card present on + the system, for example in our case, we added these lines:</para> + +<programlisting>ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0" +ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlisting> + + <para>You have to replace <filename>dc0</filename>, + <filename>dc1</filename>, and so on, with + the correct device for your cards, and the addresses with the + proper ones. You should read the card driver and + &man.ifconfig.8; manual pages for more details about the allowed + options and also &man.rc.conf.5; manual page for more + information on the syntax of + <filename>/etc/rc.conf</filename>.</para> + + <para>If you configured the network during installation, some + lines about the network card(s) may be already present. Double + check <filename>/etc/rc.conf</filename> before adding any + lines.</para> + + <para>You will also have to edit the file + <filename>/etc/hosts</filename> to add the names and the IP + addresses of various machines of the LAN, if they are not already + there. For more information please refer to &man.hosts.5; + and to <filename>/usr/share/examples/etc/hosts</filename>.</para> + </sect2> + + <sect2> + <title>測試與疑難排除</title> + + <para>Once you have made the necessary changes in + <filename>/etc/rc.conf</filename>, you should reboot your + system. This will allow the change(s) to the interface(s) to + be applied, and verify that the system restarts without any + configuration errors.</para> + + <para>Once the system has been rebooted, you should test the + network interfaces.</para> + + <sect3> + <title>測試乙太網路卡(Ethernet Card)</title> + + <indexterm> + <primary>network cards</primary> + <secondary>testing</secondary> + </indexterm> + + <para>To verify that an Ethernet card is configured correctly, + you have to try two things. First, ping the interface itself, + and then ping another machine on the LAN.</para> + + <para>First test the local interface:</para> + +<screen>&prompt.user; <userinput>ping -c5 192.168.1.3</userinput> +PING 192.168.1.3 (192.168.1.3): 56 data bytes +64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms +64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms +64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms +64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms +64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms + +--- 192.168.1.3 ping statistics --- +5 packets transmitted, 5 packets received, 0% packet loss +round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms</screen> + + <para>Now we have to ping another machine on the LAN:</para> + +<screen>&prompt.user; <userinput>ping -c5 192.168.1.2</userinput> +PING 192.168.1.2 (192.168.1.2): 56 data bytes +64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms +64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms +64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms +64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms +64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms + +--- 192.168.1.2 ping statistics --- +5 packets transmitted, 5 packets received, 0% packet loss +round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen> + + <para>You could also use the machine name instead of + <systemitem class="ipaddress">192.168.1.2</systemitem> if you have set up the + <filename>/etc/hosts</filename> file.</para> + </sect3> + + <sect3> + <title>疑難排除</title> + + <indexterm> + <primary>network cards</primary> + <secondary>troubleshooting</secondary> + </indexterm> + + <para>Troubleshooting hardware and software configurations is always + a pain, and a pain which can be alleviated by checking the simple + things first. Is your network cable plugged in? Have you properly + configured the network services? Did you configure the firewall + correctly? Is the card you are using supported by &os;? Always + check the hardware notes before sending off a bug report. Update + your version of &os; to the latest STABLE version. Check the + mailing list archives, or perhaps search the Internet.</para> + + <para>If the card works, yet performance is poor, it would be + worthwhile to read over the &man.tuning.7; manual page. You + can also check the network configuration as incorrect network + settings can cause slow connections.</para> + + <para>Some users experience one or two <errorname>device + timeout</errorname> messages, which is normal for some cards. If they + continue, or are bothersome, you may wish to be sure the + device is not conflicting with another device. Double check + the cable connections. Perhaps you may just need to get + another card.</para> + + <para>At times, users see a few <errorname>watchdog timeout</errorname> + errors. The first thing to do here is to check your network + cable. Many cards require a PCI slot which supports Bus + Mastering. On some old motherboards, only one PCI slot allows + it (usually slot 0). Check the network card and the + motherboard documentation to determine if that may be the + problem.</para> + + <para><errorname>No route to host</errorname> messages occur if the + system is unable to route a packet to the destination host. + This can happen if no default route is specified, or if a + cable is unplugged. Check the output of <command>netstat + -rn</command> and make sure there is a valid route to the host + you are trying to reach. If there is not, read on to <xref linkend="advanced-networking"/>.</para> + + <para><errorname>ping: sendto: Permission denied</errorname> error + messages are often caused by a misconfigured firewall. If + <command>ipfw</command> is enabled in the kernel but no rules + have been defined, then the default policy is to deny all + traffic, even ping requests! Read on to <xref linkend="firewalls"/> for more information.</para> + + <para>Sometimes performance of the card is poor, or below average. + In these cases it is best to set the media selection mode + from <literal>autoselect</literal> to the correct media selection. + While this usually works for most hardware, it may not resolve + this issue for everyone. Again, check all the network settings, + and read over the &man.tuning.7; manual page.</para> + + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="configtuning-virtual-hosts"> + <title>虛擬主機(Virtual Hosts)</title> + + <indexterm><primary>virtual hosts</primary></indexterm> + <indexterm><primary>IP aliases</primary></indexterm> + + <para>A very common use of &os; is virtual site hosting, where + one server appears to the network as many servers. This is + achieved by assigning multiple network addresses to a single + interface.</para> + + <para>A given network interface has one <quote>real</quote> address, + and may have any number of <quote>alias</quote> addresses. + These aliases are + normally added by placing alias entries in + <filename>/etc/rc.conf</filename>.</para> + + <para>An alias entry for the interface <filename>fxp0</filename> + looks like:</para> + +<programlisting>ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"</programlisting> + + <para>Note that alias entries must start with <literal>alias0</literal> and proceed + upwards in order, (for example, <literal>_alias1</literal>, <literal>_alias2</literal>, and so on). + The configuration process will stop at the first missing number. + </para> + + <para>The calculation of alias netmasks is important, but + fortunately quite simple. For a given interface, there must be + one address which correctly represents the network's netmask. + Any other addresses which fall within this network must have a + netmask of all <literal>1</literal>s (expressed as either + <systemitem class="netmask">255.255.255.255</systemitem> or <systemitem class="netmask">0xffffffff</systemitem>). + </para> + + <para>For example, consider the case where the + <filename>fxp0</filename> interface is + connected to two networks, the <systemitem class="ipaddress">10.1.1.0</systemitem> + network with a netmask of <systemitem class="netmask">255.255.255.0</systemitem> + and the <systemitem class="ipaddress">202.0.75.16</systemitem> network with + a netmask of <systemitem class="netmask">255.255.255.240</systemitem>. + We want the system to appear at <systemitem class="ipaddress">10.1.1.1</systemitem> + through <systemitem class="ipaddress">10.1.1.5</systemitem> and at + <systemitem class="ipaddress">202.0.75.17</systemitem> through + <systemitem class="ipaddress">202.0.75.20</systemitem>. As noted above, only the + first address in a given network range (in this case, + <systemitem class="ipaddress">10.0.1.1</systemitem> and + <systemitem class="ipaddress">202.0.75.17</systemitem>) should have a real + netmask; all the rest (<systemitem class="ipaddress">10.1.1.2</systemitem> + through <systemitem class="ipaddress">10.1.1.5</systemitem> and + <systemitem class="ipaddress">202.0.75.18</systemitem> through + <systemitem class="ipaddress">202.0.75.20</systemitem>) must be configured with a + netmask of <systemitem class="netmask">255.255.255.255</systemitem>.</para> + + <para>The following <filename>/etc/rc.conf</filename> entries + configure the adapter correctly for this arrangement:</para> + + <programlisting>ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0" +ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255" +ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255" +ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255" +ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255" +ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240" +ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255" +ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255" +ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting> + + </sect1> + + <sect1 xml:id="configtuning-configfiles"> + <title>還有哪些主要設定檔呢？</title> + + <sect2> + <title><filename>/etc</filename> Layout</title> + <para>There are a number of directories in which configuration + information is kept. These include:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="2*"/> + + <tbody> + <row> + <entry><filename>/etc</filename></entry> + <entry>Generic system configuration information; data here is + system-specific.</entry> + </row> + <row> + <entry><filename>/etc/defaults</filename></entry> + <entry>Default versions of system configuration files.</entry> + </row> + <row> + <entry><filename>/etc/mail</filename></entry> + <entry>Extra &man.sendmail.8; configuration, other + MTA configuration files. + </entry> + </row> + <row> + <entry><filename>/etc/ppp</filename></entry> + <entry>Configuration for both user- and kernel-ppp programs. + </entry> + </row> + <row> + <entry><filename>/etc/namedb</filename></entry> + <entry>Default location for &man.named.8; data. Normally + <filename>named.conf</filename> and zone files are stored + here.</entry> + </row> + <row> + <entry><filename>/usr/local/etc</filename></entry> + <entry>Configuration files for installed applications. + May contain per-application subdirectories.</entry> + </row> + <row> + <entry><filename>/usr/local/etc/rc.d</filename></entry> + <entry>Start/stop scripts for installed applications.</entry> + </row> + <row> + <entry><filename>/var/db</filename></entry> + <entry>Automatically generated system-specific database files, + such as the package database, the locate database, and so + on</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + + <sect2> + <title>Hostnames</title> + + <indexterm><primary>hostname</primary></indexterm> + <indexterm><primary>DNS</primary></indexterm> + + <sect3> + <title><filename>/etc/resolv.conf</filename></title> + + <indexterm> + <primary><filename>resolv.conf</filename></primary> + </indexterm> + + <para><filename>/etc/resolv.conf</filename> dictates how &os;'s + resolver accesses the Internet Domain Name System (DNS).</para> + + <para>The most common entries to <filename>resolv.conf</filename> are: + </para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="2*"/> + + <tbody> + <row> + <entry><literal>nameserver</literal></entry> + <entry>The IP address of a name server the resolver + should query. The servers are queried in the order + listed with a maximum of three.</entry> + </row> + <row> + <entry><literal>search</literal></entry> + <entry>Search list for hostname lookup. This is normally + determined by the domain of the local hostname.</entry> + </row> + <row> + <entry><literal>domain</literal></entry> + <entry>The local domain name.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>A typical <filename>resolv.conf</filename>:</para> + + <programlisting>search example.com +nameserver 147.11.1.11 +nameserver 147.11.100.30</programlisting> + + <note><para>Only one of the <literal>search</literal> and + <literal>domain</literal> options should be used.</para></note> + + <para>If you are using DHCP, &man.dhclient.8; usually rewrites + <filename>resolv.conf</filename> with information received from the + DHCP server.</para> + </sect3> + + <sect3> + <title><filename>/etc/hosts</filename></title> + + <indexterm><primary>hosts</primary></indexterm> + + <para><filename>/etc/hosts</filename> is a simple text + database reminiscent of the old Internet. It works in + conjunction with DNS and NIS providing name to IP address + mappings. Local computers connected via a LAN can be placed + in here for simplistic naming purposes instead of setting up + a &man.named.8; server. Additionally, + <filename>/etc/hosts</filename> can be used to provide a + local record of Internet names, reducing the need to query + externally for commonly accessed names.</para> + + <programlisting># $&os;$ +# +# Host Database +# This file should contain the addresses and aliases +# for local hosts that share this file. +# In the presence of the domain name service or NIS, this file may +# not be consulted at all; see /etc/nsswitch.conf for the resolution order. +# +# +::1 localhost localhost.my.domain myname.my.domain +127.0.0.1 localhost localhost.my.domain myname.my.domain + +# +# Imaginary network. +#10.0.0.2 myname.my.domain myname +#10.0.0.3 myfriend.my.domain myfriend +# +# According to RFC 1918, you can use the following IP networks for +# private nets which will never be connected to the Internet: +# +# 10.0.0.0 - 10.255.255.255 +# 172.16.0.0 - 172.31.255.255 +# 192.168.0.0 - 192.168.255.255 +# +# In case you want to be able to connect to the Internet, you need +# real official assigned numbers. PLEASE PLEASE PLEASE do not try +# to invent your own network numbers but instead get one from your +# network provider (if any) or from the Internet Registry (ftp to +# rs.internic.net, directory `/templates'). +#</programlisting> + + <para><filename>/etc/hosts</filename> takes on the simple format + of:</para> + + <programlisting>[Internet address] [official hostname] [alias1] [alias2] ...</programlisting> + + <para>For example:</para> + + <programlisting>10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2</programlisting> + + <para>Consult &man.hosts.5; for more information.</para> + </sect3> + </sect2> + + <sect2> + <title>Log File Configuration</title> + + <indexterm><primary>log files</primary></indexterm> + + <sect3> + <title><filename>syslog.conf</filename></title> + + <indexterm><primary>syslog.conf</primary></indexterm> + + <para><filename>syslog.conf</filename> is the configuration file + for the &man.syslogd.8; program. It indicates which types + of <command>syslog</command> messages are logged to particular + log files.</para> + + <programlisting># $&os;$ +# +# Spaces ARE valid field separators in this file. However, +# other *nix-like systems still insist on using tabs as field +# separators. If you are sharing this file between systems, you +# may want to use only tabs as field separators here. +# Consult the syslog.conf(5) manual page. +*.err;kern.debug;auth.notice;mail.crit /dev/console +*.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages +security.* /var/log/security +mail.info /var/log/maillog +lpr.info /var/log/lpd-errs +cron.* /var/log/cron +*.err root +*.notice;news.err root +*.alert root +*.emerg * +# uncomment this to log all writes to /dev/console to /var/log/console.log +#console.info /var/log/console.log +# uncomment this to enable logging of all log messages to /var/log/all.log +#*.* /var/log/all.log +# uncomment this to enable logging to a remote log host named loghost +#*.* @loghost +# uncomment these if you're running inn +# news.crit /var/log/news/news.crit +# news.err /var/log/news/news.err +# news.notice /var/log/news/news.notice +!startslip +*.* /var/log/slip.log +!ppp +*.* /var/log/ppp.log</programlisting> + + <para>Consult the &man.syslog.conf.5; manual page for more + information.</para> + </sect3> + + <sect3> + <title><filename>newsyslog.conf</filename></title> + + <indexterm><primary>newsyslog.conf</primary></indexterm> + + <para><filename>newsyslog.conf</filename> is the configuration + file for &man.newsyslog.8;, a program that is normally scheduled + to run by &man.cron.8;. &man.newsyslog.8; determines when log + files require archiving or rearranging. + <filename>logfile</filename> is moved to + <filename>logfile.0</filename>, <filename>logfile.0</filename> + is moved to <filename>logfile.1</filename>, and so on. + Alternatively, the log files may be archived in &man.gzip.1; format + causing them to be named: <filename>logfile.0.gz</filename>, + <filename>logfile.1.gz</filename>, and so on.</para> + + <para><filename>newsyslog.conf</filename> indicates which log + files are to be managed, how many are to be kept, and when + they are to be touched. Log files can be rearranged and/or + archived when they have either reached a certain size, or at a + certain periodic time/date.</para> + + <programlisting># configuration file for newsyslog +# $&os;$ +# +# filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num] +/var/log/cron 600 3 100 * Z +/var/log/amd.log 644 7 100 * Z +/var/log/kerberos.log 644 7 100 * Z +/var/log/lpd-errs 644 7 100 * Z +/var/log/maillog 644 7 * @T00 Z +/var/log/sendmail.st 644 10 * 168 B +/var/log/messages 644 5 100 * Z +/var/log/all.log 600 7 * @T00 Z +/var/log/slip.log 600 3 100 * Z +/var/log/ppp.log 600 3 100 * Z +/var/log/security 600 10 100 * Z +/var/log/wtmp 644 3 * @01T05 B +/var/log/daily.log 640 7 * @T00 Z +/var/log/weekly.log 640 5 1 $W6D0 Z +/var/log/monthly.log 640 12 * $M1D0 Z +/var/log/console.log 640 5 100 * Z</programlisting> + + <para>Consult the &man.newsyslog.8; manual page for more + information.</para> + </sect3> + </sect2> + + <sect2 xml:id="configtuning-sysctlconf"> + <title><filename>sysctl.conf</filename></title> + + <indexterm><primary>sysctl.conf</primary></indexterm> + <indexterm><primary>sysctl</primary></indexterm> + + <para><filename>sysctl.conf</filename> looks much like + <filename>rc.conf</filename>. Values are set in a + <literal>variable=value</literal> + form. The specified values are set after the system goes into + multi-user mode. Not all variables are settable in this mode.</para> + + <para>A sample <filename>sysctl.conf</filename> turning off logging + of fatal signal exits and letting Linux programs know they are really + running under &os;:</para> + + <programlisting>kern.logsigexit=0 # Do not log fatal signal exits (e.g. sig 11) +compat.linux.osname=&os; +compat.linux.osrelease=4.3-STABLE</programlisting> + </sect2> + </sect1> + + <sect1 xml:id="configtuning-sysctl"> + <title>Tuning with sysctl</title> + + <indexterm><primary>sysctl</primary></indexterm> + <indexterm> + <primary>tuning</primary> + <secondary>with sysctl</secondary> + </indexterm> + + <para>&man.sysctl.8; is an interface that allows you to make changes + to a running &os; system. This includes many advanced + options of the TCP/IP stack and virtual memory system that can + dramatically improve performance for an experienced system + administrator. Over five hundred system variables can be read + and set using &man.sysctl.8;.</para> + + <para>At its core, &man.sysctl.8; serves two functions: to read and + to modify system settings.</para> + + <para>To view all readable variables:</para> + + <screen>&prompt.user; <userinput>sysctl -a</userinput></screen> + + <para>To read a particular variable, for example, + <varname>kern.maxproc</varname>:</para> + + <screen>&prompt.user; <userinput>sysctl kern.maxproc</userinput> +kern.maxproc: 1044</screen> + + <para>To set a particular variable, use the intuitive + <replaceable>variable</replaceable>=<replaceable>value</replaceable> + syntax:</para> + + <screen>&prompt.root; <userinput>sysctl kern.maxfiles=5000</userinput> +kern.maxfiles: 2088 -> 5000</screen> + + <para>Settings of sysctl variables are usually either strings, + numbers, or booleans (a boolean being <literal>1</literal> for yes + or a <literal>0</literal> for no).</para> + + <para>If you want to set automatically some variables each time + the machine boots, add them to the + <filename>/etc/sysctl.conf</filename> file. For more information + see the &man.sysctl.conf.5; manual page and the + <xref linkend="configtuning-sysctlconf"/>.</para> + + <sect2 xml:id="sysctl-readonly"> + <info><title>&man.sysctl.8; Read-only</title> + <authorgroup> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + </info> + + + <para>In some cases it may be desirable to modify read-only &man.sysctl.8; + values. While this is sometimes unavoidable, it can only be done + on (re)boot.</para> + + <para>For instance on some laptop models the &man.cardbus.4; device will + not probe memory ranges, and fail with errors which look similar to:</para> + + <screen>cbb0: Could not map register memory +device_probe_and_attach: cbb0 attach returned 12</screen> + + <para>Cases like the one above usually require the modification of some + default &man.sysctl.8; settings which are set read only. To overcome + these situations a user can put &man.sysctl.8; <quote>OIDs</quote> + in their local <filename>/boot/loader.conf</filename>. Default + settings are located in the <filename>/boot/defaults/loader.conf</filename> + file.</para> + + <para>Fixing the problem mentioned above would require a user to set + <option>hw.pci.allow_unsupported_io_range=1</option> in the aforementioned + file. Now &man.cardbus.4; will work properly.</para> + + </sect2> + </sect1> + + <sect1 xml:id="configtuning-disk"> + <title>Tuning Disks</title> + + <sect2> + <title>Sysctl Variables</title> + + <sect3> + <title><varname>vfs.vmiodirenable</varname></title> + + <indexterm> + <primary><varname>vfs.vmiodirenable</varname></primary> + </indexterm> + + <para>The <varname>vfs.vmiodirenable</varname> sysctl variable + may be set to either 0 (off) or 1 (on); it is 1 by default. + This variable controls how directories are cached by the + system. Most directories are small, using just a single + fragment (typically 1 K) in the file system and less + (typically 512 bytes) in the buffer cache. + With this variable turned off (to 0), the buffer + cache will only cache a fixed number of directories even if + you have a huge amount of memory. When turned on (to 1), this sysctl + allows the buffer cache to use the VM Page Cache to cache the + directories, making all the memory available for caching + directories. However, + the minimum in-core memory used to cache a directory is the + physical page size (typically 4 K) rather than 512 + bytes. We recommend keeping this option on if you are running + any services which manipulate large numbers of files. Such + services can include web caches, large mail systems, and news + systems. Keeping this option on will generally not reduce + performance even with the wasted memory but you should + experiment to find out.</para> + </sect3> + + <sect3> + <title><varname>vfs.write_behind</varname></title> + + <indexterm> + <primary><varname>vfs.write_behind</varname></primary> + </indexterm> + + <para>The <varname>vfs.write_behind</varname> sysctl variable + defaults to <literal>1</literal> (on). This tells the file system + to issue media writes as full clusters are collected, which + typically occurs when writing large sequential files. The idea + is to avoid saturating the buffer cache with dirty buffers when + it would not benefit I/O performance. However, this may stall + processes and under certain circumstances you may wish to turn it + off.</para> + </sect3> + + <sect3> + <title><varname>vfs.hirunningspace</varname></title> + + <indexterm> + <primary><varname>vfs.hirunningspace</varname></primary> + </indexterm> + + <para>The <varname>vfs.hirunningspace</varname> sysctl variable + determines how much outstanding write I/O may be queued to disk + controllers system-wide at any given instance. The default is + usually sufficient but on machines with lots of disks you may + want to bump it up to four or five <emphasis>megabytes</emphasis>. + Note that setting too high a value (exceeding the buffer cache's + write threshold) can lead to extremely bad clustering + performance. Do not set this value arbitrarily high! Higher + write values may add latency to reads occurring at the same time. + </para> + + <para>There are various other buffer-cache and VM page cache + related sysctls. We do not recommend modifying these values, + the VM system does an extremely good job of + automatically tuning itself.</para> + </sect3> + + <sect3> + <title><varname>vm.swap_idle_enabled</varname></title> + + <indexterm> + <primary><varname>vm.swap_idle_enabled</varname></primary> + </indexterm> + + <para>The <varname>vm.swap_idle_enabled</varname> sysctl variable + is useful in large multi-user systems where you have lots of + users entering and leaving the system and lots of idle processes. + Such systems tend to generate a great deal of continuous pressure + on free memory reserves. Turning this feature on and tweaking + the swapout hysteresis (in idle seconds) via + <varname>vm.swap_idle_threshold1</varname> and + <varname>vm.swap_idle_threshold2</varname> allows you to depress + the priority of memory pages associated with idle processes more + quickly then the normal pageout algorithm. This gives a helping + hand to the pageout daemon. Do not turn this option on unless + you need it, because the tradeoff you are making is essentially + pre-page memory sooner rather than later; thus eating more swap + and disk bandwidth. In a small system this option will have a + determinable effect but in a large system that is already doing + moderate paging this option allows the VM system to stage whole + processes into and out of memory easily.</para> + </sect3> + + <sect3> + <title><varname>hw.ata.wc</varname></title> + + <indexterm> + <primary><varname>hw.ata.wc</varname></primary> + </indexterm> + + <para>&os; 4.3 flirted with turning off IDE write caching. + This reduced write bandwidth to IDE disks but was considered + necessary due to serious data consistency issues introduced + by hard drive vendors. The problem is that IDE + drives lie about when a write completes. With IDE write + caching turned on, IDE hard drives not only write data + to disk out of order, but will sometimes delay writing some + blocks indefinitely when under heavy disk loads. A crash or + power failure may cause serious file system corruption. + &os;'s default was changed to be safe. Unfortunately, the + result was such a huge performance loss that we changed + write caching back to on by default after the release. You + should check the default on your system by observing the + <varname>hw.ata.wc</varname> sysctl variable. If IDE write + caching is turned off, you can turn it back on by setting + the kernel variable back to 1. This must be done from the + boot loader at boot time. Attempting to do it after the + kernel boots will have no effect.</para> + + <para>For more information, please see &man.ata.4;.</para> + </sect3> + + <sect3> + <title><literal>SCSI_DELAY</literal> + (<varname>kern.cam.scsi_delay</varname>)</title> + + <indexterm> + <primary><varname>kern.cam.scsi_delay</varname></primary> + </indexterm> + + <indexterm> + <primary>kernel options</primary> + <secondary><literal>SCSI_DELAY</literal></secondary> + </indexterm> + + <para>The <literal>SCSI_DELAY</literal> kernel config may be used to + reduce system boot times. The defaults are fairly high and can be + responsible for <literal>15</literal> seconds of delay in the + boot process. Reducing it to <literal>5</literal> seconds usually + works (especially with modern drives). Newer versions of &os; + (5.0 and higher) should use the <varname>kern.cam.scsi_delay</varname> + boot time tunable. The tunable, and kernel config option accept + values in terms of <emphasis>milliseconds</emphasis> and + <emphasis>not</emphasis> <emphasis>seconds</emphasis>.</para> + </sect3> + </sect2> + + <sect2 xml:id="soft-updates"> + <title>Soft Updates</title> + + <indexterm><primary>Soft Updates</primary></indexterm> + <indexterm><primary>tunefs</primary></indexterm> + + <para>The &man.tunefs.8; program can be used to fine-tune a + file system. This program has many different options, but for + now we are only concerned with toggling Soft Updates on and + off, which is done by:</para> + + <screen>&prompt.root; <userinput>tunefs -n enable /filesystem</userinput> +&prompt.root; <userinput>tunefs -n disable /filesystem</userinput></screen> + + <para>A filesystem cannot be modified with &man.tunefs.8; while + it is mounted. A good time to enable Soft Updates is before any + partitions have been mounted, in single-user mode.</para> + + <para>Soft Updates drastically improves meta-data performance, mainly + file creation and deletion, through the use of a memory cache. We + recommend to use Soft Updates on all of your file systems. There + are two downsides to Soft Updates that you should be aware of: First, + Soft Updates guarantees filesystem consistency in the case of a crash + but could very easily be several seconds (even a minute!) behind + updating the physical disk. If your system crashes you may lose more + work than otherwise. Secondly, Soft Updates delays the freeing of + filesystem blocks. If you have a filesystem (such as the root + filesystem) which is almost full, performing a major update, such as + <command>make installworld</command>, can cause the filesystem to run + out of space and the update to fail.</para> + + <sect3> + <title>More Details about Soft Updates</title> + + <indexterm> + <primary>Soft Updates</primary> + <secondary>details</secondary> + </indexterm> + + <para>There are two traditional approaches to writing a file + systems meta-data back to disk. (Meta-data updates are + updates to non-content data like inodes or + directories.)</para> + + <para>Historically, the default behavior was to write out + meta-data updates synchronously. If a directory had been + changed, the system waited until the change was actually + written to disk. The file data buffers (file contents) were + passed through the buffer cache and backed up + to disk later on asynchronously. The advantage of this + implementation is that it operates safely. If there is + a failure during an update, the meta-data are always in a + consistent state. A file is either created completely + or not at all. If the data blocks of a file did not find + their way out of the buffer cache onto the disk by the time + of the crash, &man.fsck.8; is able to recognize this and + repair the filesystem by setting the file length to + 0. Additionally, the implementation is clear and simple. + The disadvantage is that meta-data changes are slow. An + <command>rm -r</command>, for instance, touches all the files + in a directory sequentially, but each directory + change (deletion of a file) will be written synchronously + to the disk. This includes updates to the directory itself, + to the inode table, and possibly to indirect blocks + allocated by the file. Similar considerations apply for + unrolling large hierarchies (<command>tar -x</command>).</para> + + <para>The second case is asynchronous meta-data updates. This + is the default for Linux/ext2fs and + <command>mount -o async</command> for *BSD ufs. All + meta-data updates are simply being passed through the buffer + cache too, that is, they will be intermixed with the updates + of the file content data. The advantage of this + implementation is there is no need to wait until each + meta-data update has been written to disk, so all operations + which cause huge amounts of meta-data updates work much + faster than in the synchronous case. Also, the + implementation is still clear and simple, so there is a low + risk for bugs creeping into the code. The disadvantage is + that there is no guarantee at all for a consistent state of + the filesystem. If there is a failure during an operation + that updated large amounts of meta-data (like a power + failure, or someone pressing the reset button), + the filesystem + will be left in an unpredictable state. There is no opportunity + to examine the state of the filesystem when the system + comes up again; the data blocks of a file could already have + been written to the disk while the updates of the inode + table or the associated directory were not. It is actually + impossible to implement a <command>fsck</command> which is + able to clean up the resulting chaos (because the necessary + information is not available on the disk). If the + filesystem has been damaged beyond repair, the only choice + is to use &man.newfs.8; on it and restore it from backup. + </para> + + <para>The usual solution for this problem was to implement + <emphasis>dirty region logging</emphasis>, which is also + referred to as <emphasis>journaling</emphasis>, although that + term is not used consistently and is occasionally applied + to other forms of transaction logging as well. Meta-data + updates are still written synchronously, but only into a + small region of the disk. Later on they will be moved + to their proper location. Because the logging + area is a small, contiguous region on the disk, there + are no long distances for the disk heads to move, even + during heavy operations, so these operations are quicker + than synchronous updates. + Additionally the complexity of the implementation is fairly + limited, so the risk of bugs being present is low. A disadvantage + is that all meta-data are written twice (once into the + logging region and once to the proper location) so for + normal work, a performance <quote>pessimization</quote> + might result. On the other hand, in case of a crash, all + pending meta-data operations can be quickly either rolled-back + or completed from the logging area after the system comes + up again, resulting in a fast filesystem startup.</para> + + <para>Kirk McKusick, the developer of Berkeley FFS, + solved this problem with Soft Updates: all pending + meta-data updates are kept in memory and written out to disk + in a sorted sequence (<quote>ordered meta-data + updates</quote>). This has the effect that, in case of + heavy meta-data operations, later updates to an item + <quote>catch</quote> the earlier ones if the earlier ones are still in + memory and have not already been written to disk. So all + operations on, say, a directory are generally performed in + memory before the update is written to disk (the data + blocks are sorted according to their position so + that they will not be on the disk ahead of their meta-data). + If the system crashes, this causes an implicit <quote>log + rewind</quote>: all operations which did not find their way + to the disk appear as if they had never happened. A + consistent filesystem state is maintained that appears to + be the one of 30 to 60 seconds earlier. The + algorithm used guarantees that all resources in use + are marked as such in their appropriate bitmaps: blocks and inodes. + After a crash, the only resource allocation error + that occurs is that resources are + marked as <quote>used</quote> which are actually <quote>free</quote>. + &man.fsck.8; recognizes this situation, + and frees the resources that are no longer used. It is safe to + ignore the dirty state of the filesystem after a crash by + forcibly mounting it with <command>mount -f</command>. In + order to free resources that may be unused, &man.fsck.8; + needs to be run at a later time. This is the idea behind + the <emphasis>background fsck</emphasis>: at system startup + time, only a <emphasis>snapshot</emphasis> of the + filesystem is recorded. The <command>fsck</command> can be + run later on. All file systems can then be mounted + <quote>dirty</quote>, so the system startup proceeds in + multiuser mode. Then, background <command>fsck</command>s + will be scheduled for all file systems where this is required, to free + resources that may be unused. (File systems that do not use + Soft Updates still need the usual foreground + <command>fsck</command> though.)</para> + + <para>The advantage is that meta-data operations are nearly as + fast as asynchronous updates (i.e. faster than with + <emphasis>logging</emphasis>, which has to write the + meta-data twice). The disadvantages are the complexity of + the code (implying a higher risk for bugs in an area that + is highly sensitive regarding loss of user data), and a + higher memory consumption. Additionally there are some + idiosyncrasies one has to get used to. + After a crash, the state of the filesystem appears to be + somewhat <quote>older</quote>. In situations where + the standard synchronous approach would have caused some + zero-length files to remain after the + <command>fsck</command>, these files do not exist at all + with a Soft Updates filesystem because neither the meta-data + nor the file contents have ever been written to disk. + Disk space is not released until the updates have been + written to disk, which may take place some time after + running <command>rm</command>. This may cause problems + when installing large amounts of data on a filesystem + that does not have enough free space to hold all the files + twice.</para> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="configtuning-kernel-limits"> + <title>Tuning Kernel Limits</title> + + <indexterm> + <primary>tuning</primary> + <secondary>kernel limits</secondary> + </indexterm> + + <sect2 xml:id="file-process-limits"> + <title>File/Process Limits</title> + + <sect3 xml:id="kern-maxfiles"> + <title><varname>kern.maxfiles</varname></title> + + <indexterm> + <primary><varname>kern.maxfiles</varname></primary> + </indexterm> + + <para><varname>kern.maxfiles</varname> can be raised or + lowered based upon your system requirements. This variable + indicates the maximum number of file descriptors on your + system. When the file descriptor table is full, + <errorname>file: table is full</errorname> will show up repeatedly + in the system message buffer, which can be viewed with the + <command>dmesg</command> command.</para> + + <para>Each open file, socket, or fifo uses one file + descriptor. A large-scale production server may easily + require many thousands of file descriptors, depending on the + kind and number of services running concurrently.</para> + + <para>In older FreeBSD releases, <varname>kern.maxfile</varname>'s default + value is derived from the <option>maxusers</option> option in your + dictated by the <option>maxusers</option> option in your + kernel configuration file. <varname>kern.maxfiles</varname> grows + proportionally to the value of <option>maxusers</option>. When + compiling a custom kernel, it is a good idea to set this kernel + configuration option according to the uses of your system. From + this number, the kernel is given most of its pre-defined limits. + Even though a production machine may not actually have 256 users + connected at once, the resources needed may be similar to a + high-scale web server.</para> + + <para>As of FreeBSD 4.5, <varname>kern.maxusers</varname> is + automatically sized at boot based on the amount of memory available + in the system, and may be determined at run-time by inspecting the + value of the read-only <varname>kern.maxusers</varname> sysctl. + Some sites will require larger or smaller values of + <varname>kern.maxusers</varname> and may set it as a loader tunable; + values of 64, 128, and 256 are not uncommon. We do not recommend + going above 256 unless you need a huge number of file descriptors; + many of the tunable values set to their defaults by + <varname>kern.maxusers</varname> may be individually overridden at + boot-time or run-time in <filename>/boot/loader.conf</filename> (see + the &man.loader.conf.5; man page or the + <filename>/boot/defaults/loader.conf</filename> file for some hints) + or as described elsewhere in this document. Systems older than + FreeBSD 4.4 must set this value via the kernel &man.config.8; + option <option>maxusers</option> instead.</para> + + <para>The system will auto-tune + <literal>maxusers</literal> for you if you explicitly set it to + <literal>0</literal><footnote> + <para>The auto-tuning algorithm sets + <literal>maxusers</literal> equal to the amount of memory in the + system, with a minimum of 32, and a maximum of 384.</para> + </footnote>. When setting this option, you will want to set + <literal>maxusers</literal> to at least 4, especially if you are + using the X Window System or compiling software. The reason is that + the most important table set by <literal>maxusers</literal> is the + maximum number of processes, which is set to <literal>20 + 16 * + maxusers</literal>, so if you set <literal>maxusers</literal> to 1, + then you can only have 36 simultaneous processes, including the 18 + or so that the system starts up at boot time and the 15 or so you + will probably create when you start the X Window System. Even a + simple task like reading a manual page will start up nine + processes to filter, decompress, and view it. Setting + <literal>maxusers</literal> to 64 will allow you to have up to 1044 + simultaneous processes, which should be enough for nearly all uses. + If, however, you see the dreaded <errortype>proc table + full</errortype> error when trying to start another program, or are + running a server with a large number of simultaneous users (like + <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem>), you can always + increase the number and rebuild.</para> + + <note> + <para><literal>maxusers</literal> does <emphasis>not</emphasis> + limit the number of users which can log into your machine. It + simply sets various table sizes to reasonable values considering + the maximum number of users you will likely have on your system + and how many processes each of them will be running. One keyword + which <emphasis>does</emphasis> limit the number of simultaneous + remote logins and X terminal windows is <link linkend="kernelconfig-ptys"><literal>pseudo-device pty + 16</literal></link>. With &os; 5.X, you do not have to + worry about this number since the &man.pty.4; driver is + <quote>auto-cloning</quote>; you simply use the line + <literal>device pty</literal> in your configuration file.</para> + </note> + + </sect3> + + <sect3> + <title><varname>kern.ipc.somaxconn</varname></title> + + <indexterm> + <primary><varname>kern.ipc.somaxconn</varname></primary> + </indexterm> + + <para>The <varname>kern.ipc.somaxconn</varname> sysctl variable + limits the size of the listen queue for accepting new TCP + connections. The default value of <literal>128</literal> is + typically too low for robust handling of new connections in a + heavily loaded web server environment. For such environments, it + is recommended to increase this value to <literal>1024</literal> or + higher. The service daemon may itself limit the listen queue size + (e.g. &man.sendmail.8;, or <application>Apache</application>) but + will often have a directive in its configuration file to adjust + the queue size. Large listen queues also do a better job of + avoiding Denial of Service (<abbrev>DoS</abbrev>) attacks.</para> + </sect3> + + </sect2> + <sect2 xml:id="nmbclusters"> + <title>Network Limits</title> + + <para>The <literal>NMBCLUSTERS</literal> kernel configuration + option dictates the amount of network Mbufs available to the + system. A heavily-trafficked server with a low number of Mbufs + will hinder &os;'s ability. Each cluster represents + approximately 2 K of memory, so a value of 1024 represents 2 + megabytes of kernel memory reserved for network buffers. A + simple calculation can be done to figure out how many are + needed. If you have a web server which maxes out at 1000 + simultaneous connections, and each connection eats a 16 K receive + and 16 K send buffer, you need approximately 32 MB worth of + network buffers to cover the web server. A good rule of thumb is + to multiply by 2, so 2x32 MB / 2 KB = + 64 MB / 2 kB = 32768. We recommend + values between 4096 and 32768 for machines with greater amounts + of memory. Under no circumstances should you specify an + arbitrarily high value for this parameter as it could lead to a + boot time crash. The <option>-m</option> option to + &man.netstat.1; may be used to observe network cluster + use.</para> + + <para><varname>kern.ipc.nmbclusters</varname> loader tunable should + be used to tune this at boot time. Only older versions of &os; + will require you to use the <literal>NMBCLUSTERS</literal> kernel + &man.config.8; option.</para> + + <para>For busy servers that make extensive use of the + &man.sendfile.2; system call, it may be necessary to increase + the number of &man.sendfile.2; buffers via the + <literal>NSFBUFS</literal> kernel configuration option or by + setting its value in <filename>/boot/loader.conf</filename> + (see &man.loader.8; for details). A common indicator that + this parameter needs to be adjusted is when processes are seen + in the <literal>sfbufa</literal> state. The sysctl + variable <varname>kern.ipc.nsfbufs</varname> is a read-only + glimpse at the kernel configured variable. This parameter + nominally scales with <varname>kern.maxusers</varname>, + however it may be necessary to tune accordingly.</para> + + <important> + <para>Even though a socket has been marked as non-blocking, + calling &man.sendfile.2; on the non-blocking socket may + result in the &man.sendfile.2; call blocking until enough + <literal>struct sf_buf</literal>'s are made + available.</para> + </important> + + <sect3> + <title><varname>net.inet.ip.portrange.*</varname></title> + + <indexterm> + <primary>net.inet.ip.portrange.*</primary> + </indexterm> + + <para>The <varname>net.inet.ip.portrange.*</varname> sysctl + variables control the port number ranges automatically bound to TCP + and UDP sockets. There are three ranges: a low range, a default + range, and a high range. Most network programs use the default + range which is controlled by the + <varname>net.inet.ip.portrange.first</varname> and + <varname>net.inet.ip.portrange.last</varname>, which default to + 1024 and 5000, respectively. Bound port ranges are used for + outgoing connections, and it is possible to run the system out of + ports under certain circumstances. This most commonly occurs + when you are running a heavily loaded web proxy. The port range + is not an issue when running servers which handle mainly incoming + connections, such as a normal web server, or has a limited number + of outgoing connections, such as a mail relay. For situations + where you may run yourself out of ports, it is recommended to + increase <varname>net.inet.ip.portrange.last</varname> modestly. + A value of <literal>10000</literal>, <literal>20000</literal> or + <literal>30000</literal> may be reasonable. You should also + consider firewall effects when changing the port range. Some + firewalls may block large ranges of ports (usually low-numbered + ports) and expect systems to use higher ranges of ports for + outgoing connections — for this reason it is not recommended that + <varname>net.inet.ip.portrange.first</varname> be lowered.</para> + </sect3> + + <sect3> + <title>TCP Bandwidth Delay Product</title> + + <indexterm> + <primary>TCP Bandwidth Delay Product Limiting</primary> + <secondary><varname>net.inet.tcp.inflight.enable</varname></secondary> + </indexterm> + + <para>The TCP Bandwidth Delay Product Limiting is similar to + TCP/Vegas in NetBSD. It can be + enabled by setting <varname>net.inet.tcp.inflight.enable</varname> + sysctl variable to <literal>1</literal>. The system will attempt + to calculate the bandwidth delay product for each connection and + limit the amount of data queued to the network to just the amount + required to maintain optimum throughput.</para> + + <para>This feature is useful if you are serving data over modems, + Gigabit Ethernet, or even high speed WAN links (or any other link + with a high bandwidth delay product), especially if you are also + using window scaling or have configured a large send window. If + you enable this option, you should also be sure to set + <varname>net.inet.tcp.inflight.debug</varname> to + <literal>0</literal> (disable debugging), and for production use + setting <varname>net.inet.tcp.inflight.min</varname> to at least + <literal>6144</literal> may be beneficial. However, note that + setting high minimums may effectively disable bandwidth limiting + depending on the link. The limiting feature reduces the amount of + data built up in intermediate route and switch packet queues as + well as reduces the amount of data built up in the local host's + interface queue. With fewer packets queued up, interactive + connections, especially over slow modems, will also be able to + operate with lower <emphasis>Round Trip Times</emphasis>. However, + note that this feature only effects data transmission (uploading + / server side). It has no effect on data reception (downloading). + </para> + + <para>Adjusting <varname>net.inet.tcp.inflight.stab</varname> is + <emphasis>not</emphasis> recommended. This parameter defaults to + 20, representing 2 maximal packets added to the bandwidth delay + product window calculation. The additional window is required to + stabilize the algorithm and improve responsiveness to changing + conditions, but it can also result in higher ping times over slow + links (though still much lower than you would get without the + inflight algorithm). In such cases, you may wish to try reducing + this parameter to 15, 10, or 5; and may also have to reduce + <varname>net.inet.tcp.inflight.min</varname> (for example, to + 3500) to get the desired effect. Reducing these parameters + should be done as a last resort only.</para> + + </sect3> + </sect2> + + <sect2> + <title>Virtual Memory</title> + + <sect3> + <title><varname>kern.maxvnodes</varname></title> + + <para>A vnode is the internal representation of a file or + directory. So increasing the number of vnodes available to + the operating system cuts down on disk I/O. Normally this + is handled by the operating system and does not need to be + changed. In some cases where disk I/O is a bottleneck and + the system is running out of vnodes, this setting will need + to be increased. The amount of inactive and free RAM will + need to be taken into account.</para> + + <para>To see the current number of vnodes in use:</para> + + <programlisting>&prompt.root; sysctl vfs.numvnodes +vfs.numvnodes: 91349</programlisting> + + <para>To see the maximum vnodes:</para> + + <programlisting>&prompt.root; sysctl kern.maxvnodes +kern.maxvnodes: 100000</programlisting> + + <para>If the current vnode usage is near the maximum, increasing + <varname>kern.maxvnodes</varname> by a value of 1,000 is + probably a good idea. Keep an eye on the number of + <varname>vfs.numvnodes</varname>. If it climbs up to the + maximum again, <varname>kern.maxvnodes</varname> will need to + be increased further. A shift in your memory usage as + reported by &man.top.1; should be visible. More memory should + be active.</para> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="adding-swap-space"> + <title>Adding Swap Space</title> + + <para>No matter how well you plan, sometimes a system does not run + as you expect. If you find you need more swap space, it is + simple enough to add. You have three ways to increase swap + space: adding a new hard drive, enabling swap over NFS, and + creating a swap file on an existing partition.</para> + + <para>For information on how to encrypt swap space, what options + for this task exist and why it should be done, please refer to + <xref linkend="swap-encrypting"/> of the Handbook.</para> + + <sect2 xml:id="new-drive-swap"> + <title>Swap on a New Hard Drive</title> + + <para>The best way to add swap, of course, is to use this as an + excuse to add another hard drive. You can always use another + hard drive, after all. If you can do this, go reread the + discussion of swap space + in <xref linkend="configtuning-initial"/> + of the Handbook for some suggestions on how to best + arrange your swap.</para> + </sect2> + + <sect2 xml:id="nfs-swap"> + <title>Swapping over NFS</title> + + <para>Swapping over NFS is only recommended if you do not have a + local hard disk to swap to; NFS swapping will be limited + by the available network bandwidth and puts an additional + burden on the NFS server.</para> + </sect2> + + <sect2 xml:id="create-swapfile"> + <title>Swapfiles</title> + + <para>You can create a file of a specified size to use as a swap + file. In our example here we will use a 64MB file called + <filename>/usr/swap0</filename>. You can use any name you + want, of course.</para> + + <example> + <title>Creating a Swapfile on &os;</title> + + <orderedlist> + <listitem> + <para>Be certain that your kernel configuration includes + the memory disk driver (&man.md.4;). It is default in + <filename>GENERIC</filename> kernel.</para> + + <programlisting>device md # Memory "disks"</programlisting> + </listitem> + + <listitem> + <para>Create a swapfile (<filename>/usr/swap0</filename>):</para> + + <screen>&prompt.root; <userinput>dd if=/dev/zero of=/usr/swap0 bs=1024k count=64</userinput></screen> + </listitem> + + <listitem> + <para>Set proper permissions on (<filename>/usr/swap0</filename>):</para> + + <screen>&prompt.root; <userinput>chmod 0600 /usr/swap0</userinput></screen> + </listitem> + + <listitem> + <para>Enable the swap file in <filename>/etc/rc.conf</filename>:</para> + + <programlisting>swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired.</programlisting> + </listitem> + + <listitem> + + <para>Reboot the machine or to enable the swap file immediately, + type:</para> + + <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /usr/swap0 -u 0 && swapon /dev/md0</userinput></screen> + </listitem> + </orderedlist> + + </example> + </sect2> + </sect1> + + <sect1 xml:id="acpi-overview"> + <info><title>Power and Resource Management</title> + <authorgroup> + <author><personname><firstname>Hiten</firstname><surname>Pandya</surname></personname><contrib>Written by </contrib></author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname></author> + </authorgroup> + </info> + + + + <para>It is very important to utilize hardware resources in an + efficient manner. Before <acronym>ACPI</acronym> was introduced, + it was very difficult and inflexible for operating systems to manage + the power usage and thermal properties of a system. The hardware was + controlled by some sort of <acronym>BIOS</acronym> embedded + interface, such as <emphasis>Plug and Play BIOS (PNPBIOS)</emphasis>, or + <emphasis>Advanced Power Management (APM)</emphasis> and so on. + Power and Resource Management is one of the key components of a modern + operating system. For example, you may want an operating system to + monitor system limits (and possibly alert you) in case your system + temperature increased unexpectedly.</para> + + <para>In this section of the &os; Handbook, we will provide + comprehensive information about <acronym>ACPI</acronym>. References + will be provided for further reading at the end.</para> + + <sect2 xml:id="acpi-intro"> + <title>What Is ACPI?</title> + + <indexterm> + <primary>ACPI</primary> + </indexterm> + + <indexterm> + <primary>APM</primary> + </indexterm> + + <para>Advanced Configuration and Power Interface + (<acronym>ACPI</acronym>) is a standard written by + an alliance of vendors to provide a standard interface for + hardware resources and power management (hence the name). + It is a key element in <emphasis>Operating System-directed + configuration and Power Management</emphasis>, i.e.: it provides + more control and flexibility to the operating system + (<acronym>OS</acronym>). + Modern systems <quote>stretched</quote> the limits of the + current Plug and Play interfaces prior to the introduction of + <acronym>ACPI</acronym>. <acronym>ACPI</acronym> is the direct + successor to <acronym>APM</acronym> + (Advanced Power Management).</para> + </sect2> + + <sect2 xml:id="acpi-old-spec"> + <title>Shortcomings of Advanced Power Management (APM)</title> + + <para>The <emphasis>Advanced Power Management (APM)</emphasis> + facility controls the power usage of a system based on its + activity. The APM BIOS is supplied by the (system) vendor and + it is specific to the hardware platform. An APM driver in the + OS mediates access to the <emphasis>APM Software Interface</emphasis>, + which allows management of power levels.</para> + + <para>There are four major problems in APM. Firstly, power + management is done by the (vendor-specific) BIOS, and the OS + does not have any knowledge of it. One example of this, is when + the user sets idle-time values for a hard drive in the APM BIOS, + that when exceeded, it (BIOS) would spin down the hard drive, + without the consent of the OS. Secondly, the APM logic is + embedded in the BIOS, and it operates outside the scope of the + OS. This means users can only fix problems in their APM BIOS by + flashing a new one into the ROM; which is a very dangerous + procedure with the potential to leave the system in an + unrecoverable state if it fails. Thirdly, APM is a vendor-specific + technology, which means that there is a lot of parity + (duplication of efforts) and bugs found in one vendor's BIOS, + may not be solved in others. Last but not the least, the APM + BIOS did not have enough room to implement a sophisticated power + policy, or one that can adapt very well to the purpose of the + machine.</para> + + <para><emphasis>Plug and Play BIOS (PNPBIOS)</emphasis> was + unreliable in many situations. PNPBIOS is 16-bit technology, + so the OS has to use 16-bit emulation in order to + <quote>interface</quote> with PNPBIOS methods.</para> + + <para>The &os; <acronym>APM</acronym> driver is documented in + the &man.apm.4; manual page.</para> + </sect2> + + <sect2 xml:id="acpi-config"> + <title>Configuring <acronym>ACPI</acronym></title> + + <para>The <filename>acpi.ko</filename> driver is loaded by default + at start up by the &man.loader.8; and should <emphasis>not</emphasis> + be compiled into the kernel. The reasoning behind this is that modules + are easier to work with, say if switching to another <filename>acpi.ko</filename> + without doing a kernel rebuild. This has the advantage of making testing easier. + Another reason is that starting <acronym>ACPI</acronym> after a system has been + brought up is not too useful, and in some cases can be fatal. In doubt, just + disable <acronym>ACPI</acronym> all together. This driver should not and can not + be unloaded because the system bus uses it for various hardware interactions. + <acronym>ACPI</acronym> can be disabled with the &man.acpiconf.8; utility. + In fact most of the interaction with <acronym>ACPI</acronym> can be done via + &man.acpiconf.8;. Basically this means, if anything about <acronym>ACPI</acronym> + is in the &man.dmesg.8; output, then most likely it is already running.</para> + + <note><para><acronym>ACPI</acronym> and <acronym>APM</acronym> cannot coexist and + should be used separately. The last one to load will terminate if the driver + notices the other running.</para></note> + + <para>In the simplest form, <acronym>ACPI</acronym> can be used to put the + system into a sleep mode with &man.acpiconf.8;, the <option>-s</option> + flag, and a <literal>1-5</literal> option. Most users will only need + <literal>1</literal>. Option <literal>5</literal> will do a soft-off + which is the same action as:</para> + + <screen>&prompt.root; <userinput>halt -p</userinput></screen> + + <para>The other options are available. Check out the &man.acpiconf.8; + manual page for more information.</para> + </sect2> + </sect1> + + <sect1 xml:id="ACPI-debug"> + <info><title>Using and Debugging &os; <acronym>ACPI</acronym></title> + <authorgroup> + <author><personname><firstname>Nate</firstname><surname>Lawson</surname></personname><contrib>Written by </contrib></author> + </authorgroup> + <authorgroup> + <author><personname><firstname>Peter</firstname><surname>Schultz</surname></personname><contrib>With contributions from </contrib></author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname></author> + </authorgroup> + </info> + + + + <indexterm> + <primary>ACPI</primary> + <secondary>problems</secondary> + </indexterm> + + <para><acronym>ACPI</acronym> is a fundamentally new way of + discovering devices, managing power usage, and providing + standardized access to various hardware previously managed + by the <acronym>BIOS</acronym>. Progress is being made toward + <acronym>ACPI</acronym> working on all systems, but bugs in some + motherboards' <firstterm><acronym>ACPI</acronym> Machine + Language</firstterm> (<acronym>AML</acronym>) bytecode, + incompleteness in &os;'s kernel subsystems, and bugs in the &intel; + <acronym>ACPI-CA</acronym> interpreter continue to appear.</para> + + <para>This document is intended to help you assist the &os; + <acronym>ACPI</acronym> maintainers in identifying the root cause + of problems you observe and debugging and developing a solution. + Thanks for reading this and we hope we can solve your system's + problems.</para> + + <sect2 xml:id="ACPI-submitdebug"> + <title>Submitting Debugging Information</title> + + <note> + <para>Before submitting a problem, be sure you are running the latest + <acronym>BIOS</acronym> version and, if available, embedded + controller firmware version.</para> + </note> + + <para>For those of you that want to submit a problem right away, + please send the following information to + <link xlink:href="mailto:freebsd-acpi@FreeBSD.org"> + freebsd-acpi@FreeBSD.org</link>:</para> + + <itemizedlist> + <listitem> + <para>Description of the buggy behavior, including system type + and model and anything that causes the bug to appear. Also, + please note as accurately as possible when the bug began + occurring if it is new for you.</para> + </listitem> + + <listitem> + <para>The &man.dmesg.8; output after <command>boot + -v</command>, including any error messages + generated by you exercising the bug.</para> + </listitem> + + <listitem> + <para>The &man.dmesg.8; output from <command>boot + -v</command> with <acronym>ACPI</acronym> + disabled, if disabling it helps fix the problem.</para> + </listitem> + + <listitem> + <para>Output from <command>sysctl hw.acpi</command>. This is also + a good way of figuring out what features your system + offers.</para> + </listitem> + + <listitem> + <para><acronym>URL</acronym> where your + <firstterm><acronym>ACPI</acronym> Source Language</firstterm> + (<acronym>ASL</acronym>) + can be found. Do <emphasis>not</emphasis> send the + <acronym>ASL</acronym> directly to the list as it can be + very large. Generate a copy of your <acronym>ASL</acronym> + by running this command:</para> + + <screen>&prompt.root; <userinput>acpidump -t -d > name-system.asl</userinput></screen> + + <para>(Substitute your login name for + <replaceable>name</replaceable> and manufacturer/model for + <replaceable>system</replaceable>. Example: + <filename>njl-FooCo6000.asl</filename>)</para> + </listitem> + </itemizedlist> + + <para>Most of the developers watch the &a.current; + but please submit problems to &a.acpi.name; to be sure it is + seen. Please be patient, all of us have full-time jobs + elsewhere. If your bug is not immediately apparent, we will + probably ask you to submit a <acronym>PR</acronym> via + &man.send-pr.1;. When entering a <acronym>PR</acronym>, please + include the same information as requested above. This will help + us track the problem and resolve it. Do not send a + <acronym>PR</acronym> without emailing &a.acpi.name; first as we use + <acronym>PR</acronym>s as reminders of existing problems, not a + reporting mechanism. It is likely that your problem has been + reported by someone before.</para> + </sect2> + + <sect2 xml:id="ACPI-background"> + <title>Background</title> + + <indexterm> + <primary>ACPI</primary> + </indexterm> + + <para><acronym>ACPI</acronym> is present in all modern computers + that conform to the ia32 (x86), ia64 (Itanium), and amd64 (AMD) + architectures. The full standard has many features including + <acronym>CPU</acronym> performance management, power planes + control, thermal zones, various battery systems, embedded + controllers, and bus enumeration. Most systems implement less + than the full standard. For instance, a desktop system usually + only implements the bus enumeration parts while a laptop might + have cooling and battery management support as well. Laptops + also have suspend and resume, with their own associated + complexity.</para> + + <para>An <acronym>ACPI</acronym>-compliant system has various + components. The <acronym>BIOS</acronym> and chipset vendors + provide various fixed tables (e.g., <acronym>FADT</acronym>) + in memory that specify things like the <acronym>APIC</acronym> + map (used for <acronym>SMP</acronym>), config registers, and + simple configuration values. Additionally, a table of bytecode + (the <firstterm>Differentiated System Description Table</firstterm> + <acronym>DSDT</acronym>) is provided that specifies a + tree-like name space of devices and methods.</para> + + <para>The <acronym>ACPI</acronym> driver must parse the fixed + tables, implement an interpreter for the bytecode, and modify + device drivers and the kernel to accept information from the + <acronym>ACPI</acronym> subsystem. For &os;, &intel; has + provided an interpreter (<acronym>ACPI-CA</acronym>) that is + shared with Linux and NetBSD. The path to the + <acronym>ACPI-CA</acronym> source code is + <filename>src/sys/contrib/dev/acpica</filename>. + The glue code that allows <acronym>ACPI-CA</acronym> to work on + &os; is in + <filename>src/sys/dev/acpica/Osd</filename>. Finally, drivers + that implement various <acronym>ACPI</acronym> devices are found + in + <filename>src/sys/dev/acpica</filename>.</para> + </sect2> + + <sect2 xml:id="ACPI-comprob"> + <title>Common Problems</title> + + <indexterm> + <primary>ACPI</primary> + <secondary>problems</secondary> + </indexterm> + + <para>For <acronym>ACPI</acronym> to work correctly, all the parts + have to work correctly. Here are some common problems, in order + of frequency of appearance, and some possible workarounds or + fixes.</para> + + <sect3> + <title>Mouse Issues</title> + + <para>In some cases, resuming from a suspend operation will + cause the mouse to fail. A known work around is to add + <literal>hint.psm.0.flags="0x3000"</literal> to the + <filename>/boot/loader.conf</filename> file. If this + does not work then please consider sending a bug report + as described above.</para> + </sect3> + + <sect3> + <title>Suspend/Resume</title> + + <para><acronym>ACPI</acronym> has three suspend to + <acronym>RAM</acronym> (<acronym>STR</acronym>) states, + <literal>S1</literal>-<literal>S3</literal>, and one suspend + to disk state (<literal>STD</literal>), called + <literal>S4</literal>. <literal>S5</literal> is + <quote>soft off</quote> and is the normal state your system + is in when plugged in but not powered up. + <literal>S4</literal> can actually be implemented two separate + ways. <literal>S4</literal><acronym>BIOS</acronym> is a + <acronym>BIOS</acronym>-assisted suspend to disk. + <literal>S4</literal><acronym>OS</acronym> is implemented + entirely by the operating system.</para> + + <para>Start by checking <command>sysctl hw.acpi</command> + for the suspend-related items. Here + are the results for a Thinkpad:</para> + + <screen>hw.acpi.supported_sleep_state: S3 S4 S5 +hw.acpi.s4bios: 0</screen> + + <para>This means that we can use <command>acpiconf -s</command> + to test <literal>S3</literal>, + <literal>S4</literal><acronym>OS</acronym>, and + <literal>S5</literal>. If <option>s4bios</option> was one + (<literal>1</literal>), we would have + <literal>S4</literal><acronym>BIOS</acronym> + support instead of <literal>S4</literal> + <acronym>OS</acronym>.</para> + + <para>When testing suspend/resume, start with + <literal>S1</literal>, if supported. This state is most + likely to work since it does not require much driver support. + No one has implemented <literal>S2</literal> but if you have + it, it is similar to <literal>S1</literal>. The next thing + to try is <literal>S3</literal>. This is the deepest + <acronym>STR</acronym> state and requires a lot of driver + support to properly reinitialize your hardware. If you have + problems resuming, feel free to email the &a.acpi.name; list but + do not expect the problem to be resolved since there are a lot + of drivers/hardware that need more testing and work.</para> + + <para>To help isolate the problem, remove as many drivers from + your kernel as possible. If it works, you can narrow down + which driver is the problem by loading drivers until it fails + again. Typically binary drivers like + <filename>nvidia.ko</filename>, X11 + display drivers, and <acronym>USB</acronym> will have the most + problems while Ethernet interfaces usually work fine. If you + can properly load/unload the drivers, you can automate this by + putting the appropriate commands in + <filename>/etc/rc.suspend</filename> and + <filename>/etc/rc.resume</filename>. There is a + commented-out example for unloading and loading a driver. Try + setting <option>hw.acpi.reset_video</option> to zero (<literal>0</literal>) if + your display is messed up after resume. Try setting longer or + shorter values for <option>hw.acpi.sleep_delay</option> to see + if that helps.</para> + + <para>Another thing to try is load a recent Linux distribution + with <acronym>ACPI</acronym> support and test their + suspend/resume support on the same hardware. If it works + on Linux, it is likely a &os; driver problem and narrowing down + which driver causes the problems will help us fix the problem. + Note that the <acronym>ACPI</acronym> maintainers do not + usually maintain other drivers (e.g sound, + <acronym>ATA</acronym>, etc.) so any work done on tracking + down a driver problem should probably eventually be posted + to the &a.current.name; list and mailed to the driver + maintainer. If you are feeling adventurous, go ahead and + start putting some debugging &man.printf.3;s in a problematic + driver to track down where in its resume function it + hangs.</para> + + <para>Finally, try disabling <acronym>ACPI</acronym> and + enabling <acronym>APM</acronym> instead. If suspend/resume + works with <acronym>APM</acronym>, you may be better off + sticking with <acronym>APM</acronym>, especially on older + hardware (pre-2000). It took vendors a while to get + <acronym>ACPI</acronym> support correct and older hardware is + more likely to have <acronym>BIOS</acronym> problems with + <acronym>ACPI</acronym>.</para> + </sect3> + + <sect3> + <title>System Hangs (temporary or permanent)</title> + + <para>Most system hangs are a result of lost interrupts or an + interrupt storm. Chipsets have a lot of problems based on how + the <acronym>BIOS</acronym> configures interrupts before boot, + correctness of the <acronym>APIC</acronym> + (<acronym>MADT</acronym>) table, and routing of the + <firstterm>System Control Interrupt</firstterm> + (<acronym>SCI</acronym>).</para> + + <indexterm> + <primary>interrupt storms</primary> + </indexterm> + + <para>Interrupt storms can be distinguished from lost interrupts + by checking the output of <command>vmstat -i</command> + and looking at the line that has + <literal>acpi0</literal>. If the counter is increasing at more + than a couple per second, you have an interrupt storm. If the + system appears hung, try breaking to <acronym>DDB</acronym> + (<keycombo action="simul"><keycap>CTRL</keycap> + <keycap>ALT</keycap><keycap>ESC</keycap></keycombo> on + console) and type <literal>show interrupts</literal>.</para> + + <indexterm> + <primary>APIC</primary> + <secondary>disabling</secondary> + </indexterm> + + <para>Your best hope when dealing with interrupt problems is to + try disabling <acronym>APIC</acronym> support with + <literal>hint.apic.0.disabled="1"</literal> in + <filename>loader.conf</filename>.</para> + </sect3> + + <sect3> + <title>Panics</title> + + <para>Panics are relatively rare for <acronym>ACPI</acronym> and + are the top priority to be fixed. The first step is to + isolate the steps to reproduce the panic (if possible) + and get a backtrace. Follow the advice for enabling + <literal>options DDB</literal> and setting up a serial console + (see <xref linkend="serialconsole-ddb"/>) + or setting up a &man.dump.8; partition. You can get a + backtrace in <acronym>DDB</acronym> with + <literal>tr</literal>. If you have to handwrite the + backtrace, be sure to at least get the lowest five (5) and top + five (5) lines in the trace.</para> + + <para>Then, try to isolate the problem by booting with + <acronym>ACPI</acronym> disabled. If that works, you can + isolate the <acronym>ACPI</acronym> subsystem by using various + values of <option>debug.acpi.disable</option>. See the + &man.acpi.4; manual page for some examples.</para> + </sect3> + + <sect3> + <title>System Powers Up After Suspend or Shutdown</title> + <para>First, try setting + <literal>hw.acpi.disable_on_poweroff="0"</literal> + in &man.loader.conf.5;. This keeps <acronym>ACPI</acronym> + from disabling various events during the shutdown process. + Some systems need this value set to <literal>1</literal> (the + default) for the same reason. This usually fixes + the problem of a system powering up spontaneously after a + suspend or poweroff.</para> + </sect3> + + <sect3> + <title>Other Problems</title> + + <para>If you have other problems with <acronym>ACPI</acronym> + (working with a docking station, devices not detected, etc.), + please email a description to the mailing list as well; + however, some of these issues may be related to unfinished + parts of the <acronym>ACPI</acronym> subsystem so they might + take a while to be implemented. Please be patient and + prepared to test patches we may send you.</para> + </sect3> + </sect2> + + <sect2 xml:id="ACPI-aslanddump"> + <title><acronym>ASL</acronym>, <command>acpidump</command>, and + <acronym>IASL</acronym></title> + + <indexterm> + <primary>ACPI</primary> + <secondary>ASL</secondary> + </indexterm> + + <para>The most common problem is the <acronym>BIOS</acronym> + vendors providing incorrect (or outright buggy!) bytecode. This + is usually manifested by kernel console messages like + this:</para> + + <screen>ACPI-1287: *** Error: Method execution failed [\\_SB_.PCI0.LPC0.FIGD._STA] \\ +(Node 0xc3f6d160), AE_NOT_FOUND</screen> + + <para>Often, you can resolve these problems by updating your + <acronym>BIOS</acronym> to the latest revision. Most console + messages are harmless but if you have other problems like + battery status not working, they are a good place to start + looking for problems in the <acronym>AML</acronym>. The + bytecode, known as <acronym>AML</acronym>, is compiled from a + source language called <acronym>ASL</acronym>. The + <acronym>AML</acronym> is found in the table known as the + <acronym>DSDT</acronym>. To get a copy of your + <acronym>ASL</acronym>, use &man.acpidump.8;. You should use + both the <option>-t</option> (show contents of the fixed tables) + and <option>-d</option> (disassemble <acronym>AML</acronym> to + <acronym>ASL</acronym>) options. See the + <link linkend="ACPI-submitdebug">Submitting Debugging + Information</link> section for an example syntax.</para> + + <para>The simplest first check you can do is to recompile your + <acronym>ASL</acronym> to check for errors. Warnings can + usually be ignored but errors are bugs that will usually prevent + <acronym>ACPI</acronym> from working correctly. To recompile + your <acronym>ASL</acronym>, issue the following command:</para> + + <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen> + </sect2> + + <sect2 xml:id="ACPI-fixasl"> + <title>Fixing Your <acronym>ASL</acronym></title> + + <indexterm> + <primary>ACPI</primary> + <secondary>ASL</secondary> + </indexterm> + + <para>In the long run, our goal is for almost everyone to have + <acronym>ACPI</acronym> work without any user intervention. At + this point, however, we are still developing workarounds for + common mistakes made by the <acronym>BIOS</acronym> vendors. + The µsoft; interpreter (<filename>acpi.sys</filename> and + <filename>acpiec.sys</filename>) does not strictly check for + adherence to the standard, and thus many <acronym>BIOS</acronym> + vendors who only test <acronym>ACPI</acronym> under &windows; + never fix their <acronym>ASL</acronym>. We hope to continue to + identify and document exactly what non-standard behavior is + allowed by µsoft;'s interpreter and replicate it so &os; can + work without forcing users to fix the <acronym>ASL</acronym>. + As a workaround and to help us identify behavior, you can fix + the <acronym>ASL</acronym> manually. If this works for you, + please send a &man.diff.1; of the old and new + <acronym>ASL</acronym> so we can possibly work around the buggy + behavior in <acronym>ACPI-CA</acronym> and thus make your fix + unnecessary.</para> + + <indexterm> + <primary>ACPI</primary> + <secondary>error messages</secondary> + </indexterm> + + <para>Here is a list of common error messages, their cause, and + how to fix them:</para> + + <sect3> + <title>_OS dependencies</title> + + <para>Some <acronym>AML</acronym> assumes the world consists of + various &windows; versions. You can tell &os; to claim it is + any <acronym>OS</acronym> to see if this fixes problems you + may have. An easy way to override this is to set + <literal>hw.acpi.osname="Windows 2001"</literal> + in <filename>/boot/loader.conf</filename> or other similar + strings you find in the <acronym>ASL</acronym>.</para> + </sect3> + + <sect3> + <title>Missing Return statements</title> + + <para>Some methods do not explicitly return a value as the + standard requires. While <acronym>ACPI-CA</acronym> + does not handle this, &os; has a workaround that allows it to + return the value implicitly. You can also add explicit + Return statements where required if you know what value should + be returned. To force <command>iasl</command> to compile the + <acronym>ASL</acronym>, use the <option>-f</option> + flag.</para> + </sect3> + + <sect3> + <title>Overriding the Default <acronym>AML</acronym></title> + + <para>After you customize <filename>your.asl</filename>, you + will want to compile it, run:</para> + + <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen> + + <para>You can add the <option>-f</option> flag to force creation + of the <acronym>AML</acronym>, even if there are errors during + compilation. Remember that some errors (e.g., missing Return + statements) are automatically worked around by the + interpreter.</para> + + <para><filename>DSDT.aml</filename> is the default output + filename for <command>iasl</command>. You can load this + instead of your <acronym>BIOS</acronym>'s buggy copy (which + is still present in flash memory) by editing + <filename>/boot/loader.conf</filename> as + follows:</para> + + <programlisting>acpi_dsdt_load="YES" +acpi_dsdt_name="/boot/DSDT.aml"</programlisting> + + <para>Be sure to copy your <filename>DSDT.aml</filename> to the + <filename>/boot</filename> directory.</para> + </sect3> + </sect2> + + <sect2 xml:id="ACPI-debugoutput"> + <title>Getting Debugging Output From + <acronym>ACPI</acronym></title> + + <indexterm> + <primary>ACPI</primary> + <secondary>problems</secondary> + </indexterm> + + <indexterm> + <primary>ACPI</primary> + <secondary>debugging</secondary> + </indexterm> + + <para>The <acronym>ACPI</acronym> driver has a very flexible + debugging facility. It allows you to specify a set of subsystems + as well as the level of verbosity. The subsystems you wish to + debug are specified as <quote>layers</quote> and are broken down + into <acronym>ACPI-CA</acronym> components (ACPI_ALL_COMPONENTS) + and <acronym>ACPI</acronym> hardware support (ACPI_ALL_DRIVERS). + The verbosity of debugging output is specified as the + <quote>level</quote> and ranges from ACPI_LV_ERROR (just report + errors) to ACPI_LV_VERBOSE (everything). The + <quote>level</quote> is a bitmask so multiple options can be set + at once, separated by spaces. In practice, you will want to use + a serial console to log the output if it is so long + it flushes the console message buffer. A full list of the + individual layers and levels is found in the &man.acpi.4; manual + page.</para> + + <para>Debugging output is not enabled by default. To enable it, + add <literal>options ACPI_DEBUG</literal> to your kernel configuration file + if <acronym>ACPI</acronym> is compiled into the kernel. You can + add <literal>ACPI_DEBUG=1</literal> to your + <filename>/etc/make.conf</filename> to enable it globally. If + it is a module, you can recompile just your + <filename>acpi.ko</filename> module as follows:</para> + + <screen>&prompt.root; <userinput>cd /sys/modules/acpi/acpi +&& make clean && +make ACPI_DEBUG=1</userinput></screen> + + <para>Install <filename>acpi.ko</filename> in + <filename>/boot/kernel</filename> and add your + desired level and layer to <filename>loader.conf</filename>. + This example enables debug messages for all + <acronym>ACPI-CA</acronym> components and all + <acronym>ACPI</acronym> hardware drivers + (<acronym>CPU</acronym>, <acronym>LID</acronym>, etc.) It will + only output error messages, the least verbose level.</para> + + <programlisting>debug.acpi.layer="ACPI_ALL_COMPONENTS ACPI_ALL_DRIVERS" +debug.acpi.level="ACPI_LV_ERROR"</programlisting> + + <para>If the information you want is triggered by a specific event + (say, a suspend and then resume), you can leave out changes to + <filename>loader.conf</filename> and instead use + <command>sysctl</command> to specify the layer and level after + booting and preparing your system for the specific event. The + <command>sysctl</command>s are named the same as the tunables + in <filename>loader.conf</filename>.</para> + </sect2> + + <sect2 xml:id="ACPI-References"> + <title>References</title> + + <para>More information about <acronym>ACPI</acronym> may be found + in the following locations:</para> + + <itemizedlist> + <listitem> + <para>The &a.acpi;</para> + </listitem> + + <listitem> + <para>The <acronym>ACPI</acronym> Mailing List Archives + <uri xlink:href="http://lists.freebsd.org/pipermail/freebsd-acpi/">http://lists.freebsd.org/pipermail/freebsd-acpi/</uri></para> + </listitem> + + <listitem> + <para>The old <acronym>ACPI</acronym> Mailing List Archives + <uri xlink:href="http://home.jp.FreeBSD.org/mail-list/acpi-jp/">http://home.jp.FreeBSD.org/mail-list/acpi-jp/</uri></para> + </listitem> + + <listitem> + <para>The <acronym>ACPI</acronym> 2.0 Specification + <uri xlink:href="http://acpi.info/spec.htm">http://acpi.info/spec.htm</uri></para> + </listitem> + + <listitem> + <para>&os; Manual pages: &man.acpi.4;, + &man.acpi.thermal.4;, &man.acpidump.8;, &man.iasl.8;, + &man.acpidb.8;</para> + </listitem> + + <listitem> + <para><link xlink:href="http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt"> + <acronym>DSDT</acronym> debugging resource</link>. + (Uses Compaq as an example but generally useful.)</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> +</chapter> diff --git a/zh_TW.UTF-8/books/handbook/cutting-edge/Makefile b/zh_TW.UTF-8/books/handbook/cutting-edge/Makefile new file mode 100644 index 0000000000..6ca842754f --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/cutting-edge/Makefile @@ -0,0 +1,16 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# Original revision: 1.1 +# + +CHAPTERS= cutting-edge/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/zh_TW.UTF-8/books/handbook/cutting-edge/chapter.xml b/zh_TW.UTF-8/books/handbook/cutting-edge/chapter.xml new file mode 100644 index 0000000000..ef0d9a6c6d --- /dev/null +++ b/zh_TW.UTF-8/books/handbook/cutting-edge/chapter.xml @@ -0,0 +1,1535 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ + Original revision: 1.225 +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="cutting-edge"> + <info><title>更新、升級 FreeBSD</title> + <authorgroup> + <author><personname><firstname>Jim</firstname><surname>Mock</surname></personname><contrib>Restructured, reorganized, and parts updated by </contrib></author> + <!-- Mar 2000 --> + </authorgroup> + <authorgroup> + <author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname><contrib>Original work by </contrib></author> + <author><personname><firstname>Poul-Henning</firstname><surname>Kamp</surname></personname></author> + <author><personname><firstname>John</firstname><surname>Polstra</surname></personname></author> + <author><personname><firstname>Nik</firstname><surname>Clayton</surname></personname></author> + </authorgroup> + + </info> + + + + <sect1 xml:id="cutting-edge-synopsis"> + <title>概述</title> + + <para>&os; 是個持續發展的作業系統。對於喜歡追求新鮮、刺激的使用者而言， + 有很多方法可以使您的系統輕鬆更新為最新版。 + 注意：並非每個人都適合這麼做！ 本章主要是協助您決定到底要跟開發版本， + 或是要使用較穩定的釋出版。 + </para> + + <para>讀完這章，您將了解︰</para> + + <itemizedlist> + <listitem><para>&os.stable; 與 &os.current; 這兩分支的不同之處；</para> + </listitem> + <listitem><para>如何以 + <application>CSup</application>, + <application>CVSup</application>, + <application>CVS</application> 或 + <application>CTM</application> 來更新你的系統</para> + </listitem> + <listitem><para>如何以 <command>make buildworld</command> + 等指令來重新編譯、安裝整個 base system。</para> + </listitem> + + </itemizedlist> + + <para>在開始閱讀這章之前，您需要︰</para> + + <itemizedlist> + <listitem><para>先設好你的網路(<xref linkend="advanced-networking"/>)。 + </para> + </listitem> + <listitem><para>知道如何透過 port/package 安裝軟體(<xref linkend="ports"/>)。</para></listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="current-stable"> + <title>&os.current; vs. &os.stable;</title> + <indexterm><primary>-CURRENT</primary></indexterm> + <indexterm><primary>-STABLE</primary></indexterm> + + <para>FreeBSD 有兩個發展分支：&os.current; 及 + &os.stable;。本節將會陸續介紹，並介紹它們分別又是如何更新。 + 首先，先介紹 &os.current;，接著再介紹 &os.stable;。</para> + + <sect2 xml:id="current"> + <title>使用最新的 &os; CURRENT</title> + + <para>這裡再次強調，&os.current; 是 &os; 開發的 <quote>最前線</quote>。 + &os.current; 使用者須有較強的技術能力， + 而且應該要有能力自己解決困難的系統問題。 若您是 &os; 新手， + 那麼請在安裝前最好先三思。</para> + + <sect3> + <title>什麼是 &os.current;？</title> + <indexterm><primary>snapshot</primary></indexterm> + + <para>&os.current; 是 &os; 的最新版。它包含： + 仍在研發階段、實驗性質的修改、過渡時期的機制， + 這些東西在下一次正式 relase 的版本可能會有，也可能不會有的。 + 儘管有許多 &os; 開發者每天都會編譯 &os.current; source code， + 但有時這些原始碼是無法編譯成功。 雖然，這些問題通常會儘快解決， + 但 &os.current; 到底是帶來浩劫或是多了想要用的新功能、改善， + 這點主要取決於您更新原始碼的時機為何而定！</para> + </sect3> + + <sect3> + <title>誰需要 &os.current;？</title> + + <para>&os.current; 適合下列這三類人：</para> + + <orderedlist> + <listitem> + <para>&os; 社群成員：積極專注於 source tree 的某一部份， + 以及認為保持為 <quote>current(最新狀態)</quote> + 為絕對需求的人。</para> + </listitem> + + <listitem> + <para>&os; 社群成員：為了確保 &os.current; + 能夠儘可能地維持在最穩定的狀態， + 而主動花時間解決問題的測試者。 此外，還有對 &os; + 能提出具體建議以及改善方向，並提出 patch 修正檔的人。</para> + </listitem> + + <listitem> + <para>只是關心或者想參考(比如，只是<emphasis>閱讀</emphasis>， + 而非執行)的人。 + 這些人有時也會做些註解，或貢獻原始碼。</para> + </listitem> + </orderedlist> + </sect3> + + <sect3> + <title>&os.current; <emphasis>並不是</emphasis> 什麼？</title> + + <orderedlist> + <listitem> + <para>追求最新功能。 聽說裡面有些很酷的新功能， + 並希望成為您周圍的人中第一個嘗試的人， + 因此將 &os.current; 視為取得搶鮮版的捷徑。 + 儘管，您能夠因此首先瞭解到最新的功能， + 但這也意味著若出現新的 bug 時，您也是首當其衝。</para> + </listitem> + + <listitem> + <para>修復 bug 的速成法。 因為 &os.current; + 的任何版本在修復已知 bug 的同時，又可能會產生新的 bug。 + </para> + </listitem> + + <listitem> + <para>無所不在的 <quote>officially supported</quote>。 + 我們會盡力協助上述 &os.current; 的那三種類別的 + <quote>legitimate</quote> 使用者， + 但我們<emphasis>沒時間</emphasis>為他們提供技術支援。 + 這不代表我們很惡劣，或是不想幫助人(若是的話， + 我們也不會為 &os; 努力了) + ，實在是因為我們分身乏術，無法每天回答數百個問題， + <emphasis>而同時</emphasis>繼續開發 &os;。 + 可以確定的一點就是， + 在改善 &os; 或是回答大量有關實驗碼的問題之間， + 若要做個選擇的話，開發者會選擇前者。</para> + </listitem> + </orderedlist> + </sect3> + + <sect3> + <title>使用 &os.current;</title> + + <orderedlist> + <listitem> + <para>加入 &a.current.name;<indexterm><primary>-CURRENT</primary><secondary>using</secondary></indexterm> 及 &a.cvsall.name; 論壇。 + 這不單只是個建議，也是 <emphasis>必須</emphasis> 作的。 + 若您沒訂閱 <emphasis>&a.current.name;</emphasis> + ，那麼就會錯過別人對目前系統狀態的說明，而枯耗在別人已解的問題。 + 更重要的是，可能會錯失一些對己身所管系統安危相當重要的公告。 + </para> + + <para>在 &a.cvsall.name; 上則可以看到每個 commit 紀錄， + 因為這些記錄會連帶影響其他相關資訊。</para> + + <para>要訂閱這些論壇或其他論壇，請參考 &a.mailman.lists.link; + 並點選想訂閱的部分即可。 至於其他後續步驟如何進行， + 在那裡會有說明。</para> + </listitem> + + <listitem> + <para>從 &os; <link linkend="mirrors">mirror 站</link> + 取得原始碼。 有兩種方式可以達成：</para> + + <orderedlist> + <listitem> + <para>以 <link linkend="cvsup">csup</link><indexterm><primary><command>cvsup</command></primary></indexterm> 或 + <link linkend="cvsup">cvsup</link> 程式搭配位於 + <filename>/usr/share/examples/cvsup</filename> 檔名為 + <filename>standard-supfile</filename> 的 + <filename>supfile</filename>。 + 這是大家最常推薦的方式，因為它可以讓您把整個 tree 都抓回來， + 之後就只取有更新的部分即可。 + 此外，許多人會把 <command>csup</command> 或 + <command>cvsup</command> 放到 + <command>cron</command><indexterm><primary><command>cron</command></primary></indexterm> 以定期自動更新。 + 您須要自訂前述的 <filename>supfile</filename> 範例檔， + 並針對自身網路環境以調整 <link linkend="cvsup">csup</link> + 或 <link linkend="cvsup">cvsup</link><indexterm><primary>-CURRENT</primary><secondary>Syncing with <application>CVSup</application></secondary></indexterm> 相關設定。</para> + </listitem> + + <listitem> + <para>使用 <application>CTM</application><indexterm><primary>-CURRENT</primary><secondary>Syncing with CTM</secondary></indexterm> 工具。 若網路環境不佳 + (上網費用貴，或只能用 email 而已) + <application>CTM</application> 會比較適合您的需求。 + 然而，這也有一些爭議並且常抓到一些有問題的檔案。 因此， + 很少人會用它。 這也註定了不能長期依賴這個更新方式。 + 若是使用 9600 bps modem 或頻寬更大的上網者，建議使用 + <application>CVSup</application> + 。</para> + </listitem> + </orderedlist> + </listitem> + + <listitem> + <para>若抓 source code 是要用來跑的，而不僅只是看看而已， + 那麼就抓 <emphasis>整個</emphasis> &os.current;，而不要只抓部分。 + 因為大部分的 source code 都會相依到其他 source code 環節部分， + 若是您只編譯其中一部份，保證會很麻煩。</para> + + <para>在編譯 &os.current;<indexterm><primary>-CURRENT</primary><secondary>compiling</secondary></indexterm> 之前，請仔細閱讀 + <filename>/usr/src</filename> 內的 <filename>Makefile</filename>。 + 儘管只是升級部分東西而已，您至少也要先 <link linkend="makeworld"> + 裝新的 kernel 以及重新編譯 world</link>。 此外，多多閱讀 + &a.current; 以及 <filename>/usr/src/UPDATING</filename> + 也是必須的， + 才能知道目前進度是怎樣以及下一版會有什麼新東西。</para> + </listitem> + + <listitem> + <para>熱血！若您正在跑 &os.current;， + 我們很想知道您對於它的想法是什麼，尤其是加強哪些功能， + 或該修正哪些錯誤的建議。 如果您在建議時能附上相關程式碼的話， + 那真是太棒了！</para> + </listitem> + </orderedlist> + </sect3> + </sect2> + + <sect2 xml:id="stable"> + <title>使用最新的 &os; STABLE</title> + + <sect3> + <title>什麼是 &os.stable;？</title> + <indexterm><primary>-STABLE</primary></indexterm> + + <para>&os.stable; 是我們的開發分支，主要的發行版就由此而來。 + 這個分支會以不同速度作修改變化，並且假設這些是第一次進入 &os.current; + 進行測試。 然而，這 <emphasis>仍然</emphasis> 屬於開發中的分支， + 也就是說在某些時候，&os.stable; 可能會、也可能不會符合一些特殊需求。 + 它只不過是另一個開發分支而已，可能不太適合一般使用者。</para> + </sect3> + + <sect3> + <title>誰需要 &os.stable;？</title> + + <para>若您有興趣去追蹤、貢獻 FreeBSD 開發過程或作些貢獻， + 尤其是會跟 FreeBSD 接下來的 <quote>關鍵性</quote> 發行有關， + 應該考慮採用 &os.stable;。</para> + + <para>雖然安全漏洞的修補也會進入 &os.stable; 分支， + 但不必僅僅因此而 <emphasis>需要</emphasis> 去用 &os.stable;。 + FreeBSD 每項 security advisory(安全公告) + 都會解說如何去修復有受到影響的版本 + <footnote><para>然而，這也不一定是正確，我們不可能永遠支援 FreeBSD + 昔日的各種發行版本，儘管每個發行版發佈之後，都仍會持續支援數年之久。 + 若欲瞭解 FreeBSD 目前對於舊版的支援政策細節，請參閱 <link xlink:href="&url.base;/security/">http://www.FreeBSD.org/security/</link> + 。</para> + </footnote> + ，若僅因為安全因素而去採用開發分支，雖然會解決現有已知問題， + 但也可能帶來一些潛藏的問題。</para> + + <para>儘管我們盡力確保 &os.stable; 分支在任何時候均能正確編譯、運作， + 但沒人能夠擔保它隨時都可以符合上述目的。 此外，雖然原始碼在進入 + &os.stable; 之前，都會先在 &os.current; 開發完畢，但使用 &os.current; + 的人畢竟遠比 &os.stable; 使用者來的少，所以通常有些問題，可能在 + &os.current; 比較沒人注意到，隨著 &os.stable; + 使用者的廣泛使用才會浮現。</para> + + <para>由於上述這些理由，我們<emphasis>並不推薦</emphasis> 盲目追隨 + &os.stable;，而且更重要的是，別在原始碼尚未經完整測試之前， + 就衝動把 production server 轉移到 &os.stable; 環境。</para> + + <para>若您沒有這些多的時間、精神的話，那推薦您使用最新的 FreeBSD + 發行版即可，並採用其所提供的 binary 更新機制來完成升級轉移。</para> + </sect3> + + <sect3> + <title>使用 &os.stable;</title> + + <orderedlist> + <listitem> + <para>訂閱 &a.stable.name;<indexterm><primary>-STABLE</primary><secondary>using</secondary></indexterm> list。 可以讓您隨時瞭解 &os.stable; + 的軟體編譯時的相依關係，以及其他需特別注意的問題。 + 開發者在考慮一些有爭議的修正或更新時，就會先在這裡發信說明， + 給使用者有機會可以反應， + 看他們對所提的更改是否有什麼建議或問題。</para> + + <para>而 &a.cvsall.name; list 這邊可以看到每個 commit log， + 其中包括了許多中肯的資訊，例如一些可能發生的邊際效應等等。</para> + + <para>想要加入這些通信論壇的話，只要到 &a.mailman.lists.link; + 點下想訂閱的 list 即可。 其餘的步驟在網頁上會有說明。</para> + </listitem> + + <listitem> + <para>若打算要安裝一個全新的系統，並且希望裝 &os.stable; + 每月定期的 snapshot，那麼請參閱 <link xlink:href="&url.base;/snapshots/">Snapshots</link> 網頁以瞭解相關細節。 + 此外，也可從 <link linkend="mirrors">mirror 站</link> + 來安裝最新的 &os.stable; 發行版，並透過下列的的說明來更新到最新的 + &os.stable; 原始碼。</para> + + <para>若已裝的是 &os; 以前的版本，而想透過原始碼方式來升級， + 那麼也是可以利用 &os; <link linkend="mirrors">mirror 站</link> + 來完成。 以下介紹兩種方式：</para> + + <orderedlist> + <listitem> + <para>以 <link linkend="cvsup">csup</link><indexterm><primary><command>cvsup</command></primary></indexterm> 或 + <link linkend="cvsup">cvsup</link> 程式搭配位於 + <filename>/usr/share/examples/cvsup</filename> 檔名為 + <filename>stable-supfile</filename> 的 + <filename>supfile</filename>。 這是大家最常推薦的方式， + 因為它可以讓你把整個 tree 都抓回來， + 之後就只取有更新的部分即可。 + 此外，許多人會把 <command>csup</command> 或 + <command>cvsup</command> 放到 <command>cron</command><indexterm><primary><command>cron</command></primary></indexterm> + 以定期自動更新。 您須要自訂前述的 + <filename>supfile</filename> 範例檔，並針對自身網路環境以調整 + <link linkend="cvsup">csup</link> 或 + <link linkend="cvsup">cvsup</link><indexterm><primary>-STABLE</primary><secondary>syncing with <application>CVSup</application></secondary></indexterm> 相關設定。</para> + </listitem> + + <listitem> + <para>使用 <application>CTM</application><indexterm><primary>-STABLE</primary><secondary>syncing with CTM</secondary></indexterm> 更新工具。 + 若網路不快或網路費用貴，那麼可以考慮採用。</para> + </listitem> + </orderedlist> + </listitem> + + <listitem> + <para>一般而言，若常需存取最新原始碼，而不計較網路頻寬的話， + 可以使用 <command>csup</command> 或 <command>cvsup</command> + 或 <command>ftp</command>。 否則，就考慮 + <application>CTM</application>。</para> + </listitem> + + <listitem> + <para>在編譯 &os.stable;<indexterm><primary>-STABLE</primary><secondary>compiling</secondary></indexterm> 之前，請先仔細閱讀 + <filename>/usr/src</filename> 內的 <filename>Makefile</filename> + 檔。 儘管只是升級部分東西而已，您至少也要先 <link linkend="makeworld">裝新的 kernel 以及重新編譯 world</link>。 + 此外，多多閱讀 &a.stable; 以及 + <filename>/usr/src/UPDATING</filename> 也是必備的， + 這樣才能知道目前進度是怎樣，以及下一版會有哪些新東西。</para> + </listitem> + </orderedlist> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="synching"> + <title>更新你的 Source</title> + + <para>&os; 計劃原始碼有許多透過網路(或 email)的方式來更新， + 無論是更新那一塊領域，這些全由您自行決定。 我們主要提供的是 <link linkend="anoncvs">Anonymous CVS</link>、<link linkend="cvsup">CVSup</link> + 、<link linkend="ctm">CTM</link>。</para> + + <warning> + <para>雖然可以只更新部分原始碼，但唯一支援的更新流程是更新整個 tree， + 並且重編 userland(比如：由使用者去執行的所有程式，像是 + <filename>/bin</filename>、<filename>/sbin</filename> 內的程式)以及 + kernel 原始碼。 + 若只更新部分的 source tree、或只有 kernel 部分、或只有 userland + 部分，通常會造成一些錯誤，像是：編譯錯誤、kernel panic、資料毀損等 + 。</para> + </warning> + + <indexterm> + <primary>CVS</primary> + <secondary>anonymous</secondary> + </indexterm> + + <para><application>Anonymous CVS</application> 及 + <application>CVSup</application> 均是採 <emphasis>pull</emphasis> + 模式來更新原始碼。 以 <application>CVSup</application> 為例， + 使用者(或 <command>cron</command> script)會執行 <command>cvsup</command> + 程式，後者會與某一台 <command>cvsupd</command> 伺服器作些互動， + 以更新相關原始碼檔案。 您所收到更新會是當時最新的， + 而且只會收到需更新的部分。 此外，也可以很輕鬆去設定要更新的範圍。 + 更新會由伺服器跟本機比對之後，丟出當時您所需要的更新檔案給你。 + <application>Anonymous CVS</application> 的概念相對於 + <application>CVSup</application> 來得更簡單些，因為它只是 + <application>CVS</application> 的延伸而已，一樣讓你可從遠端的 + CVS repository 取出最新原始碼。 然而 <application>CVSup</application> + 在這方面會更有效率，不過 <application>Anonymous CVS</application> + 對新手而言，是用起來比較簡單。</para> + + <indexterm> + <primary><application>CTM</application></primary> + </indexterm> + <para>另一種方式則是 <application>CTM</application>。 + 它並不是以交談式介面來比對您所擁有的 sources 和伺服器上的 sources + 或是您取得的更新部份。 相反的，會有一個 script + 檔專門用來辨識變更過的檔案，這個程式是由 CTM 伺服器來執行， + 每天會比對數次，並把兩次執行期間內變更過的檔案加以壓縮， + 並給它們一個序號，然後就加以編碼(只用 printable ASCII 字元)， + 並以 email 的方式寄出。 當您收到它的時候，這些 <quote>CTM deltas</quote> + 就可以由 &man.ctm.rmail.1; 程式來處理，該程式會自動解碼、確認、 + 套用這些變更。 這程序比 <application>CVSup</application> 來說是快得多了， + 而且，這個模式對我們的伺服器來說是比較輕鬆的，因為這是一個 + <emphasis>push</emphasis> 的模式，而非 <emphasis>pull</emphasis> + 的模式。</para> + + <para>當然，這樣做也會帶來一些不便。 若不小心把您部份的程式清除掉了， + <application>CVSup</application> 會偵測出來，並自動為您把不足的部份補齊。 + <application>CTM</application> 並不會為您做這些動作。 + 若清掉了您的部份 source (而且沒備份)，您可以從頭開始(從最新的 CVS + <quote>base delta</quote>)並用 <application>CTM</application> 來重建它們 + ，或是用 <application>Anonymous CVS</application> 來完成， + 只要把不正確的地方砍掉，再重新做同步的動作即可。</para> + </sect1> + + <sect1 xml:id="makeworld"> + <title>重新編譯 <quote>world</quote></title> + + <indexterm> + <primary>Rebuilding <quote>world</quote></primary> + </indexterm> + <para>在更新 &os; 的 source tree 到最新之後(無論是 &os.stable;、 + &os.current; 等等)，接下來就可以用這些 source tree 來重新編譯系統 + 。</para> + + <warning> + <title>做好備份</title> + + <para>在作任何大動作 <emphasis>之前</emphasis> + 要記得先把系統作備份的重要性無須強調。 儘管重新編譯 world 是 + (只要有照文件指示去作的話)一件很簡單的事情，但出錯也是在所難免的。 + 另外，別人在 source tree 不慎搞混的錯誤，也可能會造成系統無法開機 + 。</para> + + <para>請確認自己已作妥相關備份，並且手邊有 fixit 磁片或開機光碟。 + 您可能永遠也用不到這些東西， + 但安全第一總比事後說抱歉來得好吧！</para> + </warning> + + <warning> + <title>訂閱相關的 Mailing List</title> + + <indexterm><primary>mailing list</primary></indexterm> + <para>&os.stable; 以及 &os.current; 分支，本質上就是屬於 <emphasis> + 開發階段</emphasis>。 為 &os; 作貢獻的也都是人，偶爾也會犯錯誤。</para> + + <para>有時候這些錯誤並無大礙，只是會讓系統產生新的錯誤警告而已。 + 有時則是災難，可能會導致不能開機或檔案系統的毀損(或更糟)。</para> + + <para>若遇到類似問題，貼封標題為 <quote>heads up(注意)</quote> + 開頭的信到相關的 mailing list，並講清楚問題點以及會影響哪些系統。 + 在問題獲解決後，再貼標題為 <quote>all clear(已解決)</quote> + 開頭的聲明信。</para> + + <para>若用的是 &os.stable; 或 &os.current;，卻又不閱讀 &a.stable; 或 + &a.current; 的討論，那麼會是自找麻煩而已。</para> + </warning> + + <warning> + <title>不要用 <command>make world</command></title> + + <para>一堆早期的舊文件都會建議說使用 <command>make world</command>。 + 這樣做會跳過一些重要步驟，建議只有在你知道自己在作什麼，再這麼做。 + 在絕大多數的情況下，請不要亂用 <command>make world</command>， + 而該改用下面介紹的方式。</para> + </warning> + + <sect2> + <title>更新系統的標準方式</title> + + <para>要升級系統前，一定要先查閱 <filename>/usr/src/UPDATING</filename> + 文件，以瞭解 buildworld 之前需要作哪些事情或注意事項， + 然後才用下列步驟：</para> + + <screen>&prompt.root; <userinput>make buildworld</userinput> +&prompt.root; <userinput>make buildkernel</userinput> +&prompt.root; <userinput>make installkernel</userinput> +&prompt.root; <userinput>reboot</userinput></screen> + + <note> + <para>在少數狀況，可能需要先在 <buildtarget>buildworld</buildtarget> + 步驟之前先作 <command>mergemaster -p</command> 才能完成。 + 至於何時需要或不需要，請參閱 <filename>UPDATING</filename> 內的說明。 + 一般來說，只要不是進行跨版號(major)的 &os; 版本升級， + 就可略過這步驟。</para> + </note> + + <para>完成 <buildtarget>installkernel</buildtarget> 之後，需要重開機並切到 + single user 模式(舉例：也可以在 loader 提示符號後面加上 + <command>boot -s</command>)。 接下來執行：</para> + + <screen>&prompt.root; <userinput>mergemaster -p</userinput> +&prompt.root; <userinput>make installworld</userinput> +&prompt.root; <userinput>mergemaster</userinput> +&prompt.root; <userinput>reboot</userinput></screen> + + <warning> + <title>Read Further Explanations</title> + + <para>上述步驟只是協助您升級的簡單說明而已，若要清楚瞭解每一步驟， + 尤其是若欲自行打造 kernel 設定，就更該閱讀下面的內容。</para> + </warning> + </sect2> + + <sect2> + <title>閱讀 <filename>/usr/src/UPDATING</filename></title> + + <para>在作任何事情之前，請務必先閱讀 + <filename>/usr/src/UPDATING</filename> (或在 source code 內類似的文件) + 。 這份文件會寫到可能遭遇的問題，或指定那些會執行的指令順序為何。 + 如果你機器現在的 <filename>UPDATING</filename> + 文件與這邊的描述有衝突、矛盾之處，那麼請以機器上的 + <filename>UPDATING</filename> 為準。</para> + + <important> + <para>然而，如同先前所述，單單只靠閱讀 <filename>UPDATING</filename> + 並不能完全取代 mailing list。 這兩者都是互補的，而不相排斥。</para> + </important> + </sect2> + + <sect2> + <title>檢查 <filename>/etc/make.conf</filename></title> + <indexterm> + <primary><filename>make.conf</filename></primary> + </indexterm> + + <para>檢查 + <filename>/usr/share/examples/etc/make.conf</filename> + 以及 + <filename>/etc/make.conf</filename>。 第一份文件乃是一些系統預設值 + – 不過，大部分都被註解起來。 為了在重新編譯時能夠使用這些， + 請把這些設定加到 <filename>/etc/make.conf</filename>。 請注意在 + <filename>/etc/make.conf</filename> 的任何設定也會影響到每次使用 + <command>make</command> 的結果， + 因此設定一些適合自己系統的選項會是不錯的作法。</para> + + <para>一般使用者通常會從 + <filename>/usr/share/examples/etc/make.conf</filename> 複製 + <varname>CFLAGS</varname> 以及 <varname>NO_PROFILE</varname> + 之類的設定到 <filename>/etc/make.conf</filename>，並解除相關註解印記 + 。</para> + + <para>此外，也可以試試看其他設定 (<varname>COPTFLAGS</varname>、 + <v |