diff options
Diffstat (limited to 'en_US.ISO8859-1/books/handbook')
91 files changed, 85624 insertions, 0 deletions
diff --git a/en_US.ISO8859-1/books/handbook/Makefile b/en_US.ISO8859-1/books/handbook/Makefile new file mode 100644 index 0000000000..0a720e886f --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/Makefile @@ -0,0 +1,354 @@ +# +# $FreeBSD$ +# +# Build the FreeBSD Handbook. +# + +# ------------------------------------------------------------------------ +# +# Handbook-specific variables +# +# WITH_PGPKEYS The print version of the handbook only prints PGP +# fingerprints by default. If you would like for the +# entire key to be displayed, then set this variable. +# This option has no affect on the HTML formats. +# +# Handbook-specific targets +# +# pgpkeyring This target will read the contents of +# pgpkeys/chapter.sgml and will extract all of +# the pgpkeys to standard out. This output can then +# be redirected into a file and distributed as a +# public keyring of FreeBSD developers that can +# easily be imported into PGP/GPG. +# +# ------------------------------------------------------------------------ +# +# To add a new chapter to the Handbook: +# +# - Update this Makefile, chapters.ent and book.sgml +# - Add a descriptive entry for the new chapter in preface/preface.sgml +# +# ------------------------------------------------------------------------ + +.PATH: ${.CURDIR}/../../share/sgml/glossary + +MAINTAINER= doc@FreeBSD.org + +DOC?= book + +FORMATS?= html-split + +HAS_INDEX= true +USE_PS2PDF= yes + +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+= bsdinstall/bsdinstall-adduser1.png +IMAGES_EN+= bsdinstall/bsdinstall-adduser2.png +IMAGES_EN+= bsdinstall/bsdinstall-adduser3.png +IMAGES_EN+= bsdinstall/bsdinstall-boot-loader-menu.png +IMAGES_EN+= bsdinstall/bsdinstall-choose-mode.png +IMAGES_EN+= bsdinstall/bsdinstall-config-components.png +IMAGES_EN+= bsdinstall/bsdinstall-config-hostname.png +IMAGES_EN+= bsdinstall/bsdinstall-config-keymap.png +IMAGES_EN+= bsdinstall/bsdinstall-config-services.png +IMAGES_EN+= bsdinstall/bsdinstall-config-crashdump.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-ipv4-dhcp.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-ipv4.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-ipv4-static.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-ipv6.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-ipv6-static.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface-slaac.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-network-interface.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-network-ipv4-dns.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-wireless-accesspoints.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-wireless-scan.png +IMAGES_EN+= bsdinstall/bsdinstall-configure-wireless-wpa2setup.png +IMAGES_EN+= bsdinstall/bsdinstall-distfile-extracting.png +IMAGES_EN+= bsdinstall/bsdinstall-distfile-fetching.png +IMAGES_EN+= bsdinstall/bsdinstall-distfile-verifying.png +IMAGES_EN+= bsdinstall/bsdinstall-final-confirmation.png +IMAGES_EN+= bsdinstall/bsdinstall-finalconfiguration.png +IMAGES_EN+= bsdinstall/bsdinstall-final-modification-shell.png +IMAGES_EN+= bsdinstall/bsdinstall-keymap-select-default.png +IMAGES_EN+= bsdinstall/bsdinstall-mainexit.png +IMAGES_EN+= bsdinstall/bsdinstall-netinstall-files.png +IMAGES_EN+= bsdinstall/bsdinstall-netinstall-mirrorselect.png +IMAGES_EN+= bsdinstall/bsdinstall-part-entire-part.png +IMAGES_EN+= bsdinstall/bsdinstall-part-guided-disk.png +IMAGES_EN+= bsdinstall/bsdinstall-part-guided-manual.png +IMAGES_EN+= bsdinstall/bsdinstall-part-manual-addpart.png +IMAGES_EN+= bsdinstall/bsdinstall-part-manual-create.png +IMAGES_EN+= bsdinstall/bsdinstall-part-manual-partscheme.png +IMAGES_EN+= bsdinstall/bsdinstall-part-review.png +IMAGES_EN+= bsdinstall/bsdinstall-post-root-passwd.png +IMAGES_EN+= bsdinstall/bsdinstall-set-clock-local-utc.png +IMAGES_EN+= bsdinstall/bsdinstall-timezone-confirm.png +IMAGES_EN+= bsdinstall/bsdinstall-timezone-country.png +IMAGES_EN+= bsdinstall/bsdinstall-timezone-region.png +IMAGES_EN+= bsdinstall/bsdinstall-timezone-zone.png +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/config-keymap.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 SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS+= audit/chapter.sgml +SRCS+= book.sgml +SRCS+= bsdinstall/chapter.sgml +SRCS+= colophon.sgml +SRCS+= dtrace/chapter.sgml +SRCS+= freebsd-glossary.sgml +SRCS+= advanced-networking/chapter.sgml +SRCS+= basics/chapter.sgml +SRCS+= bibliography/chapter.sgml +SRCS+= boot/chapter.sgml +SRCS+= config/chapter.sgml +SRCS+= cutting-edge/chapter.sgml +SRCS+= desktop/chapter.sgml +SRCS+= disks/chapter.sgml +SRCS+= eresources/chapter.sgml +SRCS+= firewalls/chapter.sgml +SRCS+= filesystems/chapter.sgml +SRCS+= geom/chapter.sgml +SRCS+= install/chapter.sgml +SRCS+= introduction/chapter.sgml +SRCS+= jails/chapter.sgml +SRCS+= kernelconfig/chapter.sgml +SRCS+= l10n/chapter.sgml +SRCS+= linuxemu/chapter.sgml +SRCS+= mac/chapter.sgml +SRCS+= mail/chapter.sgml +SRCS+= mirrors/chapter.sgml +SRCS+= multimedia/chapter.sgml +SRCS+= network-servers/chapter.sgml +SRCS+= pgpkeys/chapter.sgml +SRCS+= ports/chapter.sgml +SRCS+= ppp-and-slip/chapter.sgml +SRCS+= preface/preface.sgml +SRCS+= printing/chapter.sgml +SRCS+= security/chapter.sgml +SRCS+= serialcomms/chapter.sgml +SRCS+= users/chapter.sgml +SRCS+= vinum/chapter.sgml +SRCS+= virtualization/chapter.sgml +SRCS+= x11/chapter.sgml + +# Entities +SRCS+= chapters.ent + +SYMLINKS= ${DESTDIR} index.html handbook.html + +# Turn on all the chapters. +CHAPTERS?= ${SRCS:M*chapter.sgml} + +SGMLFLAGS+= ${CHAPTERS:S/\/chapter.sgml//:S/^/-i chap./} +SGMLFLAGS+= -i chap.freebsd-glossary + +pgpkeyring: pgpkeys/chapter.sgml + @${JADE} -V nochunks ${OTHERFLAGS} ${JADEOPTS} -d ${DSLPGP} -t sgml ${MASTERDOC} + +# +# Handbook-specific variables +# +.if defined(WITH_PGPKEYS) +JADEFLAGS+= -V withpgpkeys +.endif + +URL_RELPREFIX?= ../../../.. +DOC_PREFIX?= ${.CURDIR}/../../.. + +# +# rules generating lists of mirror site from XML database. +# +XMLDOCS= mirrors-ftp:::mirrors.sgml.ftp.inc.tmp \ + mirrors-cvsup:::mirrors.sgml.cvsup.inc.tmp \ + eresources:::eresources.sgml.www.inc.tmp +DEPENDSET.DEFAULT= transtable mirror +XSLT.DEFAULT= ${XSL_MIRRORS} +XML.DEFAULT= ${XML_MIRRORS} +NO_TIDY.DEFAULT= yes + +PARAMS.mirrors-ftp+= --param 'type' "'ftp'" \ + --param 'proto' "'ftp'" \ + --param 'target' "'handbook/mirrors/chapter.sgml'" +PARAMS.mirrors-cvsup+= --param 'type' "'cvsup'" \ + --param 'proto' "'cvsup'" \ + --param 'target' "'handbook/mirrors/chapter.sgml'" +PARAMS.eresources+= --param 'type' "'www'" \ + --param 'proto' "'http'" \ + --param 'target' "'handbook/eresources/chapter.sgml'" + +SRCS+= mirrors.sgml.ftp.inc \ + mirrors.sgml.cvsup.inc \ + eresources.sgml.www.inc + +CLEANFILES+= mirrors.sgml.ftp.inc mirrors.sgml.ftp.inc.tmp \ + mirrors.sgml.cvsup.inc mirrors.sgml.cvsup.inc.tmp \ + eresources.sgml.www.inc eresources.sgml.www.inc.tmp + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" + +.for p in ftp cvsup +mirrors.sgml.${p}.inc: mirrors.sgml.${p}.inc.tmp + ${SED} -e 's,<\([^ >]*\)\([^>]*\)/>,<\1\2></\1>,;s,</anchor>,,'\ + < $@.tmp > $@ || (${RM} -f $@ && false) +.endfor + +eresources.sgml.www.inc: eresources.sgml.www.inc.tmp + ${SED} -e 's,<\([^ >]*\)\([^>]*\)/>,<\1\2></\1>,;s,</anchor>,,'\ + < $@.tmp > $@ || (${RM} -f $@ && false) diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/Makefile b/en_US.ISO8859-1/books/handbook/advanced-networking/Makefile new file mode 100644 index 0000000000..eb62e4335c --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/advanced-networking/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= advanced-networking/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml new file mode 100644 index 0000000000..b643f39108 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.sgml @@ -0,0 +1,6186 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="advanced-networking"> + <title>Advanced Networking</title> + + <sect1 id="advanced-networking-synopsis"> + <title>Synopsis</title> + + <para>This chapter will cover a number of advanced networking + topics.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>The basics of gateways and routes.</para> + </listitem> + + <listitem> + <para>How to set up &ieee; 802.11 and &bluetooth; devices.</para> + </listitem> + + <listitem> + <para>How to make FreeBSD act as a bridge.</para> + </listitem> + + <listitem> + <para>How to set up network booting on a diskless machine.</para> + </listitem> + + <listitem> + <para>How to set up network PXE booting with an NFS root file system.</para> + </listitem> + + <listitem> + <para>How to set up network address translation.</para> + </listitem> + + <listitem> + <para>How to connect two computers via PLIP.</para> + </listitem> + + <listitem> + <para>How to set up IPv6 on a FreeBSD machine.</para> + </listitem> + + <listitem> + <para>How to configure ATM.</para> + </listitem> + + <listitem> + <para>How to enable and utilize the features of CARP, the + Common Address Redundancy Protocol in &os;</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand the basics of the <filename>/etc/rc</filename> scripts.</para> + </listitem> + + <listitem> + <para>Be familiar with basic network terminology.</para> + </listitem> + + <listitem> + <para>Know how to configure and install a new FreeBSD kernel + (<xref linkend="kernelconfig">).</para> + </listitem> + + <listitem> + <para>Know how to install additional third-party + software (<xref linkend="ports">).</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1 id="network-routing"> + <sect1info> + <authorgroup> + <author> + <firstname>Coranth</firstname> + <surname>Gryphon</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Gateways and Routes</title> + + <indexterm><primary>routing</primary></indexterm> + <indexterm><primary>gateway</primary></indexterm> + <indexterm><primary>subnet</primary></indexterm> + <para>For one machine to be able to find another over a network, + there must be a mechanism in place to describe how to get from + one to the other. This is called + <firstterm>routing</firstterm>. A <quote>route</quote> is a + defined pair of addresses: a <quote>destination</quote> and a + <quote>gateway</quote>. The pair indicates that if you are + trying to get to this <emphasis>destination</emphasis>, + communicate through this <emphasis>gateway</emphasis>. There + are three types of destinations: individual hosts, subnets, and + <quote>default</quote>. The <quote>default route</quote> is + used if none of the other routes apply. We will talk a little + bit more about default routes later on. There are also three + types of gateways: individual hosts, interfaces (also called + <quote>links</quote>), and Ethernet hardware addresses (MAC + addresses). + </para> + + <sect2> + <title>An Example</title> + + <para>To illustrate different aspects of routing, we will use the + following example from <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 <hostid>localhost</hostid> 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 <devicename>lo0</devicename>, + 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 <hostid role="mac">0:e0:</hostid>. These are Ethernet + hardware addresses, which are also known as MAC addresses. + FreeBSD will automatically identify any hosts + (<hostid>test0</hostid> in the example) on the local Ethernet + and add a route for that host, directly to it over the + Ethernet interface, <devicename>ed0</devicename>. 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 (<hostid + role="ipaddr">10.20.30.255</hostid> is the broadcast address for the + subnet <hostid role="ipaddr">10.20.30</hostid>, and <hostid + role="domainname">example.com</hostid> 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 (<devicename>lo0</devicename>) + 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 + <devicename>lo0</devicename> 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 <hostid role="ipaddr">224</hostid>) 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 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 <hostid>Local1</hostid> and + <hostid>Local2</hostid> are at your site. + <hostid>Local1</hostid> 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 <hostid>T1-GW</hostid> to be the default gateway for + <hostid>Local1</hostid>, 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 <hostid>T1-GW</hostid> + 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 <hostid + role="ipaddr">X.X.X.1</hostid> as the gateway address for your local + network. So (using the same example), if your local class-C address + space was <hostid role="ipaddr">10.20.30</hostid> and your ISP was + using <hostid role="ipaddr">10.9.9</hostid> 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 + <hostid>Local2</hostid> 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 id="network-dual-homed-hosts"> + <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 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> + + <indexterm><primary>BGP</primary></indexterm> + <indexterm><primary>RIP</primary></indexterm> + <indexterm><primary>OSPF</primary></indexterm> + <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 + <filename role="package">net/zebra</filename> package. + Commercial products such as <application>&gated;</application> are also available for more + complex network routing solutions.</para> + </sect2> + + <sect2 id="network-static-routes"> + <sect2info> + <authorgroup> + <author> + <firstname>Al</firstname> + <surname>Hoang</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <!-- Feb 2004 --> + <title>Setting Up Static Routes</title> + + <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, <hostid>RouterA</hostid> is our &os; + machine that is acting as a router to the rest of the + Internet. It has a default route set to <hostid + role="ipaddr">10.0.0.1</hostid> which allows it to connect + with the outside world. We will assume that + <hostid>RouterB</hostid> 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 + <hostid>RouterB</hostid> using <hostid + role="ipaddr">192.168.1.1</hostid> as the gateway.)</para> + + <para>If we look at the routing table for + <hostid>RouterA</hostid> 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.0/24 link#1 UC 0 0 xl0 +192.168.1.0/24 link#2 UC 0 0 xl1</screen> + + <para>With the current routing table <hostid>RouterA</hostid> + will not be able to reach our Internal Net 2. It does not + have a route for <hostid + role="ipaddr">192.168.2.0/24</hostid>. One way to alleviate + this is to manually add the route. The following command + would add the Internal Net 2 network to + <hostid>RouterA</hostid>'s routing table using <hostid + role="ipaddr">192.168.1.2</hostid> 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 <hostid>RouterA</hostid> can reach any hosts on the + <hostid role="ipaddr">192.168.2.0/24</hostid> + 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_<replaceable>internalnet2</replaceable></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 <hostid + role="ipaddr">192.168.0.0/24</hostid> and <hostid + role="ipaddr">192.168.1.0/24</hostid> 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 id="network-routing-propagation"> + <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 id="network-routing-troubleshooting"> + <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 id="network-routing-multicast"> + <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> + + <note> + <para>The &man.mrouted.8; multicast routing daemon + implements the + <acronym>DVMRP</acronym> multicast routing protocol, which has + largely been replaced by &man.pim.4; in many multicast + installations. &man.mrouted.8; and the related &man.map-mbone.8; and + &man.mrinfo.8; utilities + are available in the &os; Ports Collection as + <filename role="package">net/mrouted</filename>.</para> + </note> + </sect2> + </sect1> + + <sect1 id="network-wireless"> + <sect1info> + <authorgroup> + <author> + <othername>Loader</othername> + </author> + + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + </author> + + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + </author> + </authorgroup> + </sect1info> + <title>Wireless Networking</title> + + <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>&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 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 proper driver (&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 this support is loaded as kernel + 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 and supported adapters can be + found in the &os; Hardware Notes. Copies of these notes + for various releases and architectures are available on + the <ulink + url="http://www.FreeBSD.org/releases/index.html">Release + Information</ulink> page of the &os; Web site. + 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>Under &os; 7.X, with a device driver you need to also bring + in the 802.11 networking support required by the driver. + For the &man.ath.4; driver these are at least the &man.wlan.4;, + <literal>wlan_scan_ap</literal> and + <literal>wlan_scan_sta</literal> + modules; the &man.wlan.4; module is automatically loaded with the + wireless device driver, the remaining modules must be loaded + at boot time via the <filename>/boot/loader.conf</filename> + file:</para> + + <programlisting>wlan_scan_ap_load="YES" +wlan_scan_sta_load="YES"</programlisting> + + <para>Since &os; 8.0, these modules are part of the + base &man.wlan.4; driver which is dynamically loaded with + the adapter driver.</para> + + <para>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 does not use encryption, + you will not need &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 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 wlan # 802.11 support +device wlan_wep # 802.11 WEP support +device wlan_ccmp # 802.11 CCMP support +device wlan_tkip # 802.11 TKIP support +device wlan_amrr # AMRR transmit rate control algorithm +device ath # Atheros pci/cardbus NIC's +device ath_hal # pci/cardbus chip support +options AH_SUPPORT_AR5416 # enable AR5416 tx/rx descriptors +device ath_rate_sample # SampleRate tx rate control for ath</programlisting> + + <para>Both following lines are also required by + &os; 7.X, other &os; versions do not need + them:</para> + + <programlisting>device wlan_scan_ap # 802.11 AP mode scanning +device wlan_scan_sta # 802.11 STA mode scanning</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 0x88000000-0x8800ffff irq 11 at device 0.0 on cardbus1 +ath0: [ITHREAD] +ath0: AR2413 mac 7.9 RF2413 phy 4.5</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 <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> +SSID/MESH ID BSSID CHAN RATE S:N INT CAPS +dlinkap 00:13:46:49:41:76 11 54M -90:96 100 EPS WPA WME +freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 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> + + <note> + <para>Under &os; 7.X, the adapter device, for example + <devicename><replaceable>ath0</replaceable></devicename>, + is used directly instead of the + <devicename>wlan<replaceable>0</replaceable></devicename> + device. This requires you to replace the both previous + lines with:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>ath0</replaceable> up scan</userinput></screen> + + <para>In the rest of this document, &os; 7.X users + will need to change the command and configuration lines + according to that scheme.</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> + + <table frame="none" pgwide="0"> + <title>Station Capability Codes</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Capability Code</entry> + <entry>Meaning</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>E</literal></entry> + <entry>Extended Service Set (ESS). Indicates that + the station is part of an infrastructure network + (in contrast to an IBSS/ad-hoc network).</entry> + </row> + + <row> + <entry><literal>I</literal></entry> + <entry>IBSS/ad-hoc network. Indicates that the + station is part of an ad-hoc network (in contrast + to an ESS network).</entry> + </row> + + <row> + <entry><literal>P</literal></entry> + <entry>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.</entry> + </row> + + <row> + <entry><literal>S</literal></entry> + <entry>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).</entry> + </row> + + <row> + <entry><literal>s</literal></entry> + <entry>Short slot time. Indicates that the 802.11g + network is using a short slot time because there + are no legacy (802.11b) stations present.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>One can also display the current list of known + networks with:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> 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>wlans_ath0="wlan0" +ifconfig_wlan0="DHCP"</programlisting> + + <note> + <para>As previously mentioned, &os; 7.X will only + require a line related to the adapter device:</para> + + <programlisting>ifconfig_ath0="DHCP"</programlisting> + </note> + + <para>If there are multiple access points and you want to + select a specific one, you can select it by its + SSID:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="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>wlans_ath0="wlan0" +ifconfig_wlan0="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>wlans_ath0="wlan0" +ifconfig_wlan0="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>wlans_ath0="wlan0" +ifconfig_wlan0="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, + 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>wlans_ath0="wlan0" +ifconfig_wlan0="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 <devicename>ath0</devicename>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255 + media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g + status: associated + ssid dlinkap channel 11 (2462 Mhz 11g) bssid 00:13:46:49:41:76 + country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7 + scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 + roam:rate 5 protmode CTS wme burst</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 OPEN</literal> part informs you that the + communication is not encrypted.</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>wlans_ath0="wlan0" +ifconfig_wlan0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>your_ssid_here</replaceable>"</programlisting> + </sect5> + </sect4> + + <sect4 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). TKIP 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 their 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 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>wlans_ath0="wlan0" +ifconfig_wlan0="WPA DHCP"</programlisting> + + <para>Then we can bring up the interface:</para> + + <screen>&prompt.root; <userinput><filename>/etc/rc.d/netif</filename> start</userinput> +Starting wpa_supplicant. +DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 5 +DHCPDISCOVER on wlan0 to 255.255.255.255 port 67 interval 6 +DHCPOFFER from 192.168.0.1 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 +DHCPACK from 192.168.0.1 +bound to 192.168.0.254 -- renewal in 300 seconds. +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</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 <replaceable>wlan0</replaceable> -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=CCMP GTK=CCMP] +CTRL-EVENT-CONNECTED - Connection to 00:11:95:c3:0d:ac completed (auth) [id=0 id_str=]</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 <replaceable>wlan0</replaceable></userinput> +DHCPREQUEST on wlan0 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 <replaceable>wlan0</replaceable></userinput> +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</screen> + + <note> + <para>If <filename>/etc/rc.conf</filename> has an + <literal>ifconfig_wlan0</literal> entry with the + <literal>DHCP</literal> string (like + <literal>ifconfig_wlan0="DHCP"</literal>), + <command>dhclient</command> will be launched + automatically after <command>wpa_supplicant</command> + associates with the access point.</para> + </note> + + <para>If DHCP is not possible or desired, + you can set a static IP address after + <command>wpa_supplicant</command> has authenticated the + station:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.100</replaceable> netmask <replaceable>255.255.255.0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet OFDM/36Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</screen> + + <para>When DHCP is not used, you also have to manually set + the default gateway and the nameserver:</para> + + <screen>&prompt.root; <userinput>route add default <replaceable>your_default_router</replaceable></userinput> +&prompt.root; <userinput>echo "nameserver <replaceable>your_DNS_server</replaceable>" >> /etc/resolv.conf</userinput></screen> + </sect5> + + <sect5 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 differentiate it from the less secure + WPA-Personal with its pre-shared key. + Authentication in WPA-Enterprise is based on the + Extensible Authentication Protocol (EAP).</para> + + <para>EAP does not come with an encryption method. + Instead, it was decided to embed EAP inside an encrypted + tunnel. There are many EAP authentication methods, but + EAP-TLS, EAP-TTLS, and EAP-PEAP are the most + common.</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 <ulink + url="http://www.wi-fi.org/">Wi-Fi alliance</ulink>. + 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 id="co-tls-ssid"> + proto=RSN <co id="co-tls-proto"> + key_mgmt=WPA-EAP <co id="co-tls-kmgmt"> + eap=TLS <co id="co-tls-eap"> + identity="loader" <co id="co-tls-id"> + ca_cert="/etc/certs/cacert.pem" <co id="co-tls-cacert"> + client_cert="/etc/certs/clientcert.pem" <co id="co-tls-clientcert"> + private_key="/etc/certs/clientkey.pem" <co id="co-tls-pkey"> + private_key_passwd="freebsdmallclient" <co 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 certificate.</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 lines to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="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 wlan0 to 255.255.255.255 port 67 interval 7 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</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 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 id="co-ttls-eap"> + identity="test" <co id="co-ttls-id"> + password="test" <co id="co-ttls-passwd"> + ca_cert="/etc/certs/cacert.pem" <co id="co-ttls-cacert"> + phase2="auth=MD5" <co 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 certificate.</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 lines to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>wlans_ath0="wlan0" +ifconfig_wlan0="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 wlan0 to 255.255.255.255 port 67 interval 7 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</screen> + </sect5> + + <sect5 id="network-wireless-wpa-eap-peap"> + <title>WPA with EAP-PEAP</title> + + <note> + <para>PEAPv0/EAP-MSCHAPv2 is the most common PEAP method. + In the rest of this document, we will use the PEAP term + to refer to that method.</para> + </note> + + <para>PEAP (Protected EAP) has been designed as an + alternative to EAP-TTLS, and 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 terms of + security, the difference between EAP-TTLS and PEAP is + that PEAP authentication broadcasts the username in the + clear, with only the password 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 id="co-peap-eap"> + identity="test" <co id="co-peap-id"> + password="test" <co id="co-peap-passwd"> + ca_cert="/etc/certs/cacert.pem" <co id="co-peap-cacert"> + phase1="peaplabel=0" <co id="co-peap-pha1"> + phase2="auth=MSCHAPV2" <co 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 certificate.</para> + </callout> + + <callout arearefs="co-peap-pha1"> + <para>This field contains the parameters for the + first phase of authentication (the TLS + tunnel). According to the authentication server + used, you will have to specify a specific label + for authentication. Most of the 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>wlans_ath0="wlan0" +ifconfig_wlan0="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 wlan0 to 255.255.255.255 port 67 interval 7 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 15 +DHCPREQUEST on wlan0 to 255.255.255.255 port 67 interval 21 +DHCPACK from 192.168.0.20 +bound to 192.168.0.254 -- renewal in 300 seconds. +wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet DS/11Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode WPA2/802.11i privacy ON deftxkey UNDEF + AES-CCM 3:128-bit txpower 21.5 bmiss 7 scanvalid 450 bgscan + bgscanintvl 300 bgscanidle 250 roam:rssi 7 roam:rate 5 protmode CTS + wme burst roaming MANUAL</screen> + </sect5> + </sect4> + + <sect4 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 + cracked.</para> + + <para>WEP can be set up with + <command>ifconfig</command>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> \ + ssid <replaceable>my_net</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable></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. If you do not have any idea of which key is + used by the access point, try + <literal>1</literal> (i.e., the first key) for this + value.</para> + </listitem> + + <listitem> + <para>The <literal>wepkey</literal> selects one of the + WEP keys. It should be in the format + <replaceable>index:key</replaceable>. Key + <literal>1</literal> is used by default; the index + only needs to be set if we use a key 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 the &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 <replaceable>wlan0</replaceable> -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 <hostid>A</hostid> and the machine + <hostid>B</hostid>, we will just need to choose two IP addresses + and a SSID.</para> + + <para>On the box <hostid>A</hostid>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 00:11:95:c3:0d:ac + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <adhoc> + status: running + ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac + country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 + protmode CTS wme burst</screen> + + <para>The <literal>adhoc</literal> parameter indicates the + interface is running in the IBSS mode.</para> + + <para>On <hostid>B</hostid>, we should be able to detect + <hostid>A</hostid>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> + SSID/MESH ID BSSID CHAN RATE S:N INT CAPS + freebsdap 02:11:95:c3:0d:ac 2 54M -64:-96 100 IS WME</screen> + + <para>The <literal>I</literal> in the output confirms the + machine <hostid>A</hostid> is in ad-hoc mode. We just have to + configure <hostid>B</hostid> with a different IP + address:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <adhoc> + status: running + ssid freebsdap channel 2 (2417 Mhz 11g) bssid 02:11:95:c3:0d:ac + country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 + protmode CTS wme burst</screen> + + <para>Both <hostid>A</hostid> and <hostid>B</hostid> are now + ready to exchange information.</para> + </sect2> + + <sect2 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 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 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 currently allow AP operation. Only + native &os; wireless drivers support AP mode.</para> + </note> + + <para>Once wireless networking support is loaded, you can + check if your wireless device supports the host-based access + point mode (also known as hostap mode):</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list caps</userinput> +drivercaps=6f85edc1<STA,FF,TURBOP,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,MBSS,WPA1,WPA2,BURST,WME,WDS,BGSCAN,TXFRAG> +cryptocaps=1f<WEP,TKIP,AES,AES_CCM,TKIPMIC></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, AES, etc. This information + is important to know what security protocols can be used + on the Access Point.</para> + + <para>The wireless device can only be put into hostap mode + during the creation of the network pseudo-device, so a + previously created device must be destroyed first:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> destroy</userinput></screen> + + <para>then regenerated with the correct option before setting + the other parameters:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel 1</userinput></screen> + + <para>Use <command>ifconfig</command> again to see the status + of the <devicename>wlan0</devicename> interface:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 00:11:95:c3:0d:ac + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> + status: running + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 + protmode CTS wme burst dtimperiod 1 -dfs</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 lines to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>wlans_ath0="wlan0" +create_args_wlan0="wlanmode hostap" +ifconfig_wlan0="inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel <replaceable>1</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 <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> +SSID/MESH ID BSSID CHAN RATE S:N INT CAPS +freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME</screen> + + <para>The client machine found the Access Point and can be + associated with it:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 00:11:95:d5:43:62 + inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet OFDM/54Mbps mode 11g + status: associated + ssid freebsdap channel 1 (2412 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode OPEN privacy OFF txpower 21.5 bmiss 7 + scanvalid 60 bgscan bgscanintvl 300 bgscanidle 250 roam:rssi 7 + roam:rate 5 protmode CTS wme burst</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=wlan0 <co id="co-ap-wpapsk-iface"> +debug=1 <co id="co-ap-wpapsk-dbug"> +ctrl_interface=/var/run/hostapd <co id="co-ap-wpapsk-ciface"> +ctrl_interface_group=wheel <co id="co-ap-wpapsk-cifacegrp"> +ssid=freebsdap <co id="co-ap-wpapsk-ssid"> +wpa=1 <co id="co-ap-wpapsk-wpa"> +wpa_passphrase=freebsdmall <co id="co-ap-wpapsk-pass"> +wpa_key_mgmt=WPA-PSK <co id="co-ap-wpapsk-kmgmt"> +wpa_pairwise=CCMP TKIP <co 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 + <groupname>wheel</groupname> 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 <replaceable>wlan0</replaceable></userinput> + wlan0: 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 <replaceable>wlan0</replaceable> 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 <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> \ + ssid <replaceable>freebsdap</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable> mode 11g</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 <devicename>wlan0</devicename> interface:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + ether 00:11:95:c3:0d:ac + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + media: IEEE 802.11 Wireless Ethernet autoselect mode 11g <hostap> + status: running + ssid freebsdap channel 4 (2427 Mhz 11g) bssid 00:11:95:c3:0d:ac + country US ecm authmode OPEN privacy ON deftxkey 3 wepkey 3:40-bit + txpower 21.5 scanvalid 60 protmode CTS wme burst dtimperiod 1 -dfs</screen> + + <para>From another wireless machine, it is possible to initiate + a scan to find the AP:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> +&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> 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>Using Both Wired and Wireless Connection</title> + + <para>Wired connection provides better performance and reliability, + while wireless connection provides flexibility and mobility, + users of laptop computers usually want to combine these together + and roam seamlessly between the two.</para> + + <para>On &os;, it is possible to combine two or even more network + interfaces together in a <quote>failover</quote> fashion, that + is, to use the most preferred and available connection from a + group of network interfaces, and have the operating system + switch automatically when the link state changes.</para> + + <para>We will cover link aggregation and failover in <xref linkend="network-aggregation"> + where an example for using both wired and wireless connection + is also provided at <xref linkend="networking-lagg-wired-and-wireless">.</para> + </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 <replaceable>ath0</replaceable> +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 this information. 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 id="network-bluetooth"> + <sect1info> + <authorgroup> + <author> + <firstname>Pav</firstname> + <surname>Lucistnik</surname> + <contrib>Written by </contrib> + <affiliation> + <address><email>pav@FreeBSD.org</email></address> + </affiliation> + </author> + </authorgroup> + </sect1info> + <title>Bluetooth</title> + + <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> + + <para>The <filename>/etc/rc.d/bluetooth</filename> 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.d/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> + + </sect2> + + <indexterm><primary>HCI</primary></indexterm> + <sect2> + <title>Host Controller Interface (HCI)</title> + + <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> + + <indexterm><primary>L2CAP</primary></indexterm> + <sect2> + <title>Logical Link Control and Adaptation Protocol (L2CAP)</title> + + <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> + + <indexterm><primary>RFCOMM</primary></indexterm> + <sect2> + <title>RFCOMM Protocol</title> + + <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> + + <indexterm><primary>pairing</primary></indexterm> + <sect2> + <title>Pairing of Devices</title> + + <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>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> + + <indexterm><primary>SDP</primary></indexterm> + <sect2> + <title>Service Discovery Protocol (SDP)</title> + <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. 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>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> + + <indexterm><primary>OBEX</primary></indexterm> + <sect2> + <title>OBEX Object Push (OPUSH) Profile</title> + <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 + <filename role="package">comms/obexapp</filename> 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 + <filename role="package">comms/hcidump</filename> 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 id="network-bridging"> + <sect1info> + <authorgroup> + <author> + <firstname>Andrew</firstname> + <surname>Thompson</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Bridging</title> + + <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 + <devicename>fxp0</devicename> and + <devicename>fxp1</devicename>. 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. + &os; supports RSTP and STP as operating modes, with RSTP + being the default mode.</para> + + <para>Spanning Tree can be enabled on member interfaces using + the <literal>stp</literal> command. For a bridge with + <devicename>fxp0</devicename> and + <devicename>fxp1</devicename> 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 + <devicename>fxp0</devicename>.</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 + <devicename>fxp4</devicename>:</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 <hostid + role="Hostname">CustomerA</hostid> is on + <literal>vlan100</literal> and <hostid + role="hostname">CustomerB</hostid> is on + <literal>vlan101</literal>. The bridge has the address + <hostid role="ipaddr">192.168.0.1</hostid> 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 <hostid + role="ipaddr">192.168.0.1</hostid> 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 <hostid role="netmask">/24</hostid> address range + can be allocated without subnetting.</para> + </sect3> + + <sect3> + <title>Address Limits</title> + + <para>The number of unique source MAC addresses behind an + interface can be limited. Once the limit is reached packets + with unknown source addresses are dropped until an + existing host cache entry expires or is removed.</para> + + <para>The following example sets the maximum number of Ethernet + devices for <hostid role="Hostname">CustomerA</hostid> on + <literal>vlan100</literal> to 10.</para> + + <screen>&prompt.root; <userinput>ifconfig bridge0 ifmaxaddr vlan100 10</userinput></screen> + </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 (<filename + role="package">net-mgmt/net-snmp</filename>) to query a + bridge, the <filename + role="package">net-mgmt/bsnmptools</filename> 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 id="network-aggregation"> + <sect1info> + <authorgroup> + <author> + <firstname>Andrew</firstname> + <surname>Thompson</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Link Aggregation and Failover</title> + + <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. If failover to a non-master port + occurs, the original port will become master when it becomes + available again.</para> + </listitem> + </varlistentry> + + <varlistentry><term>&cisco; Fast ðerchannel;</term> + + <listitem> + <para>&cisco; Fast ðerchannel; (FEC), 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><acronym>FEC</acronym> 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>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 (LAG). 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><acronym>LACP</acronym> 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>Round-robin</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 violates Ethernet Frame ordering and should be + used with caution.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2> + <title>Examples</title> + + <example 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 + <replaceable>FastEthernet0/1</replaceable> and + <replaceable>FastEthernet0/2</replaceable> interfaces to the + channel-group <replaceable>1</replaceable>:</para> + + <screen><userinput>interface <replaceable>FastEthernet0/1</replaceable> + channel-group <replaceable>1</replaceable> mode active + channel-protocol lacp</userinput> +! +<userinput>interface <replaceable>FastEthernet0/2</replaceable> + channel-group <replaceable>1</replaceable> mode active + channel-protocol lacp</userinput></screen> + + <para>Create the &man.lagg.4; interface using + <replaceable>fxp0</replaceable> and <replaceable>fxp1</replaceable>, + and bring the interfaces up with the IP Address of + <replaceable>10.0.0.3/24</replaceable>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput> +&prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create </userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable></userinput></screen> + + <para>View the interface status by running:</para> + + <screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput></screen> + + <para>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>To see the port status on the switch, use <userinput>show + lacp neighbor</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> + + <para>For more detail use the <userinput>show lacp neighbor + detail</userinput> command.</para> + + <para>To retain this configuration across reboots, the following + entries can be added to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_<replaceable>fxp0</replaceable>="up" +ifconfig_<replaceable>fxp1</replaceable>="up" +cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>" +ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable>" +</programlisting> + </example> + <example id="networking-lagg-failover"> + <title>Failover Mode</title> + + <para>Failover mode can be used to switch over to a secondary interface if + the link is lost on the master interface. Bring the underlying + physical interfaces up. Create the &man.lagg.4; interface, using + <replaceable>fxp0</replaceable> as the master interface and + <replaceable>fxp1</replaceable> as the secondary interface and assign + an IP Address of <replaceable>10.0.0.15/24</replaceable>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput> +&prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable></userinput></screen> + + <para>The interface will look something like this, the major + differences will be the <acronym>MAC</acronym> address and the + device names:</para> + + <screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput> +lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=8<VLAN_MTU> + ether 00:05:5d:71:8d:b8 + inet 10.0.0.15 netmask 0xffffff00 broadcast 10.0.0.255 + 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 + <replaceable>fxp0</replaceable>. If the link is lost on + <replaceable>fxp0</replaceable> then <replaceable>fxp1</replaceable> will + become the active link. If the link is restored on the master + interface then it will once again become the active link.</para> + + <para>To retain this configuration across reboots, the following + entries can be added to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_<replaceable>fxp0</replaceable>="up" +ifconfig_<replaceable>fxp1</replaceable>="up" +cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>" +ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable>" +</programlisting> + </example> + <example id="networking-lagg-wired-and-wireless"> + <title>Failover Mode Between Wired and Wireless Interfaces</title> + + <para>For laptop users, it is usually desirable to make wireless as a + secondary interface, which is to be used when the wired connection + is not available. With &man.lagg.4;, it is possible to use one + IP address, prefer the wired connection for both performance and + security reasons, while maintaining the ability to transfer data + over the wireless connection.</para> + + <para>In this setup, we will need to override the underlying + wireless interface's <acronym>MAC</acronym> address to match the &man.lagg.4;'s, + which is inherited from the master interface being used, the + wired interface.</para> + + <para>In this setup, we will treat the wired interface, + <replaceable>bge0</replaceable>, as the master, and the wireless + interface, + <replaceable>wlan0</replaceable>, as the failover interface. The + <replaceable>wlan0</replaceable> was created from + <replaceable>iwn0</replaceable> which we will set up with + the wired connection's <acronym>MAC</acronym> address. The first step would be + to obtain the <acronym>MAC</acronym> address from the wired interface:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable></userinput> +bge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=19b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,TSO4> + ether 00:21:70:da:ae:37 + inet6 fe80::221:70ff:feda:ae37%bge0 prefixlen 64 scopeid 0x2 + nd6 options=29<PERFORMNUD,IFDISABLED,AUTO_LINKLOCAL> + media: Ethernet autoselect (1000baseT <full-duplex>) + status: active</screen> + + <para>You can replace the <replaceable>bge0</replaceable> to match + your reality, and will get a different <literal>ether</literal> + line which is the <acronym>MAC</acronym> address of your wired interface. Now, + we change the underlying wireless interface, + <replaceable>iwn0</replaceable>:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>iwn0</replaceable> ether <replaceable>00:21:70:da:ae:37</replaceable></userinput></screen> + + <para>Bring up the wireless interface but don't set up any IP + address on it:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>iwn0</replaceable> ssid <replaceable>my_router</replaceable> up</userinput></screen> + + <para>Bring the <replaceable>bge0</replaceable> interface up. Create + the &man.lagg.4; interface with <replaceable>bge0</replaceable> + as master, and failover to <replaceable>wlan0</replaceable> if + necessary:</para> + + <screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable> up</userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput> +&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>bge0</replaceable> laggport <replaceable>wlan0</replaceable></userinput></screen> + + <para>The interface will look something like this, the major + differences will be the <acronym>MAC</acronym> address and the + device names:</para> + + <screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput> +lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=8<VLAN_MTU> + ether 00:21:70:da:ae:37 + media: Ethernet autoselect + status: active + laggproto failover + laggport: wlan0 flags=0<> + laggport: bge0 flags=5<MASTER,ACTIVE></screen> + + <para>Then start the DHCP client to obtain an IP address:</para> + + <screen>&prompt.root; <userinput>dhclient <literal>lagg<replaceable>0</replaceable></literal></userinput></screen> + + <para>To retain this configuration across reboots, the following + entries can be added to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_bge0="up" +ifconfig_iwn0="ether 00:21:70:da:ae:37" +wlans_iwn0="wlan0" +ifconfig_wlan0="WPA" +cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>" +ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover laggport bge0 laggport wlan0 DHCP" +</programlisting> + </example> + </sect2> + </sect1> + + <sect1 id="network-diskless"> + <sect1info> + <authorgroup> + <author> + <firstname>Jean-François</firstname> + <surname>Dockès</surname> + <contrib>Updated by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Alex</firstname> + <surname>Dupre</surname> + <contrib>Reorganized and enhanced by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Diskless Operation</title> + + <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 (<filename + role="package">net/etherboot</filename>) 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 + 4.2</application> is not part of the base + system. You will first need to install the + <filename role="package">net/isc-dhcp42-server</filename> 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 <hostid>margaux</hostid> + uses <application>Etherboot</application> and host + <hostid>corbieres</hostid> 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 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 id="co-dhcp-next-server"> + filename "/data/misc/kernel.diskless"; <co id="co-dhcp-filename"> + option root-path "192.168.4.4:/data/misc/diskless"; <co 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 + <replaceable>margaux</replaceable></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 class="directory">/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><ulink url="http://etherboot.sourceforge.net">Etherboot's Web + site</ulink> contains + <ulink url="http://etherboot.sourceforge.net/doc/html/userman/t1.html"> + extensive documentation</ulink> 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 <filename + role="package">net/etherboot</filename> 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/<replaceable>devicetype</replaceable>.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 +make installworld && make installkernel +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=<replaceable>/path/to/swapfile</replaceable> bs=1k count=1 oseek=<replaceable>100000</replaceable></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 id="network-pxe-nfs"> + <sect1info> + <authorgroup> + <author> + <firstname>Craig</firstname> + <surname>Rodrigues</surname> + <affiliation> + <address>rodrigc@FreeBSD.org</address> + </affiliation> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>PXE Booting with an NFS Root File System</title> + + <para>The &intel; Preboot eXecution Environment (<acronym>PXE</acronym>) + allows booting the operating system over the network. + <acronym>PXE</acronym> support is usually provided in the + <acronym>BIOS</acronym> of modern motherboards, where + it can be enabled in the <acronym>BIOS</acronym> settings + which enable booting from the network. A fully functioning + <acronym>PXE</acronym> setup also requires properly configured + <acronym>DHCP</acronym> and <acronym>TFTP</acronym> servers.</para> + + <para>When the host computer boots, it receives information over + <acronym>DHCP</acronym> about where to obtain the initial boot + loader via TFTP. After the host computer receives this information, + it downloads the boot loader via <acronym>TFTP</acronym>, and then + executes the boot loader. This is documented in section 2.2.1 of the + <ulink url="http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf">Preboot Execution Environment (PXE) Specification</ulink>. + In &os;, the boot loader retrieved during the <acronym>PXE</acronym> + process is <filename>/boot/pxeboot</filename>. After + <filename>/boot/pxeboot</filename> executes, the &os; kernel is + loaded, and the rest of the &os; bootup sequence proceeds. + Refer to <xref linkend="boot"> for more information about + the &os; booting process.</para> + + <sect2> + <title>Setting Up the <command>chroot</command> Environment for the NFS Root File System</title> + + <procedure> + <step> + <para>Choose a directory which will have a &os; installation + which will be NFS mountable. For example, a directory such + as <filename>/b/tftpboot/FreeBSD/install</filename> can be used.</para> + + <screen>&prompt.root; <userinput>export NFSROOTDIR=/b/tftpboot/FreeBSD/install</userinput> +&prompt.root; <userinput>mkdir -p ${NFSROOTDIR}</userinput></screen> + </step> + + <step> + <para>Enable the NFS server by following the instructions in + <xref linkend="network-configuring-nfs">.</para> + </step> + + <step> + <para>Export the directory via NFS by adding the following to + <filename>/etc/exports</filename>:</para> + + <programlisting>/b -ro -alldirs</programlisting> + </step> + + <step> + <para>Restart the NFS server:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/nfsd restart</userinput></screen> + </step> + + <step> + <para>Enable &man.inetd.8; by following the steps outlined in + <xref linkend="network-inetd-settings">.</para> + </step> + + <step> + <para>Add the following line to + <filename>/etc/inetd.conf</filename>:</para> + + <programlisting>tftp dgram udp wait root /usr/libexec/tftpd tftpd -l -s /b/tftpboot</programlisting> + </step> + + <step> + <para>Restart inetd:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/inetd restart</userinput></screen> + </step> + + <step> + <para><link linkend="makeworld">Rebuild the &os; kernel and userland</link>:</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make buildworld</userinput> +&prompt.root; <userinput>make buildkernel</userinput></screen> + </step> + + <step> + <para>Install &os; into the directory mounted over + <acronym>NFS</acronym>:</para> + + <screen> +&prompt.root; <userinput>make installworld DESTDIR=${NFSROOTDIR}</userinput> +&prompt.root; <userinput>make installkernel DESTDIR=${NFSROOTDIR}</userinput> +&prompt.root; <userinput>make distribution DESTDIR=${NFSROOTDIR}</userinput> + </screen> + </step> + + <step> + <para>Test that the <acronym>TFTP</acronym> server works and + can download the boot loader which will be obtained via PXE:</para> + + <screen> +&prompt.root; <userinput>tftp localhost</userinput> +tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput> +Received 264951 bytes in 0.1 seconds + </screen> + </step> + + <step> + <para>Edit <filename>${NFSROOTDIR}/etc/fstab</filename> and create an entry + to mount the root file system over NFS:</para> + + <programlisting> +# Device Mountpoint FSType Options Dump Pass +myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro 0 0 + </programlisting> + + <para>Replace <replaceable>myhost.example.com</replaceable> + with the hostname or IP address of your <acronym>NFS</acronym> + server. In this example, the root file system is mounted + "read-only" in order to prevent <acronym>NFS</acronym> + clients from potentially deleting the contents of the root + file system.</para> + </step> + + <step> + <para>Set the root password in the &man.chroot.8; + environment.</para> + <screen>&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput> +&prompt.root; <userinput>passwd</userinput></screen> + <para>This will set the root password for client machines + which are <acronym>PXE</acronym> booting.</para> + </step> + + <step> + <para>Enable ssh root logins for client machines which are + <acronym>PXE</acronym> booting by editing + <filename>${NFSROOTDIR}/etc/ssh/sshd_config</filename> + and enabling the <literal>PermitRootLogin</literal> option. + This is documented in &man.sshd.config.5;.</para> + </step> + + <step> + <para>Perform other customizations of the &man.chroot.8; + environment in ${NFSROOTDIR}. These customizations could + include things like adding packages with &man.pkg.add.1;, + editing the password file with &man.vipw.8;, or editing + &man.amd.conf.5; maps for automounting. For example:</para> + + <screen> +&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput> +&prompt.root; <userinput>pkg_add -r bash</userinput></screen> + </step> + </procedure> + </sect2> + + <sect2> + <title>Configuring Memory File Systems Used by <filename>/etc/rc.initdiskless</filename></title> + + <para>If you boot from an NFS root volume, + <filename>/etc/rc</filename> + detects that you booted over NFS and runs the + <filename>/etc/rc.initdiskless</filename> script. + Read the comments in this script to understand what is going on. + We need to make <filename>/etc</filename> and + <filename>/var</filename> memory backed + file systems because these directories need to be writable, but + the NFS root directory is read-only.</para> + + <screen> +&prompt.root; <userinput>chroot ${NFSROOTDIR}</userinput> +&prompt.root; <userinput>mkdir -p conf/base</userinput> +&prompt.root; <userinput>tar -c -v -f conf/base/etc.cpio.gz --format cpio --gzip etc</userinput> +&prompt.root; <userinput>tar -c -v -f conf/base/var.cpio.gz --format cpio --gzip var</userinput></screen> + + <para>When the system boots, memory file systems for + <filename>/etc</filename> and <filename>/var</filename> + will be created and mounted, and the contents of the + <filename>cpio.gz</filename> files will be copied into them.</para> + </sect2> + + <sect2> + <title>Setting up the DHCP Server</title> + + <para>PXE requires a <acronym>TFTP</acronym> server and a + <acronym>DHCP</acronym> server to be set up. The + <acronym>DHCP</acronym> server does not necessarily need + to be the same machine as the <acronym>TFTP</acronym> server, + but it needs to be accessible in your network.</para> + + <procedure> + <step> + <para>Install the <acronym>DHCP</acronym> server by following + the instructions documented at <xref linkend="network-dhcp-server">. + Make sure that <filename>/etc/rc.conf</filename> + and <filename>/usr/local/etc/dhcpd.conf</filename> + are correctly configured.</para> + </step> + + <step> + <para>In <filename>/usr/local/etc/dhcpd.conf</filename>, configure + the <literal>next-server</literal>, <literal>filename</literal>, + and <literal>option root-path</literal> settings, + to specify your <acronym>TFTP</acronym> server IP address, + the path to <filename>/boot/pxeboot</filename> in + <acronym>TFTP</acronym>, and the path to the <acronym>NFS</acronym> + root file system. Here is a sample <filename>dhcpd.conf</filename> + setup:</para> + + <programlisting> +subnet 192.168.0.0 netmask 255.255.255.0 { + range 192.168.0.2 192.168.0.3 ; + option subnet-mask 255.255.255.0 ; + option routers 192.168.0.1 ; + option broadcast-address 192.168.0.255 ; + option domain-name-server 192.168.35.35, 192.168.35.36 ; + option domain-name "example.com"; + + # IP address of TFTP server + next-server 192.168.0.1 ; + + # path of boot loader obtained + # via tftp + filename "FreeBSD/install/boot/pxeboot" ; + + # pxeboot boot loader will try to NFS mount this directory for root FS + option root-path "192.168.0.1:/b/tftpboot/FreeBSD/install/" ; + +} + </programlisting> + </step> + </procedure> + </sect2> + + <sect2> + <title>Configuring the PXE Client and Debugging Connection Problems</title> + + <procedure> + <step> + <para>When the client machine boots up, enter the + <acronym>BIOS</acronym> configuration menu. Configure the + <acronym>BIOS</acronym> to boot from the network. If all your + previous configuration steps are correct, then everything should + "just work".</para> + </step> + + <step> + <para>Use the <filename role="package">net/wireshark</filename> + port to debug the <acronym>DHCP</acronym> and <acronym>TFTP</acronym> + network traffic to look for any problems.</para> + </step> + + <step> + <para>Make sure that the <filename>pxeboot</filename> file can + be retrieved by <acronym>TFTP</acronym>. On your + <acronym>TFTP</acronym> server, look in + <filename>/var/log/xferlog</filename> to ensure that the + <filename>pxeboot</filename> file is being retrieved from + the correct location. To test the configuration from + <filename>dhcpd.conf</filename> above:</para> + + <screen>&prompt.root; <userinput>tftp 192.168.0.1</userinput> +tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput> +Received 264951 bytes in 0.1 seconds</screen> + + <para>Read &man.tftpd.8; and &man.tftp.1;. The + <literal>BUGS</literal> sections in these pages + document some limitations with + <acronym>TFTP</acronym>.</para> + </step> + + <step> + <para>Make sure that the root file system can be mounted + via <acronym>NFS</acronym>. To test configuration from + <filename>dhcpd.conf</filename> above:</para> + + <screen>&prompt.root; <userinput>mount -t nfs 192.168.0.1:/b/tftpboot/FreeBSD/install /mnt</userinput></screen> + </step> + + <step> + <para>Read the code in <filename>src/sys/boot/i386/libi386/pxe.c</filename> + to understand how the <filename>pxeboot</filename> loader sets + variables like <literal>boot.nfsroot.server</literal> and + <literal>boot.nfsroot.path</literal>. These variables are then + used in the NFS diskless root mount code in + <filename>src/sys/nfsclient/nfs_diskless.c</filename>.</para> + </step> + + <step> + <para>Read &man.pxeboot.8; and &man.loader.8;.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="network-isdn"> + <title>ISDN</title> + + <indexterm> + <primary>ISDN</primary> + </indexterm> + + <para>A good resource for information on ISDN technology and hardware is + <ulink url="http://www.alumni.caltech.edu/~dank/isdn/">Dan Kegel's ISDN + Page</ulink>.</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 id="network-isdn-cards"> + <sect2info> + <authorgroup> + <author> + <firstname>Hellmuth</firstname> + <surname>Michaelis</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <title>ISDN Cards</title> + + <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 + the <ulink + url="http://www.freebsd-support.de/i4b/">homepage of + isdn4bsd</ulink> which also has pointers to hints, erratas and + much more documentation such as the <ulink + url="http://people.FreeBSD.org/~hm/">isdn4bsd + handbook</ulink>.</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 <ulink + url="&url.articles.serial-uart;/index.html">FreeBSD Serial + Hardware</ulink> 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 <ulink + url="&url.base;/search/index.html">archives</ulink> 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 id="network-natd"> + <sect1info> + <authorgroup> + <author> + <firstname>Chern</firstname> + <surname>Lee</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Network Address Translation</title> + + <sect2 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 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 id="network-natdloaderconfiguration"> + <indexterm> + <primary>boot loader</primary> + <secondary>configuration</secondary> + </indexterm> + + <title>Boot Loader Configuration</title> + + <para>The kernel features for network address translation with + &man.natd.8; are not enabled in the <filename>GENERIC</filename> + kernel, but they can be preloaded at boot time, by adding a couple of + options to <filename>/boot/loader.conf</filename>:</para> + + <programlisting>ipfw_load="YES" +ipdivert_load="YES"</programlisting> + + <para>Additionally, + the <literal>net.inet.ip.fw.default_to_accept</literal> tunable + option may be set to <literal>1</literal>:</para> + + <programlisting>net.inet.ip.fw.default_to_accept="1"</programlisting> + + <note> + <para>It is a very good idea to set this option during the first + attempts to setup a firewall and NAT gateway. This way the default + policy of &man.ipfw.8; will be <literal>allow ip from any to + any</literal> instead of the less permissive <literal>deny ip from + any to any</literal>, and it will be slightly more difficult to get + locked out of the system right after a reboot.</para> + </note> + </sect2> + + <sect2 id="network-natdkernconfiguration"> + <title>Kernel Configuration</title> + + <indexterm> + <primary>kernel</primary> + <secondary>configuration</secondary> + </indexterm> + <para>When modules are not an option or if it is preferrable to + build all the required features into the running kernel, 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> + </sect2> + + <sect2 id="network-natdsystemconfiguration"> + <title>System Startup Configuration</title> + + <para>To enable firewall and NAT support at boot time, the + following must be in <filename>/etc/rc.conf</filename>:</para> + + <programlisting>gateway_enable="YES" <co id="co-natd-gateway-enable"> +firewall_enable="YES" <co id="co-natd-firewall-enable"> +firewall_type="OPEN" <co id="co-natd-firewall-type"> +natd_enable="YES" +natd_interface="<replaceable>fxp0</replaceable>" <co id="co-natd-natd-interface"> +natd_flags="" <co 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 <ulink + url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC 1918</ulink> + and have a default gateway of the <application>natd</application> machine's internal IP + address.</para> + + <para>For example, client <hostid>A</hostid> and + <hostid>B</hostid> behind the LAN have IP addresses of <hostid + role="ipaddr">192.168.0.2</hostid> and <hostid + role="ipaddr">192.168.0.3</hostid>, while the natd machine's + LAN interface has an IP address of <hostid + role="ipaddr">192.168.0.1</hostid>. Client <hostid>A</hostid> + and <hostid>B</hostid>'s default gateway must be set to that + of the <application>natd</application> machine, <hostid + role="ipaddr">192.168.0.1</hostid>. 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 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 <hostid>A</hostid>, and a web server runs + on client <hostid>B</hostid>. 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 <hostid>A</hostid>.</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 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 <hostid role="ipaddr">128.1.1.1</hostid>, + <hostid role="ipaddr">128.1.1.2</hostid>, and + <hostid role="ipaddr">128.1.1.3</hostid> belong to the <application>natd</application> gateway + machine. <hostid role="ipaddr">128.1.1.1</hostid> can be used + as the <application>natd</application> gateway machine's external IP address, while + <hostid role="ipaddr">128.1.1.2</hostid> and + <hostid role="ipaddr">128.1.1.3</hostid> are forwarded back to LAN + clients <hostid>A</hostid> and <hostid>B</hostid>.</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 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 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 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 <username>root</username>. For example, if you want to connect + the host <hostid>host1</hostid> with another machine <hostid>host2</hostid>:</para> + + <programlisting> host1 <-----> host2 +IP Address 10.0.0.1 10.0.0.2</programlisting> + + <para>Configure the interface on <hostid>host1</hostid> by doing:</para> + + <screen>&prompt.root; <userinput>ifconfig plip0 10.0.0.1 10.0.0.2</userinput></screen> + + <para>Configure the interface on <hostid>host2</hostid> 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 host2</programlisting> + + <para>To confirm the connection works, go to each host and ping + the other. For example, on <hostid>host1</hostid>:</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 id="network-ipv6"> + <sect1info> + <authorgroup> + <author> + <firstname>Aaron</firstname> + <surname>Kaplan</surname> + <contrib>Originally Written by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Restructured and Added by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Brad</firstname> + <surname>Davis</surname> + <contrib>Extended by </contrib> + </author> + </authorgroup> + + </sect1info> + + <title>IPv6</title> + <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 + (<hostid role="ipaddr">10.0.0.0/8</hostid>, + <hostid role="ipaddr">172.16.0.0/12</hostid>, and + <hostid role="ipaddr">192.168.0.0/16</hostid>) + 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 (<ulink + url="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</ulink>)</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 <ulink url="http://playground.sun.com/pub/ipng/html/ipng-main.html">playground.sun.com</ulink></para> + </listitem> + + <listitem> + <para><ulink url="http://www.kame.net">KAME.net</ulink></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 <hostid role="ipaddr">xxx.xxx.xxx.255</hostid>) 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><hostid role="ip6addr">::</hostid></entry> + <entry>128 bits</entry> + <entry>unspecified</entry> + <entry>cf. <hostid role="ipaddr">0.0.0.0</hostid> in + IPv4</entry> + </row> + + <row> + <entry><hostid role="ip6addr">::1</hostid></entry> + <entry>128 bits</entry> + <entry>loopback address</entry> + <entry>cf. <hostid role="ipaddr">127.0.0.1</hostid> in + IPv4</entry> + </row> + + <row> + <entry><hostid + role="ip6addr">::00:xx:xx:xx:xx</hostid></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><hostid + role="ip6addr">::ff:xx:xx:xx:xx</hostid></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><hostid role="ip6addr">fe80::</hostid> - <hostid + role="ip6addr">feb::</hostid></entry> + <entry>10 bits</entry> + <entry>link-local</entry> + <entry>cf. loopback address in IPv4</entry> + </row> + + <row> + <entry><hostid role="ip6addr">fec0::</hostid> - <hostid + role="ip6addr">fef::</hostid></entry> + <entry>10 bits</entry> + <entry>site-local</entry> + <entry> </entry> + </row> + + <row> + <entry><hostid role="ip6addr">ff::</hostid></entry> + <entry>8 bits</entry> + <entry>multicast</entry> + <entry> </entry> + </row> + + <row> + <entry><hostid role="ip6addr">001</hostid> (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: <hostid role="ip6addr">x:x:x:x:x:x:x:x</hostid>, each + <quote>x</quote> being a 16 Bit hex value. For example + <hostid role="ip6addr">FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</hostid></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 <hostid role="ip6addr">fe80::1</hostid> + corresponds to the canonical form + <hostid role="ip6addr">fe80:0000:0000:0000:0000:0000:0000:0001</hostid>.</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 + <hostid role="ip6addr">2002::10.0.0.1</hostid> + corresponds to the (hexadecimal) canonical representation + <hostid role="ip6addr">2002:0000:0000:0000:0000:0000:0a00:0001</hostid> + which in turn is equivalent to + writing <hostid role="ip6addr">2002::a00:1</hostid>.</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><hostid role="ip6addr">fe80::200:21ff:fe03:8e1%rl0</hostid> + 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 <ulink + url="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</ulink>.</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>Contact your Internet Service Provider to see if they + offer IPv6 yet.</para> + </listitem> + + <listitem> + <para><ulink url="http://www.sixxs.net">SixXS</ulink> offers + tunnels with end-points all around the globe.</para> + </listitem> + + <listitem> + <para>Tunnel via 6-to-4 (<ulink + url="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</ulink>)</para> + </listitem> + + <listitem> + <para>Use the <filename role="package">net/freenet6</filename> 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 <filename role="package">dns/djbdns</filename> (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 <hostid role="ip6addr"> + 2001:471:1f11:251:290:27ff:fee0:2093</hostid>, to your + <devicename>fxp0</devicename> interface, add:</para> + + <programlisting>ipv6_ifconfig_fxp0="2001:471:1f11:251:290:27ff:fee0:2093"</programlisting> + + <para>To assign a default router of + <hostid role="ip6addr">2001:471:1f11:251::1</hostid> + 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 <devicename>gif0</devicename>:</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 + <devicename>fxp0</devicename>:</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 <devicename>fxp0</devicename> with the interface you + are going to be using.</para> + + <para>Next, replace <hostid role="ip6addr">2001:471:1f11:246::</hostid> + with the prefix of your allocation.</para> + + <para>If you are dedicated a <hostid role="netmask">/64</hostid> 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 id="network-atm"> + <sect1info> + <authorgroup> + <author> + <firstname>Harti</firstname> + <surname>Brandt</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>Asynchronous Transfer Mode (ATM)</title> + + <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><hostid>hostA</hostid></entry> + <entry><hostid role="ipaddr">192.168.173.1</hostid></entry> + </row> + + <row> + <entry><hostid>hostB</hostid></entry> + <entry><hostid role="ipaddr">192.168.173.2</hostid></entry> + </row> + + <row> + <entry><hostid>hostC</hostid></entry> + <entry><hostid role="ipaddr">192.168.173.3</hostid></entry> + </row> + + <row> + <entry><hostid>hostD</hostid></entry> + <entry><hostid role="ipaddr">192.168.173.4</hostid></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><hostid>hostA</hostid> - <hostid>hostB</hostid></entry> + <entry>0.100</entry> + </row> + + <row> + <entry><hostid>hostA</hostid> - <hostid>hostC</hostid></entry> + <entry>0.101</entry> + </row> + + <row> + <entry><hostid>hostA</hostid> - <hostid>hostD</hostid></entry> + <entry>0.102</entry> + </row> + + <row> + <entry><hostid>hostB</hostid> - <hostid>hostC</hostid></entry> + <entry>0.103</entry> + </row> + + <row> + <entry><hostid>hostB</hostid> - <hostid>hostD</hostid></entry> + <entry>0.104</entry> + </row> + + <row> + <entry><hostid>hostC</hostid> - <hostid>hostD</hostid></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 + <devicename>hatm0</devicename> on all hosts. Now the PVCs + need to be configured on <hostid>hostA</hostid> (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 <hostid>hostA</hostid> 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 id="carp"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Common Address Redundancy Protocol (CARP)</title> + + <indexterm><primary>CARP</primary></indexterm> + <indexterm><primary>Common Address Redundancy Protocol</primary></indexterm> + + <para>The Common Address 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 as described in <xref + linkend="kernelconfig"> with the following option:</para> + + <programlisting>device carp</programlisting> + + <para>Alternatively, the <filename>if_carp.ko</filename> module can + be loaded at boot time. Add the following line to the + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>if_carp_load="YES"</programlisting> + + <para><acronym>CARP</acronym> functionality should now be available + and may be tuned via several <command>sysctl</command> + <acronym>OID</acronym>s:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>OID</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><varname>net.inet.carp.allow</varname></entry> + <entry>Accept incoming <acronym>CARP</acronym> packets. + Enabled by default.</entry> + </row> + + <row> + <entry><varname>net.inet.carp.preempt</varname></entry> + <entry>This option downs all of the <acronym>CARP</acronym> + interfaces on the host when one of them goes down. + Disabled by default</entry> + </row> + + <row> + <entry><varname>net.inet.carp.log</varname></entry> + <entry>A value of <literal>0</literal> disables any logging. + A Value of <literal>1</literal> enables logging of bad + <acronym>CARP</acronym> packets. Values greater than + <literal>1</literal> enables logging of state changes for + the <acronym>CARP</acronym> interfaces. The default value + is <literal>1</literal>.</entry> + </row> + + <row> + <entry><varname>net.inet.carp.arpbalance</varname></entry> + <entry>Balance local network traffic using + <acronym>ARP</acronym>. Disabled by default.</entry> + </row> + + <row> + <entry><varname>net.inet.carp.suppress_preempt</varname></entry> + <entry>A read only <acronym>OID</acronym> showing the status + of preemption suppression. Preemption can be suppressed + if link on an interface is down. A value of + <literal>0</literal>, means that preemption is not + suppressed. Every problem increments this + <acronym>OID</acronym>.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>The <acronym>CARP</acronym> devices themselves may be created + 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 + <hostid>hosta.example.org</hostid> and + <hostid>hostb.example.org</hostid> respectively. First, the + required lines for a <acronym>CARP</acronym> configuration have + to be added to <filename>rc.conf</filename>. For + <hostid>hosta.example.org</hostid>, 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 testpass 192.168.1.50/24"</programlisting> + + <para>On <hostid>hostb.example.org</hostid> 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 <devicename>carp</devicename> 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, + <hostid>provider.example.org</hostid>, should be prepared so that + it may handle failover from either host. This machine will require + two <devicename>carp</devicename> 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 <devicename>carp</devicename> devices will + allow <hostid>provider.example.org</hostid> 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, + <hostid>provider.example.org</hostid> may not relinquish the + <acronym>IP</acronym> address back to the original content + server. In this case, an administrator may have to manually + force the IP back to the master. The following command + should be issued on + <hostid>provider.example.org</hostid>:</para> + + <screen>&prompt.root; <userinput>ifconfig carp0 down && ifconfig carp0 up</userinput></screen> + + <para>This should be done on the <devicename>carp</devicename> + 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> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> +<!-- LocalWords: config mnt www --> diff --git a/en_US.ISO8859-1/books/handbook/appendix.decl b/en_US.ISO8859-1/books/handbook/appendix.decl new file mode 100644 index 0000000000..5b0425623d --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/appendix.decl @@ -0,0 +1 @@ +<!DOCTYPE appendix PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"> diff --git a/en_US.ISO8859-1/books/handbook/audit/Makefile b/en_US.ISO8859-1/books/handbook/audit/Makefile new file mode 100644 index 0000000000..84cb9b04ee --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/audit/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= audit/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/audit/chapter.sgml b/en_US.ISO8859-1/books/handbook/audit/chapter.sgml new file mode 100644 index 0000000000..5e12fc9b51 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/audit/chapter.sgml @@ -0,0 +1,716 @@ +<!-- + The FreeBSD Documentation Project + $FreeBSD$ +--> + +<!-- 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 id="audit"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + <author> + <firstname>Robert</firstname> + <surname>Watson</surname> + </author> + </authorgroup> + </chapterinfo> + + <title>Security Event Auditing</title> + + <sect1 id="audit-synopsis"> + <title>Synopsis</title> + + <indexterm><primary>AUDIT</primary></indexterm> + <indexterm> + <primary>Security Event Auditing</primary> + <see>MAC</see> + </indexterm> + + <para>The &os; operating system includes support for fine-grained + security event auditing. Event auditing allows the reliable, + fine-grained, and configurable logging of a variety of + security-relevant system events, including logins, configuration + changes, and file and network access. These log records can be + invaluable for live system monitoring, intrusion detection, and + postmortem analysis. &os; implements &sun;'s published + <acronym>BSM</acronym> API and file format, and is interoperable with + both &sun;'s &solaris; and &apple;'s &macos; X audit implementations.</para> + + <para>This chapter focuses on the installation and configuration of + Event Auditing. It explains audit policies, and provides an example + audit configuration.</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> + + <listitem> + <para>How to review the audit trail using the audit reduction and + review tools.</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>The audit facility has some known limitations which include + that not all security-relevant system events are currently auditable, + and that some login mechanisms, such as X11-based display managers + and third party daemons, do not properly configure auditing for user + login sessions.</para> + + <para>The security event auditing facility is able to generate very + detailed logs of system activity: on a busy system, trail file + data can be very large when configured for high detail, exceeding + gigabytes a week in some configurations. Administrators should take + into account disk space requirements associated with high volume + audit configurations. For example, it may be desirable to dedicate + a file system to the <filename>/var/audit</filename> tree so that + other file systems are not affected if the audit file system becomes + full.</para> + </warning> + + </sect1> + + <sect1 id="audit-inline-glossary"> + <title>Key Terms in This Chapter</title> + + <para>Before reading this chapter, a few key audit-related terms must be + explained:</para> + + <itemizedlist> + <listitem> + <para><emphasis>event</emphasis>: An auditable event is any event + that can be logged using the audit subsystem. + Examples of security-relevant events include the creation of + a file, the building of a network connection, or a user logging in. + Events are either <quote>attributable</quote>, + meaning that they can be traced to an authenticated user, or + <quote>non-attributable</quote> if they cannot be. + Examples of non-attributable events are any events that occur + before authentication in the login process, such as bad password + attempts.</para> + </listitem> + + <listitem> + <para><emphasis>class</emphasis>: Event classes are named sets of + related events, and are used in selection expressions. Commonly + used classes of events include <quote>file creation</quote> (fc), + <quote>exec</quote> (ex) and <quote>login_logout</quote> + (lo).</para> + </listitem> + + <listitem> + <para><emphasis>record</emphasis>: A record is an audit log entry + describing a security event. Records contain a record event type, + information on the subject (user) performing the action, + date and time information, information on any objects or + arguments, and a success or failure condition.</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>selection expression</emphasis>: A selection + expression is a string containing a list of prefixes and audit + event class names used to match events.</para> + </listitem> + + <listitem> + <para><emphasis>preselection</emphasis>: The process by which the + system identifies which events are of interest to the administrator + in order to avoid generating audit records describing events that + are not of interest. The preselection configuration + uses a series of selection expressions to identify which classes + of events to audit for which users, as well as global settings + that apply to both authenticated and unauthenticated + processes.</para> + </listitem> + + <listitem> + <para><emphasis>reduction</emphasis>: The process by which records + from existing audit trails are selected for preservation, printing, + or analysis. Likewise, the process by which undesired audit + records are removed from the audit trail. Using reduction, + administrators can implement policies for the preservation of audit + data. For example, detailed audit trails might be kept for one + month, but after that, trails might be reduced in order to preserve + only login information for archival purposes.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="audit-install"> + <title>Installing Audit Support</title> + + <para>User space support for Event Auditing is installed as part of the + base &os; operating system. Kernel support for + Event Auditing is compiled in by default, but support for this + feature must be explicitly compiled into the custom kernel by adding + the following line to the 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 an audit-enabled kernel is built, installed, and the system + has been rebooted, enable the audit daemon by adding the following line + to &man.rc.conf.5;:</para> + + <programlisting>auditd_enable="YES"</programlisting> + + <para>Audit support must then be started by a reboot, or by manually + starting the audit daemon:</para> + + <programlisting>/etc/rc.d/auditd start</programlisting> + </sect1> + + <sect1 id="audit-config"> + <title>Audit Configuration</title> + + <para>All configuration files for security audit are found in + <filename class="directory">/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, + maximum audit trail size, etc.</para> + </listitem> + + <listitem> + <para><filename>audit_event</filename> - Textual names and + descriptions of system audit events, as well as a list of which + classes each event is in.</para> + </listitem> + + <listitem> + <para><filename>audit_user</filename> - User-specific audit + requirements, which are combined with the global defaults at + login.</para> + </listitem> + + <listitem> + <para><filename>audit_warn</filename> - A customizable shell script + used by <application>auditd</application> to generate warning messages in exceptional + situations, such as when space for audit records is running low or + when the audit trail file has been rotated.</para> + </listitem> + </itemizedlist> + + <warning> + <para>Audit configuration files should be edited and maintained + carefully, as errors in configuration may result in improper + logging of events.</para> + </warning> + + <sect2> + <title>Event Selection Expressions</title> + + <para>Selection expressions are used in a number of places in the + audit configuration to determine which events should be audited. + Expressions contain a list of event classes to match, each with + a prefix indicating whether matching records should be accepted + or ignored, and optionally to indicate if the entry is intended + to match successful or failed operations. Selection expressions + are evaluated from left to right, and two expressions are + combined by appending one onto the other.</para> + + <para>The following list contains the default audit event classes + present in <filename>audit_class</filename>:</para> + + <itemizedlist> + <listitem> + <para><literal>all</literal> - <emphasis>all</emphasis> - Match all + event classes.</para> + </listitem> + + <listitem> + <para><literal>ad</literal> - <emphasis>administrative</emphasis> + - Administrative actions performed on the system as a + whole.</para> + </listitem> + + <listitem> + <para><literal>ap</literal> - <emphasis>application</emphasis> - + Application defined action.</para> + </listitem> + + <listitem> + <para><literal>cl</literal> - <emphasis>file close</emphasis> - + Audit calls to the <function>close</function> system + call.</para> + </listitem> + + <listitem> + <para><literal>ex</literal> - <emphasis>exec</emphasis> - Audit + program execution. Auditing of command line arguments and + environmental variables is controlled via &man.audit.control.5; + using the <literal>argv</literal> and <literal>envv</literal> + parameters to the <literal>policy</literal> setting.</para> + </listitem> + + <listitem> + <para><literal>fa</literal> - <emphasis>file attribute access</emphasis> + - Audit the access of object attributes such as + &man.stat.1;, &man.pathconf.2; and similar events.</para> + </listitem> + + <listitem> + <para><literal>fc</literal> - <emphasis>file create</emphasis> + - Audit events where a file is created as a result.</para> + </listitem> + + <listitem> + <para><literal>fd</literal> - <emphasis>file delete</emphasis> + - Audit events where file deletion occurs.</para> + </listitem> + + <listitem> + <para><literal>fm</literal> - <emphasis>file attribute modify</emphasis> + - Audit events where file attribute modification occurs, + such as &man.chown.8;, &man.chflags.1;, &man.flock.2;, + etc.</para> + </listitem> + + <listitem> + <para><literal>fr</literal> - <emphasis>file read</emphasis> + - Audit events in which data is read, files are opened for + reading, etc.</para> + </listitem> + + <listitem> + <para><literal>fw</literal> - <emphasis>file write</emphasis> - + Audit events in which data is written, files are written + or modified, etc.</para> + </listitem> + + <listitem> + <para><literal>io</literal> - <emphasis>ioctl</emphasis> - Audit + use of the &man.ioctl.2; system call.</para> + </listitem> + + <listitem> + <para><literal>ip</literal> - <emphasis>ipc</emphasis> - Audit + various forms of Inter-Process Communication, including POSIX + pipes and System V <acronym>IPC</acronym> operations.</para> + </listitem> + + <listitem> + <para><literal>lo</literal> - <emphasis>login_logout</emphasis> - + Audit &man.login.1; and &man.logout.1; events occurring + on the system.</para> + </listitem> + + <listitem> + <para><literal>na</literal> - <emphasis>non attributable</emphasis> - + Audit non-attributable events.</para> + </listitem> + + <listitem> + <para><literal>no</literal> - <emphasis>invalid class</emphasis> - + Match no audit events.</para> + </listitem> + + <listitem> + <para><literal>nt</literal> - <emphasis>network</emphasis> - + Audit events related to network actions, such as + &man.connect.2; and &man.accept.2;.</para> + </listitem> + + <listitem> + <para><literal>ot</literal> - <emphasis>other</emphasis> - + Audit miscellaneous events.</para> + </listitem> + + <listitem> + <para><literal>pc</literal> - <emphasis>process</emphasis> - + Audit process operations, such as &man.exec.3; and + &man.exit.3;.</para> + </listitem> + + </itemizedlist> + + <para>These audit event classes may be customized by modifying the + <filename>audit_class</filename> and + <filename>audit_event</filename> configuration files.</para> + + <para>Each audit class in the list is combined with a prefix + indicating whether successful/failed operations are matched, and + whether the entry is adding or removing matching for the class + and type.</para> + + <itemizedlist> + <listitem> + <para>(none) Audit both successful and failed instances of the + event.</para> + </listitem> + + <listitem> + <para><literal>+</literal> Audit successful events in this + class.</para> + </listitem> + + <listitem> + <para><literal>-</literal> Audit failed events in this + class.</para> + </listitem> + + <listitem> + <para><literal>^</literal> Audit neither successful nor failed + events in this class.</para> + </listitem> + + <listitem> + <para><literal>^+</literal> Do not audit successful events in this + class.</para> + </listitem> + + <listitem> + <para><literal>^-</literal> Do not audit failed events in this + class.</para> + </listitem> + + </itemizedlist> + + <para>The following example selection string selects both successful + and failed login/logout events, but only successful execution + events:</para> + + <programlisting>lo,+ex</programlisting> + + </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 properties and policies; the second may be used to fine-tune + auditing by user.</para> + + <sect3 id="audit-auditcontrol"> + <title>The <filename>audit_control</filename> File</title> + + <para>The <filename>audit_control</filename> file specifies a number + of defaults for the audit subsystem. Viewing the contents of this + file, we see the following:</para> + + <programlisting>dir:/var/audit +flags:lo +minfree:20 +naflags:lo +policy:cnt +filesz:0</programlisting> + + <para>The <option>dir</option> option is used to set one or more + directories where audit logs will be stored. If more than one + directory entry appears, they will be used in order as they fill. + It is common to configure audit so that audit logs are stored on + a dedicated file system, in order to prevent interference between + the audit subsystem and other subsystems if the file system fills. + </para> + + <para>The <option>flags</option> field sets the system-wide default + preselection mask for attributable events. In the example above, + successful and failed login and logout events are audited for all + users.</para> + + <para>The <option>minfree</option> option defines the minimum + percentage of free space for the file system where the audit trail + is stored. When this threshold is exceeded, a warning will be + generated. The above example sets the minimum free space to + twenty percent.</para> + + <para>The <option>naflags</option> option specifies audit classes to + be audited for non-attributed events, such as the login process + and system daemons.</para> + + <para>The <option>policy</option> option specifies a comma-separated + list of policy flags controlling various aspects of audit + behavior. The default <literal>cnt</literal> flag indicates that + the system should continue running despite an auditing failure + (this flag is highly recommended). Another commonly used flag is + <literal>argv</literal>, which causes command line arguments to + the &man.execve.2; system call to be audited as part of command + execution.</para> + + <para>The <option>filesz</option> option specifies the maximum size + in bytes to allow an audit trail file to grow to before + automatically terminating and rotating the trail file. The + default, 0, disables automatic log rotation. If the requested + file size is non-zero and below the minimum 512k, it will be + ignored and a log message will be generated.</para> + </sect3> + + <sect3 id="audit-audituser"> + <title>The <filename>audit_user</filename> File</title> + + <para>The <filename>audit_user</filename> file permits the + administrator to specify further audit requirements for specific + users. + Each line configures auditing for a user via two fields: the + first is the <literal>alwaysaudit</literal> field, which specifies + a set of events that should always be audited for the user, and + the second is the <literal>neveraudit</literal> field, which + specifies a set of events that should never be audited for the + user.</para> + + <para>The following example <filename>audit_user</filename> file + audits login/logout events and successful command execution for + the <username>root</username> user, and audits file creation and successful command + execution for the <username>www</username> user. + If used with the example <filename>audit_control</filename> file + above, the <literal>lo</literal> entry for <username>root</username> + is redundant, and login/logout events will also be audited for the + <username>www</username> user.</para> + + <programlisting>root:lo,+ex:no +www:fc,+ex:no</programlisting> + + </sect3> + </sect2> + </sect1> + + <sect1 id="audit-administration"> + <title>Administering the Audit Subsystem</title> + + <sect2> + <title>Viewing Audit Trails</title> + + <para>Audit trails are stored in the BSM binary format, so tools must + be used to modify or convert to text. The &man.praudit.1; + command converts trail files to a simple text format; the + &man.auditreduce.1; command may be used to reduce the + audit trail file for analysis, archiving, or printing purposes. + <command>auditreduce</command> supports a variety of selection + parameters, including event type, event class, user, date or time of + the event, and the file path or object acted on.</para> + + <para>For example, the <command>praudit</command> utility will dump + the entire contents of a specified audit log in plain text:</para> + + <screen>&prompt.root; <userinput>praudit /var/audit/AUDITFILE</userinput></screen> + + <para>Where <filename><replaceable>AUDITFILE</replaceable></filename> is the audit log to + dump.</para> + + <para>Audit trails consist of a series of audit records made up of + tokens, which <command>praudit</command> prints sequentially one per + line. Each token is of a specific type, such as + <literal>header</literal> holding an audit record header, or + <literal>path</literal> holding a file path from a name + lookup. The following is an example of an + <literal>execve</literal> event:</para> + + <programlisting>header,133,10,execve(2),0,Mon Sep 25 15:58:03 2006, + 384 msec +exec arg,finger,doug +path,/usr/bin/finger +attribute,555,root,wheel,90,24918,104944 +subject,robert,root,wheel,root,wheel,38439,38032,42086,128.232.9.100 +return,success,0 +trailer,133</programlisting> + + <para>This audit represents a successful <literal>execve</literal> + call, in which the command <literal>finger doug</literal> has been run. The + arguments token contains both the processed command line presented + by the shell to the kernel. The <literal>path</literal> token holds the path to the + executable as looked up by the kernel. The <literal>attribute</literal> token + describes the binary, and in particular, includes the file mode + which can be used to determine if the application was setuid. + The <literal>subject</literal> token describes the subject process, and stores in + sequence the audit user ID, effective user ID and group ID, real + user ID and group ID, process ID, session ID, port ID, and login + address. Notice that the audit user ID and real user ID differ: + the user <username>robert</username> has switched to the + <username>root</username> account before running this command, but + it is audited using the original authenticated user. Finally, the + <literal>return</literal> token indicates the successful execution, and the <literal>trailer</literal> + concludes the record.</para> + + <para><command>praudit</command> also supports + an XML output format, which can be selected using the + <option>-x</option> argument.</para> + + </sect2> + + <sect2> + <title>Reducing Audit Trails</title> + + <para>Since audit logs may be very large, an administrator will + likely want to select a subset of records for using, such as records + associated with a specific user:</para> + + <screen>&prompt.root; <userinput>auditreduce -u trhodes /var/audit/AUDITFILE | praudit</userinput></screen> + + <para>This will select all audit records produced for the user + <username>trhodes</username> stored in the + <filename><replaceable>AUDITFILE</replaceable></filename> file.</para> + </sect2> + + <sect2> + <title>Delegating Audit Review Rights</title> + + <para>Members of the <groupname>audit</groupname> group are given + permission to read audit trails in <filename>/var/audit</filename>; + by default, this group is empty, so only the <username>root</username> user may read + audit trails. Users may be added to the <groupname>audit</groupname> + group in order to delegate audit review rights to the user. 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> + + <sect2> + <title>Live Monitoring Using Audit Pipes</title> + + <para>Audit pipes are cloning pseudo-devices in the device file system + which allow applications to tap the live audit record stream. This + is primarily of interest to authors of intrusion detection and + system monitoring applications. However, for the administrator the + audit pipe device is a convenient way to allow live monitoring + without running into problems with audit trail file ownership or + log rotation interrupting the event stream. To track the live audit + event stream, use the following command line:</para> + + <screen>&prompt.root; <userinput>praudit /dev/auditpipe</userinput></screen> + + <para>By default, audit pipe device nodes are accessible only to the + <username>root</username> user. To make them accessible to the members of the + <groupname>audit</groupname> group, add a <literal>devfs</literal> rule + to <filename>devfs.rules</filename>:</para> + + <programlisting>add path 'auditpipe*' mode 0440 group audit</programlisting> + + <para>See &man.devfs.rules.5; for more information on configuring + the devfs file system.</para> + + <warning> + <para>It is easy to produce audit event feedback cycles, in which + the viewing of each audit event results in the generation of more + audit events. For example, if all network I/O is audited, and + &man.praudit.1; is run from an SSH session, then a continuous stream of + audit events will be generated at a high rate, as each event + being printed will generate another event. It is advisable to run + <command>praudit</command> on an audit pipe device from sessions without fine-grained + I/O auditing in order to avoid this happening.</para> + </warning> + </sect2> + + <sect2> + <title>Rotating Audit Trail Files</title> + + <para>Audit trails are written to only by the kernel, and managed only + by the audit daemon, <application>auditd</application>. 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 may 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 <application>auditd</application> daemon is not currently + running, this 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>0 */12 * * * root /usr/sbin/audit -n</programlisting> + + <para>The change will take effect once you have saved the + new <filename>/etc/crontab</filename>.</para> + + <para>Automatic rotation of the audit trail file based on file size is + possible via the <option>filesz</option> option in + &man.audit.control.5;, and is described in the configuration files + section of this chapter.</para> + </sect2> + + <sect2> + <title>Compressing Audit Trails</title> + + <para>As audit trail files can become very large, it is often desirable + to compress or otherwise archive trails once they have been closed by + the audit daemon. The <filename>audit_warn</filename> script can be + used to perform customized operations for a variety of audit-related + events, including the clean termination of audit trails when they are + rotated. For example, the following may be added to the + <filename>audit_warn</filename> script to compress audit trails on + close:</para> + + <programlisting># +# Compress audit trail files on close. +# +if [ "$1" = closefile ]; then + gzip -9 $2 +fi</programlisting> + + <para>Other archiving activities might include copying trail files to + a centralized server, deleting old trail files, or reducing the audit + trail to remove unneeded records. The script will be run only when + audit trail files are cleanly terminated, so will not be run on + trails left unterminated following an improper shutdown.</para> + </sect2> + </sect1> +</chapter> diff --git a/en_US.ISO8859-1/books/handbook/basics/Makefile b/en_US.ISO8859-1/books/handbook/basics/Makefile new file mode 100644 index 0000000000..fea6942368 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/basics/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= basics/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/basics/chapter.sgml b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml new file mode 100644 index 0000000000..7c61897293 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/basics/chapter.sgml @@ -0,0 +1,2725 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="basics"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Chris</firstname> + <surname>Shumway</surname> + <contrib>Rewritten by </contrib> + </author> + </authorgroup> + <!-- 10 Mar 2000 --> + </chapterinfo> + + <title>UNIX Basics</title> + + <sect1 id="basics-synopsis"> + <title>Synopsis</title> + + <para>The following chapter will cover the basic commands and + functionality of the FreeBSD operating system. Much of this + material is relevant for any &unix;-like operating system. Feel + free to skim over this chapter if you are familiar with the + material. If you are new to FreeBSD, then you will definitely + want to read through this chapter carefully.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to use the <quote>virtual consoles</quote> of + FreeBSD.</para> + </listitem> + <listitem> + <para>How &unix; file permissions work along with + understanding file flags in &os;.</para> + </listitem> + <listitem> + <para>The default &os; file system layout.</para> + </listitem> + <listitem> + <para>The &os; disk organization.</para> + </listitem> + <listitem> + <para>How to mount and unmount file systems.</para> + </listitem> + <listitem> + <para>What processes, daemons, and signals are.</para> + </listitem> + <listitem> + <para>What a shell is, and how to change your default login + environment.</para> + </listitem> + <listitem> + <para>How to use basic text editors.</para> + </listitem> + <listitem> + <para>What devices and device nodes are.</para> + </listitem> + <listitem> + <para>What binary format is used under &os;.</para> + </listitem> + <listitem> + <para>How to read manual pages for more information.</para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1 id="consoles"> + <title>Virtual Consoles and Terminals</title> + <indexterm><primary>virtual consoles</primary></indexterm> + <indexterm><primary>terminals</primary></indexterm> + + <para>FreeBSD can be used in various ways. One of them is typing commands + to a text terminal. A lot of the flexibility and power of a &unix; + operating system is readily available at your hands when using FreeBSD + this way. This section describes what <quote>terminals</quote> and + <quote>consoles</quote> are, and how you can use them in FreeBSD.</para> + + <sect2 id="consoles-intro"> + <title>The Console</title> + <indexterm><primary>console</primary></indexterm> + + <para>If you have not configured FreeBSD to automatically start a + graphical environment during startup, the system will present you with + a login prompt after it boots, right after the startup scripts finish + running. You will see something similar to:</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>The messages might be a bit different on your system, but you will + see something similar. The last two lines are what we are interested + in right now. The second last line reads:</para> + + <programlisting>FreeBSD/i386 (pc3.example.org) (ttyv0)</programlisting> + + <para>This line contains some bits of information about the system you + have just booted. You are looking at a <quote>FreeBSD</quote> + console, running on an Intel or compatible processor of the x86 + architecture<footnote> + <para>This is what <literal>i386</literal> means. Note that even if + you are not running FreeBSD on an Intel 386 CPU, this is going to + be <literal>i386</literal>. It is not the type of your processor, + but the processor <quote>architecture</quote> that is shown + here.</para> + </footnote>. The name of this machine (every &unix; machine has a + name) is <hostid>pc3.example.org</hostid>, and you are now looking + at its system console—the <devicename>ttyv0</devicename> + terminal.</para> + + <para>Finally, the last line is always:</para> + + <programlisting>login:</programlisting> + + <para>This is the part where you are supposed to type in your + <quote>username</quote> to log into FreeBSD. The next section + describes how you can do this.</para> + </sect2> + + <sect2 id="consoles-login"> + <title>Logging into FreeBSD</title> + + <para>FreeBSD is a multiuser, multiprocessing system. This is + the formal description that is usually given to a system that can be + used by many different people, who simultaneously run a lot of + programs on a single machine.</para> + + <para>Every multiuser system needs some way to distinguish one + <quote>user</quote> from the rest. In FreeBSD (and all the + &unix;-like operating systems), this is accomplished by requiring that + every user must <quote>log into</quote> the system before being able + to run programs. Every user has a unique name (the + <quote>username</quote>) and a personal, secret key (the + <quote>password</quote>). FreeBSD will ask for these two before + allowing a user to run any programs.</para> + + <indexterm><primary>startup scripts</primary></indexterm> + <para>Right after FreeBSD boots and finishes running its startup + scripts<footnote> + <para>Startup scripts are programs that are run automatically by + FreeBSD when booting. Their main function is to set things up for + everything else to run, and start any services that you have + configured to run in the background doing useful things.</para> + </footnote>, it will present you with a prompt and ask for a valid + username:</para> + + <screen>login:</screen> + + <para>For the sake of this example, let us assume that your username is + <username>john</username>. Type <literal>john</literal> at this prompt and press + <keycap>Enter</keycap>. You should then be presented with a prompt to + enter a <quote>password</quote>:</para> + + <screen>login: <userinput>john</userinput> +Password:</screen> + + <para>Type in <username>john</username>'s password now, and press + <keycap>Enter</keycap>. The password is <emphasis>not + echoed!</emphasis> You need not worry about this right now. Suffice + it to say that it is done for security reasons.</para> + + <para>If you have typed your password correctly, you should by now be + logged into FreeBSD and ready to try out all the available + commands.</para> + + <para>You should see the <acronym>MOTD</acronym> or message of + the day followed by a command prompt (a <literal>#</literal>, + <literal>$</literal>, or <literal>%</literal> character). This + indicates you have successfully logged into FreeBSD.</para> + </sect2> + + <sect2 id="consoles-virtual"> + <title>Multiple Consoles</title> + + <para>Running &unix; commands in one console is fine, but FreeBSD can + run many programs at once. Having one console where commands can be + typed would be a bit of a waste when an operating system like FreeBSD + can run dozens of programs at the same time. This is where + <quote>virtual consoles</quote> can be very helpful.</para> + + <para>FreeBSD can be configured to present you with many different + virtual consoles. You can switch from one of them to any other + virtual console by pressing a couple of keys on your keyboard. Each + console has its own different output channel, and FreeBSD takes care + of properly redirecting keyboard input and monitor output as you + switch from one virtual console to the next.</para> + + <para>Special key combinations have been reserved by FreeBSD for + switching consoles<footnote> + <para>A fairly technical and accurate description of all the details + of the FreeBSD console and keyboard drivers can be found in the + manual pages of &man.syscons.4;, &man.atkbd.4;, &man.vidcontrol.1; + and &man.kbdcontrol.1;. We will not expand on the details here, + but the interested reader can always consult the manual pages for + a more detailed and thorough explanation of how things + work.</para> + </footnote>. You can use + <keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo>, + <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo>, through + <keycombo><keycap>Alt</keycap><keycap>F8</keycap></keycombo> to switch + to a different virtual console in FreeBSD.</para> + + <para>As you are switching from one console to the next, FreeBSD takes + care of saving and restoring the screen output. The result is an + <quote>illusion</quote> of having multiple <quote>virtual</quote> + screens and keyboards that you can use to type commands for + FreeBSD to run. The programs that you launch on one virtual console + do not stop running when that console is not visible. They continue + running when you have switched to a different virtual console.</para> + </sect2> + + <sect2 id="consoles-ttys"> + <title>The <filename>/etc/ttys</filename> File</title> + + <para>The default configuration of FreeBSD will start up with eight + virtual consoles. This is not a hardwired setting though, and + you can easily customize your installation to boot with more + or fewer virtual consoles. The number and settings of the + virtual consoles are configured in the + <filename>/etc/ttys</filename> file.</para> + + <para>You can use the <filename>/etc/ttys</filename> file to configure + the virtual consoles of FreeBSD. Each uncommented line in this file + (lines that do not start with a <literal>#</literal> character) contains + settings for a single terminal or virtual console. The default + version of this file that ships with FreeBSD configures nine virtual + consoles, and enables eight of them. They are the lines that start with + <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>For a detailed description of every column in this file and all + the options you can use to set things up for the virtual consoles, + consult the &man.ttys.5; manual page.</para> + </sect2> + + <sect2 id="consoles-singleuser"> + <title>Single User Mode Console</title> + + <para>A detailed description of what <quote>single user mode</quote> is + can be found in <xref linkend="boot-singleuser">. It is worth noting + that there is only one console when you are running FreeBSD in single + user mode. There are no virtual consoles available. The settings of + the single user mode console can also be found in the + <filename>/etc/ttys</filename> file. Look for the line that starts + with <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>As the comments above the <literal>console</literal> line + indicate, you can edit this line and change <literal>secure</literal> to + <literal>insecure</literal>. If you do that, when FreeBSD boots + into single user mode, it will still ask for the + <username>root</username> password.</para> + + <para><emphasis>Be careful when changing this to + <literal>insecure</literal></emphasis>. If you ever forget + the <username>root</username> password, booting into single user + mode is a bit involved. It is still possible, but it might be a bit + hard for someone who is not very comfortable with the FreeBSD + booting process and the programs involved.</para> + </note> + </sect2> + + <sect2 id="consoles-vidcontrol"> + <title>Changing Console Video Modes</title> + + <para>The FreeBSD console default video mode may be adjusted to + 1024x768, 1280x1024, or any other size supported by your + graphics chip and monitor. To use a different video mode, you + first must recompile your kernel and include two additional + options:</para> + + <programlisting>options VESA +options SC_PIXEL_MODE</programlisting> + + <para>Once the kernel has been recompiled with these two + options, you can then determine what video modes are supported + by your hardware by using the &man.vidcontrol.1; utility. To + get a list of supported video modes issue the following:</para> + + <screen>&prompt.root; <userinput>vidcontrol -i mode</userinput></screen> + + <para>The output of this command is a list of video modes that + are supported by your hardware. You can then choose to use a + new video mode by passing it to &man.vidcontrol.1; in a <username>root</username> console:</para> + + <screen>&prompt.root; <userinput>vidcontrol MODE_279</userinput></screen> + + <para>If the new video mode is acceptable, it can be permanently + set on boot by setting it in the <filename>/etc/rc.conf</filename> + file:</para> + + <programlisting>allscreens_flags="MODE_279"</programlisting> + </sect2> + </sect1> + + <sect1 id="permissions"> + <title>Permissions</title> + <indexterm><primary>UNIX</primary></indexterm> + + <para>FreeBSD, being a direct descendant of BSD &unix;, is based on + several key &unix; concepts. The first and + most pronounced is that FreeBSD is a multi-user operating system. + The system can handle several users all working simultaneously on + completely unrelated tasks. The system is responsible for properly + sharing and managing requests for hardware devices, peripherals, + memory, and CPU time fairly to each user.</para> + + <para>Because the system is capable of supporting multiple users, + everything the system manages has a set of permissions governing who + can read, write, and execute the resource. These permissions are + stored as three octets broken into three pieces, one for the owner of + the file, one for the group that the file belongs to, and one for + everyone else. This numerical representation works like + this:</para> + + <indexterm><primary>permissions</primary></indexterm> + <indexterm> + <primary>file permissions</primary> + </indexterm> + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>Value</entry> + <entry>Permission</entry> + <entry>Directory Listing</entry> + </row> + </thead> + + <tbody> + <row> + <entry>0</entry> + <entry>No read, no write, no execute</entry> + <entry><literal>---</literal></entry> + </row> + + <row> + <entry>1</entry> + <entry>No read, no write, execute</entry> + <entry><literal>--x</literal></entry> + </row> + + <row> + <entry>2</entry> + <entry>No read, write, no execute</entry> + <entry><literal>-w-</literal></entry> + </row> + + <row> + <entry>3</entry> + <entry>No read, write, execute</entry> + <entry><literal>-wx</literal></entry> + </row> + + <row> + <entry>4</entry> + <entry>Read, no write, no execute</entry> + <entry><literal>r--</literal></entry> + </row> + + <row> + <entry>5</entry> + <entry>Read, no write, execute</entry> + <entry><literal>r-x</literal></entry> + </row> + + <row> + <entry>6</entry> + <entry>Read, write, no execute</entry> + <entry><literal>rw-</literal></entry> + </row> + + <row> + <entry>7</entry> + <entry>Read, write, execute</entry> + <entry><literal>rwx</literal></entry> + </row> + </tbody> + </tgroup> + </informaltable> + <indexterm> + <primary><command>ls</command></primary> + </indexterm> + <indexterm><primary>directories</primary></indexterm> + + <para>You can use the <option>-l</option> command line + argument to &man.ls.1; to view a long directory listing that + includes a column with information about a file's permissions + for the owner, group, and everyone else. For example, a + <command>ls -l</command> in an arbitrary directory may show:</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>Here is how the first column of <command>ls -l</command> is + broken up:</para> + + <screen>-rw-r--r--</screen> + + <para>The first (leftmost) character + tells if this file is a regular file, a directory, a special + character device, a socket, or any other special + pseudo-file device. In this case, the <literal>-</literal> + indicates a regular file. The next three characters, + <literal>rw-</literal> in this example, give the permissions for the owner of the + file. The next three characters, <literal>r--</literal>, give the + permissions for the group that the file belongs to. The final three + characters, <literal>r--</literal>, give the permissions for the + rest of the world. A dash means that the permission is turned off. + In the case of this file, the permissions are set so the owner can + read and write to the file, the group can read the file, and the + rest of the world can only read the file. According to the table + above, the permissions for this file would be + <literal>644</literal>, where each digit represents the three parts + of the file's permission.</para> + + <para>This is all well and good, but how does the system control + permissions on devices? FreeBSD actually treats most hardware + devices as a file that programs can open, read, and write data to + just like any other file. These special device files are stored on + the <filename>/dev</filename> directory.</para> + + <para>Directories are also treated as files. They have read, write, + and execute permissions. The executable bit for a directory has a + slightly different meaning than that of files. When a directory is + marked executable, it means it can be traversed into, that is, it is + possible to <quote>cd</quote> (change directory) into it. This also means that + within the directory it is possible to access files whose names are + known (subject, of course, to the permissions on the files + themselves).</para> + + <para>In particular, in order to perform a directory listing, + read permission must be set on the directory, whilst to delete a file + that one knows the name of, it is necessary to have write + <emphasis>and</emphasis> execute permissions to the directory + containing the file.</para> + + <para>There are more permission bits, but they are primarily used in + special circumstances such as setuid binaries and sticky + directories. If you want more information on file permissions and + how to set them, be sure to look at the &man.chmod.1; manual + page.</para> + + <sect2> + <sect2info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>Symbolic Permissions</title> + <indexterm><primary>permissions</primary><secondary>symbolic</secondary></indexterm> + + <para>Symbolic permissions, sometimes referred to as symbolic expressions, + use characters in place of octal values to assign permissions to files + or directories. Symbolic expressions use the syntax of (who) (action) + (permissions), where the following values are available:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>Option</entry> + <entry>Letter</entry> + <entry>Represents</entry> + </row> + </thead> + + <tbody> + <row> + <entry>(who)</entry> + <entry>u</entry> + <entry>User</entry> + </row> + + <row> + <entry>(who)</entry> + <entry>g</entry> + <entry>Group owner</entry> + </row> + + <row> + <entry>(who)</entry> + <entry>o</entry> + <entry>Other</entry> + </row> + + <row> + <entry>(who)</entry> + <entry>a</entry> + <entry>All (<quote>world</quote>)</entry> + </row> + + <row> + <entry>(action)</entry> + <entry>+</entry> + <entry>Adding permissions</entry> + </row> + + <row> + <entry>(action)</entry> + <entry>-</entry> + <entry>Removing permissions</entry> + </row> + + <row> + <entry>(action)</entry> + <entry>=</entry> + <entry>Explicitly set permissions</entry> + </row> + + <row> + <entry>(permissions)</entry> + <entry>r</entry> + <entry>Read</entry> + </row> + + <row> + <entry>(permissions)</entry> + <entry>w</entry> + <entry>Write</entry> + </row> + + <row> + <entry>(permissions)</entry> + <entry>x</entry> + <entry>Execute</entry> + </row> + + <row> + <entry>(permissions)</entry> + <entry>t</entry> + <entry>Sticky bit</entry> + </row> + + <row> + <entry>(permissions)</entry> + <entry>s</entry> + <entry>Set UID or GID</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>These values are used with the &man.chmod.1; command + just like before, but with letters. For an example, you could use + the following command to block other users from accessing + <replaceable>FILE</replaceable>:</para> + + <screen>&prompt.user; <userinput>chmod go= FILE</userinput></screen> + + <para>A comma separated list can be provided when more than one set + of changes to a file must be made. For example the following command + will remove the group and <quote>world</quote> write permission + on <replaceable>FILE</replaceable>, then it adds the execute + permissions for everyone:</para> + + <screen>&prompt.user; <userinput>chmod go-w,a+x <replaceable>FILE</replaceable></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> + <sect2info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>&os; File Flags</title> + + <para>In addition to file permissions discussed previously, &os; + supports the use of <quote>file flags.</quote> These flags + add an additional level of security and control over files, but + not directories.</para> + + <para>These file flags add an additional level of control over + files, helping to ensure that in some cases not even the + <username>root</username> can remove or alter files.</para> + + <para>File flags are altered by using the &man.chflags.1; utility, + using a simple interface. For example, to enable the system + undeletable flag on the file <filename>file1</filename>, + issue the following command:</para> + + <screen>&prompt.root; <userinput>chflags sunlink <filename>file1</filename></userinput></screen> + + <para>And to disable the system undeletable flag, + issue the previous command with <quote>no</quote> in + front of the <option>sunlink</option>. Observe:</para> + + <screen>&prompt.root; <userinput>chflags nosunlink <filename>file1</filename></userinput></screen> + + <para>To view the flags of this file, use the &man.ls.1; command + with the <option>-lo</option> flags:</para> + + <screen>&prompt.root; <userinput>ls -lo <filename>file1</filename></userinput></screen> + + <para>The output should look like the following:</para> + + <programlisting>-rw-r--r-- 1 trhodes trhodes sunlnk 0 Mar 1 05:54 file1</programlisting> + + <para>Several flags may only added or removed to files by the + <username>root</username> user. In other cases, the file owner + may set these flags. It is recommended that administrators read + over the &man.chflags.1; and &man.chflags.2; manual pages for + more information.</para> + </sect2> + + <sect2> + <sect2info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>The setuid, setgid, and sticky Permissions</title> + + <para>Other than the permissions already discussed, there are + three other specific settings that all administrators should + know about. They are the <literal>setuid</literal>, + <literal>setgid</literal> and <literal>sticky</literal> + permissions.</para> + + <para>These settings are important for some &unix; operations + as they provide functionality not normally granted to normal + users. To understand them, the difference between the real + user ID and effective user ID must also be noted.</para> + + <para>The real user ID is the <acronym>UID</acronym> who owns + or starts the process. The effective <acronym>UID</acronym> + is the user ID the process runs as. As an example, the + &man.passwd.1; utility runs with the real user ID as the + user changing their password; however, to manipulate the + password database, it runs as the effective ID of the + <username>root</username> user. This is what allows normal + users to change their passwords without seeing a + <errorname>Permission Denied</errorname> error.</para> + + <note> + <para>The <literal>nosuid</literal> &man.mount.8; option will + cause these binaries to silently fail. That is, they will + fail to execute without ever alerting the user. That option + is also not completely reliable as a <literal>nosuid</literal> + wrapper may be able to circumvent it; according to the + &man.mount.8; manual page.</para> + </note> + + <para>The setuid permission may be set by prefixing a permission + set with the number four (4) as shown in the following + example:</para> + + <screen>&prompt.root; <userinput>chmod 4755 suidexample.sh</userinput></screen> + + <para>The permissions on the + <filename><replaceable>suidexample.sh</replaceable></filename> + file should now look like the following:</para> + + <programlisting>-rwsr-xr-x 1 trhodes trhodes 63 Aug 29 06:36 suidexample.sh</programlisting> + + <para>It should be noticeable from this example that an + <literal>s</literal> is now part of the permission set + designated for the file owner, replacing the executable + bit. This allows utilities which need elevated permissions, + such as <command>passwd</command>.</para> + + <para>To view this in real time, open two terminals. On + one, start the <command>passwd</command> process as a normal + user. While it waits for a new password, check the process + table and look at the user information of the + <command>passwd</command> command.</para> + + <para>In terminal A:</para> + + <screen>Changing local password for trhodes +Old Password:</screen> + + <para>In terminal B:</para> + + <screen>&prompt.root; <userinput>ps aux | grep passwd</userinput></screen> + + <screen>trhodes 5232 0.0 0.2 3420 1608 0 R+ 2:10AM 0:00.00 grep passwd +root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> + + <para>As stated above, the <command>passwd</command> is run + by a normal user, but is using the effective + <acronym>UID</acronym> of <username>root</username>.</para> + + <para>The <literal>setgid</literal> permission performs the + same function as the <literal>setuid</literal> permission; + except that it alters the group settings. When an application + or utility is ran with this setting, it will be granted the + permissions based on the group that owns the file, not + the user who started the process.</para> + + <para>To set the <literal>setgid</literal> permission on a + file, provide the <command>chmod</command> command with a + leading two (2) as in the following example:</para> + + <screen>&prompt.root; <userinput>chmod 2755 sgidexample.sh</userinput></screen> + + <para>The new setting may be viewed as before, notice the + <literal>s</literal> is now in the field designated for the + group permission settings:</para> + + <screen>-rwxr-sr-x 1 trhodes trhodes 44 Aug 31 01:49 sgidexample.sh</screen> + + <note> + <para>In these examples, even though the shell script in + question is an executable file, it will not run with + a different <acronym>EUID</acronym> or effective user ID. + This is because shell scripts may not access the + &man.setuid.2; system calls.</para> + </note> + + <para>The first two special permission bits we discussed + (the <literal>setuid</literal> and <literal>setgid</literal> + permission bits) may lower system security, by allowing for + elevated permissions. There is a third special permission bit + that can strengthen the security of a system: the + <literal>sticky bit</literal>.</para> + + <para>The <literal>sticky bit</literal>, when set on a directory, + allows file deletion only by the file owner. This + permission set is useful to prevent file deletion in public + directories, such as + <filename class="directory">/tmp</filename>, by users who do + not own the file. To utilize this permission, prefix the + permission with a one (1). For example:</para> + + <screen>&prompt.root; <userinput>chmod 1777 /tmp</userinput></screen> + + <para>Now, it is possible to see the effect by using the + <command>ls</command> command:</para> + + <screen>&prompt.root; <userinput>ls -al / | grep tmp</userinput></screen> + + <screen>drwxrwxrwt 10 root wheel 512 Aug 31 01:49 tmp</screen> + + <para>The <literal>sticky bit</literal> permission is + distinguishable from the <literal>t</literal> at the very + end of the set.</para> + </sect2> + </sect1> + + <sect1 id="dirstructure"> + <title>Directory Structure</title> + <indexterm><primary>directory hierarchy</primary></indexterm> + + <para>The FreeBSD directory hierarchy is fundamental to obtaining + an overall understanding of the system. The most important + concept to grasp is that of the root directory, + <quote>/</quote>. This directory is the first one mounted at + boot time and it contains the base system necessary to prepare + the operating system for multi-user operation. The root + directory also contains mount points for other file systems + that are mounted during the transition to multi-user + operation.</para> + + <para>A mount point is a directory where additional file systems can + be grafted onto a parent file system (usually the root file system). + This is further described in <xref linkend="disk-organization">. + Standard mount points include + <filename>/usr</filename>, <filename>/var</filename>, <filename>/tmp</filename>, + <filename>/mnt</filename>, and <filename>/cdrom</filename>. These + directories are usually referenced to entries in the file + <filename>/etc/fstab</filename>. <filename>/etc/fstab</filename> is + a table of various file systems and mount points for reference by the + system. Most of the file systems in <filename>/etc/fstab</filename> + are mounted automatically at boot time from the script &man.rc.8; + unless they contain the <option>noauto</option> option. + Details can be found in <xref linkend="disks-fstab">.</para> + + <para>A complete description of the file system hierarchy is + available in &man.hier.7;. For now, a brief overview of the + most common directories will suffice.</para> + + <para> + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Directory</entry> + <entry>Description</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><filename class="directory">/</filename></entry> + <entry>Root directory of the file system.</entry> + </row> + + <row> + <entry><filename class="directory">/bin/</filename></entry> + <entry>User utilities fundamental to both single-user + and multi-user environments.</entry> + </row> + + <row> + <entry><filename class="directory">/boot/</filename></entry> + <entry>Programs and configuration files used during + operating system bootstrap.</entry> + </row> + + <row> + <entry><filename class="directory">/boot/defaults/</filename></entry> + <entry>Default bootstrapping configuration files; see + &man.loader.conf.5;.</entry> + </row> + + <row> + <entry><filename class="directory">/dev/</filename></entry> + <entry>Device nodes; see &man.intro.4;.</entry> + </row> + + <row> + <entry><filename class="directory">/etc/</filename></entry> + <entry>System configuration files and scripts.</entry> + </row> + + <row> + <entry><filename class="directory">/etc/defaults/</filename></entry> + <entry>Default system configuration files; see &man.rc.8;.</entry> + </row> + + <row> + <entry><filename class="directory">/etc/mail/</filename></entry> + <entry>Configuration files for mail transport agents such + as &man.sendmail.8;.</entry> + </row> + + <row> + <entry><filename class="directory">/etc/namedb/</filename></entry> + <entry><command>named</command> configuration files; see + &man.named.8;.</entry> + </row> + + <row> + <entry><filename class="directory">/etc/periodic/</filename></entry> + <entry>Scripts that are run daily, weekly, and monthly, + via &man.cron.8;; see &man.periodic.8;.</entry> + </row> + + <row> + <entry><filename class="directory">/etc/ppp/</filename></entry> + <entry><command>ppp</command> configuration files; see + &man.ppp.8;.</entry> + </row> + + <row> + <entry><filename class="directory">/mnt/</filename></entry> + <entry>Empty directory commonly used by system administrators as a + temporary mount point.</entry> + </row> + + <row> + <entry><filename class="directory">/proc/</filename></entry> + <entry>Process file system; see &man.procfs.5;, + &man.mount.procfs.8;.</entry> + </row> + + <row> + <entry><filename class="directory">/rescue/</filename></entry> + <entry>Statically linked programs for emergency recovery; see + &man.rescue.8;.</entry> + </row> + + <row> + <entry><filename class="directory">/root/</filename></entry> + <entry>Home directory for the <username>root</username> + account.</entry> + </row> + + <row> + <entry><filename class="directory">/sbin/</filename></entry> + <entry>System programs and administration utilities fundamental to + both single-user and multi-user environments.</entry> + </row> + + + <row> + <entry><filename class="directory">/tmp/</filename></entry> + <entry>Temporary files. The contents of + <filename class="directory">/tmp</filename> are usually NOT + preserved across a system reboot. A memory-based file system + is often mounted at + <filename class="directory">/tmp</filename>. + This can be automated using the tmpmfs-related variables of + &man.rc.conf.5; (or with an entry in + <filename>/etc/fstab</filename>; see &man.mdmfs.8;).</entry> + </row> + + + <row> + <entry><filename class="directory">/usr/</filename></entry> + <entry>The majority of user utilities and applications.</entry> + </row> + + <row> + <entry><filename class="directory">/usr/bin/</filename></entry> + <entry>Common utilities, programming tools, and applications.</entry> + </row> + + <row> + <entry><filename class="directory">/usr/include/</filename></entry> + <entry>Standard C include files.</entry> + </row> + + <row> + <entry><filename class="directory">/usr/lib/</filename></entry> + <entry>Archive libraries.</entry> + </row> + + + <row> + <entry><filename class="directory">/usr/libdata/</filename></entry> + <entry>Miscellaneous utility data files.</entry> + </row> + + <row> + <entry><filename class="directory">/usr/libexec/</filename></entry> + <entry>System daemons & system utilities (executed by other + programs).</entry> + </row> + + <row> + <entry><filename + class="directory">/usr/local/</filename></entry> + + <entry>Local executables, libraries, etc. Also used as + the default destination for the FreeBSD ports + framework. Within <filename>/usr/local</filename>, + the general layout sketched out by &man.hier.7; for + <filename>/usr</filename> should be used. Exceptions + are the man directory, which is directly under + <filename>/usr/local</filename> rather than under + <filename>/usr/local/share</filename>, and the ports + documentation is in + <filename>share/doc/<replaceable>port</replaceable></filename>. + </entry> + </row> + + <row> + <entry><filename class="directory">/usr/obj/</filename></entry> + <entry>Architecture-specific target tree produced by building + the <filename>/usr/src</filename> tree.</entry> + </row> + + <row> + <entry><filename class="directory">/usr/ports/</filename></entry> + <entry>The FreeBSD Ports Collection (optional).</entry> + </row> + + <row> + <entry><filename class="directory">/usr/sbin/</filename></entry> + <entry>System daemons & system utilities (executed by users).</entry> + </row> + + <row> + <entry><filename class="directory">/usr/share/</filename></entry> + <entry>Architecture-independent files.</entry> + </row> + + <row> + <entry><filename class="directory">/usr/src/</filename></entry> + <entry>BSD and/or local source files.</entry> + </row> + + <row> + <entry><filename + class="directory">/usr/X11R6/</filename></entry> + <entry>X11R6 distribution executables, libraries, etc + (optional).</entry> + </row> + + <row> + <entry><filename class="directory">/var/</filename></entry> + <entry>Multi-purpose log, temporary, transient, and spool files. + A memory-based file system is sometimes mounted at + <filename class="directory">/var</filename>. + This can be automated using the varmfs-related variables of + &man.rc.conf.5 (or with an entry in + <filename>/etc/fstab</filename>; see &man.mdmfs.8;).</entry> + </row> + + + <row> + <entry><filename class="directory">/var/log/</filename></entry> + <entry>Miscellaneous system log files.</entry> + </row> + + <row> + <entry><filename class="directory">/var/mail/</filename></entry> + <entry>User mailbox files.</entry> + </row> + + <row> + <entry><filename class="directory">/var/spool/</filename></entry> + <entry>Miscellaneous printer and mail system spooling directories. + </entry> + </row> + + <row> + <entry><filename class="directory">/var/tmp/</filename></entry> + <entry>Temporary files. + The files are usually preserved across a system reboot, + unless <filename class="directory">/var</filename> + is a memory-based file system.</entry> + </row> + + <row> + <entry><filename class="directory">/var/yp/</filename></entry> + <entry>NIS maps.</entry> + </row> + + </tbody> + </tgroup> + </informaltable> + </para> + + </sect1> + + <sect1 id="disk-organization"> + <title>Disk Organization</title> + + <para>The smallest unit of organization that FreeBSD uses to find files + is the filename. Filenames are case-sensitive, which means that + <filename>readme.txt</filename> and <filename>README.TXT</filename> + are two separate files. FreeBSD does not use the extension + (<filename>.txt</filename>) of a file to determine whether the file is + a program, or a document, or some other form of data.</para> + + <para>Files are stored in directories. A directory may contain no + files, or it may contain many hundreds of files. A directory can also + contain other directories, allowing you to build up a hierarchy of + directories within one another. This makes it much easier to organize + your data.</para> + + <para>Files and directories are referenced by giving the file or + directory name, followed by a forward slash, <literal>/</literal>, + followed by any other directory names that are necessary. If you have + directory <filename>foo</filename>, which contains directory + <filename>bar</filename>, which contains the file + <filename>readme.txt</filename>, then the full name, or + <firstterm>path</firstterm> to the file is + <filename>foo/bar/readme.txt</filename>.</para> + + <para>Directories and files are stored in a file system. Each file system + contains exactly one directory at the very top level, called the + <firstterm>root directory</firstterm> for that file system. This root + directory can then contain other directories.</para> + + <para>So far this is probably similar to any other operating system you + may have used. There are a few differences; for example, &ms-dos; uses + <literal>\</literal> to separate file and directory names, while &macos; + uses <literal>:</literal>.</para> + + <para>FreeBSD does not use drive letters, or other drive names in the + path. You would not write <filename>c:/foo/bar/readme.txt</filename> + on FreeBSD.</para> + + <para>Instead, one file system is designated the <firstterm>root + file system</firstterm>. The root file system's root directory is + referred to as <literal>/</literal>. Every other file system is then + <firstterm>mounted</firstterm> under the root file system. No matter + how many disks you have on your FreeBSD system, every directory + appears to be part of the same disk.</para> + + <para>Suppose you have three file systems, called <literal>A</literal>, + <literal>B</literal>, and <literal>C</literal>. Each file system has + one root directory, which contains two other directories, called + <literal>A1</literal>, <literal>A2</literal> (and likewise + <literal>B1</literal>, <literal>B2</literal> and + <literal>C1</literal>, <literal>C2</literal>).</para> + + <para>Call <literal>A</literal> the root file system. If you used the + <command>ls</command> command to view the contents of this directory + you would see two subdirectories, <literal>A1</literal> and + <literal>A2</literal>. The directory tree looks like this:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/example-dir1" format="EPS"> + </imageobject> + + <textobject> + <literallayout class="monospaced"> / + | + +--- A1 + | + `--- A2</literallayout> + </textobject> + </mediaobject> + + <para>A file system must be mounted on to a directory in another + file system. So now suppose that you mount file system + <literal>B</literal> on to the directory <literal>A1</literal>. The + root directory of <literal>B</literal> replaces <literal>A1</literal>, + and the directories in <literal>B</literal> appear accordingly:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/example-dir2" format="EPS"> + </imageobject> + + <textobject> + <literallayout class="monospaced"> / + | + +--- A1 + | | + | +--- B1 + | | + | `--- B2 + | + `--- A2</literallayout> + </textobject> + </mediaobject> + + <para>Any files that are in the <literal>B1</literal> or + <literal>B2</literal> directories can be reached with the path + <filename>/A1/B1</filename> or <filename>/A1/B2</filename> as + necessary. Any files that were in <filename>/A1</filename> have been + temporarily hidden. They will reappear if <literal>B</literal> is + <firstterm>unmounted</firstterm> from A.</para> + + <para>If <literal>B</literal> had been mounted on <literal>A2</literal> + then the diagram would look like this:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/example-dir3" format="EPS"> + </imageobject> + + <textobject> + <literallayout class="monospaced"> / + | + +--- A1 + | + `--- A2 + | + +--- B1 + | + `--- B2</literallayout> + </textobject> + </mediaobject> + + <para>and the paths would be <filename>/A2/B1</filename> and + <filename>/A2/B2</filename> respectively.</para> + + <para>File systems can be mounted on top of one another. Continuing the + last example, the <literal>C</literal> file system could be mounted on + top of the <literal>B1</literal> directory in the <literal>B</literal> + file system, leading to this arrangement:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/example-dir4" format="EPS"> + </imageobject> + + <textobject> + <literallayout class="monospaced"> / + | + +--- A1 + | + `--- A2 + | + +--- B1 + | | + | +--- C1 + | | + | `--- C2 + | + `--- B2</literallayout> + </textobject> + </mediaobject> + + <para>Or <literal>C</literal> could be mounted directly on to the + <literal>A</literal> file system, under the <literal>A1</literal> + directory:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/example-dir5" format="EPS"> + </imageobject> + + <textobject> + <literallayout class="monospaced"> / + | + +--- A1 + | | + | +--- C1 + | | + | `--- C2 + | + `--- A2 + | + +--- B1 + | + `--- B2</literallayout> + </textobject> + </mediaobject> + + <para>If you are familiar with &ms-dos;, this is similar, although not + identical, to the <command>join</command> command.</para> + + <para>This is not normally something you need to concern yourself with. + Typically you create file systems when installing FreeBSD and decide + where to mount them, and then never change them unless you add a new + disk.</para> + + <para>It is entirely possible to have one large root file system, and not + need to create any others. There are some drawbacks to this approach, + and one advantage.</para> + + <itemizedlist> + <title>Benefits of Multiple File Systems</title> + + <listitem> + <para>Different file systems can have different <firstterm>mount + options</firstterm>. For example, with careful planning, the + root file system can be mounted read-only, making it impossible for + you to inadvertently delete or edit a critical file. Separating + user-writable file systems, such as <filename>/home</filename>, + from other file systems also allows them to be mounted + <firstterm>nosuid</firstterm>; this option prevents the + <firstterm>suid</firstterm>/<firstterm>guid</firstterm> bits on + executables stored on the file system from taking effect, possibly + improving security.</para> + </listitem> + + <listitem> + <para>FreeBSD automatically optimizes the layout of files on a + file system, depending on how the file system is being used. So a + file system that contains many small files that are written + frequently will have a different optimization to one that contains + fewer, larger files. By having one big file system this + optimization breaks down.</para> + </listitem> + + <listitem> + <para>FreeBSD's file systems are very robust should you lose power. + However, a power loss at a critical point could still damage the + structure of the file system. By splitting your data over multiple + file systems it is more likely that the system will still come up, + making it easier for you to restore from backup as necessary.</para> + </listitem> + </itemizedlist> + + <itemizedlist> + <title>Benefit of a Single File System</title> + + <listitem> + <para>File systems are a fixed size. If you create a file system when + you install FreeBSD and give it a specific size, you may later + discover that you need to make the partition bigger. This is not + easily accomplished without backing up, recreating the file system + with the new size, and then restoring the backed up data.</para> + + <important> + <para>FreeBSD features the &man.growfs.8; + command, which makes it possible to increase the size of + file system on the fly, removing this limitation.</para> + </important> + </listitem> + </itemizedlist> + + <para>File systems are contained in partitions. This does not have the + same meaning as the common usage of the term partition (for example, &ms-dos; + partition), because of &os;'s &unix; heritage. Each partition is + identified by a letter from <literal>a</literal> through to + <literal>h</literal>. Each partition can contain only one file system, + which means that file systems are often described by either their + typical mount point in the file system hierarchy, or the letter of the + partition they are contained in.</para> + + <para>FreeBSD also uses disk space for <firstterm>swap + space</firstterm>. Swap space provides FreeBSD with + <firstterm>virtual memory</firstterm>. This allows your computer to + behave as though it has much more memory than it actually does. When + FreeBSD runs out of memory it moves some of the data that is not + currently being used to the swap space, and moves it back in (moving + something else out) when it needs it.</para> + + <para>Some partitions have certain conventions associated with + them.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"> + <colspec colwidth="5*"> + + <thead> + <row> + <entry>Partition</entry> + + <entry>Convention</entry> + </row> + </thead> + + <tbody valign="top"> + <row> + <entry><literal>a</literal></entry> + + <entry>Normally contains the root file system</entry> + </row> + + <row> + <entry><literal>b</literal></entry> + + <entry>Normally contains swap space</entry> + </row> + + <row> + <entry><literal>c</literal></entry> + + <entry>Normally the same size as the enclosing slice. This + allows utilities that need to work on the entire slice (for + example, a bad block scanner) to work on the + <literal>c</literal> partition. You would not normally create + a file system on this partition.</entry> + </row> + + <row> + <entry><literal>d</literal></entry> + + <entry>Partition <literal>d</literal> used to have a special + meaning associated with it, although that is now gone and + <literal>d</literal> may work as any normal partition.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Each partition-that-contains-a-file-system is stored in what + FreeBSD calls a <firstterm>slice</firstterm>. Slice is FreeBSD's term + for what the common call partitions, and again, this is because of + FreeBSD's &unix; background. Slices are numbered, starting at 1, + through to 4.</para> + + <indexterm><primary>slices</primary></indexterm> + <indexterm><primary>partitions</primary></indexterm> + <indexterm><primary>dangerously dedicated</primary></indexterm> + + <para>Slice numbers follow + the device name, prefixed with an <literal>s</literal>, + starting at 1. So <quote>da0<emphasis>s1</emphasis></quote> + is the first slice on the first SCSI drive. There can only be + four physical slices on a disk, but you can have logical + slices inside physical slices of the appropriate type. These + extended slices are numbered starting at 5, so + <quote>ad0<emphasis>s5</emphasis></quote> is the first + extended slice on the first IDE disk. These devices are used by file + systems that expect to occupy a slice.</para> + + <para>Slices, <quote>dangerously dedicated</quote> physical + drives, and other drives contain + <firstterm>partitions</firstterm>, which are represented as + letters from <literal>a</literal> to <literal>h</literal>. + This letter is appended to the device name, so + <quote>da0<emphasis>a</emphasis></quote> is the a partition on + the first da drive, which is <quote>dangerously dedicated</quote>. + <quote>ad1s3<emphasis>e</emphasis></quote> is the fifth partition + in the third slice of the second IDE disk drive.</para> + + <para>Finally, each disk on the system is identified. A disk name + starts with a code that indicates the type of disk, and then a number, + indicating which disk it is. Unlike slices, disk numbering starts at + 0. Common codes that you will see are listed in + <xref linkend="basics-dev-codes">.</para> + + <para>When referring to a partition FreeBSD requires that you also name + the slice and disk that contains the partition, and when referring to + a slice you must also refer to the disk name. + Thus, you refer to a partition by listing + the disk name, <literal>s</literal>, the slice number, and then the + partition letter. Examples are shown in + <xref linkend="basics-disk-slice-part">.</para> + + <para><xref linkend="basics-concept-disk-model"> shows a conceptual + model of the disk layout that should help make things clearer.</para> + + <para>In order to install FreeBSD you must first configure the disk + slices, then create partitions within the slice you will use for + FreeBSD, and then create a file system (or swap space) in each + partition, and decide where that file system will be mounted.</para> + + <table frame="none" pgwide="1" id="basics-dev-codes"> + <title>Disk Device Codes</title> + + <tgroup cols="2"> + <colspec colwidth="1*"> + <colspec colwidth="5*"> + + <thead> + <row> + <entry>Code</entry> + + <entry>Meaning</entry> + </row> + </thead> + + <tbody> + <row> + <entry><devicename>ad</devicename></entry> + + <entry>ATAPI (IDE) disk</entry> + </row> + + <row> + <entry><devicename>da</devicename></entry> + + <entry>SCSI direct access disk</entry> + </row> + + <row> + <entry><devicename>acd</devicename></entry> + + <entry>ATAPI (IDE) CDROM</entry> + </row> + + <row> + <entry><devicename>cd</devicename></entry> + + <entry>SCSI CDROM</entry> + </row> + + <row> + <entry><devicename>fd</devicename></entry> + + <entry>Floppy disk</entry> + </row> + </tbody> + </tgroup> + </table> + + <example id="basics-disk-slice-part"> + <title>Sample Disk, Slice, and Partition Names</title> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"> + <colspec colwidth="5*"> + + <thead> + <row> + <entry>Name</entry> + + <entry>Meaning</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>ad0s1a</literal></entry> + + <entry>The first partition (<literal>a</literal>) on the first + slice (<literal>s1</literal>) on the first IDE disk + (<literal>ad0</literal>).</entry> + </row> + + <row> + <entry><literal>da1s2e</literal></entry> + + <entry>The fifth partition (<literal>e</literal>) on the + second slice (<literal>s2</literal>) on the second SCSI disk + (<literal>da1</literal>).</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + + <example id="basics-concept-disk-model"> + <title>Conceptual Model of a Disk</title> + + <para>This diagram shows FreeBSD's view of the first IDE disk attached + to the system. Assume that the disk is 4 GB in size, and contains + two 2 GB slices (&ms-dos; partitions). The first slice contains a &ms-dos; + disk, <devicename>C:</devicename>, and the second slice contains a + FreeBSD installation. This example FreeBSD installation has three + data partitions, and a swap partition.</para> + + <para>The three partitions will each hold a file system. Partition + <literal>a</literal> will be used for the root file system, + <literal>e</literal> for the <filename>/var</filename> directory + hierarchy, and <literal>f</literal> for the + <filename>/usr</filename> directory hierarchy.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="install/disk-layout" format="EPS"> + </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 id="mount-unmount"> + <title>Mounting and Unmounting File Systems</title> + + <para>The file system is best visualized as a tree, + rooted, as it were, at <filename>/</filename>. + <filename>/dev</filename>, <filename>/usr</filename>, and the + other directories in the root directory are branches, which may + have their own branches, such as + <filename>/usr/local</filename>, and so on.</para> + + <indexterm><primary>root file system</primary></indexterm> + <para>There are various reasons to house some of these + directories on separate file systems. <filename>/var</filename> + contains the directories <filename>log/</filename>, + <filename>spool/</filename>, + and various types of temporary files, and + as such, may get filled up. Filling up the root file system + is not a good idea, so splitting <filename>/var</filename> from + <filename>/</filename> is often favorable.</para> + + <para>Another common reason to contain certain directory trees on + other file systems is if they are to be housed on separate + physical disks, or are separate virtual disks, such as <link + linkend="network-nfs">Network File System</link> mounts, or CDROM + drives.</para> + + <sect2 id="disks-fstab"> + <title>The <filename>fstab</filename> File</title> + <indexterm> + <primary>file systems</primary> + <secondary>mounted with fstab</secondary> + </indexterm> + + <para>During the <link linkend="boot">boot process</link>, + file systems listed in <filename>/etc/fstab</filename> are + automatically mounted (unless they are listed with the + <option>noauto</option> option).</para> + + <para>The <filename>/etc/fstab</filename> file contains a list + of lines of the following format:</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>A device name (which should exist), as explained in + <xref linkend="disks-naming">.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>mount-point</literal></term> + + <listitem><para>A directory (which should exist), on which + to mount the file system.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>fstype</literal></term> + + <listitem><para>The file system type to pass to + &man.mount.8;. The default FreeBSD file system is + <literal>ufs</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>options</literal></term> + + <listitem><para>Either <option>rw</option> for read-write + file systems, or <option>ro</option> for read-only + file systems, followed by any other options that may be + needed. A common option is <option>noauto</option> for + file systems not normally mounted during the boot sequence. + Other options are listed in the &man.mount.8; manual page.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>dumpfreq</literal></term> + + <listitem><para>This is used by &man.dump.8; to determine which + file systems require dumping. If the field is missing, + a value of zero is assumed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>passno</literal></term> + + <listitem> + <para>This determines the order in which file systems should + be checked. File systems that should be skipped should have + their <literal>passno</literal> set to zero. The root + file system (which needs to be checked before everything + else) should have its <literal>passno</literal> set to + one, and other file systems' <literal>passno</literal> + should be set to values greater than one. If more than one + file systems have the same <literal>passno</literal> then + &man.fsck.8; will attempt to check file systems in parallel + if possible.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Consult the &man.fstab.5; manual page for more information + on the format of the <filename>/etc/fstab</filename> file and + the options it contains.</para> + </sect2> + + <sect2 id="disks-mount"> + <title>The <command>mount</command> Command</title> + <indexterm> + <primary>file systems</primary> + <secondary>mounting</secondary> + </indexterm> + + <para>The &man.mount.8; command is what is ultimately used to + mount file systems.</para> + + <para>In its most basic form, you use:</para> + + <informalexample> + <screen>&prompt.root; <userinput>mount <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></userinput></screen> + </informalexample> + + <para>There are plenty of options, as mentioned in the + &man.mount.8; manual page, but the most common are:</para> + + <variablelist> + <title>Mount Options</title> + + <varlistentry> + <term><option>-a</option></term> + + <listitem> + <para>Mount all the file systems listed in + <filename>/etc/fstab</filename>. Except those + marked as <quote>noauto</quote>, excluded by the + <option>-t</option> flag, or those that are already + mounted.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + + <listitem> + <para>Do everything except for the actual mount system call. + This option is useful in conjunction with the + <option>-v</option> flag to determine what + &man.mount.8; is actually trying to do.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-f</option></term> + + <listitem> + <para>Force the mount of an unclean file system + (dangerous), or forces the revocation of write access + when downgrading a file system's mount status from + read-write to read-only.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-r</option></term> + + <listitem> + <para>Mount the file system read-only. This is identical + to using the <option>ro</option> + argument to the + <option>-o</option> option.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-t</option> + <replaceable>fstype</replaceable></term> + + <listitem> + <para>Mount the given file system as the given file system + type, or mount only file systems of the given type, if + given the <option>-a</option> option.</para> + + <para><quote>ufs</quote> is the default file system + type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-u</option></term> + + <listitem> + <para>Update mount options on the file system.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-v</option></term> + + <listitem> + <para>Be verbose.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-w</option></term> + + <listitem> + <para>Mount the file system read-write.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The <option>-o</option> option takes a comma-separated list of + the options, including the following:</para> + + <variablelist> + <varlistentry> + <term>noexec</term> + + <listitem> + <para>Do not allow execution of binaries on this + file system. This is also a useful security option.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>nosuid</term> + + <listitem> + <para>Do not interpret setuid or setgid flags on the + file system. This is also a useful security option.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="disks-umount"> + <title>The <command>umount</command> Command</title> + <indexterm> + <primary>file systems</primary> + <secondary>unmounting</secondary> + </indexterm> + + <para>The &man.umount.8; command takes, as a parameter, one of a + mountpoint, a device name, or the <option>-a</option> or + <option>-A</option> option.</para> + + <para>All forms take <option>-f</option> to force unmounting, + and <option>-v</option> for verbosity. Be warned that + <option>-f</option> is not generally a good idea. Forcibly + unmounting file systems might crash the computer or damage data + on the file system.</para> + + <para><option>-a</option> and <option>-A</option> are used to + unmount all mounted file systems, possibly modified by the + file system types listed after <option>-t</option>. + <option>-A</option>, however, does not attempt to unmount the + root file system.</para> + </sect2> + </sect1> + + <sect1 id="basics-processes"> + <title>Processes</title> + + <para>FreeBSD is a multi-tasking operating system. This means that it + seems as though more than one program is running at once. Each program + running at any one time is called a <firstterm>process</firstterm>. + Every command you run will start at least one new process, and there are + a number of system processes that run all the time, keeping the system + functional.</para> + + <para>Each process is uniquely identified by a number called a + <firstterm>process ID</firstterm>, or <firstterm>PID</firstterm>, and, + like files, each process also has one owner and group. The owner and + group information is used to determine what files and devices the + process can open, using the file permissions discussed earlier. Most + processes also have a parent process. The parent process is the process + that started them. For example, if you are typing commands to the shell + then the shell is a process, and any commands you run are also + processes. Each process you run in this way will have your shell as its + parent process. The exception to this is a special process called + &man.init.8;. <command>init</command> is always the first + process, so its PID is always 1. <command>init</command> is started + automatically by the kernel when FreeBSD starts.</para> + + <para>Two commands are particularly useful to see the processes on the + system, &man.ps.1; and &man.top.1;. The <command>ps</command> command is used to + show a static list of the currently running processes, and can show + their PID, how much memory they are using, the command line they were + started with, and so on. The <command>top</command> command displays all the + running processes, and updates the display every few seconds, so that + you can interactively see what your computer is doing.</para> + + <para>By default, <command>ps</command> only shows you the commands that are running + and are owned by you. For example:</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>As you can see in this example, the output from &man.ps.1; is + organized into a number of columns. <literal>PID</literal> is the + process ID discussed earlier. PIDs are assigned starting from 1, go up + to 99999, and wrap around back to the beginning when you run out + (a PID is not reassigned if it is already in use). + The <literal>TT</literal> column shows the tty the program is running on, and can + safely be ignored for the moment. <literal>STAT</literal> shows the + program's state, and again, can be safely ignored. + <literal>TIME</literal> is the amount of time the program has been + running on the CPU—this is usually not the elapsed time since + you started the program, as most programs spend a lot of time waiting + for things to happen before they need to spend time on the CPU. + Finally, <literal>COMMAND</literal> is the command line that was used to + run the program.</para> + + <para>&man.ps.1; supports a number of different options to change the + information that is displayed. One of the most useful sets is + <literal>auxww</literal>. <option>a</option> displays information + about all the running processes, not just your own. <option>u</option> + displays the username of the process' owner, as well as memory usage. + <option>x</option> displays information about daemon processes, and + <option>ww</option> causes &man.ps.1; to display the full command line + for each process, + rather than truncating it once it gets too long to fit on the + screen.</para> + + <para>The output from &man.top.1; is similar. A sample session looks like + this:</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>The output is split into two sections. The header (the first five + lines) shows the PID of the last process to run, the system load averages + (which are a measure of how busy the system is), the system uptime (time + since the last reboot) and the current time. The other figures in the + header relate to how many processes are running (47 in this case), how + much memory and swap space has been taken up, and how much time the + system is spending in different CPU states.</para> + + <para>Below that are a series of columns containing similar information + to the output from &man.ps.1;. As before you can see the PID, the + username, the amount of CPU time taken, and the command that was run. + &man.top.1; also defaults to showing you the amount of memory space + taken by the process. This is split into two columns, one for total + size, and one for resident size—total size is how much memory the + application has needed, and the resident size is how much it is actually + using at the moment. In this example you can see that <application>&netscape;</application> has + required almost 30 MB of RAM, but is currently only using 9 MB.</para> + + <para>&man.top.1; automatically updates this display every two seconds; + this can be changed with the <option>s</option> option.</para> + </sect1> + + <sect1 id="basics-daemons"> + <title>Daemons, Signals, and Killing Processes</title> + + <para>When you run an editor it is easy to control the editor, tell it to + load files, and so on. You can do this because the editor provides + facilities to do so, and because the editor is attached to a + <firstterm>terminal</firstterm>. Some programs are not designed to be + run with continuous user input, and so they disconnect from the terminal + at the first opportunity. For example, a web server spends all day + responding to web requests, it normally does not need any input from + you. Programs that transport email from site to site are another + example of this class of application.</para> + + <para>We call these programs <firstterm>daemons</firstterm>. Daemons were + characters in Greek mythology: neither good or evil, they were little + attendant spirits that, by and large, did useful things for mankind, + much like the web servers and mail servers of today do useful things. + This is why the BSD mascot has, for a long time, been the + cheerful-looking daemon with sneakers and a pitchfork.</para> + + <para>There is a convention to name programs that normally run as daemons + with a trailing <quote>d</quote>. <application>BIND</application> is the + Berkeley Internet Name Domain, but the actual program that executes is called + <command>named</command>; the <application>Apache</application> web + server program is called <command>httpd</command>; the line printer + spooling daemon is <command>lpd</command> and so on. This is a + convention, not a hard and fast rule; for example, the main mail daemon + for the <application>Sendmail</application> application is called + <command>sendmail</command>, and not <command>maild</command>, as you + might imagine.</para> + + <para>Sometimes you will need to communicate with a daemon process. + One way to do so is to send it (or any other running process), + what is known as a <firstterm>signal</firstterm>. + There are a number of different signals that you can + send—some of them have a specific meaning, others are interpreted + by the application, and the application's documentation will tell you + how that application interprets signals. You can only send a signal to + a process that you own. If you send a signal to someone else's + process with &man.kill.1; or &man.kill.2;, permission will be denied. + The exception to this is the + <username>root</username> user, who can send signals to everyone's + processes.</para> + + <para>FreeBSD will also send applications signals in some cases. If an + application is badly written, and tries to access memory that it is not + supposed to, FreeBSD sends the process the <firstterm>Segmentation + Violation</firstterm> signal (<literal>SIGSEGV</literal>). If an + application has used the &man.alarm.3; system call to be alerted after a + period of time has elapsed then it will be sent the Alarm signal + (<literal>SIGALRM</literal>), and so on.</para> + + <para>Two signals can be used to stop a process, + <literal>SIGTERM</literal> and <literal>SIGKILL</literal>. + <literal>SIGTERM</literal> is the polite way to kill a process; the + process can <emphasis>catch</emphasis> the signal, realize that you want + it to shut down, close any log files it may have open, and generally + finish whatever it is doing at the time before shutting down. In some + cases a process may even ignore <literal>SIGTERM</literal> if it is in + the middle of some task that can not be interrupted.</para> + + <para><literal>SIGKILL</literal> can not be ignored by a process. This is + the <quote>I do not care what you are doing, stop right now</quote> + signal. If you send <literal>SIGKILL</literal> to a process then + FreeBSD will stop that process there and then<footnote> + <para>Not quite true—there are a few things that can not be + interrupted. For example, if the process is trying to read from a + file that is on another computer on the network, and the other + computer has gone away for some reason (been turned off, or the + network has a fault), then the process is said to be + <quote>uninterruptible</quote>. Eventually the process will time + out, typically after two minutes. As soon as this time out occurs + the process will be killed.</para> + </footnote>.</para> + + <para>The other signals you might want to use are + <literal>SIGHUP</literal>, <literal>SIGUSR1</literal>, and + <literal>SIGUSR2</literal>. These are general purpose signals, and + different applications will do different things when they are + sent.</para> + + <para>Suppose that you have changed your web server's configuration + file—you would like to tell the web server to re-read its + configuration. You could stop and restart <command>httpd</command>, but + this would result in a brief outage period on your web server, which may + be undesirable. Most daemons are written to respond to the + <literal>SIGHUP</literal> signal by re-reading their configuration + file. So instead of killing and restarting <command>httpd</command> you + would send it the <literal>SIGHUP</literal> signal. Because there is no + standard way to respond to these signals, different daemons will have + different behavior, so be sure and read the documentation for the + daemon in question.</para> + + <para>Signals are sent using the &man.kill.1; command, as this example + shows.</para> + + <procedure> + <title>Sending a Signal to a Process</title> + + <para>This example shows how to send a signal to &man.inetd.8;. The + <command>inetd</command> configuration file is + <filename>/etc/inetd.conf</filename>, and <command>inetd</command> will re-read + this configuration file when it is sent + <literal>SIGHUP</literal>.</para> + + <step> + <para>Find the process ID of the process you want to send the signal + to. Do this using &man.ps.1; and &man.grep.1;. The &man.grep.1; + command is used to search through output, looking for the string you + specify. This command is run as a normal user, and &man.inetd.8; is + run as <username>root</username>, so the <option>ax</option> options + must be given to &man.ps.1;.</para> + + <screen>&prompt.user; <userinput>ps -ax | grep inetd</userinput> + 198 ?? IWs 0:00.00 inetd -wW</screen> + + <para>So the &man.inetd.8; PID is 198. In some cases the + <literal>grep inetd</literal> command might also appear in this + output. This is because of the way &man.ps.1; has to find the list + of running processes.</para> + </step> + + <step> + <para>Use &man.kill.1; to send the signal. Because &man.inetd.8; is + being run by <username>root</username> you must use &man.su.1; to + become <username>root</username> first.</para> + + <screen>&prompt.user; <userinput>su</userinput> +<prompt>Password:</prompt> +&prompt.root; <userinput>/bin/kill -s HUP 198</userinput></screen> + + <para>In common with most &unix; commands, &man.kill.1; will not print any + output if it is successful. If you send a signal to a + process that you do not own then you will see <errorname>kill: + <replaceable>PID</replaceable>: Operation not + permitted</errorname>. If you mistype the PID you will either + send the signal to the wrong process, which could be bad, or, if + you are lucky, you will have sent the signal to a PID that is not + currently in use, and you will see <errorname>kill: + <replaceable>PID</replaceable>: No such process</errorname>.</para> + + <note> + <title>Why Use <command>/bin/kill</command>?</title> + + <para>Many shells provide the <command>kill</command> command as a + built in command; that is, the shell will send the signal + directly, rather than running <filename>/bin/kill</filename>. + This can be very useful, but different shells have a different + syntax for specifying the name of the signal to send. Rather than + try to learn all of them, it can be simpler just to use the + <command>/bin/kill <replaceable>...</replaceable></command> + command directly.</para> + </note> + </step> + </procedure> + + <para>Sending other signals is very similar, just substitute + <literal>TERM</literal> or <literal>KILL</literal> in the command line + as necessary.</para> + + <important> + <para>Killing random process on the system can be a bad idea. In + particular, &man.init.8;, process ID 1, is very special. Running + <command>/bin/kill -s KILL 1</command> is a quick way to shutdown your + system. <emphasis>Always</emphasis> double check the arguments you + run &man.kill.1; with <emphasis>before</emphasis> you press + <keycap>Return</keycap>.</para> + </important> + </sect1> + + <sect1 id="shells"> + <title>Shells</title> + <indexterm><primary>shells</primary></indexterm> + <indexterm><primary>command line</primary></indexterm> + + <para>In FreeBSD, a lot of everyday work is done in a command line + interface called a shell. A shell's main job is to take commands + from the input channel and execute them. A lot of shells also have + built in functions to help with everyday tasks such as file management, + file globbing, command line editing, command macros, and environment + variables. FreeBSD comes with a set of shells, such as + <command>sh</command>, the Bourne Shell, and <command>tcsh</command>, + the improved C-shell. Many other shells are available + from the FreeBSD Ports Collection, such as + <command>zsh</command> and <command>bash</command>.</para> + + <para>Which shell do you use? It is really a matter of taste. If you + are a C programmer you might feel more comfortable with a C-like shell + such as <command>tcsh</command>. If you have come from Linux or are new + to a &unix; command line interface you might try <command>bash</command>. + The point is that each + shell has unique properties that may or may not work with your + preferred working environment, and that you have a choice of what + shell to use.</para> + + <para>One common feature in a shell is filename completion. Given + the typing of the first few letters of a command or filename, you + can usually have the shell automatically complete the rest of the + command or filename by hitting the <keycap>Tab</keycap> key on the keyboard. Here is + an example. Suppose you have two files called + <filename>foobar</filename> and <filename>foo.bar</filename>. You + want to delete <filename>foo.bar</filename>. So what you would type + on the keyboard is: <command>rm fo[<keycap>Tab</keycap>].[<keycap>Tab</keycap>]</command>.</para> + + <para>The shell would print out <command>rm + foo[BEEP].bar</command>.</para> + + <para>The [BEEP] is the console bell, which is the shell telling me it + was unable to totally complete the filename because there is more + than one match. Both <filename>foobar</filename> and + <filename>foo.bar</filename> start with <literal>fo</literal>, but + it was able to complete to <literal>foo</literal>. If you type in + <literal>.</literal>, then hit <keycap>Tab</keycap> again, the shell would be able to + fill in the rest of the filename for you.</para> + <indexterm><primary>environment variables</primary></indexterm> + + <para>Another feature of the shell is the use of environment variables. + Environment variables are a variable/key pair stored in the shell's + environment space. This space can be read by any program invoked by + the shell, and thus contains a lot of program configuration. Here + is a list of common environment variables and what they mean:</para> + <indexterm><primary>environment variables</primary></indexterm> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Variable</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><envar>USER</envar></entry> + <entry>Current logged in user's name.</entry> + </row> + + <row> + <entry><envar>PATH</envar></entry> + <entry>Colon-separated list of directories to search for + binaries.</entry> + </row> + + <row> + <entry><envar>DISPLAY</envar></entry> + <entry>Network name of the X11 display to connect to, if + available.</entry> + </row> + + <row> + <entry><envar>SHELL</envar></entry> + <entry>The current shell.</entry> + </row> + + <row> + <entry><envar>TERM</envar></entry> + <entry>The name of the user's type of terminal. Used to determine the + capabilities of the terminal.</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>Type of operating system. e.g., FreeBSD.</entry> + </row> + + <row> + <entry><envar>MACHTYPE</envar></entry> + <entry>The CPU architecture that the system is running + on.</entry> + </row> + + <row> + <entry><envar>EDITOR</envar></entry> + <entry>The user's preferred text editor.</entry> + </row> + + <row> + <entry><envar>PAGER</envar></entry> + <entry>The user's preferred text pager.</entry> + </row> + + <row> + <entry><envar>MANPATH</envar></entry> + <entry>Colon-separated list of directories to search for + manual pages.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <indexterm><primary>Bourne shells</primary></indexterm> + <para>Setting an environment variable differs somewhat from + shell to shell. For example, in the C-Style shells such as + <command>tcsh</command> and <command>csh</command>, you would use + <command>setenv</command> to set environment variables. + Under Bourne shells such as <command>sh</command> and + <command>bash</command>, you would use + <command>export</command> to set your current environment + variables. For example, to set or modify the + <envar>EDITOR</envar> environment variable, under <command>csh</command> or + <command>tcsh</command> a + command like this would set <envar>EDITOR</envar> to + <filename>/usr/local/bin/emacs</filename>:</para> + + <screen>&prompt.user; <userinput>setenv EDITOR /usr/local/bin/emacs</userinput></screen> + + <para>Under Bourne shells:</para> + + <screen>&prompt.user; <userinput>export EDITOR="/usr/local/bin/emacs"</userinput></screen> + + <para>You can also make most shells expand the environment variable by + placing a <literal>$</literal> character in front of it on the + command line. For example, <command>echo $TERM</command> would + print out whatever <envar>$TERM</envar> is set to, because the shell + expands <envar>$TERM</envar> and passes it on to <command>echo</command>.</para> + + <para>Shells treat a lot of special characters, called meta-characters + as special representations of data. The most common one is the + <literal>*</literal> character, which represents any number of + characters in a filename. These special meta-characters can be used + to do filename globbing. For example, typing in + <command>echo *</command> is almost the same as typing in + <command>ls</command> because the shell takes all the files that + match <literal>*</literal> and puts them on the command line for + <command>echo</command> to see.</para> + + <para>To prevent the shell from interpreting these special characters, + they can be escaped from the shell by putting a backslash + (<literal>\</literal>) character in front of them. <command>echo + $TERM</command> prints whatever your terminal is set to. + <command>echo \$TERM</command> prints <envar>$TERM</envar> as + is.</para> + + <sect2 id="changing-shells"> + <title>Changing Your Shell</title> + + <para>The easiest way to change your shell is to use the + <command>chsh</command> command. Running <command>chsh</command> will + place you into the editor that is in your <envar>EDITOR</envar> + environment variable; if it is not set, you will be placed in + <command>vi</command>. Change the <quote>Shell:</quote> line + accordingly.</para> + + <para>You can also give <command>chsh</command> the + <option>-s</option> option; this will set your shell for you, + without requiring you to enter an editor. + For example, if you wanted to + change your shell to <command>bash</command>, the following should do the + trick:</para> + + <screen>&prompt.user; <userinput>chsh -s /usr/local/bin/bash</userinput></screen> + + <note> + <para>The shell that you wish to use <emphasis>must</emphasis> be + present in the <filename>/etc/shells</filename> file. If you + have installed a shell from the <link linkend="ports">ports + collection</link>, then this should have been done for you + already. If you installed the shell by hand, you must do + this.</para> + + <para>For example, if you installed <command>bash</command> by hand + and placed it into <filename>/usr/local/bin</filename>, you would + want to:</para> + + <screen>&prompt.root; <userinput>echo "/usr/local/bin/bash" >> /etc/shells</userinput></screen> + + <para>Then rerun <command>chsh</command>.</para> + </note> + </sect2> + </sect1> + + <sect1 id="editors"> + <title>Text Editors</title> + <indexterm><primary>text editors</primary></indexterm> + <indexterm><primary>editors</primary></indexterm> + + <para>A lot of configuration in FreeBSD is done by editing text files. + Because of this, it would be a good idea to become familiar + with a text editor. FreeBSD comes with a few as part of the base + system, and many more are available in the Ports Collection.</para> + + <indexterm> + <primary><command>ee</command></primary> + </indexterm> + <indexterm> + <primary>editors</primary> + <secondary><command>ee</command></secondary> + </indexterm> + <para>The easiest and simplest editor to learn is an editor called + <application>ee</application>, which stands for easy editor. To + start <application>ee</application>, one would type at the command + line <command>ee <replaceable>filename</replaceable></command> where + <replaceable>filename</replaceable> is the name of the file to be edited. + For example, to edit <filename>/etc/rc.conf</filename>, type in + <command>ee /etc/rc.conf</command>. Once inside of + <command>ee</command>, all of the + commands for manipulating the editor's functions are listed at the + top of the display. The caret <literal>^</literal> character represents + the <keycap>Ctrl</keycap> key on the keyboard, so <literal>^e</literal> expands to the key combination + <keycombo action="simul"><keycap>Ctrl</keycap><keycap>e</keycap></keycombo>. To leave + <application>ee</application>, hit the <keycap>Esc</keycap> key, then choose leave + editor. The editor will prompt you to save any changes if the file + has been modified.</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 also comes with more powerful text editors such as + <application>vi</application> as part of the base system, while other editors, like + <application>Emacs</application> and <application>vim</application>, + are part of the FreeBSD Ports Collection (<filename role="package">editors/emacs</filename> and <filename role="package">editors/vim</filename>). These editors offer much + more functionality and power at the expense of being a little more + complicated to learn. However if you plan on doing a lot of text + editing, learning a more powerful editor such as + <application>vim</application> or <application>Emacs</application> + will save you much more time in the long run.</para> + + <para>Many applications which modify files or require typed input + will automatically open a text editor. To alter the default + editor used, set the <envar>EDITOR</envar> environment + variable. See <link linkend="shells">shells</link> + section for more details.</para> + </sect1> + + <sect1 id="basics-devices"> + <title>Devices and Device Nodes</title> + + <para>A device is a term used mostly for hardware-related + activities in a system, including disks, printers, graphics + cards, and keyboards. When FreeBSD boots, the majority + of what FreeBSD displays are devices being detected. + You can look through the boot messages again by viewing + <filename>/var/run/dmesg.boot</filename>.</para> + + <para>For example, <devicename>acd0</devicename> is the + first IDE CDROM drive, while <devicename>kbd0</devicename> + represents the keyboard.</para> + + <para>Most of these devices in a &unix; operating system must be + accessed through special files called device nodes, which are + located in the <filename>/dev</filename> directory.</para> + + <sect2> + <title>Creating Device Nodes</title> + <para>When adding a new device to your system, or compiling + in support for additional devices, new device nodes must + be created.</para> + + <sect3> + <title><literal>DEVFS</literal> (DEVice File System)</title> + + <para> The device file system, or <literal>DEVFS</literal>, provides access to + kernel's device namespace in the global file system namespace. + Instead of having to create and modify device nodes, + <literal>DEVFS</literal> maintains this particular file system for you.</para> + + <para>See the &man.devfs.5; manual page for more + information.</para> + </sect3> + </sect2> + </sect1> + + <sect1 id="binary-formats"> + <title>Binary Formats</title> + + <para>To understand why &os; uses the &man.elf.5; + format, you must first know a little about the three currently + <quote>dominant</quote> executable formats for &unix;:</para> + + <itemizedlist> + <listitem> + <para>&man.a.out.5;</para> + + <para>The oldest and <quote>classic</quote> &unix; object + format. 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 id="basics-more-information"> + <title>For More Information</title> + + <sect2 id="basics-man"> + <title>Manual Pages</title> + <indexterm><primary>manual pages</primary></indexterm> + + <para>The most comprehensive documentation on FreeBSD is in the form + of manual pages. Nearly every program on the system comes with a + short reference manual explaining the basic operation and various + arguments. These manuals can be viewed with the <command>man</command> command. Use + of the <command>man</command> command is simple:</para> + + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> + + <para><literal>command</literal> is the name of the command you + wish to learn about. For example, to learn more about + <command>ls</command> command type:</para> + + <screen>&prompt.user; <userinput>man ls</userinput></screen> + + <para>The online manual is divided up into numbered sections:</para> + + <orderedlist> + <listitem> + <para>User commands.</para> + </listitem> + + <listitem> + <para>System calls and error numbers.</para> + </listitem> + + <listitem> + <para>Functions in the C libraries.</para> + </listitem> + + <listitem> + <para>Device drivers.</para> + </listitem> + + <listitem> + <para>File formats.</para> + </listitem> + + <listitem> + <para>Games and other diversions.</para> + </listitem> + + <listitem> + <para>Miscellaneous information.</para> + </listitem> + + <listitem> + <para>System maintenance and operation commands.</para> + </listitem> + + <listitem> + <para>Kernel developers.</para> + </listitem> + </orderedlist> + + <para>In some cases, the same topic may appear in more than one + section of the online manual. For example, there is a + <command>chmod</command> user command and a + <function>chmod()</function> system call. In this case, you can + tell the <command>man</command> command which one you want by specifying the + section:</para> + + <screen>&prompt.user; <userinput>man 1 chmod</userinput></screen> + + <para>This will display the manual page for the user command + <command>chmod</command>. References to a particular section of + the online manual are traditionally placed in parenthesis in + written documentation, so &man.chmod.1; refers to the + <command>chmod</command> user command and &man.chmod.2; refers to + the system call.</para> + + <para>This is fine if you know the name of the command and just + wish to know how to use it, but what if you cannot recall the + command name? You can use <command>man</command> to search for keywords in the + command descriptions by using the <option>-k</option> + switch:</para> + + <screen>&prompt.user; <userinput>man -k mail</userinput></screen> + + <para>With this command you will be presented with a list of + commands that have the keyword <quote>mail</quote> in their + descriptions. This is actually functionally equivalent to using + the <command>apropos</command> command.</para> + + <para>So, you are looking at all those fancy commands in + <filename>/usr/bin</filename> but do not have the faintest idea + what most of them actually do? Type:</para> + + <screen>&prompt.user; <userinput>cd /usr/bin</userinput> +&prompt.user; <userinput>man -f *</userinput></screen> + + <para>or</para> + + <screen>&prompt.user; <userinput>cd /usr/bin</userinput> +&prompt.user; <userinput>whatis *</userinput></screen> + + <para>which does the same thing.</para> + </sect2> + + <sect2 id="basics-info"> + <title>GNU Info Files</title> + <indexterm><primary>Free Software Foundation</primary></indexterm> + + <para>FreeBSD includes many applications and utilities produced by + the Free Software Foundation (FSF). In addition to manual pages, + these programs come with more extensive hypertext documents called + <literal>info</literal> files which can be viewed with the + <command>info</command> command or, if you installed + <application>emacs</application>, the info mode of + <application>emacs</application>.</para> + + <para>To use the &man.info.1; command, type:</para> + + <screen>&prompt.user; <userinput>info</userinput></screen> + + <para>For a brief introduction, type <literal>h</literal>. For a + quick command reference, type <literal>?</literal>.</para> + </sect2> + </sect1> +</chapter> +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/basics/disk-layout.kil b/en_US.ISO8859-1/books/handbook/basics/disk-layout.kil Binary files differnew file mode 100644 index 0000000000..85820c2878 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/basics/disk-layout.kil diff --git a/en_US.ISO8859-1/books/handbook/basics/example-dir1.dot b/en_US.ISO8859-1/books/handbook/basics/example-dir1.dot new file mode 100644 index 0000000000..f259e8377d --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/basics/example-dir1.dot @@ -0,0 +1,7 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/"; +} diff --git a/en_US.ISO8859-1/books/handbook/basics/example-dir2.dot b/en_US.ISO8859-1/books/handbook/basics/example-dir2.dot new file mode 100644 index 0000000000..b846c82399 --- /dev/null +++ b/en_US.ISO8859-1/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/en_US.ISO8859-1/books/handbook/basics/example-dir3.dot b/en_US.ISO8859-1/books/handbook/basics/example-dir3.dot new file mode 100644 index 0000000000..178a3a91bb --- /dev/null +++ b/en_US.ISO8859-1/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/en_US.ISO8859-1/books/handbook/basics/example-dir4.dot b/en_US.ISO8859-1/books/handbook/basics/example-dir4.dot new file mode 100644 index 0000000000..82d12b421a --- /dev/null +++ b/en_US.ISO8859-1/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/en_US.ISO8859-1/books/handbook/basics/example-dir5.dot b/en_US.ISO8859-1/books/handbook/basics/example-dir5.dot new file mode 100644 index 0000000000..f5aa6e01dc --- /dev/null +++ b/en_US.ISO8859-1/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/en_US.ISO8859-1/books/handbook/bibliography/Makefile b/en_US.ISO8859-1/books/handbook/bibliography/Makefile new file mode 100644 index 0000000000..f926466a22 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/bibliography/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= bibliography/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml b/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml new file mode 100644 index 0000000000..feda377e3c --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/bibliography/chapter.sgml @@ -0,0 +1,712 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<appendix id="bibliography"> + <title>Bibliography</title> + + <para>While the manual pages provide the definitive reference for + individual pieces of the FreeBSD operating system, they are + notorious for not illustrating how to put the pieces together to + make the whole operating system run smoothly. For this, there is + no substitute for a good book on &unix; system administration and + a good users' manual.</para> + + <sect1 id="bibliography-freebsd"> + <title>Books & Magazines Specific to FreeBSD</title> + + <para><emphasis>International books & + Magazines:</emphasis></para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://jdli.tw.FreeBSD.org/publication/book/freebsd2/index.htm">Using + FreeBSD</ulink> (in Traditional Chinese), published by + <ulink url="http://www.drmaster.com.tw/">Drmaster</ulink>, + 1997. ISBN 9-578-39435-7.</para> + </listitem> + + <listitem> + + <para>FreeBSD Unleashed (Simplified Chinese translation), + published by + <ulink url="http://www.hzbook.com/">China Machine + Press</ulink>. ISBN 7-111-10201-0.</para> + </listitem> + + <listitem> + <para>FreeBSD From Scratch First Edition (in Simplified + Chinese), published by China Machine Press. ISBN + 7-111-07482-3.</para> + </listitem> + + <listitem> + <para>FreeBSD From Scratch Second Edition (in Simplified + Chinese), published by China Machine Press. ISBN + 7-111-10286-X.</para> + </listitem> + + <listitem> + <para>FreeBSD Handbook Second Edition (Simplified Chinese + translation), published by <ulink + url="http://www.ptpress.com.cn/">Posts & Telecom + Press</ulink>. ISBN 7-115-10541-3.</para> + </listitem> + + <listitem> + <para>FreeBSD 3.x Internet (in Simplified Chinese), published + by <ulink url="http://www.tup.tsinghua.edu.cn/">Tsinghua + University Press</ulink>. ISBN 7-900625-66-6.</para> + </listitem> + + <listitem> + <para>FreeBSD & Windows (in Simplified Chinese), published + by <ulink url="http://www.tdpress.com/">China Railway + Publishing House</ulink>. ISBN 7-113-03845-X</para> + </listitem> + + <listitem> + <para>FreeBSD Internet Services HOWTO (in Simplified Chinese), + published by China Railway Publishing House. ISBN + 7-113-03423-3</para> + </listitem> + + <listitem> + <para>FreeBSD for PC 98'ers (in Japanese), published by SHUWA + System Co, LTD. ISBN 4-87966-468-5 C3055 P2900E.</para> + </listitem> + + <listitem> + <para>FreeBSD (in Japanese), published by CUTT. ISBN + 4-906391-22-2 C3055 P2400E.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.shoeisha.com/book/Detail.asp?bid=650">Complete + Introduction to FreeBSD</ulink> (in Japanese), published + by <ulink url="http://www.shoeisha.co.jp/">Shoeisha Co., + Ltd</ulink>. ISBN 4-88135-473-6 P3600E.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.ascii.co.jp/pb/book1/shinkan/detail/1322785.html">Personal + UNIX Starter Kit FreeBSD</ulink> (in Japanese), published + by <ulink url="http://www.ascii.co.jp/">ASCII</ulink>. ISBN + 4-7561-1733-3 P3000E.</para> + </listitem> + + <listitem> + <para>FreeBSD Handbook (Japanese translation), published by + <ulink url="http://www.ascii.co.jp/">ASCII</ulink>. ISBN + 4-7561-1580-2 P3800E.</para> + </listitem> + + <listitem> + <para>FreeBSD mit Methode (in German), published by + <ulink url="http://www.cul.de">Computer und Literatur + Verlag</ulink>/Vertrieb Hanser, 1998. ISBN + 3-932311-31-0.</para> + </listitem> + + <listitem> + <para><ulink url="http://www.cul.de/freebsd.html">FreeBSD 4 - + Installieren, Konfigurieren, Administrieren</ulink> + (in German), published by <ulink + url="http://www.cul.de">Computer und Literatur + Verlag</ulink>, 2001. ISBN 3-932311-88-4.</para> + </listitem> + + <listitem> + <para><ulink url="http://www.cul.de/freebsd.html">FreeBSD 5 - + Installieren, Konfigurieren, Administrieren</ulink> + (in German), published by <ulink + url="http://www.cul.de">Computer und Literatur + Verlag</ulink>, 2003. ISBN 3-936546-06-1.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.mitp.de/vmi/mitp/detail/pWert/1343/"> + FreeBSD de Luxe</ulink> (in German), published by + <ulink url="http://www.mitp.de">Verlag Modere + Industrie</ulink>, 2003. ISBN 3-8266-1343-0.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.pc.mycom.co.jp/FreeBSD/install-manual.html">FreeBSD + Install and Utilization Manual</ulink> (in Japanese), + published by + <ulink url="http://www.pc.mycom.co.jp/">Mainichi + Communications Inc.</ulink>, 1998. ISBN + 4-8399-0112-0.</para> + </listitem> + + <listitem> + <para>Onno W Purbo, Dodi Maryanto, Syahrial Hubbany, Widjil + Widodo <emphasis><ulink + url="http://maxwell.itb.ac.id/">Building Internet Server + with FreeBSD</ulink></emphasis> (in Indonesia Language), + published by <ulink url="http://www.elexmedia.co.id/">Elex + Media Komputindo</ulink>.</para> + </listitem> + + <listitem> + <para>Absolute BSD: The Ultimate Guide to FreeBSD (Traditional + Chinese translation), published by <ulink + url="http://www.grandtech.com.tw/">GrandTech + Press</ulink>, 2003. ISBN 986-7944-92-5.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.twbsd.org/cht/book/">The FreeBSD 6.0 + Book</ulink> (in Traditional Chinese), published by + Drmaster, 2006. ISBN 9-575-27878-X.</para> + </listitem> + </itemizedlist> + + <para><emphasis>English language books & + Magazines:</emphasis></para> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.absoluteFreeBSD.com/">Absolute + FreeBSD, 2nd Edition: The Complete Guide to + FreeBSD</ulink>, published by + <ulink url="http://www.nostarch.com/">No Starch + Press</ulink>, 2007. ISBN: 978-1-59327-151-0</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.freebsdmall.com/cgi-bin/fm/bsdcomp"> + The Complete FreeBSD</ulink>, published by + <ulink url="http://www.oreilly.com/">O'Reilly</ulink>, 2003. + ISBN: 0596005164</para> + </listitem> + + <listitem> + <para><ulink url="http://www.freebsd-corp-net-guide.com/">The + FreeBSD Corporate Networker's Guide</ulink>, published by + <ulink url="http://www.awl.com/aw/">Addison-Wesley</ulink>, + 2000. ISBN: 0201704811</para> + </listitem> + + <listitem> + <para><ulink + url="http://andrsn.stanford.edu/FreeBSD/introbook/"> + FreeBSD: An Open-Source Operating System for Your Personal + Computer</ulink>, published by The Bit Tree Press, 2001. + ISBN: 0971204500</para> + </listitem> + + <listitem> + <para>Teach Yourself FreeBSD in 24 Hours, published by + <ulink url="http://www.samspublishing.com/">Sams</ulink>, + 2002. ISBN: 0672324245</para> + </listitem> + + <listitem> + <para>FreeBSD 6 Unleashed, published by + <ulink url="http://www.samspublishing.com/">Sams</ulink>, + 2006. ISBN: 0672328755</para> + </listitem> + + <listitem> + <para>FreeBSD: The Complete Reference, published by <ulink + url="http://books.mcgraw-hill.com">McGrawHill</ulink>, + 2003. ISBN: 0072224096 </para> + </listitem> + + <listitem> + <para><ulink url="http://www.bsdmag.org">BSD Magazine</ulink>, + published by Software Press Sp. z o.o. SK. + ISSN 1898-9144</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="bibliography-userguides"> + <title>Users' Guides</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>Ohio State University has written a <ulink + url="http://www.cs.duke.edu/csl/docs/unix_course/">UNIX + Introductory Course</ulink> which is available online in + HTML and PostScript format.</para> + + <para>An Italian <ulink + url="&url.doc.base;/it_IT.ISO8859-15/books/unix-introduction/index.html">translation</ulink> + of this document is available as part of the FreeBSD Italian + Documentation Project.</para> + </listitem> + + <listitem> + <para><ulink url="http://www.jp.FreeBSD.org/">Jpman Project, + Japan FreeBSD Users Group</ulink>. <ulink + url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD + User's Reference Manual</ulink> (Japanese translation). + <ulink url="http://www.pc.mycom.co.jp/">Mainichi + Communications Inc.</ulink>, 1998. ISBN4-8399-0088-4 + P3800E.</para> + </listitem> + + <listitem> + <para><ulink url="http://www.ed.ac.uk/">Edinburgh + University</ulink> has written an <ulink + url="http://unixhelp.ed.ac.uk/">Online Guide</ulink> for + newcomers to the UNIX environment.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="bibliography-adminguides"> + <title>Administrators' Guides</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><ulink url="http://www.jp.FreeBSD.org/">Jpman Project, + Japan FreeBSD Users Group</ulink>. <ulink + url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD + System Administrator's Manual</ulink> (Japanese + translation). <ulink + url="http://www.pc.mycom.co.jp/">Mainichi Communications + Inc.</ulink>, 1998. ISBN4-8399-0109-0 P3300E.</para> + </listitem> + + <listitem> + <para>Dreyfus, Emmanuel. <ulink + url="http://www.eyrolles.com/Informatique/Livre/9782212114638/">Cahiers + de l'Admin: BSD</ulink> 2nd Ed. (in French), Eyrolles, + 2004. ISBN 2-212-11463-X</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="bibliography-programmers"> + <title>Programmers' Guides</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. <ulink + url="http://www.spinellis.gr/codereading/"><emphasis>Code + Reading: The Open Source Perspective</emphasis></ulink>. + Addison-Wesley, 2003. ISBN 0-201-79940-5</para> + </listitem> + + <listitem> + <para>Spinellis, Diomidis. <ulink + url="http://www.spinellis.gr/codequality/"><emphasis>Code + Quality: The Open Source Perspective</emphasis></ulink>. + 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 id="bibliography-osinternals"> + <title>Operating System Internals</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>(Chapter 2 of this book is available <ulink + url="&url.books.design-44bsd;/book.html">online</ulink> as + part of the FreeBSD Documentation Project.)</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 id="bibliography-security"> + <title>Security Reference</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 id="bibliography-hardware"> + <title>Hardware Reference</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 publishes documentation on their CPUs, + chipsets and standards on their <ulink + url="http://developer.intel.com/">developer web + site</ulink>, usually as PDF files.</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 id="bibliography-history"> + <title>&unix; History</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 <ulink + url="http://www.catb.org/~esr/jargon/html/index.html">Jargon + File</ulink></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 <ulink + url="http://www.simson.net/ref/ugh.pdf">online</ulink>.</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>The BSD family tree</emphasis>. + <ulink + url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/share/misc/bsd-family-tree"></ulink> + or + <ulink type="html" + url="file://localhost/usr/share/misc/bsd-family-tree"><filename>/usr/share/misc/bsd-family-tree</filename></ulink> + on a FreeBSD machine.</para> + </listitem> + + <listitem> + <para><emphasis>Networked Computer Science Technical Reports + Library</emphasis>. + <ulink url="http://www.ncstrl.org/"></ulink></para> + </listitem> + + <listitem> + <para><emphasis>Old BSD releases from the Computer Systems + Research group (CSRG)</emphasis>. + <ulink url="http://www.mckusick.com/csrg/"></ulink>: 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 id="bibliography-journals"> + <title>Magazines and Journals</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> (in German) Computer- und + Literaturverlag GmbH, ISSN 1436-7033</para> + </listitem> + </itemizedlist> + </sect1> +</appendix> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../appendix.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "appendix") + End: +--> + diff --git a/en_US.ISO8859-1/books/handbook/book.sgml b/en_US.ISO8859-1/books/handbook/book.sgml new file mode 100644 index 0000000000..0e0bf2e7d8 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/book.sgml @@ -0,0 +1,358 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ +<!ENTITY % books.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Books Entity Set//EN"> +%books.ent; +<!ENTITY % chapters SYSTEM "chapters.ent"> +%chapters; +<!ENTITY % txtfiles SYSTEM "txtfiles.ent"> +%txtfiles; + +<!ENTITY % not.published "INCLUDE"> + +<!ENTITY % chap.introduction "IGNORE"> +<!ENTITY % chap.install "IGNORE"> +<!ENTITY % chap.bsdinstall "IGNORE"> +<!ENTITY % chap.basics "IGNORE"> +<!ENTITY % chap.ports "IGNORE"> +<!ENTITY % chap.config "IGNORE"> +<!ENTITY % chap.boot "IGNORE"> +<!ENTITY % chap.users "IGNORE"> +<!ENTITY % chap.kernelconfig "IGNORE"> +<!ENTITY % chap.security "IGNORE"> +<!ENTITY % chap.jails "IGNORE"> +<!ENTITY % chap.printing "IGNORE"> +<!ENTITY % chap.disks "IGNORE"> +<!ENTITY % chap.geom "IGNORE"> +<!ENTITY % chap.vinum "IGNORE"> +<!ENTITY % chap.x11 "IGNORE"> +<!ENTITY % chap.l10n "IGNORE"> +<!ENTITY % chap.multimedia "IGNORE"> +<!ENTITY % chap.desktop "IGNORE"> +<!ENTITY % chap.serialcomms "IGNORE"> +<!ENTITY % chap.ppp-and-slip "IGNORE"> +<!ENTITY % chap.advanced-networking "IGNORE"> +<!ENTITY % chap.firewalls "IGNORE"> +<!ENTITY % chap.network-servers "IGNORE"> +<!ENTITY % chap.mail "IGNORE"> +<!ENTITY % chap.cutting-edge "IGNORE"> +<!ENTITY % chap.linuxemu "IGNORE"> +<!ENTITY % chap.mirrors "IGNORE"> +<!ENTITY % chap.bibliography "IGNORE"> +<!ENTITY % chap.eresources "IGNORE"> +<!ENTITY % chap.pgpkeys "IGNORE"> +<!ENTITY % chap.index "IGNORE"> +<!ENTITY % chap.freebsd-glossary "IGNORE"> +<!ENTITY % chap.mac "IGNORE"> +<!ENTITY % chap.audit "IGNORE"> +<!ENTITY % chap.filesystems "IGNORE"> +<!ENTITY % chap.dtrace "IGNORE"> + +<!ENTITY % pgpkeys SYSTEM "../../../share/pgpkeys/pgpkeys.ent"> %pgpkeys; +]> + +<book> + <bookinfo> + <title>FreeBSD Handbook</title> + + <corpauthor>The FreeBSD Documentation Project</corpauthor> + + <pubdate>February 1999</pubdate> + + <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> + <year>2009</year> + <year>2010</year> + <year>2011</year> + <year>2012</year> + <holder>The FreeBSD Documentation Project</holder> + </copyright> + + &bookinfo.legalnotice; + + <legalnotice 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>Welcome to FreeBSD! This handbook covers the installation + and day to day use of + <emphasis>FreeBSD &rel2.current;-RELEASE</emphasis> and + <emphasis>FreeBSD &rel.current;-RELEASE</emphasis>. This + manual is a <emphasis>work in progress</emphasis> and is the + work of many individuals. As such, some sections may become + dated and require updating. If you are interested in helping + out with this project, send email to the &a.doc;. The latest + version of this document is always available from the + <ulink url="http://www.FreeBSD.org/">FreeBSD web site</ulink> + (previous versions of this handbook can be obtained from + <ulink url="http://docs.FreeBSD.org/doc/"></ulink>). It may + also be downloaded in a variety of formats and compression + options from the + <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD + FTP server</ulink> or one of the numerous + <link linkend="mirrors-ftp">mirror sites</link>. If you would + prefer to have a hard copy of the handbook, you can purchase + one at the + <ulink url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>. + You may also want to + <ulink url="&url.base;/search/index.html">search the + handbook</ulink>.</para> + </abstract> + </bookinfo> + + &chap.preface; + + <part id="getting-started"> + <title>Getting Started</title> + + <partintro> + <para>This part of the FreeBSD Handbook is for users and + administrators who are new to FreeBSD. These chapters:</para> + + <itemizedlist> + <listitem> + <para>Introduce you to FreeBSD.</para> + </listitem> + + <listitem> + <para>Guide you through the installation process.</para> + </listitem> + + <listitem> + <para>Teach you &unix; basics and fundamentals.</para> + </listitem> + + <listitem> + <para>Show you how to install the wealth of third party + applications available for FreeBSD.</para> + </listitem> + + <listitem> + <para>Introduce you to X, the &unix; windowing system, and + detail how to configure a desktop environment that makes + you more productive.</para> + </listitem> + </itemizedlist> + + <para>We have tried to keep the number of forward references in + the text to a minimum so that you can read this section of the + Handbook from front to back with the minimum page flipping + required.</para> + </partintro> + + <![ %chap.introduction; [ &chap.introduction; ]]> + <![ %chap.install; [ &chap.install; ]]> + <![ %chap.bsdinstall; [ &chap.bsdinstall; ]]> + <![ %chap.basics; [ &chap.basics; ]]> + <![ %chap.ports; [ &chap.ports; ]]> + <![ %chap.x11; [ &chap.x11; ]]> + </part> + + <part id="common-tasks"> + <title>Common Tasks</title> + + <partintro> + <para>Now that the basics have been covered, this part of the + FreeBSD Handbook will discuss some frequently used features of + FreeBSD. These chapters:</para> + + <itemizedlist> + <listitem> + <para>Introduce you to popular and useful desktop + applications: browsers, productivity tools, document + viewers, etc.</para> + </listitem> + + <listitem> + <para>Introduce you to a number of multimedia tools + available for FreeBSD.</para> + </listitem> + + <listitem> + <para>Explain the process of building a customized FreeBSD + kernel, to enable extra functionality on your + system.</para> + </listitem> + + <listitem> + <para>Describe the print system in detail, both for desktop + and network-connected printer setups.</para> + </listitem> + + <listitem> + <para>Show you how to run Linux applications on your FreeBSD + system.</para> + </listitem> + </itemizedlist> + + <para>Some of these chapters recommend that you do some prior + reading, and this is noted in the synopsis at the beginning of + each chapter.</para> + </partintro> + + <![ %chap.desktop; [ &chap.desktop; ]]> + <![ %chap.multimedia; [ &chap.multimedia; ]]> + <![ %chap.kernelconfig; [ &chap.kernelconfig; ]]> + <![ %chap.printing; [ &chap.printing; ]]> + <![ %chap.linuxemu; [ &chap.linuxemu; ]]> + </part> + + <part id="system-administration"> + <title>System Administration</title> + + <partintro> + <para>The remaining chapters of the FreeBSD Handbook cover all + aspects of FreeBSD system administration. Each chapter starts + by describing what you will learn as a result of reading the + chapter, and also details what you are expected to know before + tackling the material.</para> + + <para>These chapters are designed to be read when you need + the information. You do not have to read them in any + particular order, nor do you need to read all of them before + you can begin using FreeBSD.</para> + </partintro> + + <![ %chap.config; [ &chap.config; ]]> + <![ %chap.boot; [ &chap.boot; ]]> + <![ %chap.users; [ &chap.users; ]]> + <![ %chap.security; [ &chap.security; ]]> + <![ %chap.jails; [ &chap.jails; ]]> + <![ %chap.mac; [ &chap.mac; ]]> + <![ %chap.audit; [ &chap.audit; ]]> + <![ %chap.disks; [ &chap.disks; ]]> + <![ %chap.geom; [ &chap.geom; ]]> + <![ %chap.filesystems; [ &chap.filesystems; ]]> + <![ %chap.vinum; [ &chap.vinum; ]]> + <![ %chap.virtualization; [ &chap.virtualization; ]]> + <![ %chap.l10n; [ &chap.l10n; ]]> + <![ %chap.cutting-edge; [ &chap.cutting-edge; ]]> + <![ %chap.dtrace; [ &chap.dtrace; ]]> + </part> + + <part id="network-communication"> + <title>Network Communication</title> + + <partintro> + <para>FreeBSD is one of the most widely deployed operating + systems for high performance network servers. The chapters in + this part cover:</para> + + <itemizedlist> + <listitem> + <para>Serial communication</para> + </listitem> + + <listitem> + <para>PPP and PPP over Ethernet</para> + </listitem> + + <listitem> + <para>Electronic Mail</para> + </listitem> + + <listitem> + <para>Running Network Servers</para> + </listitem> + + <listitem> + <para>Firewalls</para> + </listitem> + + <listitem> + <para>Other Advanced Networking Topics</para> + </listitem> + </itemizedlist> + + <para>These chapters are designed to be read when + you need the information. You do not have to read them in any + particular order, nor do you need to read all of them before + you can begin using FreeBSD in a network environment.</para> + </partintro> + + <![ %chap.serialcomms; [ &chap.serialcomms; ]]> + <![ %chap.ppp-and-slip; [ &chap.ppp-and-slip; ]]> + <![ %chap.mail; [ &chap.mail; ]]> + <![ %chap.network-servers; [ &chap.network-servers; ]]> + <![ %chap.firewalls; [ &chap.firewalls; ]]> + <![ %chap.advanced-networking; [ &chap.advanced-networking; ]]> + + </part> + + <part id="appendices"> + <title>Appendices</title> + + <![ %chap.mirrors; [ &chap.mirrors; ]]> + <![ %chap.bibliography; [ &chap.bibliography; ]]> + <![ %chap.eresources; [ &chap.eresources; ]]> + <![ %chap.pgpkeys; [ &chap.pgpkeys; ]]> + </part> + <![ %chap.freebsd-glossary; [ &bookinfo.freebsd-glossary; ]]> + <![ %chap.index; [ &chap.index; ]]> + &chap.colophon; +</book> + +<!-- + Local Variables: + mode: sgml + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/boot/Makefile b/en_US.ISO8859-1/books/handbook/boot/Makefile new file mode 100644 index 0000000000..92105efc40 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/boot/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= boot/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/boot/chapter.sgml b/en_US.ISO8859-1/books/handbook/boot/chapter.sgml new file mode 100644 index 0000000000..5268b9b5d4 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/boot/chapter.sgml @@ -0,0 +1,1059 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="boot"> + <title>The FreeBSD Booting Process</title> + + <sect1 id="boot-synopsis"> + <title>Synopsis</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>After reading this chapter, you will know:</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>The basics of &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 id="boot-introduction"> + <title>The Booting Problem</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> (aka + <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 (aka 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 id="boot-blocks"> + <title>The Boot Manager and Boot Stages</title> + + <indexterm><primary>Boot Manager</primary></indexterm> + + <sect2 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 + <literal>0x55AA</literal> 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 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 <replaceable>device</replaceable></userinput></screen> + + <para>where <replaceable>device</replaceable> is the device that + you boot from, such as <devicename>ad0</devicename> for the + first IDE disk, <devicename>ad2</devicename> for the first IDE + disk on a second IDE controller, <devicename>da0</devicename> + 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 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>bsdlabel</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>bsdlabel</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 id="boot-boot2-example"> + <title><filename>boot2</filename> Screenshot</title> + + <screen>>> FreeBSD/i386 BOOT +Default: 0:ad(0,a)/boot/loader +boot:</screen> + </example> + + <para>If you ever need to replace the installed + <filename>boot1</filename> and <filename>boot2</filename> use + &man.bsdlabel.8;:</para> + + <screen>&prompt.root; <userinput>bsdlabel -B <replaceable>diskslice</replaceable></userinput></screen> + + <para>where <replaceable>diskslice</replaceable> is the disk and + slice you boot from, such as <devicename>ad0s1</devicename> + 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 + <devicename>ad0</devicename>, in the &man.bsdlabel.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.bsdlabel.8; + command before you press <keycap>Return</keycap>.</para> + </warning> + </sect2> + + <sect2 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 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 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><replaceable>-options</replaceable></optional> + <optional><replaceable>kernelname</replaceable></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. Providing a kernel name on the command-line + is only applicable after an + <emphasis>unload</emphasis> command has been issued, + otherwise the previously-loaded kernel will be + used.</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><replaceable>topic</replaceable></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><option>-t</option> + <replaceable>type</replaceable></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><option>-l</option></optional> + <optional><replaceable>path</replaceable></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><option>-v</option></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><option>-v</option></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 id="boot-loader-examples"> + <title>Loader Examples</title> + + <para>Here are some practical examples of loader usage:</para> + + <itemizedlist> + <indexterm><primary>single-user mode</primary></indexterm> + + <listitem> + <para>To boot your usual kernel, but in single-user + mode:</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> + + <indexterm> + <primary><filename>kernel.old</filename></primary> + </indexterm> + + <screen><userinput>unload</userinput> +<userinput>load <replaceable>kernel.old</replaceable></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> 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="<replaceable>kernel.old</replaceable>"</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 <replaceable>/boot/kernel.conf</replaceable></userinput></screen> + </listitem> + </itemizedlist> + </sect3> + + <sect3 id="boot-splash"> + <sect3info> + <authorgroup> + <author> + <firstname>Joseph J.</firstname> + <surname>Barbish</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect3info> + + <title>Boot Time Splash Screens</title> + + <para>The splash screen creates a more visually appealing boot + screen compared to the original boot messages. This screen + will be displayed until a console login prompt or an X + display manager offers a login prompt.</para> + + <para>There are two basic environments available in &os;. The + first is the default legacy virtual console command line + environment. After the system finishes booting, a console + login prompt is presented. The second environment is the + X11 Desktop graphical environment. After + <link linkend="x-install">X11</link> and one of the + graphical + <link linkend="x11-wm">desktop environments</link>, such as + <application>GNOME</application>, + <application>KDE</application>, or + <application>XFce</application> are installed, the X11 + desktop can be launched by using the + <command>startx</command> command.</para> + + <para>Some users prefer the X11 graphical login screen over + the traditional text based login prompt. Display managers + like <application>XDM</application> for &xorg;, + <application>gdm</application> for + <application>GNOME</application>, and + <application>kdm</application> for + <application>KDE</application> (and any other from the Ports + Collection) provide a graphical login screen in + place of the console login prompt. After a successful + login, they present the user with a graphical + desktop.</para> + + <para>In the command line environment, the splash screen would + hide all the boot probe messages and task startup messages + before displaying the login prompt. In X11 environment, the + users would get a visually clearer system start up + experience resembling something closer to what a + (µsoft; &windows; or non-unix type system) user would + experience.</para> + + <sect4 id="boot-splash-function"> + <title>Splash Screen Function</title> + + <para>The splash screen function supports 256-color + bitmap (<filename>.bmp</filename>), ZSoft + <acronym>PCX</acronym> (<filename>.pcx</filename>), or + TheDraw (<filename>.bin</filename>) files. + In addition, the splash image files must have a resolution + of 320 by 200 pixels or less to work on standard VGA + adapters.</para> + + <para>To use larger images, up to the maximum resolution of + 1024 by 768 pixels, activate the <acronym>VESA</acronym> + support included in &os;. This can be enabled by loading + the <acronym>VESA</acronym> module during system boot, or + adding a <literal>VESA</literal> kernel configuration + option and building a custom kernel (see <xref + linkend="kernelconfig">). The <acronym>VESA</acronym> + support gives users the ability to display a splash screen + image that fills the whole display screen.</para> + + <para>While the splash screen is being displayed during the + booting process, it can be turned off any time by hitting + any key on the keyboard.</para> + + <para>The splash screen also defaults to being a screen + saver outside of X11. After a time period of non-use the + screen will change to the splash screen and cycle through + steps of changing intensity of the image, from bright to a + very dark and over again. This default splash screen + (screen saver) behavior could be overridden by adding a + <literal>saver=</literal> line to + <filename>/etc/rc.conf</filename>. Option + <literal>saver=</literal> has several built-in screen + savers to choose from, the full list can be found in the + &man.splash.4; manual page. The default screen saver is + called <quote>warp</quote>. Note that the + <literal>saver=</literal> option specified in + <filename>/etc/rc.conf</filename> only applies to virtual + consoles. It has no effect on X11 display + managers.</para> + + <para>A few boot loader messages, including the boot options + menu and a timed wait count down prompt are displayed at + boot time, even when the splash screen is enabled.</para> + + <para>Sample splash screen files can be downloaded from the + gallery at <ulink + url="http://artwork.freebsdgr.org/node/3/">http://artwork.freebsdgr.org</ulink>. + By installing the <filename + role="package">sysutils/bsd-splash-changer</filename> + port, splash images can be chosen from a collection + randomly at each boot.</para> + </sect4> + + <sect4 id="boot-splash-enable"> + <title>Enabling the Splash Screen Function</title> + + <para>The splash screen (<filename>.bmp</filename>, + <filename>.pcx</filename>, or <filename>.bin</filename>) + file has to be placed on the root partition, for example + in the <filename class="directory">/boot</filename> + directory.</para> + + <para>For default boot display resolution (256-color, 320 by + 200 pixels, or less), edit + <filename>/boot/loader.conf</filename>, so it contains the + following:</para> + + <programlisting>splash_bmp_load="YES" +bitmap_load="YES" +bitmap_name="<replaceable>/boot/splash.bmp</replaceable>"</programlisting> + + <para>For larger video resolutions up to the maximum of 1024 + by 768 pixels, edit + <filename>/boot/loader.conf</filename>, so it contains the + following:</para> + + <programlisting>vesa_load="YES" +splash_bmp_load="YES" +bitmap_load="YES" +bitmap_name="<replaceable>/boot/splash.bmp</replaceable>"</programlisting> + + <para>The above assumes that + <filename><replaceable>/boot/splash.bmp</replaceable></filename> + is used for splash screen. When a <acronym>PCX</acronym> + file is desired, use the following statements, plus the + <literal>vesa_load="YES"</literal> line depending on the + resolution.</para> + + <programlisting>splash_pcx_load="YES" +bitmap_load="YES" +bitmap_name="<replaceable>/boot/splash.pcx</replaceable>"</programlisting> + + <para>In version 8.3 another option is to use ascii art in + <ulink url="https://en.wikipedia.org/wiki/TheDraw">TheDraw</ulink> + format.</para> + + <programlisting>splash_txt="YES" +bitmap_load="YES" +bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> + + <para>The file name is not restricted to <quote>splash</quote> + as shown in the above example. It can be anything as long + as it is one of the above types such as, + <filename><replaceable>splash_640x400</replaceable>.bmp</filename> + or + <filename><replaceable>bluewave</replaceable>.pcx</filename>.</para> + + <para>Some other interesting + <filename>loader.conf</filename> options:</para> + + <variablelist> + <varlistentry> + <term><literal>beastie_disable="YES"</literal></term> + + <listitem> + <para>This will stop the boot options menu from being + displayed, but the timed wait count down prompt will + still be present. Even with the display of the boot + options menu disabled, entering an option selection + at the timed wait count down prompt will enact the + corresponding boot option.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>loader_logo="beastie"</literal></term> + + <listitem> + <para>This will replace the default words + <quote>&os;</quote>, which are displayed to the + right of the boot options menu with the colored + beastie logo like releases in the past had.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>For more information, please see the &man.splash.4;, + &man.loader.conf.5;, and &man.vga.4; manual pages.</para> + </sect4> + </sect3> + </sect2> + </sect1> + + <sect1 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 id="boot-kernel-bootflags"> + <indexterm> + <primary>kernel</primary> + <secondary>bootflags</secondary> + </indexterm> + <title>Kernel Boot Flags</title> + + <para>Here are the more common boot flags:</para> + + <variablelist 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 id="device-hints"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <!-- 18 OCT 2002 --> + </sect1info> + <indexterm> + <primary>device.hints</primary> + </indexterm> + <title>Device Hints</title> + + <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="<replaceable>value</replaceable>"</userinput></screen> + + <para>The syntax for the Stage 3 boot loader is:</para> + + <screen><userinput>set hint.driver.unit.keyword=<replaceable>value</replaceable></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 id="boot-init"> + <indexterm> + <primary><command>init</command></primary> + </indexterm> + <title>Init: Process Control Initialization</title> + + <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 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 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 <username>root</username> + password before initiating single-user mode.</para> + + <example 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 + <username>root</username> 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 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 id="boot-rc"> + <indexterm><primary>rc files</primary></indexterm> + <title>Resource Configuration (rc)</title> + + <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 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, 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 + <username>root</username> or a member of + <groupname>operator</groupname> 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.</para> + </note> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/bsdinstall/Makefile b/en_US.ISO8859-1/books/handbook/bsdinstall/Makefile new file mode 100644 index 0000000000..b5f6bf3805 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/bsdinstall/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= bsdinstall/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.sgml b/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.sgml new file mode 100644 index 0000000000..5e996fa4ce --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.sgml @@ -0,0 +1,2729 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="bsdinstall"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Mock</surname> + <contrib>Restructured, reorganized, and parts + rewritten by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Randy</firstname> + <surname>Pratt</surname> + <contrib>The sysinstall walkthrough, screenshots, and general + copy by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Gavin</firstname> + <surname>Atkinson</surname> + <contrib>Updated for bsdinstall by </contrib> + </author> + + <author> + <firstname>Warren</firstname> + <surname>Block</surname> + </author> + </authorgroup> + </chapterinfo> + + <title>Installing &os; 9.<replaceable>x</replaceable> and + Later</title> + + <sect1 id="bsdinstall-synopsis"> + <title>Synopsis</title> + + <indexterm><primary>installation</primary></indexterm> + + <para>&os; comes with a text-based, easy to use installation + program. &os; 9.0-RELEASE and later use an installation + program called <application>bsdinstall</application>, while + releases prior to &os; 9.0-RELEASE using + <application>sysinstall</application> for installation. This + chapter describes the use of + <application>bsdinstall</application>. The use of + <application>sysinstall</application> is covered in <xref + linkend="install">.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to create the &os; installation media.</para> + </listitem> + + <listitem> + <!-- WB: verify this, including GPT partition notation (ada0p2) --> + <para>How &os; subdivides and refers to hard disks.</para> + </listitem> + + <listitem> + <para>How to start + <application>bsdinstall</application>.</para> + </listitem> + + <listitem> + <para>The questions <application>bsdinstall</application> will + ask you, what they mean, and how to answer them.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Read the supported hardware list that shipped with the + version of &os; you are installing, and verify that your + hardware is supported.</para> + </listitem> + </itemizedlist> + + <note> + <para>In general, these installation instructions are written + for &i386; (<quote>PC compatible</quote>) architecture + computers. Where applicable, instructions specific to other + platforms will be listed. There may be minor differences + between the installer and what is shown here, so use this + chapter as a general guide rather than as exact literal + instructions.</para> + </note> + </sect1> + + <sect1 id="bsdinstall-hardware"> + <title>Hardware Requirements</title> + + <sect2 id="bsdinstall-hardware-minimal"> + <title>Minimal Configuration</title> + + <para>The minimal configuration to install &os; varies with the + &os; version and the hardware architecture.</para> + + <para>A summary of this information is given in the following + sections. Depending on the method you choose to install &os;, + you may also need a supported CDROM drive, and in some cases a + network adapter. This will be covered by <xref + linkend="bsdinstall-installation-media">.</para> + + <sect3> + <title>&os;/&arch.i386;</title> + + <para>&os;/&arch.i386; requires a 486 or better processor and + at least 64 MB of RAM. At least 1.1 GB of free + hard drive space is needed for the most minimal + installation.</para> + + <note> + <para>On old computers, increasing RAM and hard drive space + is usually more effective at improving performance than + installing a faster processor.</para> + </note> + </sect3> + + <sect3> + <title>&os;/&arch.amd64;</title> + + <para>There are two classes of processors capable of running + &os;/&arch.amd64;. The first are AMD64 processors, + including the &amd.athlon;64, + &amd.athlon;64-FX, &amd.opteron; or better + processors.</para> + + <para>The second class of processors that can use + &os;/&arch.amd64; includes those using the + &intel; EM64T architecture. Examples of these + processors include the &intel; &core; 2 Duo, Quad, + Extreme processor families, the &intel; &xeon; 3000, + 5000, and 7000 sequences of processors, and the + &intel; &core; i3, i5 and i7 processors.</para> + + <para>If you have a machine based on an nVidia nForce3 + Pro-150, you <emphasis>must</emphasis> use the BIOS setup to + disable the IO APIC. If you do not have an option to do + this, you will likely have to disable ACPI instead. There + are bugs in the Pro-150 chipset for which we have not yet + found a workaround.</para> + </sect3> + + <sect3> + <title>&os;/&arch.powerpc; &apple; &macintosh;</title> + + <para>All New World &apple; &macintosh; systems with built-in + USB are supported. SMP is supported on machines with + multiple CPUs.</para> + + <para>A 32-bit kernel can only use the first 2 GB of RAM. + &firewire; is not supported on the Blue & White PowerMac + G3.</para> + </sect3> + + <sect3> + <title>&os;/&arch.sparc64;</title> + + <para>Systems supported by &os;/&arch.sparc64; are listed at + the <ulink + url="http://www.freebsd.org/platforms/sparc.html"> + FreeBSD/sparc64</ulink> Project.</para> + + <para>A dedicated disk is required for &os;/&arch.sparc64;. + It is not possible to share a disk with another operating + system at this time.</para> + </sect3> + </sect2> + + <sect2 id="bsdinstall-hardware-supported"> + <title>Supported Hardware</title> + + <para>Hardware architectures and devices supported by a &os; + release are listed in the Hardware Notes file. Usually named + <filename>HARDWARE.TXT</filename>, the file is located in the + root directory of the release media. Copies of the supported + hardware list are also available on the <ulink + url="http://www.FreeBSD.org/releases/index.html">Release + Information</ulink> page of the &os; web site.</para> + </sect2> + </sect1> + + <sect1 id="bsdinstall-pre"> + <title>Pre-Installation Tasks</title> + + <sect2> + <title>Back Up Your Data</title> + + <para>Back up all important data on the target computer + where &os; will be installed. Test the backups before + continuing. The &os; installer will ask before making changes + to the disk, but once the process has started it cannot be + undone.</para> + </sect2> + + <sect2 id="bsdinstall-where"> + <title>Decide Where to Install &os;</title> + + <para>If &os; will be the only operating system installed, and + will be allowed to use the entire hard disk, the rest of + this section can be skipped. But if &os; will share the disk + with other operating systems, an understanding of disk + layout is useful during the installation.</para> + + <sect3 id="bsdinstall-where-i386"> + <title>Disk Layouts for &os;/&arch.i386; and + &os;/&arch.amd64;</title> + + <para>Hard disks can be divided into multiple sections. These + sections are called + <firstterm>partitions</firstterm>.</para> + + <para>There are two ways of dividing a disk into partitions. + A traditional <firstterm>Master Boot Record</firstterm> + (<acronym role="Master Boot Record">MBR</acronym>) holds a + partition table defining up to four <firstterm>primary + partitions</firstterm>. (For historical reasons, &os; + calls primary partitions <firstterm>slices</firstterm>.) A + limit of only four partitions is restrictive for large + disks, so one of these primary partitions can be made into + an <firstterm>extended partition</firstterm>. Multiple + <firstterm>logical partitions</firstterm> may then be + created inside the extended partition. This may sound a + little unwieldy, and it is.</para> + + <para>The <firstterm>GUID Partition Table</firstterm> + (<acronym role="GUID Partition Table">GPT</acronym>) is a + newer and simpler method of partitioning a disk. <acronym + role="GUID Partition Table">GPT</acronym> is far more + versatile than the traditional MBR partition table. Common + <acronym>GPT</acronym> implementations allow up to 128 + partitions per disk, eliminating the need for inconvenient + workarounds like logical partitions.</para> + + <warning> + <para>Some older operating systems like &windows; XP + are not compatible with the <acronym>GPT</acronym> + partition scheme. If &os; will be sharing a disk with + such an operating system, <acronym role="Master Boot + Record">MBR</acronym> partitioning is required.</para> + </warning> + + <para>&os;'s standard boot loader requires either a primary or + <acronym>GPT</acronym> partition. (See <xref + linkend="boot"> for more information about the &os; + booting process.) If all of the primary or + <acronym>GPT</acronym> partitions are already in use, one + must be freed for &os;.</para> + + <para>A minimal installation of &os; takes as little as + 1 GB of disk space. However, that is a + <emphasis>very</emphasis> minimal install, leaving almost no + free space. A more realistic minimum is 3 GB without a + graphical environment, and 5 GB or more if a graphical + user interface will be used. Third-party application + software requires more space.</para> + + <para>A variety of <ulink + url="http://en.wikipedia.org/wiki/List_of_disk_partitioning_software"> + free and commercial partition resizing tools</ulink> are + available. <ulink + url="http://gparted.sourceforge.net/livecd.php">GParted + Live</ulink> is a free Live CD which includes the GParted + partition editor. GParted is also included with many other + Linux Live CD distributions.</para> + + <warning> + <para>Disk partition applications can destroy data. Make a + full backup and verify its integrity before modifying disk + partitions.</para> + </warning> + + <para>Resizing µsoft; Vista partitions can be + difficult. A Vista installation CDROM can be useful when + attempting such an operation.</para> + + <example> + <title>Using an Existing Partition</title> + + <para>A &windows; computer has a single 40 GB disk that + has been split into two 20 GB partitions. &windows; + calls them <devicename>C:</devicename> and + <devicename>D:</devicename>. The + <devicename>C:</devicename> partition contains 10 GB + of data, and the <devicename>D:</devicename> partition + contains 5 GB of data.</para> + + <para>Moving the data from <devicename>D:</devicename> to + <devicename>C:</devicename> frees up the second partition + to be used for &os;.</para> + </example> + + <example> + <title>Shrinking an Existing Partition</title> + + <para>A &windows; computer has a single 40 GB disk and + one large partition using the whole disk. &windows; shows + this 40 GB partition as a single + <devicename>C:</devicename>. 15 GB of space is being + used. The goal is to end up with &windows; in a + 20 GB partition, and have another 20 GB + partition for &os;.</para> + + <para>There are two ways to do this.</para> + + <orderedlist> + <listitem> + <para>Back up your &windows; data. Then reinstall + &windows;, creating a 20 GB partition during the + install.</para> + </listitem> + + <listitem> + <para>Use a partition resizing tool like + <application>GParted</application> to shrink the + &windows; partition and create a new partition in the + freed space for &os;.</para> + </listitem> + </orderedlist> + </example> + + <para>Disk partitions containing different operating systems + make it possible to run any one of those operating systems + at a time. An alternative method that allows running + multiple operating systems at the same time is covered in + <xref linkend="virtualization">.</para> + </sect3> + </sect2> + + <sect2 id="bsdinstall-collect-network-information"> + <title>Collect Network Information</title> + + <para>Some &os; installation methods need a network connection + to download files. To connect to an Ethernet network (or + cable or DSL modem with an Ethernet interface), the installer + will request some information about the network.</para> + + <para><firstterm><acronym role="Dynamic Host Configuration + Protocol">DHCP</acronym></firstterm> is commonly used to + provide automatic network configuration. If + <acronym>DHCP</acronym> is not available, this network + information must be obtained from the local network + administrator or service provider:</para> + + <orderedlist> + <title>Network Information</title> + + <listitem> + <para><acronym role="Internet Protocol">IP</acronym> + address</para> + </listitem> + + <listitem> + <para>Subnet mask</para> + </listitem> + + <listitem> + <para>Default router <acronym>IP</acronym> address</para> + </listitem> + + <listitem> + <para>domain name of the local network</para> + </listitem> + + <listitem> + <para><acronym role="Domain Name System">DNS</acronym> + server <acronym>IP</acronym> address(es)</para> + </listitem> + </orderedlist> + </sect2> + + <sect2> + <title>Check for &os; Errata</title> + + <para>Although the &os; Project strives to ensure that each + release of &os; is as stable as possible, bugs occasionally + creep into the process. On very rare occasions those bugs + affect the installation process. As these problems are + discovered and fixed, they are noted in the <ulink + url="&url.base;/releases/9.0R/errata.html">FreeBSD + Errata</ulink> on the &os; web site. Check the errata before + installing to make sure that there are no problems that might + affect the installation.</para> + + <para>Information and errata for all the releases can be found + on the <ulink url="&url.base;/releases/index.html">release + information</ulink> section of the <ulink + url="&url.base;/index.html">&os; web site</ulink>.</para> + </sect2> + + <sect2 id="bsdinstall-installation-media"> + <title>Prepare the Installation Media</title> + + <para>A &os; installation is started by booting the computer + with a &os; installation CD, DVD, or USB memory stick. The + installer is not a program that can be run from within another + operating system.</para> + + <para>In addition to the standard installation media which + contains copies of all the &os; installation files, there is a + <emphasis>bootonly</emphasis> variant. Bootonly install media + does not have copies of the installation files, but downloads + them from the network during an install. The bootonly install + CD is consequently much smaller, and reduces bandwidth usage + during the install by only downloading required files.</para> + + <para>Copies of &os; installation media are available at the + <ulink url="&url.base;/where.html#download">&os; web + site</ulink>.</para> + + <tip> + <para>If you already have a copy of &os; on CDROM, DVD, or USB + memory stick, this section can be skipped.</para> + </tip> + + <para>&os; CD and DVD images are bootable ISO files. Only one + CD or DVD is needed for an install. Burn the ISO image to a + bootable CD or DVD using the CD recording applications + available with your current operating system.</para> + + <para>To create a bootable memory stick, follow these + steps:</para> + + <procedure> + <step> + <title>Acquire the Memory Stick Image</title> + + <para>Memory stick images for &os; 9.0-RELEASE and + later can be downloaded from the + <filename class="directory">ISO-IMAGES/</filename> + directory at + <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>arch</replaceable>/ISO-IMAGES/<replaceable>version</replaceable>/&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-memstick.img</literal>. + Replace <replaceable>arch</replaceable> and + <replaceable>version</replaceable> with the + architecture and the version number which you want to + install, respectively. For example, the memory stick + images for &os;/&arch.i386; 9.0-RELEASE are + available from <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/9.0/&os;-9.0-RELEASE-&arch.i386;-memstick.img"></ulink>.</para> + + <tip> + <para>A different directory path is used for + &os; 8.<replaceable>X</replaceable> and earlier versions. Details of + download and installation of &os; 8.<replaceable>X</replaceable> and + earlier is covered in <xref linkend="install">.</para> + </tip> + + <para>The memory stick image has a <filename>.img</filename> + extension. The <filename + class="directory">ISO-IMAGES/</filename> directory + contains a number of different images, and the one needed + depends on the version of &os; being installed, and in + some cases, the target hardware.</para> + + <important> + <para>Before proceeding, <emphasis>back up</emphasis> the + data on the USB stick, as this procedure will + <emphasis>erase</emphasis> it.</para> + </important> + </step> + + <step> + <title>Write the Image File to the Memory Stick</title> + + <procedure> + <title>Using &os; to Write the Image</title> + + <warning> + <para>The example below shows <filename + class="devicefile">/dev/da0</filename> as the target + device where the image will be written. Be very + careful that the correct device is used as the output + target, or you may destroy existing data.</para> + </warning> + + <step> + <title>Writing the Image with &man.dd.1;</title> + + <para>The <filename>.img</filename> file is + <emphasis>not</emphasis> a regular file. It is an + <emphasis>image</emphasis> of the complete contents of + the memory stick. It <emphasis>cannot</emphasis> + simply be copied like a regular file, but must be + written directly to the target device with + &man.dd.1;:</para> + + <screen>&prompt.root; <userinput>dd if=&os;-9.0-RELEASE-&arch.i386;-memstick.img of=/dev/<replaceable>da0</replaceable> bs=64k</userinput></screen> + </step> + </procedure> + + <procedure> + <title>Using &windows; to Write the Image</title> + + <warning> + <para>Be sure to give the correct drive letter as the + output target, or you may overwrite and destroy + existing data.</para> + </warning> + + <step> + <title>Obtaining <application>Image Writer for + &windows;</application></title> + + <para><application>Image Writer for + &windows;</application> is a free application that + can correctly write an image file to a memory stick. + Download it from <ulink + url="https://launchpad.net/win32-image-writer/"></ulink> + and extract it into a folder.</para> + </step> + + <step> + <title>Writing the Image with Image Writer</title> + + <para>Double-click the + <application>Win32DiskImager</application> icon to + start the program. Verify that the drive letter shown + under <computeroutput>Device</computeroutput> is the + drive with the memory stick. Click the folder icon + and select the image to be written to the memory + stick. Click + <guibutton>[ Save ]</guibutton> to accept + the image file name. Verify that everything is + correct, and that no folders on the memory stick are + open in other windows. When everything is ready, + click <guibutton>[ Write ]</guibutton> to + write the image file to the memory stick.</para> + </step> + </procedure> + </step> + </procedure> + + <note> + <para>Installation from floppy disks is no longer + supported.</para> + </note> + + <para>You are now ready to start installing &os;.</para> + </sect2> + </sect1> + + <sect1 id="bsdinstall-start"> + <title>Starting the Installation</title> + + <important> + <para>By default, the installation will not make any changes to + your disk(s) until you see the following message:</para> + + <literallayout class="monospaced">Your changes will now be written to disk. If you +have chosen to overwrite existing data, it will +be PERMANENTLY ERASED. Are you sure you want to +commit your changes?</literallayout> + + <para>The install can be exited at any time prior to this + warning without changing the contents of the hard drive. If + you are concerned that you have configured something + incorrectly you can just turn the computer off before this + point, and no damage will be done.</para> + </important> + + <sect2 id="bsdinstall-starting"> + <title>Booting</title> + + <sect3 id="bsdinstall-starting-i386"> + <title>Booting on &i386; and &arch.amd64;</title> + + <procedure> + <step> + <para>If you prepared a <quote>bootable</quote> USB stick, + as described in + <xref linkend="bsdinstall-installation-media">, then + plug in your USB stick before turning on the + computer.</para> + + <para>If you are booting from CDROM, then you will need to + turn on the computer, and insert the CDROM at the first + opportunity.</para> + </step> + + <step> + <para>Configure your machine to boot from either the CDROM + or from USB, depending on the media being used for the + installation. <acronym role="Basic Input/Output + System">BIOS</acronym> configurations allow the + selection of a specific boot device. Most systems also + provide for selecting a boot device during startup, + typically by pressing <keycap>F10</keycap>, + <keycap>F11</keycap>, <keycap>F12</keycap>, or + <keycap>Escape</keycap>.</para> + </step> + + <step> + <para>If your computer starts up as normal and loads your + existing operating system, then either:</para> + + <orderedlist> + <listitem> + <para>The disks were not inserted early enough in the + boot process. Leave them in, and try restarting + your computer.</para> + </listitem> + + <listitem> + <para>The <acronym>BIOS</acronym> changes earlier did + not work correctly. You should redo that step until + you get the right option.</para> + </listitem> + + <listitem> + <para>Your particular <acronym>BIOS</acronym> does not + support booting from the desired media. The <ulink + url="http://www.plop.at/en/bootmanager.html">Plop + Boot Manager</ulink> can be used to boot older + computers from CD or USB media.</para> + </listitem> + </orderedlist> + </step> + + <step> + <para>&os; will start to boot. If you are booting from + CDROM you will see a display similar to this (version + information omitted):</para> + + <screen>Booting from CD-ROM... +645MB medium detected +CD Loader 1.2 + +Building the boot loader arguments +Looking up /BOOT/LOADER... Found +Relocating the loader and the BTX +Starting the BTX loader + +BTX loader 1.00 BTX version is 1.02 +Consoles: internal video/keyboard +BIOS CD is cd0 +BIOS drive C: is disk0 +BIOS drive D: is disk1 +BIOS 636kB/261056kB available memory + +FreeBSD/i386 bootstrap loader, Revision 1.1 + +Loading /boot/defaults/loader.conf +/boot/kernel/kernel text=0x64daa0 data=0xa4e80+0xa9e40 syms=[0x4+0x6cac0+0x4+0x88e9d] +\</screen> + </step> + + <step> + <para>The &os; boot loader is displayed:</para> + + <figure id="bsdinstall-boot-loader-menu"> + <title>&os; Boot Loader Menu</title> + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-boot-loader-menu" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Either wait ten seconds, or press + <keycap>Enter</keycap>.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Booting for &macintosh; &powerpc;</title> + + <para>On most machines, holding <keycap>C</keycap> on the + keyboard during boot will boot from the CD. Otherwise, hold + <keycombo action="simul"> + <keycap>Command</keycap> + <keycap>Option</keycap> + <keycap>O</keycap> + <keycap>F</keycap> + </keycombo>, + or + <keycombo action="simul"> + <keycap>Windows</keycap> + <keycap>Alt</keycap> + <keycap>O</keycap> + <keycap>F</keycap> + </keycombo> + on non-&apple; keyboards. At the <prompt>0 ></prompt> + prompt, enter</para> + + <screen><userinput>boot cd:,\ppc\loader cd:0</userinput></screen> + + <para>For Xserves without keyboards, see + <ulink url="http://support.apple.com/kb/TA26930">&apple;'s + support web site</ulink> about booting into Open + Firmware.</para> + </sect3> + + <sect3> + <title>Booting for &sparc64;</title> + + <para>Most &sparc64; systems are set up to boot automatically + from disk. To install &os;, you need to boot over the + network or from a CDROM, which requires you to break into + the <acronym role="Programmable Read Only + Memory">PROM</acronym> (OpenFirmware).</para> + + <para>To do this, reboot the system, and wait until the boot + message appears. It depends on the model, but should look + about like:</para> + + <screen>Sun Blade 100 (UltraSPARC-IIe), Keyboard Present +Copyright 1998-2001 Sun Microsystems, Inc. All rights reserved. +OpenBoot 4.2, 128 MB memory installed, Serial #51090132. +Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.</screen> + + <para>If your system proceeds to boot from disk at this point, + you need to press + <keycombo + action="simul"><keycap>L1</keycap><keycap>A</keycap></keycombo> + or + <keycombo + action="simul"><keycap>Stop</keycap><keycap>A</keycap></keycombo> + on the keyboard, or send a <command>BREAK</command> over the + serial console (using for example <command>~#</command> in + &man.tip.1; or &man.cu.1;) to get to the <acronym + role="Programmable Read Only Memory">PROM</acronym> + prompt. It looks like this:</para> + + <screenco> + <areaspec> + <area id="bsdinstall-prompt-single" coords="1 5"> + <area id="bsdinstall-prompt-smp" coords="2 5"> + </areaspec> + + <screen><prompt>ok </prompt> +<prompt>ok {0} </prompt></screen> + + <calloutlist> + <callout arearefs="bsdinstall-prompt-single"> + <para>This is the prompt used on systems with just one + CPU.</para> + </callout> + + <callout arearefs="bsdinstall-prompt-smp"> + <para>This is the prompt used on SMP systems, the digit + indicates the number of the active CPU.</para> + </callout> + </calloutlist> + </screenco> + + <para>At this point, place the CDROM into your drive, and from + the <acronym>PROM</acronym> prompt, type + <command>boot cdrom</command>.</para> + + </sect3> + + </sect2> + + <sect2 id="bsdinstall-view-probe"> + <title>Reviewing the Device Probe Results</title> + + <para>The last few hundred lines that have been displayed on + screen are stored and can be reviewed.</para> + + <para>To review the buffer, press <keycap>Scroll Lock</keycap>. + This turns on scrolling in the display. You can then use the + arrow keys, or <keycap>PageUp</keycap> and + <keycap>PageDown</keycap> to view the results. Press + <keycap>Scroll Lock</keycap> again to stop scrolling.</para> + + <para>Do this now, to review the text that scrolled off the + screen when the kernel was carrying out the device probes. + You will see text similar to <xref + linkend="bsdinstall-dev-probe">, although the precise text + will differ depending on the devices that you have in your + computer.</para> + + <figure id="bsdinstall-dev-probe"> + <title>Typical Device Probe Results</title> + + <screen>Copyright (c) 1992-2011 The FreeBSD Project. +Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994 + The Regents of the University of California. All rights reserved. +FreeBSD is a registered trademark of The FreeBSD Foundation. +FreeBSD 9.0-RELEASE #0 r225473M: Sun Sep 11 16:07:30 BST 2011 + root@psi:/usr/obj/usr/src/sys/GENERIC amd64 +CPU: Intel(R) Core(TM)2 Duo CPU T9400 @ 2.53GHz (2527.05-MHz K8-class CPU) + Origin = "GenuineIntel" Id = 0x10676 Family = 6 Model = 17 Stepping = 6 + Features=0xbfebfbff<FPU,VME,DE,PSE,TSC,MSR,PAE,MCE,CX8,APIC,SEP,MTRR,PGE,MCA,CMOV,PAT,PSE36,CLFLUSH,DTS,ACPI,MMX,FXSR,SSE,SSE2,SS,HTT,TM,PBE> + Features2=0x8e3fd<SSE3,DTES64,MON,DS_CPL,VMX,SMX,EST,TM2,SSSE3,CX16,xTPR,PDCM,SSE4.1> + AMD Features=0x20100800<SYSCALL,NX,LM> + AMD Features2=0x1<LAHF> + TSC: P-state invariant, performance statistics +real memory = 3221225472 (3072 MB) +avail memory = 2926649344 (2791 MB) +Event timer "LAPIC" quality 400 +ACPI APIC Table: <TOSHIB A0064 > +FreeBSD/SMP: Multiprocessor System Detected: 2 CPUs +FreeBSD/SMP: 1 package(s) x 2 core(s) + cpu0 (BSP): APIC ID: 0 + cpu1 (AP): APIC ID: 1 +ioapic0: Changing APIC ID to 1 +ioapic0 <Version 2.0> irqs 0-23 on motherboard +kbd1 at kbdmux0 +acpi0: <TOSHIB A0064> on motherboard +acpi0: Power Button (fixed) +acpi0: reservation of 0, a0000 (3) failed +acpi0: reservation of 100000, b6690000 (3) failed +Timecounter "ACPI-safe" frequency 3579545 Hz quality 850 +acpi_timer0: <24-bit timer at 3.579545MHz> port 0xd808-0xd80b on acpi0 +cpu0: <ACPI CPU> on acpi0 +ACPI Warning: Incorrect checksum in table [ASF!] - 0xFE, should be 0x9A (20110527/tbutils-282) +cpu1: <ACPI CPU> on acpi0 +pcib0: <ACPI Host-PCI bridge> port 0xcf8-0xcff on acpi0 +pci0: <ACPI PCI bus> on pcib0 +vgapci0: <VGA-compatible display> port 0xcff8-0xcfff mem 0xff400000-0xff7fffff,0xe0000000-0xefffffff irq 16 at device 2.0 on pci0 +agp0: <Intel GM45 SVGA controller> on vgapci0 +agp0: aperture size is 256M, detected 131068k stolen memory +vgapci1: <VGA-compatible display> mem 0xffc00000-0xffcfffff at device 2.1 on pci0 +pci0: <simple comms> at device 3.0 (no driver attached) +em0: <Intel(R) PRO/1000 Network Connection 7.2.3> port 0xcf80-0xcf9f mem 0xff9c0000-0xff9dffff,0xff9fe000-0xff9fefff irq 20 at device 25.0 on pci0 +em0: Using an MSI interrupt +em0: Ethernet address: 00:1c:7e:6a:ca:b0 +uhci0: <Intel 82801I (ICH9) USB controller> port 0xcf60-0xcf7f irq 16 at device 26.0 on pci0 +usbus0: <Intel 82801I (ICH9) USB controller> on uhci0 +uhci1: <Intel 82801I (ICH9) USB controller> port 0xcf40-0xcf5f irq 21 at device 26.1 on pci0 +usbus1: <Intel 82801I (ICH9) USB controller> on uhci1 +uhci2: <Intel 82801I (ICH9) USB controller> port 0xcf20-0xcf3f irq 19 at device 26.2 on pci0 +usbus2: <Intel 82801I (ICH9) USB controller> on uhci2 +ehci0: <Intel 82801I (ICH9) USB 2.0 controller> mem 0xff9ff800-0xff9ffbff irq 19 at device 26.7 on pci0 +usbus3: EHCI version 1.0 +usbus3: <Intel 82801I (ICH9) USB 2.0 controller> on ehci0 +hdac0: <Intel 82801I High Definition Audio Controller> mem 0xff9f8000-0xff9fbfff irq 22 at device 27.0 on pci0 +pcib1: <ACPI PCI-PCI bridge> irq 17 at device 28.0 on pci0 +pci1: <ACPI PCI bus> on pcib1 +iwn0: <Intel(R) WiFi Link 5100> mem 0xff8fe000-0xff8fffff irq 16 at device 0.0 on pci1 +pcib2: <ACPI PCI-PCI bridge> irq 16 at device 28.1 on pci0 +pci2: <ACPI PCI bus> on pcib2 +pcib3: <ACPI PCI-PCI bridge> irq 18 at device 28.2 on pci0 +pci4: <ACPI PCI bus> on pcib3 +pcib4: <ACPI PCI-PCI bridge> at device 30.0 on pci0 +pci5: <ACPI PCI bus> on pcib4 +cbb0: <RF5C476 PCI-CardBus Bridge> at device 11.0 on pci5 +cardbus0: <CardBus bus> on cbb0 +pccard0: <16-bit PCCard bus> on cbb0 +isab0: <PCI-ISA bridge> at device 31.0 on pci0 +isa0: <ISA bus> on isab0 +ahci0: <Intel ICH9M AHCI SATA controller> port 0x8f58-0x8f5f,0x8f54-0x8f57,0x8f48-0x8f4f,0x8f44-0x8f47,0x8f20-0x8f3f mem 0xff9fd800-0xff9fdfff irq 19 at device 31.2 on pci0 +ahci0: AHCI v1.20 with 4 3Gbps ports, Port Multiplier not supported +ahcich0: <AHCI channel> at channel 0 on ahci0 +ahcich1: <AHCI channel> at channel 1 on ahci0 +ahcich2: <AHCI channel> at channel 4 on ahci0 +acpi_lid0: <Control Method Lid Switch> on acpi0 +battery0: <ACPI Control Method Battery> on acpi0 +acpi_button0: <Power Button> on acpi0 +acpi_acad0: <AC Adapter> on acpi0 +acpi_toshiba0: <Toshiba HCI Extras> on acpi0 +acpi_tz0: <Thermal Zone> on acpi0 +attimer0: <AT timer> port 0x40-0x43 irq 0 on acpi0 +Timecounter "i8254" frequency 1193182 Hz quality 0 +Event timer "i8254" frequency 1193182 Hz quality 100 +atkbdc0: <Keyboard controller (i8042)> port 0x60,0x64 irq 1 on acpi0 +atkbd0: <AT Keyboard> irq 1 on atkbdc0 +kbd0 at atkbd0 +atkbd0: [GIANT-LOCKED] +psm0: <PS/2 Mouse> irq 12 on atkbdc0 +psm0: [GIANT-LOCKED] +psm0: model GlidePoint, device ID 0 +atrtc0: <AT realtime clock> port 0x70-0x71 irq 8 on acpi0 +Event timer "RTC" frequency 32768 Hz quality 0 +hpet0: <High Precision Event Timer> iomem 0xfed00000-0xfed003ff on acpi0 +Timecounter "HPET" frequency 14318180 Hz quality 950 +Event timer "HPET" frequency 14318180 Hz quality 450 +Event timer "HPET1" frequency 14318180 Hz quality 440 +Event timer "HPET2" frequency 14318180 Hz quality 440 +Event timer "HPET3" frequency 14318180 Hz quality 440 +uart0: <16550 or compatible> port 0x3f8-0x3ff irq 4 flags 0x10 on acpi0 +sc0: <System console> at flags 0x100 on isa0 +sc0: VGA <16 virtual consoles, flags=0x300> +vga0: <Generic ISA VGA> at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0 +ppc0: cannot reserve I/O port range +est0: <Enhanced SpeedStep Frequency Control> on cpu0 +p4tcc0: <CPU Frequency Thermal Control> on cpu0 +est1: <Enhanced SpeedStep Frequency Control> on cpu1 +p4tcc1: <CPU Frequency Thermal Control> on cpu1 +Timecounters tick every 1.000 msec +hdac0: HDA Codec #0: Realtek ALC268 +hdac0: HDA Codec #1: Lucent/Agere Systems (Unknown) +pcm0: <HDA Realtek ALC268 PCM #0 Analog> at cad 0 nid 1 on hdac0 +pcm1: <HDA Realtek ALC268 PCM #1 Analog> at cad 0 nid 1 on hdac0 +usbus0: 12Mbps Full Speed USB v1.0 +usbus1: 12Mbps Full Speed USB v1.0 +usbus2: 12Mbps Full Speed USB v1.0 +usbus3: 480Mbps High Speed USB v2.0 +ugen0.1: <Intel> at usbus0 +uhub0: <Intel UHCI root HUB, class 9/0, rev 1.00/1.00, addr 1> on usbus0 +ugen1.1: <Intel> at usbus1 +uhub1: <Intel UHCI root HUB, class 9/0, rev 1.00/1.00, addr 1> on usbus1 +ugen2.1: <Intel> at usbus2 +uhub2: <Intel UHCI root HUB, class 9/0, rev 1.00/1.00, addr 1> on usbus2 +ugen3.1: <Intel> at usbus3 +uhub3: <Intel EHCI root HUB, class 9/0, rev 2.00/1.00, addr 1> on usbus3 +uhub0: 2 ports with 2 removable, self powered +uhub1: 2 ports with 2 removable, self powered +uhub2: 2 ports with 2 removable, self powered +uhub3: 6 ports with 6 removable, self powered +ugen2.2: <vendor 0x0b97> at usbus2 +uhub8: <vendor 0x0b97 product 0x7761, class 9/0, rev 1.10/1.10, addr 2> on usbus2 +ugen1.2: <Microsoft> at usbus1 +ada0 at ahcich0 bus 0 scbus1 target 0 lun 0 +ada0: <Hitachi HTS543225L9SA00 FBEOC43C> ATA-8 SATA 1.x device +ada0: 150.000MB/s transfers (SATA 1.x, UDMA6, PIO 8192bytes) +ada0: Command Queueing enabled +ada0: 238475MB (488397168 512 byte sectors: 16H 63S/T 16383C) +ada0: Previously was known as ad4 +ums0: <Microsoft Microsoft 3-Button Mouse with IntelliEyeTM, class 0/0, rev 1.10/3.00, addr 2> on usbus1 +SMP: AP CPU #1 Launched! +cd0 at ahcich1 bus 0 scbus2 target 0 lun 0 +cd0: <TEAC DV-W28S-RT 7.0C> Removable CD-ROM SCSI-0 device +cd0: 150.000MB/s transfers (SATA 1.x, ums0: 3 buttons and [XYZ] coordinates ID=0 +UDMA2, ATAPI 12bytes, PIO 8192bytes) +cd0: cd present [1 x 2048 byte records] +ugen0.2: <Microsoft> at usbus0 +ukbd0: <Microsoft Natural Ergonomic Keyboard 4000, class 0/0, rev 2.00/1.73, addr 2> on usbus0 +kbd2 at ukbd0 +uhid0: <Microsoft Natural Ergonomic Keyboard 4000, class 0/0, rev 2.00/1.73, addr 2> on usbus0 +Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> + </figure> + + <para>Check the probe results carefully to make sure that &os; + found all the devices you expected. If a device was not + found, then it will not be listed. <link + linkend="kernelconfig-modules">Kernel modules</link> allows + you to add in support for devices which are not in the + <filename>GENERIC</filename> kernel.</para> + + <para>After the procedure of device probing, you will see + <xref linkend="bsdinstall-choose-mode">. The install media + can be used in three ways: to install &os;, as a "live CD", or + to simply access a &os; shell. Use the arrow keys to choose + an option, and <keycap>Enter</keycap> to select.</para> + + <figure id="bsdinstall-choose-mode"> + <title>Selecting Installation Media Mode</title> + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-choose-mode" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Selecting <guibutton>[ Install ]</guibutton> + here will enter the installer.</para> + </sect2> + </sect1> + + <sect1 id="using-bsdinstall"> + <title>Introducing <application>bsdinstall</application></title> + + <para><application>bsdinstall</application> is a text-based &os; + installer program written by &a.nwhitehorn; and introduced in + 2011 for &os; 9.0.</para> + + <note> + <para>&a.kmoore;'s <application>pc-sysinstall</application> is + included with <ulink url="http://pcbsd.org">PC-BSD</ulink>, + and can also be used to <ulink + url="http://wiki.pcbsd.org/index.php/Use_PC-BSD_Installer_to_Install_FreeBSD"> + install &os;</ulink>. Although sometimes confused with + <application>bsdinstall</application>, the two are not + related.</para> + </note> + + <para>The <application>bsdinstall</application> menu system is + controlled by the arrow keys, <keycap>Enter</keycap>, + <keycap>Tab</keycap>, <keycap>Space</keycap>, and other + keys.</para> + + <sect2 id="bsdinstall-keymap"> + <title>Selecting the Keymap Menu</title> + + <para>Depending on the system console being used, + <application>bsdinstall</application> may initially prompt to + select a non-default keyboard layout.</para> + + <figure id="bsdinstall-keymap-select-default"> + <title>Keymap Selection</title> + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-keymap-select-default" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>If <guibutton>[ YES ]</guibutton> is selected, + the following keyboard selection screen will be displayed. + Otherwise, this selection menu will not be displayed, and a + default keyboard mapping will be used.</para> + + <figure id="bsdinstall-config-keymap"> + <title>Selecting Keyboard Menu</title> + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-config-keymap" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Select the keymap that most closely represents the mapping + of the keyboard attached to the system, using the up/down + arrow keys and pressing <keycap>Enter</keycap>.</para> + + <note> + <para>Pressing <keycap>Esc</keycap> will use the default + keymap. <guimenuitem>United States of America + ISO-8859-1</guimenuitem> is also a safe option if the + choice of keymap is not clear.</para> + </note> + </sect2> + + <sect2 id="bsdinstall-hostname"> + <title>Setting the Hostname</title> + + <para>Next, <application>bsdinstall</application> will prompt + for the hostname to be given to the newly installed + system.</para> + + <figure id="bsdinstall-config-hostname"> + <title>Setting the Hostname</title> + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-config-hostname" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The entered hostname should be a fully-qualified hostname, + such as + <hostid role="fqdn">machine3.example.com</hostid></para> + </sect2> + + <sect2 id="bsdinstall-components"> + <title>Selecting Components to Install</title> + + <para>Next, <application>bsdinstall</application> will prompt to + select optional components to install.</para> + + <figure id="bsdinstall-config-components"> + <title>Selecting Components to Install</title> + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-config-components" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Deciding which components to install will depend largely + on the intended use of the system and the amount of disk space + available. The &os; Kernel and userland (collectively the + <quote>base system</quote>) are always installed.</para> + + <para>Depending on the type of installation, some of these + components may not appear.</para> + + <itemizedlist> + <title>Optional Components</title> + + <listitem> + <para><literal>doc</literal> - Additional documentation, + mostly of historical interest. Documentation provided by + the &os; Documentation Project may be installed + later.</para> + </listitem> + + <listitem> + <para><literal>games</literal> - Several traditional BSD + games, including <application>fortune</application>, + <application>rot13</application>, and others.</para> + </listitem> + + <listitem> + <para><literal>lib32</literal> - Compatibility libraries for + running 32-bit applications on a 64-bit version of + &os;.</para> + </listitem> + + <listitem> + <para><literal>ports</literal> - The &os; Ports + Collection.</para> + + <para>The ports collection is an easy and convenient way to + install software. The Ports Collection does not contain + the source code necessary to compile the software. + Instead, it is a collection of files which automates the + downloading, compiling and installation of third-party + software packages. <xref linkend="ports"> discusses how + to use the ports collection.</para> + + <warning> + <para>The installation program does not check to see if + you have adequate space. Select this option only if you + have adequate hard disk space. As of &os; 9.0, the + &os; Ports Collection takes up about &ports.size; of + disk space. You can safely assume a larger value for + more recent versions of &os;.</para> + </warning> + </listitem> + + <listitem> + <para><literal>src</literal> - System source code.</para> + + <para>&os; comes with full source code for both the kernel + and the userland. Although not required for the majority + of applications, it may be required to build certain + software supplied as source (for example, device drivers + or kernel modules), or for developing &os; itself.</para> + + <para>The full source tree requires 1 GB of disk space, + and recompiling the entire &os; system requires an + additional 5 GB of space.</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="bsdinstall-netinstall"> + <title>Installing from the Network</title> + + <para>The <emphasis>bootonly</emphasis> installation media does + not hold copies of the installation files. When a + <emphasis>bootonly</emphasis> installation method is used, the + files must be retrieved over a network connection as they are + needed.</para> + + <figure id="bsdinstall-netinstall-notify"> + <title>Installing from the Network</title> + + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-netinstall-files" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>After the network connection has been configured as shown in + <xref linkend="bsdinstall-config-network-dev">, a mirror site is + selected. Mirror sites cache copies of the &os; files. Choose + a mirror site located in the same region of the world as the + computer on which &os; is being installed. Files can be + retrieved more quickly when the mirror is close to the target + computer, and installation time will be reduced.</para> + + <figure id="bsdinstall-netinstall-mirror"> + <title>Choosing a Mirror</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-netinstall-mirrorselect" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Installation will continue as if the installation files + were located on local media.</para> + </sect1> + + <sect1 id="bsdinstall-partitioning"> + <title>Allocating Disk Space</title> + + <para>There are three ways to allocate disk space for &os;. + <emphasis>Guided</emphasis> partitioning automatically sets up + disk partitions, while <emphasis>Manual</emphasis> partitioning + allows advanced users to create customized partitions. Finally, + there's the option of starting a shell where command-line + programs like &man.gpart.8;, &man.fdisk.8;, and &man.bsdlabel.8; + can be used directly.</para> + <!-- WB: mention ZFS here? --> + + <figure id="bsdinstall-part-guided-manual"> + <title>Selecting Guided or Manual Partitioning</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-part-guided-manual" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <sect2 id="bsdinstall-part-guided"> + <title>Guided Partitioning</title> + + <para>If multiple disks are connected, choose the one where &os; + is to be installed.</para> + + <figure id="bsdinstall-part-guided-disk"> + <title>Selecting from Multiple Disks</title> + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-part-guided-disk" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The entire disk can be allocated to &os;, or just a + portion of it. If + <guibutton>[ Entire Disk ]</guibutton> is + chosen, a general partition layout filling the whole disk is + created. Selecting + <guibutton>[ Partition ]</guibutton> creates a + partition layout in unused space on the disk.</para> + + <figure id="bsdinstall-part-entire-part"> + <title>Selecting Entire Disk or Partition</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-part-entire-part" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>After the partition layout has been created, review it + carefully for accuracy. If a mistake has been made, selecting + <guibutton>[ Revert ]</guibutton> will reset the + partitions as they were previously, or + <guibutton>[ Auto ]</guibutton> will recreate the + automatic &os; partitions. Partitions can be manually + created, modified, or deleted. When the partitioning is + correct, select <guibutton>[ Finish ]</guibutton> to + continue with the installation.</para> + + <figure id="bsdinstall-part-review"> + <title>Review Created Partitions</title> + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-part-review" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + </sect2> + + <sect2 id="bsdinstall-part-manual"> + <title>Manual Partitioning</title> + + <para>Manual partitioning goes straight to the partition + editor.</para> + + <figure id="bsdinstall-part-manual-create"> + <title>Manually Create Partitions</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-part-manual-create" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Highlighting a drive (<devicename>ada0</devicename> in + this example) and selecting + <guibutton>[ Create ]</guibutton> displays a menu + for choosing the type of <firstterm>partitioning + scheme</firstterm>.</para> + + <figure id="bsdinstall-part-manual-partscheme"> + <title>Manually Create Partitions</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-part-manual-partscheme" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para><acronym>GPT</acronym> partitioning is usually the most + appropriate choice for PC-compatible computers. Older PC + operating systems that are not compatible with + <acronym>GPT</acronym> may require <acronym>MBR</acronym> + partitioning instead. The other partitioning schemes are + generally used for uncommon or older computer systems.</para> + + <table frame="none" rowsep="1" pgwide="1"> + <title>Partitioning Schemes</title> + + <tgroup cols="2" align="left"> + <thead> + <row> + <entry align="left">Abbreviation</entry> + <entry align="left">Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry>APM</entry> + <entry><ulink + url="http://support.apple.com/kb/TA21692">Apple + Partition Map, used by &powerpc; + &macintosh;.</ulink></entry> + </row> + + <row> + <entry>BSD</entry> + <entry>BSD Labels without an MBR, sometimes called + "dangerously dedicated mode". See + &man.bsdlabel.8;.</entry> + </row> + + <row> + <entry>GPT</entry> + <entry><ulink + url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID + Partition Table.</ulink></entry> + </row> + + <row> + <entry>MBR</entry> + <entry><ulink + url="http://en.wikipedia.org/wiki/Master_boot_record">Master + Boot Record.</ulink></entry> + </row> + + <row> + <entry>PC98</entry> + <entry><ulink + url="http://en.wikipedia.org/wiki/Pc9801">MBR + variant, used by NEC PC-98 + computers.</ulink></entry> + </row> + + <row> + <entry>VTOC8</entry> + <entry>Volume Table Of Contents, used by Sun SPARC64 and + UltraSPARC computers.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>After the partitioning scheme has been selected and + created, selecting <guibutton>[ Create ]</guibutton> + again will create new partitions.</para> + + <figure id="bsdinstall-part-manual-addpart"> + <title>Manually Create Partitions</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-part-manual-addpart" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>A standard &os; <acronym>GPT</acronym> installation uses + at least three partitions:</para> + + <itemizedlist> + <title>Standard &os; <acronym>GPT</acronym> Partitions</title> + + <listitem> + <para><literal>freebsd-boot</literal> - &os; boot code. + This partition must be first on the disk.</para> + </listitem> + + <listitem> + <para><literal>freebsd-ufs</literal> - A &os; UFS + filesystem.</para> + </listitem> + + <listitem> + <para><literal>freebsd-swap</literal> - &os; swap + space.</para> + </listitem> + </itemizedlist> + + <para>Multiple filesystem partitions can be used, and some + people may prefer a traditional layout with separate + partitions for the <filename>/</filename>, + <filename>/var</filename>, <filename>/tmp</filename>, and <filename>/usr</filename> + filesystems. See <xref + linkend="bsdinstall-part-manual-splitfs"> for an + example.</para> + + <para>See &man.gpart.8; for a complete list of available + <acronym>GPT</acronym> partition types.</para> + + <para>Size may be entered with common abbreviations: + <emphasis>K</emphasis> for kilobytes, <emphasis>M</emphasis> + for megabytes, or <emphasis>G</emphasis> for gigabytes.</para> + + <tip> + <para>Proper sector alignment provides the best performance, + and making partition sizes even multiples of 4K bytes helps + to ensure alignment on drives with either 512-byte or + 4K-byte sectors. Generally, using partition sizes that are + even multiples of 1M or 1G is the easiest way to make sure + every partition starts at an even multiple of 4K. One + exception: at present, the <emphasis>freebsd-boot</emphasis> + partition should be no larger than 512K due to boot code + limitations.</para> + </tip> + + <para>A mountpoint is needed if this partition will contain a + filesystem. If only a single UFS partition will be created, + the mountpoint should be <filename>/</filename>.</para> + + <para>A <firstterm>label</firstterm> is also requested. A label + is a name by which this partition will be known. Drive + names or numbers can change if the drive is connected to + a different controller or port, but the partition label does + not change. Referring to labels instead of drive names + and partition numbers in files like + <filename>/etc/fstab</filename> makes the system more tolerant + of changing hardware. GPT labels appear in + <filename>/dev/gpt/</filename> when a disk is attached. + Other partitioning schemes have different label + capabilities, and their labels appear in different directories + in <filename>/dev/</filename>.</para> + + <tip> + <para>Use a unique label on every filesystem to avoid + conflicts from identical labels. A few letters from the + computer's name, use, or location can be added to the label. + "labroot" or "rootfs-lab" for the UFS root partition on the + lab's computer, for example.</para> + </tip> + + <example id="bsdinstall-part-manual-splitfs"> + <title>Creating Traditional Split Filesystem + Partitions</title> + + <para>For a traditional partition layout where the + <filename>/</filename>, <filename>/var</filename>, + <filename>/tmp</filename>, and <filename>/usr</filename> + directories are separate filesystems on their own + partitions, create a GPT partitioning scheme, then create + the partitions as shown. Partition sizes shown are typical + for a 20G target disk. If more space is available on the + target disk, larger swap or <filename>/var</filename> + partitions may be useful. Labels shown here are prefixed + with <literal>ex</literal> for "example", but readers + should use other unique label values as described + above.</para> + + <informaltable frame="none"> + <tgroup cols="4"> + <thead> + <row> + <entry>Partition Type</entry> + <entry>Size</entry> + <entry>Mountpoint</entry> + <entry>Label</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>freebsd-boot</literal></entry> + <entry><literal>512K</literal></entry> + </row> + + <row> + <entry><literal>freebsd-ufs</literal></entry> + <entry><literal>2G</literal></entry> + <entry><filename>/</filename></entry> + <entry><literal>exrootfs</literal></entry> + </row> + + <row> + <entry><literal>freebsd-swap</literal></entry> + <entry><literal>4G</literal></entry> + <entry></entry> + <entry><literal>exswap</literal></entry> + </row> + + <row> + <entry><literal>freebsd-ufs</literal></entry> + <entry><literal>2G</literal></entry> + <entry><filename>/var</filename></entry> + <entry><literal>exvarfs</literal></entry> + </row> + + <row> + <entry><literal>freebsd-ufs</literal></entry> + <entry><literal>1G</literal></entry> + <entry><filename>/tmp</filename></entry> + <entry><literal>extmpfs</literal></entry> + </row> + + <row> + <entry><literal>freebsd-ufs</literal></entry> + <entry>accept the default (remainder of the + disk)</entry> + <entry><filename>/usr</filename></entry> + <entry><literal>exusrfs</literal></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + + <para>After the custom partitions have been created, select + <guibutton>[ Finish ]</guibutton> to continue with + the installation.</para> + </sect2> + </sect1> + + <sect1 id="bsdinstall-final-warning"> + <title>Committing to the Installation</title> + + <para>This is the last chance for aborting the installation to + prevent changes to the hard drive.</para> + + <figure id="bsdinstall-final-confirmation"> + <title>Final Confirmation</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-final-confirmation" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Select <guibutton>[ Commit ]</guibutton> and press + <keycap>Enter</keycap> to proceed. If changes need to be made, + select <guibutton>[ Back ]</guibutton> to return to + the partition editor. + <guibutton>[ Revert & Exit ] + </guibutton> will exit the installer without making any changes + to the hard drive.</para> + + <para>Installation time will vary depending on the distributions + chosen, installation media, and speed of the computer. + There will be a series of + messages displayed indicating progress.</para> + + <para>Firstly, the installer will write the partitions to the + disk, and perform a <command>newfs</command> to initialise the + partitions.</para> + + <para>If doing a network install, + <application>bsdinstall</application> will then proceed to + download the required distribution files.</para> + <!-- XXXGA: What does it do if fetch fails? --> + + <figure id="bsdinstall-distfile-fetching"> + <title>Fetching Distribution Files</title> + + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-distfile-fetching" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Next, the integrity of the distribution files is verified, + to ensure they have not been corrupted during download or + misread from the installation media.</para> + + <figure id="bsdinstall-distfile-verify"> + <title>Verifying Distribution Files</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-distfile-verifying" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Finally, the verified distribution files are extracted to + the disk.</para> + + <figure id="bsdinstall-distfile-extract"> + <title>Extracting Distribution Files</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-distfile-extracting" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Once all requested distribution files have been extracted, + <application>bsdinstall</application> will then drop straight + into the post-installation configuration tasks (see + <xref linkend="bsdinstall-post">).</para> + </sect1> + + <sect1 id="bsdinstall-post"> + <title>Post-Installation</title> + + <para>Configuration of various options follows a successful + installation of &os;. An option can be configured by + re-entering the configuration options from the final menu before + booting into the newly installed &os; system.</para> + + <sect2 id="bsdinstall-post-root"> + <title>Setting the <username>root</username> Password</title> + + <para>The <username>root</username> password must be set. Note + that while entering the password, the characters being typed + are not displayed on the screen. After the password has been + entered, it must be entered again. This helps prevent typing + errors.</para> + + <figure id="bsdinstall-post-set-root-passwd"> + <title>Setting the <username>root</username> Password</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-post-root-passwd" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>After the password has been successfully entered, the + installation will continue.</para> + </sect2> + + <sect2 id="bsdinstall-config-network-dev"> + <title>Configuring Network Interfaces</title> + + <note> + <para>Network configuration will be skipped if it has already + been done as part of a <emphasis>bootonly</emphasis> + installation.</para> + </note> + + <para>A list of all the network interfaces found on the computer + is shown next. Select one to be configured.</para> + + <figure id="bsdinstall-configure-net-interface"> + <title>Choose a Network Interface</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-network-interface" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <sect3 id="bsdinstall-configure-net-wireless"> + <title>Configuring a Wireless Network Interface</title> + + <para>If a wireless network interface is chosen, wireless + identification and security parameters must be entered to + allow it to connect to the network.</para> + + <para>Wireless networks are identified by a Service Set + Identifier, or <acronym role="Service Set Identifier"> + SSID</acronym>. The <acronym role="Service Set + Identifier">SSID</acronym> is a short, unique name given to + each network.</para> + + <para>Most wireless networks encrypt transmitted data to + protect information from unauthorized viewing. <acronym + role="Wi-Fi Protected Access II">WPA2</acronym> encryption + is strongly recommended. Older encryption types, like + <acronym role="Wired Equivalent Privacy">WEP</acronym>, + offer very little security.</para> + + <para>The first step in connecting to a wireless network is to + scan for wireless access points.</para> + + <figure id="bsdinstall-wireless-scan"> + <title>Scanning for Wireless Access Points</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-wireless-scan" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para><acronym role="Service Set Identifiers">SSIDs</acronym> + found during the scan are listed, followed by a description + of the encryption types available for that network. If the + desired <acronym role="Service Set + Identifier">SSID</acronym> doesn't appear in the list, + select <guibutton>[ Rescan ]</guibutton> to scan + again. If the desired network still does not appear, check + for problems with antenna connections or try moving the + computer closer to the access point. Rescan after each + change is made.</para> + + <figure id="bsdinstall-wireless-accesspoints"> + <title>Choosing a Wireless Network</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-wireless-accesspoints" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The encryption information for connecting to the + selected wireless network is entered after selecting the + network. With <acronym role="Wi-Fi Protected Access + II">WPA2</acronym>, only a password (also known as the + Pre-Shared Key, or <acronym role="Pre-Shared + Key">PSK</acronym>) is needed. Characters typed into the + input box are shown as asterisks for security.</para> + + <figure id="bsdinstall-wireless-wpa2"> + <title>WPA2 Setup</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-wireless-wpa2setup" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Network configuration continues after selection of the + wireless network and entry of the connection + information.</para> + </sect3> + + <sect3 id="bsdinstall-ipv4"> + <title>Configuring IPv4 Networking</title> + + <para>Choose whether IPv4 networking is to be used. This is + the most common type of network connection.</para> + + <figure id="bsdinstall-configure-net-ipv4"> + <title>Choose IPv4 Networking</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>There are two methods of IPv4 configuration. + <firstterm><acronym role="Dynamic Host Configuration + Protocol">DHCP</acronym></firstterm> will automatically + configure the network interface correctly, and is the + preferred method. <firstterm>Static</firstterm> + configuration requires manual entry of network + information.</para> + + <note> + <para>Do not enter random network information, as it will + not work. Obtain the information shown in + <xref linkend="bsdinstall-collect-network-information"> + from the network administrator or service provider.</para> + </note> + + <sect4 id="bsdinstall-net-ipv4-dhcp-config"> + <title>IPv4 DHCP Network Configuration</title> + + <para>If a DHCP server is available, select + <guibutton>[ Yes ]</guibutton> to automatically + configure the network interface.</para> + + <figure id="bsdinstall-net-ipv4-dhcp"> + <title>Choose IPv4 DHCP Configuration</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4-dhcp" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + </sect4> + + <sect4 id="bsdinstall-net-ipv4-static-config"> + <title>IPv4 Static Network Configuration</title> + + <para>Static configuration of the network interface requires + entry of some IPv4 information.</para> + + <figure id="bsdinstall-net-ipv4-static"> + <title>IPv4 Static Configuration</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4-static" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <itemizedlist> + <listitem> + <para><literal>IP Address</literal> - The + manually-assigned IPv4 address to be assigned to this + computer. This address must be unique and not already + in use by another piece of equipment on the local + network.</para> + </listitem> + + <listitem> + <para><literal>Subnet Mask</literal> - The subnet mask + used for the local network. Typically, this is + <literal>255.255.255.0</literal>.</para> + </listitem> + + <listitem> + <para><literal>Default Router</literal> - The IP address + of the default router on this network. Usually this + is the address of the router or other network + equipment that connects the local network to the + Internet. Also known as the <emphasis>default + gateway</emphasis>.</para> + </listitem> + </itemizedlist> + </sect4> + </sect3> + + <sect3 id="bsdinstall-ipv6"> + <title>Configuring IPv6 Networking</title> + + <para>IPv6 is a newer method of network configuration. If + IPv6 is available and desired, choose + <guibutton>[ Yes ]</guibutton> to select + it.</para> + + <figure id="bsdinstall-net-ipv6"> + <title>Choose IPv6 Networking</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-network-interface-ipv6" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>IPv6 also has two methods of configuration. + <firstterm><acronym role="StateLess Address + AutoConfiguration">SLAAC</acronym> </firstterm>, or + <emphasis>StateLess Address AutoConfiguration</emphasis>, + will automatically configure the network interface + correctly. <firstterm>Static</firstterm> configuration + requires manual entry of network information.</para> + + <sect4 id="bsdinstall-net-ipv6-slaac-config"> + <title>IPv6 Stateless Address Autoconfiguration</title> + + <para><acronym>SLAAC</acronym> allows an IPv6 network + component to request autoconfiguration information from a + local router. See <ulink + url="http://tools.ietf.org/html/rfc4862">RFC4862</ulink> + for more information.</para> + + <figure id="bsdinstall-net-ipv6-slaac"> + <title>Choose IPv6 SLAAC Configuration</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-network-interface-slaac" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + </sect4> + + <sect4 id="bsdinstall-net-ipv6-static-config"> + <title>IPv6 Static Network Configuration</title> + + <para>Static configuration of the network interface requires + entry of the IPv6 configuration information.</para> + + <figure id="bsdinstall-net-ipv6-static"> + <title>IPv6 Static Configuration</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-network-interface-ipv6-static" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <itemizedlist> + <listitem> + <para><literal>IPv6 Address</literal> - The + manually-assigned <acronym>IP</acronym> address to be + assigned to this computer. This address must be + unique and not already in use by another piece of + equipment on the local network.</para> + </listitem> + + <listitem> + <para><literal>Default Router</literal> - The IPv6 + address of the default router on this network. + Usually this is the address of the router or other + network equipment that connects the local network to + the Internet. Also known as the <emphasis>default + gateway</emphasis>.</para> + </listitem> + </itemizedlist> + </sect4> + </sect3> + + <sect3 id="bsdinstall-net-dns"> + <title>Configuring <acronym role="Domain Name + System">DNS</acronym></title> + + <para>The <firstterm>Domain Name System</firstterm> (or + <emphasis><acronym role="Domain Name + System">DNS</acronym></emphasis>) Resolver converts + hostnames to and from network addresses. If + <acronym>DHCP</acronym> or <acronym>SLAAC</acronym> was used + to autoconfigure the network interface, the Resolver + Configuration values may already be present. Otherwise, + enter the local network's domain name in the Search field. + <acronym>DNS</acronym> #1 and <acronym>DNS</acronym> #2 are + the <acronym>IP</acronym> addresses for the local + <acronym>DNS</acronym> servers. At least one + <acronym>DNS</acronym> server is required.</para> + + <figure id="bsdinstall-net-dns-config"> + <title>DNS Configuration</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-configure-network-ipv4-dns" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + </sect3> + </sect2> + + <sect2 id="bsdinstall-timezone"> + <title>Setting the Time Zone</title> + + <para>Setting the time zone for your machine will allow it to + automatically correct for any regional time changes and + perform other time zone related functions properly.</para> + + <para>The example shown is for a machine located in the Eastern + time zone of the United States. Your selections will vary + according to your geographical location.</para> + + <figure id="bsdinstall-local-utc"> + <title>Select Local or UTC Clock</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-set-clock-local-utc" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Select <guibutton>[ Yes ]</guibutton> + or <guibutton>[ No ]</guibutton> according to how + the machine's clock is configured and press + <keycap>Enter</keycap>. If you don't know whether the system + uses UTC or local time, select + <guibutton>[ No ]</guibutton> to choose the more + commonly-used local time.</para> + + <figure id="bsdinstall-timezone-region"> + <title>Select a Region</title> + + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-timezone-region" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The appropriate region is selected using the arrow keys + and then pressing <keycap>Enter</keycap>.</para> + + <figure id="bsdinstall-timezone-country"> + <title>Select a Country</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-timezone-country" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Select the appropriate country using the arrow keys + and press <keycap>Enter</keycap>.</para> + + <figure id="bsdinstall-timezone-zone"> + <title>Select a Time Zone</title> + + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-timezone-zone" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The appropriate time zone is selected using the arrow + keys and pressing <keycap>Enter</keycap>.</para> + + <figure id="bsdinstall-timezone-confirmation"> + <title>Confirm Time Zone</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-timezone-confirm" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Confirm the abbreviation for the time zone is correct. + If it looks okay, press <keycap>Enter</keycap> to continue + with the post-installation configuration.</para> + </sect2> + + <sect2 id="bsdinstall-sysconf"> + <title>Selecting Services to Enable</title> + + <para>Additional system services which will be started at boot + can be enabled. All of these services are optional.</para> + + <figure id="bsdinstall-config-serv"> + <title>Selecting Additional Services to Enable</title> + + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-config-services" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <itemizedlist> + <title>Additional Services</title> + + <listitem> + <para><literal>sshd</literal> - Secure Shell + (<acronym role="Secure Shell">SSH</acronym>) daemon for + secure remote access.</para> + </listitem> + + <listitem> + <para><literal>moused</literal> - Provides mouse usage + within the system console.</para> + </listitem> + + <listitem> + <para><literal>ntpd</literal> - Network Time Protocol + (<acronym role="Network Time Protocol">NTP</acronym>) + daemon for automatic clock synchronization.</para> + </listitem> + + <listitem> + <para><literal>powerd</literal> - System power control + utility for power control and energy saving.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2 id="bsdinstall-crashdump"> + <title>Enabling Crash Dumps</title> + + <para><application>bsdinstall</application> will prompt if crash + dumps should be enabled on the target system. Enabling crash + dumps can be very useful in debugging issues with the system, + so users are encouraged to enable crash dumps whenever + possible. Select <guibutton>[ Yes ]</guibutton> to + enable crash dumps, or <guibutton>[ No ]</guibutton> + to proceed without crash dumps enabled.</para> + + <figure id="bsdinstall-config-crashdump"> + <title>Enabling Crash Dumps</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-config-crashdump" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + </sect2> + + <sect2 id="bsdinstall-addusers"> + <title>Add Users</title> + + <para>Adding at least one user during the installation allows + the system to be used without being logged in as + <username>root</username>. When logged in as + <username>root</username>, there are essentially no limits or + protection on what can be done. Logging in as a normal user + is safer and more secure.</para> + + <para>Select <guibutton>[ Yes ]</guibutton> to add new + users.</para> + + <figure id="bsdinstall-add-user1"> + <title>Add User Accounts</title> + + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-adduser1" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Enter the information for the user to be added.</para> + + <figure id="bsdinstall-add-user2"> + <title>Enter User Information</title> + + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-adduser2" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <itemizedlist> + <title>User Information</title> + + <listitem> + <para><literal>Username</literal> - The name the user will + enter to log in. Typically the first letter of their + first name combined with their last name.</para> + </listitem> + + <listitem> + <para><literal>Full name</literal> - The user's full + name.</para> + </listitem> + + <listitem> + <para><literal>Uid</literal> - User ID. Typically, this + is left blank so the system will assign a value.</para> + </listitem> + + <listitem> + <para><literal>Login group</literal> - The user's group. + Typically left blank to accept the default.</para> + </listitem> + + <listitem> + <para><literal>Invite <replaceable>user</replaceable> into + other groups?</literal> - Additional groups to which the + user will be added as a member.</para> + </listitem> + + <listitem> + <para><literal>Login class</literal> - Typically left blank + for the default.</para> + </listitem> + + <listitem> + <para><literal>Shell</literal> - The interactive shell for + this user. In the example, &man.csh.1; has been + chosen.</para> + </listitem> + + <listitem> + <para><literal>Home directory</literal> - The user's home + directory. The default is usually correct.</para> + </listitem> + + <listitem> + <para><literal>Home directory permissions</literal> - + Permissions on the user's home directory. The default is + usually correct.</para> + </listitem> + + <listitem> + <para><literal>Use password-based authentication?</literal> + - Typically "yes".</para> + </listitem> + + <listitem> + <para><literal>Use an empty password?</literal> - + Typically "no".</para> + </listitem> + + <listitem> + <para><literal>Use a random password?</literal> - Typically + "no".</para> + </listitem> + + <listitem> + <para><literal>Enter password</literal> - The actual + password for this user. Characters typed will not show on + the screen.</para> + </listitem> + + <listitem> + <para><literal>Enter password again</literal> - The password + must be typed again for verification.</para> + </listitem> + + <listitem> + <para><literal>Lock out the account after + creation?</literal> - Typically "no".</para> + </listitem> + </itemizedlist> + + <para>After entering everything, a summary is shown, and the + system asks if it is correct. If a mistake was made during + entry, enter <literal>no</literal> and try again. If + everything is correct, enter <literal>yes</literal> to create + the new user.</para> + + <figure id="bsdinstall-add-user3"> + <title>Exit User and Group Management</title> + + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-adduser3" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>If there are more users to add, answer the "Add another + user?" question with <literal>yes</literal>. Enter + <literal>no</literal> to finish adding users and continue the + installation.</para> + + <para>For more information on adding users and user management, + see <xref linkend="users">.</para> + </sect2> + + <sect2 id="bsdinstall-final-conf"> + <title>Final Configuration</title> + + <para>After everything has been installed and configured, a + final chance is provided to modify settings.</para> + + <figure id="bsdinstall-final-config"> + <title>Final Configuration</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-finalconfiguration" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Use this menu to make any changes or do any additional + configuration before completing the installation.</para> + + <itemizedlist> + <title>Final Configuration Options</title> + + <listitem> + <para><literal>Add User</literal> - Described in + <xref linkend="bsdinstall-addusers">.</para> + </listitem> + + <listitem> + <para><literal>Root Password</literal> - Described in + <xref linkend="bsdinstall-post-root">.</para> + </listitem> + + <listitem> + <para><literal>Hostname</literal> - Described in + <xref linkend="bsdinstall-hostname">.</para> + </listitem> + + <listitem> + <para><literal>Network</literal> - Described in + <xref linkend="bsdinstall-config-network-dev">.</para> + </listitem> + + <listitem> + <para><literal>Services</literal> - Described in + <xref linkend="bsdinstall-sysconf">.</para> + </listitem> + + <listitem> + <para><literal>Time Zone</literal> - Described in + <xref linkend="bsdinstall-timezone">.</para> + </listitem> + + <listitem> + <para><literal>Handbook</literal> - Download and install the + &os; Handbook (which is what you are reading now).</para> + </listitem> + </itemizedlist> + + <para>After any final configuration is complete, select + <guibutton>Exit</guibutton> to leave the installation.</para> + + <figure id="bsdinstall-final-modification-shell"> + <title>Manual Configuration</title> + + <mediaobject> + <imageobject> + <imagedata + fileref="bsdinstall/bsdinstall-final-modification-shell" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para><application>bsdinstall</application> will prompt if there + are any additional configuration that needs to be done before + rebooting into the new system. Select + <guibutton>[ Yes ]</guibutton> to exit to a shell + within the new system, or + <guibutton>[ No ]</guibutton> to proceed to the last + step of the installation.</para> + + <figure id="bsdinstall-final-main"> + <title>Complete the Installation</title> + + <mediaobject> + <imageobject> + <imagedata fileref="bsdinstall/bsdinstall-mainexit" + format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>If further configuration or special setup is needed, + selecting <guibutton>[ Live CD ]</guibutton> + will boot the install media into Live CD mode.</para> + + <para>When the installation is complete, select + <guibutton>[ Reboot ]</guibutton> to reboot the + computer and start the new &os; system. Don't forget to + remove the &os; install CD, DVD, or USB memory stick, or the + computer may boot from it again.</para> + </sect2> + + <sect2 id="bsdinstall-freebsdboot"> + <title>&os; Booting and Shutdown</title> + + <sect3 id="bsdinstall-freebsdboot-i386"> + <title>&os;/&arch.i386; Booting</title> + + <para>As &os; boots, many informational messages are + displayed. Most will scroll off the screen; this is normal. + After the system finishes booting, a login prompt is + displayed. Messages that scrolled off the screen can be + reviewed by pressing <keycap>Scroll-Lock</keycap> to turn on + the <emphasis>scroll-back buffer</emphasis>. The + <keycap>PgUp</keycap>, <keycap>PgDn</keycap>, and arrow keys + can be used to scroll back through the messages. Pressing + <keycap>Scroll-Lock</keycap> again unlocks the display and + returns to the normal screen.</para> + + <para>At the <prompt>login:</prompt> prompt, enter the + username added during the installation, + <username>asample</username> in the example. Avoid logging + in as <username>root</username> except when + necessary.</para> + + <para>The scroll-back buffer examined above is limited in + size, so not all of the messages may have been visible. + After logging in, most of them can be seen from the command + line by typing <command>dmesg | less</command> at the + prompt. Press <keycap>q</keycap> to return to the command + line after viewing.</para> + + <para>Typical boot messages (version information + omitted):</para> + + <screen>Copyright (c) 1992-2011 The FreeBSD Project. +Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994 + The Regents of the University of California. All rights reserved. +FreeBSD is a registered trademark of The FreeBSD Foundation. + + root@farrell.cse.buffalo.edu:/usr/obj/usr/src/sys/GENERIC amd64 +CPU: Intel(R) Core(TM)2 Duo CPU E8400 @ 3.00GHz (3007.77-MHz K8-class CPU) + Origin = "GenuineIntel" Id = 0x10676 Family = 6 Model = 17 Stepping = 6 + Features=0x783fbff<FPU,VME,DE,PSE,TSC,MSR,PAE,MCE,CX8,APIC,SEP,MTRR,PGE,MCA,CMOV,PAT,PSE36,MMX,FXSR,SSE,SSE2> + Features2=0x209<SSE3,MON,SSSE3> + AMD Features=0x20100800<SYSCALL,NX,LM> + AMD Features2=0x1<LAHF> +real memory = 536805376 (511 MB) +avail memory = 491819008 (469 MB) +Event timer "LAPIC" quality 400 +ACPI APIC Table: <VBOX VBOXAPIC> +ioapic0: Changing APIC ID to 1 +ioapic0 <Version 1.1> irqs 0-23 on motherboard +kbd1 at kbdmux0 +acpi0: <VBOX VBOXXSDT> on motherboard +acpi0: Power Button (fixed) +acpi0: Sleep Button (fixed) +Timecounter "ACPI-fast" frequency 3579545 Hz quality 900 +acpi_timer0: <32-bit timer at 3.579545MHz> port 0x4008-0x400b on acpi0 +cpu0: <ACPI CPU> on acpi0 +pcib0: <ACPI Host-PCI bridge> port 0xcf8-0xcff on acpi0 +pci0: <ACPI PCI bus> on pcib0 +isab0: <PCI-ISA bridge> at device 1.0 on pci0 +isa0: <ISA bus> on isab0 +atapci0: <Intel PIIX4 UDMA33 controller> port 0x1f0-0x1f7,0x3f6,0x170-0x177,0x376,0xd000-0xd00f at device 1.1 on pci0 +ata0: <ATA channel 0> on atapci0 +ata1: <ATA channel 1> on atapci0 +vgapci0: <VGA-compatible display> mem 0xe0000000-0xe0ffffff irq 18 at device 2.0 on pci0 +em0: <Intel(R) PRO/1000 Legacy Network Connection 1.0.3> port 0xd010-0xd017 mem 0xf0000000-0xf001ffff irq 19 at device 3.0 on pci0 +em0: Ethernet address: 08:00:27:9f:e0:92 +pci0: <base peripheral> at device 4.0 (no driver attached) +pcm0: <Intel ICH (82801AA)> port 0xd100-0xd1ff,0xd200-0xd23f irq 21 at device 5.0 on pci0 +pcm0: <SigmaTel STAC9700/83/84 AC97 Codec> +ohci0: <OHCI (generic) USB controller> mem 0xf0804000-0xf0804fff irq 22 at device 6.0 on pci0 +usbus0: <OHCI (generic) USB controller> on ohci0 +pci0: <bridge> at device 7.0 (no driver attached) +acpi_acad0: <AC Adapter> on acpi0 +atkbdc0: <Keyboard controller (i8042)> port 0x60,0x64 irq 1 on acpi0 +atkbd0: <AT Keyboard> irq 1 on atkbdc0 +kbd0 at atkbd0 +atkbd0: [GIANT-LOCKED] +psm0: <PS/2 Mouse> irq 12 on atkbdc0 +psm0: [GIANT-LOCKED] +psm0: model IntelliMouse Explorer, device ID 4 +attimer0: <AT timer> port 0x40-0x43,0x50-0x53 on acpi0 +Timecounter "i8254" frequency 1193182 Hz quality 0 +Event timer "i8254" frequency 1193182 Hz quality 100 +sc0: <System console> at flags 0x100 on isa0 +sc0: VGA <16 virtual consoles, flags=0x300> +vga0: <Generic ISA VGA> at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0 +atrtc0: <AT realtime clock> at port 0x70 irq 8 on isa0 +Event timer "RTC" frequency 32768 Hz quality 0 +ppc0: cannot reserve I/O port range +Timecounters tick every 10.000 msec +pcm0: measured ac97 link rate at 485193 Hz +em0: link state changed to UP +usbus0: 12Mbps Full Speed USB v1.0 +ugen0.1: <Apple> at usbus0 +uhub0: <Apple OHCI root HUB, class 9/0, rev 1.00/1.00, addr 1> on usbus0 +cd0 at ata1 bus 0 scbus1 target 0 lun 0 +cd0: <VBOX CD-ROM 1.0> Removable CD-ROM SCSI-0 device +cd0: 33.300MB/s transfers (UDMA2, ATAPI 12bytes, PIO 65534bytes) +cd0: Attempt to query device size failed: NOT READY, Medium not present +ada0 at ata0 bus 0 scbus0 target 0 lun 0 +ada0: <VBOX HARDDISK 1.0> ATA-6 device +ada0: 33.300MB/s transfers (UDMA2, PIO 65536bytes) +ada0: 12546MB (25694208 512 byte sectors: 16H 63S/T 16383C) +ada0: Previously was known as ad0 +Timecounter "TSC" frequency 3007772192 Hz quality 800 +Root mount waiting for: usbus0 +uhub0: 8 ports with 8 removable, self powered +Trying to mount root from ufs:/dev/ada0p2 [rw]... +Setting hostuuid: 1848d7bf-e6a4-4ed4-b782-bd3f1685d551. +Setting hostid: 0xa03479b2. +Entropy harvesting: interrupts ethernet point_to_point kickstart. +Starting file system checks: +/dev/ada0p2: FILE SYSTEM CLEAN; SKIPPING CHECKS +/dev/ada0p2: clean, 2620402 free (714 frags, 327461 blocks, 0.0% fragmentation) +Mounting local file systems:. +vboxguest0 port 0xd020-0xd03f mem 0xf0400000-0xf07fffff,0xf0800000-0xf0803fff irq 20 at device 4.0 on pci0 +vboxguest: loaded successfully +Setting hostname: machine3.example.com. +Starting Network: lo0 em0. +lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 + options=3<RXCSUM,TXCSUM> + inet6 ::1 prefixlen 128 + inet6 fe80::1%lo0 prefixlen 64 scopeid 0x3 + inet 127.0.0.1 netmask 0xff000000 + nd6 options=21<PERFORMNUD,AUTO_LINKLOCAL> +em0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=9b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM> + ether 08:00:27:9f:e0:92 + nd6 options=29<PERFORMNUD,IFDISABLED,AUTO_LINKLOCAL> + media: Ethernet autoselect (1000baseT <full-duplex>) + status: active +Starting devd. +Starting Network: usbus0. +DHCPREQUEST on em0 to 255.255.255.255 port 67 +DHCPACK from 10.0.2.2 +bound to 192.168.1.142 -- renewal in 43200 seconds. +add net ::ffff:0.0.0.0: gateway ::1 +add net ::0.0.0.0: gateway ::1 +add net fe80::: gateway ::1 +add net ff02::: gateway ::1 +ELF ldconfig path: /lib /usr/lib /usr/lib/compat /usr/local/lib +32-bit compatibility ldconfig path: /usr/lib32 +Creating and/or trimming log files. +Starting syslogd. +No core dumps found. +Clearing /tmp (X related). +Updating motd:. +Configuring syscons: blanktime. +Generating public/private rsa1 key pair. +Your identification has been saved in /etc/ssh/ssh_host_key. +Your public key has been saved in /etc/ssh/ssh_host_key.pub. +The key fingerprint is: +10:a0:f5:af:93:ae:a3:1a:b2:bb:3c:35:d9:5a:b3:f3 root@machine3.example.com +The key's randomart image is: ++--[RSA1 1024]----+ +| o.. | +| o . . | +| . o | +| o | +| o S | +| + + o | +|o . + * | +|o+ ..+ . | +|==o..o+E | ++-----------------+ +Generating public/private dsa key pair. +Your identification has been saved in /etc/ssh/ssh_host_dsa_key. +Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub. +The key fingerprint is: +7e:1c:ce:dc:8a:3a:18:13:5b:34:b5:cf:d9:d1:47:b2 root@machine3.example.com +The key's randomart image is: ++--[ DSA 1024]----+ +| .. . .| +| o . . + | +| . .. . E .| +| . . o o . . | +| + S = . | +| + . = o | +| + . * . | +| . . o . | +| .o. . | ++-----------------+ +Starting sshd. +Starting cron. +Starting background file system checks in 60 seconds. + +Thu Oct 6 19:15:31 MDT 2011 + +FreeBSD/amd64 (machine3.example.com) (ttyv0) + +login:</screen> + + <para>Generating the RSA and DSA keys may take some time on + slower machines. This happens only on the initial boot-up + of a new installation, and only if + <application>sshd</application> is set to start + automatically. Subsequent boots will be faster.</para> + + <para>&os; does not install graphical environments by default, + but many are available. See <xref linkend="x11"> for more + information.</para> + </sect3> + </sect2> + + <sect2 id="bsdinstall-shutdown"> + <title>&os; Shutdown</title> + + <para>Proper shutdown of a &os; computer helps protect data and + even hardware from damage. Do not just turn off the power. + If the user is a member of the <groupname>wheel</groupname> + group, become the superuser by typing <command>su</command> at + the command line and entering the <username>root</username> + password. Otherwise, log in as <username>root</username> and + use <command>shutdown -p now</command>. The system will close + down cleanly and turn itself off.</para> + + <para>The + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>Alt</keycap> + <keycap>Del</keycap> + </keycombo> + key combination can be used to reboot the system, but is not + recommended during normal operation.</para> + </sect2> + </sect1> + + <sect1 id="bsdinstall-install-trouble"> + <title>Troubleshooting</title> + + <indexterm> + <primary>installation</primary> + <secondary>troubleshooting</secondary> + </indexterm> + <para>The following section covers basic installation + troubleshooting, such as common problems people have + reported.</para> + + <sect2> + <title>What to Do If Something Goes Wrong</title> + + <para>Due to various limitations of the PC architecture, it is + impossible for probing to be 100% reliable, however, there are + a few things you can do if it fails.</para> + + <para>Check the <ulink + url="http://www.FreeBSD.org/releases/index.html">Hardware + Notes</ulink> document for your version of &os; to make sure + your hardware is supported.</para> + + <para>If your hardware is supported and you still experience + lock-ups or other problems, you will need to build a + <link linkend="kernelconfig">custom kernel</link>. This will + allow you to add in support for devices which are not present + in the <filename>GENERIC</filename> kernel. The kernel on the + boot disks is configured assuming that most hardware devices + are in their factory default configuration in terms of IRQs, + IO addresses, and DMA channels. If your hardware has been + reconfigured, you will most likely need to edit the kernel + configuration and recompile to tell &os; where to find + things.</para> + + <para>It is also possible that a probe for a device not present + will cause a later probe for another device that is present to + fail. In that case, the probes for the conflicting driver(s) + should be disabled.</para> + + <note> + <para>Some installation problems can be avoided or alleviated + by updating the firmware on various hardware components, + most notably the motherboard. Motherboard firmware is + usually referred to as the <acronym>BIOS</acronym>. Most + motherboard and computer manufacturers have a website for + upgrades and upgrade information.</para> + + <para>Manufacturers generally advise against upgrading the + motherboard <acronym>BIOS</acronym> unless there is a good + reason for doing so, like a critical update. The upgrade + process <emphasis>can</emphasis> go wrong, leaving the + <acronym>BIOS</acronym> incomplete and the computer + inoperative.</para> + </note> + </sect2> + + <sect2> + <title>Troubleshooting Questions and Answers</title> + + <qandaset> + <qandaentry> + <question> + <para>My system hangs while probing hardware during boot, + or it behaves strangely during install.</para> + </question> + + <answer> + <para>&os; makes extensive use of the system + ACPI service on the i386, amd64, and ia64 platforms to + aid in system configuration if it is detected during + boot. Unfortunately, some bugs still exist in both the + ACPI driver and within system motherboards and + <acronym>BIOS</acronym> + firmware. ACPI can be disabled by setting + the <literal>hint.acpi.0.disabled</literal> hint in the + third stage boot loader:</para> + + <screen><userinput>set hint.acpi.0.disabled="1"</userinput></screen> + + <para>This is reset each time the system is booted, so it + is necessary to + add <literal>hint.acpi.0.disabled="1"</literal> to the + file + <filename>/boot/loader.conf</filename>. More + information about the boot loader can be found + in <xref linkend="boot-synopsis">.</para> + </answer> + </qandaentry> + </qandaset> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/chapter.decl b/en_US.ISO8859-1/books/handbook/chapter.decl new file mode 100644 index 0000000000..ecb0cac2f9 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/chapter.decl @@ -0,0 +1 @@ +<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"> diff --git a/en_US.ISO8859-1/books/handbook/chapters.ent b/en_US.ISO8859-1/books/handbook/chapters.ent new file mode 100644 index 0000000000..5e35a4db6f --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/chapters.ent @@ -0,0 +1,64 @@ +<!-- + 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 .sgml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $FreeBSD$ +--> + +<!ENTITY chap.preface SYSTEM "preface/preface.sgml"> + +<!-- Part one --> +<!ENTITY chap.introduction SYSTEM "introduction/chapter.sgml"> +<!ENTITY chap.install SYSTEM "install/chapter.sgml"> +<!ENTITY chap.bsdinstall SYSTEM "bsdinstall/chapter.sgml"> +<!ENTITY chap.basics SYSTEM "basics/chapter.sgml"> +<!ENTITY chap.ports SYSTEM "ports/chapter.sgml"> +<!ENTITY chap.x11 SYSTEM "x11/chapter.sgml"> + +<!-- Part two --> +<!ENTITY chap.desktop SYSTEM "desktop/chapter.sgml"> +<!ENTITY chap.multimedia SYSTEM "multimedia/chapter.sgml"> +<!ENTITY chap.kernelconfig SYSTEM "kernelconfig/chapter.sgml"> +<!ENTITY chap.printing SYSTEM "printing/chapter.sgml"> +<!ENTITY chap.linuxemu SYSTEM "linuxemu/chapter.sgml"> + +<!-- Part three --> +<!ENTITY chap.config SYSTEM "config/chapter.sgml"> +<!ENTITY chap.boot SYSTEM "boot/chapter.sgml"> +<!ENTITY chap.users SYSTEM "users/chapter.sgml"> +<!ENTITY chap.security SYSTEM "security/chapter.sgml"> +<!ENTITY chap.jails SYSTEM "jails/chapter.sgml"> +<!ENTITY chap.mac SYSTEM "mac/chapter.sgml"> +<!ENTITY chap.audit SYSTEM "audit/chapter.sgml"> +<!ENTITY chap.disks SYSTEM "disks/chapter.sgml"> +<!ENTITY chap.geom SYSTEM "geom/chapter.sgml"> +<!ENTITY chap.filesystems SYSTEM "filesystems/chapter.sgml"> +<!ENTITY chap.vinum SYSTEM "vinum/chapter.sgml"> +<!ENTITY chap.virtualization SYSTEM "virtualization/chapter.sgml"> +<!ENTITY chap.l10n SYSTEM "l10n/chapter.sgml"> +<!ENTITY chap.cutting-edge SYSTEM "cutting-edge/chapter.sgml"> +<!ENTITY chap.dtrace SYSTEM "dtrace/chapter.sgml"> + +<!-- Part four --> +<!ENTITY chap.serialcomms SYSTEM "serialcomms/chapter.sgml"> +<!ENTITY chap.ppp-and-slip SYSTEM "ppp-and-slip/chapter.sgml"> +<!ENTITY chap.mail SYSTEM "mail/chapter.sgml"> +<!ENTITY chap.network-servers SYSTEM "network-servers/chapter.sgml"> +<!ENTITY chap.firewalls SYSTEM "firewalls/chapter.sgml"> +<!ENTITY chap.advanced-networking SYSTEM "advanced-networking/chapter.sgml"> + +<!-- Part five (appendices) --> +<!ENTITY chap.mirrors SYSTEM "mirrors/chapter.sgml"> +<!ENTITY chap.mirrors.ftp.inc SYSTEM "mirrors.sgml.ftp.inc"> +<!ENTITY chap.mirrors.cvsup.inc SYSTEM "mirrors.sgml.cvsup.inc"> + +<!ENTITY chap.bibliography SYSTEM "bibliography/chapter.sgml"> +<!ENTITY chap.eresources SYSTEM "eresources/chapter.sgml"> +<!ENTITY chap.eresources.www.inc SYSTEM "eresources.sgml.www.inc"> +<!ENTITY chap.pgpkeys SYSTEM "pgpkeys/chapter.sgml"> +<!ENTITY chap.index SYSTEM "index.sgml"> +<!ENTITY chap.colophon SYSTEM "colophon.sgml"> diff --git a/en_US.ISO8859-1/books/handbook/colophon.sgml b/en_US.ISO8859-1/books/handbook/colophon.sgml new file mode 100644 index 0000000000..30fbc870b0 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/colophon.sgml @@ -0,0 +1,32 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<colophon 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 <application>&tex;</application> typesetting language, + Leslie Lamport's <application>LaTeX</application>, or Sebastian + Rahtz's <application>JadeTeX</application> macro package.</para> +</colophon> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/config/Makefile b/en_US.ISO8859-1/books/handbook/config/Makefile new file mode 100644 index 0000000000..40c8e11572 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/config/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= config/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/config/chapter.sgml b/en_US.ISO8859-1/books/handbook/config/chapter.sgml new file mode 100644 index 0000000000..b70b5a8fdb --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/config/chapter.sgml @@ -0,0 +1,3369 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="config-tuning"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Chern</firstname> + <surname>Lee</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Mike</firstname> + <surname>Smith</surname> + <contrib>Based on a tutorial written by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Matt</firstname> + <surname>Dillon</surname> + <contrib>Also based on tuning(7) written by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>Configuration and Tuning</title> + + <sect1 id="config-synopsis"> + <title>Synopsis</title> + + <indexterm><primary>system configuration</primary></indexterm> + <indexterm><primary>system optimization</primary></indexterm> + + <para>One of the important aspects of &os; is system + configuration. Correct system configuration will help prevent + headaches during future upgrades. This chapter will explain + much of the &os; configuration process, including some of the + parameters which can be set to tune a &os; system.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to efficiently work with + file systems and swap partitions.</para> + </listitem> + + <listitem> + <para>The basics of <filename>rc.conf</filename> configuration + and <filename + class="directory">/usr/local/etc/rc.d</filename> startup + systems.</para> + </listitem> + + <listitem> + <para>How to configure and test a network card.</para> + </listitem> + + <listitem> + <para>How to configure virtual hosts on your network + devices.</para> + </listitem> + + <listitem> + <para>How to use the various configuration files in + <filename class="directory">/etc</filename>.</para> + </listitem> + + <listitem> + <para>How to tune &os; using <command>sysctl</command> + variables.</para> + </listitem> + + <listitem> + <para>How to tune disk performance and modify kernel + limitations.</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> + </itemizedlist> + </sect1> + + <sect1 id="configtuning-initial"> + <title>Initial Configuration</title> + + <sect2> + <title>Partition Layout</title> + + <indexterm><primary>partition layout</primary></indexterm> + <indexterm> + <primary><filename class="directory">/etc</filename></primary> + </indexterm> + <indexterm> + <primary><filename class="directory">/var</filename></primary> + </indexterm> + <indexterm> + <primary><filename class="directory">/usr</filename></primary> + </indexterm> + + <sect3> + <title>Base Partitions</title> + + <para>When laying out file systems with &man.bsdlabel.8; or + &man.sysinstall.8;, remember that hard drives transfer data + faster from the outer tracks to the inner. Thus smaller and + heavier-accessed file systems should be closer to the + outside of the drive, while larger partitions like + <filename class="directory">/usr</filename> should be placed + toward the inner parts of the disk. It is a good idea to + create partitions in an order similar to: root, swap, + <filename class="directory">/var</filename>, + <filename class="directory">/usr</filename>.</para> + + <para>The size of the + <filename class="directory">/var</filename> partition + reflects the intended machine usage. The + <filename class="directory">/var</filename> file system is + used to hold mailboxes, log files, and printer spools. + Mailboxes and log files can grow to unexpected sizes + depending on how many users exist and how long log files are + kept. Most users will rarely need more than about a + gigabyte of free disk space in + <filename class="directory">/var</filename>.</para> + + <note> + <para>There are a few times that a lot of disk space is + required in + <filename class="directory">/var/tmp</filename>. When new + software is installed with &man.pkg.add.1; the packaging + tools extract a temporary copy of the packages under + <filename class="directory">/var/tmp</filename>. Large + software packages, like + <application>Firefox</application>, + <application>OpenOffice</application> or + <application>LibreOffice</application> may be tricky to + install if there is not enough disk space under + <filename class="directory">/var/tmp</filename>.</para> + </note> + + <para>The <filename class="directory">/usr</filename> + partition holds many of the files required to support the + system, including the &man.ports.7; collection (recommended) + and the source code (optional). Both the ports and the + sources of the base system are optional at install time, but + we recommend at least 2 gigabytes for this partition.</para> + + <para>When selecting partition sizes, keep the space + requirements in mind. Running out of space in + one partition while barely using another can be a + hassle.</para> + + <note> + <para>Some users have found that &man.sysinstall.8;'s + <literal>Auto-defaults</literal> partition sizer will + sometimes select smaller than adequate + <filename class="directory">/var</filename> and + <filename class="directory">/</filename> partitions. + Partition wisely and generously.</para> + </note> + </sect3> + + <sect3 id="swap-design"> + <title>Swap Partition</title> + + <indexterm><primary>swap sizing</primary></indexterm> + <indexterm><primary>swap partition</primary></indexterm> + + <para>As a rule of thumb, the swap partition should be about + double the size of system memory (RAM). For example, if the + machine has 128 megabytes of memory, the swap file + should be 256 megabytes. Systems with less memory may + perform better with more swap. Less than 256 megabytes + of swap is not recommended and memory expansion should be + considered. The kernel's VM paging algorithms are tuned to + perform best when the swap partition is at least two times + the size of main memory. Configuring too little swap can + lead to inefficiencies in the VM page scanning code and + might create issues later if more memory is added.</para> + + <para>On larger systems with multiple SCSI disks (or multiple + IDE disks operating on different controllers), it is + recommend that a swap is configured on each drive (up to + four drives). The swap partitions should be approximately + the same size. The kernel can handle arbitrary sizes but + internal data structures scale to 4 times the largest swap + partition. Keeping the swap partitions near the same size + will allow the kernel to optimally stripe swap space across + disks. Large swap sizes are fine, even if swap is not used + much. It might be easier to recover from a runaway program + before being forced to reboot.</para> + </sect3> + + <sect3> + <title>Why Partition?</title> + + <para>Several users think a single large partition will be + fine, but there are several reasons why this is a bad idea. + First, each partition has different operational + characteristics and separating them allows the file system + to tune accordingly. For example, the root and + <filename class="directory">/usr</filename> partitions are + read-mostly, without much writing. While a lot of reading + and writing could occur in + <filename class="directory">/var</filename> and + <filename class="directory">/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 class="directory">/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 id="configtuning-core-configuration"> + <title>Core Configuration</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 class="directory">/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 + system-specific configuration into the + <filename>/etc/rc.conf.local</filename> file. For + example:</para> + + <itemizedlist> + <listitem> + <para><filename>/etc/rc.conf</filename>:</para> + + <programlisting>sshd_enable="YES" +keyrate="fast" +defaultrouter="10.1.1.254"</programlisting> + + </listitem> + + <listitem> + <para><filename>/etc/rc.conf.local</filename>:</para> + + <programlisting>hostname="node1.example.org" +ifconfig_fxp0="inet 10.1.1.1/8"</programlisting> + + </listitem> + </itemizedlist> + + <para>The <filename>rc.conf</filename> file can then be + distributed to every system using <command>rsync</command> or a + similar program, while the <filename>rc.conf.local</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> + + <tip> + <para>The <filename>/etc/rc.conf</filename> configuration file + is parsed by &man.sh.1;. This allows system operators to + add a certain amount of logic to this file, which may help to + create very complex configuration scenarios. Please see + &man.rc.conf.5; for further information on this topic.</para> + </tip> + </sect1> + + <sect1 id="configtuning-appconfig"> + <title>Application Configuration</title> + + <para>Typically, installed applications have their own + configuration files, with their own syntax, etc. It is + important that these files be kept separate from the base + system, so that they may be easily located and managed by the + package management tools.</para> + + <indexterm><primary>/usr/local/etc</primary></indexterm> + + <para>Typically, these files are installed in + <filename class="directory">/usr/local/etc</filename>. In the + case where an application has a large number of configuration + files, a subdirectory will be created to hold them.</para> + + <para>Normally, when a port or package is installed, sample + configuration files are also installed. These are usually + identified with a <filename>.default</filename> suffix. If + there are no existing configuration files for the application, + they will be created by copying the + <filename>.default</filename> files.</para> + + <para>For example, consider the contents of the directory + <filename + class="directory">/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>The file sizes show that only the + <filename>srm.conf</filename> file has been changed. A later + update of the <application>Apache</application> port would not + overwrite this changed file.</para> + </sect1> + + <sect1 id="configtuning-starting-services"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>Starting Services</title> + + <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 <filename role="package">mail/postfix</filename> or + <filename role="package">www/apache22</filename> 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> + + <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_enable + +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> pseudo-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 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>Using Services to Start Services</title> + + <para>Other services, such as <acronym>POP</acronym>3 server + daemons, <acronym>IMAP</acronym>, etc. could be started using + &man.inetd.8;. This involves installing the service utility + from the Ports Collection with a configuration line added to + the <filename>/etc/inetd.conf</filename> file, or by + 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 make more sense 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 id="configtuning-cron"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + <!-- 20 May 2003 --> + </author> + </authorgroup> + </sect1info> + <title>Configuring the <command>cron</command> Utility</title> + + <indexterm><primary>cron</primary> + <secondary>configuration</secondary></indexterm> + + <para>One of the most useful utilities in &os; is &man.cron.8;. + The <command>cron</command> utility runs in the background and + constantly checks the <filename>/etc/crontab</filename> file. + The <command>cron</command> utility also checks the + <filename class="directory">/var/cron/tabs</filename> directory, + in search of new <filename>crontab</filename> files. These + <filename>crontab</filename> files store information about + specific functions which <command>cron</command> is supposed to + perform at certain times.</para> + + <para>The <command>cron</command> utility uses two different types + of configuration files, the system crontab and user crontabs. + These formats only differ in the sixth field and later. In the + system crontab, <command>cron</command> will run the command as + the user specified in the sixth field. In a user crontab, all + commands run as the user who created the crontab, so the sixth + field is the last field; this is an important security feature. + The final field is always the command to run.</para> + + <note> + <para>User crontabs allow individual users to schedule tasks + without the need for <username>root</username> privileges. + Commands in a user's crontab run with the permissions of the + user who owns the crontab.</para> + + <para>The <username>root</username> user can have a user crontab + just like any other user. The <username>root</username> user + crontab is separate from <filename>/etc/crontab</filename> + (the system crontab). Because the system crontab effectively + invokes the specified commands as root there is usually no + need to create a user crontab for + <username>root</username>.</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 id="co-comments"> +# +SHELL=/bin/sh +PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env"> +HOME=/var/log +# +# +#minute hour mday month wday who command <co id="co-field-descr"> +# +# +*/5 * * * * root /usr/libexec/atrun <co 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. The last + field is 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 <username>root</username> 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 setup 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 id="configtuning-installcrontab"> + <title>Installing a Crontab</title> + + <important> + <para>Do not use the procedure described here to edit and + install the system crontab, + <filename>/etc/crontab</filename>. Just use your favorite + editor: the <command>cron</command> utility will notice that + the file has changed and immediately begin using the updated + version. See <ulink + url="&url.books.faq;/admin.html#ROOT-NOT-FOUND-CRON-ERRORS"> + this FAQ entry</ulink> 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>In order to remove a user <filename>crontab</filename> + completely, use <command>crontab</command> with the + <option>-r</option> option.</para> + </sect2> + </sect1> + + <sect1 id="configtuning-rcd"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + <!-- 16 May 2003 --> + </author> + </authorgroup> + </sect1info> + + <title>Using &man.rc.8; Under &os;</title> + + <para>In 2002 &os; integrated the NetBSD <filename>rc.d</filename> + system for system initialization. Users should notice the files + listed in the <filename class="directory">/etc/rc.d</filename> + directory. Many of these files are for basic services which can + be controlled with the <option>start</option>, + <option>stop</option>, and <option>restart</option> options. + For instance, &man.sshd.8; can be restarted with the following + command:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/sshd restart</userinput></screen> + + <para>This procedure is similar for other services. Of course, + services are usually started automatically at boot time as + specified in &man.rc.conf.5;. For example, enabling the Network + Address Translation daemon at startup is as simple as adding the + following line to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>natd_enable="YES"</programlisting> + + <para>If a <option>natd_enable="NO"</option> line is already + present, then simply change the <option>NO</option> to + <option>YES</option>. The rc scripts will automatically load + any other dependent services during the next reboot, as + described below.</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>one</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 onerestart</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 + <username>root</username> console.</para> + </note> + + <para>To determine if a service is running, a + <option>status</option> option is available. For instance to + verify that <command>sshd</command> is actually started:</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.</para> + + <para>The following words must be included in all startup scripts + (they are required by &man.rc.subr.8; to <quote>enable</quote> + the startup script):</para> + + <itemizedlist> + <listitem> + <para><literal>PROVIDE</literal>: Specifies the services this + file provides.</para> + </listitem> + </itemizedlist> + + <para>The following words may be included at the top of each + startup file. They are not strictly necessary, but they are + useful as hints to &man.rcorder.8;:</para> + + <itemizedlist> + <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 carefully setting these keywords for each startup script, + an administrator has a very fine-grained level of control of the + startup order of the scripts, 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. If you are interested in writing your own + <filename>rc.d</filename> scripts or improving the existing + ones, you may find <ulink url="&url.articles.rc-scripting">this + article</ulink> also useful.</para> + </sect1> + + <sect1 id="config-network-setup"> + <sect1info> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + <contrib>Contributed by </contrib> + <!-- 6 October 2002 --> + </author> + </authorgroup> + </sect1info> + + <title>Setting Up Network Interface Cards</title> + + <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>Locating the Correct 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/<replaceable>arch</replaceable>/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 +miibus0: <MII bus> on dc0 +bmtphy0: <BCM5201 10/100baseTX PHY> PHY 1 on miibus0 +bmtphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto +dc0: Ethernet address: 00:a0:cc:da:da:da +dc0: [ITHREAD] +dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30 +000ff irq 11 at device 12.0 on pci0 +miibus1: <MII bus> on dc1 +bmtphy1: <BCM5201 10/100baseTX PHY> PHY 1 on miibus1 +bmtphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto +dc1: Ethernet address: 00:a0:cc:da:da:db +dc1: [ITHREAD]</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/<replaceable>arch</replaceable>/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 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.sgml --> + + <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) 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 only runs on &i386; and amd64 systems. + PCI, CardBus, PCMCIA (PC-Card), and USB devices are + supported.</para> + + <para>To use the NDISulator, three things are needed:</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 vendor's + website. In the following examples, we will use + <filename>W32DRIVER.SYS</filename> and + <filename>W32DRIVER.INF</filename>.</para> + + <para>The driver bit width must match the version of &os;. + For &os;/i386, use a &windows; 32-bit driver. For + &os;/amd64, a &windows; 64-bit driver is needed.</para> + + <para>The next step is to compile the driver binary into a + loadable kernel module. As <username>root</username>, use + &man.ndisgen.8;:</para> + + <screen>&prompt.root; <userinput>ndisgen <replaceable>/path/to/W32DRIVER.INF</replaceable> <replaceable>/path/to/W32DRIVER.SYS</replaceable></userinput></screen> + + <para>&man.ndisgen.8; is interactive and prompts for any extra + information it requires. A new kernel module is written in + the current directory. Use &man.kldload.8; to load the new + module:</para> + + <screen>&prompt.root; <userinput>kldload <replaceable>./W32DRIVER_SYS.ko</replaceable></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 + <devicename>ndis0</devicename> device like any other network + interface (e.g., <devicename>dc0</devicename>).</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_SYS.ko</filename>, to the <filename + class="directory">/boot/modules</filename> directory. Then, + add the following line to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>W32DRIVER_SYS_load="YES"</programlisting> + </sect3> + </sect2> + + <sect2> + <title>Configuring the Network Card</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> metric 0 mtu 1500 + options=80008<VLAN_MTU,LINKSTATE> + ether 00:a0:cc:da:da:da + inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255 + media: Ethernet autoselect (100baseTX <full-duplex>) + status: active +dc1: flags=8802<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 + options=80008<VLAN_MTU,LINKSTATE> + ether 00:a0:cc:da:da:db + inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255 + media: Ethernet 10baseT/UTP + status: no carrier +plip0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> metric 0 mtu 1500 +lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 + options=3<RXCSUM,TXCSUM> + inet6 fe80::1%lo0 prefixlen 64 scopeid 0x4 + inet6 ::1 prefixlen 128 + inet 127.0.0.1 netmask 0xff000000 + nd6 options=3<PERFORMNUD,ACCEPT_RTADV></screen> + + <para>In this example, the following devices were + displayed:</para> + + <itemizedlist> + <listitem> + <para><devicename>dc0</devicename>: The first Ethernet + interface</para> + </listitem> + + <listitem> + <para><devicename>dc1</devicename>: The second Ethernet + interface</para> + </listitem> + + <listitem> + <para><devicename>plip0</devicename>: The parallel port + interface (if a parallel port is present on the + machine)</para> + </listitem> + + <listitem> + <para><devicename>lo0</devicename>: The loopback + device</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 <devicename>sis2</devicename> would + be the third network card on the system using the &man.sis.4; + driver.</para> + + <para>In this example, the <devicename>dc0</devicename> 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 + <hostid role="ipaddr">192.168.1.3</hostid>).</para> + </listitem> + + <listitem> + <para>It has a valid subnet mask + (<literal>netmask</literal>; + <hostid role="netmask">0xffffff00</hostid> is the same as + <hostid role="netmask">255.255.255.0</hostid>).</para> + </listitem> + + <listitem> + <para>It has a valid broadcast address (in this case, + <hostid role="ipaddr">192.168.1.255</hostid>).</para> + </listitem> + + <listitem> + <para>The MAC address of the card (<literal>ether</literal>) + is <hostid role="mac">00:a0:cc:da:da:da</hostid></para> + </listitem> + + <listitem> + <para>The physical media selection is on autoselection mode + (<literal>media: Ethernet autoselect (100baseTX + <full-duplex>)</literal>). We see that + <devicename>dc1</devicename> 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 <devicename>dc1</devicename>, 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> metric 0 mtu 1500 + options=80008<VLAN_MTU,LINKSTATE> + ether 00:a0:cc:da:da:da + media: Ethernet autoselect (100baseTX <full-duplex>) + status: active</screen> + + <para>it would indicate the card has not been configured.</para> + + <para>To configure your card, you need <username>root</username> + 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 <devicename>dc0</devicename>, + <devicename>dc1</devicename>, 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> + + <note> + <para>If access to the Internet is planned with the machine, + you also have to manually set up the default gateway and the + nameserver:</para> + + <screen>&prompt.root; <userinput>echo 'defaultrouter="<replaceable>your_default_router</replaceable>"' >> /etc/rc.conf</userinput> +&prompt.root; <userinput>echo 'nameserver <replaceable>your_DNS_server</replaceable>' >> /etc/resolv.conf</userinput></screen> + </note> + </sect2> + + <sect2> + <title>Testing and Troubleshooting</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. Alternatively you can just relaunch the + networking system:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/netif restart</userinput></screen> + + <note> + <para>If a default gateway has been set in + <filename>/etc/rc.conf</filename>, use also this + command:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/routing restart</userinput></screen> + </note> + + <para>Once the networking system has been relaunched, you should + test the network interfaces.</para> + + <sect3> + <title>Testing the 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 + <hostid role="ipaddr">192.168.1.2</hostid> if you have set + up the <filename>/etc/hosts</filename> file.</para> + </sect3> + + <sect3> + <title>Troubleshooting</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 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 + <devicename>fxp0</devicename> 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 + <hostid role="netmask">255.255.255.255</hostid> or + <hostid role="netmask">0xffffffff</hostid>).</para> + + <para>For example, consider the case where the + <devicename>fxp0</devicename> interface is connected to two + networks, the <hostid role="ipaddr">10.1.1.0</hostid> network + with a netmask of <hostid role="netmask">255.255.255.0</hostid> + and the <hostid role="ipaddr">202.0.75.16</hostid> network with + a netmask of <hostid role="netmask">255.255.255.240</hostid>. + We want the system to appear at + <hostid role="ipaddr">10.1.1.1</hostid> through + <hostid role="ipaddr">10.1.1.5</hostid> and at + <hostid role="ipaddr">202.0.75.17</hostid> through + <hostid role="ipaddr">202.0.75.20</hostid>. As noted above, + only the first address in a given network range (in this case, + <hostid role="ipaddr">10.0.1.1</hostid> and + <hostid role="ipaddr">202.0.75.17</hostid>) should have a real + netmask; all the rest (<hostid role="ipaddr">10.1.1.2</hostid> + through <hostid role="ipaddr">10.1.1.5</hostid> and + <hostid role="ipaddr">202.0.75.18</hostid> through + <hostid role="ipaddr">202.0.75.20</hostid>) must be configured + with a netmask of + <hostid role="netmask">255.255.255.255</hostid>.</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 id="configtuning-configfiles"> + <title>Configuration Files</title> + + <sect2> + <title><filename class="directory">/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 + class="directory">/etc</filename></entry> + <entry>Generic system configuration information; data + here is system-specific.</entry> + </row> + + <row> + <entry><filename + class="directory">/etc/defaults</filename></entry> + <entry>Default versions of system configuration + files.</entry> + </row> + + <row> + <entry><filename + class="directory">/etc/mail</filename></entry> + <entry>Extra &man.sendmail.8; configuration, other + MTA configuration files.</entry> + </row> + + <row> + <entry><filename + class="directory">/etc/ppp</filename></entry> + <entry>Configuration for both user- and kernel-ppp + programs.</entry> + </row> + + <row> + <entry><filename + class="directory">/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 + class="directory">/usr/local/etc</filename></entry> + <entry>Configuration files for installed applications. + May contain per-application subdirectories.</entry> + </row> + + <row> + <entry><filename + class="directory">/usr/local/etc/rc.d</filename></entry> + <entry>Start/stop scripts for installed + applications.</entry> + </row> + + <row> + <entry><filename + class="directory">/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. Replace 'my.domain' below with the domainname of your +# machine. +# +# 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 +127.0.0.1 localhost localhost.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. Do not try to invent your own network +# numbers but instead get one from your network provider (if any) or +# from your regional registry (ARIN, APNIC, LACNIC, RIPE NCC, or AfriNIC.) +#</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 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>To turn off logging of fatal signal exits and prevent + users from seeing processes started from other users, the + following tunables can be set in + <filename>sysctl.conf</filename>:</para> + + <programlisting># Do not log fatal signal exits (e.g., sig 11) +kern.logsigexit=0 + +# Prevent users from seeing information about processes that +# are being run under another UID. +security.bsd.see_other_uids=0</programlisting> + + </sect2> + </sect1> + + <sect1 id="configtuning-sysctl"> + <title>Tuning with &man.sysctl.8;</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 id="sysctl-readonly"> + <sect2info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + <!-- 31 January 2003 --> + </author> + </authorgroup> + </sect2info> + <title>&man.sysctl.8; Read-only</title> + + <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 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). The <varname>kern.cam.scsi_delay</varname> + boot time tunable should be used. 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 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 id="configtuning-kernel-limits"> + <title>Tuning Kernel Limits</title> + + <indexterm> + <primary>tuning</primary> + <secondary>kernel limits</secondary> + </indexterm> + + <sect2 id="file-process-limits"> + <title>File/Process Limits</title> + + <sect3 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, the default value of + <varname>kern.maxfiles</varname> is derived from 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>The variable <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; manual page or the + <filename>/boot/defaults/loader.conf</filename> file for + some hints) or as described elsewhere in this + document.</para> + + <para>In older releases, 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 + <hostid role="fqdn">ftp.FreeBSD.org</hostid>), 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.</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 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> + + <screen>&prompt.root; <userinput>sysctl vfs.numvnodes</userinput> +vfs.numvnodes: 91349</screen> + + <para>To see the maximum vnodes:</para> + + <screen>&prompt.root; <userinput>sysctl kern.maxvnodes</userinput> +kern.maxvnodes: 100000</screen> + + <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 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 id="new-drive-swap"> + <title>Swap on a New or Existing Hard Drive</title> + + <para>Adding a new hard drive for swap gives better performance + than adding a partition on an existing drive. Setting up + partitions and hard drives is explained in + <xref linkend="disks-adding">. + <xref linkend="configtuning-initial"> discusses partition + layouts and swap partition size considerations.</para> + + <para>Use &man.swapon.8; to add a swap partition to the system. + For example:</para> + + <screen>&prompt.root; <userinput>swapon<replaceable> /dev/ada1s1p2</replaceable></userinput></screen> + + <warning> + + <para>It is possible to use any partition not currently + mounted, even if it already contains data. Using + &man.swapon.8; on a partition that contains data will + overwrite and destroy that data. Make sure that the + partition to be added as swap is really the intended + partition before running &man.swapon.8;.</para> + </warning> + + <para>To automatically add this swap partition on boot, add an + entry to <filename>/etc/fstab</filename> for the + partition:</para> + + <programlisting><replaceable>/dev/ada1s1p1</replaceable> none swap sw 0 0</programlisting> + + <para>See &man.fstab.5; for an explaination of the entries in + <filename>/etc/fstab</filename>.</para> + </sect2> + + <sect2 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 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>The <filename>GENERIC</filename> kernel already + includes the memory disk driver (&man.md.4;) required + for this operation. When building a custom kernel, make + sure to include the following line in your custom + configuration file:</para> + + <programlisting>device md</programlisting> + + <para>For information on building your own kernel, please + refer to <xref linkend="kernelconfig">.</para> + </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 id="acpi-overview"> + <sect1info> + <authorgroup> + <author> + <firstname>Hiten</firstname> + <surname>Pandya</surname> + <contrib>Written by </contrib> + </author> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + </author> + </authorgroup> + </sect1info> + + <title>Power and Resource Management</title> + + <para>It is important to utilize hardware resources in an + efficient manner. Before <acronym>ACPI</acronym> was + introduced, it was difficult and inflexible for operating + systems to manage the power usage and thermal properties of a + system. The hardware was managed by the <acronym>BIOS</acronym> + and thus the user had less control and visibility into the power + management settings. Some limited configurability was available + via <emphasis>Advanced Power Management (APM)</emphasis>. 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 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 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. APM should still be used for + systems manufactured at or before the year 2000.</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 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 + often doesn't work well. If you are experiencing problems, + you can disable <acronym>ACPI</acronym> altogether. 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 by setting + <literal>hint.acpi.0.disabled="1"</literal> in + <filename>/boot/loader.conf</filename> or at the + &man.loader.8; prompt.</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><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> or <literal>3</literal> + (suspend to RAM). 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>Other options are available via &man.sysctl.8;. Check out + the &man.acpi.4; and &man.acpiconf.8; manual pages for more + information.</para> + </sect2> + </sect1> + + <sect1 id="ACPI-debug"> + <sect1info> + <authorgroup> + <author> + <firstname>Nate</firstname> + <surname>Lawson</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Peter</firstname> + <surname>Schultz</surname> + <contrib>With contributions from </contrib> + </author> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + </author> + </authorgroup> + </sect1info> + + <title>Using and Debugging &os; <acronym>ACPI</acronym></title> + + <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 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 + <ulink url="mailto:freebsd-acpi@FreeBSD.org"> + freebsd-acpi@FreeBSD.org</ulink>:</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 -dt > <replaceable>name</replaceable>-<replaceable>system</replaceable>.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 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 + class="directory">src/sys/contrib/dev/acpica</filename>. + The glue code that allows <acronym>ACPI-CA</acronym> to work + on &os; is in + <filename class="directory">src/sys/dev/acpica/Osd</filename>. + Finally, drivers that implement various + <acronym>ACPI</acronym> devices are found in <filename + class="directory">src/sys/dev/acpica</filename>.</para> + </sect2> + + <sect2 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>A common problem with suspend/resume is that many device + drivers do not save, restore, or reinitialize their + firmware, registers, or device memory properly. As a first + attempt at debugging the problem, try:</para> + + <screen>&prompt.root; <userinput>sysctl debug.bootverbose=1</userinput> +&prompt.root; <userinput>sysctl debug.acpi.suspend_bounce=1</userinput> +&prompt.root; <userinput>acpiconf -s 3</userinput></screen> + + <para>This test emulates suspend/resume cycle of all device + drivers without actually going into <literal>S3</literal> + state. In some cases, you can easily catch problems with + this method (e.g., losing firmware state, device watchdog + time out, and retrying forever). Note that the system will + not really enter <literal>S3</literal> state, which means + devices may not lose power, and many will work fine even if + suspend/resume methods are totally missing, unlike real + <literal>S3</literal> state.</para> + + <para>Harder cases require additional hardware, i.e., serial + port/cable for serial console or Firewire port/cable for + &man.dcons.4;, and kernel debugging skills.</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 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 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 class="directory">/boot</filename> + directory.</para> + </sect3> + </sect2> + + <sect2 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 class="directory">/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 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 + <ulink + url="http://lists.freebsd.org/pipermail/freebsd-acpi/"></ulink></para> + </listitem> + + <listitem> + <para>The old <acronym>ACPI</acronym> Mailing List Archives + <ulink + url="http://home.jp.FreeBSD.org/mail-list/acpi-jp/"></ulink></para> + </listitem> + + <listitem> + <para>The <acronym>ACPI</acronym> 2.0 Specification + <ulink url="http://acpi.info/spec.htm"></ulink></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><ulink + url="http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt"> + <acronym>DSDT</acronym> debugging resource</ulink>. + (Uses Compaq as an example but generally useful.)</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/Makefile b/en_US.ISO8859-1/books/handbook/cutting-edge/Makefile new file mode 100644 index 0000000000..29da7845dd --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= cutting-edge/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml new file mode 100644 index 0000000000..8e7a8c0e54 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.sgml @@ -0,0 +1,3238 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="updating-upgrading"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Mock</surname> + <contrib>Restructured, reorganized, and parts updated by </contrib> + </author> + <!-- Mar 2000 --> + </authorgroup> + + <authorgroup> + <author> + <firstname>Jordan</firstname> + <surname>Hubbard</surname> + <contrib>Original work by </contrib> + </author> + + <author> + <firstname>Poul-Henning</firstname> + <surname>Kamp</surname> + </author> + + <author> + <firstname>John</firstname> + <surname>Polstra</surname> + </author> + + <author> + <firstname>Nik</firstname> + <surname>Clayton</surname> + </author> + </authorgroup> + <!-- with feedback from various others --> + </chapterinfo> + + <title>Updating and Upgrading &os;</title> + + <sect1 id="updating-upgrading-synopsis"> + <title>Synopsis</title> + + <para>&os; is under constant development between releases. Some people + prefer to use the officially released versions, while others prefer + to keep in sync with the latest developments. However, even official + releases are often updated with security and other critical fixes. + Regardless of the version used, &os; provides all necessary tools + to keep your system updated, and also allows for easy upgrades between + versions. + This chapter will help you decide if you want to track the + development system, or stick with one of the released + versions. The basic tools for keeping your system up to date are + also presented.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>What utilities may be used to update the system and + the Ports Collection.</para> + </listitem> + + <listitem> + <para>How to keep your system up to date with + <application>freebsd-update</application>, + <application>CVSup</application>, + <application>CVS</application>, or + <application>CTM</application>.</para> + </listitem> + + <listitem> + <para>How to compare the state of an installed system against + a known pristine copy.</para> + </listitem> + + <listitem> + <para>How to keep your documentation up to date with + <application>CVSup</application> or documentation ports<!--, and + <application>Docsnap</application>-->.</para> + </listitem> + + <listitem> + <para>The difference between the two development + branches: &os.stable; and &os.current;.</para> + </listitem> + + <listitem> + <para>How to rebuild and reinstall the entire base + system with <command>make buildworld</command> (etc).</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Properly set up your network connection (<xref + linkend="advanced-networking">).</para> + </listitem> + + <listitem> + <para>Know how to install additional third-party + software (<xref linkend="ports">).</para> + </listitem> + </itemizedlist> + + <note> + <para>Throughout this chapter, the <command>cvsup</command> command is + used to obtain and update &os; sources. To use it, you will need to + install the port or the package for <filename + role="package">net/cvsup</filename> (if you do not want to install + the graphical <command>cvsup</command> client, you can just install + the port <filename>net/cvsup-without-gui</filename>). + You may wish to substitute this + with &man.csup.1;, which is part of the base system.</para> + </note> + </sect1> + + <sect1 id="updating-upgrading-freebsdupdate"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Colin</firstname> + <surname>Percival</surname> + <contrib>Based on notes provided by </contrib> + </author> + </authorgroup> + </sect1info> + <title>FreeBSD Update</title> + + <indexterm><primary>Updating and Upgrading</primary></indexterm> + <indexterm> + <primary>freebsd-update</primary> + <see>updating-upgrading</see> + </indexterm> + + <para>Applying security patches is an important part of maintaining + computer software, especially the operating system. For the + longest time on &os; this process was not an easy one. Patches + had to be applied to the source code, the code rebuilt into + binaries, and then the binaries had to be re-installed.</para> + + <para>This is no longer the case as &os; now includes a utility + simply called <command>freebsd-update</command>. This utility + provides two separate functions. First, it allows for binary + security and errata updates to be applied to the &os; base system + without the build and install requirements. Second, the utility + supports minor and major release upgrades.</para> + + <note> + <para>Binary updates are available for all architectures and + releases currently supported by the security team. + Before updating to a new release, the current + release announcements should be reviewed as they may contain + important information pertinent to the desired release. These + announcements may be viewed at the following link: + <ulink url="http://www.FreeBSD.org/releases/"></ulink>.</para> + </note> + + <para>If a <command>crontab</command> utilizing the features + of <command>freebsd-update</command> exists, it must be + disabled before the following operation is started.</para> + + <sect2 id="freebsdupdate-config-file"> + <title>The Configuration File</title> + + <para>Some users may wish to tweak the default configuration file + in <filename>/etc/freebsd-update.conf</filename>, + allowing better control of the process. The options are + very well documented, but the following few may require a + bit more explanation:</para> + + <programlisting># Components of the base system which should be kept updated. +Components src world kernel</programlisting> + + <para>This parameter controls what parts of &os; will be kept + up to date. The default is to update the source code, the + entire base system, and the kernel. Components are the + same as those available during the install, for instance, + adding <literal>world/games</literal> here would allow game patches to be + applied. Using <literal>src/bin</literal> would allow the source code in + <filename class="directory">src/bin</filename> to be + updated.</para> + + <para>The best option is to leave this at the default as + changing it to include specific items will require the user + to list every item they prefer to be updated. This could + have disastrous consequences as source code and binaries may + become out of sync.</para> + + <programlisting># Paths which start with anything matching an entry in an IgnorePaths +# statement will be ignored. +IgnorePaths</programlisting> + + <para>Add paths, such as + <filename class="directory">/bin</filename> or + <filename class="directory">/sbin</filename> to leave these + specific directories untouched during the update + process. This option may be used to prevent + <command>freebsd-update</command> from overwriting local + modifications.</para> + + <programlisting># Paths which start with anything matching an entry in an UpdateIfUnmodified +# statement will only be updated if the contents of the file have not been +# modified by the user (unless changes are merged; see below). +UpdateIfUnmodified /etc/ /var/ /root/ /.cshrc /.profile</programlisting> + + <para>Update configuration files in the specified directories + only if they have not been modified. Any changes made by the + user will invalidate the automatic updating of these files. + There is another option, + <literal>KeepModifiedMetadata</literal>, which will instruct + <command>freebsd-update</command> to save the changes during + the merge.</para> + + <programlisting># When upgrading to a new &os; release, files which match MergeChanges +# will have any local changes merged into the version from the new release. +MergeChanges /etc/ /var/named/etc/</programlisting> + + <para>List of directories with configuration files that + <command>freebsd-update</command> should attempt merges in. + The file merge process is a series of &man.diff.1; patches + similar to &man.mergemaster.8; with fewer options, the merges + are either accepted, open an editor, or + <command>freebsd-update</command> will abort. When in doubt, + backup <filename class="directory">/etc</filename> and just + accept the merges. See <xref linkend="mergemaster"> for more + information about the <command>mergemaster</command> + command.</para> + + <programlisting># Directory in which to store downloaded updates and temporary +# files used by &os; Update. +# WorkDir /var/db/freebsd-update</programlisting> + + <para>This directory is where all patches and temporary + files will be placed. In cases where the user is doing + a version upgrade, this location should have a least a + gigabyte of disk space available.</para> + + <programlisting># When upgrading between releases, should the list of Components be +# read strictly (StrictComponents yes) or merely as a list of components +# which *might* be installed of which &os; Update should figure out +# which actually are installed and upgrade those (StrictComponents no)? +# StrictComponents no</programlisting> + + <para>When set to <literal>yes</literal>, + <command>freebsd-update</command> will assume that the + <literal>Components</literal> list is complete and will not + attempt to make changes outside of the list. Effectively, + <command>freebsd-update</command> will attempt to update + every file which belongs to the <literal>Components</literal> + list.</para> + </sect2> + + <sect2 id="freebsdupdate-security-patches"> + <title>Security Patches</title> + + <para>Security patches are stored on a remote machine and + may be downloaded and installed using the following + command:</para> + + <screen>&prompt.root; <userinput>freebsd-update fetch</userinput> +&prompt.root; <userinput>freebsd-update install</userinput></screen> + + <para>If any kernel patches have been applied the system will + need a reboot. If all went well the system should be patched + and <command>freebsd-update</command> may be run as a nightly + &man.cron.8; job. An entry in <filename>/etc/crontab</filename> + would be sufficient to accomplish this task:</para> + + <programlisting>@daily root freebsd-update cron</programlisting> + + <para>This entry states that once every day, the + <command>freebsd-update</command> utility will be run. In this way, + using the <option>cron</option> argument, + <command>freebsd-update</command> will only check if updates + exist. If patches exist, they will automatically be downloaded + to the local disk but not applied. The + <username>root</username> user will be sent an email so they + may install them manually.</para> + + <para>If anything went wrong, <command>freebsd-update</command> + has the ability to roll back the last set of changes with + the following command:</para> + + <screen>&prompt.root; <userinput>freebsd-update rollback</userinput></screen> + + <para>Once complete, the system should be restarted if the kernel + or any kernel modules were modified. This will allow &os; to + load the new binaries into memory.</para> + + <para>The <command>freebsd-update</command> utility can + automatically update the <filename>GENERIC</filename> kernel only. + If a custom kernel is in use, it will have to be rebuilt and + reinstalled after <command>freebsd-update</command> finishes + installing the rest of the updates. However, + <command>freebsd-update</command> will detect and update the + <filename>GENERIC</filename> kernel in <filename + class="directory">/boot/GENERIC</filename> (if it exists), even if + it is not the current (running) kernel of the system.</para> + + <note> + <para>It is a good idea to always keep a copy of the + <filename>GENERIC</filename> kernel in <filename + class="directory">/boot/GENERIC</filename>. It will be helpful + in diagnosing a variety of problems, and in performing version + upgrades using <command>freebsd-update</command> as described in + <xref linkend="freebsdupdate-upgrade">.</para> + </note> + + <para>Unless the default configuration in + <filename>/etc/freebsd-update.conf</filename> has been changed, + <command>freebsd-update</command> will install the updated kernel + sources along with the rest of the updates. Rebuilding and + reinstalling your new custom kernel can then be performed in the usual + way.</para> + + <note> + <para>The updates distributed via <command>freebsd-update</command>, + do not always involve the kernel. It will not be necessary to + rebuild your custom kernel if the kernel sources have not been + modified by the execution of + <command>freebsd-update install</command>. However, + <command>freebsd-update</command> will always update the + <filename>/usr/src/sys/conf/newvers.sh</filename> file. The current + patch level (as indicated by the <literal>-p</literal> number + reported by <command>uname -r</command>) is + obtained from this file. Rebuilding your custom kernel, even if + nothing else changed, will allow &man.uname.1; to accurately report + the current patch level of the system. This is particularly + helpful when maintaining multiple systems, as it allows for a quick + assessment of the updates installed in each one.</para> + </note> + </sect2> + + <sect2 id="freebsdupdate-upgrade"> + <title>Major and Minor Upgrades</title> + + <para>This process will remove old object files and + libraries which will break most third party applications. + It is recommended that all installed ports either be removed + and re-installed or upgraded later using the + <filename role="package">ports-mgmt/portupgrade</filename> + utility. Most users will want to run a test build using + the following command:</para> + + <screen>&prompt.root; <userinput>portupgrade -af</userinput></screen> + + <para>This will ensure everything will be re-installed + correctly. Note that setting the + <makevar>BATCH</makevar> environment variable to + <literal>yes</literal> will answer <literal>yes</literal> to + any prompts during this process, removing the need for + manual intervention during the build process.</para> + + <para>If a custom kernel is in use, the upgrade process is slightly + more involved. A copy of the <filename>GENERIC</filename> kernel is + needed, and it should be placed in <filename + class="directory">/boot/GENERIC</filename>. If the + <filename>GENERIC</filename> kernel is not already present in the + system, it may be obtained using one of the following methods:</para> + + <itemizedlist> + <listitem> + <para>If a custom kernel has only been built once, the kernel in + <filename class="directory">/boot/kernel.old</filename> is + actually the <filename>GENERIC</filename> one. Simply rename this + directory to + <filename class="directory">/boot/GENERIC</filename>.</para> + </listitem> + + <listitem> + <para>Assuming physical access to the machine is possible, a copy + of the <filename>GENERIC</filename> kernel can be installed from + the CD-ROM media. Insert your installation disc and use the + following commands:</para> + + <screen>&prompt.root; <userinput>mount /cdrom</userinput> +&prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput> +&prompt.root; <userinput>./install.sh GENERIC</userinput></screen> + + <para>Replace <filename + class="directory"><replaceable>X.Y-RELEASE</replaceable></filename> + with the actual version of the release you are using. The + <filename>GENERIC</filename> kernel will be installed in <filename + class="directory">/boot/GENERIC</filename> by default.</para> + </listitem> + + <listitem> + <para>Failing all the above, the <filename>GENERIC</filename> kernel + may be rebuilt and installed from the sources:</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel</userinput> +&prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput> +&prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen> + + <para>For this kernel to be picked up as <filename>GENERIC</filename> + by <command>freebsd-update</command>, the + <filename>GENERIC</filename> configuration file must not have been + modified in any way. It is also suggested that it is built + without any other special options (preferably with an empty + <filename>/etc/make.conf</filename>).</para> + </listitem> + </itemizedlist> + + <para>Rebooting to the <filename>GENERIC</filename> kernel is not + required at this stage.</para> + + <para>Major and minor version updates may be performed by + providing <command>freebsd-update</command> with a release + version target, for example, the following command will + update to &os; 8.1:</para> + + <screen>&prompt.root; <userinput>freebsd-update -r 8.1-RELEASE upgrade</userinput></screen> + + <para>After the command has been received, + <command>freebsd-update</command> will evaluate the + configuration file and current system in an attempt to gather + the information necessary to update the system. A screen + listing will display what components have been detected and + what components have not been detected. For example:</para> + + <screen>Looking up update.FreeBSD.org mirrors... 1 mirrors found. +Fetching metadata signature for 8.0-RELEASE from update1.FreeBSD.org... done. +Fetching metadata index... done. +Inspecting system... done. + +The following components of FreeBSD seem to be installed: +kernel/smp src/base src/bin src/contrib src/crypto src/etc src/games +src/gnu src/include src/krb5 src/lib src/libexec src/release src/rescue +src/sbin src/secure src/share src/sys src/tools src/ubin src/usbin +world/base world/info world/lib32 world/manpages + +The following components of FreeBSD do not seem to be installed: +kernel/generic world/catpages world/dict world/doc world/games +world/proflibs + +Does this look reasonable (y/n)? y</screen> + + <para>At this point, <command>freebsd-update</command> will + attempt to download all files required for the upgrade. In + some cases, the user may be prompted with questions regarding + what to install or how to proceed.</para> + + <para>When using a custom kernel, the above step will produce a warning + similar to the following:</para> + + <screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" kernel, which is not a +kernel configuration distributed as part of FreeBSD 8.0-RELEASE. +This kernel will not be updated: you MUST update the kernel manually +before running "/usr/sbin/freebsd-update install"</screen> + + <para>This warning may be safely ignored at this point. The updated + <filename>GENERIC</filename> kernel will be used as an intermediate + step in the upgrade process.</para> + + <para>After all patches have been downloaded to the local + system, they will then be applied. This process may take + a while depending on the speed and workload of the machine. + Configuration files will then be merged — this part + of the process requires some user intervention as a file may be + merged or an editor may appear on screen for a manual merge. + The results of every successful merge will be shown to the user + as the process continues. A failed or ignored merge will cause + the process to abort. Users may wish to make a backup of + <filename class="directory">/etc</filename> and manually merge + important files, such as <filename>master.passwd</filename> + or <filename>group</filename> at a later time.</para> + + <note> + <para>The system is not being altered yet, all patching and + merging is happening in another directory. When all + patches have been applied successfully, all configuration + files have been merged and it seems the process will go + smoothly, the changes will need to be committed by the + user.</para> + </note> + + <para>Once this process is complete, the upgrade may be committed + to disk using the following command.</para> + + <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> + + <para>The kernel and kernel modules will be patched first. At + this point the machine must be rebooted. If the system was running + with a custom kernel, use the &man.nextboot.8; command to set the + kernel for the next boot to <filename + class="directory">/boot/GENERIC</filename> (which was + updated):</para> + + <screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen> + + <warning> + <para>Before rebooting with the <filename>GENERIC</filename> kernel, + make sure it contains all drivers required for your system to boot + properly (and connect to the network, if the machine that is being + updated is accessed remotely). In particular, if the previously + running custom kernel contained built-in functionality usually + provided by kernel modules, make sure to temporarily load these + modules into the <filename>GENERIC</filename> kernel using the + <filename>/boot/loader.conf</filename> facility. You may also wish + to disable non-essential services, disk and network mounts, etc. + until the upgrade process is complete.</para> + </warning> + + <para>The machine should now be restarted with the updated kernel:</para> + + <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen> + + <para>Once the system has come back online, + <command>freebsd-update</command> will need to be started + again. The state of the process has been saved and thus, + <command>freebsd-update</command> will not start from the + beginning, but will remove all old shared libraries and object + files. To continue to this stage, issue the following + command:</para> + + <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> + + <note> + <para>Depending on whether any libraries version numbers got + bumped, there may only be two install phases instead of + three.</para> + </note> + + <para>All third party software will now need to be rebuilt and + re-installed. This is required as installed software may + depend on libraries which have been removed during the upgrade + process. The + <filename role="package">ports-mgmt/portupgrade</filename> + command may be used to automate this process. The following + commands may be used to begin this process:</para> + + <screen>&prompt.root; <userinput>portupgrade -f ruby</userinput> +&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db</userinput> +&prompt.root; <userinput>portupgrade -f ruby18-bdb</userinput> +&prompt.root; <userinput>rm /var/db/pkg/pkgdb.db /usr/ports/INDEX-*.db</userinput> +&prompt.root; <userinput>portupgrade -af</userinput></screen> + + <para>Once this has completed, finish the upgrade process with a + final call to <command>freebsd-update</command>. Issue the + following command to tie up all loose ends in the upgrade + process:</para> + + <screen>&prompt.root; <userinput>freebsd-update install</userinput></screen> + + <para>If the <filename>GENERIC</filename> kernel was temporarily used, + this is the time to build and install a new custom kernel in the + usual way.</para> + + <para>Reboot the machine into the new &os; version. The process + is complete.</para> + </sect2> + + <sect2 id="freebsdupdate-system-comparison"> + <title>System State Comparison</title> + + <para>The <command>freebsd-update</command> utility may be used + to test the state of the installed &os; version against a + known good copy. This option evaluates the current version + of system utilities, libraries, and configuration files. + To begin the comparison, issue the following command:</para> + + <screen>&prompt.root; <userinput>freebsd-update IDS >> outfile.ids</userinput></screen> + + <warning> + <para>While the command name is <acronym>IDS</acronym> it should + in no way be a replacement for an intrusion detection system + such as <filename role="package">security/snort</filename>. + As <command>freebsd-update</command> stores data on disk, the + possibility of tampering is evident. While this possibility + may be reduced by using the + <varname>kern.securelevel</varname> setting and storing the + <command>freebsd-update</command> data on a read only file + system when not in use, a better solution would be to + compare the system against a secure disk, such as a + <acronym>DVD</acronym> or securely stored external + <acronym>USB</acronym> disk device.</para> + </warning> + + <para>The system will now be inspected, and a list of files + along with their &man.sha256.1; hash values, both the known value + in the release and the current installed value, will be printed. This is why + the output has been sent to the + <filename>outfile.ids</filename> file. It scrolls by too + quickly for eye comparisons, and soon it fills up the console + buffer.</para> + + <para>These lines are also extremely long, but the output format + may be parsed quite easily. For instance, to obtain a list of + all files different from those in the release, issue the + following command:</para> + + <screen>&prompt.root; <userinput>cat outfile.ids | awk '{ print $1 }' | more</userinput> +/etc/master.passwd +/etc/motd +/etc/passwd +/etc/pf.conf</screen> + + <para>This output has been truncated, many more files exist. + Some of these files have natural modifications, the + <filename>/etc/passwd</filename> has been modified because + users have been added to the system. In some cases, there + may be other files, such as kernel modules, which differ + as <command>freebsd-update</command> may have updated them. + To exclude specific files or directories, add them to the + <literal>IDSIgnorePaths</literal> option in + <filename>/etc/freebsd-update.conf</filename>.</para> + + <para>This system may be used as part of an elaborate upgrade + method, aside from the previously discussed version.</para> + </sect2> + </sect1> + + <sect1 id="updating-upgrading-portsnap"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Colin</firstname> + <surname>Percival</surname> + <contrib>Based on notes provided by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Portsnap: A Ports Collection Update Tool</title> + + <indexterm><primary>Updating and Upgrading</primary></indexterm> + <indexterm> + <primary>Portsnap</primary> + <see>Updating and Upgrading</see> + </indexterm> + + <para>The base system of &os; includes a utility for updating + the Ports Collection too: the &man.portsnap.8; utility. Upon + execution, it will connect to a remote site, verify the secure + key, and download a new copy of the Ports Collection. The key + is used to verify the integrity of all downloaded files, ensuring + they have not been modified in-flight. To download the latest + Ports Collection files, issue the following command:</para> + + <screen>&prompt.root; <userinput>portsnap fetch</userinput> +Looking up portsnap.FreeBSD.org mirrors... 3 mirrors found. +Fetching snapshot tag from portsnap1.FreeBSD.org... done. +Fetching snapshot metadata... done. +Updating from Wed Aug 6 18:00:22 EDT 2008 to Sat Aug 30 20:24:11 EDT 2008. +Fetching 3 metadata patches.. done. +Applying metadata patches... done. +Fetching 3 metadata files... done. +Fetching 90 patches.....10....20....30....40....50....60....70....80....90. done. +Applying patches... done. +Fetching 133 new ports or files... done.</screen> + + <para>What this example shows is that &man.portsnap.8; + has found and verified + several patches to the current ports data. This also indicates + that the utility was run previously, if it was a first time + run, the collection would have simply been downloaded.</para> + + <para>When &man.portsnap.8; successfully completes + a <command>fetch</command> operation, the Ports Collection and + subsequent patches exist on the local system that have passed + verification. The first time <command>portsnap</command> is executed, + you have to use <literal>extract</literal> to install the + downloaded files:</para> + + <screen>&prompt.root; <userinput>portsnap extract</userinput> +/usr/ports/.cvsignore +/usr/ports/CHANGES +/usr/ports/COPYRIGHT +/usr/ports/GIDs +/usr/ports/KNOBS +/usr/ports/LEGAL +/usr/ports/MOVED +/usr/ports/Makefile +/usr/ports/Mk/bsd.apache.mk +/usr/ports/Mk/bsd.autotools.mk +/usr/ports/Mk/bsd.cmake.mk +<replaceable>...</replaceable></screen> + + <para>To update an already installed Ports Collection use the command + <command>portsnap update</command>:</para> + + <screen>&prompt.root; <userinput>portsnap update</userinput></screen> + + <para>The process is now complete, and applications may be + installed or upgraded using the updated Ports Collection.</para> + + <para>The <literal>fetch</literal> and <literal>extract</literal> or + <literal>update</literal> operations may be run consecutively, as + shown in the following example:</para> + + <screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen> + + <para>This command will download the latest version of the + Ports Collection and update your local version under + <filename class="directory">/usr/ports</filename>.</para> + </sect1> + + <sect1 id="updating-upgrading-documentation"> + <title>Updating the Documentation Set</title> + + <indexterm><primary>Updating and Upgrading</primary></indexterm> + + <indexterm> + <primary>Documentation</primary> + <see>Updating and Upgrading</see> + </indexterm> + + <para>Besides the base system and the Ports Collection, + documentation is an integral part of the &os; operating system. + While an up-to-date version of the &os; Documentation Set is + always available on the <ulink + url="http://www.freebsd.org/doc/">&os; web site</ulink>, some + users might have slow or no permanent network connectivity at all. + Fortunately, there are several ways to update the documentation + shipped with each release by maintaining a local copy of the + latest &os; Documentation Set.</para> + + <sect2 id="csup-doc"> + <title>Using CVSup to Update the Documentation</title> + + <para>The sources and the installed copy of the &os; documentation + can be updated with <application>CVSup</application>, using a + mechanism similar to the one employed for the base system + sources (c.f. <xref linkend="makeworld">). This section + describes:</para> + + <itemizedlist> + <listitem> + <para>How to install the documentation toolchain, the tools + that are required to rebuild the &os; documentation from its + source.</para> + </listitem> + + <listitem> + <para>How to download a copy of the documentation source + at <filename class="directory">/usr/doc</filename>, + using <application>CVSup</application>.</para> + </listitem> + + <listitem> + <para>How to rebuild the &os; documentation from its source, + and install it + under <filename class="directory">/usr/share/doc</filename>.</para> + </listitem> + + <listitem> + <para>Some of the build options that are supported by the + build system of the documentation, i.e., the options that + build only some of the different language translations of + the documentation or the options that select a specific + output format.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2 id="installing-documentation-toolchain"> + <title>Installing CVSup and the Documentation Toolchain</title> + + <para>Rebuilding the &os; documentation from source requires a + fairly large collection of tools. These tools are not part of + the &os; base system, because they need a large amount of disk + space and they are not useful to all &os; users; they are only + useful to those users that are actively writing new + documentation for &os; or are frequently updating their + documentation from source.</para> + + <para>All the required tools are available as part of the Ports + Collection. The <filename + role="package">textproc/docproj</filename> port is a master + port that has been developed by the &os; Documentation Project, + to ease the initial installation and future updates of these + tools.</para> + + <note> + <para>When no &postscript; or PDF documentation required, one + might consider installing the <filename + role="package">textproc/docproj-nojadetex</filename> port + instead. This version of the documentation toolchain includes + everything except the <application>teTeX</application> + typesetting engine. <application>teTeX</application> is a + very large collection of tools, so it may be quite sensible to + omit its installation if PDF output is not really + necessary.</para> + </note> + + <para>For more information on installing and using + <application>CVSup</application>, see <link + linkend="cvsup">Using CVSup</link>.</para> + </sect2> + + <sect2 id="updating-documentation-sources"> + <title>Updating the Documentation Sources</title> + + <para>The <application>CVSup</application> utility can fetch a + clean copy of the documentation sources, using + the <filename>/usr/share/examples/cvsup/doc-supfile</filename> + file as a configuration template. The default update host is + set to a placeholder value in <filename>doc-supfile</filename>, + but &man.cvsup.1; accepts a host name through the command line, + so the documentation sources can be fetched from one of the + <application>CVSup</application> servers by typing:</para> + + <screen>&prompt.root; <userinput>cvsup -h <replaceable>cvsup.FreeBSD.org</replaceable> -g -L 2 <filename>/usr/share/examples/cvsup/doc-supfile</filename></userinput></screen> + + <para>Change <replaceable>cvsup.FreeBSD.org</replaceable> to the + nearest <application>CVSup</application> server. See <xref + linkend="cvsup-mirrors"> for a complete listing of mirror + sites.</para> + + <para>The initial download of the documentation sources may take a + while. Let it run until it completes.</para> + + <para>Future updates of the documentation sources may be fetched + by running the same command. + The <application>CVSup</application> utility downloads and + copies only the updates since the last time it ran, so every run + of <application>CVSup</application> after the first complete run + should be pretty fast.</para> + + <para>After checking out the sources, an alternative way of + updating the documentation is supported by the + <filename>Makefile</filename> of the <filename + class="directory">/usr/doc</filename> directory. By setting + <makevar>SUP_UPDATE</makevar>, <makevar>SUPHOST</makevar> and + <makevar>DOCSUPFILE</makevar> in the + <filename>/etc/make.conf</filename> file, it is possible to + run:</para> + + <screen>&prompt.root; <userinput>cd /usr/doc</userinput> +&prompt.root; <userinput>make update</userinput></screen> + + <para>A typical set of these &man.make.1; options + for <filename>/etc/make.conf</filename> is:</para> + + <programlisting>SUP_UPDATE= yes +SUPHOST?= cvsup.freebsd.org +DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile</programlisting> + + <note> + <para>Setting the <makevar>SUPHOST</makevar> + and <makevar>DOCSUPFILE</makevar> value + with <literal>?=</literal> permits overriding them in the + command-line of make. This is the recommended way of adding + options to <filename>make.conf</filename>, to avoid having to + edit the file every time a different option value has to be + tested.</para> + </note> + </sect2> + + <sect2 id="updating-documentation-options"> + <title>Tunable Options of the Documentation Sources</title> + + <para>The updating and build system of the &os; documentation + supports a few options that ease the process of updating only + parts of the documentation, or the build of specific + translations. These options can be set either as system-wide + options in the <filename>/etc/make.conf</filename> file, or as + command-line options passed to the &man.make.1; utility.</para> + + <para>The following options are some of these:</para> + + <variablelist> + <varlistentry> + <term><makevar>DOC_LANG</makevar></term> + + <listitem> + <para>The list of languages and encodings to build and + install, e.g., <literal>en_US.ISO8859-1</literal> for the + English documentation only.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><makevar>FORMATS</makevar></term> + + <listitem> + <para>A single format or a list of output formats to be + built. Currently, <literal>html</literal>, + <literal>html-split</literal>, <literal>txt</literal>, + <literal>ps</literal>, <literal>pdf</literal>, + and <literal>rtf</literal> are supported.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><makevar>SUPHOST</makevar></term> + + <listitem> + <para>The hostname of the <application>CVSup</application> + server to use when updating.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><makevar>DOCDIR</makevar></term> + + <listitem> + <para>Where to install the documentation. It defaults to + <filename + class="directory">/usr/share/doc</filename>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>For more make variables supported as system-wide options in + &os;, see &man.make.conf.5;.</para> + + <para>For more make variables supported by the build system of the + &os; documentation, please refer to + the <ulink url="&url.doc.langbase;/books/fdp-primer">&os; + Documentation Project Primer for New Contributors</ulink>.</para> + </sect2> + + <sect2 id="updating-installed-documentation"> + <title>Installing the &os; Documentation from Source</title> + + <para>When an up-to-date snapshot of the documentation sources has + been fetched in <filename class="directory">/usr/doc</filename>, + everything is ready for an update of the installed + documentation.</para> + + <para>A full update of all the languages defined in + the <makevar>DOC_LANG</makevar> makefile option may be done by + typing:</para> + + <screen>&prompt.root; <userinput>cd /usr/doc</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>If <filename>make.conf</filename> has been set up with the + correct <makevar>DOCSUPFILE</makevar>, <makevar>SUPHOST</makevar> + and <makevar>SUP_UPDATE</makevar> options, the install step may + be combined with an update of the documentation sources by + typing:</para> + + <screen>&prompt.root; <userinput>cd /usr/doc</userinput> +&prompt.root; <userinput>make update install clean</userinput></screen> + + <para>If an update of only a specific language is desired, + &man.make.1; can be invoked in a language specific subdirectory + of <filename class="directory">/usr/doc</filename>, i.e.:</para> + + <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput> +&prompt.root; <userinput>make update install clean</userinput></screen> + + <para>The output formats that will be installed may be specified + by setting the <makevar>FORMATS</makevar> make variable, + i.e.:</para> + + <screen>&prompt.root; <userinput>cd /usr/doc</userinput> +&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen> + </sect2> + + <sect2 id="doc-ports"> + <sect2info> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + <contrib>Based on the work of </contrib> + </author> + </authorgroup> + </sect2info> + + <title>Using Documentation Ports</title> + + <indexterm><primary>Updating and Upgrading</primary></indexterm> + + <indexterm> + <primary>documentation package</primary> + <see>Updating and Upgrading</see> + </indexterm> + + <para>In the previous section, we have presented a method for + updating the &os; documentation from sources. Source based + updates may not be feasible or practical for all &os; systems + though. Building the documentation sources requires a fairly + large collection of tools and utilities, the + <emphasis>documentation toolchain</emphasis>, a certain level of + familiarity with <application>CVS</application> and source + checkouts from a repository, and a few manual steps to build the + checked out sources. In this section, we describe an + alternative way of updating the installed copies of the &os; + documentation; one that uses the Ports Collection and makes + it possible to:</para> + + <itemizedlist> + <listitem> + <para>Download and install pre-built snaphots of the + documentation, without having to locally build anything + (eliminating this way the need for an installation of the + entire documentation toolchain).</para> + </listitem> + + <listitem> + <para>Download the documentation sources and build them + through the ports framework (making the checkout and build + steps a bit eaiser).</para> + </listitem> + </itemizedlist> + + <para>These two methods of updating the &os; documentation are + supported by a set of <emphasis>documentation ports</emphasis>, + updated by the &a.doceng; on a monthly basis. These are listed + in the &os; Ports Collection, under the virtual category + named <ulink + url="http://www.freshports.org/docs/">docs</ulink>.</para> + + <sect3 id="doc-ports-install-make"> + <title>Building and Installing Documentation Ports</title> + + <para>The documentation ports use the ports building framework + to make documentation builds easier. They automate the + process of checking out the documentation source, running + &man.make.1; with the appropriate environment settings and + command-line options, and they make the installation or + deinstallation of documentation as easy as the installation of + any other &os; port or package.</para> + + <note> + <para>As an extra feature, when the documentation ports are + built locally, they record a dependency to the + <emphasis>documentation toolchain</emphasis> ports, so the + latter is automatically installed too.</para> + </note> + + <para>Organization of the documentation ports is as follows:</para> + + <itemizedlist> + <listitem> + <para>There is a <quote>master port</quote>, <filename + role="package">misc/freebsd-doc-en</filename>, where the + documentation port files can be found. It is the base of + all documentation ports. By default, it builds the + English documentation only.</para> + </listitem> + + <listitem> + <para>There is an <quote>all in one port</quote>, <filename + role="package">misc/freebsd-doc-all</filename>, and it + builds and installs all documentation in all available + languages.</para> + </listitem> + + <listitem> + <para>Finally, there is a <quote>slave port</quote> for + each translation, e.g.: <filename + role="package">misc/freebsd-doc-hu</filename> for the + Hungarian-language documents. All of them depend on the + master port and install the translated documentation of + the respective language.</para> + </listitem> + </itemizedlist> + + <para>To install a documentation port from source, issue the + following commands (as <username>root</username>):</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>This will build and install the English documentation in + split <acronym>HTML</acronym> format (the same as used on <ulink + url="http://www.FreeBSD.org"></ulink>) in the <filename + class="directory">/usr/local/share/doc/freebsd</filename> + directory.</para> + + <sect4 id="doc-ports-options"> + <title>Common Knobs and Options</title> + + <para>There are many options for modifying the default + behavior of the documentation ports. The following is just + a short list:</para> + + <variablelist> + <varlistentry> + <term><makevar>WITH_HTML</makevar></term> + + <listitem> + <para>Allows the build of the HTML format: a single HTML + file per document. The formatted documentation is + saved to a file called + <filename>article.html</filename>, or + <filename>book.html</filename>, as appropriate, plus + images.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><makevar>WITH_PDF</makevar></term> + + <listitem> + <para>Allows the build of the &adobe; Portable Document + Format, for use with &adobe; &acrobat.reader;, + <application>Ghostscript</application> or other PDF + readers. The formatted documentation is saved to a + file called <filename>article.pdf</filename> or + <filename>book.pdf</filename>, as appropriate.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><makevar>DOCBASE</makevar></term> + + <listitem> + <para>Where to install the documentation. It defaults + to <filename + class="directory">/usr/local/share/doc/freebsd</filename>.</para> + + <note> + <para>Notice that the default target directory + differs from the directory used by the + <application>CVSup</application> method. This is + because we are installing a port, and ports are + usually installed under the <filename + class="directory">/usr/local</filename> directory. + This can be overridden by adding the + <makevar>PREFIX</makevar> variable.</para> + </note> + </listitem> + </varlistentry> + </variablelist> + + <para>Here is a brief example on how to use the variables + mentioned above to install the Hungarian documentation in + Portable Document Format:</para> + + <screen>&prompt.root; cd /usr/ports/misc/freebsd-doc-hu +&prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean</screen> + </sect4> + </sect3> + + <sect3 id="doc-ports-install-package"> + <title>Using Documentation Packages</title> + + <para>Building the documentation ports from source, as described + in the previous section, requires a local installation of the + documentation toolchain and a bit of disk space for the build + of the ports. When resources are not available to install the + documentation toolchain, or because the build from sources + would take too much disk space, it is still possible to + install pre-built snapshots of the documentation ports.</para> + + <para>The &a.doceng; prepares monthly snapshots of the &os; + documentation packages. These binary packages can be used + with any of the bundled package tools, like &man.pkg.add.1;, + &man.pkg.delete.1;, and so on.</para> + + <note> + <para>When binary packages are used, the &os; documentation + will be installed in <emphasis>all</emphasis> available + formats for the given language.</para> + </note> + + <para>For example, the following command will install the latest + pre-built package of the Hungarian documentation:</para> + + <screen>&prompt.root; <userinput>pkg_add -r hu-freebsd-doc</userinput></screen> + + <note> + <para>Packages have the following name format that differs + from the corresponding port's name: + <literal><replaceable>lang</replaceable>-freebsd-doc</literal>. + Here <replaceable>lang</replaceable> is the short format of + the language code, i.e., <literal>hu</literal> for + Hungarian, or <literal>zh_cn</literal> for Simplified + Chinese.</para> + </note> + </sect3> + + <sect3 id="doc-ports-update"> + <title>Updating Documentation Ports</title> + + <para>To update a previously installed documentation port, any + tool suitable for updating ports is sufficient. For example, + the following command updates the installed Hungarian + documentation via the <filename + role="package">ports-mgmt/portupgrade</filename> tool by + using packages only:</para> + + <screen>&prompt.root; <userinput>portupgrade -PP hu-freebsd-doc</userinput></screen> + </sect3> + </sect2> + +<!-- FIXME: Waiting for a working docsnap server... --> +<![ IGNORE [ + <sect2 id="docsnap"> + <sect2info> + <authorgroup> + <author> + <firstname>Pav</firstname> + <surname>Lucistnik</surname> + <contrib>Based on information provided by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>Using Docsnap</title> + + <indexterm><primary>Updating and Upgrading</primary></indexterm> + + <indexterm> + <primary>Docsnap</primary> + <see>Updating and Upgrading</see> + </indexterm> + + <para><application>Docsnap</application> is an &man.rsync.1; + repository for updating installed &os; Documentation in a + relatively easy and fast way. A + <quote><application>Docsnap</application> server</quote> tracks + the documentation sources, and builds them in HTML format every + hour. The <filename role="package">textproc/docproj</filename> + is unneeded with <application>Docsnap</application> as only + patches to the built documentation exist.</para> + + <para>The only requirement for using this technique is + the <filename role="package">net/rsync</filename> port or + package. To add it, use the following command:</para> + + <screen>&prompt.root; <userinput>pkg_add -r rsync</userinput></screen> + + <note> + <para><application>Docsnap</application> has been originally + developed for updating documentation installed + to <filename class="directory">/usr/share/doc</filename>, but + the following examples could be adapted for other directories + as well. For user directories, it does not require + <username>root</username> privileges.</para> + </note> + + <para>To update the documentation set, issue the following + command:</para> + + <screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap <replaceable>/usr/share/doc</replaceable></userinput></screen> + + <note> + <para>There is only one <application>Docsnap</application> + server at the moment; + the <hostid>docsnap.sk.FreeBSD.org</hostid> shown + above.</para> + </note> + + <para>Do not use the <option>--delete</option> flag here as there + are some items installed + into <filename class="directory">/usr/share/doc</filename> + during <command>make installworld</command>, which would + accidentally be removed. To clean up, use this command + instead:</para> + + <screen>&prompt.root; <userinput>rsync -rltvz --delete <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap/??_??\.\* <replaceable>/usr/share/doc</replaceable></userinput></screen> + + <para>If a subset of documentation needs to be updated, for + example, the English documentation only, the following command + should be used:</para> + + <screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap/en_US.ISO8859-1 <replaceable>/usr/share/doc</replaceable></userinput></screen> + </sect2> +]]> + </sect1> + + <sect1 id="current-stable"> + <title>Tracking a Development Branch</title> + <indexterm><primary>-CURRENT</primary></indexterm> + <indexterm><primary>-STABLE</primary></indexterm> + + <para>There are two development branches to FreeBSD: &os.current; and + &os.stable;. This section will explain a bit about each and describe + how to keep your system up-to-date with each respective tree. + &os.current; will be discussed first, then &os.stable;.</para> + + <sect2 id="current"> + <title>Staying Current with &os;</title> + + <para>As you read this, keep in mind that &os.current; is the + <quote>bleeding edge</quote> of &os; development. + &os.current; users are expected to have a high degree of + technical skill, and should be capable of solving difficult + system problems on their own. If you are new to &os;, think + twice before installing it.</para> + + <sect3> + <title>What Is &os.current;?</title> + <indexterm><primary>snapshot</primary></indexterm> + + <para>&os.current; is the latest working sources for &os;. + This includes work in progress, experimental changes, and + transitional mechanisms that might or might not be present + in the next official release of the software. While many + &os; developers compile the &os.current; source code daily, + there are periods of time when the sources are not + buildable. These problems are resolved as expeditiously as + possible, but whether or not &os.current; brings disaster or + greatly desired functionality can be a matter of which exact + moment you grabbed the source code in!</para> + </sect3> + + <sect3> + <title>Who Needs &os.current;?</title> + + <para>&os.current; is made available for 3 primary + interest groups:</para> + + <orderedlist> + <listitem> + <para>Members of the &os; community who are actively working + on some part of the source tree and for whom keeping + <quote>current</quote> is an absolute + requirement.</para> + </listitem> + + <listitem> + <para>Members of the &os; community who are active testers, + willing to spend time solving problems in order to + ensure that &os.current; remains as sane as possible. + These are also people who wish to make topical + suggestions on changes and the general direction of + &os;, and submit patches to implement them.</para> + </listitem> + + <listitem> + <para>Those who merely wish to keep an eye on things, or + to use the current sources for reference purposes + (e.g., for <emphasis>reading</emphasis>, not running). + These people also make the occasional comment or + contribute code.</para> + </listitem> + </orderedlist> + </sect3> + + <sect3> + <title>What Is &os.current; <emphasis>Not</emphasis>?</title> + + <orderedlist> + <listitem> + <para>A fast-track to getting pre-release bits because you + heard there is some cool new feature in there and you + want to be the first on your block to have it. Being + the first on the block to get the new feature means that + you are the first on the block to get the new + bugs.</para> + </listitem> + + <listitem> + <para>A quick way of getting bug fixes. Any given version + of &os.current; is just as likely to introduce new bugs + as to fix existing ones.</para> + </listitem> + + <listitem> + <para>In any way <quote>officially supported</quote>. We + do our best to help people genuinely in one of the 3 + <quote>legitimate</quote> &os.current; groups, but we + simply <emphasis>do not have the time</emphasis> to + provide tech support. This is not because we are mean + and nasty people who do not like helping people out (we + would not even be doing &os; if we were). We simply + cannot answer hundreds messages a day + <emphasis>and</emphasis> work on FreeBSD! Given the + choice between improving &os; and answering lots of + questions on experimental code, the developers opt for + the former.</para> + </listitem> + </orderedlist> + </sect3> + + <sect3> + <title>Using &os.current;</title> + + <indexterm> + <primary>-CURRENT</primary> + <secondary>using</secondary> + </indexterm> + <orderedlist> + <listitem> + <para>Join the &a.current.name; and the &a.svn-src-head.name; + lists. This is not just a good idea, it is + <emphasis>essential</emphasis>. If you are not on the + <emphasis>&a.current.name;</emphasis> list, you will not see + the comments that people are making about the current state of + the system and thus will probably end up stumbling over a lot + of problems that others have already found and solved. Even + more importantly, you will miss out on important bulletins + which may be critical to your system's continued health.</para> + + <para>The &a.svn-src-head.name; list will allow you to see the + commit log entry for each change as it is made, along with + any pertinent information on possible side-effects.</para> + + <para>To join these lists, or one of the others available + go to &a.mailman.lists.link; and click on the list that + you wish to subscribe to. Instructions on the rest of + the procedure are available there. If you are interested + in tracking changes for the whole source tree, we would + recommend subscribing to the &a.svn-src-all.name; list.</para> + </listitem> + + <listitem> + <para>Grab the sources from a &os; <link linkend="mirrors">mirror + site</link>. You can do this in one of two ways:</para> + + <orderedlist> + <indexterm> + <primary><command>cvsup</command></primary> + </indexterm> + <indexterm> + <primary><command>cron</command></primary> + </indexterm> + <indexterm> + <primary>-CURRENT</primary> + <secondary>Syncing with <application>CVSup</application></secondary> + </indexterm> + + <listitem> + <para>Use the <link linkend="cvsup">cvsup</link> program + with the <filename>supfile</filename> named + <filename>standard-supfile</filename> + available from + <filename>/usr/share/examples/cvsup</filename>. + This is the most recommended method, since it allows you to + grab the entire collection once and then only what has + changed from then on. Many people run + <command>cvsup</command> from <command>cron</command> and + keep their sources up-to-date automatically. You have to + customize the sample <filename>supfile</filename> above, + and configure <link + linkend="cvsup">cvsup</link> for your environment.</para> + + <note> + <para>The sample <filename>standard-supfile</filename> is + intended for tracking a specific security branch of + &os;, and not &os.current;. You will need to edit this + file and replace the following line:</para> + + <programlisting>*default release=cvs tag=RELENG_<replaceable>X</replaceable>_<replaceable>Y</replaceable></programlisting> + + <para>With this one:</para> + + <programlisting>*default release=cvs tag=.</programlisting> + + <para>For a detailed explanation of usable tags, please + refer to the Handbook's <link + linkend="cvs-tags">CVS Tags</link> section.</para> + </note> + </listitem> + + <indexterm> + <primary>-CURRENT</primary> + <secondary>Syncing with CTM</secondary> + </indexterm> + <listitem> + <para>Use the <application><link + linkend="ctm">CTM</link></application> facility. If you + have very bad connectivity (high price connections or + only email access) <application>CTM</application> is an + option. However, it is a lot of hassle and can give you + broken files. This leads to it being rarely used, which + again increases the chance of it not working for fairly + long periods of time. We recommend using + <application><link linkend="cvsup">CVSup</link></application> + for anybody with a 9600 bps modem or faster + connection.</para> + </listitem> + </orderedlist> + </listitem> + + <listitem> + <para>If you are grabbing the sources to run, and not just + look at, then grab <emphasis>all</emphasis> of &os.current;, not + just selected portions. The reason for this is that various + parts of the source depend on updates elsewhere, and trying + to compile just a subset is almost guaranteed to get you + into trouble.</para> + + <indexterm> + <primary>-CURRENT</primary> + <secondary>compiling</secondary> + </indexterm> + <para>Before compiling &os.current;, read the + <filename>Makefile</filename> in <filename>/usr/src</filename> + carefully. You should at least <link + linkend="makeworld">install a new kernel and rebuild the + world</link> the first time through + as part of the upgrading process. Reading the &a.current; + and <filename>/usr/src/UPDATING</filename> will keep you + up-to-date on other bootstrapping procedures that sometimes + become necessary as we move toward the next release.</para> + </listitem> + + <listitem> + <para>Be active! If you are running &os.current;, we want + to know what you have to say about it, especially if you + have suggestions for enhancements or bug fixes. Suggestions + with accompanying code are received most + enthusiastically!</para> + </listitem> + </orderedlist> + </sect3> + </sect2> + + <sect2 id="stable"> + <title>Staying Stable with &os;</title> + + <sect3> + <title>What Is &os.stable;?</title> + <indexterm><primary>-STABLE</primary></indexterm> + + <para>&os.stable; is our development branch from which major releases + are made. Changes go into this branch at a different pace, and + with the general assumption that they have first gone into + &os.current; for testing. This is <emphasis>still</emphasis> + a development branch, however, and this means that at any given + time, the sources for &os.stable; may or may not be suitable for any + particular purpose. It is simply another engineering development + track, not a resource for end-users.</para> + </sect3> + + <sect3> + <title>Who Needs &os.stable;?</title> + + <para>If you are interested in tracking or contributing to the + FreeBSD development process, especially as it relates to the + next <quote>point</quote> release of FreeBSD, then you should + consider following &os.stable;.</para> + + <para>While it is true that security fixes also go into the + &os.stable; branch, you do not <emphasis>need</emphasis> to + track &os.stable; to do this. Every security advisory for + FreeBSD explains how to fix the problem for the releases it + affects + <footnote><para>That is not quite true. We can not continue to + support old releases of FreeBSD forever, although we do + support them for many years. For a complete description + of the current security policy for old releases of + FreeBSD, please see <ulink + url="&url.base;/security/">http://www.FreeBSD.org/security/</ulink>.</para> + </footnote>, + and tracking an entire development branch just + for security reasons is likely to bring in a lot of unwanted + changes as well.</para> + + <para>Although we endeavor to ensure that the &os.stable; branch + compiles and runs at all times, this cannot be guaranteed. In + addition, while code is developed in &os.current; before including + it in &os.stable;, more people run &os.stable; than &os.current;, so + it is inevitable that bugs and corner cases will sometimes be found + in &os.stable; that were not apparent in &os.current;.</para> + + <para>For these reasons, we do <emphasis>not</emphasis> recommend that + you blindly track &os.stable;, and it is particularly important that + you do not update any production servers to &os.stable; without + first thoroughly testing the code in your development + environment.</para> + + <para>If you do not have the resources to do this then we recommend + that you run the most recent release of FreeBSD, and use the binary + update mechanism to move from release to release.</para> + </sect3> + + <sect3> + <title>Using &os.stable;</title> + + <indexterm> + <primary>-STABLE</primary> + <secondary>using</secondary> + </indexterm> + <orderedlist> + <listitem> + <para>Join the &a.stable.name; list. This will keep you informed + of build-dependencies that may appear in &os.stable; + or any other issues requiring special attention. Developers + will also make announcements in this mailing list when they are + contemplating some controversial fix or update, giving the + users a chance to respond if they have any issues to raise + concerning the proposed change.</para> + + <para>Join the relevant <application>SVN</application> list for + the branch you are tracking. For example, if you are tracking + the 7-STABLE branch, join the &a.svn-src-stable-7.name; list. + This will allow you to view the commit log entry for each + change as it is made, along with any pertinent information on + possible side-effects.</para> + + <para>To join these lists, or one of the others available + go to &a.mailman.lists.link; and click on the list that + you wish to subscribe to. Instructions on the rest of + the procedure are available there. If you are interested + in tracking changes for the whole source tree, we would + recommend subscribing to the &a.svn-src-all.name; list.</para> + </listitem> + + <listitem> + <para>If you are going to install a new system and want it + to run monthly snapshot built from &os.stable;, please + check the <ulink + url="&url.base;/snapshots/">Snapshots</ulink> web page for + more information. Alternatively, it is possible to + install the most recent &os.stable; release from the + <link linkend="mirrors">mirror sites</link> and follow + the instructions below to upgrade your system to the + most up to date &os.stable; source code.</para> + + <para>If you are already running a previous release of &os; + and wish to upgrade via sources then you can easily do so + from &os; <link linkend="mirrors">mirror site</link>. This can + be done in one of two ways:</para> + + <orderedlist> + <indexterm> + <primary><command>cvsup</command></primary> + </indexterm> + <indexterm> + <primary><command>cron</command></primary> + </indexterm> + <indexterm> + <primary>-STABLE</primary> + <secondary>syncing with <application>CVSup</application></secondary> + </indexterm> + <listitem> + <para>Use the <link linkend="cvsup">cvsup</link> program + with the <filename>supfile</filename> named + <filename>stable-supfile</filename> from the directory + <filename>/usr/share/examples/cvsup</filename>. + This is the most recommended method, since it allows you to + grab the entire collection once and then only what has + changed from then on. Many people run + <command>cvsup</command> from <command>cron</command> to + keep their sources up-to-date automatically. You have to + customize the sample <filename>supfile</filename> above, + and configure <link linkend="cvsup">cvsup</link> for your + environment.</para> + </listitem> + + <indexterm> + <primary>-STABLE</primary> + <secondary>syncing with CTM</secondary> + </indexterm> + <listitem> + <para>Use the <application><link + linkend="ctm">CTM</link></application> facility. If + you do not have a fast and inexpensive connection to + the Internet, this is the method you should consider + using.</para> + </listitem> + </orderedlist> + </listitem> + + <listitem> + <para>Essentially, if you need rapid on-demand access to the + source and communications bandwidth is not a consideration, + use <command>cvsup</command> or <command>ftp</command>. + Otherwise, use <application>CTM</application>.</para> + </listitem> + + <indexterm> + <primary>-STABLE</primary> + <secondary>compiling</secondary> + </indexterm> + <listitem> + <para>Before compiling &os.stable;, read the + <filename>Makefile</filename> in <filename>/usr/src</filename> + carefully. You should at least <link + linkend="makeworld">install a new kernel and rebuild the + world</link> the first time through + as part of the upgrading process. Reading the &a.stable; and + <filename>/usr/src/UPDATING</filename> will keep you up-to-date + on other bootstrapping procedures that sometimes become + necessary as we move toward the next release.</para> + </listitem> + </orderedlist> + </sect3> + </sect2> + </sect1> + + <sect1 id="synching"> + <title>Synchronizing Your Source</title> + + <para>There are various ways of using an Internet (or email) + connection to stay up-to-date with any given area of the &os; + project sources, or all areas, depending on what interests you. The + primary services we offer are <link linkend="anoncvs">Anonymous + CVS</link>, <link linkend="cvsup">CVSup</link>, and <link + linkend="ctm">CTM</link>.</para> + + <warning> + <para>While it is possible to update only parts of your source tree, + the only supported update procedure is to update the entire tree + and recompile both userland (i.e., all the programs that run in + user space, such as those in <filename>/bin</filename> and + <filename>/sbin</filename>) and kernel sources. Updating only part + of your source tree, only the kernel, or only userland will often + result in problems. These problems may range from compile errors + to kernel panics or data corruption.</para> + </warning> + + <indexterm> + <primary>CVS</primary> + <secondary>anonymous</secondary> + </indexterm> + + <para><application>Anonymous CVS</application> and + <application>CVSup</application> use the <emphasis>pull</emphasis> + model of updating sources. In the case of + <application>CVSup</application> the user (or a + <command>cron</command> script) invokes + the <command>cvsup</command> program, and it interacts with a + <command>cvsupd</command> server somewhere to bring your files + up-to-date. The updates you receive are up-to-the-minute and you + get them when, and only when, you want them. You can easily + restrict your updates to the specific files or directories that are + of interest to you. Updates are generated on the fly by the server, + according to what you have and what you want to have. + <application>Anonymous CVS</application> is quite a bit more + simplistic than <application>CVSup</application> in that it is just an + extension to <application>CVS</application> which allows it to pull + changes directly from a remote CVS repository. + <application>CVSup</application> can do this far more efficiently, + but <application>Anonymous CVS</application> is easier to use.</para> + + <indexterm> + <primary><application>CTM</application></primary> + </indexterm> + <para><application>CTM</application>, on the other hand, does not + interactively compare the sources you have with those on the master + archive or otherwise pull them across. Instead, a script which + identifies changes in files since its previous run is executed + several times a day on the master CTM machine, any detected changes + being compressed, stamped with a sequence-number and encoded for + transmission over email (in printable ASCII only). Once received, + these <quote>CTM deltas</quote> can then be handed to the + &man.ctm.rmail.1; utility which will automatically decode, verify + and apply the changes to the user's copy of the sources. This + process is far more efficient than <application>CVSup</application>, + and places less strain on our server resources since it is a + <emphasis>push</emphasis> rather than a <emphasis>pull</emphasis> + model.</para> + + <para>There are other trade-offs, of course. If you inadvertently + wipe out portions of your archive, <application>CVSup</application> + will detect and rebuild the damaged portions for you. + <application>CTM</application> will not do this, and if you wipe some + portion of your source tree out (and do not have it backed up) then + you will have to start from scratch (from the most recent CVS + <quote>base delta</quote>) and rebuild it all with + <application>CTM</application> or, with + <application>Anonymous CVS</application>, simply delete the bad bits + and resync.</para> + </sect1> + + <sect1 id="makeworld"> + <title>Rebuilding <quote>world</quote></title> + + <indexterm> + <primary>Rebuilding <quote>world</quote></primary> + </indexterm> + <para>Once you have synchronized your local source tree against a + particular version of &os; (&os.stable;, &os.current;, and so on) + you can then use the source tree to rebuild the system.</para> + + <warning> + <title>Make a Backup</title> + + <para>It cannot be stressed enough how important it is to make a + backup of your system <emphasis>before</emphasis> you do this. + While rebuilding the world is (as long as you follow these + instructions) an easy task to do, there will inevitably be times + when you make mistakes, or when mistakes made by others in the + source tree render your system unbootable.</para> + + <para>Make sure you have taken a backup. And have a fixit floppy or + bootable CD at hand. You will probably never have to use it, but it + is better to be safe than sorry!</para> + </warning> + + <warning> + <title>Subscribe to the Right Mailing List</title> + + <indexterm><primary>mailing list</primary></indexterm> + <para>The &os.stable; and &os.current; branches are, by their + nature, <emphasis>in development</emphasis>. People that + contribute to &os; are human, and mistakes occasionally + happen.</para> + + <para>Sometimes these mistakes can be quite harmless, just causing + your system to print a new diagnostic warning. Or the change may + be catastrophic, and render your system unbootable or destroy your + file systems (or worse).</para> + + <para>If problems like these occur, a <quote>heads up</quote> is + posted to the appropriate mailing list, explaining the nature of + the problem and which systems it affects. And an <quote>all + clear</quote> announcement is posted when the problem has been + solved.</para> + + <para>If you try to track &os.stable; or &os.current; and do + not read the &a.stable; or the &a.current; respectively, then you + are asking for trouble.</para> + </warning> + + <warning> + <title>Do not use <command>make world</command></title> + + <para>A lot of older documentation recommends using + <command>make world</command> for this. Doing that skips + some important steps and should only be used if you are + sure of what you are doing. For almost all circumstances + <command>make world</command> is the wrong thing to do, and + the procedure described here should be used instead.</para> + </warning> + + <sect2 id="canonical-build"> + <title>The Canonical Way to Update Your System</title> + + <para>To update your system, you should check + <filename>/usr/src/UPDATING</filename> for any pre-buildworld + steps necessary for your version of the sources and then use the + procedure outlined here.</para> + + <para>These upgrade steps assume that you are currently using an old + &os; version, consisting of an old compiler, old kernel, old world and + old configuration files. By <quote>world</quote> here we mean the + core system binaries, libraries and programming files. The compiler + is part of <quote>world</quote>, but has a few special concerns.</para> + + <para>We also assume that you have already obtained the sources to a + newer system. If the sources available on the particular system are + old too, see <xref linkend="synching"> for detailed help about + synchronizing them to a newer version.</para> + + <para>Updating the system from sources is a bit more subtle than it + might initially seem to be, and the &os; developers have found it + necessary over the years to change the recommended approach fairly + dramatically as new kinds of unavoidable dependencies come to light. + The rest of this section describes the rationale behind the currently + recommended upgrade sequence.</para> + + <para>Any successful update sequence must deal with the following + issues:</para> + + <itemizedlist> + <listitem> + <para>The old compiler might not be able to compile the new + kernel. (Old compilers sometimes have bugs.) So, the new + kernel should be built with the new compiler. In particular, + the new compiler must be built before the new kernel is built. + This does not necessarily mean that the new compiler must + be <emphasis>installed</emphasis> before building the new + kernel.</para> + </listitem> + + <listitem> + <para>The new world might rely on new kernel features. So, the + new kernel must be installed before the new world is + installed.</para> + </listitem> + </itemizedlist> + + <para>These first two issues are the basis for the + core <maketarget>buildworld</maketarget>, + <maketarget>buildkernel</maketarget>, + <maketarget>installkernel</maketarget>, + <maketarget>installworld</maketarget> sequence that we describe in + the following paragraphs. This is not an exhaustive list of all the + reasons why you should prefer the currently recommended upgrade + process. Some of the less obvious ones are listed below:</para> + + <itemizedlist> + <listitem> + <para>The old world might not run correctly on the new kernel, so + you must install the new world immediately upon installing the + new kernel.</para> + </listitem> + + <listitem> + <para>Some configuration changes must be done before the new world + is installed, but others might break the old world. Hence, two + different configuration upgrade steps are generally + needed.</para> + </listitem> + + <listitem> + <para>For the most part, the update process only replaces or adds + files; existing old files are not deleted. In a few cases, this + can cause problems. As a result, the update procedure will + sometimes specify certain files that should be manually deleted + at certain steps. This may or may not be automated in the + future.</para> + </listitem> + </itemizedlist> + + <para>These concerns have led to the following recommended sequence. + Note that the detailed sequence for particular updates may require + additional steps, but this core process should remain unchanged for + some time:</para> + + <orderedlist> + <listitem> + <para><command>make <maketarget>buildworld</maketarget></command></para> + + <para>This first compiles the new compiler and a few related + tools, then uses the new compiler to compile the rest of the new + world. The result ends up + in <filename class="directory">/usr/obj</filename>.</para> + </listitem> + + <listitem> + <para><command>make <maketarget>buildkernel</maketarget></command></para> + + <para>Unlike the older approach, using &man.config.8; and + &man.make.1;, this uses the <emphasis>new</emphasis> compiler + residing in <filename class="directory">/usr/obj</filename>. + This protects you against compiler-kernel mismatches.</para> + </listitem> + + <listitem> + <para><command>make <maketarget>installkernel</maketarget></command></para> + + <para>Place the new kernel and kernel modules onto the disk, + making it possible to boot with the newly updated kernel.</para> + </listitem> + + <listitem> + <para>Reboot into single user mode.</para> + + <para>Single user mode minimizes problems from updating software + that's already running. It also minimizes any problems from + running the old world on a new kernel.</para> + </listitem> + + <listitem> + <para><command>mergemaster <option>-p</option></command></para> + + <para>This does some initial configuration file updates in + preparation for the new world. For instance it may add new user + groups to the system, or new user names to the password database. + This is often necessary when new groups or special system-user + accounts have been added since the last update, so that + the <maketarget>installworld</maketarget> step will be able to + use the newly installed system user or system group names + without problems.</para> + </listitem> + + <listitem> + <para><command>make <maketarget>installworld</maketarget></command></para> + + <para>Copies the world + from <filename class="directory">/usr/obj</filename>. You now + have a new kernel and new world on disk.</para> + </listitem> + + <listitem> + <para><command>mergemaster</command></para> + + <para>Now you can update the remaining configuration files, since + you have a new world on disk.</para> + </listitem> + + <listitem> + <para>Reboot.</para> + + <para>A full machine reboot is needed now to load the new kernel + and new world with new configuration files.</para> + </listitem> + </orderedlist> + + <para>Note that if you're upgrading from one release of the same &os; + branch to a more recent release of the same branch, i.e., from 7.0 to + 7.1, then this procedure may not be absolutely necessary, since + you're unlikely to run into serious mismatches between compiler, + kernel, userland and configuration files. The older approach + of <command>make <maketarget>world</maketarget></command> followed + by building and installing a new kernel might work well enough for + minor updates.</para> + + <para>But, when upgrading across major releases, people who don't + follow this procedure should expect some problems.</para> + + <para>It is also worth noting that many upgrades + (i.e., 4.<replaceable>X</replaceable> to 5.0) may require + specific additional steps (renaming or deleting specific files prior + to installworld, for instance). Read + the <filename>/usr/src/UPDATING</filename> file carefully, + especially at the end, where the currently recommended upgrade + sequence is explicitly spelled out.</para> + + <para>This procedure has evolved over time as the developers have + found it impossible to completely prevent certain kinds of mismatch + problems. Hopefully, the current procedure will remain stable for a + long time.</para> + + <para>To summarize, the currently recommended way of upgrading &os; + from sources is:</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make buildworld</userinput> +&prompt.root; <userinput>make buildkernel</userinput> +&prompt.root; <userinput>make installkernel</userinput> +&prompt.root; <userinput>shutdown -r now</userinput></screen> + + <note> + <para>There are a few rare cases when an extra run of + <command>mergemaster -p</command> is needed before the + <maketarget>buildworld</maketarget> step. These are + described in <filename>UPDATING</filename>. In general, + though, you can safely omit this step if you are not + updating across one or more major &os; versions.</para> + </note> + + <para>After <maketarget>installkernel</maketarget> finishes + successfully, you should boot in single user mode + (i.e., using <command>boot -s</command> from the loader + prompt). Then run:</para> + + <screen>&prompt.root; <userinput>mount -u /</userinput> +&prompt.root; <userinput>mount -a -t ufs</userinput> +&prompt.root; <userinput>adjkerntz -i</userinput> +&prompt.root; <userinput>mergemaster -p</userinput> +&prompt.root; <userinput>cd /usr/src</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>The sequence described above is only a short resume to + help you getting started. You should however read the + following sections to clearly understand each step, especially + if you want to use a custom kernel configuration.</para> + </warning> + </sect2> + + <sect2 id="src-updating"> + <title>Read <filename>/usr/src/UPDATING</filename></title> + + <para>Before you do anything else, read + <filename>/usr/src/UPDATING</filename> (or the equivalent file + wherever you have a copy of the source code). This file should + contain important information about problems you might encounter, or + specify the order in which you might have to run certain commands. + If <filename>UPDATING</filename> contradicts something you read here, + <filename>UPDATING</filename> takes precedence.</para> + + <important> + <para>Reading <filename>UPDATING</filename> is not an acceptable + substitute for subscribing to the correct mailing list, as + described previously. The two requirements are complementary, not + exclusive.</para> + </important> + </sect2> + + <sect2 id="make-conf"> + <title>Check <filename>/etc/make.conf</filename></title> + <indexterm> + <primary><filename>make.conf</filename></primary> + </indexterm> + + <para>Examine the files + <filename>/usr/share/examples/etc/make.conf</filename> and + <filename>/etc/make.conf</filename>. The first contains some + default defines – most of which are commented out. To + make use of them when you rebuild your system from source, add + them to <filename>/etc/make.conf</filename>. Keep in mind that + anything you add to <filename>/etc/make.conf</filename> is also + used every time you run <command>make</command>, so it is a good + idea to set them to something sensible for your system.</para> + + <para>A typical user will probably want to copy the + <makevar>CFLAGS</makevar> and + <makevar>NO_PROFILE</makevar> lines found in + <filename>/usr/share/examples/etc/make.conf</filename> + to <filename>/etc/make.conf</filename> and uncomment them.</para> + + <para>Examine the other definitions (<makevar>COPTFLAGS</makevar>, + <makevar>NOPORTDOCS</makevar> and so + on) and decide if they are relevant to you.</para> + </sect2> + + <sect2 id="updating-etc"> + <title>Update the Files in <filename>/etc</filename></title> + + <para>The <filename>/etc</filename> directory contains a large part + of your system's configuration information, as well as scripts + that are run at system startup. Some of these scripts change from + version to version of FreeBSD.</para> + + <para>Some of the configuration files are also used in the day to + day running of the system. In particular, + <filename>/etc/group</filename>.</para> + + <para>There have been occasions when the installation part of + <command>make installworld</command> has expected certain usernames + or groups to exist. When performing an upgrade it is likely that + these users or groups did not exist. This caused problems when + upgrading. In some cases <command>make buildworld</command> will + check to see if these users or groups exist.</para> + + <para>An example of this is when the <username>smmsp</username> user + was added. Users had the installation process fail for them when + &man.mtree.8; was trying to create + <filename>/var/spool/clientmqueue</filename>.</para> + + <para>The solution is to run &man.mergemaster.8; in + pre-buildworld mode by providing the <option>-p</option> option. + This will compare only those files that are essential for the success + of <maketarget>buildworld</maketarget> or + <maketarget>installworld</maketarget>.</para> + + <tip> + <para>If you are feeling particularly paranoid, you can check your + system to see which files are owned by the group you are + renaming or deleting:</para> + + <screen>&prompt.root; <userinput>find / -group <replaceable>GID</replaceable> -print</userinput></screen> + + <para>will show all files owned by group + <replaceable>GID</replaceable> (which can be either a group name + or a numeric group ID).</para> + </tip> + </sect2> + + <sect2 id="makeworld-singleuser"> + <title>Drop to Single User Mode</title> + <indexterm><primary>single-user mode</primary></indexterm> + + <para>You may want to compile the system in single user mode. Apart + from the obvious benefit of making things go slightly faster, + reinstalling the system will touch a lot of important system + files, all the standard system binaries, libraries, include files + and so on. Changing these on a running system (particularly if + you have active users on the system at the time) is asking for + trouble.</para> + + <indexterm><primary>multi-user mode</primary></indexterm> + <para>Another method is to compile the system in multi-user mode, and + then drop into single user mode for the installation. If you would + like to do it this way, simply hold off on the following steps until + the build has completed. You can postpone dropping to single user + mode until you have to <maketarget>installkernel</maketarget> or + <maketarget>installworld</maketarget>.</para> + + <para>As the superuser, you can execute:</para> + + <screen>&prompt.root; <userinput>shutdown now</userinput></screen> + + <para>from a running system, which will drop it to single user + mode.</para> + + <para>Alternatively, reboot the system, and at the boot prompt, + select the <quote>single user</quote> option. The system will then + boot single user. At the shell prompt you should then run:</para> + + <screen>&prompt.root; <userinput>fsck -p</userinput> +&prompt.root; <userinput>mount -u /</userinput> +&prompt.root; <userinput>mount -a -t ufs</userinput> +&prompt.root; <userinput>swapon -a</userinput></screen> + + <para>This checks the file systems, remounts <filename>/</filename> + read/write, mounts all the other UFS file systems referenced in + <filename>/etc/fstab</filename> and then turns swapping on.</para> + + <note> + <para>If your CMOS clock is set to local time and not to GMT + (this is true if the output of the &man.date.1; command + does not show the correct time and zone), + you may also need to run the following command:</para> + + <screen>&prompt.root; <userinput>adjkerntz -i</userinput></screen> + + <para>This will make sure that your local time-zone settings + get set up correctly — without this, you may later run + into some problems.</para> + </note> + </sect2> + + <sect2 id="cleaning-usr-obj"> + <title>Remove <filename>/usr/obj</filename></title> + + <para>As parts of the system are rebuilt they are placed in + directories which (by default) go under + <filename>/usr/obj</filename>. The directories shadow those under + <filename>/usr/src</filename>.</para> + + <para>You can speed up the <command>make buildworld</command> process, + and possibly save yourself some dependency headaches by removing this + directory as well.</para> + + <para>Some files below <filename>/usr/obj</filename> may have the + immutable flag set (see &man.chflags.1; for more information) + which must be removed first.</para> + + <screen>&prompt.root; <userinput>cd /usr/obj</userinput> +&prompt.root; <userinput>chflags -R noschg *</userinput> +&prompt.root; <userinput>rm -rf *</userinput></screen> + </sect2> + + <sect2 id="updating-upgrading-compilebase"> + <title>Recompile the Base System</title> + + <sect3> + <title>Saving the Output</title> + + <para>It is a good idea to save the output you get from running + &man.make.1; to another file. If something goes wrong you will + have a copy of the error message. While this might not help you + in diagnosing what has gone wrong, it can help others if you post + your problem to one of the &os; mailing lists.</para> + + <para>The easiest way to do this is to use the &man.script.1; + command, with a parameter that specifies the name of the file to + save all output to. You would do this immediately before + rebuilding the world, and then type <userinput>exit</userinput> + when the process has finished.</para> + + <screen>&prompt.root; <userinput>script /var/tmp/mw.out</userinput> +Script started, output file is /var/tmp/mw.out +&prompt.root; <userinput>make TARGET</userinput> +<emphasis>… compile, compile, compile …</emphasis> +&prompt.root; <userinput>exit</userinput> +Script done, …</screen> + + <para>If you do this, <emphasis>do not</emphasis> save the output + in <filename>/tmp</filename>. This directory may be cleared + next time you reboot. A better place to store it is in + <filename>/var/tmp</filename> (as in the previous example) or + in <username>root</username>'s home directory.</para> + </sect3> + + <sect3 id="make-buildworld"> + <title>Compile the Base System</title> + + <para>You must be in the <filename>/usr/src</filename> + directory:</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen> + + <para>(unless, of course, your source code is elsewhere, in which + case change to that directory instead).</para> + <indexterm><primary><command>make</command></primary></indexterm> + + <para>To rebuild the world you use the &man.make.1; command. This + command reads instructions from the <filename>Makefile</filename>, + which describes how the programs that comprise &os; should be + rebuilt, the order in which they should be built, and so on.</para> + + <para>The general format of the command line you will type is as + follows:</para> + + <screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen> + + <para>In this example, <option>-<replaceable>x</replaceable></option> + is an option that you would pass to &man.make.1;. See the + &man.make.1; manual page for an example of the options you can + pass.</para> + + <para><option>-D<replaceable>VARIABLE</replaceable></option> + passes a variable to the <filename>Makefile</filename>. The + behavior of the <filename>Makefile</filename> is controlled by + these variables. These are the same variables as are set in + <filename>/etc/make.conf</filename>, and this provides another + way of setting them.</para> + + <screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen> + + <para>is another way of specifying that profiled libraries should + not be built, and corresponds with the</para> + + <programlisting>NO_PROFILE= true # Avoid compiling profiled libraries</programlisting> + + <para>line in <filename>/etc/make.conf</filename>.</para> + + <para><replaceable>target</replaceable> tells &man.make.1; what + you want to do. Each <filename>Makefile</filename> defines a + number of different <quote>targets</quote>, and your choice of + target determines what happens.</para> + + <para>Some targets are listed in the + <filename>Makefile</filename>, but are not meant for you to run. + Instead, they are used by the build process to break out the + steps necessary to rebuild the system into a number of + sub-steps.</para> + + <para>Most of the time you will not need to pass any parameters to + &man.make.1;, and so your command like will look like + this:</para> + + <screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen> + + <para>Where <replaceable>target</replaceable> will be one of + many build options. The first target should always be + <makevar>buildworld</makevar>.</para> + + <para>As the names imply, <maketarget>buildworld</maketarget> + builds a complete new tree under <filename>/usr/obj</filename>, + and <maketarget>installworld</maketarget>, another target, + installs this tree on the current machine.</para> + + <para>Having separate options is very useful for two reasons. First, + it allows you to do the build safe in the knowledge that no + components of your running system will be affected. The build is + <quote>self hosted</quote>. Because of this, you can safely + run <maketarget>buildworld</maketarget> on a machine running + in multi-user mode with no fear of ill-effects. It is still + recommended that you run the <maketarget>installworld</maketarget> + part in single user mode, though.</para> + + <para>Secondly, it allows you to use NFS mounts to upgrade + multiple machines on your network. If you have three machines, + <hostid>A</hostid>, <hostid>B</hostid> and <hostid>C</hostid> that + you want to upgrade, run <command>make buildworld</command> and + <command>make installworld</command> on <hostid>A</hostid>. + <hostid>B</hostid> and <hostid>C</hostid> should then NFS mount + <filename>/usr/src</filename> and <filename>/usr/obj</filename> + from <hostid>A</hostid>, and you can then run + <command>make installworld</command> to install the results of + the build on <hostid>B</hostid> and <hostid>C</hostid>.</para> + + <para>Although the <maketarget>world</maketarget> target still exists, + you are strongly encouraged not to use it.</para> + + <para>Run</para> + + <screen>&prompt.root; <userinput>make buildworld</userinput></screen> + + <para>It is possible to specify a <option>-j</option> option to + <command>make</command> which will cause it to spawn several + simultaneous processes. This is most useful on multi-CPU machines. + However, since much of the compiling process is IO bound rather + than CPU bound it is also useful on single CPU machines.</para> + + <para>On a typical single-CPU machine you would run:</para> + + <screen>&prompt.root; <userinput>make -j4 buildworld</userinput></screen> + + <para>&man.make.1; will then have up to 4 processes running at any one + time. Empirical evidence posted to the mailing lists shows this + generally gives the best performance benefit.</para> + + <para>If you have a multi-CPU machine and you are using an SMP + configured kernel try values between 6 and 10 and see how they speed + things up.</para> + </sect3> + + <sect3> + <title>Timings</title> + <indexterm> + <primary>rebuilding <quote>world</quote></primary> + <secondary>timings</secondary> + </indexterm> + + <para>Many factors influence the build time, but fairly recent + machines may only take a one or two hours to build + the &os.stable; tree, with no tricks or shortcuts used during the + process. A &os.current; tree will take somewhat longer.</para> + </sect3> + </sect2> + + <sect2 id="new-kernel"> + <title>Compile and Install a New Kernel</title> + <indexterm> + <primary>kernel</primary> + <secondary>compiling</secondary> + </indexterm> + + <para>To take full advantage of your new system you should recompile the + kernel. This is practically a necessity, as certain memory structures + may have changed, and programs like &man.ps.1; and &man.top.1; will + fail to work until the kernel and source code versions are the + same.</para> + + <para>The simplest, safest way to do this is to build and install a + kernel based on <filename>GENERIC</filename>. While + <filename>GENERIC</filename> may not have all the necessary devices + for your system, it should contain everything necessary to boot your + system back to single user mode. This is a good test that the new + system works properly. After booting from + <filename>GENERIC</filename> and verifying that your system works you + can then build a new kernel based on your normal kernel configuration + file.</para> + + <para>On &os; it is important to <link + linkend="make-buildworld">build world</link> before building a + new kernel.</para> + + <note> + <para>If you want to build a custom kernel, and already have a + configuration file, just use + <literal>KERNCONF=<replaceable>MYKERNEL</replaceable></literal> + like this:</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput> +&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> + </note> + + <para>Note that if you have raised <literal>kern.securelevel</literal> + above 1 <emphasis>and</emphasis> you have set either the + <literal>noschg</literal> or similar flags to your kernel binary, you + might find it necessary to drop into single user mode to use + <maketarget>installkernel</maketarget>. Otherwise you should be able + to run both these commands from multi user mode without + problems. See &man.init.8; for details about + <literal>kern.securelevel</literal> and &man.chflags.1; for details + about the various file flags.</para> + </sect2> + + <sect2 id="new-kernel-singleuser"> + <title>Reboot into Single User Mode</title> + <indexterm><primary>single-user mode</primary></indexterm> + + <para>You should reboot into single user mode to test the new kernel + works. Do this by following the instructions in + <xref linkend="makeworld-singleuser">.</para> + </sect2> + + <sect2 id="make-installworld"> + <title>Install the New System Binaries</title> + + <para> + You should now use + <maketarget>installworld</maketarget> to install the new system + binaries.</para> + + <para>Run</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make installworld</userinput></screen> + + <note> + <para>If you specified variables on the + <command>make buildworld</command> command line, you must specify + the same variables in the <command>make installworld</command> + command line. This does not necessarily hold true for other + options; for example, <option>-j</option> must never be used with + <maketarget>installworld</maketarget>.</para> + + <para>For example, if you ran:</para> + + <screen>&prompt.root; <userinput>make -DNO_PROFILE buildworld</userinput></screen> + + <para>you must install the results with:</para> + + <screen>&prompt.root; <userinput>make -DNO_PROFILE installworld</userinput></screen> + + <para>otherwise it would try to install profiled libraries that + had not been built during the <command>make buildworld</command> + phase.</para> + </note> + </sect2> + + <sect2 id="post-installworld-updates"> + <title>Update Files Not Updated by <command>make installworld</command></title> + + <para>Remaking the world will not update certain directories (in + particular, <filename>/etc</filename>, <filename>/var</filename> and + <filename>/usr</filename>) with new or changed configuration + files.</para> + + <para>The simplest way to update these files is to use + &man.mergemaster.8;, though it is possible to do it manually + if you would prefer to do that. Regardless of which way you + choose, be sure to make a backup of <filename>/etc</filename> in + case anything goes wrong.</para> + + <sect3 id="mergemaster"> + <sect3info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect3info> + <title><command>mergemaster</command></title> + <indexterm><primary><command>mergemaster</command></primary></indexterm> + + <para>The &man.mergemaster.8; utility is a Bourne script that will + aid you in determining the differences between your configuration + files in <filename>/etc</filename>, and the configuration files in + the source tree <filename>/usr/src/etc</filename>. This is + the recommended solution for keeping the system configuration files + up to date with those located in the source tree.</para> + + <para>To begin simply type <command>mergemaster</command> at your + prompt, and watch it start going. <command>mergemaster</command> + will then build a temporary root environment, from + <filename>/</filename> down, and populate it with various system + configuration files. Those files are then compared to the ones + currently installed in your system. At this point, files that + differ will be shown in &man.diff.1; format, with the + <option>+</option> sign representing added or modified lines, and + <option>-</option> representing lines that will be either removed + completely, or replaced with a new line. See the &man.diff.1; + manual page for more information about the &man.diff.1; syntax and + how file differences are shown.</para> + + <para>&man.mergemaster.8; will then show you each file that displays + variances, and at this point you will have the option of either + deleting the new file (referred to as the temporary file), + installing the temporary file in its unmodified state, merging the + temporary file with the currently installed file, or viewing the + &man.diff.1; results again.</para> + + <para>Choosing to delete the temporary file will tell + &man.mergemaster.8; that we wish to keep our current file + unchanged, and to delete the new version. This option is not + recommended, unless you see no reason to change the current file. + You can get help at any time by typing <keycap>?</keycap> at the + &man.mergemaster.8; prompt. If the user chooses to skip a file, + it will be presented again after all other files have been dealt + with.</para> + + <para>Choosing to install the unmodified temporary file will replace + the current file with the new one. For most unmodified files, + this is the best option.</para> + + <para>Choosing to merge the file will present you with a text editor, + and the contents of both files. You can now merge them by + reviewing both files side by side on the screen, and choosing parts + from both to create a finished product. When the files are + compared side by side, the <keycap>l</keycap> key will select the + left contents and the <keycap>r</keycap> key will select contents + from your right. The final output will be a file consisting of + both parts, which can then be installed. This option is + customarily used for files where settings have been modified by + the user.</para> + + <para>Choosing to view the &man.diff.1; results again will show you + the file differences just like &man.mergemaster.8; did before + prompting you for an option.</para> + + <para>After &man.mergemaster.8; is done with the system files you + will be prompted for other options. &man.mergemaster.8; may ask + if you want to rebuild the password file and will finish up with + an option to remove left-over temporary files.</para> + </sect3> + + <sect3> + <title>Manual Update</title> + + <para>If you wish to do the update manually, however, + you cannot just copy over the files from + <filename>/usr/src/etc</filename> to <filename>/etc</filename> and + have it work. Some of these files must be <quote>installed</quote> + first. This is because the <filename>/usr/src/etc</filename> + directory <emphasis>is not</emphasis> a copy of what your + <filename>/etc</filename> directory should look like. In addition, + there are files that should be in <filename>/etc</filename> that are + not in <filename>/usr/src/etc</filename>.</para> + + <para>If you are using &man.mergemaster.8; (as recommended), + you can skip forward to the <link + linkend="updating-upgrading-rebooting">next section</link>.</para> + + <para>The simplest way to do this by hand is to install the + files into a new directory, and then work through them looking + for differences.</para> + + <warning> + <title>Backup Your Existing <filename>/etc</filename></title> + + <para>Although, in theory, nothing is going to touch this directory + automatically, it is always better to be sure. So copy your + existing <filename>/etc</filename> directory somewhere safe. + Something like:</para> + + <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen> + + <para><option>-R</option> does a recursive copy, <option>-p</option> + preserves times, ownerships on files and suchlike.</para> + </warning> + + <para>You need to build a dummy set of directories to install the new + <filename>/etc</filename> and other files into. + <filename>/var/tmp/root</filename> is a reasonable choice, and + there are a number of subdirectories required under this as + well.</para> + + <screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput> +&prompt.root; <userinput>cd /usr/src/etc</userinput> +&prompt.root; <userinput>make DESTDIR=/var/tmp/root distrib-dirs distribution</userinput></screen> + + <para>This will build the necessary directory structure and install + the files. A lot of the subdirectories that have been created under + <filename>/var/tmp/root</filename> are empty and should be deleted. + The simplest way to do this is to:</para> + + <screen>&prompt.root; <userinput>cd /var/tmp/root</userinput> +&prompt.root; <userinput>find -d . -type d | xargs rmdir 2>/dev/null</userinput></screen> + + <para>This will remove all empty directories. (Standard error is + redirected to <filename>/dev/null</filename> to prevent the warnings + about the directories that are not empty.)</para> + + <para><filename>/var/tmp/root</filename> now contains all the files + that should be placed in appropriate locations below + <filename>/</filename>. You now have to go through each of these + files, determining how they differ with your existing files.</para> + + <para>Note that some of the files that will have been installed in + <filename>/var/tmp/root</filename> have a leading <quote>.</quote>. + At the time of writing the only files like this are shell startup + files in <filename>/var/tmp/root/</filename> and + <filename>/var/tmp/root/root/</filename>, although there may be + others (depending on when you are reading this). Make sure you use + <command>ls -a</command> to catch them.</para> + + <para>The simplest way to do this is to use &man.diff.1; to compare + the two files:</para> + + <screen>&prompt.root; <userinput>diff /etc/shells /var/tmp/root/etc/shells</userinput></screen> + + <para>This will show you the differences between your + <filename>/etc/shells</filename> file and the new + <filename>/var/tmp/root/etc/shells</filename> file. Use these to + decide whether to merge in changes that you have made or whether to + copy over your old file.</para> + + <tip> + <title>Name the New Root Directory + (<filename>/var/tmp/root</filename>) with a Time Stamp, so You Can + Easily Compare Differences Between Versions</title> + + <para>Frequently rebuilding the world means that you have to update + <filename>/etc</filename> frequently as well, which can be a bit + of a chore.</para> + + <para>You can speed this process up by keeping a copy of the last + set of changed files that you merged into + <filename>/etc</filename>. The following procedure gives one + idea of how to do this.</para> + + <procedure> + <step> + <para>Make the world as normal. When you want to update + <filename>/etc</filename> and the other directories, give the + target directory a name based on the current date. If you + were doing this on the 14th of February 1998 you could do the + following:</para> + + <screen>&prompt.root; <userinput>mkdir /var/tmp/root-19980214</userinput> +&prompt.root; <userinput>cd /usr/src/etc</userinput> +&prompt.root; <userinput>make DESTDIR=/var/tmp/root-19980214 \ + distrib-dirs distribution</userinput></screen> + </step> + + <step> + <para>Merge in the changes from this directory as outlined + above.</para> + + <para><emphasis>Do not</emphasis> remove the + <filename>/var/tmp/root-19980214</filename> directory when you + have finished.</para> + </step> + + <step> + <para>When you have downloaded the latest version of the source + and remade it, follow step 1. This will give you a new + directory, which might be called + <filename>/var/tmp/root-19980221</filename> (if you wait a + week between doing updates).</para> + </step> + + <step> + <para>You can now see the differences that have been made in the + intervening week using &man.diff.1; to create a recursive + diff between the two directories:</para> + + <screen>&prompt.root; <userinput>cd /var/tmp</userinput> +&prompt.root; <userinput>diff -r root-19980214 root-19980221</userinput></screen> + + <para>Typically, this will be a much smaller set of differences + than those between + <filename>/var/tmp/root-19980221/etc</filename> and + <filename>/etc</filename>. Because the set of differences is + smaller, it is easier to migrate those changes across into + your <filename>/etc</filename> directory.</para> + </step> + + <step> + <para>You can now remove the older of the two + <filename>/var/tmp/root-*</filename> directories:</para> + + <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-19980214</userinput></screen> + </step> + + <step> + <para>Repeat this process every time you need to merge in + changes to <filename>/etc</filename>.</para> + </step> + </procedure> + + <para>You can use &man.date.1; to automate the generation of the + directory names:</para> + + <screen>&prompt.root; <userinput>mkdir /var/tmp/root-`date "+%Y%m%d"`</userinput></screen> + </tip> + </sect3> + </sect2> + + <sect2 id="updating-upgrading-rebooting"> + <title>Rebooting</title> + + <para>You are now done. After you have verified that everything appears + to be in the right place you can reboot the system. A simple + &man.shutdown.8; should do it:</para> + + <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen> + </sect2> + + <sect2> + <title>Finished</title> + + <para>You should now have successfully upgraded your &os; system. + Congratulations.</para> + + <para>If things went slightly wrong, it is easy to rebuild a particular + piece of the system. For example, if you accidentally deleted + <filename>/etc/magic</filename> as part of the upgrade or merge of + <filename>/etc</filename>, the &man.file.1; command will stop working. + In this case, the fix would be to run:</para> + + <screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput> +&prompt.root; <userinput>make all install</userinput></screen> + </sect2> + + <sect2 id="updating-questions"> + <title>Questions</title> + + <qandaset> + <qandaentry> + <question> + <para>Do I need to re-make the world for every change?</para> + </question> + + <answer> + <para>There is no easy answer to this one, as it depends on the + nature of the change. For example, if you just ran + <application>CVSup</application>, and it has shown the + following files as being updated:</para> + + <screen><filename>src/games/cribbage/instr.c</filename> +<filename>src/games/sail/pl_main.c</filename> +<filename>src/release/sysinstall/config.c</filename> +<filename>src/release/sysinstall/media.c</filename> +<filename>src/share/mk/bsd.port.mk</filename></screen> + + <para>it probably is not worth rebuilding the entire world. + You could just go to the appropriate sub-directories and + <command>make all install</command>, and that's about it. But + if something major changed, for example + <filename>src/lib/libc/stdlib</filename> then you should either + re-make the world, or at least those parts of it that are + statically linked (as well as anything else you might have added + that is statically linked).</para> + + <para>At the end of the day, it is your call. You might be happy + re-making the world every fortnight say, and let changes + accumulate over that fortnight. Or you might want to re-make + just those things that have changed, and be confident you can + spot all the dependencies.</para> + + <para>And, of course, this all depends on how often you want to + upgrade, and whether you are tracking &os.stable; or + &os.current;.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>My compile failed with lots of signal 11 (or other signal + number) errors. What has happened?</para> + </question> + <indexterm><primary>signal 11</primary></indexterm> + + <answer> + <para>This is normally indicative of hardware problems. + (Re)making the world is an effective way to stress test your + hardware, and will frequently throw up memory problems. These + normally manifest themselves as the compiler mysteriously dying + on receipt of strange signals.</para> + + <para>A sure indicator of this is if you can restart the make and + it dies at a different point in the process.</para> + + <para>In this instance there is little you can do except start + swapping around the components in your machine to determine + which one is failing.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can I remove <filename>/usr/obj</filename> when I have + finished?</para> + </question> + + <answer> + <para>The short answer is yes.</para> + + <para><filename>/usr/obj</filename> contains all the object files + that were produced during the compilation phase. Normally, one + of the first steps in the <command>make buildworld</command> + process is to remove this directory and start afresh. In this + case, keeping <filename>/usr/obj</filename> around after you + have finished makes little sense, and will free up a large + chunk of disk space (currently about 2 GB).</para> + + <para>However, if you know what you are doing you can have + <command>make buildworld</command> skip this step. This will + make subsequent builds run much faster, since most of sources + will not need to be recompiled. The flip side of this is that + subtle dependency problems can creep in, causing your build to + fail in odd ways. This frequently generates noise on the &os; + mailing lists, when one person complains that their build has + failed, not realizing that it is because they have tried to cut + corners.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Can interrupted builds be resumed?</para> + </question> + + <answer> + <para>This depends on how far through the process you got before + you found a problem.</para> + + <para><emphasis>In general</emphasis> (and this is not a hard and + fast rule) the <command>make buildworld</command> process + builds new copies of essential tools (such as &man.gcc.1;, and + &man.make.1;) and the system libraries. These tools and + libraries are then installed. The new tools and libraries are + then used to rebuild themselves, and are installed again. The + entire system (now including regular user programs, such as + &man.ls.1; or &man.grep.1;) is then rebuilt with the new + system files.</para> + + <para>If you are at the last stage, and you know it (because you + have looked through the output that you were storing) then you + can (fairly safely) do:</para> + + <screen><emphasis>… fix the problem …</emphasis> +&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make -DNO_CLEAN all</userinput></screen> + + <para>This will not undo the work of the previous + <command>make buildworld</command>.</para> + + <para>If you see the message:</para> + + <screen>-------------------------------------------------------------- +Building everything.. +--------------------------------------------------------------</screen> + + <para>in the <command>make buildworld</command> output then it is + probably fairly safe to do so.</para> + + <para>If you do not see that message, or you are not sure, then it + is always better to be safe than sorry, and restart the build + from scratch.</para> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>How can I speed up making the world?</para> + </question> + + <answer> + <itemizedlist> + <listitem> + <para>Run in single user mode.</para> + </listitem> + + <listitem> + <para>Put the <filename>/usr/src</filename> and + <filename>/usr/obj</filename> directories on separate + file systems held on separate disks. If possible, put these + disks on separate disk controllers.</para> + </listitem> + + <listitem> + <para>Better still, put these file systems across multiple + disks using the &man.ccd.4; (concatenated disk + driver) device.</para> + </listitem> + + <listitem> + <para>Turn off profiling (set <quote>NO_PROFILE=true</quote> + in <filename>/etc/make.conf</filename>). You almost + certainly do not need it.</para> + </listitem> + + <listitem> + <para>Also in <filename>/etc/make.conf</filename>, set + <makevar>CFLAGS</makevar> to something like <option>-O + -pipe</option>. The optimization <option>-O2</option> + is much slower, and the optimization difference between + <option>-O</option> and <option>-O2</option> is normally + negligible. <option>-pipe</option> lets the compiler use + pipes rather than temporary files for communication, which + saves disk access (at the expense of memory).</para> + </listitem> + + <listitem> + <para>Pass the + <option>-j<replaceable>n</replaceable></option> option to + &man.make.1; to run multiple processes in parallel. This + usually helps regardless of whether you have a single or + a multi processor machine.</para> + </listitem> + + <listitem> + <para>The file system holding <filename>/usr/src</filename> + can be mounted (or remounted) with the + <option>noatime</option> option. This prevents the + file system from recording the file access time. + You probably do not need this information anyway.</para> + + <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen> + + <warning> + <para>The example assumes <filename>/usr/src</filename> is + on its own file system. If it is not (if it is a part of + <filename>/usr</filename> for example) then you will + need to use that file system mount point, and not + <filename>/usr/src</filename>.</para> + </warning> + </listitem> + + <listitem> + <para>The file system holding <filename>/usr/obj</filename> + can be mounted (or remounted) with the + <option>async</option> option. This causes disk writes to + happen asynchronously. In other words, the write completes + immediately, and the data is written to the disk a few + seconds later. This allows writes to be clustered + together, and can be a dramatic performance boost.</para> + + <warning> + <para>Keep in mind that this option makes your file system + more fragile. With this option there is an increased + chance that, should power fail, the file system will be in + an unrecoverable state when the machine restarts.</para> + + <para>If <filename>/usr/obj</filename> is the only thing on + this file system then it is not a problem. If you have + other, valuable data on the same file system then ensure + your backups are fresh before you enable this + option.</para> + </warning> + + <screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen> + + <warning> + <para>As above, if <filename>/usr/obj</filename> is not on + its own file system, replace it in the example with the + name of the appropriate mount point.</para> + </warning> + </listitem> + </itemizedlist> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>What do I do if something goes wrong?</para> + </question> + + <answer> + <para>Make absolutely sure your environment has no + extraneous cruft from earlier builds. This is simple + enough.</para> + + <screen>&prompt.root; <userinput>chflags -R noschg /usr/obj/usr</userinput> +&prompt.root; <userinput>rm -rf /usr/obj/usr</userinput> +&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make cleandir</userinput> +&prompt.root; <userinput>make cleandir</userinput></screen> + + <para>Yes, <command>make cleandir</command> really should + be run twice.</para> + + <para>Then restart the whole process, starting + with <command>make buildworld</command>.</para> + + <para>If you still have problems, send the error and the + output of <command>uname -a</command> to &a.questions;. + Be prepared to answer other questions about your + setup!</para> + </answer> + </qandaentry> + </qandaset> + </sect2> + </sect1> + + <sect1 id="make-delete-old"> + <sect1info> + <authorgroup> + <author> + <firstname>Anton</firstname> + <surname>Shterenlikht</surname> + <contrib>Based on notes provided by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Deleting obsolete files, directories and libraries</title> + <indexterm> + <primary>Deleting obsolete files, directories and libraries</primary> + </indexterm> + + <para>As a part of the &os; development lifecycle, it happens from time + to time that files and their contents become obsolete. This may be + because their functionality is implemented elsewhere, the version number + of the library has changed or it was removed from the system entirely. + This includes old files, libraries and directories, which should + be removed when updating the system. The benefit for the user is that + the system is not cluttered with old files which take up unnecessary + space on the storage (and backup) medium. Additionally, if the old + library had a security or stability issue, you should update to the + newer library to keep your system safe and prevent crashes caused by + the old library implementation. The files, directories, and libraries + that are considered obsolete are listed in + <filename>/usr/src/ObsoleteFiles.inc</filename>. The following + instructions will help you removing these obsolete files during the + system upgrade process.</para> + + <para>We assume you are following the steps outlined in <xref + linkend="canonical-build">. After the <command>make + <maketarget>installworld</maketarget></command> and the subsequent + <command>mergemaster</command> commands have finished successfully, you + should check for obsolete files and libraries as follows:</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make check-old</userinput></screen> + + <para>If any obsolete files are found, they can be deleted using the + following commands:</para> + + <screen>&prompt.root; <userinput>make delete-old</userinput></screen> + + <tip> + <para>See <filename>/usr/src/Makefile</filename> + for more targets of interest.</para> + </tip> + + <para>A prompt is displayed before deleting each obsolete file. You can + skip the prompt and let the system remove these files automatically by + using the <makevar>BATCH_DELETE_OLD_FILES</makevar> make-variable as + follows:</para> + + <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen> + + <para>You can also achieve the same goal by piping these commands through + <command>yes</command> like this:</para> + + <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen> + + <warning> + <title>Warning</title> + <para>Deleting obsolete files will break applications that still + depend on those obsolete files. This is especially true for old + libraries. In most cases, you need to recompile the programs, ports, + or libraries that used the old library before <command>make + <maketarget>delete-old-libs</maketarget></command> is executed.</para> + </warning> + + <para>Utilities for checking shared library dependencies are available from + the Ports Collection in <filename + role="package">sysutils/libchk</filename> or <filename + role="package">sysutils/bsdadminscripts</filename>.</para> + + <para>Obsolete shared libraries can conflict with newer libraries, + causing messages like these:</para> + + <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5 +/usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen> + + <para>To solve these problems, determine which port installed the + library:</para> + + <screen>&prompt.root; <userinput>pkg_info -W /usr/local/lib/libtiff.so</userinput> +/usr/local/lib/libtiff.so was installed by package tiff-3.9.4 +&prompt.root; <userinput>pkg_info -W /usr/local/lib/libXext.so</userinput> +/usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</screen> + + <para>Then deinstall, rebuild and reinstall the port. The <filename + role="package">ports-mgmt/portmaster</filename> and <filename + role="package">ports-mgmt/portupgrade</filename> utilities can be used to + automate this process. After you've made sure that all ports are rebuilt + and do not use the old libraries anymore, you can delete them using the + following command:</para> + + <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen> + </sect1> + + <sect1 id="small-lan"> + <sect1info> + <authorgroup> + <author> + <firstname>Mike</firstname> + <surname>Meyer</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>Tracking for Multiple Machines</title> + <indexterm> + <primary>NFS</primary> + <secondary>installing multiple machines</secondary> + </indexterm> + + <para>If you have multiple machines that you want to track the + same source tree, then having all of them download sources and + rebuild everything seems like a waste of resources: disk space, + network bandwidth, and CPU cycles. It is, and the solution is + to have one machine do most of the work, while the rest of the + machines mount that work via NFS. This section outlines a + method of doing so.</para> + + <sect2 id="small-lan-preliminaries"> + <title>Preliminaries</title> + + <para>First, identify a set of machines that is going to run + the same set of binaries, which we will call a + <emphasis>build set</emphasis>. Each machine can have a + custom kernel, but they will be running the same userland + binaries. From that set, choose a machine to be the + <emphasis>build machine</emphasis>. It is going to be the + machine that the world and kernel are built on. Ideally, it + should be a fast machine that has sufficient spare CPU to + run <command>make buildworld</command> and + <command>make buildkernel</command>. You will also want to + choose a machine to be the <emphasis>test + machine</emphasis>, which will test software updates before they + are put into production. This <emphasis>must</emphasis> be a + machine that you can afford to have down for an extended + period of time. It can be the build machine, but need not be.</para> + + <para>All the machines in this build set need to mount + <filename>/usr/obj</filename> and + <filename>/usr/src</filename> from the same machine, and at + the same point. Ideally, those are on two different drives + on the build machine, but they can be NFS mounted on that machine + as well. If you have multiple build sets, + <filename>/usr/src</filename> should be on one build machine, and + NFS mounted on the rest.</para> + + <para>Finally make sure that + <filename>/etc/make.conf</filename> and + <filename>/etc/src.conf</filename> on all the machines in + the build set agrees with the build machine. That means that + the build machine must build all the parts of the base + system that any machine in the build set is going to + install. Also, each build machine should have its kernel + name set with <makevar>KERNCONF</makevar> in + <filename>/etc/make.conf</filename>, and the build machine + should list them all in <makevar>KERNCONF</makevar>, listing + its own kernel first. The build machine must have the kernel + configuration files for each machine in + <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf</filename> + if it is going to build their kernels.</para> + </sect2> + + <sect2 id="small-lan-base-system"> + <title>The Base System</title> + + <para>Now that all that is done, you are ready to build + everything. Build the kernel and world as described in <xref + linkend="make-buildworld"> on the build machine, + but do not install anything. After the build has finished, go + to the test machine, and install the kernel you just + built. If this machine mounts <filename>/usr/src</filename> + and <filename>/usr/obj</filename> via NFS, when you reboot + to single user you will need to enable the network and mount + them. The easiest way to do this is to boot to multi-user, + then run <command>shutdown now</command> to go to single user + mode. Once there, you can install the new kernel and world and run + <command>mergemaster</command> just as you normally would. When + done, reboot to return to normal multi-user operations for this + machine.</para> + + <para>After you are certain that everything on the test + machine is working properly, use the same procedure to + install the new software on each of the other machines in + the build set.</para> + </sect2> + + <sect2 id="small-lan-ports"> + <title>Ports</title> + + <para>The same ideas can be used for the ports tree. The first + critical step is mounting <filename>/usr/ports</filename> from + the same machine to all the machines in the build set. You can + then set up <filename>/etc/make.conf</filename> properly to share + distfiles. You should set <makevar>DISTDIR</makevar> to a + common shared directory that is writable by whichever user + <username>root</username> is mapped to by your NFS mounts. Each + machine should set <makevar>WRKDIRPREFIX</makevar> to a + local build directory. Finally, if you are going to be + building and distributing packages, you should set + <makevar>PACKAGES</makevar> to a directory similar to + <makevar>DISTDIR</makevar>.</para> + </sect2> + </sect1> +</chapter> +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/desktop/Makefile b/en_US.ISO8859-1/books/handbook/desktop/Makefile new file mode 100644 index 0000000000..6dd222f080 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/desktop/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= desktop/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml b/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml new file mode 100644 index 0000000000..0b13dcb250 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/desktop/chapter.sgml @@ -0,0 +1,1359 @@ +<!-- + The FreeBSD Documentation Project + $FreeBSD$ +--> + +<chapter id="desktop"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Christophe</firstname> + <surname>Juniet</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>Desktop Applications</title> + + <sect1 id="desktop-synopsis"> + <title>Synopsis</title> + + <para>FreeBSD can run a wide variety of desktop applications, such + as browsers and word processors. Most of these are available as + packages or can be automatically built from the Ports Collection. + Many new users expect to find these kinds of + applications on their desktop. This chapter will show you how + to install some popular desktop applications effortlessly, + either from their packages or from the Ports Collection.</para> + + <para>Note that when installing programs from the ports, they are + compiled from source. This can take a very long time, depending + on what you are compiling and the processing power of your + machine(s). If building from source takes a prohibitively long + amount of time for you, you can install most of the programs of + the Ports Collection from pre-built packages.</para> + + <para>As FreeBSD features Linux binary compatibility, many + applications originally developed for Linux are available for + your desktop. It is strongly recommended that you read + <xref linkend="linuxemu"> before installing any of the Linux + applications. Many of the ports using the Linux binary + compatibility start with <quote>linux-</quote>. Remember this + when you search for a particular port, for instance with + &man.whereis.1;. In the following text, it is assumed that you + have enabled Linux binary compatibility before installing any of + the Linux applications.</para> + + <para>Here are the categories covered by this chapter:</para> + + <itemizedlist> + <listitem> + <para>Browsers (such as <application>Firefox</application>, + <application>Opera</application>, + <application>Konqueror</application>, + <application>Chromium</application>)</para> + </listitem> + + <listitem> + <para>Productivity (such as + <application>KOffice</application>, + <application>AbiWord</application>, + <application>The GIMP</application>, + <application>OpenOffice.org</application>, + <application>LibreOffice</application>)</para> + </listitem> + + <listitem> + <para>Document Viewers (such as <application>&acrobat.reader;</application>, + <application>gv</application>, + <application>Xpdf</application>, + <application>GQview</application>)</para> + </listitem> + + <listitem> + <para>Finance (such as + <application>GnuCash</application>, + <application>Gnumeric</application>, + <application>Abacus</application>)</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Know how to install additional third-party software + (<xref linkend="ports">).</para> + </listitem> + + <listitem> + <para>Know how to install additional Linux software + (<xref linkend="linuxemu">).</para> + </listitem> + </itemizedlist> + + <para>For information on how to get a multimedia environment, read + <xref linkend="multimedia">. If you want to set up and use + electronic mail, please refer to <xref linkend="mail">.</para> + </sect1> + + <sect1 id="desktop-browsers"> + <title>Browsers</title> + + <indexterm> + <primary>browsers</primary> + <secondary>web</secondary> + </indexterm> + + <para>FreeBSD does not come with a particular browser + pre-installed. Instead, the + <ulink url="http://www.FreeBSD.org/ports/www.html">www</ulink> + directory of the Ports Collection contains a lot of browsers + ready to be installed. If you do not have time to compile + everything (this can take a very long time in some cases) many + of them are available as packages.</para> + + <para><application>KDE</application> and + <application>GNOME</application> already provide HTML browsers. + Please refer to <xref linkend="x11-wm"> for more information on + how to set up these complete desktops.</para> + + <para>If you are looking for light-weight browsers, you should + investigate the Ports Collection for + <filename role="package">www/dillo2</filename>, + <filename role="package">www/links</filename>, or + <filename role="package">www/w3m</filename>.</para> + + <para>This section covers these applications:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="4"> + <thead> + <row> + <entry>Application Name</entry> + <entry>Resources Needed</entry> + <entry>Installation from Ports</entry> + <entry>Major Dependencies</entry> + </row> + </thead> + + <tbody> + <row> + <entry><application>Firefox</application></entry> + <entry>medium</entry> + <entry>heavy</entry> + <entry><application>Gtk+</application></entry> + </row> + + <row> + <entry><application>Opera</application></entry> + <entry>light</entry> + <entry>light</entry> + <entry>FreeBSD and Linux versions available. The Linux + version depends on the Linux Binary Compatibility and + <application>linux-openmotif</application>.</entry> + </row> + + <row> + <entry><application>Konqueror</application></entry> + <entry>medium</entry> + <entry>heavy</entry> + <entry><application>KDE</application> Libraries</entry> + </row> + + <row> + <entry><application>Chromium</application></entry> + <entry>medium</entry> + <entry>medium</entry> + <entry><application>Gtk+</application></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <sect2> + <title>Firefox</title> + <indexterm> + <primary><application>Firefox</application></primary> + </indexterm> + + <para><application>Firefox</application> is a modern, free, + open-source stable browser that is fully ported to &os;: it + features a very standards-compliant HTML display engine, + tabbed browsing, popup blocking, extensions, improved + security, and more. <application>Firefox</application> is + based on the <application>Mozilla</application> codebase.</para> + + <para>Install the package by typing:</para> + + <screen>&prompt.root; <userinput>pkg_add -r firefox</userinput></screen> + + <para>This will install the latest release version of + <application>Firefox</application>, + if you want to run <application>Firefox</application> + Extended Support Release (ESR) version, use instead:</para> + + <screen>&prompt.root; <userinput>pkg_add -r firefox-esr</userinput></screen> + + <para>You can also use the Ports Collection if you + prefer to compile from source code:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/www/firefox</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>For <application>Firefox</application> ESR, in the + previous command replace <literal>firefox</literal> with + <literal>firefox-esr</literal>.</para> + </sect2> + + <sect2 id="moz-java-plugin"> + <title>Firefox and &java; Plugin</title> + + <note> + <para>In this section and in the next two sections, we assume you have + already installed <application>Firefox</application>.</para> + </note> + + <para>Install <application>OpenJDK 6</application> + through the Ports Collection by typing:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/java/openjdk6</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>Then install the <filename + role="package">java/icedtea-web</filename> port:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/java/icedtea-web</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>Make sure you have kept the default configuration options + for both ports.</para> + + <para>Start your browser, enter <literal>about:plugins</literal> + in the location bar and press <keycap>Enter</keycap>. A page + listing the installed plugins will be displayed; the + <application>&java;</application> plugin should be listed there + now.</para> + + <para>If the browser is unable to find the plugin, each user + will have to run the following command and relaunch the + browser:</para> + + <screen>&prompt.user; <userinput>ln -s /usr/local/lib/IcedTeaPlugin.so \ + $HOME/.mozilla/plugins/</userinput></screen> + </sect2> + + <sect2 id="moz-flash-plugin"> + + <title>Firefox and &adobe; &flash; Plugin</title> + <indexterm> + <primary>Flash</primary> + </indexterm> + + <para>The &adobe; &flash; plugin is not available for &os;. However, + a software layer (wrapper) for running the Linux version of the plugin + exists. This wrapper also supports &adobe; &acrobat; plugin, + &realplayer; plugin and more.</para> + + <para>According to the version of &os; you run various steps are + required:</para> + + <procedure> + <step> + <title>Under &os; 7.X</title> + + <para>Install the <filename + role="package">www/nspluginwrapper</filename> port. This + port requires <filename + role="package">emulators/linux_base-fc4</filename> which + is a large port.</para> + + <para>The next step is to install the <filename + role="package">www/linux-flashplugin9</filename> + port. This will install &flash; 9.X, this version is + known to run correctly under &os; 7.X.</para> + </step> + + <step> + <title>Under &os; 8.X or Newer</title> + + <para>Install the <filename + role="package">www/nspluginwrapper</filename> port. This + port requires <filename + role="package">emulators/linux_base-f10</filename> which + is a large port.</para> + + <para>The next step is to install &flash; 11.X from the + <filename role="package">www/linux-f10-flashplugin11</filename> + port.</para> + + <para>This version will require the following link to be + created:</para> + + <screen>&prompt.root; <userinput>ln -s /usr/local/lib/npapi/linux-f10-flashplugin/libflashplayer.so \ + /usr/local/lib/browser_plugins/</userinput></screen> + + <para>The <filename + class="directory">/usr/local/lib/browser_plugins</filename> + directory will have to be created manually if it does not + exist on the system.</para> + </step> + </procedure> + + <para>Once the right &flash; port, according to the &os; version + you run, + is installed, the plugin must be installed by each + user with <command>nspluginwrapper</command>:</para> + + <screen>&prompt.user; <userinput>nspluginwrapper -v -a -i</userinput></screen> + + <para>The &linux; process file system, &man.linprocfs.5; has to + be mounted on <filename + class="directory">/compat/linux/proc</filename>, if one + wants to play &flash; animations. This can be done via the + following command:</para> + + <screen>&prompt.root; <userinput>mount -t linprocfs linproc /compat/linux/proc</userinput></screen> + + <para>This point can be automated at boot time with the addition + of the matching line in + <filename>/etc/fstab</filename>:</para> + + <programlisting>linproc /compat/linux/proc linprocfs rw 0 0</programlisting> + + <para>Then, start your browser, enter + <literal>about:plugins</literal> in the location bar and press + <keycap>Enter</keycap>. + A list should appear with all the currently + available plugins.</para> + </sect2> + + <sect2 id="moz-swfdec-flash-plugin"> + <title>Firefox and Swfdec &flash; Plugin</title> + + <para>Swfdec is the library for decoding and rendering &flash; animations. + And Swfdec-Mozilla is a plugin for <application>Firefox</application> + browsers that uses the Swfdec library for playing SWF files. + It is still in heavy development.</para> + + <para>If you cannot or do not want to compile it, just install + the package from the network:</para> + + <screen>&prompt.root; <userinput>pkg_add -r swfdec-plugin</userinput></screen> + + <para>If the package is not available, you can compile and install it + from the Ports Collection:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/www/swfdec-plugin</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>Then, restart your browser for this plugin taking effect.</para> + </sect2> + + <sect2> + <title>Opera</title> + <indexterm> + <primary><application>Opera</application></primary> + </indexterm> + + <para><application>Opera</application> is a + full-featured and standards-compliant browser. It also + comes with a built-in mail and news reader, an IRC client, + an RSS/Atom feeds reader and much more. Despite this, + <application>Opera</application> is relatively lightweight + and very fast. It comes in two flavors: a <quote>native</quote> + FreeBSD version and a version that runs under Linux + emulation.</para> + + <para>To browse the Web with the FreeBSD version of <application>Opera</application>, + install the package:</para> + + <screen>&prompt.root; <userinput>pkg_add -r opera</userinput></screen> + + <para>Some FTP sites do not have all the packages, but + <application>Opera</application> can still be obtained + through the Ports Collection by typing:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/www/opera</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>To install the Linux version of + <application>Opera</application>, substitute + <literal>linux-opera</literal> in place of + <literal>opera</literal> in the example above.</para> + + <para>The &adobe; &flash; plugin is not available for &os;. + However, a &linux; version of the plugin exists. To install + this version, the <filename + role="package">www/linux-f10-flashplugin11</filename> port has + to be installed, then install the port <filename + role="package">www/opera-linuxplugins</filename>:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/www/linux-f10-flashplugin11</userinput> +&prompt.root; <userinput>make install clean</userinput> +&prompt.root; <userinput>cd /usr/ports/www/opera-linuxplugins</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>You can check the presence of the plugin: start your + browser, enter <literal>opera:plugins</literal> in the + location bar and press <keycap>Enter</keycap>. A list should + appear with all the currently available plugins.</para> + + <para>To add the <application>&java;</application> plugin, + follow the <link linkend="moz-java-plugin">instructions for + Firefox</link>.</para> + </sect2> + + <sect2> + <title>Konqueror</title> + <indexterm> + <primary><application>Konqueror</application></primary> + </indexterm> + + <para><application>Konqueror</application> is part of + <application>KDE</application> but it can also be used outside + of <application>KDE</application> by installing + <filename role="package">x11/kdebase3</filename>. + <application>Konqueror</application> is much more than a browser, + it is also a file manager and a multimedia viewer.</para> + + <para>There is also a set of plugins available for + <application>Konqueror</application>, + available in <filename role="package">misc/konq-plugins</filename>.</para> + + <para><application>Konqueror</application> also supports <application>&flash;</application>; a <quote>How To</quote> guide + for getting <application>&flash;</application> support on + <application>Konqueror</application> + is available at <ulink url="http://freebsd.kde.org/howtos/konqueror-flash.php"></ulink>.</para> + </sect2> + + <sect2> + <title>Chromium</title> + <indexterm> + <primary><application>Chromium</application></primary> + </indexterm> + + <para><application>Chromium</application> is an open-source + browser project that aims to build a safer, faster, and more + stable web browsing experience. <application>Chromium</application> + features tabbed browsing, popup blocking, extensions, and much + more. <application>Chromium</application> is the open-source + project upon which the Google Chrome web browser is + based.</para> + + <para><application>Chromium</application> can be installed as a + package by typing:</para> + + <screen>&prompt.root; <userinput>pkg_add -r chromium</userinput></screen> + + <para>Alternatively, <application>Chromium</application> can be + compiled from source using the Ports Collection:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/www/chromium</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <note> + <para><application>Chromium</application> is installed as + <filename>/usr/local/bin/chrome</filename>, not + <filename>/usr/local/bin/chromium</filename>.</para> + </note> + </sect2> + + <sect2 id="chromium-java-plugin"> + <title>Chromium and &java; Plugin</title> + + <note> + <para>This section assumes <application>Chromium</application> + is already installed.</para> + </note> + + <para>Install <application>OpenJDK 6</application> through the + Ports Collection by typing:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/java/openjdk6 +&prompt.root; make install clean</userinput></screen> + + <para>Next, install <filename + role="package">java/icedtea-web</filename> from the Ports + Collection:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/java/icedtea-web +&prompt.root; make install clean</userinput></screen> + + <para>Start <application>Chromium</application>, and enter + <literal>about:plugins</literal> in the address bar. + IcedTea-Web should be listed as one of the installed plugins.</para> + + <para>If <application>Chromium</application> does not display the + IcedTea-Web plugin, run the following commands, and restart the web + browser:</para> + + <screen>&prompt.root; <userinput>mkdir -p /usr/local/share/chromium/plugins +&prompt.root; ln -s /usr/local/lib/IcedTeaPlugin.so \ + /usr/local/share/chromium/plugins/</userinput></screen> + </sect2> + + <sect2 id="chromium-flash-plugin"> + <title>Chromium and &adobe; &flash; Plugin</title> + + <note> + <para>This section assumes <application>Chromium</application> + is already installed.</para> + </note> + + <para>Configuring <application>Chromium</application> and + &adobe; &flash; is similar to the <link + linkend="moz-flash-plugin">instructions for Firefox</link>. For + more detailed instructions on installing &adobe; &flash; on + &os;, please refer to that section. No additional configuration + should be necessary, since <application>Chromium</application> is + able to use some plugins from other browsers.</para> + </sect2> + </sect1> + + <sect1 id="desktop-productivity"> + <title>Productivity</title> + + <para>When it comes to productivity, new users often look for a + good office suite or a friendly word processor. While some + <link linkend="x11-wm">desktop environments</link> like + <application>KDE</application> already provide an office suite, + there is no default productivity package. FreeBSD can provide all that is + needed, regardless of your desktop environment.</para> + + <para>This section covers these applications:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="4"> + <thead> + <row> + <entry>Application Name</entry> + <entry>Resources Needed</entry> + <entry>Installation from Ports</entry> + <entry>Major Dependencies</entry> + </row> + </thead> + + <tbody> + <row> + <entry><application>KOffice</application></entry> + <entry>light</entry> + <entry>heavy</entry> + <entry><application>KDE</application></entry> + </row> + + <row> + <entry><application>AbiWord</application></entry> + <entry>light</entry> + <entry>light</entry> + <entry><application>Gtk+</application> or <application>GNOME</application></entry> + </row> + + <row> + <entry><application>The Gimp</application></entry> + <entry>light</entry> + <entry>heavy</entry> + <entry><application>Gtk+</application></entry> + </row> + + <row> + <entry><application>OpenOffice.org</application></entry> + <entry>heavy</entry> + <entry>huge</entry> + <entry><application>&jdk;</application>, <application>Mozilla</application></entry> + </row> + + <row> + <entry><application>LibreOffice</application></entry> + <entry>somewhat heavy</entry> + <entry>huge</entry> + <entry><application>Gtk+</application>, or <application>KDE</application>/ + <application>GNOME</application>, or <application>&jdk;</application></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <sect2> + <title>KOffice</title> + <indexterm> + <primary><application>KOffice</application></primary> + </indexterm> + <indexterm> + <primary>office suite</primary> + <secondary><application>KOffice</application></secondary> + </indexterm> + + <para>The KDE community has provided its desktop environment + with an office suite which can be used outside + <application>KDE</application>. It includes the four standard + components that can be found in other office suites. + <application>KWord</application> is the word processor, + <application>KSpread</application> is the spreadsheet program, + <application>KPresenter</application> manages slide + presentations, and <application>Kontour</application> lets you + draw graphical documents.</para> + + <para>Before installing the latest + <application>KOffice</application>, make sure you have an + up-to-date version of <application>KDE</application>.</para> + + <para>To install <application>KOffice</application> for + <application>KDE4</application> as a + package, issue the following command:</para> + + <screen>&prompt.root; <userinput>pkg_add -r koffice-kde4</userinput></screen> + + <para>If the package is not available, you can use the Ports Collection. + For instance, to install + <application>KOffice</application> for + <application>KDE4</application>, do:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/editors/koffice-kde4</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + </sect2> + + <sect2> + <title>AbiWord</title> + <indexterm> + <primary><application>AbiWord</application></primary> + </indexterm> + + <para><application>AbiWord</application> is a free word + processing program similar in look and feel to <application>µsoft; Word</application>. + It is suitable for typing papers, letters, reports, memos, and + so forth. It is very fast, contains many features, and is + very user-friendly.</para> + + <para><application>AbiWord</application> can import or export + many file formats, including some proprietary ones like + µsoft;'s <filename>.doc</filename>.</para> + + <para><application>AbiWord</application> is available as a + package. You can install it by:</para> + + <screen>&prompt.root; <userinput>pkg_add -r abiword</userinput></screen> + + <para>If the package is not available, it can be compiled from + the Ports Collection. The Ports Collection should be more + up to date. It can be done as follows:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/editors/abiword</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + </sect2> + + <sect2> + <title>The GIMP</title> + <indexterm> + <primary><application>The GIMP</application></primary> + </indexterm> + + <para>For image authoring or picture retouching, + <application>The GIMP</application> is a very sophisticated + image manipulation program. It can be used as a simple paint + program or as a quality photo retouching suite. It supports a + large number of plug-ins and features a scripting interface. + <application>The GIMP</application> can read and write a wide + range of file formats. It supports interfaces with scanners + and tablets.</para> + + <para>You can install the package by issuing this + command:</para> + + <screen>&prompt.root; <userinput>pkg_add -r gimp</userinput></screen> + + <para>If your FTP site does not have this package, you can use + the Ports Collection. The + <ulink url="http://www.FreeBSD.org/ports/graphics.html">graphics</ulink> + directory of the Ports Collection also contains + <application>The Gimp Manual</application>. Here is how to + get them installed:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/graphics/gimp</userinput> +&prompt.root; <userinput>make install clean</userinput> +&prompt.root; <userinput>cd /usr/ports/graphics/gimp-manual-pdf</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <note> + <para>The + <ulink url="http://www.FreeBSD.org/ports/graphics.html">graphics</ulink> + directory of the Ports Collection holds the development + version of <application>The GIMP</application> in + <filename role="package">graphics/gimp-devel</filename>. + An HTML version of + <application>The Gimp Manual</application> is available from + <filename role="package">graphics/gimp-manual-html</filename>.</para> + </note> + </sect2> + + <sect2> + <title>OpenOffice.org</title> + <indexterm> + <primary><application>OpenOffice.org</application></primary> + </indexterm> + <indexterm> + <primary>office suite</primary> + <secondary><application>OpenOffice.org</application></secondary> + </indexterm> + + <para><application>OpenOffice.org</application> includes all of the + mandatory applications in a complete office productivity + suite: a word processor, a spreadsheet, a presentation manager, + and a drawing program. Its user interface is very similar + to other office suites, and it can import and export in various + popular file formats. It is available in a number of + different languages — internationalization has been + extended to interfaces, spell checkers, and + dictionaries.</para> + + <para>The word processor of + <application>OpenOffice.org</application> uses a native XML + file format for increased portability and flexibility. The + spreadsheet program features a macro language and it can be + interfaced with external databases. + <application>OpenOffice.org</application> is already stable + and runs natively on &windows;, &solaris;, Linux, FreeBSD, + and &macos; X. More + information about <application>OpenOffice.org</application> + can be found on the + <ulink url="http://www.openoffice.org/">OpenOffice.org web site</ulink>. + For FreeBSD specific information, and to directly + download packages, use the <ulink + url="http://porting.openoffice.org/freebsd/">FreeBSD OpenOffice.org + Porting Team</ulink>'s web site.</para> + + <para>To install <application>OpenOffice.org</application>, + do:</para> + + <screen>&prompt.root; <userinput>pkg_add -r openoffice.org</userinput></screen> + + <note> + <para>When running a -RELEASE version of &os;, this should work. + Otherwise, you should look on the &os; <application>OpenOffice.org</application> Porting Team's + web site to download and install the appropriate package + using &man.pkg.add.1;. Both the current release and + development version are available for download at this + location.</para> + </note> + + <para>Once the package is installed, you just have to type the + following command to run + <application>OpenOffice.org</application>:</para> + + <screen>&prompt.user; <userinput>openoffice.org</userinput></screen> + + <note> + <para>During the first launch, you will be asked some + questions and a <filename>.openoffice.org</filename> folder + will be created in your home directory.</para> + </note> + + <para>If the <application>OpenOffice.org</application> packages + are not available, you still have the option to compile the + port. However, you must bear in mind that it requires a lot of + disk space and a fairly long time to compile.</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/editors/openoffice.org-3</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <note> + <para>If you want to build a localized version, replace the + previous command line with the following:</para> + + <screen>&prompt.root; <userinput>make LOCALIZED_LANG=<replaceable>your_language</replaceable> install clean</userinput></screen> + + <para>You have to replace + <replaceable>your_language</replaceable> with the correct + language ISO-code. A list of supported language codes is + available in the + <filename>files/Makefile.localized</filename> file, located + in the port directory.</para> + </note> + + <para>Once this is done, + <application>OpenOffice.org</application> can be launched with + the command:</para> + + <screen>&prompt.user; <userinput>openoffice.org</userinput></screen> + </sect2> + + <sect2> + <title>LibreOffice</title> + <indexterm> + <primary><application>LibreOffice</application></primary> + </indexterm> + <indexterm> + <primary>office suite</primary> + <secondary><application>LibreOffice</application></secondary> + </indexterm> + + <para><application>LibreOffice</application> is a free software + office suite developed by <ulink + url="http://www.documentfoundation.org/">The Document + Foundation</ulink> that is compatible with other + major office suites and available on a variety of platforms. + It is a rebranded fork of + <application>OpenOffice.org</application> which includes all of the + mandatory applications in a complete office productivity + suite: a word processor, a spreadsheet, a presentation manager, + a drawing program, a database management program, and a tool for + creating and editing mathematical formula. It is available in a + number of different languages — internationalization has been + extended to interfaces, spell checkers, and dictionaries.</para> + + <para>The word processor of <application>LibreOffice</application> + uses a native XML file format for increased portability and + flexibility. The spreadsheet program features a macro language + and it can be interfaced with external databases. + <application>LibreOffice</application> is already stable + and runs natively on &windows;, Linux, FreeBSD, and + &macos; X. More information about <application>LibreOffice + </application> can be found on the + <ulink url="http://www.libreoffice.org/">LibreOffice web site</ulink>.</para> + + <para>To install <application>LibreOffice</application> as package, + do:</para> + + <screen>&prompt.root; <userinput>pkg_add -r libreoffice</userinput></screen> + + <note> + <para>When running a -RELEASE version of &os;, this should work.</para> + </note> + + <para>Once the package is installed, you need to type the following + command to run <application>LibreOffice</application>:</para> + + <screen>&prompt.user; <userinput>libreoffice</userinput></screen> + + <note> + <para>During the first launch, you will be asked some + questions and a <filename class="directory">.libreoffice</filename> + folder will be created in your home directory.</para> + </note> + + <para>If the <application>LibreOffice</application> packages + are not available, you still have the option to compile the + port. However, you must bear in mind that it requires a lot of + disk space and a fairly long time to compile.</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/editors/libreoffice</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <note> + <para>If you want to build a localized version, replace the + previous command line with the following:</para> + + <screen>&prompt.root; <userinput>make LOCALIZED_LANG=<replaceable>your_language</replaceable> install clean</userinput></screen> + + <para>You have to replace + <replaceable>your_language</replaceable> with the correct + language ISO-code. A list of supported language codes are + available in the <maketarget>pre-fetch</maketarget> target of + the port <filename>Makefile</filename>. + </para> + </note> + + <para>Once this is done, + <application>LibreOffice</application> can be launched with + the command:</para> + + <screen>&prompt.user; <userinput>libreoffice</userinput></screen> + </sect2> + </sect1> + + <sect1 id="desktop-viewers"> + <title>Document Viewers</title> + + <para>Some new document formats have gained popularity since + the advent of &unix;; + the standard viewers they require may not be available in the + base system. We will see how to install such viewers in this + section.</para> + + <para>This section covers these applications:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="4"> + <thead> + <row> + <entry>Application Name</entry> + <entry>Resources Needed</entry> + <entry>Installation from Ports</entry> + <entry>Major Dependencies</entry> + </row> + </thead> + + <tbody> + <row> + <entry><application>&acrobat.reader;</application></entry> + <entry>light</entry> + <entry>light</entry> + <entry>Linux Binary Compatibility</entry> + </row> + + <row> + <entry><application>gv</application></entry> + <entry>light</entry> + <entry>light</entry> + <entry><application>Xaw3d</application></entry> + </row> + + <row> + <entry><application>Xpdf</application></entry> + <entry>light</entry> + <entry>light</entry> + <entry><application>FreeType</application></entry> + </row> + + <row> + <entry><application>GQview</application></entry> + <entry>light</entry> + <entry>light</entry> + <entry><application>Gtk+</application> or <application>GNOME</application></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <sect2> + <title>&acrobat.reader;</title> + <indexterm> + <primary><application>Acrobat Reader</application></primary> + </indexterm> + <indexterm> + <primary>PDF</primary> + <secondary>viewing</secondary> + </indexterm> + + <para>Many documents are now distributed as PDF files, + which stands for <quote>Portable Document Format</quote>. One + of the recommended viewers for these types of files is + <application>&acrobat.reader;</application>, released by Adobe + for Linux. As FreeBSD can run Linux binaries, it is also + available for FreeBSD.</para> + + <para>To install <application>&acrobat.reader; 8</application> from + the Ports collection, do:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/print/acroread8</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>A package is not available due to licencing restrictions.</para> + + </sect2> + + <sect2> + <title>gv</title> + <indexterm> + <primary><application>gv</application></primary> + </indexterm> + <indexterm> + <primary>PDF</primary> + <secondary>viewing</secondary> + </indexterm> + <indexterm> + <primary>PostScript</primary> + <secondary>viewing</secondary> + </indexterm> + + <para><application>gv</application> is a &postscript; and PDF + viewer. It is originally based on + <application>ghostview</application> but it has a nicer look + thanks to the <application>Xaw3d</application> library. It is fast and its interface is + clean. <application>gv</application> has many features, such as + orientation, paper size, scale, and anti-aliasing. Almost any + operation can be done with either the keyboard or the + mouse.</para> + + <para>To install <application>gv</application> as a package, + do:</para> + + <screen>&prompt.root; <userinput>pkg_add -r gv</userinput></screen> + + <para>If you cannot get the package, you can use the Ports Collection:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/print/gv</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + </sect2> + + <sect2> + <title>Xpdf</title> + <indexterm> + <primary><application>Xpdf</application></primary> + </indexterm> + <indexterm> + <primary>PDF</primary> + <secondary>viewing</secondary> + </indexterm> + + <para>If you want a small FreeBSD PDF viewer, + <application>Xpdf</application> is a light-weight and + efficient viewer. It requires very few resources and is + very stable. It uses the standard X fonts and does not + require <application>&motif;</application> or any other X toolkit.</para> + + <para>To install the <application>Xpdf</application> package, + issue this command:</para> + + <screen>&prompt.root; <userinput>pkg_add -r xpdf</userinput></screen> + + <para>If the package is not available or you prefer to use the + Ports Collection, do:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/graphics/xpdf</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>Once the installation is complete, you can launch + <application>Xpdf</application> and use the right mouse button + to activate the menu.</para> + </sect2> + + <sect2> + <title>GQview</title> + <indexterm> + <primary><application>GQview</application></primary> + </indexterm> + + <para><application>GQview</application> is an image manager. + You can view a file with a single click, launch an external + editor, get thumbnail previews, and much more. It also + features a slideshow mode and some basic file operations. You + can manage image collections and easily find duplicates. + <application>GQview</application> can do full screen viewing + and supports internationalization.</para> + + <para>If you want to install the + <application>GQview</application> package, do:</para> + + <screen>&prompt.root; <userinput>pkg_add -r gqview</userinput></screen> + + <para>If the package is not available or you prefer to use the + Ports Collection, do:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/graphics/gqview</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + </sect2> + </sect1> + + <sect1 id="desktop-finance"> + <title>Finance</title> + + <para>If, for any reason, you would like to manage your personal + finances on your FreeBSD Desktop, there are some powerful and + easy-to-use applications ready to be installed. Some of them + are compatible with widespread file formats, such as the formats used by + <application><trademark class="registered">Quicken</trademark></application> + and <application>Excel</application> to store documents.</para> + + <para>This section covers these programs:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="4"> + <thead> + <row> + <entry>Application Name</entry> + <entry>Resources Needed</entry> + <entry>Installation from Ports</entry> + <entry>Major Dependencies</entry> + </row> + </thead> + + <tbody> + <row> + <entry><application>GnuCash</application></entry> + <entry>light</entry> + <entry>heavy</entry> + <entry><application>GNOME</application></entry> + </row> + + <row> + <entry><application>Gnumeric</application></entry> + <entry>light</entry> + <entry>heavy</entry> + <entry><application>GNOME</application></entry> + </row> + + <row> + <entry><application>Abacus</application></entry> + <entry>light</entry> + <entry>light</entry> + <entry><application>Tcl/Tk</application></entry> + </row> + + <row> + <entry><application>KMyMoney</application></entry> + <entry>light</entry> + <entry>heavy</entry> + <entry><application>KDE</application></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <sect2> + <title>GnuCash</title> + <indexterm> + <primary><application>GnuCash</application></primary> + </indexterm> + + <para><application>GnuCash</application> is part of the + <application>GNOME</application> effort to provide + user-friendly, yet powerful, applications to end-users. With + <application>GnuCash</application>, you can keep track of your + income and expenses, your bank accounts, and your stocks. It + features an intuitive interface while remaining very + professional.</para> + + <para><application>GnuCash</application> provides a smart + register, a hierarchical system of accounts, and many keyboard + accelerators and auto-completion methods. It can split a + single transaction into several more detailed pieces. + <application>GnuCash</application> can import and merge + <application>Quicken</application> QIF files. It also handles + most international date and currency formats.</para> + + <para>To install <application>GnuCash</application> on your + system, do:</para> + + <screen>&prompt.root; <userinput>pkg_add -r gnucash</userinput></screen> + + <para>If the package is not available, you can use the Ports Collection:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/finance/gnucash</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + </sect2> + + <sect2> + <title>Gnumeric</title> + <indexterm> + <primary><application>Gnumeric</application></primary> + </indexterm> + <indexterm> + <primary>spreadsheet</primary> + <secondary><application>Gnumeric</application></secondary> + </indexterm> + + <para><application>Gnumeric</application> is a spreadsheet program, part + of the <application>GNOME</application> desktop environment. + It features convenient automatic <quote>guessing</quote> of user + input according to the cell format with an autofill system for + many sequences. It can import files in a number of popular + formats like those of <application>Excel</application>, + <application>Lotus 1-2-3</application>, or <application>Quattro Pro</application>. + <application>Gnumeric</application> supports graphs through + the <filename role="package">math/guppi</filename> graphing + program. It has a large number of built-in functions and + allows all of the usual cell formats such as number, currency, + date, time, and much more.</para> + + <para>To install <application>Gnumeric</application> as a + package, do:</para> + + <screen>&prompt.root; <userinput>pkg_add -r gnumeric</userinput></screen> + + <para>If the package is not available, you can use the Ports Collection + by doing:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/math/gnumeric</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + </sect2> + + <sect2> + <title>Abacus</title> + <indexterm> + <primary><application>Abacus</application></primary> + </indexterm> + <indexterm> + <primary>spreadsheet</primary> + <secondary><application>Abacus</application></secondary> + </indexterm> + + <para><application>Abacus</application> is a small and easy to + use spreadsheet program. It includes many built-in functions useful + in several domains such as statistics, finances, and + mathematics. It can import and export the <application>Excel</application> file format. + <application>Abacus</application> can produce &postscript; + output.</para> + + <para>To install <application>Abacus</application> as a + package, do:</para> + + <screen>&prompt.root; <userinput>pkg_add -r abacus</userinput></screen> + + <para>If the package is not available, you can use the Ports Collection + by doing:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/deskutils/abacus</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + </sect2> + + <sect2> + <title>KMyMoney</title> + + <indexterm><primary><application>KMyMoney</application></primary></indexterm> + + <indexterm> + <primary>spreadsheet</primary> + <secondary><application>KMyMoney</application></secondary> + </indexterm> + + <para><application>KMyMoney</application> is a personal finance + manager built for <application>KDE</application>. <application>KMyMoney</application> intends to provide and + incorporate all the important features found in commercial + personal finance manager applications. It also highlights + ease-of-use and proper double-entry accounting among its + features. <application>KMyMoney</application> imports from standard Quicken Interchange + Format (QIF) files, tracks investments, handles multiple + currencies, and provides a wealth of reports. OFX import + capabilities are also available through a separate plugin.</para> + + <para>To install <application>KMyMoney</application> as a + package, do:</para> + + <screen>&prompt.root; <userinput>pkg_add -r kmymoney2</userinput></screen> + + <para>If the package is not available, you can use the Ports + Collection by doing:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/finance/kmymoney2</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + </sect2> + </sect1> + + <sect1 id="desktop-summary"> + <title>Summary</title> + + <para>While FreeBSD is popular among ISPs for its performance and + stability, it is quite ready for day-to-day use as a desktop. + With several thousand applications available as + <ulink url="http://www.FreeBSD.org/applications.html">packages</ulink> or + <ulink url="http://www.FreeBSD.org/ports/index.html">ports</ulink>, + you can build a perfect desktop that suits all your needs.</para> + + <para>Here is a quick review of all the desktop applications + covered in this chapter:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>Application Name</entry> + <entry>Package Name</entry> + <entry>Ports Name</entry> + </row> + </thead> + + <tbody> + <row> + <entry><application>Opera</application></entry> + <entry><literal>opera</literal></entry> + <entry><filename role="package">www/opera</filename></entry> + </row> + + <row> + <entry><application>Firefox</application></entry> + <entry><literal>firefox</literal></entry> + <entry><filename role="package">www/firefox</filename></entry> + </row> + + <row> + <entry><application>Chromium</application></entry> + <entry><literal>chromium</literal></entry> + <entry><filename role="package">www/chromium</filename></entry> + </row> + + <row> + <entry><application>KOffice</application></entry> + <entry><literal>koffice-kde4</literal></entry> + <entry><filename role="package">editors/koffice-kde4</filename></entry> + </row> + + <row> + <entry><application>AbiWord</application></entry> + <entry><literal>abiword</literal></entry> + <entry><filename role="package">editors/abiword</filename></entry> + </row> + + <row> + <entry><application>The GIMP</application></entry> + <entry><literal>gimp</literal></entry> + <entry><filename role="package">graphics/gimp</filename></entry> + </row> + + <row> + <entry><application>OpenOffice.org</application></entry> + <entry><literal>openoffice</literal></entry> + <entry><filename role="package">editors/openoffice.org-3</filename></entry> + </row> + + <row> + <entry><application>LibreOffice</application></entry> + <entry><literal>libreoffice</literal></entry> + <entry><filename role="package">editors/libreoffice</filename></entry> + </row> + + <row> + <entry><application>&acrobat.reader;</application></entry> + <entry><literal>acroread</literal></entry> + <entry><filename role="package">print/acroread8</filename></entry> + </row> + + <row> + <entry><application>gv</application></entry> + <entry><literal>gv</literal></entry> + <entry><filename role="package">print/gv</filename></entry> + </row> + + <row> + <entry><application>Xpdf</application></entry> + <entry><literal>xpdf</literal></entry> + <entry><filename role="package">graphics/xpdf</filename></entry> + </row> + + <row> + <entry><application>GQview</application></entry> + <entry><literal>gqview</literal></entry> + <entry><filename role="package">graphics/gqview</filename></entry> + </row> + + <row> + <entry><application>GnuCash</application></entry> + <entry><literal>gnucash</literal></entry> + <entry><filename role="package">finance/gnucash</filename></entry> + </row> + + <row> + <entry><application>Gnumeric</application></entry> + <entry><literal>gnumeric</literal></entry> + <entry><filename role="package">math/gnumeric</filename></entry> + </row> + + <row> + <entry><application>Abacus</application></entry> + <entry><literal>abacus</literal></entry> + <entry><filename role="package">deskutils/abacus</filename></entry> + </row> + + <row> + <entry><application>KMyMoney</application></entry> + <entry><literal>kmymoney2</literal></entry> + <entry><filename role="package">finance/kmymoney2</filename></entry> + </row> + + </tbody> + </tgroup> + </informaltable> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/disks/Makefile b/en_US.ISO8859-1/books/handbook/disks/Makefile new file mode 100644 index 0000000000..140975c79e --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/disks/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= disks/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/disks/chapter.sgml b/en_US.ISO8859-1/books/handbook/disks/chapter.sgml new file mode 100644 index 0000000000..fa88f03677 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/disks/chapter.sgml @@ -0,0 +1,4880 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="disks"> + <title>Storage</title> + + <sect1 id="disks-synopsis"> + <title>Synopsis</title> + + <para>This chapter covers the use of disks in FreeBSD. This + includes memory-backed disks, network-attached disks, + standard SCSI/IDE storage devices, and devices using the USB + interface.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>The terminology FreeBSD uses to describe the + organization of data on a physical disk (partitions and + slices).</para> + </listitem> + + <listitem> + <para>How to add additional hard disks to your system.</para> + </listitem> + + <listitem> + <para>How to configure &os; to use USB storage devices.</para> + </listitem> + + <listitem> + <para>How to set up virtual file systems, such as memory + disks.</para> + </listitem> + + <listitem> + <para>How to use quotas to limit disk space usage.</para> + </listitem> + + <listitem> + <para>How to encrypt disks to secure them against + attackers.</para> + </listitem> + + <listitem> + <para>How to create and burn CDs and DVDs on FreeBSD.</para> + </listitem> + + <listitem> + <para>The various storage media options for backups.</para> + </listitem> + + <listitem> + <para>How to use backup programs available under + FreeBSD.</para> + </listitem> + + <listitem> + <para>How to backup to floppy disks.</para> + </listitem> + + <listitem> + <para>What file system snapshots are and how to use them + efficiently.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Know how to configure and install a new FreeBSD kernel + (<xref linkend="kernelconfig">).</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="disks-naming"> + <title>Device Names</title> + + <para>The following is a list of physical storage devices + supported in FreeBSD, and the device names associated with + them.</para> + + <table id="disk-naming-physical-table" frame="none"> + <title>Physical Disk Naming Conventions</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Drive type</entry> + <entry>Drive device name</entry> + </row> + </thead> + + <tbody> + <row> + <entry>IDE hard drives</entry> + <entry><literal>ad</literal></entry> + </row> + + <row> + <entry>IDE CDROM drives</entry> + <entry><literal>acd</literal></entry> + </row> + + <row> + <entry>SCSI hard drives and USB Mass storage + devices</entry> + <entry><literal>da</literal></entry> + </row> + + <row> + <entry>SCSI CDROM drives</entry> + <entry><literal>cd</literal></entry> + </row> + + <row> + <entry>Assorted non-standard CDROM drives</entry> + <entry><literal>mcd</literal> for Mitsumi CD-ROM and + <literal>scd</literal> for Sony CD-ROM devices</entry> + </row> + + <row> + <entry>Floppy drives</entry> + <entry><literal>fd</literal></entry> + </row> + + <row> + <entry>SCSI tape drives</entry> + <entry><literal>sa</literal></entry> + </row> + + <row> + <entry>IDE tape drives</entry> + <entry><literal>ast</literal></entry> + </row> + + <row> + <entry>Flash drives</entry> + <entry><literal>fla</literal> for &diskonchip; Flash + device</entry> + </row> + + <row> + <entry>RAID drives</entry> + <entry><literal>aacd</literal> for &adaptec; AdvancedRAID, + <literal>mlxd</literal> and <literal>mlyd</literal> + for &mylex;, + <literal>amrd</literal> for AMI &megaraid;, + <literal>idad</literal> for Compaq Smart RAID, + <literal>twed</literal> for &tm.3ware; RAID.</entry> + </row> + </tbody> + </tgroup> + </table> + </sect1> + + <sect1 id="disks-adding"> + <sect1info> + <authorgroup> + <author> + <firstname>David</firstname> + <surname>O'Brien</surname> + <contrib>Originally contributed by </contrib> + </author> + </authorgroup> + <!-- 26 Apr 1998 --> + </sect1info> + + <title>Adding Disks</title> + + <indexterm> + <primary>disks</primary> + <secondary>adding</secondary> + </indexterm> + + <para>The following section will describe how to add a new + <acronym>SCSI</acronym> disk to a machine that currently only + has a single drive. First turn off the computer and install the + drive in the computer following the instructions of the + computer, controller, and drive manufacturer. Due to the wide + variations of procedures to do this, the details are beyond the + scope of this document.</para> + + <para>Login as user <username>root</username>. After you have + installed the drive, inspect + <filename>/var/run/dmesg.boot</filename> to ensure the new disk + was found. Continuing with our example, the newly added drive + will be <devicename>da1</devicename> and we want to mount it on + <filename>/1</filename> (if you are adding an IDE drive, the + device name will be <devicename>ad1</devicename>).</para> + + <indexterm><primary>partitions</primary></indexterm> + <indexterm><primary>slices</primary></indexterm> + <indexterm> + <primary><command>fdisk</command></primary> + </indexterm> + + <para>FreeBSD runs on IBM-PC compatible computers, therefore it + must take into account the PC BIOS partitions. These are + different from the traditional BSD partitions. A PC disk has up + to four BIOS partition entries. If the disk is going to be + truly dedicated to FreeBSD, you can use the + <emphasis>dedicated</emphasis> mode. Otherwise, FreeBSD will + have to live within one of the PC BIOS partitions. FreeBSD + calls the PC BIOS partitions <emphasis>slices</emphasis> so as + not to confuse them with traditional BSD partitions. You may + also use slices on a disk that is dedicated to FreeBSD, but used + in a computer that also has another operating system installed. + This is a good way to avoid confusing the + <command>fdisk</command> utility of other, non-FreeBSD operating + systems.</para> + + <para>In the slice case the drive will be added as + <filename>/dev/da1s1e</filename>. This is read as: SCSI disk, + unit number 1 (second SCSI disk), slice 1 (PC BIOS partition 1), + and <filename>e</filename> BSD partition. In the dedicated + case, the drive will be added simply as + <filename>/dev/da1e</filename>.</para> + + <para>Due to the use of 32-bit integers to store the number of + sectors, &man.bsdlabel.8; is limited to 2^32-1 sectors per disk + or 2TB in most cases. The &man.fdisk.8; format allows a + starting sector of no more than 2^32-1 and a length of no more + than 2^32-1, limiting partitions to 2TB and disks to 4TB in most + cases. The &man.sunlabel.8; format is limited to 2^32-1 sectors + per partition and 8 partitions for a total of 16TB. For larger + disks, &man.gpart.8; may be used to create + <acronym>GPT</acronym> partitions. <acronym>GPT</acronym> has + the added benefit of not being limited to 4 slices.</para> + + <sect2> + <title>Using &man.sysinstall.8;</title> + <indexterm> + <primary><application>sysinstall</application></primary> + <secondary>adding disks</secondary> + </indexterm> + <indexterm> + <primary>su</primary> + </indexterm> + + <procedure> + <step> + <title>Navigating + <application>Sysinstall</application></title> + + <para>You may use <command>sysinstall</command> to partition + and label a new disk using its easy to use menus. Either + login as user <username>root</username> or use the + <command>su</command> command. Run + <command>sysinstall</command> and enter the + <literal>Configure</literal> menu. Within the + <literal>FreeBSD Configuration Menu</literal>, scroll down + and select the <literal>Fdisk</literal> option.</para> + </step> + + <step> + <title><application>fdisk</application> Partition + Editor</title> + + <para>Once inside <application>fdisk</application>, pressing + <keycap>A</keycap> will use the entire disk for FreeBSD. + When asked if you want to <quote>remain cooperative with + any future possible operating systems</quote>, answer + <literal>YES</literal>. Write the changes to the disk + using <keycap>W</keycap>. Now exit the FDISK editor by + pressing <keycap>Q</keycap>. Next you will be asked about + the <quote>Master Boot Record</quote>. Since you are + adding a disk to an already running system, choose + <literal>None</literal>.</para> + </step> + + <step> + <title>Disk Label Editor</title> + <indexterm><primary>BSD partitions</primary></indexterm> + + <para>Next, you need to exit + <application>sysinstall</application> and start it again. + Follow the directions above, although this time choose the + <literal>Label</literal> option. This will enter the + <literal>Disk Label Editor</literal>. This is where you + will create the traditional BSD partitions. A disk can + have up to eight partitions, labeled + <literal>a-h</literal>. A few of the partition labels + have special uses. The <literal>a</literal> partition is + used for the root partition (<filename>/</filename>). + Thus only your system disk (e.g., the disk you boot from) + should have an <literal>a</literal> partition. The + <literal>b</literal> partition is used for swap + partitions, and you may have many disks with swap + partitions. The <literal>c</literal> partition addresses + the entire disk in dedicated mode, or the entire FreeBSD + slice in slice mode. The other partitions are for general + use.</para> + + <para><application>sysinstall</application>'s Label editor + favors the <literal>e</literal> partition for non-root, + non-swap partitions. Within the Label editor, create a + single file system by pressing <keycap>C</keycap>. When + prompted if this will be a FS (file system) or swap, + choose <literal>FS</literal> and type in a mount point + (e.g., <filename>/mnt</filename>). When adding a disk in + post-install mode, <application>sysinstall</application> + will not create entries in <filename>/etc/fstab</filename> + for you, so the mount point you specify is not + important.</para> + + <para>You are now ready to write the new label to the disk + and create a file system on it. Do this by pressing + <keycap>W</keycap>. Ignore any errors from + <application>sysinstall</application> that it could not + mount the new partition. Exit the Label Editor and + <application>sysinstall</application> completely.</para> + </step> + + <step> + <title>Finish</title> + + <para>The last step is to edit + <filename>/etc/fstab</filename> to add an entry for your + new disk.</para> + </step> + </procedure> + </sect2> + + <sect2> + <title>Using Command Line Utilities</title> + + <sect3> + <title>Using Slices</title> + + <para>This setup will allow your disk to work correctly with + other operating systems that might be installed on your + computer and will not confuse other operating systems' + <command>fdisk</command> utilities. It is recommended + to use this method for new disk installs. Only use + <literal>dedicated</literal> mode if you have a good reason + to do so!</para> + + <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput> +&prompt.root; <userinput>fdisk -BI da1</userinput> #Initialize your new disk +&prompt.root; <userinput>bsdlabel -B -w da1s1 auto</userinput> #Label it. +&prompt.root; <userinput>bsdlabel -e da1s1</userinput> # Edit the bsdlabel just created and add any partitions. +&prompt.root; <userinput>mkdir -p /1</userinput> +&prompt.root; <userinput>newfs /dev/da1s1e</userinput> # Repeat this for every partition you created. +&prompt.root; <userinput>mount /dev/da1s1e /1</userinput> # Mount the partition(s) +&prompt.root; <userinput>vi /etc/fstab</userinput> # Add the appropriate entry/entries to your <filename>/etc/fstab</filename>.</screen> + + <para>If you have an IDE disk, substitute + <filename>ad</filename> for <filename>da</filename>.</para> + </sect3> + + <sect3> + <title>Dedicated</title> + <indexterm><primary>OS/2</primary></indexterm> + + <para>If you will not be sharing the new drive with another + operating system, you may use the + <literal>dedicated</literal> mode. Remember this mode can + confuse Microsoft operating systems; however, no damage will + be done by them. IBM's &os2; however, will + <quote>appropriate</quote> any partition it finds which it + does not understand.</para> + + <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 bs=1k count=1</userinput> +&prompt.root; <userinput>bsdlabel -Bw da1 auto</userinput> +&prompt.root; <userinput>bsdlabel -e da1</userinput> # create the `e' partition +&prompt.root; <userinput>newfs /dev/da1e</userinput> +&prompt.root; <userinput>mkdir -p /1</userinput> +&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e +&prompt.root; <userinput>mount /1</userinput></screen> + + <para>An alternate method is:</para> + + <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/da1 count=2</userinput> +&prompt.root; <userinput>bsdlabel /dev/da1 | bsdlabel -BR da1 /dev/stdin</userinput> +&prompt.root; <userinput>newfs /dev/da1e</userinput> +&prompt.root; <userinput>mkdir -p /1</userinput> +&prompt.root; <userinput>vi /etc/fstab</userinput> # add an entry for /dev/da1e +&prompt.root; <userinput>mount /1</userinput></screen> + + </sect3> + </sect2> + </sect1> + + <sect1 id="raid"> + <title>RAID</title> + + <sect2 id="raid-soft"> + <title>Software RAID</title> + + <sect3 id="ccd"> + <sect3info> + <authorgroup> + <author> + <firstname>Christopher</firstname> + <surname>Shumway</surname> + <contrib>Original work by </contrib> + </author> + </authorgroup> + + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Brown</surname> + <contrib>Revised by </contrib> + </author> + </authorgroup> + </sect3info> + + <indexterm><primary>RAID</primary><secondary>software</secondary></indexterm> + <indexterm><primary>RAID</primary><secondary>CCD</secondary></indexterm> + + <title>Concatenated Disk Driver (CCD) Configuration</title> + + <para>When choosing a mass storage solution the most important + factors to consider are speed, reliability, and cost. It is + rare to have all three in balance; normally a fast, reliable + mass storage device is expensive, and to cut back on cost + either speed or reliability must be sacrificed.</para> + + <para>In designing the system described below, cost was + chosen as the most important factor, followed by speed, + then reliability. Data transfer speed for this system is + ultimately constrained by the network. And while + reliability is very important, the CCD drive described + below serves online data that is already fully backed up + on CD-R's and can easily be replaced.</para> + + <para>Defining your own requirements is the first step in + choosing a mass storage solution. If your requirements + prefer speed or reliability over cost, your solution will + differ from the system described in this section.</para> + + <sect4 id="ccd-installhw"> + <title>Installing the Hardware</title> + + <para>In addition to the IDE system disk, three Western + Digital 30GB, 5400 RPM IDE disks form the core of the CCD + disk described below providing approximately 90GB of + online storage. Ideally, each IDE disk would have its own + IDE controller and cable, but to minimize cost, additional + IDE controllers were not used. Instead the disks were + configured with jumpers so that each IDE controller has + one master, and one slave.</para> + + <para>Upon reboot, the system BIOS was configured to + automatically detect the disks attached. More + importantly, FreeBSD detected them on reboot:</para> + + <programlisting>ad0: 19574MB <WDC WD205BA> [39770/16/63] at ata0-master UDMA33 +ad1: 29333MB <WDC WD307AA> [59598/16/63] at ata0-slave UDMA33 +ad2: 29333MB <WDC WD307AA> [59598/16/63] at ata1-master UDMA33 +ad3: 29333MB <WDC WD307AA> [59598/16/63] at ata1-slave UDMA33</programlisting> + + <note><para>If FreeBSD does not detect all the disks, ensure + that you have jumpered them correctly. Most IDE drives + also have a <quote>Cable Select</quote> jumper. This is + <emphasis>not</emphasis> the jumper for the master/slave + relationship. Consult the drive documentation for help in + identifying the correct jumper.</para></note> + + <para>Next, consider how to attach them as part of the file + system. You should research both &man.vinum.4; (<xref + linkend="vinum-vinum">) and &man.ccd.4;. In this + particular configuration, &man.ccd.4; was chosen.</para> + </sect4> + + <sect4 id="ccd-setup"> + <title>Setting Up the CCD</title> + + <para>The &man.ccd.4; driver allows you to take several + identical disks and concatenate them into one logical file + system. In order to use &man.ccd.4;, you need a kernel + with &man.ccd.4; support built in. Add this line to your + kernel configuration file, rebuild, and reinstall the + kernel:</para> + + <programlisting>device ccd</programlisting> + + <para>The &man.ccd.4; support can also be loaded as a kernel + loadable module.</para> + + <para>To set up &man.ccd.4;, you must first use + &man.bsdlabel.8; to label the disks:</para> + + <programlisting>bsdlabel -w ad1 auto +bsdlabel -w ad2 auto +bsdlabel -w ad3 auto</programlisting> + + <para>This creates a bsdlabel for + <devicename>ad1c</devicename>, + <devicename>ad2c</devicename> and + <devicename>ad3c</devicename> that spans the entire + disk.</para> + + <para>The next step is to change the disk label type. You + can use &man.bsdlabel.8; to edit the disks:</para> + + <programlisting>bsdlabel -e ad1 +bsdlabel -e ad2 +bsdlabel -e ad3</programlisting> + + <para>This opens up the current disk label on each disk with + the editor specified by the <envar>EDITOR</envar> + environment variable, typically &man.vi.1;.</para> + + <para>An unmodified disk label will look something like + this:</para> + + <programlisting>8 partitions: +# size offset fstype [fsize bsize bps/cpg] + c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597)</programlisting> + + <para>Add a new <literal>e</literal> partition for + &man.ccd.4; to use. This can usually be copied from the + <literal>c</literal> partition, but the + <option>fstype</option> <emphasis>must</emphasis> be + <userinput>4.2BSD</userinput>. The disk label should now + look something like this:</para> + + <programlisting>8 partitions: +# size offset fstype [fsize bsize bps/cpg] + c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) + e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597)</programlisting> + </sect4> + + <sect4 id="ccd-buildingfs"> + <title>Building the File System</title> + + <para>Now that you have all the disks labeled, you must + build the &man.ccd.4;. To do that, use &man.ccdconfig.8;, + with options similar to the following:</para> + + <programlisting>ccdconfig ccd0<co id="co-ccd-dev"> 32<co id="co-ccd-interleave"> 0<co id="co-ccd-flags"> /dev/ad1e<co id="co-ccd-devs"> /dev/ad2e /dev/ad3e</programlisting> + + <para>The use and meaning of each option is shown + below:</para> + + <calloutlist> + <callout arearefs="co-ccd-dev"> + <para>The first argument is the device to configure, in + this case, <filename>/dev/ccd0c</filename>. The + <filename>/dev/</filename> portion is optional.</para> + </callout> + + <callout arearefs="co-ccd-interleave"> + <para>The interleave for the file system. The + interleave defines the size of a stripe in disk + blocks, each normally 512 bytes. So, an interleave of + 32 would be 16,384 bytes.</para> + </callout> + + <callout arearefs="co-ccd-flags"> + <para>Flags for &man.ccdconfig.8;. If you want to + enable drive mirroring, you can specify a flag here. + This configuration does not provide mirroring for + &man.ccd.4;, so it is set at 0 (zero).</para> + </callout> + + <callout arearefs="co-ccd-devs"> + <para>The final arguments to &man.ccdconfig.8; are the + devices to place into the array. Use the complete + pathname for each device.</para> + </callout> + </calloutlist> + + <para>After running &man.ccdconfig.8; the &man.ccd.4; is + configured. A file system can be installed. Refer to + &man.newfs.8; for options, or simply run: </para> + + <programlisting>newfs /dev/ccd0c</programlisting> + </sect4> + + <sect4 id="ccd-auto"> + <title>Making it All Automatic</title> + + <para>Generally, you will want to mount the &man.ccd.4; upon + each reboot. To do this, you must configure it first. + Write out your current configuration to + <filename>/etc/ccd.conf</filename> using the following + command:</para> + + <programlisting>ccdconfig -g > /etc/ccd.conf</programlisting> + + <para>During reboot, the script <command>/etc/rc</command> + runs <command>ccdconfig -C</command> if + <filename>/etc/ccd.conf</filename> exists. This + automatically configures the &man.ccd.4; so it can be + mounted.</para> + + <note> + <para>If you are booting into single user mode, before you + can &man.mount.8; the &man.ccd.4;, you need to issue the + following command to configure the array:</para> + + <programlisting>ccdconfig -C</programlisting> + </note> + + <para>To automatically mount the &man.ccd.4;, place an entry + for the &man.ccd.4; in <filename>/etc/fstab</filename> so + it will be mounted at boot time:</para> + + <programlisting>/dev/ccd0c /media ufs rw 2 2</programlisting> + </sect4> + </sect3> + + <sect3 id="vinum"> + <title>The Vinum Volume Manager</title> + + <indexterm> + <primary>RAID</primary> + <secondary>software</secondary> + </indexterm> + <indexterm> + <primary>RAID</primary> + <secondary>Vinum</secondary> + </indexterm> + + <para>The Vinum Volume Manager is a block device driver which + implements virtual disk drives. It isolates disk hardware + from the block device interface and maps data in ways which + result in an increase in flexibility, performance and + reliability compared to the traditional slice view of disk + storage. &man.vinum.4; implements the RAID-0, RAID-1 and + RAID-5 models, both individually and in combination.</para> + + <para>See <xref linkend="vinum-vinum"> for more + information about &man.vinum.4;.</para> + </sect3> + </sect2> + + <sect2 id="raid-hard"> + <title>Hardware RAID</title> + + <indexterm> + <primary>RAID</primary> + <secondary>hardware</secondary> + </indexterm> + + <para>FreeBSD also supports a variety of hardware + <acronym>RAID</acronym> controllers. These devices control a + <acronym>RAID</acronym> subsystem without the need for FreeBSD + specific software to manage the array.</para> + + <para>Using an on-card <acronym>BIOS</acronym>, the card + controls most of the disk operations itself. The following is + a brief setup description using a Promise + <acronym>IDE</acronym> <acronym>RAID</acronym> controller. + When this card is installed and the system is started up, it + displays a prompt requesting information. Follow the + instructions to enter the card's setup screen. From here, you + have the ability to combine all the attached drives. After + doing so, the disk(s) will look like a single drive to + FreeBSD. Other <acronym>RAID</acronym> levels can be set up + accordingly.</para> + </sect2> + + <sect2> + <title>Rebuilding ATA RAID1 Arrays</title> + + <para>FreeBSD allows you to hot-replace a failed disk in an + array. This requires that you catch it before you + reboot.</para> + + <para>You will probably see something like the following in + <filename>/var/log/messages</filename> or in the &man.dmesg.8; + output:</para> + + <programlisting>ad6 on monster1 suffered a hard error. +ad6: READ command timeout tag=0 serv=0 - resetting +ad6: trying fallback to PIO mode +ata3: resetting devices .. done +ad6: hard error reading fsbn 1116119 of 0-7 (ad6 bn 1116119; cn 1107 tn 4 sn 11)\\ +status=59 error=40 +ar0: WARNING - mirror lost</programlisting> + + <para>Using &man.atacontrol.8;, check for further + information:</para> + + <screen>&prompt.root; <userinput>atacontrol list</userinput> +ATA channel 0: + Master: no device present + Slave: acd0 <HL-DT-ST CD-ROM GCR-8520B/1.00> ATA/ATAPI rev 0 + +ATA channel 1: + Master: no device present + Slave: no device present + +ATA channel 2: + Master: ad4 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 + Slave: no device present + +ATA channel 3: + Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 + Slave: no device present + +&prompt.root; <userinput>atacontrol status ar0</userinput> +ar0: ATA RAID1 subdisks: ad4 ad6 status: DEGRADED</screen> + + <procedure> + <step> + <para>You will first need to detach the ata channel with the + failed disk so you can safely remove it:</para> + + <screen>&prompt.root; <userinput>atacontrol detach ata3</userinput></screen> + </step> + + <step> + <para>Replace the disk.</para> + </step> + + <step> + <para>Reattach the ata channel:</para> + + <screen>&prompt.root; <userinput>atacontrol attach ata3</userinput> +Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 +Slave: no device present</screen> + </step> + + <step> + <para>Add the new disk to the array as a spare:</para> + + <screen>&prompt.root; <userinput>atacontrol addspare ar0 ad6</userinput></screen> + </step> + + <step> + <para>Rebuild the array:</para> + + <screen>&prompt.root; <userinput>atacontrol rebuild ar0</userinput></screen> + </step> + + <step> + <para>It is possible to check on the progress by issuing the + following command:</para> + + <screen>&prompt.root; <userinput>dmesg | tail -10</userinput> +[output removed] +ad6: removed from configuration +ad6: deleted from ar0 disk1 +ad6: inserted into ar0 disk1 as spare + +&prompt.root; <userinput>atacontrol status ar0</userinput> +ar0: ATA RAID1 subdisks: ad4 ad6 status: REBUILDING 0% completed</screen> + </step> + + <step> + <para>Wait until this operation completes.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="usb-disks"> + <sect1info> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <!-- Jul 2004 --> + </sect1info> + + <title>USB Storage Devices</title> + <indexterm> + <primary>USB</primary> + <secondary>disks</secondary> + </indexterm> + + <para>A lot of external storage solutions, nowadays, use the + Universal Serial Bus (USB): hard drives, USB thumbdrives, CD-R + burners, etc. &os; provides support for these devices.</para> + + <sect2> + <title>Configuration</title> + + <para>The USB mass storage devices driver, &man.umass.4;, + provides the support for USB storage devices. If you use the + <filename>GENERIC</filename> kernel, you do not have to change + anything in your configuration. If you use a custom kernel, + be sure that the following lines are present in your kernel + configuration file:</para> + + <programlisting>device scbus +device da +device pass +device uhci +device ohci +device ehci +device usb +device umass</programlisting> + + <para>The &man.umass.4; driver uses the SCSI subsystem to access + to the USB storage devices, your USB device will be seen as a + SCSI device by the system. Depending on the USB chipset on + your motherboard, you only need either <literal>device + uhci</literal> or <literal>device ohci</literal> for USB 1.X + support, however having both in the kernel configuration file + is harmless. Support for USB 2.0 controllers is provided by + the &man.ehci.4; driver (the <literal>device ehci</literal> + line). Do not forget to compile and install the new kernel if + you added any lines.</para> + + <note> + <para>If your USB device is a CD-R or DVD burner, the SCSI + CD-ROM driver, &man.cd.4;, must be added to the kernel via + the line:</para> + + <programlisting>device cd</programlisting> + + <para>Since the burner is seen as a SCSI drive, the driver + &man.atapicam.4; should not be used in the kernel + configuration.</para> + </note> + </sect2> + + <sect2> + <title>Testing the Configuration</title> + + <para>The configuration is ready to be tested: plug in your USB + device, and in the system message buffer (&man.dmesg.8;), the + drive should appear as something like:</para> + + <screen>umass0: USB Solid state disk, rev 1.10/1.00, addr 2 +GEOM: create disk da0 dp=0xc2d74850 +da0 at umass-sim0 bus 0 target 0 lun 0 +da0: <Generic Traveling Disk 1.11> Removable Direct Access SCSI-2 device +da0: 1.000MB/s transfers +da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)</screen> + + <para>Of course, the brand, the device node + (<devicename>da0</devicename>) and other details can differ + according to your configuration.</para> + + <para>Since the USB device is seen as a SCSI one, the + <command>camcontrol</command> command can be used to list the + USB storage devices attached to the system:</para> + + <screen>&prompt.root; <userinput>camcontrol devlist</userinput> +<Generic Traveling Disk 1.11> at scbus0 target 0 lun 0 (da0,pass0)</screen> + + <para>If the drive comes with a file system, you should be able + to mount it. The <xref linkend="disks-adding"> will help you + to format and create partitions on the USB drive if + needed.</para> + + <warning> + <para>Allowing untrusted users to mount arbitrary media, + e.g., by enabling <literal>vfs.usermount</literal> as + described below, should not be considered safe from a + security point of view. Most file systems in &os; were not + built to safeguard against malicious devices.</para> + </warning> + + <para>To make this device mountable as a normal user, certain + steps have to be taken. First, the devices that are created + when a USB storage device is connected need to be accessible + by the user. A solution is to make all users of these devices + a member of the <groupname>operator</groupname> group. This + is done with &man.pw.8;. Second, when the devices are + created, the <groupname>operator</groupname> group should be + able to read and write them. This is accomplished by adding + these lines to + <filename>/etc/devfs.rules</filename>:</para> + + <programlisting>[localrules=5] +add path 'da*' mode 0660 group operator</programlisting> + + <note> + <para>If there already are SCSI disks in the system, it must + be done a bit different. E.g., if the system already + contains disks <devicename>da0</devicename> through + <devicename>da2</devicename> attached to the system, change + the second line as follows:</para> + + <programlisting>add path 'da[3-9]*' mode 0660 group operator</programlisting> + + <para>This will exclude the already existing disks from + belonging to the <groupname>operator</groupname> + group.</para> + </note> + + <para>You also have to enable your &man.devfs.rules.5; ruleset + in your <filename>/etc/rc.conf</filename> file:</para> + + <programlisting>devfs_system_ruleset="localrules"</programlisting> + + <para>Next, the kernel has to be configured to allow regular + users to mount file systems. The easiest way is to add the + following line to + <filename>/etc/sysctl.conf</filename>:</para> + + <programlisting>vfs.usermount=1</programlisting> + + <para>Note that this only takes effect after the next reboot. + Alternatively, one can also use &man.sysctl.8; to set this + variable.</para> + + <para>The final step is to create a directory where the file + system is to be mounted. This directory needs to be owned by + the user that is to mount the file system. One way to do that + is for <username>root</username> to create a subdirectory + owned by that user as + <filename>/mnt/<replaceable>username</replaceable></filename> + (replace <replaceable>username</replaceable> by the login name + of the actual user and <replaceable>usergroup</replaceable> by + the user's primary group):</para> + + <screen>&prompt.root; <userinput>mkdir /mnt/<replaceable>username</replaceable></userinput> +&prompt.root; <userinput>chown <replaceable>username</replaceable>:<replaceable>usergroup</replaceable> /mnt/<replaceable>username</replaceable></userinput></screen> + + <para>Suppose a USB thumbdrive is plugged in, and a device + <filename>/dev/da0s1</filename> appears. Since these devices + usually come preformatted with a FAT file system, one can + mount them like this:</para> + + <screen>&prompt.user; <userinput>mount -t msdosfs -o -m=644,-M=755 /dev/da0s1 /mnt/<replaceable>username</replaceable></userinput></screen> + + <para>If you unplug the device (the disk must be unmounted + before), you should see, in the system message buffer, + something like the following:</para> + + <screen>umass0: at uhub0 port 1 (addr 2) disconnected +(da0:umass-sim0:0:0:0): lost device +(da0:umass-sim0:0:0:0): removing device entry +GEOM: destroy disk da0 dp=0xc2d74850 +umass0: detached</screen> + </sect2> + + <sect2> + <title>Further Reading</title> + + <para>Beside the <link linkend="disks-adding">Adding + Disks</link> and <link linkend="mount-unmount">Mounting and + Unmounting File Systems</link> sections, reading various + manual pages may be also useful: &man.umass.4;, + &man.camcontrol.8;, and &man.usbconfig.8; under &os; 8.X + or &man.usbdevs.8; under earlier versions of &os;.</para> + </sect2> + </sect1> + + <sect1 id="creating-cds"> + <sect1info> + <authorgroup> + <author> + <firstname>Mike</firstname> + <surname>Meyer</surname> + <contrib>Contributed by </contrib> + <!-- mwm@mired.org --> + </author> + </authorgroup> + <!-- Apr 2001 --> + </sect1info> + + <title>Creating and Using Optical Media (CDs)</title> + <indexterm> + <primary>CDROMs</primary> + <secondary>creating</secondary> + </indexterm> + + <sect2> + <title>Introduction</title> + + <para>CDs have a number of features that differentiate them from + conventional disks. Initially, they were not writable by the + user. They are designed so that they can be read continuously + without delays to move the head between tracks. They are also + much easier to transport between systems than similarly sized + media were at the time.</para> + + <para>CDs do have tracks, but this refers to a section of data + to be read continuously and not a physical property of the + disk. To produce a CD on FreeBSD, you prepare the data files + that are going to make up the tracks on the CD, then write the + tracks to the CD.</para> + + <indexterm><primary>ISO 9660</primary></indexterm> + <indexterm> + <primary>file systems</primary> + <secondary>ISO 9660</secondary> + </indexterm> + + <para>The ISO 9660 file system was designed to deal with these + differences. It unfortunately codifies file system limits + that were common then. Fortunately, it provides an extension + mechanism that allows properly written CDs to exceed those + limits while still working with systems that do not support + those extensions.</para> + + <indexterm> + <primary><filename + role="package">sysutils/cdrtools</filename></primary> + </indexterm> + + <para>The <filename role="package">sysutils/cdrtools</filename> + port includes &man.mkisofs.8;, a program that you can use to + produce a data file containing an ISO 9660 file + system. It has options that support various extensions, and + is described below.</para> + + <indexterm> + <primary>CD burner</primary> + <secondary>ATAPI</secondary> + </indexterm> + + <para>Which tool to use to burn the CD depends on whether your + CD burner is ATAPI or something else. ATAPI CD burners use + the <command><link linkend="burncd">burncd</link></command> + program that is part of the base system. SCSI and USB CD + burners should use + <command><link linkend="cdrecord">cdrecord</link></command> + from the <filename role="package">sysutils/cdrtools</filename> + port. It is also possible to use + <command><link linkend="cdrecord">cdrecord</link></command> + and other tools for SCSI drives on ATAPI hardware with the + <link linkend="atapicam">ATAPI/CAM module</link>.</para> + + <para>If you want CD burning software with a graphical user + interface, you may wish to take a look at either + <application>X-CD-Roast</application> or + <application>K3b</application>. These tools are available as + packages or from the + <filename role="package">sysutils/xcdroast</filename> and + <filename role="package">sysutils/k3b</filename> ports. + <application>X-CD-Roast</application> and + <application>K3b</application> require the + <link linkend="atapicam">ATAPI/CAM module</link> with ATAPI + hardware.</para> + </sect2> + + <sect2 id="mkisofs"> + <title><application>mkisofs</application></title> + + <para>The &man.mkisofs.8; program, which is part of the + <filename role="package">sysutils/cdrtools</filename> port, + produces an ISO 9660 file system that is an image of a + directory tree in the &unix; file system name space. The + simplest usage is:</para> + + <screen>&prompt.root; <userinput>mkisofs -o <replaceable>imagefile.iso</replaceable> <replaceable>/path/to/tree</replaceable></userinput></screen> + + <indexterm> + <primary>file systems</primary> + <secondary>ISO 9660</secondary> + </indexterm> + + <para>This command will create an + <replaceable>imagefile.iso</replaceable> containing an ISO + 9660 file system that is a copy of the tree at + <replaceable>/path/to/tree</replaceable>. In the process, it + will map the file names to names that fit the limitations of + the standard ISO 9660 file system, and will exclude files that + have names uncharacteristic of ISO file systems.</para> + + <indexterm> + <primary>file systems</primary> + <secondary>HFS</secondary> + </indexterm> + <indexterm> + <primary>file systems</primary> + <secondary>Joliet</secondary> + </indexterm> + <para>A number of options are available to overcome those + restrictions. In particular, <option>-R</option> enables the + Rock Ridge extensions common to &unix; systems, + <option>-J</option> enables Joliet extensions used by + Microsoft systems, and <option>-hfs</option> can be used to + create HFS file systems used by &macos;.</para> + + <para>For CDs that are going to be used only on FreeBSD systems, + <option>-U</option> can be used to disable all filename + restrictions. When used with <option>-R</option>, it produces + a file system image that is identical to the FreeBSD tree you + started from, though it may violate the ISO 9660 standard in a + number of ways.</para> + + <indexterm> + <primary>CDROMs</primary> + <secondary>creating bootable</secondary> + </indexterm> + <para>The last option of general use is <option>-b</option>. + This is used to specify the location of the boot image for use + in producing an <quote>El Torito</quote> bootable CD. This + option takes an argument which is the path to a boot image + from the top of the tree being written to the CD. By default, + &man.mkisofs.8; creates an ISO image in the so-called + <quote>floppy disk emulation</quote> mode, and thus expects + the boot image to be exactly 1200, 1440 or 2880 KB in + size. Some boot loaders, like the one used by the FreeBSD + distribution disks, do not use emulation mode; in this case, + the <option>-no-emul-boot</option> option should be used. So, + if <filename>/tmp/myboot</filename> holds a bootable FreeBSD + system with the boot image in + <filename>/tmp/myboot/boot/cdboot</filename>, you could + produce the image of an ISO 9660 file system in + <filename>/tmp/bootable.iso</filename> like so:</para> + + <screen>&prompt.root; <userinput>mkisofs -R -no-emul-boot -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot</userinput></screen> + + <para>Having done that, if you have <devicename>md</devicename> + configured in your kernel, you can mount the file system + with:</para> + + <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /tmp/bootable.iso -u 0</userinput> +&prompt.root; <userinput>mount -t cd9660 /dev/md0 /mnt</userinput></screen> + + <para>At which point you can verify that + <filename>/mnt</filename> and <filename>/tmp/myboot</filename> + are identical.</para> + + <para>There are many other options you can use with + &man.mkisofs.8; to fine-tune its behavior. In particular: + modifications to an ISO 9660 layout and the creation of Joliet + and HFS discs. See the &man.mkisofs.8; manual page for + details.</para> + </sect2> + + <sect2 id="burncd"> + <title><application>burncd</application></title> + <indexterm> + <primary>CDROMs</primary> + <secondary>burning</secondary> + </indexterm> + <para>If you have an ATAPI CD burner, you can use the + <command>burncd</command> command to burn an ISO image onto a + CD. <command>burncd</command> is part of the base system, + installed as <filename>/usr/sbin/burncd</filename>. Usage is + very simple, as it has few options:</para> + + <screen>&prompt.root; <userinput>burncd -f <replaceable>cddevice</replaceable> data <replaceable>imagefile.iso</replaceable> fixate</userinput></screen> + + <para>Will burn a copy of + <replaceable>imagefile.iso</replaceable> on + <replaceable>cddevice</replaceable>. The default device is + <filename>/dev/acd0</filename>. See &man.burncd.8; for + options to set the write speed, eject the CD after burning, + and write audio data.</para> + </sect2> + + <sect2 id="cdrecord"> + <title><application>cdrecord</application></title> + + <para>If you do not have an ATAPI CD burner, you will have to + use <command>cdrecord</command> to burn your CDs. + <command>cdrecord</command> is not part of the base system; + you must install it from either the port at + <filename role="package">sysutils/cdrtools</filename> or the + appropriate package. Changes to the base system can cause + binary versions of this program to fail, possibly resulting in + a <quote>coaster</quote>. You should therefore either upgrade + the port when you upgrade your system, or if you are + <link linkend="stable">tracking -STABLE</link>, upgrade the + port when a new version becomes available.</para> + + <para>While <command>cdrecord</command> has many options, basic + usage is even simpler than <command>burncd</command>. Burning + an ISO 9660 image is done with:</para> + + <screen>&prompt.root; <userinput>cdrecord dev=<replaceable>device</replaceable> <replaceable>imagefile.iso</replaceable></userinput></screen> + + <para>The tricky part of using <command>cdrecord</command> is + finding the <option>dev</option> to use. To find the proper + setting, use the <option>-scanbus</option> flag of + <command>cdrecord</command>, which might produce results like + this:</para> + + <indexterm> + <primary>CDROMs</primary> + <secondary>burning</secondary> + </indexterm> + <screen>&prompt.root; <userinput>cdrecord -scanbus</userinput> +Cdrecord-Clone 2.01 (i386-unknown-freebsd7.0) Copyright (C) 1995-2004 Jörg Schilling +Using libscg version 'schily-0.1' +scsibus0: + 0,0,0 0) 'SEAGATE ' 'ST39236LW ' '0004' Disk + 0,1,0 1) 'SEAGATE ' 'ST39173W ' '5958' Disk + 0,2,0 2) * + 0,3,0 3) 'iomega ' 'jaz 1GB ' 'J.86' Removable Disk + 0,4,0 4) 'NEC ' 'CD-ROM DRIVE:466' '1.26' Removable CD-ROM + 0,5,0 5) * + 0,6,0 6) * + 0,7,0 7) * +scsibus1: + 1,0,0 100) * + 1,1,0 101) * + 1,2,0 102) * + 1,3,0 103) * + 1,4,0 104) * + 1,5,0 105) 'YAMAHA ' 'CRW4260 ' '1.0q' Removable CD-ROM + 1,6,0 106) 'ARTEC ' 'AM12S ' '1.06' Scanner + 1,7,0 107) *</screen> + + <para>This lists the appropriate <option>dev</option> value for + the devices on the list. Locate your CD burner, and use the + three numbers separated by commas as the value for + <option>dev</option>. In this case, the CRW device is 1,5,0, + so the appropriate input would be <option>dev=1,5,0</option>. + There are easier ways to specify this value; see + &man.cdrecord.1; for details. That is also the place to look + for information on writing audio tracks, controlling the + speed, and other things.</para> + </sect2> + + <sect2 id="duplicating-audiocds"> + <title>Duplicating Audio CDs</title> + + <para>You can duplicate an audio CD by extracting the audio data + from the CD to a series of files, and then writing these files + to a blank CD. The process is slightly different for ATAPI + and SCSI drives.</para> + + <procedure> + <title>SCSI Drives</title> + + <step> + <para>Use <command>cdda2wav</command> to extract the + audio.</para> + + <screen>&prompt.user; <userinput>cdda2wav -vall -D2,0 -B -Owav</userinput></screen> + </step> + + <step> + <para>Use <command>cdrecord</command> to write the + <filename>.wav</filename> files.</para> + + <screen>&prompt.user; <userinput>cdrecord -v dev=<replaceable>2,0</replaceable> -dao -useinfo *.wav</userinput></screen> + + <para>Make sure that <replaceable>2,0</replaceable> is set + appropriately, as described in + <xref linkend="cdrecord">.</para> + </step> + </procedure> + + <procedure> + <title>ATAPI Drives</title> + + <note> + <para>With the help of the + <link linkend="atapicam">ATAPI/CAM module</link>, + <command>cdda2wav</command> can also be used on ATAPI + drives. This tool is usually a better choice for most of + users (jitter correction, endianness issues, etc.) than + the method proposed below.</para> + </note> + + <step> + <para>The ATAPI CD driver makes each track available as + <filename>/dev/acd<replaceable>d</replaceable>t<replaceable>nn</replaceable></filename>, + where <replaceable>d</replaceable> is the drive number, + and <replaceable>nn</replaceable> is the track number + written with two decimal digits, prefixed with zero as + needed. So the first track on the first disk is + <filename>/dev/acd0t01</filename>, the second is + <filename>/dev/acd0t02</filename>, the third is + <filename>/dev/acd0t03</filename>, and so on.</para> + + <para>Make sure the appropriate files exist in + <filename>/dev</filename>. If the entries are missing, + force the system to retaste the media:</para> + + <screen>&prompt.root; <userinput>dd if=/dev/acd0 of=/dev/null count=1</userinput></screen> + </step> + + <step> + <para>Extract each track using &man.dd.1;. You must also + use a specific block size when extracting the + files.</para> + + <screen>&prompt.root; <userinput>dd if=/dev/acd0t01 of=track1.cdr bs=2352</userinput> +&prompt.root; <userinput>dd if=/dev/acd0t02 of=track2.cdr bs=2352</userinput> +...</screen> + </step> + + <step> + <para>Burn the extracted files to disk using + <command>burncd</command>. You must specify that these + are audio files, and that <command>burncd</command> should + fixate the disk when finished.</para> + + <screen>&prompt.root; <userinput>burncd -f <replaceable>/dev/acd0</replaceable> audio track1.cdr track2.cdr <replaceable>...</replaceable> fixate</userinput></screen> + </step> + </procedure> + </sect2> + + <sect2 id="imaging-cd"> + <title>Duplicating Data CDs</title> + + <para>You can copy a data CD to a image file that is + functionally equivalent to the image file created with + &man.mkisofs.8;, and you can use it to duplicate any data CD. + The example given here assumes that your CDROM device is + <devicename>acd0</devicename>. Substitute your correct CDROM + device.</para> + + <screen>&prompt.root; <userinput>dd if=/dev/acd0 of=file.iso bs=2048</userinput></screen> + + <para>Now that you have an image, you can burn it to CD as + described above.</para> + </sect2> + + <sect2 id="mounting-cd"> + <title>Using Data CDs</title> + + <para>Now that you have created a standard data CDROM, you + probably want to mount it and read the data on it. By + default, &man.mount.8; assumes that a file system is of type + <literal>ufs</literal>. If you try something like:</para> + + <screen>&prompt.root; <userinput>mount /dev/cd0 /mnt</userinput></screen> + + <para>you will get a complaint about <errorname>Incorrect super + block</errorname>, and no mount. The CDROM is not a + <literal>UFS</literal> file system, so attempts to mount it as + such will fail. You just need to tell &man.mount.8; that the + file system is of type <literal>ISO9660</literal>, and + everything will work. You do this by specifying the + <option>-t cd9660</option> option &man.mount.8;. For example, + if you want to mount the CDROM device, + <filename>/dev/cd0</filename>, under + <filename>/mnt</filename>, you would execute:</para> + + <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen> + + <para>Note that your device name (<filename>/dev/cd0</filename> + in this example) could be different, depending on the + interface your CDROM uses. Also, the <option>-t + cd9660</option> option just executes &man.mount.cd9660.8;. + The above example could be shortened to:</para> + + <screen>&prompt.root; <userinput>mount_cd9660 /dev/cd0 /mnt</userinput></screen> + + <para>You can generally use data CDROMs from any vendor in this + way. Disks with certain ISO 9660 extensions might behave + oddly, however. For example, Joliet disks store all filenames + in two-byte Unicode characters. The FreeBSD kernel does not + speak Unicode, but the &os; CD9660 driver is able to convert + Unicode characters on the fly. If some non-English characters + show up as question marks you will need to specify the local + charset you use with the <option>-C</option> option. For more + information, consult the &man.mount.cd9660.8; manual + page.</para> + + <note> + <para>To be able to do this character conversion with the help + of the <option>-C</option> option, the kernel will require + the <filename>cd9660_iconv.ko</filename> module to be + loaded. This can be done either by adding this line to + <filename>loader.conf</filename>:</para> + + <programlisting>cd9660_iconv_load="YES"</programlisting> + + <para>and then rebooting the machine, or by directly loading + the module with &man.kldload.8;.</para> + </note> + + <para>Occasionally, you might get <errorname>Device not + configured</errorname> when trying to mount a CDROM. This + usually means that the CDROM drive thinks that there is no + disk in the tray, or that the drive is not visible on the bus. + It can take a couple of seconds for a CDROM drive to realize + that it has been fed, so be patient.</para> + + <para>Sometimes, a SCSI CDROM may be missed because it did not + have enough time to answer the bus reset. If you have a SCSI + CDROM please add the following option to your kernel + configuration and <link + linkend="kernelconfig-building">rebuild your + kernel</link>.</para> + + <programlisting>options SCSI_DELAY=15000</programlisting> + + <para>This tells your SCSI bus to pause 15 seconds during boot, + to give your CDROM drive every possible chance to answer the + bus reset.</para> + </sect2> + + <sect2 id="rawdata-cd"> + <title>Burning Raw Data CDs</title> + + <para>You can choose to burn a file directly to CD, without + creating an ISO 9660 file system. Some people do this for + backup purposes. This runs more quickly than burning a + standard CD:</para> + + <screen>&prompt.root; <userinput>burncd -f /dev/acd1 -s 12 data archive.tar.gz fixate</userinput></screen> + + <para>In order to retrieve the data burned to such a CD, you + must read data from the raw device node:</para> + + <screen>&prompt.root; <userinput>tar xzvf /dev/acd1</userinput></screen> + + <para>You cannot mount this disk as you would a normal CDROM. + Such a CDROM cannot be read under any operating system + except FreeBSD. If you want to be able to mount the CD, or + share data with another operating system, you must use + &man.mkisofs.8; as described above.</para> + </sect2> + + <sect2 id="atapicam"> + <sect2info> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + + <indexterm> + <primary>CD burner</primary> + <secondary>ATAPI/CAM driver</secondary> + </indexterm> + <title>Using the ATAPI/CAM Driver</title> + + <para>This driver allows ATAPI devices (CD-ROM, CD-RW, DVD + drives etc...) to be accessed through the SCSI subsystem, and + so allows the use of applications like <filename + role="package">sysutils/cdrdao</filename> or + &man.cdrecord.1;.</para> + + <para>To use this driver, you will need to add the following + line to the <filename>/boot/loader.conf</filename> + file:</para> + + <programlisting>atapicam_load="YES"</programlisting> + + <para>then, reboot your machine.</para> + + <note> + <para>If you prefer to statically compile the &man.atapicam.4; + support in your kernel, you will have to add this line to + your kernel configuration file:</para> + + <programlisting>device atapicam</programlisting> + + <para>You also need the following lines in your kernel + configuration file:</para> + + <programlisting>device ata +device scbus +device cd +device pass</programlisting> + + <para>which should already be present. Then rebuild, install + your new kernel, and reboot your machine.</para> + </note> + + <para>During the boot process, your burner should show up, + like so:</para> + + <screen>acd0: CD-RW <MATSHITA CD-RW/DVD-ROM UJDA740> at ata1-master PIO4 +cd0 at ata1 bus 0 target 0 lun 0 +cd0: <MATSHITA CDRW/DVD UJDA740 1.00> Removable CD-ROM SCSI-0 device +cd0: 16.000MB/s transfers +cd0: Attempt to query device size failed: NOT READY, Medium not present - tray closed</screen> + + <para>The drive could now be accessed via the + <filename>/dev/cd0</filename> device name, for example to + mount a CD-ROM on <filename>/mnt</filename>, just type the + following:</para> + + <screen>&prompt.root; <userinput>mount -t cd9660 <replaceable>/dev/cd0</replaceable> /mnt</userinput></screen> + + <para>As <username>root</username>, you can run the following + command to get the SCSI address of the burner:</para> + + <screen>&prompt.root; <userinput>camcontrol devlist</userinput> +<MATSHITA CDRW/DVD UJDA740 1.00> at scbus1 target 0 lun 0 (pass0,cd0)</screen> + + <para>So <literal>1,0,0</literal> will be the SCSI address to + use with &man.cdrecord.1; and other SCSI application.</para> + + <para>For more information about ATAPI/CAM and SCSI system, + refer to the &man.atapicam.4; and &man.cam.4; manual + pages.</para> + </sect2> + </sect1> + + <sect1 id="creating-dvds"> + <sect1info> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Andy</firstname> + <surname>Polyakov</surname> + <contrib>With inputs from </contrib> + </author> + </authorgroup> + <!-- Feb 2004 --> + </sect1info> + + <title>Creating and Using Optical Media (DVDs)</title> + <indexterm> + <primary>DVD</primary> + <secondary>burning</secondary> + </indexterm> + + <sect2> + <title>Introduction</title> + + <para>Compared to the CD, the DVD is the next generation of + optical media storage technology. The DVD can hold more data + than any CD and is nowadays the standard for video + publishing.</para> + + <para>Five physical recordable formats can be defined for what + we will call a recordable DVD:</para> + + <itemizedlist> + <listitem> + <para>DVD-R: This was the first DVD recordable format + available. The DVD-R standard is defined by the + <ulink url="http://www.dvdforum.com/forum.shtml">DVD + Forum</ulink>. This format is write once.</para> + </listitem> + + <listitem> + <para>DVD-RW: This is the rewritable version of the + DVD-R standard. A DVD-RW can be rewritten about 1000 + times.</para> + </listitem> + + <listitem> + <para>DVD-RAM: This is also a rewritable format + supported by the DVD Forum. A DVD-RAM can be seen as a + removable hard drive. However, this media is not + compatible with most DVD-ROM drives and DVD-Video players; + only a few DVD writers support the DVD-RAM format. Read + the <xref linkend="creating-dvd-ram"> for more information + on DVD-RAM use.</para> + </listitem> + + <listitem> + <para>DVD+RW: This is a rewritable format defined by + the <ulink url="http://www.dvdrw.com/">DVD+RW + Alliance</ulink>. A DVD+RW can be rewritten about 1000 + times.</para> + </listitem> + + <listitem> + <para>DVD+R: This format is the write once variation + of the DVD+RW format.</para> + </listitem> + </itemizedlist> + + <para>A single layer recordable DVD can hold up to + 4,700,000,000 bytes which is actually 4.38 GB or + 4485 MB (1 kilobyte is 1024 bytes).</para> + + <note> + <para>A distinction must be made between the physical media + and the application. For example, a DVD-Video is a specific + file layout that can be written on any recordable DVD + physical media: DVD-R, DVD+R, DVD-RW etc. Before choosing + the type of media, you must be sure that both the burner and + the DVD-Video player (a standalone player or a DVD-ROM drive + on a computer) are compatible with the media under + consideration.</para> + </note> + </sect2> + + <sect2> + <title>Configuration</title> + + <para>The program &man.growisofs.1; will be used to perform DVD + recording. This command is part of the + <application>dvd+rw-tools</application> utilities (<filename + role="package">sysutils/dvd+rw-tools</filename>). The + <application>dvd+rw-tools</application> support all DVD media + types.</para> + + <para>These tools use the SCSI subsystem to access to the + devices, therefore the <link linkend="atapicam">ATAPI/CAM + support</link> must be added to your kernel. If your burner + uses the USB interface this addition is useless, and you + should read the <xref linkend="usb-disks"> for more details on + USB devices configuration.</para> + + <para>You also have to enable DMA access for ATAPI devices, this + can be done in adding the following line to the + <filename>/boot/loader.conf</filename> file:</para> + + <programlisting>hw.ata.atapi_dma="1"</programlisting> + + <para>Before attempting to use the + <application>dvd+rw-tools</application> you should consult the + <ulink + url="http://fy.chalmers.se/~appro/linux/DVD+RW/hcn.html">dvd+rw-tools' + hardware compatibility notes</ulink> for any information + related to your DVD burner.</para> + + <note> + <para>If you want a graphical user interface, you should have + a look to <application>K3b</application> (<filename + role="package">sysutils/k3b</filename>) which provides a + user friendly interface to &man.growisofs.1; and many other + burning tools.</para> + </note> + </sect2> + + <sect2> + <title>Burning Data DVDs</title> + + <para>The &man.growisofs.1; command is a frontend to <link + linkend="mkisofs">mkisofs</link>, it will invoke + &man.mkisofs.8; to create the file system layout and will + perform the write on the DVD. This means you do not need to + create an image of the data before the burning process.</para> + + <para>To burn onto a DVD+R or a DVD-R the data from the + <filename class="directory">/path/to/data</filename> + directory, use the following command:</para> + + <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen> + + <para>The options <option>-J -R</option> are passed to + &man.mkisofs.8; for the file system creation (in this case: an + ISO 9660 file system with Joliet and Rock Ridge extensions), + consult the &man.mkisofs.8; manual page for more + details.</para> + + <para>The option <option>-Z</option> is used for the initial + session recording in any case: multiple sessions or not. The + DVD device, <replaceable>/dev/cd0</replaceable>, must be + changed according to your configuration. The + <option>-dvd-compat</option> parameter will close the disk, + the recording will be unappendable. In return this should + provide better media compatibility with DVD-ROM drives.</para> + + <para>It is also possible to burn a pre-mastered image, for + example to burn the image + <replaceable>imagefile.iso</replaceable>, we will run:</para> + + <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z <replaceable>/dev/cd0</replaceable>=<replaceable>imagefile.iso</replaceable></userinput></screen> + + <para>The write speed should be detected and automatically set + according to the media and the drive being used. If you want + to force the write speed, use the <option>-speed=</option> + parameter. For more information, read the &man.growisofs.1; + manual page.</para> + + <note> + <para>In order to have working files larger than 4.38GB in + your compilation, an UDF/ISO-9660 hybrid filesystem must be + created by passing additional <option>-udf -iso-level + 3</option> parameter to &man.mkisofs.8; and all related + programs (i.e., &man.growisofs.1;). This is required only + when creating an ISO image file, or writing files directly + to a disk. Disk created this way must be mounted as an UDF + filesystem with &man.mount.udf.8; utility, so it will be + usable only on an UDF aware Operating System,otherwise it + will look as if it contains corrupted files.</para> + + <para>To create a such ISO file:</para> + + <screen>&prompt.user; <userinput>mkisofs -R -J -udf -iso-level 3 -o <replaceable>imagefile.iso</replaceable> <replaceable>/path/to/data</replaceable></userinput></screen> + + <para>To burn files directly to a disk:</para> + + <screen>&prompt.root; <userinput>growisofs -dvd-compat -udf -iso-level 3 -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen> + + <para>When you have an ISO image containing large files + already inside, no additional options are required for + &man.growisofs.1; to burn that image on a disk.</para> + + <para>Also, be sure that you have an up-to-date version of + <filename role="package">sysutils/cdrtools</filename> (which + contain &man.mkisofs.8;), as the older ones does not + contain large files support. If you experience troubles + please move to the development package, i.e., <filename + role="package">sysutils/cdrtools-devel</filename> and read + &man.mkisofs.8; manual page.</para> + </note> + </sect2> + + <indexterm> + <primary>DVD</primary> + <secondary>DVD-Video</secondary> + </indexterm> + + <sect2> + <title>Burning a DVD-Video</title> + + <para>A DVD-Video is a specific file layout based on ISO 9660 + and the micro-UDF (M-UDF) specifications. The DVD-Video also + presents a specific data structure hierarchy, it is the reason + why you need a particular program such as <filename + role="package">multimedia/dvdauthor</filename> to author the + DVD.</para> + + <para>If you already have an image of the DVD-Video file system, + just burn it in the same way as for any image, see the + previous section for an example. If you have made the DVD + authoring and the result is in, for example, the directory + <filename class="directory">/path/to/video</filename>, the + following command should be used to burn the DVD-Video:</para> + + <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -dvd-video <replaceable>/path/to/video</replaceable></userinput></screen> + + <para>The <option>-dvd-video</option> option will be passed down + to &man.mkisofs.8; and will instruct it to create a DVD-Video + file system layout. Beside this, the + <option>-dvd-video</option> option implies + <option>-dvd-compat</option> &man.growisofs.1; option.</para> + </sect2> + + <indexterm> + <primary>DVD</primary> + <secondary>DVD+RW</secondary> + </indexterm> + + <sect2> + <title>Using a DVD+RW</title> + + <para>Unlike CD-RW, a virgin DVD+RW needs to be formatted before + first use. The &man.growisofs.1; program will take care of it + automatically whenever appropriate, which is the + <emphasis>recommended</emphasis> way. However you can use the + <command>dvd+rw-format</command> command to format the + DVD+RW:</para> + + <screen>&prompt.root; <userinput>dvd+rw-format <replaceable>/dev/cd0</replaceable></userinput></screen> + + <para>You need to perform this operation just once, keep in mind + that only virgin DVD+RW medias need to be formatted. Then you + can burn the DVD+RW in the way seen in previous + sections.</para> + + <para>If you want to burn new data (burn a totally new file + system not append some data) onto a DVD+RW, you do not need to + blank it, you just have to write over the previous recording + (in performing a new initial session), like this:</para> + + <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/newdata</replaceable></userinput></screen> + + <para>DVD+RW format offers the possibility to easily append data + to a previous recording. The operation consists in merging a + new session to the existing one, it is not multisession + writing, &man.growisofs.1; will <emphasis>grow</emphasis> the + ISO 9660 file system present on the media.</para> + + <para>For example, if we want to append data to our previous + DVD+RW, we have to use the following:</para> + + <screen>&prompt.root; <userinput>growisofs -M <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/nextdata</replaceable></userinput></screen> + + <para>The same &man.mkisofs.8; options we used to burn the + initial session should be used during next writes.</para> + + <note> + <para>You may want to use the <option>-dvd-compat</option> + option if you want better media compatibility with DVD-ROM + drives. In the DVD+RW case, this will not prevent you from + adding data.</para> + </note> + + <para>If for any reason you really want to blank the media, do + the following:</para> + + <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable>=<replaceable>/dev/zero</replaceable></userinput></screen> + </sect2> + + <indexterm> + <primary>DVD</primary> + <secondary>DVD-RW</secondary> + </indexterm> + + <sect2> + <title>Using a DVD-RW</title> + + <para>A DVD-RW accepts two disc formats: the incremental + sequential one and the restricted overwrite. By default + DVD-RW discs are in sequential format.</para> + + <para>A virgin DVD-RW can be directly written without the need + of a formatting operation, however a non-virgin DVD-RW in + sequential format needs to be blanked before to be able to + write a new initial session.</para> + + <para>To blank a DVD-RW in sequential mode, run:</para> + + <screen>&prompt.root; <userinput>dvd+rw-format -blank=full <replaceable>/dev/cd0</replaceable></userinput></screen> + + <note> + <para>A full blanking (<option>-blank=full</option>) will take + about one hour on a 1x media. A fast blanking can be + performed using the <option>-blank</option> option if the + DVD-RW will be recorded in Disk-At-Once (DAO) mode. To burn + the DVD-RW in DAO mode, use the command:</para> + + <screen>&prompt.root; <userinput>growisofs -use-the-force-luke=dao -Z <replaceable>/dev/cd0</replaceable>=<replaceable>imagefile.iso</replaceable></userinput></screen> + + <para>The <option>-use-the-force-luke=dao</option> option + should not be required since &man.growisofs.1; attempts to + detect minimally (fast blanked) media and engage DAO + write.</para> + + <para>In fact one should use restricted overwrite mode with + any DVD-RW, this format is more flexible than the default + incremental sequential one.</para> + </note> + + <para>To write data on a sequential DVD-RW, use the same + instructions as for the other DVD formats:</para> + + <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen> + + <para>If you want to append some data to your previous + recording, you will have to use the &man.growisofs.1; + <option>-M</option> option. However, if you perform data + addition on a DVD-RW in incremental sequential mode, a new + session will be created on the disc and the result will be a + multi-session disc.</para> + + <para>A DVD-RW in restricted overwrite format does not need to + be blanked before a new initial session, you just have to + overwrite the disc with the <option>-Z</option> option, this + is similar to the DVD+RW case. It is also possible to grow an + existing ISO 9660 file system written on the disc in a same + way as for a DVD+RW with the <option>-M</option> option. The + result will be a one-session DVD.</para> + + <para>To put a DVD-RW in the restricted overwrite format, the + following command must be used:</para> + + <screen>&prompt.root; <userinput>dvd+rw-format <replaceable>/dev/cd0</replaceable></userinput></screen> + + <para>To change back to the sequential format use:</para> + + <screen>&prompt.root; <userinput>dvd+rw-format -blank=full <replaceable>/dev/cd0</replaceable></userinput></screen> + </sect2> + + <sect2> + <title>Multisession</title> + + <para>Very few DVD-ROM drives support + multisession DVDs, they will most of time, hopefully, only + read the first session. DVD+R, DVD-R and DVD-RW in sequential + format can accept multiple sessions, the notion of multiple + sessions does not exist for the DVD+RW and the DVD-RW + restricted overwrite formats.</para> + + <para>Using the following command after an initial (non-closed) + session on a DVD+R, DVD-R, or DVD-RW in sequential format, + will add a new session to the disc:</para> + + <screen>&prompt.root; <userinput>growisofs -M <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/nextdata</replaceable></userinput></screen> + + <para>Using this command line with a DVD+RW or a DVD-RW in + restricted overwrite mode, will append data in merging the new + session to the existing one. The result will be a + single-session disc. This is the way used to add data after + an initial write on these medias.</para> + + <note> + <para>Some space on the media is used between each session for + end and start of sessions. Therefore, one should add + sessions with large amount of data to optimize media space. + The number of sessions is limited to 154 for a DVD+R, + about 2000 for a DVD-R, and 127 for a DVD+R Double + Layer.</para> + </note> + </sect2> + + <sect2> + <title>For More Information</title> + + <para>To obtain more information about a DVD, the + <command>dvd+rw-mediainfo + <replaceable>/dev/cd0</replaceable></command> command can be + ran with the disc in the drive.</para> + + <para>More information about the + <application>dvd+rw-tools</application> can be found in + the &man.growisofs.1; manual page, on the <ulink + url="http://fy.chalmers.se/~appro/linux/DVD+RW/">dvd+rw-tools + web site</ulink> and in the <ulink + url="http://lists.debian.org/cdwrite/">cdwrite mailing + list</ulink> archives.</para> + + <note> + <para>The <command>dvd+rw-mediainfo</command> output of the + resulting recording or the media with issues is mandatory + for any problem report. Without this output, it will be + quite impossible to help you.</para> + </note> + </sect2> + + <sect2 id="creating-dvd-ram"> + <title>Using a DVD-RAM</title> + <indexterm> + <primary>DVD</primary> + <secondary>DVD-RAM</secondary> + </indexterm> + + <sect3> + <title>Configuration</title> + + <para>DVD-RAM writers come with either SCSI or ATAPI + interface. DMA access for ATAPI devices has to be enabled, + this can be done by adding the following line to the + <filename>/boot/loader.conf</filename> file:</para> + + <programlisting>hw.ata.atapi_dma="1"</programlisting> + </sect3> + + <sect3> + <title>Preparing the Medium</title> + + <para>As previously mentioned in the chapter introduction, a + DVD-RAM can be seen as a removable hard drive. As any other + hard drive the DVD-RAM must be <quote>prepared</quote> + before the first use. In the example, the whole disk space + will be used with a standard UFS2 file system:</para> + + <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/dev/acd0</replaceable> bs=2k count=1</userinput> +&prompt.root; <userinput>bsdlabel -Bw <replaceable>acd0</replaceable></userinput> +&prompt.root; <userinput>newfs <replaceable>/dev/acd0</replaceable></userinput></screen> + + <para>The DVD device, <devicename>acd0</devicename>, must be + changed according to the configuration.</para> + </sect3> + + <sect3> + <title>Using the Medium</title> + + <para>Once the previous operations have been performed on the + DVD-RAM, it can be mounted as a normal hard drive:</para> + + <screen>&prompt.root; <userinput>mount <replaceable>/dev/acd0</replaceable> <replaceable>/mnt</replaceable></userinput></screen> + + <para>After this the DVD-RAM will be both readable and + writeable.</para> + </sect3> + </sect2> + </sect1> + + <sect1 id="floppies"> + <sect1info> + <authorgroup> + <author> + <firstname>Julio</firstname> + <surname>Merino</surname> + <contrib>Original work by </contrib> + </author> + </authorgroup> + <!-- 24 Dec 2001 --> + <authorgroup> + <author> + <firstname>Martin</firstname> + <surname>Karlsson</surname> + <contrib>Rewritten by </contrib> + </author> + </authorgroup> + <!-- 27 Apr 2003 --> + </sect1info> + + <title>Creating and Using Floppy Disks</title> + + <para>Storing data on floppy disks is sometimes useful, for + example when one does not have any other removable storage media + or when one needs to transfer small amounts of data to another + computer.</para> + + <para>This section will explain how to use floppy disks in + FreeBSD. It will primarily cover formatting and usage of + 3.5inch DOS floppies, but the concepts are similar for other + floppy disk formats.</para> + + <sect2> + <title>Formatting Floppies</title> + + <sect3> + <title>The Device</title> + + <para>Floppy disks are accessed through entries in + <filename>/dev</filename>, just like other devices. To + access the raw floppy disk, simply use + <filename>/dev/fd<replaceable>N</replaceable></filename>.</para> + </sect3> + + <sect3> + <title>Formatting</title> + + <para>A floppy disk needs to be low-level formatted before it + can be used. This is usually done by the vendor, but + formatting is a good way to check media integrity. Although + it is possible to force larger (or smaller) disk sizes, + 1440kB is what most floppy disks are designed for.</para> + + <para>To low-level format the floppy disk you need to use + &man.fdformat.1;. This utility expects the device name as + an argument.</para> + + <para>Make note of any error messages, as these can help + determine if the disk is good or bad.</para> + + <sect4> + <title>Formatting Floppy Disks</title> + + <para>Use the + <filename>/dev/fd<replaceable>N</replaceable></filename> + devices to format the floppy. Insert a new 3.5inch floppy + disk in your drive and issue:</para> + + <screen>&prompt.root; <userinput>/usr/sbin/fdformat -f 1440 /dev/fd0</userinput></screen> + </sect4> + </sect3> + </sect2> + + <sect2> + <title>The Disk Label</title> + + <para>After low-level formatting the disk, you will need to + place a disk label on it. This disk label will be destroyed + later, but it is needed by the system to determine the size of + the disk and its geometry later.</para> + + <para>The new disk label will take over the whole disk, and will + contain all the proper information about the geometry of the + floppy. The geometry values for the disk label are listed in + <filename>/etc/disktab</filename>.</para> + + <para>You can run now &man.bsdlabel.8; like so:</para> + + <screen>&prompt.root; <userinput>/sbin/bsdlabel -B -w /dev/fd0 fd1440</userinput></screen> + </sect2> + + <sect2> + <title>The File System</title> + + <para>Now the floppy is ready to be high-level formatted. This + will place a new file system on it, which will let FreeBSD + read and write to the disk. After creating the new file + system, the disk label is destroyed, so if you want to + reformat the disk, you will have to recreate the disk + label.</para> + + <para>The floppy's file system can be either UFS or FAT. + FAT is generally a better choice for floppies.</para> + + <para>To put a new file system on the floppy, issue:</para> + + <screen>&prompt.root; <userinput>/sbin/newfs_msdos /dev/fd0</userinput></screen> + + <para>The disk is now ready for use.</para> + </sect2> + + <sect2> + <title>Using the Floppy</title> + + <para>To use the floppy, mount it with &man.mount.msdosfs.8;. + One can also use + <filename role="package">emulators/mtools</filename> from the + ports collection.</para> + </sect2> + </sect1> + + <sect1 id="backups-tapebackups"> + <title>Creating and Using Data Tapes</title> + + <indexterm><primary>tape media</primary></indexterm> + + <para>The major tape media are the 4mm, 8mm, QIC, mini-cartridge + and DLT.</para> + + <sect2 id="backups-tapebackups-4mm"> + <title>4mm (DDS: Digital Data Storage)</title> + + <indexterm> + <primary>tape media</primary> + <secondary>DDS (4mm) tapes</secondary> + </indexterm> + <indexterm> + <primary>tape media</primary> + <secondary>QIC tapes</secondary> + </indexterm> + <para>4mm tapes are replacing QIC as the workstation backup + media of choice. This trend accelerated greatly when Conner + purchased Archive, a leading manufacturer of QIC drives, and + then stopped production of QIC drives. 4mm drives are small + and quiet but do not have the reputation for reliability that + is enjoyed by 8mm drives. The cartridges are less expensive + and smaller (3 x 2 x 0.5 inches, 76 x 51 x 12 mm) than 8mm + cartridges. 4mm, like 8mm, has comparatively short head life + for the same reason, both use helical scan.</para> + + <para>Data throughput on these drives starts ~150 kB/s, + peaking at ~500 kB/s. Data capacity starts at + 1.3 GB and ends at 2.0 GB. Hardware compression, + available with most of these drives, approximately doubles the + capacity. Multi-drive tape library units can have 6 drives in + a single cabinet with automatic tape changing. Library + capacities reach 240 GB.</para> + + <para>The DDS-3 standard now supports tape capacities up to + 12 GB (or 24 GB compressed).</para> + + <para>4mm drives, like 8mm drives, use helical-scan. All the + benefits and drawbacks of helical-scan apply to both 4mm and + 8mm drives.</para> + + <para>Tapes should be retired from use after 2,000 passes or 100 + full backups.</para> + </sect2> + + <sect2 id="backups-tapebackups-8mm"> + <title>8mm (Exabyte)</title> + <indexterm> + <primary>tape media</primary> + <secondary>Exabyte (8mm) tapes</secondary> + </indexterm> + + <para>8mm tapes are the most common SCSI tape drives; they are + the best choice of exchanging tapes. Nearly every site has an + Exabyte 2 GB 8mm tape drive. 8mm drives are reliable, + convenient and quiet. Cartridges are inexpensive and small + (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm). One downside of + 8mm tape is relatively short head and tape life due to the + high rate of relative motion of the tape across the + heads.</para> + + <para>Data throughput ranges from ~250 kB/s to + ~500 kB/s. Data sizes start at 300 MB and go up to + 7 GB. Hardware compression, available with most of these + drives, approximately doubles the capacity. These drives are + available as single units or multi-drive tape libraries with 6 + drives and 120 tapes in a single cabinet. Tapes are changed + automatically by the unit. Library capacities reach + 840+ GB.</para> + + <para>The Exabyte <quote>Mammoth</quote> model supports + 12 GB on one tape (24 GB with compression) and costs + approximately twice as much as conventional tape + drives.</para> + + <para>Data is recorded onto the tape using helical-scan, the + heads are positioned at an angle to the media (approximately 6 + degrees). The tape wraps around 270 degrees of the spool that + holds the heads. The spool spins while the tape slides over + the spool. The result is a high density of data and closely + packed tracks that angle across the tape from one edge to the + other.</para> + </sect2> + + <sect2 id="backups-tapebackups-qic"> + <title>QIC</title> + + <indexterm> + <primary>tape media</primary> + <secondary>QIC-150</secondary> + </indexterm> + + <para>QIC-150 tapes and drives are, perhaps, the most common + tape drive and media around. QIC tape drives are the least + expensive <quote>serious</quote> backup drives. The downside + is the cost of media. QIC tapes are expensive compared to 8mm + or 4mm tapes, up to 5 times the price per GB data storage. + But, if your needs can be satisfied with a half-dozen tapes, + QIC may be the correct choice. QIC is the + <emphasis>most</emphasis> common tape drive. Every site has a + QIC drive of some density or another. Therein lies the rub, + QIC has a large number of densities on physically similar + (sometimes identical) tapes. QIC drives are not quiet. These + drives audibly seek before they begin to record data and are + clearly audible whenever reading, writing or seeking. QIC + tapes measure 6 x 4 x 0.7 inches (152 x + 102 x 17 mm).</para> + + <para>Data throughput ranges from ~150 kB/s to + ~500 kB/s. Data capacity ranges from 40 MB to + 15 GB. Hardware compression is available on many of the + newer QIC drives. QIC drives are less frequently installed; + they are being supplanted by DAT drives.</para> + + <para>Data is recorded onto the tape in tracks. The tracks run + along the long axis of the tape media from one end to the + other. The number of tracks, and therefore the width of a + track, varies with the tape's capacity. Most if not all newer + drives provide backward-compatibility at least for reading + (but often also for writing). QIC has a good reputation + regarding the safety of the data (the mechanics are simpler + and more robust than for helical scan drives).</para> + + <para>Tapes should be retired from use after 5,000 + backups.</para> + </sect2> + + <sect2 id="backups-tapebackups-dlt"> + <title>DLT</title> + <indexterm> + <primary>tape media</primary> + <secondary>DLT</secondary> + </indexterm> + + <para>DLT has the fastest data transfer rate of all the drive + types listed here. The 1/2" (12.5mm) tape is contained in a + single spool cartridge (4 x 4 x 1 inches; 100 x 100 x 25 mm). + The cartridge has a swinging gate along one entire side of the + cartridge. The drive mechanism opens this gate to extract the + tape leader. The tape leader has an oval hole in it which the + drive uses to <quote>hook</quote> the tape. The take-up spool + is located inside the tape drive. All the other tape + cartridges listed here (9 track tapes are the only exception) + have both the supply and take-up spools located inside the + tape cartridge itself.</para> + + <para>Data throughput is approximately 1.5 MB/s, three + times the throughput of 4mm, 8mm, or QIC tape drives. Data + capacities range from 10 GB to 20 GB for a single + drive. Drives are available in both multi-tape changers and + multi-tape, multi-drive tape libraries containing from 5 to + 900 tapes over 1 to 20 drives, providing from 50 GB to + 9 TB of storage.</para> + + <para>With compression, DLT Type IV format supports up to + 70 GB capacity.</para> + + <para>Data is recorded onto the tape in tracks parallel to the + direction of travel (just like QIC tapes). Two tracks are + written at once. Read/write head lifetimes are relatively + long; once the tape stops moving, there is no relative motion + between the heads and the tape.</para> + </sect2> + + <sect2> + <title id="backups-tapebackups-ait">AIT</title> + <indexterm> + <primary>tape media</primary> + <secondary>AIT</secondary> + </indexterm> + + <para>AIT is a new format from Sony, and can hold up to + 50 GB (with compression) per tape. The tapes contain + memory chips which retain an index of the tape's contents. + This index can be rapidly read by the tape drive to determine + the position of files on the tape, instead of the several + minutes that would be required for other tapes. Software such + as <application>SAMS:Alexandria</application> can operate + forty or more AIT tape libraries, communicating directly with + the tape's memory chip to display the contents on screen, + determine what files were backed up to which tape, locate the + correct tape, load it, and restore the data from the + tape.</para> + + <para>Libraries like this cost in the region of $20,000, pricing + them a little out of the hobbyist market.</para> + </sect2> + + <sect2> + <title>Using a New Tape for the First Time</title> + + <para>The first time that you try to read or write a new, + completely blank tape, the operation will fail. The console + messages should be similar to:</para> + + <screen>sa0(ncr1:4:0): NOT READY asc:4,1 +sa0(ncr1:4:0): Logical unit is in process of becoming ready</screen> + + <para>The tape does not contain an Identifier Block (block + number 0). All QIC tape drives since the adoption of QIC-525 + standard write an Identifier Block to the tape. There are two + solutions:</para> + + <itemizedlist> + <listitem> + <para><command>mt fsf 1</command> causes the tape drive to + write an Identifier Block to the tape.</para> + </listitem> + + <listitem> + <para>Use the front panel button to eject the tape.</para> + + <para>Re-insert the tape and <command>dump</command> data to + the tape.</para> + + <para><command>dump</command> will report + <errorname>DUMP: End of tape detected</errorname> and the + console will show: <errorname>HARDWARE FAILURE info:280 + asc:80,96</errorname>.</para> + + <para>rewind the tape using: + <command>mt rewind</command>.</para> + + <para>Subsequent tape operations are successful.</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="backups-floppybackups"> + <title>Backups to Floppies</title> + + <sect2 id="floppies-using"> + <title>Can I Use Floppies for Backing Up My Data?</title> + <indexterm><primary>backup floppies</primary></indexterm> + <indexterm><primary>floppy disks</primary></indexterm> + + <para>Floppy disks are not really a suitable media for + making backups as:</para> + + <itemizedlist> + <listitem> + <para>The media is unreliable, especially over long periods + of time.</para> + </listitem> + + <listitem> + <para>Backing up and restoring is very slow.</para> + </listitem> + + <listitem> + <para>They have a very limited capacity (the days of backing + up an entire hard disk onto a dozen or so floppies has + long since passed).</para> + </listitem> + </itemizedlist> + + <para>However, if you have no other method of backing up your + data then floppy disks are better than no backup at + all.</para> + + <para>If you do have to use floppy disks then ensure that you + use good quality ones. Floppies that have been lying around + the office for a couple of years are a bad choice. Ideally + use new ones from a reputable manufacturer.</para> + </sect2> + + <sect2 id="floppies-creating"> + <title>So How Do I Backup My Data to Floppies?</title> + + <para>The best way to backup to floppy disk is to use + &man.tar.1; with the <option>-M</option> (multi + volume) option, which allows backups to span multiple + floppies.</para> + + <para>To backup all the files in the current directory and + sub-directory use this (as <username>root</username>):</para> + + <screen>&prompt.root; <userinput>tar Mcvf /dev/fd0 *</userinput></screen> + + <para>When the first floppy is full &man.tar.1; will prompt you + to insert the next volume (because &man.tar.1; is media + independent it refers to volumes; in this context it means + floppy disk).</para> + + <screen>Prepare volume #2 for /dev/fd0 and hit return:</screen> + + <para>This is repeated (with the volume number incrementing) + until all the specified files have been archived.</para> + </sect2> + + <sect2 id="floppies-compress"> + <title>Can I Compress My Backups?</title> + <indexterm> + <primary><command>tar</command></primary> + </indexterm> + <indexterm> + <primary><command>gzip</command></primary> + </indexterm> + <indexterm><primary>compression</primary></indexterm> + + <para>Unfortunately, &man.tar.1; will not allow the + <option>-z</option> option to be used for multi-volume + archives. You could, of course, &man.gzip.1; all the files, + &man.tar.1; them to the floppies, then &man.gunzip.1; the + files again!</para> + </sect2> + + <sect2 id="floppies-restoring"> + <title>How Do I Restore My Backups?</title> + + <para>To restore the entire archive use:</para> + + <screen>&prompt.root; <userinput>tar Mxvf /dev/fd0</userinput></screen> + + <para>There are two ways that you can use to restore only + specific files. First, you can start with the first floppy + and use:</para> + + <screen>&prompt.root; <userinput>tar Mxvf /dev/fd0 <replaceable>filename</replaceable></userinput></screen> + + <para>The utility &man.tar.1; will prompt you to insert + subsequent floppies until it finds the required file.</para> + + <para>Alternatively, if you know which floppy the file is on + then you can simply insert that floppy and use the same + command as above. Note that if the first file on the floppy + is a continuation from the previous one then &man.tar.1; will + warn you that it cannot restore it, even if you have not asked + it to!</para> + </sect2> + </sect1> + + <sect1 id="backup-strategies"> + <sect1info> + <authorgroup> + <author> + <firstname>Lowell</firstname> + <surname>Gilbert</surname> + <contrib>Original work by </contrib> + </author> + </authorgroup> + <!-- 3 Dec 2005 --> + </sect1info> + + <title>Backup Strategies</title> + + <para>The first requirement in devising a backup plan is to make + sure that all of the following problems are covered:</para> + + <itemizedlist> + <listitem> + <para>Disk failure</para> + </listitem> + + <listitem> + <para>Accidental file deletion</para> + </listitem> + + <listitem> + <para>Random file corruption</para> + </listitem> + + <listitem> + <para>Complete machine destruction (e.g., fire), including + destruction of any on-site backups.</para> + </listitem> + </itemizedlist> + + <para>It is perfectly possible that some systems will be best + served by having each of these problems covered by a completely + different technique. Except for strictly personal systems with + very low-value data, it is unlikely that one technique would + cover all of them.</para> + + <para>Some of the techniques in the toolbox are:</para> + + <itemizedlist> + <listitem> + <para>Archives of the whole system, backed up onto permanent + media offsite. This actually provides protection against + all of the possible problems listed above, but is slow and + inconvenient to restore from. You can keep copies of the + backups onsite and/or online, but there will still be + inconveniences in restoring files, especially for + non-privileged users.</para> + </listitem> + + <listitem> + <para>Filesystem snapshots. This is really only helpful in + the accidental file deletion scenario, but it can be + <emphasis>very</emphasis> helpful in that case, and is quick + and easy to deal with.</para> + </listitem> + + <listitem> + <para>Copies of whole filesystems and/or disks (e.g., periodic + &man.rsync.1; of the whole machine). This is generally most + useful in networks with unique requirements. For general + protection against disk failure, it is usually inferior to + <acronym>RAID</acronym>. For restoring accidentally deleted + files, it can be comparable to <acronym>UFS</acronym> + snapshots, but that depends on your preferences.</para> + </listitem> + + <listitem> + <para><acronym>RAID</acronym>. Minimizes or avoids downtime + when a disk fails. At the expense of having to deal with + disk failures more often (because you have more disks), + albeit at a much lower urgency.</para> + </listitem> + + <listitem> + <para>Checking fingerprints of files. The &man.mtree.8; + utility is very useful for this. Although it is not a + backup technique, it helps guarantee that you will notice + when you need to resort to your backups. This is + particularly important for offline backups, and should be + checked periodically.</para> + </listitem> + </itemizedlist> + + <para>It is quite easy to come up with even more techniques, many + of them variations on the ones listed above. Specialized + requirements will usually lead to specialized techniques (for + example, backing up a live database usually requires a method + particular to the database software as an intermediate step). + The important thing is to know what dangers you want to protect + against, and how you will handle each.</para> + </sect1> + + <sect1 id="backup-basics"> + <title>Backup Basics</title> + + <para>The three major backup programs are &man.dump.8;, + &man.tar.1;, and &man.cpio.1;.</para> + + <sect2> + <title>Dump and Restore</title> + + <indexterm> + <primary>backup software</primary> + <secondary>dump / restore</secondary> + </indexterm> + <indexterm> + <primary><command>dump</command></primary> + </indexterm> + <indexterm> + <primary><command>restore</command></primary> + </indexterm> + + <para>The traditional &unix; backup programs are + <command>dump</command> and <command>restore</command>. They + operate on the drive as a collection of disk blocks, below the + abstractions of files, links and directories that are created + by the file systems. Unlike other backup software, + <command>dump</command> backs up an entire file system on a + device. It is unable to backup only part of a file system or + a directory tree that spans more than one file system. The + <command>dump</command> command does not write files and + directories to tape, but rather writes the raw data blocks + that comprise files and directories. When being used to + extract data, <command>restore</command> stores temporary + files in <filename>/tmp/</filename> by default — if you + are operating from a recovery disk with a small + <filename>/tmp</filename> directory, you may need to set the + <envar>TMPDIR</envar> environment variable to a directory with + more free space for the restore to be successful.</para> + + <note> + <para>If you use <command>dump</command> on your root + directory, you would not back up <filename>/home</filename>, + <filename>/usr</filename> or many other directories since + these are typically mount points for other file systems or + symbolic links into those file systems.</para> + </note> + + <para><command>dump</command> has quirks that remain from its + early days in Version 6 of AT&T UNIX (circa 1975). The + default parameters are suitable for 9-track tapes (6250 bpi), + not the high-density media available today (up to 62,182 + ftpi). These defaults must be overridden on the command line + to utilize the capacity of current tape drives.</para> + + <indexterm> + <primary><filename>.rhosts</filename></primary> + </indexterm> + <para>It is also possible to backup data across the network to a + tape drive attached to another computer with + <command>rdump</command> and <command>rrestore</command>. + Both programs rely upon &man.rcmd.3; and &man.ruserok.3; to + access the remote tape drive. Therefore, the user performing + the backup must be listed in the <filename>.rhosts</filename> + file on the remote computer. The arguments to + <command>rdump</command> and <command>rrestore</command> must + be suitable to use on the remote computer. When + <command>rdump</command>ing from a FreeBSD computer to an + Exabyte tape drive connected to a Sun called + <hostid>komodo</hostid>, use:</para> + + <screen>&prompt.root; <userinput>/sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&1</userinput></screen> + + <para>Beware: there are security implications to allowing + <filename>.rhosts</filename> authentication. Evaluate your + situation carefully.</para> + + <para>It is also possible to use <command>dump</command> and + <command>restore</command> in a more secure fashion over + <command>ssh</command>.</para> + + <example> + <title>Using <command>dump</command> over + <application>ssh</application></title> + + <screen>&prompt.root; <userinput>/sbin/dump -0uan -f - /usr | gzip -2 | ssh -c blowfish \ + targetuser@targetmachine.example.com dd of=/mybigfiles/dump-usr-l0.gz</userinput></screen> + </example> + + <para>Or using <command>dump</command>'s built-in method, + setting the environment variable <envar>RSH</envar>:</para> + + <example> + <title>Using <command>dump</command> over + <application>ssh</application> with <envar>RSH</envar> + set</title> + + <screen>&prompt.root; <userinput>RSH=/usr/bin/ssh /sbin/dump -0uan -f targetuser@targetmachine.example.com:/dev/sa0 /usr</userinput></screen> + </example> + </sect2> + + <sect2> + <title><command>tar</command></title> + <indexterm> + <primary>backup software</primary> + <secondary><command>tar</command></secondary> + </indexterm> + + <para>&man.tar.1; also dates back to Version 6 of AT&T UNIX + (circa 1975). <command>tar</command> operates in cooperation + with the file system; it writes files and directories to tape. + <command>tar</command> does not support the full range of + options that are available from &man.cpio.1;, but it does not + require the unusual command pipeline that + <command>cpio</command> uses.</para> + + <indexterm><primary><command>tar</command></primary></indexterm> + + <para>To <command>tar</command> to an Exabyte tape drive + connected to a Sun called <hostid>komodo</hostid>, use:</para> + + <screen>&prompt.root; <userinput>tar cf - . | rsh komodo dd of=<replaceable>tape-device</replaceable> obs=20b</userinput></screen> + + <para>If you are worried about the security of backing up over a + network you should use the <command>ssh</command> command + instead of <command>rsh</command>.</para> + </sect2> + + <sect2> + <title><command>cpio</command></title> + <indexterm> + <primary>backup software</primary> + <secondary><command>cpio</command></secondary> + </indexterm> + + <para>&man.cpio.1; is the original &unix; file interchange tape + program for magnetic media. <command>cpio</command> has + options (among many others) to perform byte-swapping, write a + number of different archive formats, and pipe the data to + other programs. This last feature makes + <command>cpio</command> an excellent choice for installation + media. <command>cpio</command> does not know how to walk the + directory tree and a list of files must be provided through + <filename>stdin</filename>.</para> + + <indexterm> + <primary><command>cpio</command></primary> + </indexterm> + + <para><command>cpio</command> does not support backups across + the network. You can use a pipeline and + <command>rsh</command> to send the data to a remote tape + drive.</para> + + <screen>&prompt.root; <userinput>for f in <replaceable>directory_list; do</replaceable></userinput> +<userinput>find $f >> backup.list</userinput> +<userinput>done</userinput> +&prompt.root; <userinput>cpio -v -o --format=newc < backup.list | ssh <replaceable>user</replaceable>@<replaceable>host</replaceable> "cat > <replaceable>backup_device</replaceable>"</userinput></screen> + + <para>Where <replaceable>directory_list</replaceable> is the + list of directories you want to back up, + <replaceable>user</replaceable>@<replaceable>host</replaceable> + is the user/hostname combination that will be performing the + backups, and <replaceable>backup_device</replaceable> is where + the backups should be written to (e.g., + <filename>/dev/nsa0</filename>).</para> + </sect2> + + <sect2> + <title><command>pax</command></title> + + <indexterm> + <primary>backup software</primary> + <secondary><command>pax</command></secondary> + </indexterm> + <indexterm><primary><command>pax</command></primary></indexterm> + <indexterm><primary>POSIX</primary></indexterm> + <indexterm><primary>IEEE</primary></indexterm> + + <para>&man.pax.1; is IEEE/&posix;'s answer to + <command>tar</command> and <command>cpio</command>. Over the + years the various versions of <command>tar</command> and + <command>cpio</command> have gotten slightly incompatible. So + rather than fight it out to fully standardize them, &posix; + created a new archive utility. <command>pax</command> + attempts to read and write many of the various + <command>cpio</command> and <command>tar</command> formats, + plus new formats of its own. Its command set more resembles + <command>cpio</command> than <command>tar</command>.</para> + </sect2> + + <sect2 id="backups-programs-amanda"> + <title><application>Amanda</application></title> + <indexterm> + <primary>backup software</primary> + <secondary><application>Amanda</application></secondary> + </indexterm> + <indexterm> + <primary><application>Amanda</application></primary> + </indexterm> + + <!-- Remove link until <port> tag is available --> + <para><application>Amanda</application> (Advanced Maryland + Network Disk Archiver) is a client/server backup system, + rather than a single program. An + <application>Amanda</application> server will backup to a + single tape drive any number of computers that have + <application>Amanda</application> clients and a network + connection to the <application>Amanda</application> server. A + common problem at sites with a number of large disks is that + the length of time required to backup to data directly to tape + exceeds the amount of time available for the task. + <application>Amanda</application> solves this problem. + <application>Amanda</application> can use a + <quote>holding disk</quote> to backup several file systems at + the same time. <application>Amanda</application> creates + <quote>archive sets</quote>: a group of tapes used over a + period of time to create full backups of all the file systems + listed in <application>Amanda</application>'s configuration + file. The <quote>archive set</quote> also contains nightly + incremental (or differential) backups of all the file systems. + Restoring a damaged file system requires the most recent full + backup and the incremental backups.</para> + + <para>The configuration file provides fine control of backups + and the network traffic that <application>Amanda</application> + generates. <application>Amanda</application> will use any of + the above backup programs to write the data to tape. + <application>Amanda</application> is available as either a + port or a package, it is not installed by default.</para> + </sect2> + + <sect2> + <title>Do Nothing</title> + + <para><quote>Do nothing</quote> is not a computer program, but + it is the most widely used backup strategy. There are no + initial costs. There is no backup schedule to follow. Just + say no. If something happens to your data, grin and bear + it!</para> + + <para>If your time and your data is worth little to nothing, + then <quote>Do nothing</quote> is the most suitable backup + program for your computer. But beware, &unix; is a useful + tool, you may find that within six months you have a + collection of files that are valuable to you.</para> + + <para><quote>Do nothing</quote> is the correct backup method for + <filename>/usr/obj</filename> and other directory trees that + can be exactly recreated by your computer. An example is the + files that comprise the HTML or &postscript; version of this + Handbook. These document formats have been created from SGML + input files. Creating backups of the HTML or &postscript; + files is not necessary. The SGML files are backed up + regularly.</para> + </sect2> + + <sect2> + <title>Which Backup Program Is Best?</title> + <indexterm> + <primary>LISA</primary> + </indexterm> + + <para>&man.dump.8; <emphasis>Period.</emphasis> Elizabeth D. + Zwicky torture tested all the backup programs discussed here. + The clear choice for preserving all your data and all the + peculiarities of &unix; file systems is + <command>dump</command>. Elizabeth created file systems + containing a large variety of unusual conditions (and some not + so unusual ones) and tested each program by doing a backup and + restore of those file systems. The peculiarities included: + files with holes, files with holes and a block of nulls, files + with funny characters in their names, unreadable and + unwritable files, devices, files that change size during the + backup, files that are created/deleted during the backup and + more. She presented the results at LISA V in Oct. 1991. See + <ulink + url="http://www.coredumps.de/doc/dump/zwicky/testdump.doc.html">torture-testing + Backup and Archive Programs</ulink>.</para> + </sect2> + + <sect2> + <title>Emergency Restore Procedure</title> + + <sect3> + <title>Before the Disaster</title> + + <para>There are only four steps that you need to perform in + preparation for any disaster that may occur.</para> + <indexterm> + <primary><command>bsdlabel</command></primary> + </indexterm> + + <para>First, print the bsdlabel from each of your disks (e.g., + <command>bsdlabel da0 | lpr</command>), your file system + table (<filename>/etc/fstab</filename>) and all boot + messages, two copies of each.</para> + + <indexterm><primary>livefs CD</primary></indexterm> + <para>Second, burn a <quote>livefs</quote> CDROM. This CDROM + contains support for booting into a &os; + <quote>livefs</quote> rescue mode allowing the user to + perform many tasks like running &man.dump.8;, + &man.restore.8;, &man.fdisk.8;, &man.bsdlabel.8;, + &man.newfs.8;, &man.mount.8;, and more. Livefs CD image for + &os;/&arch.i386; &rel2.current;-RELEASE is available + from <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-livefs.iso"></ulink>.</para> + + <note> + <para>Livefs CD images are not available for + &os; &rel.current;-RELEASE and later. In addition to + the CDROM installation images, flash drive installation + images may be used to recover a system. The + <quote>memstick</quote> image for + &os;/&arch.i386; &rel.current;-RELEASE is available + from <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/&rel.current;/&os;-&rel.current;-RELEASE-&arch.i386;-memstick.img"></ulink>.</para> + </note> + + <para>Third, create backup tapes regularly. Any changes that + you make after your last backup may be irretrievably lost. + Write-protect the backup tapes.</para> + + <para>Fourth, test the <quote>livefs</quote> CDROM you made in + step two and backup tapes. Make notes of the procedure. + Store these notes with the CDROM, the printouts and the + backup tapes. You will be so distraught when restoring that + the notes may prevent you from destroying your backup tapes + (How? In place of <command>tar xvf /dev/sa0</command>, you + might accidentally type <command>tar cvf /dev/sa0</command> + and over-write your backup tape).</para> + + <para>For an added measure of security, make + <quote>livefs</quote> CDROM and two backup tapes each time. + Store one of each at a remote location. A remote location + is NOT the basement of the same office building. A number + of firms in the World Trade Center learned this lesson the + hard way. A remote location should be physically separated + from your computers and disk drives by a significant + distance.</para> + </sect3> + + <sect3> + <title>After the Disaster</title> + + <para>The key question is: did your hardware survive? You + have been doing regular backups so there is no need to worry + about the software.</para> + + <para>If the hardware has been damaged, the parts should be + replaced before attempting to use the computer.</para> + + <para>If your hardware is okay, insert the + <quote>livefs</quote> CDROM in the CDROM drive and boot the + computer. The original install menu will be displayed on + the screen. Select the correct country, then choose + <guimenuitem>Fixit -- Repair mode with CDROM/DVD/floppy or + start a shell.</guimenuitem> option and select the + <guimenuitem>CDROM/DVD -- Use the live filesystem + CDROM/DVD</guimenuitem> item. The tool + <command>restore</command> and the other programs that you + need are located in + <filename class="directory">/mnt2/rescue</filename>.</para> + + <para>Recover each file system separately.</para> + + <indexterm> + <primary><command>mount</command></primary> + </indexterm> + <indexterm><primary>root partition</primary></indexterm> + <indexterm> + <primary><command>bsdlabel</command></primary> + </indexterm> + <indexterm> + <primary><command>newfs</command></primary> + </indexterm> + + <para>Try to <command>mount</command> (e.g., + <command>mount /dev/da0a /mnt</command>) the root partition + of your first disk. If the bsdlabel was damaged, use + <command>bsdlabel</command> to re-partition and label the + disk to match the label that you printed and saved. Use + <command>newfs</command> to re-create the file systems. + Re-mount the root partition of the disk read-write + (<command>mount -u -o rw /mnt</command>). Use your backup + program and backup tapes to recover the data for this file + system (e.g., <command>restore vrf /dev/sa0</command>). + Unmount the file system (e.g., + <command>umount /mnt</command>). Repeat for each file + system that was damaged.</para> + + <para>Once your system is running, backup your data onto new + tapes. Whatever caused the crash or data loss may strike + again. Another hour spent now may save you from further + distress later.</para> + </sect3> + +<![ %not.published; [ + + <sect3> + <title>* I Did Not Prepare for the Disaster, What Now?</title> + + <para></para> + </sect3> +]]> + + </sect2> + </sect1> + + <sect1 id="disks-virtual"> + <sect1info> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + <contrib>Reorganized and enhanced by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Network, Memory, and File-Backed File Systems</title> + <indexterm><primary>virtual disks</primary></indexterm> + <indexterm> + <primary>disks</primary> + <secondary>virtual</secondary> + </indexterm> + + <para>Aside from the disks you physically insert into your + computer: floppies, CDs, hard drives, and so forth; other forms + of disks are understood by FreeBSD - the <firstterm>virtual + disks</firstterm>.</para> + + <indexterm><primary>NFS</primary></indexterm> + <indexterm><primary>Coda</primary></indexterm> + <indexterm> + <primary>disks</primary> + <secondary>memory</secondary> + </indexterm> + <para>These include network file systems such as the + <link linkend="network-nfs">Network File System</link> and Coda, + memory-based file systems and file-backed file systems.</para> + + <para>According to the FreeBSD version you run, you will have to + use different tools for creation and use of file-backed and + memory-based file systems.</para> + + <note> + <para>Use &man.devfs.5; to allocate device nodes transparently + for the user.</para> + </note> + + <sect2 id="disks-mdconfig"> + <title>File-Backed File System</title> + <indexterm> + <primary>disks</primary> + <secondary>file-backed</secondary> + </indexterm> + + <para>The utility &man.mdconfig.8; is used to configure and + enable memory disks, &man.md.4;, under FreeBSD. To use + &man.mdconfig.8;, you have to load &man.md.4; module or to add + the support in your kernel configuration file:</para> + + <programlisting>device md</programlisting> + + <para>The &man.mdconfig.8; command supports three kinds of + memory backed virtual disks: memory disks allocated with + &man.malloc.9;, memory disks using a file or swap space as + backing. One possible use is the mounting of floppy + or CD images kept in files.</para> + + <para>To mount an existing file system image:</para> + + <example> + <title>Using <command>mdconfig</command> to Mount an Existing + File System Image</title> + + <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f <replaceable>diskimage</replaceable> -u <replaceable>0</replaceable></userinput> +&prompt.root; <userinput>mount /dev/md<replaceable>0</replaceable> <replaceable>/mnt</replaceable></userinput></screen> + </example> + + <para>To create a new file system image with + &man.mdconfig.8;:</para> + + <example> + <title>Creating a New File-Backed Disk with + <command>mdconfig</command></title> + + <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>newimage</replaceable> bs=1k count=<replaceable>5</replaceable>k</userinput> +5120+0 records in +5120+0 records out +&prompt.root; <userinput>mdconfig -a -t vnode -f <replaceable>newimage</replaceable> -u <replaceable>0</replaceable></userinput> +&prompt.root; <userinput>bsdlabel -w md<replaceable>0</replaceable> auto</userinput> +&prompt.root; <userinput>newfs md<replaceable>0</replaceable>a</userinput> +/dev/md0a: 5.0MB (10224 sectors) block size 16384, fragment size 2048 + using 4 cylinder groups of 1.25MB, 80 blks, 192 inodes. +super-block backups (for fsck -b #) at: + 160, 2720, 5280, 7840 +&prompt.root; <userinput>mount /dev/md<replaceable>0</replaceable>a <replaceable>/mnt</replaceable></userinput> +&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput> +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/md0a 4710 4 4330 0% /mnt</screen> + </example> + + <para>If you do not specify the unit number with the + <option>-u</option> option, &man.mdconfig.8; will use the + &man.md.4; automatic allocation to select an unused device. + The name of the allocated unit will be output on stdout like + <devicename>md4</devicename>. For more details about + &man.mdconfig.8;, please refer to the manual page.</para> + + <para>The utility &man.mdconfig.8; is very useful, however it + asks many command lines to create a file-backed file system. + FreeBSD also comes with a tool called &man.mdmfs.8;, this + program configures a &man.md.4; disk using &man.mdconfig.8;, + puts a UFS file system on it using &man.newfs.8;, and mounts + it using &man.mount.8;. For example, if you want to create + and mount the same file system image as above, simply type the + following:</para> + + <example> + <title>Configure and Mount a File-Backed Disk with + <command>mdmfs</command></title> + + <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>newimage</replaceable> bs=1k count=<replaceable>5</replaceable>k</userinput> +5120+0 records in +5120+0 records out +&prompt.root; <userinput>mdmfs -F <replaceable>newimage</replaceable> -s <replaceable>5</replaceable>m md<replaceable>0</replaceable> <replaceable>/mnt</replaceable></userinput> +&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput> +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/md0 4718 4 4338 0% /mnt</screen> + </example> + + <para>If you use the option <option>md</option> without unit + number, &man.mdmfs.8; will use &man.md.4; auto-unit feature to + automatically select an unused device. For more details + about &man.mdmfs.8;, please refer to the manual page.</para> + </sect2> + + <sect2 id="disks-md-freebsd5"> + <title>Memory-Based File System</title> + + <indexterm> + <primary>disks</primary> + <secondary>memory file system</secondary> + </indexterm> + + <para>For a memory-based file system the + <quote>swap backing</quote> should normally be used. Using + swap backing does not mean that the memory disk will be + swapped out to disk by default, but merely that the memory + disk will be allocated from a memory pool which can be swapped + out to disk if needed. It is also possible to create + memory-based disk which are &man.malloc.9; backed, but using + malloc backed memory disks, especially large ones, can result + in a system panic if the kernel runs out of memory.</para> + + <example> + <title>Creating a New Memory-Based Disk with + <command>mdconfig</command></title> + + <screen>&prompt.root; <userinput>mdconfig -a -t swap -s <replaceable>5</replaceable>m -u <replaceable>1</replaceable></userinput> +&prompt.root; <userinput>newfs -U md<replaceable>1</replaceable></userinput> +/dev/md1: 5.0MB (10240 sectors) block size 16384, fragment size 2048 + using 4 cylinder groups of 1.27MB, 81 blks, 192 inodes. + with soft updates +super-block backups (for fsck -b #) at: + 160, 2752, 5344, 7936 +&prompt.root; <userinput>mount /dev/md<replaceable>1</replaceable> <replaceable>/mnt</replaceable></userinput> +&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput> +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/md1 4718 4 4338 0% /mnt</screen> + </example> + + <example> + <title>Creating a New Memory-Based Disk with + <command>mdmfs</command></title> + + <screen>&prompt.root; <userinput>mdmfs -s <replaceable>5</replaceable>m md<replaceable>2</replaceable> <replaceable>/mnt</replaceable></userinput> +&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput> +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/md2 4846 2 4458 0% /mnt</screen> + </example> + </sect2> + + <sect2> + <title>Detaching a Memory Disk from the System</title> + + <indexterm> + <primary>disks</primary> + <secondary>detaching a memory disk</secondary> + </indexterm> + + <para>When a memory-based or file-based file system is not used, + you should release all resources to the system. The first + thing to do is to unmount the file system, then use + &man.mdconfig.8; to detach the disk from the system and + release the resources.</para> + + <para>For example to detach and free all resources used by + <filename>/dev/md4</filename>:</para> + + <screen>&prompt.root; <userinput>mdconfig -d -u <replaceable>4</replaceable></userinput></screen> + + <para>It is possible to list information about configured + &man.md.4; devices in using the command + <command>mdconfig -l</command>.</para> + </sect2> + </sect1> + + <sect1 id="snapshots"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <!-- 15 JUL 2002 --> + </sect1info> + + <title>File System Snapshots</title> + + <indexterm> + <primary>file systems</primary> + <secondary>snapshots</secondary> + </indexterm> + + <para>FreeBSD offers a feature in conjunction with + <link linkend="soft-updates">Soft Updates</link>: File system + snapshots.</para> + + <para>Snapshots allow a user to create images of specified file + systems, and treat them as a file. Snapshot files must be + created in the file system that the action is performed on, and + a user may create no more than 20 snapshots per file system. + Active snapshots are recorded in the superblock so they are + persistent across unmount and remount operations along with + system reboots. When a snapshot is no longer required, it can + be removed with the standard &man.rm.1; command. Snapshots may + be removed in any order, however all the used space may not be + acquired because another snapshot will possibly claim some of + the released blocks.</para> + + <para>The un-alterable <option>snapshot</option> file flag is set + by &man.mksnap.ffs.8; after initial creation of a snapshot file. + The &man.unlink.1; command makes an exception for snapshot files + since it allows them to be removed.</para> + + <para>Snapshots are created with the &man.mount.8; command. To + place a snapshot of <filename>/var</filename> in the file + <filename>/var/snapshot/snap</filename> use the following + command:</para> + + <screen>&prompt.root; <userinput>mount -u -o snapshot /var/snapshot/snap /var</userinput></screen> + + <para>Alternatively, you can use &man.mksnap.ffs.8; to create + a snapshot:</para> + + <screen>&prompt.root; <userinput>mksnap_ffs /var /var/snapshot/snap</userinput></screen> + + <para>One can find snapshot files on a file system (e.g., + <filename>/var</filename>) by using the &man.find.1; + command:</para> + + <screen>&prompt.root; <userinput>find /var -flags snapshot</userinput></screen> + + <para>Once a snapshot has been created, it has several + uses:</para> + + <itemizedlist> + <listitem> + <para>Some administrators will use a snapshot file for backup + purposes, because the snapshot can be transferred to CDs or + tape.</para> + </listitem> + + <listitem> + <para>The file system integrity checker, &man.fsck.8;, may be + run on the snapshot. Assuming that the file system was + clean when it was mounted, you should always get a clean + (and unchanging) result. This is essentially what the + background &man.fsck.8; process does.</para> + </listitem> + + <listitem> + <para>Run the &man.dump.8; utility on the snapshot. A dump + will be returned that is consistent with the file system and + the timestamp of the snapshot. &man.dump.8; can also take a + snapshot, create a dump image and then remove the snapshot + in one command using the <option>-L</option> flag.</para> + </listitem> + + <listitem> + <para>&man.mount.8; the snapshot as a frozen image of the file + system. To &man.mount.8; the snapshot + <filename>/var/snapshot/snap</filename> run:</para> + + <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /var/snapshot/snap -u 4</userinput> +&prompt.root; <userinput>mount -r /dev/md4 /mnt</userinput></screen> + </listitem> + </itemizedlist> + + <para>You can now walk the hierarchy of your frozen + <filename>/var</filename> file system mounted at + <filename>/mnt</filename>. Everything will initially be in the + same state it was during the snapshot creation time. The only + exception is that any earlier snapshots will appear as zero + length files. When the use of a snapshot has delimited, it can + be unmounted with:</para> + + <screen>&prompt.root; <userinput>umount /mnt</userinput> +&prompt.root; <userinput>mdconfig -d -u 4</userinput></screen> + + <para>For more information about <option>softupdates</option> and + file system snapshots, including technical papers, you can visit + Marshall Kirk McKusick's website at + <ulink url="http://www.mckusick.com/"></ulink>.</para> + </sect1> + + <sect1 id="quotas"> + <title>File System Quotas</title> + <indexterm> + <primary>accounting</primary> + <secondary>disk space</secondary> + </indexterm> + <indexterm><primary>disk quotas</primary></indexterm> + + <para>Quotas are an optional feature of the operating system that + allow you to limit the amount of disk space and/or the number of + files a user or members of a group may allocate on a per-file + system basis. This is used most often on timesharing systems + where it is desirable to limit the amount of resources any one + user or group of users may allocate. This will prevent one user + or group of users from consuming all of the available disk + space.</para> + + <sect2> + <title>Configuring Your System to Enable Disk Quotas</title> + + <para>Before attempting to use disk quotas, it is necessary to + make sure that quotas are configured in your kernel. This is + done by adding the following line to your kernel configuration + file:</para> + + <programlisting>options QUOTA</programlisting> + + <para>The stock <filename>GENERIC</filename> kernel does not + have this enabled by default, so you will have to configure, + build and install a custom kernel in order to use disk quotas. + Please refer to <xref linkend="kernelconfig"> for more + information on kernel configuration.</para> + + <para>Next you will need to enable disk quotas in + <filename>/etc/rc.conf</filename>. On &os; 7.X and + earlier, this is done by adding the line:</para> + + <programlisting>enable_quotas="YES"</programlisting> + + <para>On &os; 8.0-RELEASE and later, add the following + line instead:</para> + + <programlisting>quota_enable="YES"</programlisting> + <indexterm> + <primary>disk quotas</primary> + <secondary>checking</secondary> + </indexterm> + <para>For finer control over your quota startup, there is an + additional configuration variable available. Normally on + bootup, the quota integrity of each file system is checked by + the &man.quotacheck.8; program. The &man.quotacheck.8; + facility insures that the data in the quota database properly + reflects the data on the file system. This is a very time + consuming process that will significantly affect the time your + system takes to boot. If you would like to skip this step, a + variable in <filename>/etc/rc.conf</filename> is made + available for the purpose:</para> + + <programlisting>check_quotas="NO"</programlisting> + + <para>Finally you will need to edit + <filename>/etc/fstab</filename> to enable disk quotas on a + per-file system basis. This is where you can either enable + user or group quotas or both for all of your file + systems.</para> + + <para>To enable per-user quotas on a file system, add the + <option>userquota</option> option to the options field in the + <filename>/etc/fstab</filename> entry for the file system you + want to enable quotas on. For example:</para> + + <programlisting>/dev/da1s2g /home ufs rw,userquota 1 2</programlisting> + + <para>Similarly, to enable group quotas, use the + <option>groupquota</option> option instead of + <option>userquota</option>. To enable both user and group + quotas, change the entry as follows:</para> + + <programlisting>/dev/da1s2g /home ufs rw,userquota,groupquota 1 2</programlisting> + + <para>By default, the quota files are stored in the root + directory of the file system with the names + <filename>quota.user</filename> and + <filename>quota.group</filename> for user and group quotas + respectively. See &man.fstab.5; for more information. Even + though the &man.fstab.5; manual page says that you can specify + an alternate location for the quota files, this is not + recommended because the various quota utilities do not seem to + handle this properly.</para> + + <para>At this point you should reboot your system with your new + kernel. <filename>/etc/rc</filename> will automatically run + the appropriate commands to create the initial quota files for + all of the quotas you enabled in + <filename>/etc/fstab</filename>, so there is no need to + manually create any zero length quota files.</para> + + <para>In the normal course of operations you should not be + required to run the &man.quotacheck.8;, &man.quotaon.8;, or + &man.quotaoff.8; commands manually. However, you may want to + read their manual pages just to be familiar with their + operation.</para> + </sect2> + + <sect2> + <title>Setting Quota Limits</title> + <indexterm> + <primary>disk quotas</primary> + <secondary>limits</secondary> + </indexterm> + + <para>Once you have configured your system to enable quotas, + verify that they really are enabled. An easy way to do this + is to run:</para> + + <screen>&prompt.root; <userinput>quota -v</userinput></screen> + + <para>You should see a one line summary of disk usage and + current quota limits for each file system that quotas are + enabled on.</para> + + <para>You are now ready to start assigning quota limits with the + &man.edquota.8; command.</para> + + <para>You have several options on how to enforce limits on the + amount of disk space a user or group may allocate, and how + many files they may create. You may limit allocations based + on disk space (block quotas) or number of files (inode quotas) + or a combination of both. Each of these limits are further + broken down into two categories: hard and soft limits.</para> + + <indexterm><primary>hard limit</primary></indexterm> + <para>A hard limit may not be exceeded. Once a user reaches his + hard limit he may not make any further allocations on the file + system in question. For example, if the user has a hard limit + of 500 kbytes on a file system and is currently using 490 + kbytes, the user can only allocate an additional 10 kbytes. + Attempting to allocate an additional 11 kbytes will + fail.</para> + + <indexterm><primary>soft limit</primary></indexterm> + <para>Soft limits, on the other hand, can be exceeded for a + limited amount of time. This period of time is known as the + grace period, which is one week by default. If a user stays + over his or her soft limit longer than the grace period, the + soft limit will turn into a hard limit and no further + allocations will be allowed. When the user drops back below + the soft limit, the grace period will be reset.</para> + + <para>The following is an example of what you might see when you + run the &man.edquota.8; command. When the &man.edquota.8; + command is invoked, you are placed into the editor specified + by the <envar>EDITOR</envar> environment variable, or in the + <application>vi</application> editor if the + <envar>EDITOR</envar> variable is not set, to allow you to + edit the quota limits.</para> + + <screen>&prompt.root; <userinput>edquota -u test</userinput></screen> + + <programlisting>Quotas for user test: +/usr: kbytes in use: 65, limits (soft = 50, hard = 75) + inodes in use: 7, limits (soft = 50, hard = 60) +/usr/var: kbytes in use: 0, limits (soft = 50, hard = 75) + inodes in use: 0, limits (soft = 50, hard = 60)</programlisting> + + <para>You will normally see two lines for each file system that + has quotas enabled. One line for the block limits, and one + line for inode limits. Simply change the value you want + updated to modify the quota limit. For example, to raise this + user's block limit from a soft limit of 50 and a hard limit of + 75 to a soft limit of 500 and a hard limit of 600, + change:</para> + + <programlisting>/usr: kbytes in use: 65, limits (soft = 50, hard = 75)</programlisting> + + <para>to:</para> + + <programlisting>/usr: kbytes in use: 65, limits (soft = 500, hard = 600)</programlisting> + + <para>The new quota limits will be in place when you exit the + editor.</para> + + <para>Sometimes it is desirable to set quota limits on a range + of UIDs. This can be done by use of the <option>-p</option> + option on the &man.edquota.8; command. First, assign the + desired quota limit to a user, and then run + <command>edquota -p protouser startuid-enduid</command>. For + example, if user <username>test</username> has the desired + quota limits, the following command can be used to duplicate + those quota limits for UIDs 10,000 through 19,999:</para> + + <screen>&prompt.root; <userinput>edquota -p test 10000-19999</userinput></screen> + + <para>For more information see &man.edquota.8; manual + page.</para> + </sect2> + + <sect2> + <title>Checking Quota Limits and Disk Usage</title> + <indexterm> + <primary>disk quotas</primary> + <secondary>checking</secondary> + </indexterm> + + <para>You can use either the &man.quota.1; or the + &man.repquota.8; commands to check quota limits and disk + usage. The &man.quota.1; command can be used to check + individual user or group quotas and disk usage. A user may + only examine his own quota, and the quota of a group he is a + member of. Only the super-user may view all user and group + quotas. The &man.repquota.8; command can be used to get a + summary of all quotas and disk usage for file systems with + quotas enabled.</para> + + <para>The following is some sample output from the + <command>quota -v</command> command for a user that has quota + limits on two file systems.</para> + + <programlisting>Disk quotas for user test (uid 1002): + Filesystem usage quota limit grace files quota limit grace + /usr 65* 50 75 5days 7 50 60 + /usr/var 0 50 75 0 50 60</programlisting> + + <indexterm><primary>grace period</primary></indexterm> + <para>On the <filename>/usr</filename> file system in the above + example, this user is currently 15 kbytes over the soft limit + of 50 kbytes and has 5 days of the grace period left. Note + the asterisk <literal>*</literal> which indicates that the + user is currently over his quota limit.</para> + + <para>Normally file systems that the user is not using any disk + space on will not show up in the output from the + &man.quota.1; command, even if he has a quota limit + assigned for that file system. The <option>-v</option> option + will display those file systems, such as the + <filename>/usr/var</filename> file system in the above + example.</para> + </sect2> + + <sect2> + <title>Quotas over NFS</title> + + <indexterm><primary>NFS</primary></indexterm> + + <para>Quotas are enforced by the quota subsystem on the NFS + server. The &man.rpc.rquotad.8; daemon makes quota + information available to the &man.quota.1; command on NFS + clients, allowing users on those machines to see their quota + statistics.</para> + + <para>Enable <command>rpc.rquotad</command> in + <filename>/etc/inetd.conf</filename> like so:</para> + + <programlisting>rquotad/1 dgram rpc/udp wait root /usr/libexec/rpc.rquotad rpc.rquotad</programlisting> + + <para>Now restart <command>inetd</command>:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/inetd restart</userinput></screen> + </sect2> + </sect1> + + <sect1 id="disks-encrypting"> + <sect1info> + <authorgroup> + <author> + <firstname>Lucky</firstname> + <surname>Green</surname> + <contrib>Contributed by </contrib> + <affiliation> + <address><email>shamrock@cypherpunks.to</email></address> + </affiliation> + </author> + </authorgroup> + <!-- 11 MARCH 2003 --> + </sect1info> + + <title>Encrypting Disk Partitions</title> + + <indexterm> + <primary>disks</primary> + <secondary>encrypting</secondary> + </indexterm> + + <para>FreeBSD offers excellent online protections against + unauthorized data access. File permissions and Mandatory Access + Control (MAC) (see <xref linkend="mac">) help prevent + unauthorized third-parties from accessing data while the + operating system is active and the computer is powered up. + However, the permissions enforced by the operating system are + irrelevant if an attacker has physical access to a computer and + can simply move the computer's hard drive to another system to + copy and analyze the sensitive data.</para> + + <para>Regardless of how an attacker may have come into possession + of a hard drive or powered-down computer, both <application>GEOM + Based Disk Encryption (gbde)</application> and + <command>geli</command> cryptographic subsystems in &os; are + able to protect the data on the computer's file systems against + even highly-motivated attackers with significant resources. + Unlike cumbersome encryption methods that encrypt only + individual files, <command>gbde</command> and + <command>geli</command> transparently encrypt entire file + systems. No cleartext ever touches the hard drive's + platter.</para> + + <sect2> + <title>Disk Encryption with + <application>gbde</application></title> + + <procedure> + <step> + <title>Become <username>root</username></title> + + <para>Configuring <application>gbde</application> requires + super-user privileges.</para> + + <screen>&prompt.user; <userinput>su -</userinput> +Password:</screen> + </step> + + <step> + <title>Add &man.gbde.4; Support to the Kernel Configuration + File</title> + + <para>Add the following line to the kernel configuration + file:</para> + + <para><literal>options GEOM_BDE</literal></para> + + <para>Rebuild the kernel as described in <xref + linkend="kernelconfig">.</para> + + <para>Reboot into the new kernel.</para> + </step> + + <step> + <para>An alternative to recompiling the kernel is to use + <command>kldload</command> to load &man.gbde.4;:</para> + + <screen>&prompt.root; <userinput>kldload geom_bde</userinput></screen> + </step> + </procedure> + + <sect3> + <title>Preparing the Encrypted Hard Drive</title> + + <para>The following example assumes that you are adding a new + hard drive to your system that will hold a single encrypted + partition. This partition will be mounted as + <filename>/private</filename>. + <application>gbde</application> can also be used to encrypt + <filename>/home</filename> and + <filename>/var/mail</filename>, but this requires more + complex instructions which exceed the scope of this + introduction.</para> + + <procedure> + <step> + <title>Add the New Hard Drive</title> + + <para>Install the new drive to the system as explained in + <xref linkend="disks-adding">. For the purposes of this + example, a new hard drive partition has been added as + <filename>/dev/ad4s1c</filename>. The + <filename>/dev/ad0s1<replaceable>*</replaceable></filename> + devices represent existing standard FreeBSD partitions + on the example system.</para> + + <screen>&prompt.root; <userinput>ls /dev/ad*</userinput> +/dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 +/dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c +/dev/ad0s1a /dev/ad0s1d /dev/ad4</screen> + </step> + + <step> + <title>Create a Directory to Hold gbde Lock Files</title> + + <screen>&prompt.root; <userinput>mkdir /etc/gbde</userinput></screen> + + <para>The <application>gbde</application> lock file + contains information that + <application>gbde</application> requires to access + encrypted partitions. Without access to the lock file, + <application>gbde</application> will not be able to + decrypt the data contained in the encrypted partition + without significant manual intervention which is not + supported by the software. Each encrypted partition + uses a separate lock file.</para> + </step> + + <step> + <title>Initialize the gbde Partition</title> + + <para>A <application>gbde</application> partition must be + initialized before it can be used. This initialization + needs to be performed only once:</para> + + <screen>&prompt.root; <userinput>gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c.lock</userinput></screen> + + <para>&man.gbde.8; will open your editor, permitting you + to set various configuration options in a template. For + use with UFS1 or UFS2, set the sector_size to + 2048:</para> + + <programlisting># $FreeBSD: src/sbin/gbde/template.txt,v 1.1.36.1 2009/08/03 08:13:06 kensmith Exp $ +# +# Sector size is the smallest unit of data which can be read or written. +# Making it too small decreases performance and decreases available space. +# Making it too large may prevent filesystems from working. 512 is the +# minimum and always safe. For UFS, use the fragment size +# +sector_size = 2048 +[...]</programlisting> + + <para>&man.gbde.8; will ask you twice to type the + passphrase that should be used to secure the data. The + passphrase must be the same both times. + <application>gbde</application>'s ability to protect + your data depends entirely on the quality of the + passphrase that you choose. + <footnote> + <para>For tips on how to select a secure passphrase + that is easy to remember, see the <ulink + url="http://world.std.com/~reinhold/diceware.html">Diceware + Passphrase</ulink> + website.</para></footnote></para> + + <para>The <command>gbde init</command> command creates a + lock file for your <application>gbde</application> + partition that in this example is stored as + <filename>/etc/gbde/ad4s1c.lock</filename>. + <application>gbde</application> lock files must end in + <quote>.lock</quote> in order to be correctly detected + by the <filename>/etc/rc.d/gbde</filename> start up + script.</para> + + <caution> + <para><application>gbde</application> lock files + <emphasis>must</emphasis> be backed up together with + the contents of any encrypted partitions. While + deleting a lock file alone cannot prevent a determined + attacker from decrypting a + <application>gbde</application> partition, without the + lock file, the legitimate owner will be unable to + access the data on the encrypted partition without a + significant amount of work that is totally unsupported + by &man.gbde.8; and its designer.</para> + </caution> + </step> + + <step> + <title>Attach the Encrypted Partition to the + Kernel</title> + + <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c.lock</userinput></screen> + + <para> You will be asked to provide the passphrase that + you selected during the initialization of the encrypted + partition. The new encrypted device will show up in + <filename>/dev</filename> as + <filename>/dev/device_name.bde</filename>:</para> + + <screen>&prompt.root; <userinput>ls /dev/ad*</userinput> +/dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 +/dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c +/dev/ad0s1a /dev/ad0s1d /dev/ad4 /dev/ad4s1c.bde</screen> + </step> + + <step> + <title>Create a File System on the Encrypted + Device</title> + + <para>Once the encrypted device has been attached to the + kernel, you can create a file system on the device. To + create a file system on the encrypted device, use + &man.newfs.8;. Since it is much faster to initialize a + new UFS2 file system than it is to initialize the old + UFS1 file system, using &man.newfs.8; with the + <option>-O2</option> option is recommended.</para> + + <screen>&prompt.root; <userinput>newfs -U -O2 /dev/ad4s1c.bde</userinput></screen> + + <note> + <para>The &man.newfs.8; command must be performed on an + attached <application>gbde</application> partition + which is identified by a + <filename><replaceable>*</replaceable>.bde</filename> + extension to the device name.</para> + </note> + </step> + + <step> + <title>Mount the Encrypted Partition</title> + + <para>Create a mount point for the encrypted file + system.</para> + + <screen>&prompt.root; <userinput>mkdir /private</userinput></screen> + + <para>Mount the encrypted file system.</para> + + <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen> + </step> + + <step> + <title>Verify That the Encrypted File System is + Available</title> + + <para>The encrypted file system should now be visible to + &man.df.1; and be available for use.</para> + + <screen>&prompt.user; <userinput>df -H</userinput> +Filesystem Size Used Avail Capacity Mounted on +/dev/ad0s1a 1037M 72M 883M 8% / +/devfs 1.0K 1.0K 0B 100% /dev +/dev/ad0s1f 8.1G 55K 7.5G 0% /home +/dev/ad0s1e 1037M 1.1M 953M 0% /tmp +/dev/ad0s1d 6.1G 1.9G 3.7G 35% /usr +/dev/ad4s1c.bde 150G 4.1K 138G 0% /private</screen> + </step> + </procedure> + </sect3> + + <sect3> + <title>Mounting Existing Encrypted File Systems</title> + + <para>After each boot, any encrypted file systems must be + re-attached to the kernel, checked for errors, and mounted, + before the file systems can be used. The required commands + must be executed as user <username>root</username>.</para> + + <procedure> + <step> + <title>Attach the gbde Partition to the Kernel</title> + + <screen>&prompt.root; <userinput>gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c.lock</userinput></screen> + + <para>You will be asked to provide the passphrase that you + selected during initialization of the encrypted + <application>gbde</application> partition.</para> + </step> + + <step> + <title>Check the File System for Errors</title> + + <para>Since encrypted file systems cannot yet be listed in + <filename>/etc/fstab</filename> for automatic mounting, + the file systems must be checked for errors by running + &man.fsck.8; manually before mounting.</para> + + <screen>&prompt.root; <userinput>fsck -p -t ffs /dev/ad4s1c.bde</userinput></screen> + </step> + + <step> + <title>Mount the Encrypted File System</title> + + <screen>&prompt.root; <userinput>mount /dev/ad4s1c.bde /private</userinput></screen> + + <para>The encrypted file system is now available for + use.</para> + </step> + </procedure> + + <sect4> + <title>Automatically Mounting Encrypted Partitions</title> + + <para>It is possible to create a script to automatically + attach, check, and mount an encrypted partition, but for + security reasons the script should not contain the + &man.gbde.8; password. Instead, it is recommended that + such scripts be run manually while providing the password + via the console or &man.ssh.1;.</para> + + <para>As an alternative, an <filename>rc.d</filename> script + is provided. Arguments for this script can be passed via + &man.rc.conf.5;, for example:</para> + + <programlisting>gbde_autoattach_all="YES" +gbde_devices="ad4s1c" +gbde_lockdir="/etc/gbde"</programlisting> + + <para>This will require that the + <application>gbde</application> passphrase be entered at + boot time. After typing the correct passphrase, the + <application>gbde</application> encrypted partition will + be mounted automatically. This can be very useful when + using <application>gbde</application> on notebooks.</para> + </sect4> + </sect3> + + <sect3> + <title>Cryptographic Protections Employed by gbde</title> + + <para>&man.gbde.8; encrypts the sector payload using 128-bit + AES in CBC mode. Each sector on the disk is encrypted with + a different AES key. For more information on + <application>gbde</application>'s cryptographic design, + including how the sector keys are derived from the + user-supplied passphrase, see &man.gbde.4;.</para> + </sect3> + + <sect3> + <title>Compatibility Issues</title> + + <para>&man.sysinstall.8; is incompatible with + <application>gbde</application>-encrypted devices. All + <devicename><replaceable>*</replaceable>.bde</devicename> + devices must be detached from the kernel before starting + &man.sysinstall.8; or it will crash during its initial + probing for devices. To detach the encrypted device used in + our example, use the following command:</para> + + <screen>&prompt.root; <userinput>gbde detach /dev/ad4s1c</userinput></screen> + + <para>Also note that, as &man.vinum.4; does not use the + &man.geom.4; subsystem, you cannot use + <application>gbde</application> with + <application>vinum</application> volumes.</para> + </sect3> + </sect2> + + <sect2> + <sect2info> + <authorgroup> + <author> + <firstname>Daniel</firstname> + <surname>Gerzo</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <!-- Date of writing: 28 November 2005 --> + </sect2info> + + <title>Disk Encryption with <command>geli</command></title> + + <para>An alternative cryptographic GEOM class is available - + <command>geli</command>. It is currently being developed by + &a.pjd;. The <command>geli</command> utility is different to + <command>gbde</command>; it offers different features and uses + a different scheme for doing cryptographic work.</para> + + <para>The most important features of &man.geli.8; are:</para> + + <itemizedlist> + <listitem> + <para>Utilizes the &man.crypto.9; framework — when + cryptographic hardware is available, + <command>geli</command> will use it automatically.</para> + </listitem> + + <listitem> + <para>Supports multiple cryptographic algorithms (currently + AES, Blowfish, and 3DES).</para> + </listitem> + + <listitem> + <para>Allows the root partition to be encrypted. The + passphrase used to access the encrypted root partition + will be requested during the system boot.</para> + </listitem> + + <listitem> + <para>Allows the use of two independent keys (e.g., a + <quote>key</quote> and a + <quote>company key</quote>).</para> + </listitem> + + <listitem> + <para><command>geli</command> is fast - performs simple + sector-to-sector encryption.</para> + </listitem> + + <listitem> + <para>Allows backup and restore of Master Keys. When a user + has to destroy his keys, it will be possible to get access + to the data again by restoring keys from the + backup.</para> + </listitem> + + <listitem> + <para>Allows to attach a disk with a random, one-time key + — useful for swap partitions and temporary file + systems.</para> + </listitem> + </itemizedlist> + + <para>More <command>geli</command> features can be found in the + &man.geli.8; manual page.</para> + + <para>The next steps will describe how to enable support for + <command>geli</command> in the &os; kernel and will explain + how to create and use a <command>geli</command> encryption + provider.</para> + + <para>Super-user privileges will be required since modifications + to the kernel are necessary.</para> + + <procedure> + <step> + <title>Adding <command>geli</command> Support to the + Kernel</title> + + <para>Add the following lines to the kernel configuration + file:</para> + + <programlisting>options GEOM_ELI +device crypto</programlisting> + + <para>Rebuild the kernel as described in <xref + linkend="kernelconfig">.</para> + + <para>Alternatively, the <command>geli</command> module can + be loaded at boot time. Add the following line to the + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>geom_eli_load="YES"</programlisting> + + <para>&man.geli.8; should now be supported by the + kernel.</para> + </step> + + <step> + <title>Generating the Master Key</title> + + <para>The following example will describe how to generate a + key file, which will be used as part of the Master Key for + the encrypted provider mounted under + <filename class="directory">/private</filename>. The key + file will provide some random data used to encrypt the + Master Key. The Master Key will be protected by a + passphrase as well. Provider's sector size will be 4kB + big. Furthermore, the discussion will describe how to + attach the <command>geli</command> provider, create a file + system on it, how to mount it, how to work with it, and + finally how to detach it.</para> + + <para>It is recommended to use a bigger sector size (like + 4kB) for better performance.</para> + + <para>The Master Key will be protected with a passphrase and + the data source for key file will be + <filename>/dev/random</filename>. The sector size of + <filename>/dev/da2.eli</filename>, which we call provider, + will be 4kB.</para> + + <screen>&prompt.root; <userinput>dd if=/dev/random of=/root/da2.key bs=64 count=1</userinput> +&prompt.root; <userinput>geli init -s 4096 -K /root/da2.key /dev/da2</userinput> +Enter new passphrase: +Reenter new passphrase:</screen> + + <para>It is not mandatory that both a passphrase and a key + file are used; either method of securing the Master Key + can be used in isolation.</para> + + <para>If key file is given as <quote>-</quote>, standard + input will be used. This example shows how more than one + key file can be used.</para> + + <screen>&prompt.root; <userinput>cat keyfile1 keyfile2 keyfile3 | geli init -K - /dev/da2</userinput></screen> + </step> + + <step> + <title>Attaching the Provider with the Generated Key</title> + + <screen>&prompt.root; <userinput>geli attach -k /root/da2.key /dev/da2</userinput> +Enter passphrase:</screen> + + <para>The new plaintext device will be named + <filename>/dev/<replaceable>da2</replaceable>.eli</filename>.</para> + + <screen>&prompt.root; <userinput>ls /dev/da2*</userinput> +/dev/da2 /dev/da2.eli</screen> + </step> + + <step> + <title>Creating the New File System</title> + + <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/da2.eli bs=1m</userinput> +&prompt.root; <userinput>newfs /dev/da2.eli</userinput> +&prompt.root; <userinput>mount /dev/da2.eli /private</userinput></screen> + + <para>The encrypted file system should be visible to + &man.df.1; and be available for use now:</para> + + <screen>&prompt.root; <userinput>df -H</userinput> +Filesystem Size Used Avail Capacity Mounted on +/dev/ad0s1a 248M 89M 139M 38% / +/devfs 1.0K 1.0K 0B 100% /dev +/dev/ad0s1f 7.7G 2.3G 4.9G 32% /usr +/dev/ad0s1d 989M 1.5M 909M 0% /tmp +/dev/ad0s1e 3.9G 1.3G 2.3G 35% /var +/dev/da2.eli 150G 4.1K 138G 0% /private</screen> + </step> + + <step> + <title>Unmounting and Detaching the Provider</title> + + <para>Once the work on the encrypted partition is done, and + the <filename class="directory">/private</filename> + partition is no longer needed, it is prudent to consider + unmounting and detaching the <command>geli</command> + encrypted partition from the kernel.</para> + + <screen>&prompt.root; <userinput>umount /private</userinput> +&prompt.root; <userinput>geli detach da2.eli</userinput></screen> + </step> + </procedure> + + <para>More information about the use of &man.geli.8; can be + found in the manual page.</para> + + <sect3> + <title>Using the <filename>geli</filename> + <filename>rc.d</filename> Script</title> + + <para><command>geli</command> comes with a + <filename>rc.d</filename> script which can be used to + simplify the usage of <command>geli</command>. An example + of configuring <command>geli</command> through + &man.rc.conf.5; follows:</para> + + <programlisting>geli_devices="da2" +geli_da2_flags="-p -k /root/da2.key"</programlisting> + + <para>This will configure <filename>/dev/da2</filename> as a + <command>geli</command> provider of which the Master Key + file is located in <filename>/root/da2.key</filename>, and + <command>geli</command> will not use a passphrase when + attaching the provider (note that this can only be used if + <option>-P</option> was given during the + <literal>geli init</literal> phase). The system will detach + the <command>geli</command> provider from the kernel before + the system shuts down.</para> + + <para>More information about configuring + <filename>rc.d</filename> is provided in the + <link linkend="configtuning-rcd">rc.d</link> section of the + Handbook.</para> + </sect3> + </sect2> + </sect1> + + <sect1 id="swap-encrypting"> + <sect1info> + <authorgroup> + <author> + <firstname>Christian</firstname> + <surname>Brüffer</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>Encrypting Swap Space</title> + + <indexterm> + <primary>swap</primary> + <secondary>encrypting</secondary> + </indexterm> + + <para>Swap encryption in &os; is easy to configure. Depending on + which version of &os; is being used, different options are + available and configuration can vary slightly. The &man.gbde.8; + or &man.geli.8; encryption systems can be used for swap + encryption. Both systems use the <filename>encswap</filename> + <link linkend="configtuning-rcd">rc.d</link> script.</para> + + <para>The previous section, <link + linkend="disks-encrypting">Encrypting Disk Partitions</link>, + includes a short discussion on the different encryption + systems.</para> + + <sect2> + <title>Why Should Swap be Encrypted?</title> + + <para>Like the encryption of disk partitions, encryption of swap + space is done to protect sensitive information. Imagine an + application that e.g., deals with passwords. As long as these + passwords stay in physical memory, all is well. However, if + the operating system starts swapping out memory pages to free + space for other applications, the passwords may be written to + the disk platters unencrypted and easy to retrieve for an + adversary. Encrypting swap space can be a solution for this + scenario.</para> + </sect2> + + <sect2> + <title>Preparation</title> + + <note> + <para>For the remainder of this section, + <devicename>ad0s1b</devicename> will be the swap + partition.</para> + </note> + + <para>Up to this point the swap has been unencrypted. It is + possible that there are already passwords or other sensitive + data on the disk platters in cleartext. To rectify this, the + data on the swap partition should be overwritten with random + garbage:</para> + + <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ad0s1b bs=1m</userinput></screen> + </sect2> + + <sect2> + <title>Swap Encryption with &man.gbde.8;</title> + + <para>The <literal>.bde</literal> suffix should be added to the + device in the respective <filename>/etc/fstab</filename> swap + line:</para> + + <programlisting># Device Mountpoint FStype Options Dump Pass# +/dev/ad0s1b.bde none swap sw 0 0</programlisting> + </sect2> + + <sect2> + <title>Swap Encryption with &man.geli.8;</title> + + <para>Alternatively, the procedure for using &man.geli.8; for + swap encryption is similar to that of using &man.gbde.8;. The + <literal>.eli</literal> suffix should be added to the device + in the respective <filename>/etc/fstab</filename> swap + line:</para> + + <programlisting># Device Mountpoint FStype Options Dump Pass# +/dev/ad0s1b.eli none swap sw 0 0</programlisting> + + <para>&man.geli.8; uses the <acronym>AES</acronym> algorithm + with a key length of 128 bit by default.</para> + + <para>Optionally, these defaults can be altered using the + <literal>geli_swap_flags</literal> option in + <filename>/etc/rc.conf</filename>. The following line tells + the <filename>encswap</filename> rc.d script to create + &man.geli.8; swap partitions using the Blowfish algorithm with + a key length of 128 bit, a sectorsize of 4 kilobytes and the + <quote>detach on last close</quote> option set:</para> + + <programlisting>geli_swap_flags="-e blowfish -l 128 -s 4096 -d"</programlisting> + + <para>Please refer to the description of the + <command>onetime</command> command in the &man.geli.8; manual + page for a list of possible options.</para> + </sect2> + + <sect2> + <title>Verifying That it Works</title> + + <para>Once the system has been rebooted, proper operation of the + encrypted swap can be verified using the + <command>swapinfo</command> command.</para> + + <para>If &man.gbde.8; is being used:</para> + + <screen>&prompt.user; <userinput>swapinfo</userinput> +Device 1K-blocks Used Avail Capacity +/dev/ad0s1b.bde 542720 0 542720 0%</screen> + + <para>If &man.geli.8; is being used:</para> + + <screen>&prompt.user; <userinput>swapinfo</userinput> +Device 1K-blocks Used Avail Capacity +/dev/ad0s1b.eli 542720 0 542720 0%</screen> + </sect2> + </sect1> + + <sect1 id="disks-hast"> + <sect1info> + <authorgroup> + <author> + <firstname>Daniel</firstname> + <surname>Gerzo</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Freddie</firstname> + <surname>Cash</surname> + <contrib>With inputs from </contrib> + </author> + <author> + <firstname>Pawel Jakub</firstname> + <surname>Dawidek</surname> + </author> + <author> + <firstname>Michael W.</firstname> + <surname>Lucas</surname> + </author> + <author> + <firstname>Viktor</firstname> + <surname>Petersson</surname> + </author> + </authorgroup> + <!-- Date of writing: 26 February 2011 --> + </sect1info> + + <title>Highly Available Storage (HAST)</title> + <indexterm> + <primary>HAST</primary> + <secondary>high availability</secondary> + </indexterm> + + <sect2> + <title>Synopsis</title> + + <para>High availability is one of the main requirements in + serious business applications and highly-available storage is + a key component in such environments. Highly Available + STorage, or <acronym>HAST<remark role="acronym">Highly + Available STorage</remark></acronym>, was developed by + &a.pjd; as a framework which allows transparent storage of the + same data across several physically separated machines + connected by a TCP/IP network. <acronym>HAST</acronym> can be + understood as a network-based RAID1 (mirror), and is similar + to the DRBD® storage system known from the GNU/&linux; + platform. In combination with other high-availability + features of &os; like <acronym>CARP</acronym>, + <acronym>HAST</acronym> makes it possible to build a + highly-available storage cluster that is resistant to hardware + failures.</para> + + <para>After reading this section, you will know:</para> + + <itemizedlist> + <listitem> + <para>What <acronym>HAST</acronym> is, how it works and + which features it provides.</para> + </listitem> + + <listitem> + <para>How to set up and use <acronym>HAST</acronym> on + &os;.</para> + </listitem> + + <listitem> + <para>How to integrate <acronym>CARP</acronym> and + &man.devd.8; to build a robust storage system.</para> + </listitem> + </itemizedlist> + + <para>Before reading this section, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand &unix; and &os; basics + (<xref linkend="basics">).</para> + </listitem> + + <listitem> + <para>Know how to configure network interfaces and other + core &os; subsystems + (<xref linkend="config-tuning">).</para> + </listitem> + + <listitem> + <para>Have a good understanding of &os; networking + (<xref linkend="network-communication">).</para> + </listitem> + + <listitem> + <para>Use &os; 8.1-RELEASE or newer.</para> + </listitem> + </itemizedlist> + + <para>The <acronym>HAST</acronym> project was sponsored by The + &os; Foundation with the support from <ulink + url="http://www.omc.net/">OMCnet Internet Service + GmbH</ulink> and <ulink url="http://www.transip.nl/">TransIP + BV</ulink>.</para> + </sect2> + + <sect2> + <title>HAST Features</title> + + <para>The main features of the <acronym>HAST</acronym> system + are:</para> + + <itemizedlist> + <listitem> + <para>Can be used to mask I/O errors on local hard + drives.</para> + </listitem> + + <listitem> + <para>File system agnostic; works with any file + system supported by &os;.</para> + </listitem> + + <listitem> + <para>Efficient and quick resynchronization, synchronizing + only blocks that were modified during the downtime of a + node.</para> + </listitem> + + <!-- + <listitem> + <para>Has several synchronization modes to allow for fast + failover.</para> + </listitem> + --> + + <listitem> + <para>Can be used in an already deployed environment to add + additional redundancy.</para> + </listitem> + + <listitem> + <para>Together with <acronym>CARP</acronym>, + <application>Heartbeat</application>, or other tools, it + can be used to build a robust and durable storage + system.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>HAST Operation</title> + + <para>As <acronym>HAST</acronym> provides a synchronous + block-level replication of any storage media to several + machines, it requires at least two nodes (physical machines) + — the <literal>primary</literal> (also known as + <literal>master</literal>) node, and the + <literal>secondary</literal> (<literal>slave</literal>) node. + These two machines together will be called a cluster.</para> + + <note> + <para>HAST is currently limited to two cluster nodes in + total.</para> + </note> + + <para>Since <acronym>HAST</acronym> works in a + primary-secondary configuration, it allows only one of the + cluster nodes to be active at any given time. The + <literal>primary</literal> node, also called + <literal>active</literal>, is the one which will handle all + the I/O requests to <acronym>HAST</acronym>-managed + devices. The <literal>secondary</literal> node is then being + automatically synchronized from the <literal>primary</literal> + node.</para> + + <para>The physical components of the <acronym>HAST</acronym> + system are:</para> + + <itemizedlist> + <listitem> + <para>local disk (on primary node)</para> + </listitem> + + <listitem> + <para>disk on remote machine (secondary node)</para> + </listitem> + </itemizedlist> + + <para><acronym>HAST</acronym> operates synchronously on a block + level, making it transparent to file systems and applications. + <acronym>HAST</acronym> provides regular GEOM providers in + <filename class="directory">/dev/hast/</filename> directory + for use by other tools or applications, thus there is no + difference between using <acronym>HAST</acronym>-provided + devices and raw disks, partitions, etc.</para> + + <para>Each write, delete or flush operation is sent to the local + disk and to the remote disk over TCP/IP. Each read operation + is served from the local disk, unless the local disk is not + up-to-date or an I/O error occurs. In such case, the read + operation is sent to the secondary node.</para> + + <sect3> + <title>Synchronization and Replication Modes</title> + + <para><acronym>HAST</acronym> tries to provide fast failure + recovery. For this reason, it is very important to reduce + synchronization time after a node's outage. To provide fast + synchronization, <acronym>HAST</acronym> manages an on-disk + bitmap of dirty extents and only synchronizes those during a + regular synchronization (with an exception of the initial + sync).</para> + + <para>There are many ways to handle synchronization. + <acronym>HAST</acronym> implements several replication modes + to handle different synchronization methods:</para> + + <itemizedlist> + <listitem> + <para><emphasis>memsync</emphasis>: report write operation + as completed when the local write operation is finished + and when the remote node acknowledges data arrival, but + before actually storing the data. The data on the + remote node will be stored directly after sending the + acknowledgement. This mode is intended to reduce + latency, but still provides very good reliability. The + <emphasis>memsync</emphasis> replication mode is + currently not implemented.</para> + </listitem> + + <listitem> + <para><emphasis>fullsync</emphasis>: report write + operation as completed when local write completes and + when remote write completes. This is the safest and the + slowest replication mode. This mode is the + default.</para> + </listitem> + + <listitem> + <para><emphasis>async</emphasis>: report write operation + as completed when local write completes. This is the + fastest and the most dangerous replication mode. It + should be used when replicating to a distant node where + latency is too high for other modes. The + <emphasis>async</emphasis> replication mode is currently + not implemented.</para> + </listitem> + </itemizedlist> + + <warning> + <para>Only the <emphasis>fullsync</emphasis> replication + mode is currently supported.</para> + </warning> + </sect3> + </sect2> + + <sect2> + <title>HAST Configuration</title> + + <para><acronym>HAST</acronym> requires + <literal>GEOM_GATE</literal> support in order to function. + The <literal>GENERIC</literal> kernel does + <emphasis>not</emphasis> include <literal>GEOM_GATE</literal> + by default, however the <filename>geom_gate.ko</filename> + loadable module is available in the default &os; installation. + For stripped-down systems, make sure this module is available. + Alternatively, it is possible to build + <literal>GEOM_GATE</literal> support into the kernel + statically, by adding this line to the custom kernel + configuration file:</para> + + <programlisting>options GEOM_GATE</programlisting> + + <para>The <acronym>HAST</acronym> framework consists of several + parts from the operating system's point of view:</para> + + <itemizedlist> + <listitem> + <para>the &man.hastd.8; daemon responsible for the data + synchronization,</para> + </listitem> + + <listitem> + <para>the &man.hastctl.8; userland management + utility,</para> + </listitem> + + <listitem> + <para>the &man.hast.conf.5; configuration file.</para> + </listitem> + </itemizedlist> + + <para>The following example describes how to configure two nodes + in <literal>master</literal>-<literal>slave</literal> / + <literal>primary</literal>-<literal>secondary</literal> + operation using <acronym>HAST</acronym> to replicate the data + between the two. The nodes will be called + <literal><replaceable>hasta</replaceable></literal> with an IP + address <replaceable>172.16.0.1</replaceable> and + <literal><replaceable>hastb</replaceable></literal> with an IP + address <replaceable>172.16.0.2</replaceable>. Both of these + nodes will have a dedicated hard drive + <devicename>/dev/<replaceable>ad6</replaceable></devicename> + of the same size for <acronym>HAST</acronym> operation. The + <acronym>HAST</acronym> pool (sometimes also referred to as a + resource, i.e., the GEOM provider in + <filename class="directory">/dev/hast/</filename>) will be + called + <filename><replaceable>test</replaceable></filename>.</para> + + <para>Configuration of <acronym>HAST</acronym> is done + in the <filename>/etc/hast.conf</filename> file. This file + should be the same on both nodes. The simplest configuration + possible is:</para> + + <programlisting>resource test { + on hasta { + local /dev/ad6 + remote 172.16.0.2 + } + on hastb { + local /dev/ad6 + remote 172.16.0.1 + } +}</programlisting> + + <para>For more advanced configuration, please consult the + &man.hast.conf.5; manual page.</para> + + <tip> + <para>It is also possible to use host names in the + <literal>remote</literal> statements. In such a case, make + sure that these hosts are resolvable, e.g., they are defined + in the <filename>/etc/hosts</filename> file, or + alternatively in the local <acronym>DNS</acronym>.</para> + </tip> + + <para>Now that the configuration exists on both nodes, + the <acronym>HAST</acronym> pool can be created. Run these + commands on both nodes to place the initial metadata onto the + local disk, and start the &man.hastd.8; daemon:</para> + + <screen>&prompt.root; <userinput>hastctl create test</userinput> +&prompt.root; <userinput>/etc/rc.d/hastd onestart</userinput></screen> + + <note> + <para>It is <emphasis>not</emphasis> possible to use GEOM + providers with an existing file system (i.e., convert an + existing storage to <acronym>HAST</acronym>-managed pool), + because this procedure needs to store some metadata onto the + provider and there will not be enough required space + available.</para> + </note> + + <para>A HAST node's role (<literal>primary</literal> or + <literal>secondary</literal>) is selected by an administrator + or other software like <application>Heartbeat</application> + using the &man.hastctl.8; utility. Move to the primary node + (<literal><replaceable>hasta</replaceable></literal>) and + issue this command:</para> + + <screen>&prompt.root; <userinput>hastctl role primary test</userinput></screen> + + <para>Similarly, run this command on the secondary node + (<literal><replaceable>hastb</replaceable></literal>):</para> + + <screen>&prompt.root; <userinput>hastctl role secondary test</userinput></screen> + + <caution> + <para>When the nodes are unable to communicate with each + other, and both are configured as primary nodes, the + condition is called <literal>split-brain</literal>. To + troubleshoot this situation, follow the steps described in + <xref linkend="disks-hast-sb">.</para> + </caution> + + <para>Verify the result with the + &man.hastctl.8; utility on each node:</para> + + <screen>&prompt.root; <userinput>hastctl status test</userinput></screen> + + <para>The important text is the <literal>status</literal> line, + which should say <literal>complete</literal> + on each of the nodes. If it says <literal>degraded</literal>, + something went wrong. At this point, the synchronization + between the nodes has already started. The synchronization + completes when <command>hastctl status</command> + reports 0 bytes of <literal>dirty</literal> extents.</para> + + + <para>The next step is to create a filesystem on the + <devicename>/dev/hast/<replaceable>test</replaceable></devicename> + GEOM provider and mount it. This must be done on the + <literal>primary</literal> node, as + <filename>/dev/hast/<replaceable>test</replaceable></filename> + appears only on the <literal>primary</literal> node. Creating + the filesystem can take a few minutes, depending on the size + of the hard drive:</para> + + <screen>&prompt.root; <userinput>newfs -U /dev/hast/test</userinput> +&prompt.root; <userinput>mkdir /hast/test</userinput> +&prompt.root; <userinput>mount /dev/hast/test /hast/test</userinput></screen> + + <para>Once the <acronym>HAST</acronym> framework is configured + properly, the final step is to make sure that + <acronym>HAST</acronym> is started automatically during the + system boot. Add this line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>hastd_enable="YES"</programlisting> + + <sect3> + <title>Failover Configuration</title> + + <para>The goal of this example is to build a robust storage + system which is resistant to the failure of any given node. + The scenario is that a <literal>primary</literal> node of + the cluster fails. If this happens, the + <literal>secondary</literal> node is there to take over + seamlessly, check and mount the file system, and continue to + work without missing a single bit of data.</para> + + <para>To accomplish this task, another &os; feature provides + for automatic failover on the IP layer — + <acronym>CARP</acronym>. <acronym>CARP</acronym> (Common + Address Redundancy Protocol) allows multiple hosts on the + same network segment to share an IP address. Set up + <acronym>CARP</acronym> on both nodes of the cluster + according to the documentation available in + <xref linkend="carp">. After setup, each node will have its + own <devicename>carp0</devicename> interface with a shared + IP address <replaceable>172.16.0.254</replaceable>. The + primary <acronym>HAST</acronym> node of the cluster must be + the master <acronym>CARP</acronym> node.</para> + + <para>The <acronym>HAST</acronym> pool created in the previous + section is now ready to be exported to the other hosts on + the network. This can be accomplished by exporting it + through <acronym>NFS</acronym>, + <application>Samba</application> etc, using the shared IP + address <replaceable>172.16.0.254</replaceable>. The only + problem which remains unresolved is an automatic failover + should the primary node fail.</para> + + <para>In the event of <acronym>CARP</acronym> interfaces going + up or down, the &os; operating system generates a + &man.devd.8; event, making it possible to watch for the + state changes on the <acronym>CARP</acronym> interfaces. A + state change on the <acronym>CARP</acronym> interface is an + indication that one of the nodes failed or came back online. + These state change events make it possible to run a script + which will automatically handle the HAST failover.</para> + + <para>To be able to catch state changes on the + <acronym>CARP</acronym> interfaces, add this + configuration to + <filename>/etc/devd.conf</filename> on each node:</para> + + <programlisting>notify 30 { + match "system" "IFNET"; + match "subsystem" "carp0"; + match "type" "LINK_UP"; + action "/usr/local/sbin/carp-hast-switch master"; +}; + +notify 30 { + match "system" "IFNET"; + match "subsystem" "carp0"; + match "type" "LINK_DOWN"; + action "/usr/local/sbin/carp-hast-switch slave"; +};</programlisting> + + <para>Restart &man.devd.8; on both nodes to put the new + configuration into effect:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/devd restart</userinput></screen> + + <para>When the <devicename>carp0</devicename> interface goes + up or down (i.e., the interface state changes), the system + generates a notification, allowing the &man.devd.8; + subsystem to run an arbitrary script, in this case + <filename>/usr/local/sbin/carp-hast-switch</filename>. This + is the script which will handle the automatic failover. For + further clarification about the above &man.devd.8; + configuration, please consult the &man.devd.conf.5; manual + page.</para> + + <para>An example of such a script could be:</para> + + <programlisting>#!/bin/sh + +# Original script by Freddie Cash <fjwcash@gmail.com> +# Modified by Michael W. Lucas <mwlucas@BlackHelicopters.org> +# and Viktor Petersson <vpetersson@wireload.net> + +# The names of the HAST resources, as listed in /etc/hast.conf +resources="test" + +# delay in mounting HAST resource after becoming master +# make your best guess +delay=3 + +# logging +log="local0.debug" +name="carp-hast" + +# end of user configurable stuff + +case "$1" in + master) + logger -p $log -t $name "Switching to primary provider for ${resources}." + sleep ${delay} + + # Wait for any "hastd secondary" processes to stop + for disk in ${resources}; do + while $( pgrep -lf "hastd: ${disk} \(secondary\)" > /dev/null 2>&1 ); do + sleep 1 + done + + # Switch role for each disk + hastctl role primary ${disk} + if [ $? -ne 0 ]; then + logger -p $log -t $name "Unable to change role to primary for resource ${disk}." + exit 1 + fi + done + + # Wait for the /dev/hast/* devices to appear + for disk in ${resources}; do + for I in $( jot 60 ); do + [ -c "/dev/hast/${disk}" ] && break + sleep 0.5 + done + + if [ ! -c "/dev/hast/${disk}" ]; then + logger -p $log -t $name "GEOM provider /dev/hast/${disk} did not appear." + exit 1 + fi + done + + logger -p $log -t $name "Role for HAST resources ${resources} switched to primary." + + + logger -p $log -t $name "Mounting disks." + for disk in ${resources}; do + mkdir -p /hast/${disk} + fsck -p -y -t ufs /dev/hast/${disk} + mount /dev/hast/${disk} /hast/${disk} + done + + ;; + + slave) + logger -p $log -t $name "Switching to secondary provider for ${resources}." + + # Switch roles for the HAST resources + for disk in ${resources}; do + if ! mount | grep -q "^/dev/hast/${disk} on " + then + else + umount -f /hast/${disk} + fi + sleep $delay + hastctl role secondary ${disk} 2>&1 + if [ $? -ne 0 ]; then + logger -p $log -t $name "Unable to switch role to secondary for resource ${disk}." + exit 1 + fi + logger -p $log -t $name "Role switched to secondary for resource ${disk}." + done + ;; +esac</programlisting> + + <para>In a nutshell, the script takes these actions when a + node becomes <literal>master</literal> / + <literal>primary</literal>:</para> + + <itemizedlist> + <listitem> + <para>Promotes the <acronym>HAST</acronym> pools to + primary on a given node.</para> + </listitem> + + <listitem> + <para>Checks the file system under the + <acronym>HAST</acronym> pool.</para> + </listitem> + + <listitem> + <para>Mounts the pools at an appropriate place.</para> + </listitem> + </itemizedlist> + + <para>When a node becomes <literal>backup</literal> / + <literal>secondary</literal>:</para> + + <itemizedlist> + <listitem> + <para>Unmounts the <acronym>HAST</acronym> pools.</para> + </listitem> + + <listitem> + <para>Degrades the <acronym>HAST</acronym> pools to + secondary.</para> + </listitem> + </itemizedlist> + + <caution> + <para>Keep in mind that this is just an example script which + should serve as a proof of concept. It does not + handle all the possible scenarios and can be extended or + altered in any way, for example it can start/stop required + services, etc.</para> + </caution> + + <tip> + <para>For this example, we used a standard UFS + file system. To reduce the time needed for + recovery, a journal-enabled UFS or ZFS file system can + be used.</para> + </tip> + + <para>More detailed information with additional examples can + be found in the + <ulink url="http://wiki.FreeBSD.org/HAST">HAST Wiki</ulink> + page.</para> + </sect3> + </sect2> + + <sect2> + <title>Troubleshooting</title> + + <sect3> + <title>General Troubleshooting Tips</title> + + <para><acronym>HAST</acronym> should generally work without + issues. However, as with any other software product, there + may be times when it does not work as supposed. The sources + of the problems may be different, but the rule of thumb is + to ensure that the time is synchronized between all nodes of + the cluster.</para> + + <para>When troubleshooting <acronym>HAST</acronym> problems, + the debugging level of &man.hastd.8; should be increased by + starting the &man.hastd.8; daemon with the + <literal>-d</literal> argument. Note that this argument may + be specified multiple times to further increase the + debugging level. A lot of useful information may be + obtained this way. Consider also using the + <literal>-F</literal> argument, which starts the + &man.hastd.8; daemon in the foreground.</para> + </sect3> + + <sect3 id="disks-hast-sb"> + <title>Recovering from the Split-brain Condition</title> + + <para><literal>Split-brain</literal> is when the nodes of the + cluster are unable to communicate with each other, and both + are configured as primary. This is a dangerous condition + because it allows both nodes to make incompatible changes to + the data. This problem must be corrected manually by the + system administrator.</para> + + <para>The administrator must decide which node has more + important changes (or merge them manually) and let + <acronym>HAST</acronym> perform full synchronization of the + node which has the broken data. To do this, issue these + commands on the node which needs to be + resynchronized:</para> + + <screen>&prompt.root; <userinput>hastctl role init <resource></userinput> +&prompt.root; <userinput>hastctl create <resource></userinput> +&prompt.root; <userinput>hastctl role secondary <resource></userinput></screen> + </sect3> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/dtrace/Makefile b/en_US.ISO8859-1/books/handbook/dtrace/Makefile new file mode 100644 index 0000000000..0a0e6e03dc --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/dtrace/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= dtrace/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml b/en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml new file mode 100644 index 0000000000..8b5977fae9 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/dtrace/chapter.sgml @@ -0,0 +1,386 @@ +<!-- +Recently I suggested to myself that this should become a profiling +and debugging chapter, which covers things like ktrace(1) and +using other debugging (like -x in shell scripts). But then I +realized that, over time and while DTrace becomes better supported, +that might make this chapter too large. +--> + +<!-- + The FreeBSD Documentation Project + $FreeBSD$ +--> + +<chapter id="dtrace"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>&dtrace;</title> + + <sect1 id="dtrace-synopsis"> + <title>Synopsis</title> + + <indexterm><primary>&dtrace;</primary></indexterm> + <indexterm> + <primary>&dtrace; support</primary> + <see>&dtrace;</see> + </indexterm> + + <para>&dtrace;, also known as Dynamic Tracing, was developed by + &sun; as a tool for locating performance bottlenecks + in production and pre-production systems. It is not, in any way, + a debugging tool, but a tool for real time system analysis to + locate performance and other issues.</para> + + <para>&dtrace; is a remarkable profiling tool, with an impressive + array of features for diagnosing system issues. It may also be + used to run pre-written scripts to take advantage of its + capabilities. Users may even author their own utilities using + the &dtrace; D Language, allowing them to customize their profiling + based on specific needs.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>What &dtrace; is and what features it provides.</para> + </listitem> + + <listitem> + <para>Differences between the &solaris; &dtrace; implementation + and the one provided by &os;.</para> + </listitem> + + <listitem> + <para>How to enable and use &dtrace; on &os;.</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> + + <listitem> + <para>Understand how to obtain and rebuild the &os; sources + (<xref linkend="updating-upgrading">).</para> + </listitem> + </itemizedlist> + + <!-- + Temporary warning to avoid listing experimental versions + and production versions of FreeBSD with this technology. + --> + <warning> + <para>This feature is considered experimental. Some options + may be lacking in functionality, other parts may not work + at all. In time, this feature will be considered production + ready and this documentation will be altered to fit that + situation.</para> + </warning> + </sect1> + + <sect1 id="dtrace-implementation"> + <title>Implementation Differences</title> + + <para>While the &dtrace; in &os; is very similar to that found + in &solaris;, differences exist that should be explained before + continuing. The primary difference users will notice is that + on &os;, &dtrace; needs to be specifically enabled. There are + kernel options and modules which must be enabled for &dtrace; to + work properly. These will be explained later.</para> + + <para>There is a <literal>DDB_CTF</literal> kernel option which + is used to enable support for loading the <acronym>CTF</acronym> + data from kernel modules and the kernel itself. + <acronym>CTF</acronym> is the &solaris; Compact C Type Format + which encapsulates a reduced form of debugging information + similar to <acronym>DWARF</acronym> and the venerable stabs. + This <acronym>CTF</acronym> data is added to the binaries by the + <command>ctfconvert</command> and <command>ctfmerge</command> + build tools. The <command>ctfconvert</command> utility parses + <acronym>DWARF</acronym> <acronym>ELF</acronym> debug sections + created by the compiler and <command>ctfmerge</command> merges + <acronym>CTF</acronym> <acronym>ELF</acronym> sections from + objects into either executables or shared libraries. More on + how to enable this for the kernel and &os; build is + forthcoming.</para> + + <para>Some different providers exist for &os; than for &solaris;. + Most notable is the <literal>dtmalloc</literal> provider, which + allows tracing <function>malloc()</function> by type in the + &os; kernel.</para> + + <para>Only <username>root</username> may use &dtrace; on &os;. + This is related to security differences, &solaris; has a few + low level security checks which do not yet exist in &os;. As + such, the <devicename>/dev/dtrace/dtrace</devicename> is strictly + limited to <username>root</username> users only.</para> + + <para>Finally, the &dtrace; software falls under &sun;'s + <acronym>CDDL</acronym> license. The <literal>Common Development + and Distribution License</literal> comes with &os;, see the + <filename>/usr/src/cddl/contrib/opensolaris/OPENSOLARIS.LICENSE</filename> + or view it online at + <ulink url="http://www.opensolaris.org/os/licensing"></ulink>.</para> + + <para>This license means that a &os; kernel with the &dtrace; options + is still <acronym>BSD</acronym> licensed; however the + <acronym>CDDL</acronym> kicks in when the modules are distributed + in binary form, or the binaries are loaded.</para> + </sect1> + + <sect1 id="dtrace-enable"> + <title>Enabling &dtrace; Support</title> + + <para>To enable support for &dtrace;, add the following lines to + the kernel configuration file:</para> + + <programlisting>options KDTRACE_HOOKS +options DDB_CTF</programlisting> + + <note> + <para>Users of the AMD64 architecture will want to add the + following line to their kernel configuration file:</para> + + <programlisting>options KDTRACE_FRAME</programlisting> + + <para>This option provides support for the <acronym>FBT</acronym> + feature. &dtrace; will work without this option; however, there + will be limited support for function boundary tracing.</para> + </note> + + <para>All sources must be rebuilt and installed with <acronym>CTF</acronym> options. + To accomplish this task, rebuild the &os; sources using:</para> + + <!-- XXXTR: WITH_CTF has been reported to leave a user with a + broken system when used with buildworld. Until this is + fixed, comment out those parts. When uncommenting, kill + the extra screen. + --> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput> +<!-- &prompt.root; <userinput>make WITH_CTF=1 buildworld</userinput> --> +&prompt.root; <userinput>make WITH_CTF=1 kernel</userinput></screen> +<!-- &prompt.root; <userinput>make WITH_CTF=1 installworld</userinput> +&prompt.root; <userinput>mergemaster -Ui</userinput></screen> --> + + <para>The system will need to be restarted.</para> + + <para>After rebooting and allowing the new kernel to be loaded + into memory, support for the Korn shell should be added. This + is needed as the &dtrace; toolkit has several utilities written + in <command>ksh</command>. Install the + <filename role="package">shells/ksh93</filename>. It is also + possible to run these tools under + <filename role="package">shells/pdksh</filename> or + <filename role="package">shells/mksh</filename>.</para> + + <para>Finally, obtain the current &dtrace; toolkit. The current + version is available at + <ulink url="http://www.opensolaris.org/os/community/dtrace/dtracetoolkit/"></ulink>. + There is an install mechanism included; however, installation + is not required to make use of the bundled utilities.</para> + </sect1> + + <sect1 id="dtrace-using"> + <title>Using &dtrace;</title> + + <para>Before making use of &dtrace; functionality, the &dtrace; device + must exist. To load the device, issue the following + command:</para> + + <screen>&prompt.root; <userinput>kldload dtraceall</userinput></screen> + + <para>&dtrace; support should now be available. To view all probes + the administrator may now execute the following command:</para> + + <screen>&prompt.root; <userinput>dtrace -l | more</userinput></screen> + + <para>All output is passed to the <command>more</command> + utility as it will quickly overflow the screen buffer. At + this point, &dtrace; should be considered working. It is now + time to review the toolkit.</para> + + <para>The toolkit is a collection of ready-made scripts to run + with &dtrace; to collect system information. There are scripts + to check open files, memory, <acronym>CPU</acronym> usage and + a lot more. Extract the scripts with the following + command:</para> + + <screen>&prompt.root; <userinput>gunzip -c DTraceToolkit* | tar xvf -</userinput></screen> + + <para>Change into that directory with the <command>cd</command> + and change the execution permissions on all files, designated + as those files with lower case names, to + <literal>755</literal>.</para> + + <para>All of these scripts will need modifications to their + contents. The ones which refer to + <filename>/usr/bin/ksh</filename> need that changed to + <filename>/usr/local/bin/ksh</filename>, the others which + use <filename>/usr/bin/sh</filename> need to be altered to use + <filename>/bin/sh</filename>, and finally the ones which + use <filename>/usr/bin/perl</filename> will need altered to + use <filename>/usr/local/bin/perl</filename>.</para> + + <important> + <para>At this point it is prudent to remind the reader that + &dtrace; support in &os; is <emphasis>incomplete</emphasis> + and <emphasis>experimental</emphasis>. Many of these scripts + will not work as they are either too &solaris;-specific or + use probes which are unsupported at this time.</para> + </important> + + <para>At the time of this writing only two of the scripts of the + &dtrace; Toolkit are fully supported in &os;: + the <filename>hotkernel</filename> + and <filename>procsystime</filename> scripts. These are the two + we will explore in the following parts of this section.</para> + + <para>The <filename>hotkernel</filename> is designed to identify + which function is using the most kernel time. Run normally, it + will produce output similar to the following:</para> + + <screen>&prompt.root; <userinput>./hotkernel</userinput> +Sampling... Hit Ctrl-C to end.</screen> + + <para>The system administrator must use the + <keycombo action="simul"><keycap>Ctrl</keycap><keycap>C</keycap> + </keycombo> key combination to stop the process. Upon + termination, the script will display a list of kernel functions and + timing information, sorting the output in increasing order of + time:</para> + + <screen>kernel`_thread_lock_flags 2 0.0% +0xc1097063 2 0.0% +kernel`sched_userret 2 0.0% +kernel`kern_select 2 0.0% +kernel`generic_copyin 3 0.0% +kernel`_mtx_assert 3 0.0% +kernel`vm_fault 3 0.0% +kernel`sopoll_generic 3 0.0% +kernel`fixup_filename 4 0.0% +kernel`_isitmyx 4 0.0% +kernel`find_instance 4 0.0% +kernel`_mtx_unlock_flags 5 0.0% +kernel`syscall 5 0.0% +kernel`DELAY 5 0.0% +0xc108a253 6 0.0% +kernel`witness_lock 7 0.0% +kernel`read_aux_data_no_wait 7 0.0% +kernel`Xint0x80_syscall 7 0.0% +kernel`witness_checkorder 7 0.0% +kernel`sse2_pagezero 8 0.0% +kernel`strncmp 9 0.0% +kernel`spinlock_exit 10 0.0% +kernel`_mtx_lock_flags 11 0.0% +kernel`witness_unlock 15 0.0% +kernel`sched_idletd 137 0.3% +0xc10981a5 42139 99.3%</screen> + + <!-- XXXTR: I attempted to use objdump and nm on /boot/kernel/kernel + to find 0xc10981a5, but to no avail. It would be nice to know + how we should look that up. --> + + <para>This script will also work with kernel modules. To use this + feature, run the script with the <option>-m</option> flag:</para> + + <screen>&prompt.root; <userinput>./hotkernel -m</userinput> +Sampling... Hit Ctrl-C to end. +^C +MODULE COUNT PCNT +0xc107882e 1 0.0% +0xc10e6aa4 1 0.0% +0xc1076983 1 0.0% +0xc109708a 1 0.0% +0xc1075a5d 1 0.0% +0xc1077325 1 0.0% +0xc108a245 1 0.0% +0xc107730d 1 0.0% +0xc1097063 2 0.0% +0xc108a253 73 0.0% +kernel 874 0.4% +0xc10981a5 213781 99.6%</screen> + + <!-- XXXTR: I was unable to match these up with output from + kldstat and kldstat -v and grep. Maybe I'm missing something + seriously obvious. It is 5AM btw. --> + + <para>The <filename>procsystime</filename> script captures and + prints the system call time usage for a given + <acronym>PID</acronym> or process name. In the following + example, a new instance of <filename>/bin/csh</filename> + was spawned. The <filename>procsystime</filename> was executed + and remained waiting while a few commands were typed on the + other incarnation of <command>csh</command>. These are the + results of this test:</para> + + <screen>&prompt.root; <userinput>./procsystime -n csh</userinput> +Tracing... Hit Ctrl-C to end... +^C + +Elapsed Times for processes csh, + + SYSCALL TIME (ns) + getpid 6131 + sigreturn 8121 + close 19127 + fcntl 19959 + dup 26955 + setpgid 28070 + stat 31899 + setitimer 40938 + wait4 62717 + sigaction 67372 + sigprocmask 119091 + gettimeofday 183710 + write 263242 + execve 492547 + ioctl 770073 + vfork 3258923 + sigsuspend 6985124 + read 3988049784</screen> + + <para>As shown, the <function>read()</function> system call seems to use the + most time in nanoseconds with the <function>getpid()</function> + system call used the least amount of time.</para> + </sect1> + + <sect1 id="dtrace-language"> + <title>The D Language</title> + + <para>The &dtrace; Toolkit includes many scripts in the special language of + &dtrace;. This language is called <quote>the D language</quote> by &sun; + documentation, and it is very similar to C++. An in depth + discussion of the language is beyond the scope of this document. It is + extensively discussed + at <ulink url="http://wikis.sun.com/display/DTrace/Documentation"></ulink>.</para> + </sect1> +</chapter> + + <!-- XXXTR: Should probably put links and resources here. I'm + nervous about this chapter as it may require a partial + re-write and large modification once DTrace is complete, but + at least we can get everyone started ... --> diff --git a/en_US.ISO8859-1/books/handbook/eresources/Makefile b/en_US.ISO8859-1/books/handbook/eresources/Makefile new file mode 100644 index 0000000000..cb030a0162 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/eresources/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= eresources/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml b/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml new file mode 100644 index 0000000000..594cd5ee65 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/eresources/chapter.sgml @@ -0,0 +1,2129 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<appendix id="eresources"> + <title>Resources on the Internet</title> + + <para>The rapid pace of FreeBSD progress makes print media impractical as a + means of following the latest developments. Electronic resources are the + best, if not often the only, way to stay informed of the latest advances. + Since FreeBSD is a volunteer effort, the user community itself also + generally serves as a <quote>technical support department</quote> of sorts, + with electronic mail, web forums, and USENET news being the most + effective way of reaching that community.</para> + + <para>The most important points of contact with the FreeBSD user community + are outlined below. If you are aware of other resources not mentioned + here, please send them to the &a.doc; so that they may also be + included.</para> + + <sect1 id="eresources-mail"> + <title>Mailing Lists</title> + + <para>The mailing lists are the most direct way of addressing + questions or opening a technical discussion to a concentrated + FreeBSD audience. There are a wide variety of lists on a number + of different FreeBSD topics. Addressing your questions to the + most appropriate mailing list will invariably assure a faster + and more accurate response.</para> + + <para>The charters for the various lists are given at the bottom of this + document. <emphasis>Please read the charter before joining or sending + mail to any list</emphasis>. Most of our list subscribers now receive + many hundreds of FreeBSD related messages every day, and by setting down + charters and rules for proper use we are striving to keep the + signal-to-noise ratio of the lists high. To do less would see the + mailing lists ultimately fail as an effective communications medium for + the project.</para> + + <note> + <para><emphasis>If you wish to test your ability to send to + &os; lists, send a test message to &a.test.name;.</emphasis> + Please do not send test messages to any other list.</para> + </note> + + <para>When in doubt about what list to post a question to, see <ulink + url="&url.articles.freebsd-questions;">How to get best results from + the FreeBSD-questions mailing list</ulink>.</para> + + <para>Before posting to any list, please learn about how to best use + the mailing lists, such as how to help avoid frequently-repeated + discussions, by reading the <ulink url="&url.articles.mailing-list-faq;"> + Mailing List Frequently Asked Questions</ulink> (FAQ) document.</para> + + <para>Archives are kept for all of the mailing lists and can be searched + using the <ulink url="&url.base;/search/index.html">FreeBSD World + Wide Web server</ulink>. The keyword searchable archive offers an + excellent way of finding answers to frequently asked questions and + should be consulted before posting a question. Note that this + also means that messages sent to FreeBSD mailing lists are + archived in perpetuity. When protecting privacy is a + concern, consider using a disposable secondary email address and + posting only public information.</para> + + <sect2 id="eresources-summary"> + <title>List Summary</title> + + <para><emphasis>General lists:</emphasis> The following are general + lists which anyone is free (and encouraged) to join:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>List</entry> + <entry>Purpose</entry> + </row> + </thead> + + <tbody> + <row> + <entry>&a.advocacy.name;</entry> + <entry>FreeBSD Evangelism</entry> + </row> + + <row> + <entry>&a.announce.name;</entry> + <entry>Important events and project milestones</entry> + </row> + + <row> + <entry>&a.arch.name;</entry> + <entry>Architecture and design discussions</entry> + </row> + + <row> + <entry>&a.bugbusters.name;</entry> + <entry>Discussions pertaining to the maintenance of the FreeBSD + problem report database and related tools</entry> + </row> + + <row> + <entry>&a.bugs.name;</entry> + <entry>Bug reports</entry> + </row> + + <row> + <entry>&a.chat.name;</entry> + <entry>Non-technical items related to the FreeBSD + community</entry> + </row> + + <row> + <entry>&a.chromium.name;</entry> + <entry>FreeBSD-specific Chromium issues</entry> + </row> + + <row> + <entry>&a.current.name;</entry> + <entry>Discussion concerning the use of + &os.current;</entry> + </row> + + <row> + <entry>&a.isp.name;</entry> + <entry>Issues for Internet Service Providers using + FreeBSD</entry> + </row> + + <row> + <entry>&a.jobs.name;</entry> + <entry>FreeBSD employment and consulting + opportunities</entry> + </row> + + <row> + <entry>&a.questions.name;</entry> + <entry>User questions and technical support</entry> + </row> + + <row> + <entry>&a.security-notifications.name;</entry> + <entry>Security notifications</entry> + </row> + + <row> + <entry>&a.stable.name;</entry> + <entry>Discussion concerning the use of + &os.stable;</entry> + </row> + + <row> + <entry>&a.test.name;</entry> + <entry>Where to send your test messages instead of one of + the actual lists</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para><emphasis>Technical lists:</emphasis> The following lists are for + technical discussion. You should read the charter for each list + carefully before joining or sending mail to one as there are firm + guidelines for their use and content.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>List</entry> + <entry>Purpose</entry> + </row> + </thead> + + <tbody> + <row> + <entry>&a.acpi.name;</entry> + <entry>ACPI and power management development</entry> + </row> + + <row> + <entry>&a.afs.name;</entry> + <entry>Porting AFS to FreeBSD</entry> + </row> + + <row> + <entry>&a.aic7xxx.name;</entry> + <entry>Developing drivers for the &adaptec; AIC 7xxx</entry> + </row> + + <row> + <entry>&a.amd64.name;</entry> + <entry>Porting FreeBSD to AMD64 systems</entry> + </row> + + <row> + <entry>&a.apache.name;</entry> + <entry>Discussion about <application>Apache</application> related ports</entry> + </row> + + <row> + <entry>&a.arm.name;</entry> + <entry>Porting FreeBSD to &arm; processors</entry> + </row> + + <row> + <entry>&a.atm.name;</entry> + <entry>Using ATM networking with FreeBSD</entry> + </row> + + <row> + <entry>&a.binup.name;</entry> + <entry>Design and development of the binary update system</entry> + </row> + + <row> + <entry>&a.bluetooth.name;</entry> + <entry>Using &bluetooth; technology in FreeBSD</entry> + </row> + + <row> + <entry>&a.cluster.name;</entry> + <entry>Using FreeBSD in a clustered environment</entry> + </row> + + <row> + <entry>&a.cvsweb.name;</entry> + <entry>CVSweb maintenance</entry> + </row> + + <row> + <entry>&a.database.name;</entry> + <entry>Discussing database use and development under + FreeBSD</entry> + </row> + + <row> + <entry>&a.desktop.name;</entry> + <entry>Using and improving &os; on the desktop</entry> + </row> + + <row> + <entry>&a.doc.name;</entry> + <entry>Creating FreeBSD related documents</entry> + </row> + + <row> + <entry>&a.drivers.name;</entry> + <entry>Writing device drivers for &os;</entry> + </row> + + <row> + <entry>&a.eclipse.name;</entry> + <entry>FreeBSD users of Eclipse IDE, tools, rich client + applications and ports.</entry> + </row> + + <row> + <entry>&a.embedded.name;</entry> + <entry>Using FreeBSD in embedded applications</entry> + </row> + + <row> + <entry>&a.eol.name;</entry> + <entry>Peer support of FreeBSD-related software that + is no longer supported by the FreeBSD project.</entry> + </row> + + <row> + <entry>&a.emulation.name;</entry> + <entry>Emulation of other systems such as + Linux/&ms-dos;/&windows;</entry> + </row> + + <row> + <entry>&a.firewire.name;</entry> + <entry>FreeBSD &firewire; (iLink, IEEE 1394) technical + discussion</entry> + </row> + + <row> + <entry>&a.fs.name;</entry> + <entry>File systems</entry> + </row> + + <row> + <entry>&a.gecko.name;</entry> + <entry><application>Gecko Rendering Engine</application> issues</entry> + </row> + + <row> + <entry>&a.geom.name;</entry> + <entry>GEOM-specific discussions and implementations</entry> + </row> + + <row> + <entry>&a.gnome.name;</entry> + <entry>Porting <application>GNOME</application> and <application>GNOME</application> applications</entry> + </row> + + <row> + <entry>&a.hackers.name;</entry> + <entry>General technical discussion</entry> + </row> + + <row> + <entry>&a.hardware.name;</entry> + <entry>General discussion of hardware for running + FreeBSD</entry> + </row> + + <row> + <entry>&a.i18n.name;</entry> + <entry>FreeBSD Internationalization</entry> + </row> + + <row> + <entry>&a.ia32.name;</entry> + <entry>FreeBSD on the IA-32 (&intel; x86) platform</entry> + </row> + + <row> + <entry>&a.ia64.name;</entry> + <entry>Porting FreeBSD to &intel;'s upcoming IA64 systems</entry> + </row> + + <row> + <entry>&a.ipfw.name;</entry> + <entry>Technical discussion concerning the redesign of the IP + firewall code</entry> + </row> + + <row> + <entry>&a.isdn.name;</entry> + <entry>ISDN developers</entry> + </row> + + <row> + <entry>&a.jail.name;</entry> + <entry>Discussion about the &man.jail.8; facility</entry> + </row> + + <row> + <entry>&a.java.name;</entry> + <entry>&java; developers and people porting &jdk;s to + FreeBSD</entry> + </row> + + <row> + <entry>&a.kde.name;</entry> + <entry>Porting <application>KDE</application> and <application>KDE</application> applications</entry> + </row> + + <row> + <entry>&a.lfs.name;</entry> + <entry>Porting LFS to FreeBSD</entry> + </row> + + <row> + <entry>&a.mips.name;</entry> + <entry>Porting FreeBSD to &mips;</entry> + </row> + + <row> + <entry>&a.mobile.name;</entry> + <entry>Discussions about mobile computing</entry> + </row> + + <row> + <entry>&a.mono.name;</entry> + <entry>Mono and C# applications on FreeBSD</entry> + </row> + + <row> + <entry>&a.mozilla.name;</entry> + <entry>Porting <application>Mozilla</application> to FreeBSD</entry> + </row> + + <row> + <entry>&a.multimedia.name;</entry> + <entry>Multimedia applications</entry> + </row> + + <row> + <entry>&a.newbus.name;</entry> + <entry>Technical discussions about bus architecture</entry> + </row> + + <row> + <entry>&a.net.name;</entry> + <entry>Networking discussion and TCP/IP source code</entry> + </row> + + <row> + <entry>&a.office.name;</entry> + <entry>Office applications on &os;</entry> + </row> + + <row> + <entry>&a.performance.name;</entry> + <entry>Performance tuning questions for high + performance/load installations</entry> + </row> + + <row> + <entry>&a.perl.name;</entry> + <entry>Maintenance of a number of + Perl-related ports</entry> + </row> + + <row> + <entry>&a.pf.name;</entry> + <entry>Discussion and questions about the packet filter + firewall system</entry> + </row> + + <row> + <entry>&a.platforms.name;</entry> + <entry>Concerning ports to non &intel; architecture + platforms</entry> + </row> + + <row> + <entry>&a.ports.name;</entry> + <entry>Discussion of the Ports Collection</entry> + </row> + + <row> + <entry>&a.ports-announce.name;</entry> + <entry>Important news and instructions about the Ports Collection</entry> + </row> + + <row> + <entry>&a.ports-bugs.name;</entry> + <entry>Discussion of the ports bugs/PRs</entry> + </row> + + <row> + <entry>&a.ppc.name;</entry> + <entry>Porting FreeBSD to the &powerpc;</entry> + </row> + + <row> + <entry>&a.proliant.name;</entry> + <entry>Technical discussion of FreeBSD on HP ProLiant server platforms</entry> + </row> + + <row> + <entry>&a.python.name;</entry> + <entry>FreeBSD-specific Python issues</entry> + </row> + + <row> + <entry>&a.rc.name;</entry> + <entry>Discussion related to the <filename>rc.d</filename> system and its development</entry> + </row> + + <row> + <entry>&a.realtime.name;</entry> + <entry>Development of realtime extensions to FreeBSD</entry> + </row> + + <row> + <entry>&a.ruby.name;</entry> + <entry>FreeBSD-specific Ruby discussions</entry> + </row> + + <row> + <entry>&a.scsi.name;</entry> + <entry>The SCSI subsystem</entry> + </row> + + <row> + <entry>&a.security.name;</entry> + <entry>Security issues affecting FreeBSD</entry> + </row> + + <row> + <entry>&a.small.name;</entry> + <entry>Using FreeBSD in embedded applications + (obsolete; use &a.embedded.name; instead)</entry> + </row> + + <row> + <entry>&a.sparc.name;</entry> + <entry>Porting FreeBSD to &sparc; based systems</entry> + </row> + + <row> + <entry>&a.standards.name;</entry> + <entry>FreeBSD's conformance to the C99 and the &posix; + standards</entry> + </row> + + <row> + <entry>&a.sysinstall.name;</entry> + <entry>&man.sysinstall.8; development</entry> + </row> + + <row> + <entry>&a.threads.name;</entry> + <entry>Threading in FreeBSD</entry> + </row> + + <row> + <entry>&a.tilera.name;</entry> + <entry>Porting FreeBSD to the Tilera family of CPUs</entry> + </row> + + <row> + <entry>&a.tokenring.name;</entry> + <entry>Support Token Ring in FreeBSD</entry> + </row> + + <row> + <entry>&a.toolchain.name;</entry> + <entry>Maintenance of &os;'s integrated toolchain</entry> + </row> + + <row> + <entry>&a.usb.name;</entry> + <entry>Discussing &os; support for USB</entry> + </row> + + <row> + <entry>&a.virtualization.name;</entry> + <entry>Discussion of various virtualization techniques supported + by &os;</entry> + </row> + + <row> + <entry>&a.vuxml.name;</entry> + <entry>Discussion on VuXML infrastructure</entry> + </row> + + <row> + <entry>&a.x11.name;</entry> + <entry>Maintenance and support of X11 on FreeBSD</entry> + </row> + + <row> + <entry>&a.xen.name;</entry> + <entry>Discussion of the &os; port to &xen; — implementation and usage</entry> + </row> + + <row> + <entry>&a.xfce.name;</entry> + <entry><application>XFCE</application> for &os; — porting and maintaining</entry> + </row> + + <row> + <entry>&a.zope.name;</entry> + <entry><application>Zope</application> for &os; — + porting and maintaining</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para><emphasis>Limited lists:</emphasis> The following lists are for + more specialized (and demanding) audiences and are probably not of + interest to the general public. It is also a good idea to establish a + presence in the technical lists before joining one of these limited + lists so that you will understand the communications etiquette involved.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>List</entry> + <entry>Purpose</entry> + </row> + </thead> + + <tbody> + <row> + <entry>&a.hubs.name;</entry> + <entry>People running mirror sites (infrastructural + support)</entry> + </row> + + <row> + <entry>&a.usergroups.name;</entry> + <entry>User group coordination</entry> + </row> + + <row> + <entry>&a.vendors.name;</entry> + <entry>Vendors pre-release coordination</entry> + </row> + + <row> + <entry>&a.wip-status.name;</entry> + <entry>FreeBSD Work-In-Progress Status</entry> + </row> + + <row> + <entry>&a.wireless.name;</entry> + <entry>Discussions of 802.11 stack, tools, device driver + development</entry> + </row> + + <row> + <entry>&a.www.name;</entry> + <entry>Maintainers of <ulink url="&url.base;/index.html">www.FreeBSD.org</ulink></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para><emphasis>Digest lists:</emphasis> All of the above lists + are available in a digest format. Once subscribed to a list, + you can change your digest options in your account options + section.</para> + + <para><emphasis>CVS & SVN lists:</emphasis> The following lists + are for people interested in seeing the log messages for changes to + various areas of the source tree. They are + <emphasis>Read-Only</emphasis> lists and should not have mail sent to + them.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>List</entry> + <entry>Source area</entry> + <entry>Area Description (source for)</entry> + </row> + </thead> + + <tbody> + <row> + <entry>&a.cvsall.name;</entry> + <entry><filename>/usr/(CVSROOT|doc|ports)</filename></entry> + <entry>All changes to any place in the tree (superset of other CVS commit lists)</entry> + </row> + + <row> + <entry>&a.cvs-doc.name;</entry> + <entry><filename>/usr/(doc|www)</filename></entry> + <entry>All changes to the doc and www trees</entry> + </row> + + <row> + <entry>&a.cvs-ports.name;</entry> + <entry><filename>/usr/ports</filename></entry> + <entry>All changes to the ports tree</entry> + </row> + + <row> + <entry>&a.cvs-projects.name;</entry> + <entry><filename>/usr/projects</filename></entry> + <entry>All changes to the projects tree</entry> + </row> + + <row> + <entry>&a.cvs-src.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the src tree (generated by the svn-to-cvs + importer commits)</entry> + </row> + + <row> + <entry>&a.svn-src-all.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the Subversion repository (except + for <filename>user</filename> + and <filename>projects</filename>)</entry> + </row> + + <row> + <entry>&a.svn-src-head.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the <quote>head</quote> branch of + the Subversion repository (the &os;-CURRENT + branch)</entry> + </row> + + <row> + <entry>&a.svn-src-projects.name;</entry> + <entry><filename>/usr/projects</filename></entry> + <entry>All changes to the <filename>projects</filename> + area of the src Subversion repository</entry> + </row> + + <row> + <entry>&a.svn-src-release.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the <filename>releases</filename> + area of the src Subversion repository</entry> + </row> + + <row> + <entry>&a.svn-src-releng.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the <filename>releng</filename> + branches of the src Subversion repository (the + security / release engineering branches)</entry> + </row> + + <row> + <entry>&a.svn-src-stable.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the all stable branches of the src + Subversion repository</entry> + </row> + + <row> + <entry>&a.svn-src-stable-6.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the <filename>stable/6</filename> + branch of the src Subversion repository</entry> + </row> + + <row> + <entry>&a.svn-src-stable-7.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the <filename>stable/7</filename> + branch of the src Subversion repository</entry> + </row> + + <row> + <entry>&a.svn-src-stable-8.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the <filename>stable/8</filename> + branch of the src Subversion repository</entry> + </row> + + <row> + <entry>&a.svn-src-stable-9.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the <filename>stable/9</filename> + branch of the src Subversion repository</entry> + </row> + + <row> + <entry>&a.svn-src-stable-other.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the + older <filename>stable</filename> branches of the src + Subversion repository</entry> + </row> + + <row> + <entry>&a.svn-src-svnadmin.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the administrative scripts, hooks, + and other configuration data of the src Subversion + repository</entry> + </row> + + <row> + <entry>&a.svn-src-user.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the + experimental <filename>user</filename> area of the src + Subversion repository</entry> + </row> + + <row> + <entry>&a.svn-src-vendor.name;</entry> + <entry><filename>/usr/src</filename></entry> + <entry>All changes to the vendor work area of the src + Subversion repository</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + + <sect2 id="eresources-subscribe"> + <title>How to Subscribe</title> + + <para>To subscribe to a list, click on the list name above or + go to &a.mailman.lists.link; + and click on the list that you are interested in. The list + page should contain all of the necessary subscription + instructions.</para> + + <para>To actually post to a given list, send mail to + <email><replaceable>listname</replaceable>@FreeBSD.org</email>. It will then + be redistributed to mailing list members world-wide.</para> + + <para>To unsubscribe yourself from a list, click on the URL + found at the bottom of every email received from the list. It + is also possible to send an email to + <email><replaceable>listname</replaceable>-unsubscribe@FreeBSD.org</email> to unsubscribe + yourself.</para> + + <para>Again, we would like to request that you keep discussion in the + technical mailing lists on a technical track. If you are only + interested in important announcements then it is suggested that + you join the &a.announce;, which is intended only for infrequent + traffic.</para> + </sect2> + + <sect2 id="eresources-charters"> + <title>List Charters</title> + + <para><emphasis>All</emphasis> FreeBSD mailing lists have certain basic + rules which must be adhered to by anyone using them. Failure to comply + with these guidelines will result in two (2) written warnings from the + FreeBSD Postmaster <email>postmaster@FreeBSD.org</email>, after which, + on a third offense, the poster will removed from all FreeBSD mailing + lists and filtered from further posting to them. We regret that such + rules and measures are necessary at all, but today's Internet is a + pretty harsh environment, it would seem, and many fail to appreciate + just how fragile some of its mechanisms are.</para> + + <para>Rules of the road:</para> + + <itemizedlist> + <listitem> + <para>The topic of any posting should adhere to the basic charter of + the list it is posted to, e.g., if the list is about technical + issues then your posting should contain technical discussion. + Ongoing irrelevant chatter or flaming only detracts from the value + of the mailing list for everyone on it and will not be tolerated. + For free-form discussion on no particular topic, the &a.chat; + is freely available and should be used instead.</para> + </listitem> + + <listitem> + <para>No posting should be made to more than 2 mailing lists, and + only to 2 when a clear and obvious need to post to both lists + exists. For most lists, there is already a great deal of + subscriber overlap and except for the most esoteric mixes (say + <quote>-stable & -scsi</quote>), there really is no reason to post to more + than one list at a time. If a message is sent to you in such a + way that multiple mailing lists appear on the + <literal>Cc</literal> line then the <literal>Cc</literal> + line should also be trimmed before sending it out again. + <emphasis>You are still responsible for your + own cross-postings, no matter who the originator might have + been.</emphasis></para> + </listitem> + + <listitem> + <para>Personal attacks and profanity (in the context of an argument) + are not allowed, and that includes users and developers alike. + Gross breaches of netiquette, like excerpting or reposting private + mail when permission to do so was not and would not be + forthcoming, are frowned upon but not specifically enforced. + <emphasis>However</emphasis>, there are also very few cases where + such content would fit within the charter of a list and it would + therefore probably rate a warning (or ban) on that basis + alone.</para> + </listitem> + + <listitem> + <para>Advertising of non-FreeBSD related products or services is + strictly prohibited and will result in an immediate ban if it is + clear that the offender is advertising by spam.</para> + </listitem> + </itemizedlist> + + <para><emphasis>Individual list charters:</emphasis></para> + + <variablelist> + + <varlistentry> + <term>&a.acpi.name;</term> + + <listitem> + <para><emphasis>ACPI and power management + development</emphasis></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.afs.name;</term> + + <listitem> + <para><emphasis>Andrew File System</emphasis></para> + + <para>This list is for discussion on porting and using AFS from + CMU/Transarc</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.announce.name;</term> + + <listitem> + <para><emphasis>Important events / milestones</emphasis></para> + + <para>This is the mailing list for people interested only in + occasional announcements of significant FreeBSD events. This + includes announcements about snapshots and other releases. It + contains announcements of new FreeBSD capabilities. It may + contain calls for volunteers etc. This is a low volume, strictly + moderated mailing list.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.arch.name;</term> + + <listitem> + <para><emphasis>Architecture and design + discussions</emphasis></para> + + <para>This list is for discussion of the FreeBSD + architecture. Messages will mostly be kept strictly + technical in nature. Examples of suitable topics + are:</para> + + <itemizedlist> + <listitem> + <para>How to re-vamp the build system to have several + customized builds running at the same time.</para> + </listitem> + + <listitem> + <para>What needs to be fixed with VFS to make Heidemann layers + work.</para> + </listitem> + + <listitem> + <para>How do we change the device driver interface to be able + to use the same drivers cleanly on many buses and + architectures.</para> + </listitem> + + <listitem> + <para>How to write a network driver.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.binup.name;</term> + + <listitem> + <para><emphasis>FreeBSD Binary Update Project</emphasis></para> + + <para>This list exists to provide discussion for the binary + update system, or <application>binup</application>. + Design issues, implementation details, + patches, bug reports, status reports, feature requests, commit + logs, and all other things related to + <application>binup</application> are fair game.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.bluetooth.name;</term> + + <listitem> + <para><emphasis>&bluetooth; in FreeBSD</emphasis></para> + + <para>This is the forum where FreeBSD's &bluetooth; users + congregate. Design issues, implementation details, + patches, bug reports, status reports, feature requests, + and all matters related to &bluetooth; are fair + game.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.bugbusters.name;</term> + + <listitem> + <para><emphasis>Coordination of the Problem Report handling effort</emphasis></para> + + <para>The purpose of this list is to serve as a coordination and + discussion forum for the Bugmeister, his Bugbusters, and any other + parties who have a genuine interest in the PR database. This list + is not for discussions about specific bugs, patches or PRs.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.bugs.name;</term> + + <listitem> + <para><emphasis>Bug reports</emphasis></para> + + <para>This is the mailing list for reporting bugs in FreeBSD. + Whenever possible, bugs should be submitted using the + &man.send-pr.1; + command or the <ulink + url="&url.base;/send-pr.html">WEB + interface</ulink> to it.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.chat.name;</term> + + <listitem> + <para><emphasis>Non technical items related to the FreeBSD + community</emphasis></para> + + <para>This list contains the overflow from the other lists about + non-technical, social information. It includes discussion about + whether Jordan looks like a toon ferret or not, whether or not + to type in capitals, who is drinking too much coffee, where the + best beer is brewed, who is brewing beer in their basement, and + so on. Occasional announcements of important events (such as + upcoming parties, weddings, births, new jobs, etc) can be made + to the technical lists, but the follow ups should be directed to + this -chat list.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.chromium.name;</term> + + <listitem> + <para><emphasis>FreeBSD-specific Chromium issues</emphasis></para> + + <para>This is a list for the discussion of Chromium + support for FreeBSD. This is a technical list to discuss + development and installation of Chromium.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.core.name;</term> + + <listitem> + <para><emphasis>FreeBSD core team</emphasis></para> + + <para>This is an internal mailing list for use by the core + members. Messages can be sent to it when a serious + FreeBSD-related matter requires arbitration or high-level + scrutiny.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.current.name;</term> + + <listitem> + <para><emphasis>Discussions about the use of + &os.current;</emphasis></para> + + <para>This is the mailing list for users of &os.current;. It + includes warnings about new features coming out in -CURRENT that + will affect the users, and instructions on steps that must be + taken to remain -CURRENT. Anyone running <quote>CURRENT</quote> + must subscribe to this list. This is a technical mailing list + for which strictly technical content is expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.cvsweb.name;</term> + + <listitem> + <para><emphasis>FreeBSD CVSweb Project</emphasis></para> + + <para>Technical discussions about use, development and maintenance + of FreeBSD-CVSweb.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.desktop.name;</term> + + <listitem> + <para><emphasis>Using and improving &os; on the desktop</emphasis></para> + + <para>This is a forum for discussion of &os; on the + desktop. It is primarily a place for desktop porters + and users to discuss issues and improve &os;'s desktop + support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.doc.name;</term> + + <listitem> + <para><emphasis>Documentation project</emphasis></para> + + <para>This mailing list is for the discussion of issues and + projects related to the creation of documentation for FreeBSD. + The members of this mailing list are collectively referred to as + <quote>The FreeBSD Documentation Project</quote>. It is an open + list; feel free to join and contribute!</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.drivers.name;</term> + + <listitem> + <para><emphasis>Writing device drivers for &os;</emphasis></para> + + <para>This is a forum for technical discussions related to + device drivers on &os;. It is primarily a place + for device driver writers to ask questions about + how to write device drivers using the APIs in the + &os; kernel.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.eclipse.name;</term> + + <listitem> + <para><emphasis>&os; users of Eclipse IDE, tools, rich + client applications and ports.</emphasis></para> + + <para>The intention of this list is to provide mutual + support for everything to do with choosing, installing, + using, developing and maintaining the Eclipse IDE, + tools, rich client applications on the &os; platform and + assisting with the porting of Eclipse IDE and plugins to + the &os; environment.</para> + + <para>The intention is also to facilitate exchange of + information between the Eclipse community and the &os; + community to the mutual benefit of both.</para> + + <para>Although this list is focused primarily on the needs + of Eclipse users it will also provide a forum for those + who would like to develop &os; specific applications + using the Eclipse framework. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.embedded.name;</term> + + <listitem> + <para><emphasis>Using FreeBSD in embedded + applications</emphasis></para> + + <para>This list discusses topics related to using FreeBSD in + embedded systems. This is a technical mailing list for which + strictly technical content is expected. For the purpose of + this list we define embedded systems as those computing + devices which are not desktops and which usually serve a + single purpose as opposed to being general computing + environments. Examples include, but are not limited to, + all kinds of phone handsets, network equipment such as + routers, switches and PBXs, remote measuring equipment, + PDAs, Point Of Sale systems, and so on.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.emulation.name;</term> + + <listitem> + <para><emphasis>Emulation of other systems such as + Linux/&ms-dos;/&windows;</emphasis></para> + + <para>This is a forum for technical discussions related to + running programs written for other operating systems on &os;. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.eol.name;</term> + + <listitem> + <para><emphasis>Peer support of FreeBSD-related software that is + no longer supported by the FreeBSD project.</emphasis></para> + + <para>This list is for those interested in providing or making use + of peer support of FreeBSD-related software for which the + FreeBSD project no longer provides official support (e.g., in + the form of security advisories and patches).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.firewire.name;</term> + + <listitem> + <para><emphasis>&firewire; (iLink, IEEE 1394)</emphasis></para> + + <para>This is a mailing list for discussion of the design + and implementation of a &firewire; (aka IEEE 1394 aka + iLink) subsystem for FreeBSD. Relevant topics + specifically include the standards, bus devices and + their protocols, adapter boards/cards/chips sets, and + the architecture and implementation of code for their + proper support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.fs.name;</term> + + <listitem> + <para><emphasis>File systems</emphasis></para> + + <para>Discussions concerning FreeBSD file systems. This is a + technical mailing list for which strictly technical content is + expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.gecko.name;</term> + + <listitem> + <para><emphasis>Gecko Rendering Engine</emphasis></para> + + <para>This is a forum about <application>Gecko</application> + applications using &os;.</para> + + <para>Discussion centers around Gecko Ports applications, + their installation, their development and their support + within &os;.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.geom.name;</term> + + <listitem> + <para><emphasis>GEOM</emphasis></para> + + <para>Discussions specific to GEOM and related implementations. + This is a technical mailing list for which strictly technical + content is expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.gnome.name;</term> + + <listitem> + <para><emphasis>GNOME</emphasis></para> + + <para>Discussions concerning The <application>GNOME</application> Desktop Environment for + FreeBSD systems. This is a technical mailing list for + which strictly technical content is expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.ipfw.name;</term> + + <listitem> + <para><emphasis>IP Firewall</emphasis></para> + + <para>This is the forum for technical discussions concerning the + redesign of the IP firewall code in FreeBSD. This is a + technical mailing list for which strictly technical content is + expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.ia64.name;</term> + + <listitem> + <para><emphasis>Porting FreeBSD to IA64</emphasis></para> + + <para>This is a technical mailing list for individuals + actively working on porting FreeBSD to the IA-64 platform + from &intel;, to bring up problems or discuss alternative + solutions. Individuals interested in following the + technical discussion are also welcome.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.isdn.name;</term> + + <listitem> + <para><emphasis>ISDN Communications</emphasis></para> + + <para>This is the mailing list for people discussing the + development of ISDN support for FreeBSD.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.java.name;</term> + + <listitem> + <para><emphasis>&java; Development</emphasis></para> + + <para>This is the mailing list for people discussing the + development of significant &java; applications for FreeBSD and the + porting and maintenance of &jdk;s.</para> + </listitem> + </varlistentry> + + <varlistentry id="eresources-charters-jobs"> + <term>&a.jobs.name;</term> + + <listitem> + <para><emphasis>Jobs offered and sought</emphasis></para> + + <para>This is a forum for posting employment notices and + resumes specifically related to &os;, e.g., if you are + seeking &os;-related employment or have a job involving + &os; to advertise then this is the right place. This is + <emphasis>not</emphasis> a mailing list for general + employment issues since adequate forums for that + already exist elsewhere.</para> + + <para>Note that this list, like other <hostid role="domainname">FreeBSD.org</hostid> mailing + lists, is distributed worldwide. Thus, you need to be + clear about location and the extent to which + telecommuting or assistance with relocation is + available.</para> + + <para>Email should use open formats only — + preferably plain text, but basic Portable Document + Format (<acronym>PDF</acronym>), HTML, and a few others + are acceptable to many readers. Closed formats such as + µsoft; Word (<filename>.doc</filename>) will be + rejected by the mailing list server.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.kde.name;</term> + + <listitem> + <para><emphasis>KDE</emphasis></para> + + <para>Discussions concerning <application>KDE</application> on + FreeBSD systems. This is a technical mailing list for + which strictly technical content is expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.hackers.name;</term> + + <listitem> + <para><emphasis>Technical discussions</emphasis></para> + + <para>This is a forum for technical discussions related to + FreeBSD. This is the primary technical mailing list. It is for + individuals actively working on FreeBSD, to bring up problems or + discuss alternative solutions. Individuals interested in + following the technical discussion are also welcome. This is a + technical mailing list for which strictly technical content is + expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.hardware.name;</term> + + <listitem> + <para><emphasis>General discussion of FreeBSD + hardware</emphasis></para> + + <para>General discussion about the types of hardware that FreeBSD + runs on, various problems and suggestions concerning what to buy + or avoid.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.hubs.name;</term> + + <listitem> + <para><emphasis>Mirror sites</emphasis></para> + + <para>Announcements and discussion for people who run FreeBSD + mirror sites.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.isp.name;</term> + + <listitem> + <para><emphasis>Issues for Internet Service + Providers</emphasis></para> + + <para>This mailing list is for discussing topics relevant to + Internet Service Providers (ISPs) using FreeBSD. This is a + technical mailing list for which strictly technical content is + expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.mono.name;</term> + + <listitem> + <para><emphasis>Mono and C# applications on + FreeBSD</emphasis></para> + + <para>This is a list for discussions related to the Mono + development framework on &os;. This is a technical + mailing list. It is for individuals actively working on + porting Mono or C# applications to &os;, to bring up + problems or discuss alternative solutions. Individuals + interested in following the technical discussion are also + welcome.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.office.name;</term> + + <listitem> + <para><emphasis>Office applications on &os;</emphasis></para> + + <para>Discussion centers around office applications, + their installation, their development and their support + within &os;.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.performance.name;</term> + + <listitem> + <para><emphasis>Discussions about tuning or speeding up FreeBSD</emphasis></para> + + <para>This mailing list exists to provide a place for + hackers, administrators, and/or concerned parties to + discuss performance related topics pertaining to + FreeBSD. Acceptable topics includes talking about + FreeBSD installations that are either under high load, + are experiencing performance problems, or are pushing + the limits of FreeBSD. Concerned parties that are + willing to work toward improving the performance of + FreeBSD are highly encouraged to subscribe to this list. + This is a highly technical list ideally suited for + experienced FreeBSD users, hackers, or administrators + interested in keeping FreeBSD fast, robust, and + scalable. This list is not a question-and-answer list + that replaces reading through documentation, but it is a + place to make contributions or inquire about unanswered + performance related topics.</para> + + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.pf.name;</term> + + <listitem> + <para><emphasis>Discussion and questions about the packet filter + firewall system</emphasis></para> + + <para>Discussion concerning the packet filter (pf) firewall + system in terms of FreeBSD. Technical discussion and user + questions are both welcome. This list is also a place to + discuss the ALTQ QoS framework.</para> + + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.platforms.name;</term> + + <listitem> + <para><emphasis>Porting to Non &intel; platforms</emphasis></para> + + <para>Cross-platform FreeBSD issues, general discussion and + proposals for non &intel; FreeBSD ports. This is a technical + mailing list for which strictly technical content is + expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.ports.name;</term> + + <listitem> + <para><emphasis>Discussion of + <quote>ports</quote></emphasis></para> + + <para>Discussions concerning FreeBSD's <quote>ports + collection</quote> (<filename>/usr/ports</filename>), ports infrastructure, and + general ports coordination efforts. This is a technical mailing list + for which strictly technical content is expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.ports-announce.name;</term> + + <listitem> + <para><emphasis>Important news and instructions about the + &os; <quote>Ports Collection</quote></emphasis></para> + + <para>Important news for developers, porters, and users of + the <quote>Ports Collection</quote> (<filename + role="directory">/usr/ports</filename>), including + architecture/infrastructure changes, new capabilities, + critical upgrade instructions, and release engineering + information. This is a low-volume mailing list, intended + for announcements.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.ports-bugs.name;</term> + + <listitem> + <para><emphasis>Discussion of + <quote>ports</quote> bugs</emphasis></para> + + <para>Discussions concerning problem reports for FreeBSD's <quote>ports + collection</quote> (<filename>/usr/ports</filename>), proposed + ports, or modifications to ports. This is a technical mailing list + for which strictly technical content is expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.proliant.name;</term> + + <listitem> + <para><emphasis>Technical discussion of FreeBSD on HP + ProLiant server platforms</emphasis></para> + + <para>This mailing list is to be used for the technical + discussion of the usage of FreeBSD on HP ProLiant servers, + including the discussion of ProLiant-specific drivers, + management software, configuration tools, and BIOS + updates. As such, this is the primary place to discuss + the hpasmd, hpasmcli, and hpacucli modules.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.python.name;</term> + + <listitem> + <para><emphasis>Python on FreeBSD</emphasis></para> + + <para>This is a list for discussions related to improving Python-support + on FreeBSD. This is a technical mailing list. It is for individuals + working on porting Python, its 3rd party modules and <application>Zope</application> stuff to + FreeBSD. Individuals interested in following the technical discussion + are also welcome.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.questions.name;</term> + + <listitem> + <para><emphasis>User questions</emphasis></para> + + <para>This is the mailing list for questions about FreeBSD. You + should not send <quote>how to</quote> questions to the technical + lists unless you consider the question to be pretty + technical.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.ruby.name;</term> + + <listitem> + <para><emphasis>FreeBSD-specific Ruby + discussions</emphasis></para> + + <para>This is a list for discussions related to the Ruby + support on FreeBSD. This is a technical mailing + list. It is for individuals working on Ruby ports, + 3rd party libraries and frameworks.</para> + + <para>Individuals interested in the technical discussion + are also welcome.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.scsi.name;</term> + + <listitem> + <para><emphasis>SCSI subsystem</emphasis></para> + + <para>This is the mailing list for people working on the SCSI + subsystem for FreeBSD. This is a technical mailing list for + which strictly technical content is expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.security.name;</term> + + <listitem> + <para><emphasis>Security issues</emphasis></para> + + <para>FreeBSD computer security issues (DES, Kerberos, known + security holes and fixes, etc). This is a technical mailing + list for which strictly technical discussion is expected. Note + that this is not a question-and-answer list, but that + contributions (BOTH question AND answer) to the FAQ are + welcome.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.security-notifications.name;</term> + + <listitem> + <para><emphasis>Security Notifications</emphasis></para> + + <para>Notifications of FreeBSD security problems and + fixes. This is not a discussion list. The discussion + list is FreeBSD-security.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.small.name;</term> + + <listitem> + <para><emphasis>Using FreeBSD in embedded + applications</emphasis></para> + + <para>This list discusses topics related to unusually small and + embedded FreeBSD installations. This is a technical mailing + list for which strictly technical content is expected.</para> + + <note> + <para>This list has been obsoleted by &a.embedded.name;.</para> + </note> + + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.stable.name;</term> + + <listitem> + <para><emphasis>Discussions about the use of + &os.stable;</emphasis></para> + + <para>This is the mailing list for users of &os.stable;. It + includes warnings about new features coming out in -STABLE that + will affect the users, and instructions on steps that must be + taken to remain -STABLE. Anyone running <quote>STABLE</quote> + should subscribe to this list. This is a technical mailing list + for which strictly technical content is expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.standards.name;</term> + + <listitem> + <para><emphasis>C99 & POSIX Conformance</emphasis></para> + + <para>This is a forum for technical discussions related to + FreeBSD Conformance to the C99 and the POSIX standards.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.toolchain.name;</term> + + <listitem> + <para><emphasis>Maintenance of FreeBSD's integrated + toolchain</emphasis></para> + + <para>This is the mailing list for discussions related to + the maintenance of the toolchain shipped with &os;. This + could include the state of Clang and GCC, but also pieces + of software such as assemblers, linkers and + debuggers.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.usb.name;</term> + + <listitem> + <para><emphasis>Discussing &os; support for + USB</emphasis></para> + + <para>This is a mailing list for technical discussions + related to &os; support for USB.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.usergroups.name;</term> + + <listitem> + <para><emphasis>User Group Coordination List</emphasis></para> + + <para>This is the mailing list for the coordinators from each of + the local area Users Groups to discuss matters with each other + and a designated individual from the Core Team. This mail list + should be limited to meeting synopsis and coordination of + projects that span User Groups.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.vendors.name;</term> + + <listitem> + <para><emphasis>Vendors</emphasis></para> + + <para>Coordination discussions between The FreeBSD Project and + Vendors of software and hardware for FreeBSD.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.virtualization.name;</term> + + <listitem> + <para><emphasis>Discussion of various virtualization + techniques supported by &os;</emphasis></para> + + <para>A list to discuss the various virtualization + techniques supported by &os;. On one hand the focus will + be on the implementation of the basic functionality as + well as adding new features. On the other hand users + will have a forum to ask for help in case of problems + or to discuss their use cases.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.wip-status.name;</term> + + <listitem> + <para><emphasis>&os; Work-In-Progress Status</emphasis></para> + + <para>This mailing list can be used to announce creation + and progress of your &os; related work. Messages + will be moderated. It is suggested to send the message + "To:" a more topical &os; list and only "BCC:" + this list. This way your WIP can also be discussed on + the topical list, as no discussion is allowed on this + list.</para> + + <para>Look inside the archives for examples of suitable + messages.</para> + + <para>An editorial digest of the messages to this list + might be posted to the &os; website every few month + as part of the Status Reports + <footnote><para><ulink url="http://www.freebsd.org/news/status/"></ulink></para></footnote>. + You can find more + examples and past reports there, too.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.wireless.name;</term> + + <listitem> + <para><emphasis>Discussions of 802.11 stack, tools device + driver development</emphasis></para> + + <para>The FreeBSD-wireless list focuses on 802.11 stack + (sys/net80211), device driver and tools development. + This includes bugs, new features and maintenance.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.xen.name;</term> + + <listitem> + <para><emphasis>Discussion of the &os; port to &xen; + — implementation and usage</emphasis></para> + + <para>A list that focuses on the &os; &xen; port. The + anticipated traffic level is small enough that it is + intended as a forum for both technical discussions of + the implementation and design details as well as + administrative deployment issues.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.xfce.name;</term> + + <listitem> + <para><emphasis>XFCE</emphasis></para> + + <para>This is a forum for discussions related to bring the + <application>XFCE</application> environment to &os;. This + is a technical mailing list. It is for individuals actively + working on porting <application>XFCE</application> to &os;, + to bring up problems or discuss alternative solutions. + Individuals interested in following the technical discussion + are also welcome.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&a.zope.name;</term> + + <listitem> + <para><emphasis>Zope</emphasis></para> + + <para>This is a forum for discussions related to bring the + <application>Zope</application> environment to &os;. This + is a technical mailing list. It is for individuals actively + working on porting <application>Zope</application> to &os;, + to bring up problems or discuss alternative solutions. + Individuals interested in following the technical discussion + are also welcome.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + <sect2 id="eresources-mailfiltering"> + <title>Filtering on the Mailing Lists</title> + + <para>The &os; mailing lists are filtered in multiple ways to + avoid the distribution of spam, viruses, and other unwanted emails. + The filtering actions described in this section do not include all + those used to protect the mailing lists.</para> + + <para>Only certain types of attachments are allowed on the + mailing lists. All attachments with a MIME content type not + found in the list below will be stripped before an email is + distributed on the mailing lists.</para> + + <itemizedlist> + <listitem> + <para>application/octet-stream</para> + </listitem> + + <listitem> + <para>application/pdf</para> + </listitem> + + <listitem> + <para>application/pgp-signature</para> + </listitem> + + <listitem> + <para>application/x-pkcs7-signature</para> + </listitem> + + <listitem> + <para>message/rfc822</para> + </listitem> + + <listitem> + <para>multipart/alternative</para> + </listitem> + + <listitem> + <para>multipart/related</para> + </listitem> + + <listitem> + <para>multipart/signed</para> + </listitem> + + <listitem> + <para>text/html</para> + </listitem> + + <listitem> + <para>text/plain</para> + </listitem> + + <listitem> + <para>text/x-diff</para> + </listitem> + + <listitem> + <para>text/x-patch</para> + </listitem> + </itemizedlist> + + <note> + <para>Some of the mailing lists might allow attachments of + other MIME content types, but the above list should be + applicable for most of the mailing lists.</para> + </note> + + <para>If an email contains both an HTML and a plain text version, + the HTML version will be removed. If an email contains only an + HTML version, it will be converted to plain text.</para> + </sect2> + </sect1> + + <sect1 id="eresources-news"> + <title>Usenet Newsgroups</title> + + <para>In addition to two FreeBSD specific newsgroups, there are many + others in which FreeBSD is discussed or are otherwise relevant to + FreeBSD users. <ulink + url="http://minnie.tuhs.org/BSD-info/bsdnews_search.html">Keyword + searchable archives</ulink> are available for some of these newsgroups + from courtesy of Warren Toomey <email>wkt@cs.adfa.edu.au</email>.</para> + + <sect2> + <title>BSD Specific Newsgroups</title> + + <itemizedlist> + <listitem> + <para><ulink + url="news:comp.unix.bsd.freebsd.announce">comp.unix.bsd.freebsd.announce</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:de.comp.os.unix.bsd">de.comp.os.unix.bsd</ulink> (German)</para> + </listitem> + + <listitem> + <para><ulink + url="news:fr.comp.os.bsd">fr.comp.os.bsd</ulink> (French)</para> + </listitem> + + <listitem> + <para><ulink + url="news:it.comp.os.freebsd">it.comp.os.freebsd</ulink> (Italian)</para> + </listitem> + + <listitem> + <para><ulink + url="news:tw.bbs.comp.386bsd">tw.bbs.comp.386bsd</ulink> (Traditional Chinese)</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Other &unix; Newsgroups of Interest</title> + + <itemizedlist> + <listitem> + <para><ulink url="news:comp.unix">comp.unix</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.unix.questions">comp.unix.questions</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.unix.admin">comp.unix.admin</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.unix.programmer">comp.unix.programmer</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.unix.shell">comp.unix.shell</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.unix.user-friendly">comp.unix.user-friendly</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.security.unix">comp.security.unix</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.sources.unix">comp.sources.unix</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.unix.advocacy">comp.unix.advocacy</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.unix.misc">comp.unix.misc</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.bugs.4bsd">comp.bugs.4bsd</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.bugs.4bsd.ucb-fixes">comp.bugs.4bsd.ucb-fixes</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.unix.bsd">comp.unix.bsd</ulink></para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>X Window System</title> + + <itemizedlist> + <listitem> + <para><ulink + url="news:comp.windows.x.i386unix">comp.windows.x.i386unix</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.windows.x">comp.windows.x</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.windows.x.apps">comp.windows.x.apps</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.windows.x.announce">comp.windows.x.announce</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.windows.x.intrinsics">comp.windows.x.intrinsics</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.windows.x.motif">comp.windows.x.motif</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.windows.x.pex">comp.windows.x.pex</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="news:comp.emulators.ms-windows.wine">comp.emulators.ms-windows.wine</ulink></para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="eresources-web"> + <title>World Wide Web Servers</title> + + <sect2 id="eresources-web-social"> + <title>Forums, Blogs, and Social Networks</title> + + <itemizedlist> + <listitem><para><ulink url="http://forums.freebsd.org/">The + FreeBSD Forums</ulink> provide a web based discussion forum + for FreeBSD questions and technical + discussion.</para></listitem> + + <listitem><para><ulink + url="http://planet.freebsdish.org/">Planet FreeBSD</ulink> + offers an aggregation feed of dozens of blogs written by + FreeBSD developers. Many developers use this to post quick + notes about what they are working on, new patches, and other + works in progress.</para></listitem> + + <listitem><para>The <ulink + url="http://www.youtube.com/bsdconferences">BSDConferences + YouTube Channel</ulink> provides a collection of high + quality videos from BSD Conferences around the world. This + is a great way to watch key developers give presentations + about new work in FreeBSD.</para></listitem> + </itemizedlist> + </sect2> + + <sect2 id="eresources-web-mirrors"> + <title>Official Mirrors</title> + &chap.eresources.www.inc; + </sect2> + </sect1> + + <sect1 id="eresources-email"> + <title>Email Addresses</title> + + <para>The following user groups provide FreeBSD related email addresses + for their members. The listed administrator reserves the right to + revoke the address if it is abused in any way.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="4"> + <thead> + <row> + <entry>Domain</entry> + <entry>Facilities</entry> + <entry>User Group</entry> + <entry>Administrator</entry> + </row> + </thead> + + <tbody> + <row> + <entry>ukug.uk.FreeBSD.org</entry> + <entry>Forwarding only</entry> + <entry><email>ukfreebsd@uk.FreeBSD.org</email></entry> + <entry>Lee Johnston + <email>lee@uk.FreeBSD.org</email></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> +</appendix> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../appendix.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "appendix") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/filesystems/Makefile b/en_US.ISO8859-1/books/handbook/filesystems/Makefile new file mode 100644 index 0000000000..499d815d22 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/filesystems/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= filesystems/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml b/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml new file mode 100644 index 0000000000..9d10739d79 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/filesystems/chapter.sgml @@ -0,0 +1,884 @@ +<!-- + The FreeBSD Documentation Project + $FreeBSD$ +--> + +<chapter id="filesystems"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>File Systems Support</title> + + <sect1 id="filesystems-synopsis"> + <title>Synopsis</title> + + <indexterm><primary>File Systems</primary></indexterm> + <indexterm> + <primary>File Systems Support</primary> + <see>File Systems</see> + </indexterm> + + <para>File systems are an integral part of any operating system. + They allow for users to upload and store files, provide access + to data, and of course, make hard drives useful. Different + operating systems usually have one major aspect in common, that + is their native file system. On &os; this file system is known + as the Fast File System or <acronym>FFS</acronym> which is built + on the original Unix™ File System, also known as + <acronym>UFS</acronym>. This is the native file system on &os; + which is placed on hard disks for access to data.</para> + + <para>&os; also supports a multitude of different file systems to + provide support for accessing data from other operating systems + locally, i.e., data stored on locally attached + <acronym>USB</acronym> storage devices, flash drives, and hard + disks. There is also support for some non-native file systems. + These are file systems developed on other + operating systems, like the &linux; Extended File System + (<acronym>EXT</acronym>), and the &sun; Z File System + (<acronym>ZFS</acronym>).</para> + + <para>There are different levels of support for the various file + systems in &os;. Some will require a kernel module to be loaded, + others may require a toolset to be installed. This chapter is + designed to help users of &os; access other file systems on their + systems, starting with the &sun; Z file + system.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>The difference between native and supported file systems.</para> + </listitem> + + <listitem> + <para>What file systems are supported by &os;.</para> + </listitem> + + <listitem> + <para>How to enable, configure, access and make use of + non-native file systems.</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>Feel comfortable installing third party software + in &os; (<xref linkend="ports">).</para> + </listitem> + + <listitem> + <para>Have some familiarity with disks, storage and + device names in &os; (<xref linkend="disks">).</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="filesystems-zfs"> + <title>The Z File System (ZFS)</title> + + <para>The Z file system, developed by &sun;, is a new + technology designed to use a pooled storage method. This means + that space is only used as it is needed for data storage. It + has also been designed for maximum data integrity, supporting + data snapshots, multiple copies, and data checksums. A new + data replication model, known as <acronym>RAID</acronym>-Z has + been added. The <acronym>RAID</acronym>-Z model is similar + to <acronym>RAID</acronym>5 but is designed to prevent data + write corruption.</para> + + <sect2> + <title>ZFS Tuning</title> + + <para>The <acronym>ZFS</acronym> subsystem utilizes much of + the system resources, so some tuning may be required to provide + maximum efficiency during every-day use. As an experimental + feature in &os; this may change in the near future; however, + at this time, the following steps are recommended.</para> + + <sect3> + <title>Memory</title> + + <para>The total system memory should be at least one gigabyte, + with two gigabytes or more recommended. In all of the + examples here, the system has one gigabyte of memory with + several other tuning mechanisms in place.</para> + + <para>Some people have had luck using fewer than one gigabyte + of memory, but with such a limited amount of physical memory, + when the system is under heavy load, it is very plausible + that &os; will panic due to memory exhaustion.</para> + </sect3> + + <sect3> + <title>Kernel Configuration</title> + + <para>It is recommended that unused drivers and options + be removed from the kernel configuration file. Since most + devices are available as modules, they may be loaded + using the <filename>/boot/loader.conf</filename> file.</para> + + <para>Users of the &i386; architecture should add the following + option to their kernel configuration file, rebuild their + kernel, and reboot:</para> + + <programlisting>options KVA_PAGES=512</programlisting> + + <para>This option will expand the kernel address space, thus + allowing the <varname>vm.kvm_size</varname> tunable to be + pushed beyond the currently imposed limit of 1 GB + (2 GB for <acronym>PAE</acronym>). To find the most + suitable value for this option, divide the desired address + space in megabytes by four (4). In this case, it is + <literal>512</literal> for 2 GB.</para> + </sect3> + + <sect3> + <title>Loader Tunables</title> + + <para>The <devicename>kmem</devicename> address space should be + increased on all &os; architectures. On the test system with + one gigabyte of physical memory, success was achieved with the + following options which should be placed in + the <filename>/boot/loader.conf</filename> file and the system + restarted:</para> + + <programlisting>vm.kmem_size="330M" +vm.kmem_size_max="330M" +vfs.zfs.arc_max="40M" +vfs.zfs.vdev.cache.size="5M"</programlisting> + + <para>For a more detailed list of recommendations for ZFS-related + tuning, see + <ulink url="http://wiki.freebsd.org/ZFSTuningGuide"></ulink>.</para> + </sect3> + </sect2> + + <sect2> + <title>Using <acronym>ZFS</acronym></title> + + <para>There is a start up mechanism that allows &os; to + mount <acronym>ZFS</acronym> pools during system + initialization. To set it, issue the following + commands:</para> + + <screen>&prompt.root; <userinput>echo 'zfs_enable="YES"' >> /etc/rc.conf</userinput> +&prompt.root; <userinput>/etc/rc.d/zfs start</userinput></screen> + + <para>The remainder of this document assumes three + <acronym>SCSI</acronym> disks are available, and their device names + are <devicename><replaceable>da0</replaceable></devicename>, + <devicename><replaceable>da1</replaceable></devicename> + and <devicename><replaceable>da2</replaceable></devicename>. + Users of <acronym>IDE</acronym> hardware may use the + <devicename><replaceable>ad</replaceable></devicename> + devices in place of <acronym>SCSI</acronym> hardware.</para> + + <sect3> + <title>Single Disk Pool</title> + + <para>To create a simple, non-redundant <acronym>ZFS</acronym> pool using a + single disk device, use the <command>zpool</command> command:</para> + + <screen>&prompt.root; <userinput>zpool create example /dev/da0</userinput></screen> + + <para>To view the new pool, review the output of the + <command>df</command>:</para> + + <screen>&prompt.root; <userinput>df</userinput> +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/ad0s1a 2026030 235230 1628718 13% / +devfs 1 1 0 100% /dev +/dev/ad0s1d 54098308 1032846 48737598 2% /usr +example 17547136 0 17547136 0% /example</screen> + + <para>This output clearly shows the <literal>example</literal> + pool has not only been created but + <emphasis>mounted</emphasis> as well. It is also accessible + just like a normal file system, files may be created on it + and users are able to browse it as in the + following example:</para> + + <screen>&prompt.root <userinput>cd /example</userinput> +&prompt.root; <userinput>ls</userinput> +&prompt.root; <userinput>touch testfile</userinput> +&prompt.root; <userinput>ls -al</userinput> +total 4 +drwxr-xr-x 2 root wheel 3 Aug 29 23:15 . +drwxr-xr-x 21 root wheel 512 Aug 29 23:12 .. +-rw-r--r-- 1 root wheel 0 Aug 29 23:15 testfile</screen> + + <para>Unfortunately this pool is not taking advantage of + any <acronym>ZFS</acronym> features. Create a file system + on this pool, and enable compression on it:</para> + + <screen>&prompt.root; <userinput>zfs create example/compressed</userinput> +&prompt.root; <userinput>zfs set compression=gzip example/compressed</userinput></screen> + + <para>The <literal>example/compressed</literal> is now a + <acronym>ZFS</acronym> compressed file system. Try copying + some large files to it by copying them to + <filename class="directory">/example/compressed</filename>.</para> + + <para>The compression may now be disabled with:</para> + + <screen>&prompt.root; <userinput>zfs set compression=off example/compressed</userinput></screen> + + <para>To unmount the file system, issue the following command + and then verify by using the <command>df</command> + utility:</para> + + <screen>&prompt.root; <userinput>zfs umount example/compressed</userinput> +&prompt.root; <userinput>df</userinput> +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/ad0s1a 2026030 235232 1628716 13% / +devfs 1 1 0 100% /dev +/dev/ad0s1d 54098308 1032864 48737580 2% /usr +example 17547008 0 17547008 0% /example</screen> + + <para>Re-mount the file system to make it accessible + again, and verify with <command>df</command>:</para> + + <screen>&prompt.root; <userinput>zfs mount example/compressed</userinput> +&prompt.root; <userinput>df</userinput> +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/ad0s1a 2026030 235234 1628714 13% / +devfs 1 1 0 100% /dev +/dev/ad0s1d 54098308 1032864 48737580 2% /usr +example 17547008 0 17547008 0% /example +example/compressed 17547008 0 17547008 0% /example/compressed</screen> + + <para>The pool and file system may also be observed by viewing + the output from <command>mount</command>:</para> + + <screen>&prompt.root; <userinput>mount</userinput> +/dev/ad0s1a on / (ufs, local) +devfs on /dev (devfs, local) +/dev/ad0s1d on /usr (ufs, local, soft-updates) +example on /example (zfs, local) +example/data on /example/data (zfs, local) +example/compressed on /example/compressed (zfs, local)</screen> + + <para>As observed, <acronym>ZFS</acronym> file systems, after + creation, may be used like ordinary file systems; however, + many other features are also available. In the following + example, a new file system, <literal>data</literal> is + created. Important files will be stored here, so the file + system is set to keep two copies of each data block:</para> + + <screen>&prompt.root; <userinput>zfs create example/data</userinput> +&prompt.root; <userinput>zfs set copies=2 example/data</userinput></screen> + + <para>It is now possible to see the data and space utilization + by issuing the <command>df</command> again:</para> + + <screen>&prompt.root; <userinput>df</userinput> +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/ad0s1a 2026030 235234 1628714 13% / +devfs 1 1 0 100% /dev +/dev/ad0s1d 54098308 1032864 48737580 2% /usr +example 17547008 0 17547008 0% /example +example/compressed 17547008 0 17547008 0% /example/compressed +example/data 17547008 0 17547008 0% /example/data</screen> + + <para>Notice that each file system on the pool has the same + amount of available space. This is the reason for using + the <command>df</command> through these examples, to show + that the file systems are using only the amount of space + they need and will all draw from the same pool. + The <acronym>ZFS</acronym> file system does away with concepts + such as volumes and partitions, and allows for several file + systems to occupy the same pool. Destroy the file systems, + and then destroy the pool as they are no longer + needed:</para> + + <screen>&prompt.root; <userinput>zfs destroy example/compressed</userinput> +&prompt.root; <userinput>zfs destroy example/data</userinput> +&prompt.root; <userinput>zpool destroy example</userinput></screen> + + <para>Disks go bad and fail, an unavoidable trait. When + this disk goes bad, the data will be lost. One method of + avoiding data loss due to a failed hard disk is to implement + a <acronym>RAID</acronym>. <acronym>ZFS</acronym> supports + this feature in its pool design which is covered in + the next section.</para> + </sect3> + + <sect3> + <title><acronym>ZFS</acronym> RAID-Z</title> + + <para>As previously noted, this section will assume that + three <acronym>SCSI</acronym> disks exist as devices + <devicename>da0</devicename>, <devicename>da1</devicename> + and <devicename>da2</devicename> (or <devicename>ad0</devicename> + and beyond in case IDE disks are being used). To create a + <acronym>RAID</acronym>-Z pool, issue the following + command:</para> + + <screen>&prompt.root; <userinput>zpool create storage raidz da0 da1 da2</userinput></screen> + + <note><para>&sun; recommends that the amount of devices used in a + <acronym>RAID</acronym>-Z configuration is between three and nine. If your needs + call for a single pool to consist of 10 disks or more, consider + breaking it up into smaller <acronym>RAID</acronym>-Z groups. If + you only have two disks and still require redundancy, consider using + a <acronym>ZFS</acronym> mirror instead. See the &man.zpool.8; + manual page for more details.</para></note> + + <para>The <literal>storage</literal> zpool should have been + created. This may be verified by using the &man.mount.8; and + &man.df.1; commands as before. More disk devices may have + been allocated by adding them to the end of the list above. + Make a new file system in the pool, called + <literal>home</literal> where user files will eventually be + placed:</para> + + <screen>&prompt.root; <userinput>zfs create storage/home</userinput></screen> + + <para>It is now possible to enable compression and keep extra + copies of the user's home directories and files. This may + be accomplished just as before using the following + commands:</para> + + <screen>&prompt.root; <userinput>zfs set copies=2 storage/home</userinput> +&prompt.root; <userinput>zfs set compression=gzip storage/home</userinput></screen> + + <para>To make this the new home directory for users, copy the + user data to this directory, and create the appropriate + symbolic links:</para> + + <screen>&prompt.root; <userinput>cp -rp /home/* /storage/home</userinput> +&prompt.root; <userinput>rm -rf /home /usr/home</userinput> +&prompt.root; <userinput>ln -s /storage/home /home</userinput> +&prompt.root; <userinput>ln -s /storage/home /usr/home</userinput></screen> + + <para>Users should now have their data stored on the freshly + created <filename class="directory">/storage/home</filename> + file system. Test by adding a new user and logging in as + that user.</para> + + <para>Try creating a snapshot which may be rolled back + later:</para> + + <screen>&prompt.root; <userinput>zfs snapshot storage/home@08-30-08</userinput></screen> + + <para>Note that the snapshot option will only capture a real + file system, not a home directory or a file. The + <literal>@</literal> character is a delimiter used between + the file system name or the volume name. When a user's + home directory gets trashed, restore it with:</para> + + <screen>&prompt.root; <userinput>zfs rollback storage/home@08-30-08</userinput></screen> + + <para>To get a list of all available snapshots, run the + <command>ls</command> in the file system's + <filename class="directory">.zfs/snapshot</filename> + directory. For example, to see the previously taken + snapshot, perform the following command:</para> + + <screen>&prompt.root; <userinput>ls /storage/home/.zfs/snapshot</userinput></screen> + + <para>It is possible to write a script to perform monthly + snapshots on user data; however, over time, snapshots + may consume a great deal of disk space. The previous + snapshot may be removed using the following command:</para> + + <screen>&prompt.root; <userinput>zfs destroy storage/home@08-30-08</userinput></screen> + + <para>There is no reason, after all of this testing, we should + keep <filename class="directory">/storage/home</filename> + around in its present state. Make it the real + <filename class="directory">/home</filename> file + system:</para> + + <screen>&prompt.root; <userinput>zfs set mountpoint=/home storage/home</userinput></screen> + + <para>Issuing the <command>df</command> and + <command>mount</command> commands will show that the system + now treats our file system as the real + <filename class="directory">/home</filename>:</para> + + <screen>&prompt.root; <userinput>mount</userinput> +/dev/ad0s1a on / (ufs, local) +devfs on /dev (devfs, local) +/dev/ad0s1d on /usr (ufs, local, soft-updates) +storage on /storage (zfs, local) +storage/home on /home (zfs, local) +&prompt.root; <userinput>df</userinput> +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/ad0s1a 2026030 235240 1628708 13% / +devfs 1 1 0 100% /dev +/dev/ad0s1d 54098308 1032826 48737618 2% /usr +storage 26320512 0 26320512 0% /storage +storage/home 26320512 0 26320512 0% /home</screen> + + <para>This completes the <acronym>RAID</acronym>-Z + configuration. To get status updates about the file systems + created during the nightly &man.periodic.8; runs, issue the + following command:</para> + + <screen>&prompt.root; <userinput>echo 'daily_status_zfs_enable="YES"' >> /etc/periodic.conf</userinput></screen> + </sect3> + + <sect3> + <title>Recovering <acronym>RAID</acronym>-Z</title> + + <para>Every software <acronym>RAID</acronym> has a method of + monitoring their <literal>state</literal>. + <acronym>ZFS</acronym> is no exception. The status of + <acronym>RAID</acronym>-Z devices may be viewed with the + following command:</para> + + <screen>&prompt.root; <userinput>zpool status -x</userinput></screen> + + <para>If all pools are healthy and everything is normal, the + following message will be returned:</para> + + <screen>all pools are healthy</screen> + + <para>If there is an issue, perhaps a disk has gone offline, + the pool state will be returned and look similar to:</para> + + <screen> pool: storage + state: DEGRADED +status: One or more devices has been taken offline by the administrator. + Sufficient replicas exist for the pool to continue functioning in a + degraded state. +action: Online the device using 'zpool online' or replace the device with + 'zpool replace'. + scrub: none requested +config: + + NAME STATE READ WRITE CKSUM + storage DEGRADED 0 0 0 + raidz1 DEGRADED 0 0 0 + da0 ONLINE 0 0 0 + da1 OFFLINE 0 0 0 + da2 ONLINE 0 0 0 + +errors: No known data errors</screen> + + <para>This states that the device was taken offline by the + administrator. This is true for this particular example. + To take the disk offline, the following command was + used:</para> + + <screen>&prompt.root; <userinput>zpool offline storage da1</userinput></screen> + + <para>It is now possible to replace the + <devicename>da1</devicename> after the system has been + powered down. When the system is back online, the following + command may issued to replace the disk:</para> + + <screen>&prompt.root; <userinput>zpool replace storage da1</userinput></screen> + + <para>From here, the status may be checked again, this time + without the <option>-x</option> flag to get state + information:</para> + + <screen>&prompt.root; <userinput>zpool status storage</userinput> + pool: storage + state: ONLINE + scrub: resilver completed with 0 errors on Sat Aug 30 19:44:11 2008 +config: + + NAME STATE READ WRITE CKSUM + storage ONLINE 0 0 0 + raidz1 ONLINE 0 0 0 + da0 ONLINE 0 0 0 + da1 ONLINE 0 0 0 + da2 ONLINE 0 0 0 + +errors: No known data errors</screen> + + <para>As shown from this example, everything appears to be + normal.</para> + </sect3> + + <sect3> + <title>Data Verification</title> + + <para>As previously mentioned, <acronym>ZFS</acronym> uses + <literal>checksums</literal> to verify the integrity of + stored data. They are enabled automatically upon creation + of file systems and may be disabled using the following + command:</para> + + <screen>&prompt.root; <userinput>zfs set checksum=off storage/home</userinput></screen> + + <para>This is not a wise idea, however, as checksums take + very little storage space and are more useful when enabled. There + also appears to be no noticeable costs in having them enabled. + While enabled, it is possible to have <acronym>ZFS</acronym> + check data integrity using checksum verification. This + process is known as <quote>scrubbing.</quote> To verify the + data integrity of the <literal>storage</literal> pool, issue + the following command:</para> + + <screen>&prompt.root; <userinput>zpool scrub storage</userinput></screen> + + <para>This process may take considerable time depending on + the amount of data stored. It is also very + <acronym>I/O</acronym> intensive, so much that only one + of these operations may be run at any given time. After + the scrub has completed, the status is updated and may be + viewed by issuing a status request:</para> + + <screen>&prompt.root; <userinput>zpool status storage</userinput> + pool: storage + state: ONLINE + scrub: scrub completed with 0 errors on Sat Aug 30 19:57:37 2008 +config: + + NAME STATE READ WRITE CKSUM + storage ONLINE 0 0 0 + raidz1 ONLINE 0 0 0 + da0 ONLINE 0 0 0 + da1 ONLINE 0 0 0 + da2 ONLINE 0 0 0 + +errors: No known data errors</screen> + + <para>The completion time is in plain view in this example. + This feature helps to ensure data integrity over a long + period of time.</para> + + <para>There are many more options for the Z file system, + see the &man.zfs.8; and &man.zpool.8; manual + pages.</para> + </sect3> + + <sect3> + <title>ZFS Quotas</title> + + <para>ZFS supports different types of quotas; the refquota, the + general quota, the user quota, and the group quota. This + section will explain the basics of each one, and include some + usage instructions.</para> + + <para>Quotas limit the amount of space that a dataset and its + descendants can consume, and enforce a limit on the amount of + space used by filesystems and snapshots for the descendants. + In terms of users, quotas are useful to limit the amount of + space a particular user can use.</para> + + <note> + <para>Quotas cannot be set on volumes, as the + <literal>volsize</literal> property acts as an implicit + quota.</para> + </note> + + <para>The refquota, + <literal>refquota=<replaceable>size</replaceable></literal>, + limits the amount of space a dataset can consume by enforcing + a hard limit on the space used. However, this hard limit does + not include space used by descendants, such as file systems or + snapshots.</para> + + <para>To enforce a general quota of 10 GB for + <filename>storage/home/bob</filename>, use the + following:</para> + + <screen>&prompt.root; <userinput>zfs set quota=10G storage/home/bob</userinput></screen> + + <para>User quotas limit the amount of space that can be used by + the specified user. The general format is + <literal>userquota@<replaceable>user</replaceable>=<replaceable>size</replaceable></literal>, + and the user's name must be in one of the following + formats:</para> + + <itemizedlist> + <listitem> + <para><acronym + role="Portable Operating System Interface">POSIX</acronym> + compatible name (e.g., <replaceable>joe</replaceable>).</para> + </listitem> + <listitem> + <para><acronym + role="Portable Operating System Interface">POSIX</acronym> + numeric ID (e.g., <replaceable>789</replaceable>).</para> + </listitem> + <listitem> + <para><acronym + role="System Identifier">SID</acronym> + name (e.g., + <replaceable>joe.bloggs@example.com</replaceable>).</para> + </listitem> + <listitem> + <para><acronym role="System Identifier">SID</acronym> + numeric ID (e.g., + <replaceable>S-1-123-456-789</replaceable>).</para> + </listitem> + </itemizedlist> + + <para>For example, to enforce a quota of 50 GB for a user + named <replaceable>joe</replaceable>, use the + following:</para> + + <screen>&prompt.root; <userinput>zfs set userquota@joe=50G</userinput></screen> + + <para>To remove the quota or make sure that one is not + set, instead use:</para> + + <screen>&prompt.root; <userinput>zfs set userquota@joe=none</userinput></screen> + + <para>User quota properties are not displayed by + <command>zfs get all</command>. Non-<username>root</username> + users can only see their own quotas unless they have been + granted the <literal>userquota</literal> privilege. Users + with this privilege are able to view and set everyone's + quota.</para> + + <para>The group quota limits the amount of space that a + specified user group can consume. The general format is + <literal>groupquota@<replaceable>group</replaceable>=<replaceable>size</replaceable></literal>.</para> + + <para>To set the quota for the group + <replaceable>firstgroup</replaceable> to 50 GB, + use:</para> + + <screen>&prompt.root; <userinput>zfs set groupquota@firstgroup=50G</userinput></screen> + + <para>To remove the quota for the group + <replaceable>firstgroup</replaceable>, or make sure that one + is not set, instead use:</para> + + <screen>&prompt.root; <userinput>zfs set groupquota@firstgroup=none</userinput></screen> + + <para>As with the user quota property, + non-<username>root</username> users can only see the quotas + associated with the user groups that they belong to, however + a <username>root</username> user or a user with the + <literal>groupquota</literal> privilege can view and set all + quotas for all groups.</para> + + <para>The <command>zfs userspace</command> subcommand displays + the amount of space consumed by each user on the specified + filesystem or snapshot, along with any specified quotas. + The <command>zfs groupspace</command> subcommand does the + same for groups. For more information about supported + options, or only displaying specific options, see + &man.zfs.1;.</para> + + <para>To list the quota for + <filename>storage/home/bob</filename>, if you have the + correct privileges or are <username>root</username>, + use the following:</para> + + <screen>&prompt.root; <userinput>zfs get quota storage/home/bob</userinput></screen> + </sect3> + + <sect3> + <title>ZFS Reservations</title> + + <para>ZFS supports two types of space reservations. This + section will explain the basics of each one, and include + some usage instructions.</para> + + <para>The <literal>reservation</literal> property makes it + possible to reserve a minimum amount of space guaranteed for a + dataset and its descendants. This means that if a 10 GB + reservation is set on <filename>storage/home/bob</filename>, + if disk space gets low, at least 10 GB of space is + reserved for this dataset. The + <literal>refreservation</literal> property sets or indicates + the minimum amount of space guaranteed to a dataset excluding + descendants, such as snapshots. As an example, if a snapshot + was taken of <filename>storage/home/bob</filename>, enough + disk space would have to exist outside of the + <literal>refreservation</literal> amount for the operation to + succeed because descendants of the main data set are not + counted by the <literal>refreservation</literal> amount and + so do not encroach on the space set.</para> + + <para>Reservations of any sort are useful in many situations, + for example planning and testing the suitability of disk space + allocation in a new system, or ensuring that enough space is + available on file systems for system recovery procedures and + files.</para> + + <para>The general format of the <literal>reservation</literal> + property is + <literal>reservation=<replaceable>size</replaceable></literal>, + so to set a reservation of 10 GB on + <filename>storage/home/bob</filename>the below command is + used:</para> + + <screen>&prompt.root; <userinput>zfs set reservation=10G storage/home/bob</userinput></screen> + + <para>To make sure that no reservation is set, or to remove a + reservation, instead use:</para> + + <screen>&prompt.root; <userinput>zfs set reservation=none storage/home/bob</userinput></screen> + + <para>The same principle can be applied to the + <literal>refreservation</literal> property for setting a + refreservation, with the general format + <literal>refreservation=<replaceable>size</replaceable></literal>.</para> + + <para>To check if any reservations or refreservations exist on + <filename>storage/home/bob</filename>, execute one of the + following commands:</para> + + <screen>&prompt.root; <userinput>zfs get reservation storage/home/bob</userinput> +&prompt.root; <userinput>zfs get refreservation storage/home/bob</userinput></screen> + </sect3> + </sect2> + </sect1> + + <sect1 id="filesystems-linux"> + <title>&linux; Filesystems</title> + + <para>This section will describe some of the &linux; filesystems + supported by &os;.</para> + + <sect2> + <title>Ext2FS</title> + + <para>The &man.ext2fs.5; file system kernel implementation was + written by Godmar Back, and the driver first appeared in + &os; 2.2. In &os; 8 and earlier, the code is licensed under + the <acronym>GNU</acronym> Public License, however under &os; 9, + the code has been rewritten and it is now licensed under the + <acronym>BSD</acronym> license.</para> + + <para>The &man.ext2fs.5; driver will allow the &os; kernel + to both read and write to <acronym>ext2</acronym> file systems.</para> + + <para>First, load the kernel loadable module:</para> + + <screen>kldload ext2fs</screen> + + <para>Then, to mount an &man.ext2fs.5; volume located on + <filename>/dev/ad1s1</filename>:</para> + + <screen><userinput>mount -t ext2fs /dev/ad1s1 /mnt</userinput></screen> + </sect2> + <sect2> + <title>XFS</title> + + <para>The X file system, <acronym>XFS</acronym>, was originally + written by <acronym>SGI</acronym> for the + <acronym>IRIX</acronym> operating system, and they ported it + to &linux;. The source code has been released under the + <acronym>GNU</acronym> Public License. See + <ulink url="http://oss.sgi.com/projects/xfs">this page</ulink> + for more details. The &os; port was started by Russel + Cattelan, &a.kan;, and &a.rodrigc;.</para> + + <para>To load <acronym>XFS</acronym> as a kernel-loadable + module:</para> + + <screen>kldload xfs</screen> + + <para>The &man.xfs.5; driver lets the &os; kernel access + XFS filesystems. However, at present only read-only + access is supported. Writing to a volume is not + possible.</para> + + <para>To mount a &man.xfs.5; volume located on + <filename>/dev/ad1s1</filename>, do the following:</para> + + <screen><userinput>mount -t xfs /dev/as1s1 /mnt</userinput></screen> + + <para>Also useful to note is that the + <filename role="package">sysutils/xfsprogs</filename> port + contains the <command>mkfs.xfs</command> utility which enables + creation of <acronym>XFS</acronym> filesystems, plus utilities + for analysing and repairing them.</para> + + <para>The <literal>-p</literal> flag to + <command>mkfs.xfs</command> can be used to create an + &man.xfs.5; filesystem which is populated with files and other + metadata. This can be used to quickly create a read-only + filesystem which can be tested on &os;.</para> + </sect2> + <sect2> + <title>ReiserFS</title> + + <para>The Reiser file system, ReiserFS, was ported to + &os; by &a.dumbbell;, and has been released under the + <acronym>GNU</acronym> Public License.</para> + + <para>The ReiserFS driver will permit the &os; kernel to + access ReiserFS file systems and read their contents, but not + write to them, currently.</para> + + <para>First, the kernel-loadable module needs to be loaded:</para> + + <screen>kldload reiserfs</screen> + + <para>Then, to mount a ReiserFS volume located on + <filename>/dev/ad1s1</filename>:</para> + + <screen><userinput>mount -t reiserfs /dev/ad1s1 /mnt</userinput></screen> + </sect2> + </sect1> + + <!-- + XXXTR: stub sections (added later, as needed, as desire, + after I get opinions from -doc people): + + Still need to discuss native and foreign file systems. + + <sect1> + <title>Device File System</title> + </sect1> + + <sect1> + <title>DOS and NTFS File Systems</title> + <para>This is a good section for those who transfer files, using + USB devices, from Windows to FreeBSD and vice-versa. My camera, + and many other cameras I have seen default to using FAT16. There + is (was?) a kde utility, I think called kamera, that could be used + to access camera devices. A section on this would be useful.</para> + + <para>XXXTR: Though! The disks chapter, covers a bit of this and + devfs under it's USB devices. It leaves a lot to be desired though, + see: +http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/usb-disks.html + It may be better to flesh out that section a bit more. Add the + word "camera" to it so that others can easily notice.</para> + </sect1> + + <sect1> + <title>Linux EXT File System</title> + + <para>Probably NOT as useful as the other two, but it requires + knowledge of the existence of the tools. Which are hidden in + the ports collection. Most Linux guys would probably only use + Linux, BSD guys would be smarter and use NFS.</para> + </sect1> + + <sect1> + <title>HFS</title> + + <para>I think this is the file system used on Apple OSX. There are + tools in the ports collection, and with Apple being a big + FreeBSD supporter and user of our technologies, surely there + is enough cross over to cover this?</para> + </sect1> + --> + +</chapter> diff --git a/en_US.ISO8859-1/books/handbook/firewalls/Makefile b/en_US.ISO8859-1/books/handbook/firewalls/Makefile new file mode 100644 index 0000000000..331f5bf8ec --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/firewalls/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= firewalls/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/firewalls/chapter.sgml b/en_US.ISO8859-1/books/handbook/firewalls/chapter.sgml new file mode 100644 index 0000000000..140ecfbc4f --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/firewalls/chapter.sgml @@ -0,0 +1,3388 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="firewalls"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Joseph J.</firstname> + <surname>Barbish</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Brad</firstname> + <surname>Davis</surname> + <contrib>Converted to SGML and updated by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>Firewalls</title> + + <indexterm><primary>firewall</primary></indexterm> + + <indexterm> + <primary>security</primary> + + <secondary>firewalls</secondary> + </indexterm> + + <sect1 id="firewalls-intro"> + <title>Introduction</title> + + <para>Firewalls make it possible to filter + incoming and outgoing traffic that flows through your system. + A firewall can use one or more sets of <quote>rules</quote> to + inspect the network packets as they come in or go out of your + network connections and either allows the traffic through or + blocks it. The rules of a firewall can inspect one or more + characteristics of the packets, including but not limited to the + protocol type, the source or destination host address, and the + source or destination port.</para> + + <para>Firewalls can greatly enhance the security of a host or a + network. They can be used to do one or more of + the following things:</para> + + <itemizedlist> + <listitem> + <para>To protect and insulate the applications, services and + machines of your internal network from unwanted traffic + coming in from the public Internet.</para> + </listitem> + + <listitem> + <para>To limit or disable access from hosts of the internal + network to services of the public Internet.</para> + </listitem> + + <listitem> + <para>To support network address translation + (<acronym>NAT</acronym>), which allows your internal network + to use private <acronym>IP</acronym> addresses and share a + single connection to the public Internet (either with a + single <acronym>IP</acronym> address or by a shared pool of + automatically assigned public addresses).</para> + </listitem> + </itemizedlist> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to properly define packet filtering rules.</para> + </listitem> + + <listitem> + <para>The differences between the firewalls + built into &os;.</para> + </listitem> + + <listitem> + <para>How to use and configure the OpenBSD + <application>PF</application> firewall.</para> + </listitem> + + <listitem> + <para>How to use and configure + <application>IPFILTER</application>.</para> + </listitem> + + <listitem> + <para>How to use and configure + <application>IPFW</application>.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand basic &os; and Internet concepts.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="firewalls-concepts"> + <title>Firewall Concepts</title> + + <indexterm> + <primary>firewall</primary> + + <secondary>rulesets</secondary> + </indexterm> + + <para>There are two basic ways to create firewall rulesets: + <quote>inclusive</quote> or <quote>exclusive</quote>. An + exclusive firewall allows all traffic through except for the + traffic matching the ruleset. An inclusive firewall does the + reverse. It only allows traffic matching the rules through and + blocks everything else.</para> + + <para>An inclusive firewall offers much better control of the outgoing + traffic, making it a better choice for systems that offer services to + the public Internet. It also controls the type of traffic originating + from the public Internet that can gain access to your private network. + All traffic that does not match the rules, is blocked and logged by + design. Inclusive firewalls are generally safer than exclusive + firewalls because they significantly reduce the risk of allowing + unwanted traffic to pass through them.</para> + + <note> + <para>Unless noted otherwise, all configuration and example + rulesets in this chapter, create inclusive type firewalls.</para> + </note> + + <para>Security can be tightened further using a <quote>stateful + firewall</quote>. This type of firewall keeps + track of which connections are opened through the firewall and + will only allow traffic through which either matches an existing + connection or opens a new one. The disadvantage of a stateful + firewall is that it can be vulnerable to Denial of Service + (<acronym>DoS</acronym>) attacks if a lot of new connections are + opened very fast. With most firewalls it is possible to use a + combination of stateful and non-stateful behavior to make an + optimal firewall for the site.</para> + </sect1> + + <sect1 id="firewalls-apps"> + <title>Firewall Packages</title> + + <para>&os; has three different firewall packages built + into the base system. They are: <emphasis>IPFILTER</emphasis> + (also known as <acronym>IPF</acronym>), + <emphasis>IPFIREWALL</emphasis> (also known as <acronym>IPFW</acronym>), + and <emphasis>OpenBSD's PacketFilter</emphasis> (also known as + <acronym>PF</acronym>). &os; also has two built in packages for + traffic shaping (basically controlling bandwidth usage): + &man.altq.4; and &man.dummynet.4;. Dummynet has traditionally been + closely tied with <acronym>IPFW</acronym>, and + <acronym>ALTQ</acronym> with + <acronym>PF</acronym>. Traffic shaping for IPFILTER can currently + be done with IPFILTER for NAT and filtering and + <acronym>IPFW</acronym> with &man.dummynet.4; + <emphasis>or</emphasis> by using <acronym>PF</acronym> with + <acronym>ALTQ</acronym>. + IPFW, and PF all use rules to control the access of packets to and + from your system, although they go about it different ways and + have a different rule syntax.</para> + + <para>The reason that &os; has multiple built in firewall packages + is that different people have different requirements and + preferences. No single firewall package is the best.</para> + + <para>The author prefers IPFILTER because its stateful rules are + much less complicated to use in a <acronym>NAT</acronym> + environment and it has a built in ftp proxy that simplifies the + rules to allow secure outbound FTP usage.</para> + + <para>Since all firewalls are based on inspecting the values of + selected packet control fields, the creator of the firewall + rulesets must have an understanding of how + <acronym>TCP/IP</acronym> works, what the different values in + the packet control fields are and how these values are used in a + normal session conversation. For a good explanation go to: + <ulink + url="http://www.ipprimer.com/overview.cfm"></ulink>.</para> + </sect1> + + <sect1 id="firewalls-pf"> + <sect1info> + <authorgroup> + <author> + <firstname>John</firstname> + <surname>Ferrell</surname> + <contrib>Revised and updated by </contrib> + <!-- 24 March 2008 --> + </author> + </authorgroup> + </sect1info> + + <title>The OpenBSD Packet Filter (PF) and + <acronym>ALTQ</acronym></title> + + <indexterm> + <primary>firewall</primary> + + <secondary>PF</secondary> + </indexterm> + + <para>As of July 2003 the OpenBSD firewall software application + known as <acronym>PF</acronym> was ported to &os; and + made available in the &os; Ports Collection. Released in 2004, + &os; 5.3 was the first release that contained + <acronym>PF</acronym> as an integrated part of the base system. + <acronym>PF</acronym> is a complete, full-featured firewall + that has optional support for <acronym>ALTQ</acronym> (Alternate + Queuing). <acronym>ALTQ</acronym> provides Quality of Service + (<acronym>QoS</acronym>) functionality.</para> + + <para>The OpenBSD Project does an outstanding job of + maintaining the <ulink + url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink>. + As such, this section of the Handbook will focus on + <acronym>PF</acronym> as it pertains to &os; while providing + some general information regarding usage. For detailed usage + information please refer to the <ulink + url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink>.</para> + + <para>More information about <acronym>PF</acronym> for &os; + can be found at <ulink + url="http://pf4freebsd.love2party.net/"></ulink>.</para> + + <sect2> + <title>Using the PF Loadable Kernel Modules</title> + + <para>To load the PF Kernel Module add the following line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>pf_enable="YES"</programlisting> + + <para>Then run the startup script to load the module:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/pf start</userinput></screen> + + <para>Note that the PF Module will not load if it cannot find + the ruleset config file. The default location is + <filename>/etc/pf.conf</filename>. If the PF ruleset is + located somewhere else, PF can be instructed to look there by + adding a line like the following to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>pf_rules="<replaceable>/path/to/pf.conf</replaceable>"</programlisting> + + <para>The sample <filename>pf.conf</filename> + can be found in <filename + class="directory">/usr/share/examples/pf/</filename>. + </para> + + <para>The <acronym>PF</acronym> module can also be loaded manually + from the command line:</para> + + <screen>&prompt.root; <userinput>kldload pf.ko</userinput></screen> + + <para>Logging support for PF is provided by the + <literal>pflog.ko</literal> and can be loaded by adding the + following line to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>pflog_enable="YES"</programlisting> + + <para>Then run the startup script to load the module:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/pflog start</userinput></screen> + + <para>If you need other <acronym>PF</acronym> features you will + need to compile <acronym>PF</acronym> support into the kernel.</para> + </sect2> + + <sect2> + <title>PF Kernel Options</title> + + <indexterm> + <primary>kernel options</primary> + + <secondary>device pf</secondary> + </indexterm> + + <indexterm> + <primary>kernel options</primary> + + <secondary>device pflog</secondary> + </indexterm> + + <indexterm> + <primary>kernel options</primary> + + <secondary>device pfsync</secondary> + </indexterm> + + <para>While it is not necessary that you compile + <acronym>PF</acronym> support into the &os; kernel, you may want + to do so to take advantage of one of PF's advanced features that + is not included in the loadable module, namely &man.pfsync.4;, which + is a pseudo-device that exposes certain changes to + the state table used by <acronym>PF</acronym>. It can be + paired with &man.carp.4; to create failover firewalls using + <acronym>PF</acronym>. More information on + <acronym>CARP</acronym> can be found in + <xref linkend="carp"> of the Handbook.</para> + + <para>The <acronym>PF</acronym> kernel options can be found in + <filename>/usr/src/sys/conf/NOTES</filename> and are reproduced + below:</para> + + <programlisting>device pf +device pflog +device pfsync</programlisting> + + <para>The <literal>device pf</literal> option enables support for the + <quote>Packet Filter</quote> firewall (&man.pf.4;).</para> + + <para>The <literal>device pflog</literal> option enables the optional + &man.pflog.4; pseudo network device which can be used to log + traffic to a &man.bpf.4; descriptor. The &man.pflogd.8; daemon + can be used to store the logging information to disk.</para> + + <para>The <literal>device pfsync</literal> option enables the optional + &man.pfsync.4; pseudo-network device that is used to monitor + <quote>state changes</quote>.</para> + </sect2> + + <sect2> + <title>Available <filename>rc.conf</filename> Options</title> + + <para>The following &man.rc.conf.5; statements configure + <acronym>PF</acronym> and &man.pflog.4; at boot:</para> + + <programlisting>pf_enable="YES" # Enable PF (load module if required) +pf_rules="/etc/pf.conf" # rules definition file for pf +pf_flags="" # additional flags for pfctl startup +pflog_enable="YES" # start pflogd(8) +pflog_logfile="/var/log/pflog" # where pflogd should store the logfile +pflog_flags="" # additional flags for pflogd startup</programlisting> + + <para>If you have a LAN behind this firewall and have to forward + packets for the computers on the LAN or want to do NAT, you + will need the following option as well:</para> + + <programlisting>gateway_enable="YES" # Enable as LAN gateway</programlisting> + </sect2> + + <sect2> + <title>Creating Filtering Rules</title> + + <para><acronym>PF</acronym> reads its configuration rules from + &man.pf.conf.5; (<filename>/etc/pf.conf</filename> by + default) and it modifies, drops, or passes packets according to + the rules or definitions specified there. The &os; + installation includes several sample files located in + <filename>/usr/share/examples/pf/</filename>. Please refer to + the <ulink url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink> + for complete coverage of <acronym>PF</acronym> rulesets.</para> + + <warning> + <para>When browsing the <ulink + url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink>, + please keep in mind that different versions of &os; can + contain different versions of PF. Currently, + &os; 8.<replaceable>X</replaceable> and prior is + using the same version of <acronym>PF</acronym> as + OpenBSD 4.1. &os; 9.<replaceable>X</replaceable> and + later is using the same version of <acronym>PF</acronym> as + OpenBSD 4.5.</para> + </warning> + + <para>The &a.pf; is a good place to ask questions about + configuring and running the <acronym>PF</acronym> + firewall. Do not forget to check the mailing list archives + before asking questions!</para> + </sect2> + + <sect2> + <title>Working with PF</title> + + <para>Use &man.pfctl.8; to control <acronym>PF</acronym>. Below + are some useful commands (be sure to review the &man.pfctl.8; + man page for all available options):</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Command</entry> + <entry>Purpose</entry> + </row> + </thead> + + <tbody> + <row> + <entry><command>pfctl <option>-e</option></command></entry> + <entry>Enable PF</entry> + </row> + + <row> + <entry><command>pfctl <option>-d</option></command></entry> + <entry>Disable PF</entry> + </row> + + <row> + <entry><command>pfctl <option>-F</option> all <option>-f</option> /etc/pf.conf</command></entry> + <entry>Flush all rules (nat, filter, state, table, etc.) and + reload from the file <filename>/etc/pf.conf</filename></entry> + </row> + + <row> + <entry><command>pfctl <option>-s</option> [ rules | nat | state ]</command></entry> + <entry>Report on the filter rules, nat rules, or state + table</entry> + </row> + + <row> + <entry><command>pfctl <option>-vnf</option> /etc/pf.conf</command></entry> + <entry>Check <filename>/etc/pf.conf</filename> for errors, + but do not load ruleset</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + + <sect2> + <title>Enabling <acronym>ALTQ</acronym></title> + + <para><acronym>ALTQ</acronym> is only available by compiling + support for it into the &os; kernel. <acronym>ALTQ</acronym> is + not supported by all of the available network card drivers. + Please see the &man.altq.4; manual page for a list of drivers + that are supported in your release of &os;.</para> + + <para>The following kernel options will enable + <acronym>ALTQ</acronym> and add additional functionality:</para> + + <programlisting>options ALTQ +options ALTQ_CBQ # Class Bases Queuing (CBQ) +options ALTQ_RED # Random Early Detection (RED) +options ALTQ_RIO # RED In/Out +options ALTQ_HFSC # Hierarchical Packet Scheduler (HFSC) +options ALTQ_PRIQ # Priority Queuing (PRIQ) +options ALTQ_NOPCC # Required for SMP build</programlisting> + + <para><literal>options ALTQ</literal> enables the + <acronym>ALTQ</acronym> framework.</para> + + <para><literal>options ALTQ_CBQ</literal> enables <emphasis>Class Based + Queuing</emphasis> (<acronym>CBQ</acronym>). <acronym>CBQ</acronym> + allows you to divide a connection's bandwidth into different + classes or queues to prioritize traffic based on filter + rules.</para> + + <para><literal>options ALTQ_RED</literal> enables <emphasis>Random Early + Detection</emphasis> (<acronym>RED</acronym>). <acronym>RED</acronym> is + used to avoid network congestion. <acronym>RED</acronym> does + this by measuring the length of the queue and comparing it to + the minimum and maximum thresholds for the queue. If the + queue is over the maximum all new packets will be dropped. + True to its name, <acronym>RED</acronym> drops packets from + different connections randomly.</para> + + <para><literal>options ALTQ_RIO</literal> enables <emphasis>Random Early + Detection In and Out</emphasis>.</para> + + <para><literal>options ALTQ_HFSC</literal> enables the + <emphasis>Hierarchical Fair Service Curve Packet Scheduler</emphasis>. For more + information about <acronym>HFSC</acronym> see: <ulink + url="http://www-2.cs.cmu.edu/~hzhang/HFSC/main.html"></ulink>.</para> + + <para><literal>options ALTQ_PRIQ</literal> enables <emphasis>Priority + Queuing</emphasis> (<acronym>PRIQ</acronym>). <acronym>PRIQ</acronym> + will always pass traffic that is in a higher queue + first.</para> + + <para><literal>options ALTQ_NOPCC</literal> enables + <acronym>SMP</acronym> support for <acronym>ALTQ</acronym>. + This option is required on <acronym>SMP</acronym> + systems.</para> + </sect2> + </sect1> + + <sect1 id="firewalls-ipf"> + <title>The IPFILTER (IPF) Firewall</title> + + <indexterm> + <primary>firewall</primary> + + <secondary>IPFILTER</secondary> + </indexterm> + + <para>The author of IPFILTER is Darren Reed. IPFILTER is not + operating system dependent: it is an open source application and + has been ported to &os;, NetBSD, OpenBSD, &sunos;, HP/UX, and + &solaris; operating systems. IPFILTER is actively being + supported and maintained, with updated versions being released + regularly.</para> + + <para>IPFILTER is based on a kernel-side firewall and + <acronym>NAT</acronym> mechanism that can be controlled and + monitored by userland interface programs. The firewall rules can + be set or deleted with the &man.ipf.8; utility. The + <acronym>NAT</acronym> rules can be set or deleted with the + &man.ipnat.1; utility. The &man.ipfstat.8; utility can print + run-time statistics for the kernel parts of IPFILTER. The + &man.ipmon.8; program can log IPFILTER actions to the system log + files.</para> + + <para>IPF was originally written using a rule processing logic of + <quote>the last matching rule wins</quote> and used only + stateless type of rules. Over time IPF has been enhanced to + include a <quote>quick</quote> option and a stateful <quote>keep + state</quote> option which drastically modernized the rules + processing logic. IPF's official documentation covers only the legacy + rule coding parameters and rule file processing + logic. The modernized functions are only included as additional + options, completely understating their benefits in producing a + far superior and more secure firewall.</para> + + <para>The instructions contained in this section are based on + using rules that contain the <quote>quick</quote> option and the + stateful <quote>keep state</quote> option. This is the basic + framework for coding an inclusive firewall ruleset.</para> + + <para>For detailed explanation of the legacy rules processing + method see: <ulink + url="http://www.obfuscation.org/ipf/ipf-howto.html#TOC_1"></ulink> + and <ulink + url="http://coombs.anu.edu.au/~avalon/ip-filter.html"></ulink>.</para> + + <para>The IPF FAQ is at <ulink + url="http://www.phildev.net/ipf/index.html"></ulink>.</para> + + <para>A searchable archive of the open-source IPFilter mailing list is + available at <ulink + url="http://marc.theaimsgroup.com/?l=ipfilter"></ulink>.</para> + + <sect2> + <title>Enabling IPF</title> + + <indexterm> + <primary>IPFILTER</primary> + + <secondary>enabling</secondary> + </indexterm> + + <para>IPF is included in the basic &os; install as a separate run + time loadable module. The system will dynamically load the IPF + kernel loadable module when the <filename>rc.conf</filename> statement + <literal>ipfilter_enable="YES"</literal> is used. The loadable + module was created with logging enabled and the + <literal>default pass all</literal> options. There is no need + to compile IPF into the &os; kernel just to change the default + to <literal>block all</literal>. This can be done just by adding + a <literal>block all</literal> rule at the end of your ruleset.</para> + </sect2> + + <sect2> + <title>Kernel Options</title> + + <indexterm> + <primary>kernel options</primary> + + <secondary>IPFILTER</secondary> + </indexterm> + + <indexterm> + <primary>kernel options</primary> + + <secondary>IPFILTER_LOG</secondary> + </indexterm> + + <indexterm> + <primary>kernel options</primary> + + <secondary>IPFILTER_DEFAULT_BLOCK</secondary> + </indexterm> + + <indexterm> + <primary>IPFILTER</primary> + + <secondary>kernel options</secondary> + </indexterm> + + <para>It is not a mandatory requirement to enable IPF by + compiling the following options into the &os; kernel. It is + only presented here as background information. Compiling IPF + into the kernel causes the loadable module to never be + used.</para> + + <para>Sample kernel config IPF option statements are in the + <filename>/usr/src/sys/conf/NOTES</filename> kernel source + and are reproduced here:</para> + + <programlisting>options IPFILTER +options IPFILTER_LOG +options IPFILTER_DEFAULT_BLOCK</programlisting> + + <para><literal>options IPFILTER</literal> enables support for the + <quote>IPFILTER</quote> firewall.</para> + + <para><literal>options IPFILTER_LOG</literal> enables the option + to have IPF log traffic by writing to the + <devicename>ipl</devicename> packet logging pseudo—device + for every rule that has the <literal>log</literal> + keyword.</para> + + <para><literal>options IPFILTER_DEFAULT_BLOCK</literal> changes + the default behavior so any packet not matching a firewall + <literal>pass</literal> rule gets blocked.</para> + + <para>These settings will take effect only after installing a kernel + that has been built with the above options set.</para> + </sect2> + + <sect2> + <title>Available <filename>rc.conf</filename> Options</title> + + <para>To activate IPF at boot time, the following statements need to + be added to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ipfilter_enable="YES" # Start ipf firewall +ipfilter_rules="/etc/ipf.rules" # loads rules definition text file +ipmon_enable="YES" # Start IP monitor log +ipmon_flags="-Ds" # D = start as daemon + # s = log to syslog + # v = log tcp window, ack, seq + # n = map IP & port to names</programlisting> + + <para>If there is a LAN behind this firewall that uses the + reserved private IP address ranges, the following lines will have to + be added to enable <acronym>NAT</acronym> + functionality:</para> + + <programlisting>gateway_enable="YES" # Enable as LAN gateway +ipnat_enable="YES" # Start ipnat function +ipnat_rules="/etc/ipnat.rules" # rules definition file for ipnat</programlisting> + </sect2> + + <sect2> + <title>IPF</title> + + <indexterm><primary><command>ipf</command></primary></indexterm> + + <para>The &man.ipf.8; command is used to load your ruleset file. + Your custom rules would normally be placed in a file, and the + following command could then be used to replace in mass the + currently running firewall rules:</para> + + <screen>&prompt.root; <userinput>ipf -Fa -f /etc/ipf.rules</userinput></screen> + + <para><option>-Fa</option> means flush all internal rules + tables.</para> + + <para><option>-f</option> means this is the file to read for the + rules to load.</para> + + <para>This gives you the ability to make changes to your custom + rules file, run the above IPF command, and thus update the + running firewall with a fresh copy of all the rules without + having to reboot the system. This method is very convenient + for testing new rules as the procedure can be executed as many + times as needed.</para> + + <para>See the &man.ipf.8; manual page for details on the other + flags available with this command.</para> + + <para>The &man.ipf.8; command expects the rules file to be a + standard text file. It will not accept a rules file written as + a script with symbolic substitution.</para> + + <para>There is a way to build IPF rules that utilizes the power + of script symbolic substitution. For more information, see + <xref linkend="firewalls-ipf-rules-script">.</para> + </sect2> + + <sect2> + <title>IPFSTAT</title> + + <indexterm><primary><command>ipfstat</command></primary></indexterm> + + <indexterm> + <primary>IPFILTER</primary> + + <secondary>statistics</secondary> + </indexterm> + + <para>The default behavior of &man.ipfstat.8; is to retrieve and + display the totals of the accumulated statistics gathered as a + result of applying the user coded rules against packets going + in and out of the firewall since it was last started, or since + the last time the accumulators were reset to zero by the + <command>ipf -Z</command> command.</para> + + <para>See the &man.ipfstat.8; manual page for details.</para> + + <para>The default &man.ipfstat.8; command output will look + something like this:</para> + + <screen>input packets: blocked 99286 passed 1255609 nomatch 14686 counted 0 + output packets: blocked 4200 passed 1284345 nomatch 14687 counted 0 + input packets logged: blocked 99286 passed 0 + output packets logged: blocked 0 passed 0 + packets logged: input 0 output 0 + log failures: input 3898 output 0 + fragment state(in): kept 0 lost 0 + fragment state(out): kept 0 lost 0 + packet state(in): kept 169364 lost 0 + packet state(out): kept 431395 lost 0 + ICMP replies: 0 <acronym>TCP</acronym> RSTs sent: 0 + Result cache hits(in): 1215208 (out): 1098963 + IN Pullups succeeded: 2 failed: 0 + OUT Pullups succeeded: 0 failed: 0 + Fastroute successes: 0 failures: 0 + <acronym>TCP</acronym> cksum fails(in): 0 (out): 0 + Packet log flags set: (0)</screen> + + <para>When supplied with either <option>-i</option> for inbound + or <option>-o</option> for outbound, the command will retrieve and + display the appropriate list of filter rules currently + installed and in use by the kernel.</para> + + <para><command>ipfstat -in</command> displays the inbound + internal rules table with rule number.</para> + + <para><command>ipfstat -on</command> displays the outbound + internal rules table with the rule number.</para> + + <para>The output will look something like this:</para> + + <screen>@1 pass out on xl0 from any to any +@2 block out on dc0 from any to any +@3 pass out quick on dc0 proto tcp/udp from any to any keep state</screen> + + <para><command>ipfstat -ih</command> displays the inbound + internal rules table, prefixing each rule with a count of how + many times the rule was matched.</para> + + <para><command>ipfstat -oh</command> displays the outbound + internal rules table, prefixing each rule with a count of how + many times the rule was matched.</para> + + <para>The output will look something like this:</para> + + <screen>2451423 pass out on xl0 from any to any +354727 block out on dc0 from any to any +430918 pass out quick on dc0 proto tcp/udp from any to any keep state</screen> + + <para>One of the most important functions of the + <command>ipfstat</command> command is the <option>-t</option> + flag which displays the state table in a way similar to the way + &man.top.1; shows the &os; running process table. When your + firewall is under attack, this function gives you the ability to + identify, drill down to, and see the attacking packets. The + optional sub-flags give the ability to select the destination + or source IP, port, or protocol that you want to monitor in + real time. See the &man.ipfstat.8; manual page for + details.</para> + </sect2> + + <sect2> + <title>IPMON</title> + + <indexterm><primary><command>ipmon</command></primary></indexterm> + + <indexterm> + <primary>IPFILTER</primary> + + <secondary>logging</secondary> + </indexterm> + + <para>In order for <command>ipmon</command> to work properly, the + kernel option <literal>IPFILTER_LOG</literal> must be turned on. This command has + two different modes that it can be used in. Native mode is the + default mode when the command is typed on the command line + without the <option>-D</option> flag.</para> + + <para>Daemon mode is for when a continuous + system log file is desired, so that logging of past events may be + reviewed. This is how &os; and IPFILTER are configured to + work together. &os; has a built in facility to automatically + rotate system logs. That is why outputting the log information + to &man.syslogd.8; is better than the default of outputting to a + regular file. In the default <filename>rc.conf</filename> file, + the <literal>ipmon_flags</literal> statement uses the <option>-Ds</option> + flags:</para> + + <programlisting>ipmon_flags="-Ds" # D = start as daemon + # s = log to syslog + # v = log tcp window, ack, seq + # n = map IP & port to names</programlisting> + + <para>The benefits of logging are obvious. It provides the + ability to review, after the fact, information such as which + packets had been dropped, what addresses they came from and + where they were going. These can all provide a significant edge + in tracking down attackers.</para> + + <para>Even with the logging facility enabled, IPF will not + generate any rule logging on its own. The firewall + administrator decides what rules in the ruleset he wants to + log and adds the log keyword to those rules. Normally only + deny rules are logged.</para> + + <para>It is very customary to include a default deny everything + rule with the log keyword included as your last rule in the + ruleset. This makes it possible to see all the packets that did not + match any of the rules in the ruleset.</para> + </sect2> + + <sect2> + <title>IPMON Logging</title> + + <para><application>Syslogd</application> uses its own special + method for segregation of log data. It uses special groupings + called <quote>facility</quote> and <quote>level</quote>. IPMON + in <option>-Ds</option> mode uses <literal>local0</literal> + as the <quote>facility</quote> + name by default. + The following levels can be + used to further segregate the logged data if desired:</para> + + <screen>LOG_INFO - packets logged using the "log" keyword as the action rather than pass or block. +LOG_NOTICE - packets logged which are also passed +LOG_WARNING - packets logged which are also blocked +LOG_ERR - packets which have been logged and which can be considered short</screen> + + <!-- XXX: "can be considered short" == "with incomplete header" --> + + <para>To setup IPFILTER to log all data to + <filename>/var/log/ipfilter.log</filename>, the file will need to be + created beforehand. The following command will do that:</para> + + <screen>&prompt.root; <userinput>touch /var/log/ipfilter.log</userinput></screen> + + <para>The &man.syslogd.8; function is controlled by definition statements + in the <filename>/etc/syslog.conf</filename> file. The + <filename>syslog.conf</filename> file offers considerable + flexibility in how <application>syslog</application> will deal with system messages issued + by software applications like IPF.</para> + + <para>Add the following statement to + <filename>/etc/syslog.conf</filename>:</para> + + <programlisting>local0.* /var/log/ipfilter.log</programlisting> + + <para>The <literal>local0.*</literal> + means to write all the logged messages to the coded + file location.</para> + + <para>To activate the changes to <filename>/etc/syslog.conf + </filename> you can reboot or bump the &man.syslogd.8; daemon into + re-reading <filename>/etc/syslog.conf</filename> by running + <command>/etc/rc.d/syslogd reload</command></para> + + <para>Do not forget to change + <filename>/etc/newsyslog.conf</filename> to rotate the new log + created above.</para> + </sect2> + + <sect2> + <title>The Format of Logged Messages</title> + + <para>Messages generated by <command>ipmon</command> consist of + data fields separated by white space. Fields common to all + messages are:</para> + + <orderedlist> + <listitem> + <para>The date of packet receipt.</para> + </listitem> + + <listitem> + <para>The time of packet receipt. This is in the form + HH:MM:SS.F, for hours, minutes, seconds, and fractions of a + second (which can be several digits long).</para> + </listitem> + + <listitem> + <para>The name of the interface the packet was processed on, + e.g., <devicename>dc0</devicename>.</para> + </listitem> + + <listitem> + <para>The group and rule number of the rule, e.g. + <literal>@0:17</literal>.</para> + </listitem> + </orderedlist> + + <para>These can be viewed with <command>ipfstat + -in</command>.</para> + + <orderedlist> + <listitem> + <para>The action: p for passed, b for blocked, S for a short + packet, n did not match any rules, L for a log rule. The + order of precedence in showing flags is: S, p, b, n, L. A + capital P or B means that the packet has been logged due to + a global logging setting, not a particular rule.</para> + </listitem> + + <listitem> + <para>The addresses. This is actually three fields: the + source address and port (separated by a comma), the -> + symbol, and the destination address and port, e.g.: + <literal>209.53.17.22,80 -> 198.73.220.17,1722</literal>.</para> + </listitem> + + <listitem> + <para><literal>PR</literal> followed by the protocol name or + number, e.g.: <literal>PR tcp</literal>.</para> + </listitem> + + <listitem> + <para><literal>len</literal> followed by the header length + and total length of the packet, e.g.: <literal>len 20 40</literal>.</para> + </listitem> + </orderedlist> + + <para>If the packet is a <acronym>TCP</acronym> packet, there + will be an additional field starting with a hyphen followed by + letters corresponding to any flags that were set. See the + &man.ipf.5; manual page for a list of letters and their + flags.</para> + + <para>If the packet is an ICMP packet, there will be two fields + at the end, the first always being <quote>ICMP</quote>, and the + next being the ICMP message and sub-message type, separated by + a slash, e.g., ICMP 3/3 for a port unreachable message.</para> + </sect2> + + <sect2 id="firewalls-ipf-rules-script"> + <title>Building the Rule Script with Symbolic + Substitution</title> + + <para>Some experienced IPF users create a file containing the + rules and code them in a manner compatible with running them as + a script with symbolic substitution. The major benefit of + doing this is that only the value associated + with the symbolic name needs to be changed, and when the script is run all the rules + containing the symbolic name will have the value substituted in + the rules. Being a script, symbolic substitution can be used + to code frequently used values and substitute them in multiple + rules. This can be seen in the following example.</para> + + <para>The script syntax used here is compatible with the &man.sh.1;, &man.csh.1;, + and &man.tcsh.1; shells.</para> + + <para>Symbolic substitution fields are prefixed with a dollar + sign: <literal>$</literal>.</para> + + <para>Symbolic fields do not have the $ prefix.</para> + + <para>The value to populate the symbolic field must be enclosed + with double quotes (<literal>"</literal>).</para> + + <para>Start your rule file with something like this:</para> + + <programlisting>############# Start of IPF rules script ######################## + +oif="dc0" # name of the outbound interface +odns="192.0.2.11" # ISP's DNS server IP address +myip="192.0.2.7" # my static IP address from ISP +ks="keep state" +fks="flags S keep state" + +# You can choose between building /etc/ipf.rules file +# from this script or running this script "as is". +# +# Uncomment only one line and comment out another. +# +# 1) This can be used for building /etc/ipf.rules: +#cat > /etc/ipf.rules << EOF +# +# 2) This can be used to run script "as is": +/sbin/ipf -Fa -f - << EOF + +# Allow out access to my ISP's Domain name server. +pass out quick on $oif proto tcp from any to $odns port = 53 $fks +pass out quick on $oif proto udp from any to $odns port = 53 $ks + +# Allow out non-secure standard www function +pass out quick on $oif proto tcp from $myip to any port = 80 $fks + +# Allow out secure www function https over TLS SSL +pass out quick on $oif proto tcp from $myip to any port = 443 $fks +EOF +################## End of IPF rules script ########################</programlisting> + + <para>That is all there is to it. The rules are not important in + this example; how the symbolic substitution fields are + populated and used are. If the above example was in a file + named <filename>/etc/ipf.rules.script</filename>, these rules could be + reloaded by entering the following command:</para> + + <screen>&prompt.root; <userinput>sh /etc/ipf.rules.script</userinput></screen> + + <para>There is one problem with using a rules file with embedded + symbolics: IPF does not understand symbolic substitution, and + cannot read such scripts directly.</para> + + <para>This script can be used in one of two ways:</para> + + <itemizedlist> + <listitem> + <para>Uncomment the line that begins with + <literal>cat</literal>, and comment out the line that + begins with <literal>/sbin/ipf</literal>. Place + <literal>ipfilter_enable="YES"</literal> into + <filename>/etc/rc.conf</filename> as usual, and run script + once after each modification to create or update + <filename>/etc/ipf.rules</filename>.</para> + </listitem> + + <listitem> + <para>Disable IPFILTER in system startup scripts by adding + <literal>ipfilter_enable="NO"</literal> (this is default + value) into <filename>/etc/rc.conf</filename> file.</para> + + <para>Add a script like the following to your + <filename class="directory">/usr/local/etc/rc.d/</filename> startup + directory. The script should have an obvious name like + <filename>ipf.loadrules.sh</filename>. The + <filename>.sh</filename> extension is mandatory.</para> + + <programlisting>#!/bin/sh +sh /etc/ipf.rules.script</programlisting> + + <para>The permissions on this script file must be read, + write, execute for owner <username>root</username>.</para> + + <screen>&prompt.root; <userinput>chmod 700 /usr/local/etc/rc.d/ipf.loadrules.sh</userinput></screen> + </listitem> + </itemizedlist> + + <para>Now, when your system boots, your IPF rules will be + loaded.</para> + </sect2> + + <sect2> + <title>IPF Rulesets</title> + + <para>A ruleset is a group of IPF rules coded to pass or block + packets based on the values contained in the packet. The + bi-directional exchange of packets between hosts comprises a + session conversation. The firewall ruleset processes both the + packets arriving from the public Internet, as well as the packets + produced by the system as a response to them. + Each <acronym>TCP/IP</acronym> service (i.e.: telnet, www, + mail, etc.) is predefined by its protocol and privileged (listening) + port. Packets destined for a specific service, originate from the + source address using an unprivileged (high order) port and target the + specific service port on the destination address. All the above + parameters (i.e.: ports and addresses) can be used as selection + criteria to create rules which will pass or block services.</para> + + <indexterm> + <primary>IPFILTER</primary> + + <secondary>rule processing order</secondary> + </indexterm> + + <para>IPF was originally written using a rules processing logic + of <quote>the last matching rule wins</quote> and used only + stateless rules. Over time IPF has been enhanced to include a + <quote>quick</quote> option and a stateful <quote>keep + state</quote> option which drastically modernized the rule + processing logic.</para> + + <para>The instructions contained in this section are based on + using rules that contain the <quote>quick</quote> option and + the stateful <quote>keep state</quote> option. This is the + basic framework for coding an inclusive firewall rule + set.</para> + + <warning> + <para>When working with the firewall rules, be <emphasis>very + careful</emphasis>. Some configurations <emphasis>will + lock you out</emphasis> of the server. To be on the safe + side, you may wish to consider performing the initial + firewall configuration from the local console rather than + doing it remotely e.g., via + <application>ssh</application>.</para> + </warning> + </sect2> + + <sect2> + <title>Rule Syntax</title> + + <indexterm> + <primary>IPFILTER</primary> + + <secondary>rule syntax</secondary> + </indexterm> + + <para>The rule syntax presented here has been simplified to only + address the modern stateful rule context and <quote>first + matching rule wins</quote> logic. For the complete legacy rule + syntax description see the &man.ipf.8; manual page.</para> + + <para>A <literal>#</literal> character is used to mark the start + of a comment and may appear at the end of a rule line or on its + own line. Blank lines are ignored.</para> + + <para>Rules contain keywords. These keywords have to be coded in + a specific order from left to right on the line. Keywords are + identified in bold type. Some keywords have sub-options which + may be keywords themselves and also include more sub-options. + Each of the headings in the below syntax has a bold section + header which expands on the content.</para> + + <!-- This section is probably wrong. See the OpenBSD flag --> + <!-- What is the "OpenBSD flag"? Reference please --> + + <para><replaceable>ACTION IN-OUT OPTIONS SELECTION STATEFUL PROTO + SRC_ADDR,DST_ADDR OBJECT PORT_NUM TCP_FLAG + STATEFUL</replaceable></para> + + <para><replaceable>ACTION</replaceable> = block | pass</para> + + <para><replaceable>IN-OUT</replaceable> = in | out</para> + + <para><replaceable>OPTIONS</replaceable> = log | quick | on + interface-name</para> + + <para><replaceable>SELECTION</replaceable> = proto value | + source/destination IP | port = number | flags + flag-value</para> + + <para><replaceable>PROTO</replaceable> = tcp/udp | udp | tcp | + icmp</para> + + <para><replaceable>SRC_ADD,DST_ADDR</replaceable> = all | from + object to object</para> + + <para><replaceable>OBJECT</replaceable> = IP address | any</para> + + <para><replaceable>PORT_NUM</replaceable> = port number</para> + + <para><replaceable>TCP_FLAG</replaceable> = S</para> + + <para><replaceable>STATEFUL</replaceable> = keep state</para> + + <sect3> + <title>ACTION</title> + + <para>The action indicates what to do with the packet if it + matches the rest of the filter rule. Each rule + <emphasis>must</emphasis> have an action. The following + actions are recognized:</para> + + <para><literal>block</literal> indicates that the packet should + be dropped if the selection parameters match the + packet.</para> + + <para><literal>pass</literal> indicates that the packet should + exit the firewall if the selection parameters match the + packet.</para> + </sect3> + + <sect3> + <title>IN-OUT</title> + + <para>A mandatory requirement is that each filter rule + explicitly state which side of the I/O it is to be used on. + The next keyword must be either <literal>in</literal> or <literal>out</literal> and one or the + other has to be coded or the rule will not pass syntax + checks.</para> + + <para><literal>in</literal> means this rule is being applied + against an inbound packet which has just been received on the + interface facing the public Internet.</para> + + <para><literal>out</literal> means this rule is being applied + against an outbound packet destined for the interface facing + the public Internet.</para> + </sect3> + + <sect3> + <title>OPTIONS</title> + + <note> + <para>These options must be used in the order shown + here.</para> + </note> + + <para><literal>log</literal> indicates that the packet header + will be written to + + <!-- XXX - xref here --> + + the <devicename>ipl</devicename> log (as described in the + LOGGING section below) if the selection parameters match the + packet.</para> + + <para><literal>quick</literal> indicates that if the selection + parameters match the packet, this rule will be the last rule + checked, allowing a <quote>short-circuit</quote> path to avoid processing + any following rules for this packet. This option is a + mandatory requirement for the modernized rules processing + logic.</para> + + <para><literal>on</literal> indicates the interface name to be + incorporated into the selection parameters. Interface names + are as displayed by &man.ifconfig.8;. Using this option, the + rule will only match if the packet is going through that + interface in the specified direction (in/out). This option + is a mandatory requirement for the modernized rules + processing logic.</para> + + <para>When a packet is logged, the headers of the packet are + written to the <acronym>IPL</acronym> packet logging pseudo-device. + Immediately following the <literal>log</literal> keyword, the following + qualifiers may be used (in this order):</para> + + <para><literal>body</literal> indicates that the first 128 + bytes of the packet contents will be logged after the + headers.</para> + + <para><literal>first</literal> If the <literal>log</literal> + keyword is being used in conjunction with a <literal>keep + state</literal> option, it is recommended that this option is + also applied so that only the triggering packet is logged and + not every packet which thereafter matches the <quote>keep + state</quote> information.</para> + </sect3> + + <sect3> + <title>SELECTION</title> + + <para>The keywords described in this section are used to + describe attributes of the packet to be checked when + determining whether rules match or not. There is a + keyword subject, and it has sub-option keywords, one of + which has to be selected. The following general-purpose + attributes are provided for matching, and must be used in + this order:</para> + </sect3> + + <sect3> + <title>PROTO</title> + + <para><literal>proto</literal> is the subject keyword and must + be coded along with one of its corresponding keyword + sub-option values. The value allows a specific protocol to + be matched against. This option is a mandatory requirement + for the modernized rules processing logic.</para> + + <para><literal>tcp/udp | udp | tcp | icmp</literal> or any + protocol names found in <filename>/etc/protocols</filename> + are recognized and may be used. The special protocol keyword + <literal>tcp/udp</literal> may be used to match either a + <acronym>TCP</acronym> or a <acronym>UDP</acronym> packet, and has been added as + a convenience to save duplication of otherwise identical + rules.</para> + </sect3> + + <sect3> + <title>SRC_ADDR/DST_ADDR</title> + + <para>The <literal>all</literal> keyword is essentially a + synonym for <quote>from any to any</quote> with no other + match parameters.</para> + + <para><literal>from src to dst</literal>: the <literal>from</literal> and <literal>to</literal> + keywords are used to match against IP addresses. Rules must + specify <emphasis>both</emphasis> source and destination parameters. + <literal>any</literal> is a special keyword that matches any + IP address. Examples of use: <literal>from any to any</literal> + or <literal>from 0.0.0.0/0 to any</literal> or <literal>from any to + 0.0.0.0/0</literal> or <literal>from 0.0.0.0 to any</literal> or + <literal>from any to 0.0.0.0</literal>.</para> + + + <para>There is no way to match ranges of IP addresses which + do not express themselves easily using the dotted numeric + form / mask-length notation. The <filename + role="package">net-mgmt/ipcalc</filename> port may be used to + ease up the calculations. Additional information is available in + the utility's web page: <ulink + url="http://jodies.de/ipcalc"></ulink>.</para> + </sect3> + + <sect3> + <title>PORT</title> + + <para>If a port match is included, for either or both of source + and destination, then it is only applied to + <acronym>TCP</acronym> and <acronym>UDP</acronym> packets. When composing port + comparisons, either the service name from + <filename>/etc/services</filename> or an integer port number + may be used. When the port appears as part of the <literal>from</literal> + object, it matches the source port number; when it appears + as part of the <literal>to</literal> object, it matches the destination port + number. The use of the port option with the + <literal>to</literal> object is a mandatory requirement for + the modernized rules processing logic. Example of use: + <literal>from any to any port = 80</literal></para> + + <!-- XXX: Rewritten, but probably needs more changes --> + + <para>Single port comparisons may be done in a number of ways, using + a number of different comparison operators. Port ranges may also be + specified.</para> + + <para>port "=" | "!=" | "<" | ">" | "<=" | ">=" | + "eq" | "ne" | "lt" | "gt" | "le" | "ge".</para> + + <para>To specify port ranges, port "<>" | + "><"</para> + + <warning> + <para>Following the source and destination matching + parameters, the following two parameters are mandatory + requirements for the modernized rules processing + logic.</para> + </warning> + </sect3> + + <sect3> + <title><acronym>TCP</acronym>_FLAG</title> + + <para>Flags are only effective for <acronym>TCP</acronym> + filtering. The letters represent one of the possible flags + that can be matched against the <acronym>TCP</acronym> packet + header.</para> + + <para>The modernized rules processing logic uses the + <literal>flags S</literal> parameter to identify the tcp + session start request.</para> + </sect3> + + <sect3> + <title>STATEFUL</title> + + <para><literal>keep state</literal> indicates that on a pass + rule, any packets that match the rules selection parameters + should activate the stateful filtering facility.</para> + + <note> + <para>This option is a mandatory requirement for the + modernized rules processing logic.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>Stateful Filtering</title> + + <indexterm> + <primary>IPFILTER</primary> + + <secondary>stateful filtering</secondary> + </indexterm> + + <!-- XXX: duplicated --> + + <para>Stateful filtering treats traffic as a bi-directional + exchange of packets comprising a session conversation. When + activated, keep-state dynamically generates internal rules for + each anticipated packet being exchanged during the + bi-directional session conversation. It has sufficient matching + capabilities to determine if the session conversation between the + originating sender and the destination are following the valid + procedure of bi-directional packet exchange. Any packets that + do not properly fit the session conversation template are + automatically rejected as impostors.</para> + + <para>Keep state will also allow <acronym>ICMP</acronym> packets related to a + <acronym>TCP</acronym> or <acronym>UDP</acronym> session through. So if you get + <acronym>ICMP</acronym> type 3 code 4 in response to some web surfing allowed out + by a keep state rule, they will be automatically allowed in. + Any packet that IPF can be certain is part of an active + session, even if it is a different protocol, will be let + in.</para> + + <para>What happens is:</para> + + <para>Packets destined to go out through the interface connected to the + public Internet are first checked against the dynamic state + table. If the packet matches the next expected packet + comprising an active session conversation, then it exits the + firewall and the state of the session conversation flow is + updated in the dynamic state table. Packets that do not belong to + an already active session, are simply checked against the outbound + ruleset.</para> + + <para>Packets coming in from the interface connected to the public + Internet are first checked against the dynamic state table. If + the packet matches the next expected packet comprising an + active session conversation, then it exits the firewall and + the state of the session conversation flow is updated in the + dynamic state table. Packets that do not belong to an already active + session, are simply checked against the inbound ruleset.</para> + + <para>When the conversation completes it is removed from the + dynamic state table.</para> + + <para>Stateful filtering allows you to focus on blocking/passing + new sessions. If the new session is passed, all its subsequent + packets will be allowed through automatically and any impostors + automatically rejected. If a new session is blocked, none of + its subsequent packets will be allowed through. Stateful + filtering has technically advanced matching abilities + capable of defending against the flood of different attack + methods currently employed by attackers.</para> + </sect2> + + <sect2> + <!-- XXX: This section needs a rewrite --> + + <title>Inclusive Ruleset Example</title> + + <para>The following ruleset is an example of how to code a very + secure inclusive type of firewall. An inclusive firewall only + allows services matching <literal>pass</literal> rules through, and blocks all + others by default. Firewalls intended to protect other machines, + also called <quote>network firewalls</quote>, should have at least + two interfaces, which are generally configured to trust one side + (the <acronym>LAN</acronym>) and not the other (the public Internet). Alternatively, + a firewall might be configured to protect only the system it is + running on—this is called a + <quote>host based firewall</quote>, and is particularly appropriate + for servers on an untrusted network.</para> + + <para>All &unix; flavored systems including &os; are designed to + use interface <devicename>lo0</devicename> and IP address + <hostid role="ipaddr">127.0.0.1</hostid> for internal + communication within the operating system. The firewall rules + must contain rules to allow free unmolested movement of these + special internally used packets.</para> + + <para>The interface which faces the public Internet is the one + to place the rules that authorize and control access of the outbound + and inbound connections. This can be your user PPP + <devicename>tun0</devicename> interface or your NIC that is + connected to your DSL or cable modem.</para> + + <para>In cases where one or more NICs are cabled to private network + segments, those interfaces may require rules to allow packets + originating from those LAN interfaces transit to each other and/or + to the outside (Internet).</para> + + <para>The rules should be organized into three major + sections: first trusted interfaces, then the public + interface outbound, and last the public untrusted interface inbound.</para> + + <para>The rules in each of the public interface sections should + have the most frequently matched rules placed before less + commonly matched rules, with the last rule in the section + blocking and logging all packets on that interface and + direction.</para> + + <para>The Outbound section in the following ruleset only + contains <literal>pass</literal> rules which contain selection values that + uniquely identify the service that is authorized for public + Internet access. All the rules have the <literal>quick</literal>, <literal>on</literal>, + <literal>proto</literal>, <literal>port</literal>, and <literal>keep state</literal> options set. The <literal>proto + tcp</literal> rules have the <literal>flag</literal> option included to identify the + session start request as the triggering packet to activate the + stateful facility.</para> + + <para>The Inbound section has all the blocking of undesirable + packets first, for two different reasons. The first is that + malicious packets may be partial matches for legitimate traffic. + These packets have to be discarded rather than allowed in, based on + their partial matches against <literal>allow</literal> rules. + The second reason is that known and uninteresting rejects may be + blocked silently, rather than being caught and logged by the last + rules in the section. The final rule in each section, blocks and + logs all packets and can be used to create the legal evidence needed + to prosecute the people who are attacking your system.</para> + + <para>Another thing that should be taken care of, is to ensure there is no + response returned for any of the undesirable traffic. Invalid + packets should just get dropped and vanish. This way the attacker + has no knowledge if his packets have reached your system. The + less the attackers can learn about your system, the more + time they must invest before actually doing something bad. + Rules that include a <literal>log first</literal> option, will only + log the event the first time they are triggered. This option is + included in the sample <literal>nmap OS fingerprint</literal> rule. + The <filename role="package">security/nmap</filename> utility is + commonly used by attackers who attempt to identify the operating + system of your server.</para> + + <para>Any time there are logged messages on a rule with + the <literal>log first</literal> option, an <command>ipfstat -hio</command> + command should be executed to evaluate how many times the rule has + actually matched. Large number of matches usually indicate that the + system is being flooded (i.e.: under attack).</para> + + <para>The <filename>/etc/services</filename> file may be used to + lookup unknown port numbers. Alternatively, + visit <ulink + url="http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers"></ulink> + and do a port number lookup to find the purpose of a particular + port number.</para> + + <para>Check out this link for port numbers used by Trojans <ulink + url="http://www.sans.org/security-resources/idfaq/oddports.php"></ulink>.</para> + + <para>The following ruleset creates a complete and very secure + <literal>inclusive</literal> type of firewall ruleset that has been + tested on production systems. It can be easily modified for your + own system. Just comment out any <literal>pass</literal> rules for + services that should not be authorized.</para> + + <para>To avoid logging unwanted messages, + just add a <literal>block</literal> rule in the inbound section.</para> + + <para>The <devicename>dc0</devicename> interface name has to be changed + in every rule to the real interface name of the NIC + card that connects your system to the public Internet. For + user PPP it would be <devicename>tun0</devicename>.</para> + + <para>Add the following statements to + <filename>/etc/ipf.rules</filename>:</para> + + <programlisting>################################################################# +# No restrictions on Inside LAN Interface for private network +# Not needed unless you have LAN +################################################################# + +#pass out quick on xl0 all +#pass in quick on xl0 all + +################################################################# +# No restrictions on Loopback Interface +################################################################# +pass in quick on lo0 all +pass out quick on lo0 all + +################################################################# +# Interface facing Public Internet (Outbound Section) +# Match session start requests originating from behind the +# firewall on the private network +# or from this gateway server destined for the public Internet. +################################################################# + +# Allow out access to my ISP's Domain name server. +# xxx must be the IP address of your ISP's DNS. +# Dup these lines if your ISP has more than one DNS server +# Get the IP addresses from /etc/resolv.conf file +pass out quick on dc0 proto tcp from any to xxx port = 53 flags S keep state +pass out quick on dc0 proto udp from any to xxx port = 53 keep state + +# Allow out access to my ISP's DHCP server for cable or DSL networks. +# This rule is not needed for 'user ppp' type connection to the +# public Internet, so you can delete this whole group. +# Use the following rule and check log for IP address. +# Then put IP address in commented out rule & delete first rule +pass out log quick on dc0 proto udp from any to any port = 67 keep state +#pass out quick on dc0 proto udp from any to z.z.z.z port = 67 keep state + + +# Allow out non-secure standard www function +pass out quick on dc0 proto tcp from any to any port = 80 flags S keep state + +# Allow out secure www function https over TLS SSL +pass out quick on dc0 proto tcp from any to any port = 443 flags S keep state + +# Allow out send & get email function +pass out quick on dc0 proto tcp from any to any port = 110 flags S keep state +pass out quick on dc0 proto tcp from any to any port = 25 flags S keep state + +# Allow out Time +pass out quick on dc0 proto tcp from any to any port = 37 flags S keep state + +# Allow out nntp news +pass out quick on dc0 proto tcp from any to any port = 119 flags S keep state + +# Allow out gateway & LAN users' non-secure FTP ( both passive & active modes) +# This function uses the IP<acronym>NAT</acronym> built in FTP proxy function coded in +# the nat rules file to make this single rule function correctly. +# If you want to use the pkg_add command to install application packages +# on your gateway system you need this rule. +pass out quick on dc0 proto tcp from any to any port = 21 flags S keep state + +# Allow out ssh/sftp/scp (telnet/rlogin/FTP replacements) +# This function is using SSH (secure shell) +pass out quick on dc0 proto tcp from any to any port = 22 flags S keep state + +# Allow out insecure Telnet +pass out quick on dc0 proto tcp from any to any port = 23 flags S keep state + +# Allow out FreeBSD CVSup +pass out quick on dc0 proto tcp from any to any port = 5999 flags S keep state + +# Allow out ping to public Internet +pass out quick on dc0 proto icmp from any to any icmp-type 8 keep state + +# Allow out whois from LAN to public Internet +pass out quick on dc0 proto tcp from any to any port = 43 flags S keep state + +# Block and log only the first occurrence of everything +# else that's trying to get out. +# This rule implements the default block +block out log first quick on dc0 all + +################################################################# +# Interface facing Public Internet (Inbound Section) +# Match packets originating from the public Internet +# destined for this gateway server or the private network. +################################################################# + +# Block all inbound traffic from non-routable or reserved address spaces +block in quick on dc0 from 192.168.0.0/16 to any #RFC 1918 private IP +block in quick on dc0 from 172.16.0.0/12 to any #RFC 1918 private IP +block in quick on dc0 from 10.0.0.0/8 to any #RFC 1918 private IP +block in quick on dc0 from 127.0.0.0/8 to any #loopback +block in quick on dc0 from 0.0.0.0/8 to any #loopback +block in quick on dc0 from 169.254.0.0/16 to any #DHCP auto-config +block in quick on dc0 from 192.0.2.0/24 to any #reserved for docs +block in quick on dc0 from 204.152.64.0/23 to any #Sun cluster interconnect +block in quick on dc0 from 224.0.0.0/3 to any #Class D & E multicast + +##### Block a bunch of different nasty things. ############ +# That I do not want to see in the log + +# Block frags +block in quick on dc0 all with frags + +# Block short tcp packets +block in quick on dc0 proto tcp all with short + +# block source routed packets +block in quick on dc0 all with opt lsrr +block in quick on dc0 all with opt ssrr + +# Block nmap OS fingerprint attempts +# Log first occurrence of these so I can get their IP address +block in log first quick on dc0 proto tcp from any to any flags FUP + +# Block anything with special options +block in quick on dc0 all with ipopts + +# Block public pings +block in quick on dc0 proto icmp all icmp-type 8 + +# Block ident +block in quick on dc0 proto tcp from any to any port = 113 + +# Block all Netbios service. 137=name, 138=datagram, 139=session +# Netbios is MS/Windows sharing services. +# Block MS/Windows hosts2 name server requests 81 +block in log first quick on dc0 proto tcp/udp from any to any port = 137 +block in log first quick on dc0 proto tcp/udp from any to any port = 138 +block in log first quick on dc0 proto tcp/udp from any to any port = 139 +block in log first quick on dc0 proto tcp/udp from any to any port = 81 + +# Allow traffic in from ISP's DHCP server. This rule must contain +# the IP address of your ISP's DHCP server as it's the only +# authorized source to send this packet type. Only necessary for +# cable or DSL configurations. This rule is not needed for +# 'user ppp' type connection to the public Internet. +# This is the same IP address you captured and +# used in the outbound section. +pass in quick on dc0 proto udp from z.z.z.z to any port = 68 keep state + +# Allow in standard www function because I have apache server +pass in quick on dc0 proto tcp from any to any port = 80 flags S keep state + +# Allow in non-secure Telnet session from public Internet +# labeled non-secure because ID/PW passed over public Internet as clear text. +# Delete this sample group if you do not have telnet server enabled. +#pass in quick on dc0 proto tcp from any to any port = 23 flags S keep state + +# Allow in secure FTP, Telnet, and SCP from public Internet +# This function is using SSH (secure shell) +pass in quick on dc0 proto tcp from any to any port = 22 flags S keep state + +# Block and log only first occurrence of all remaining traffic +# coming into the firewall. The logging of only the first +# occurrence avoids filling up disk with Denial of Service logs. +# This rule implements the default block. +block in log first quick on dc0 all +################### End of rules file #####################################</programlisting> + </sect2> + + <sect2> + <title><acronym>NAT</acronym></title> + + <indexterm><primary>NAT</primary></indexterm> + + <indexterm> + <primary>IP masquerading</primary> + + <see>NAT</see> + </indexterm> + + <indexterm> + <primary>network address translation</primary> + + <see>NAT</see> + </indexterm> + + <para><acronym>NAT</acronym> stands for <emphasis>Network Address + Translation</emphasis>. To those familiar with &linux;, this concept is + called IP Masquerading; <acronym>NAT</acronym> and IP + Masquerading are the same thing. One of the many things the + IPF <acronym>NAT</acronym> function enables is the ability to + have a private Local Area Network (LAN) behind the firewall + sharing a single ISP assigned IP address on the public + Internet.</para> + + <para>You may ask why would someone want to do this. ISPs + normally assign a dynamic IP address to their non-commercial + users. Dynamic means that the IP address can be different each + time you dial in and log on to your ISP, or for cable and DSL + modem users, when the modem is power cycled. This dynamic IP + address is used to identify your system to the public Internet.</para> + + <para>Now lets say you have five PCs at home and each one needs + Internet access. You would have to pay your ISP for an + individual Internet account for each PC and have five phone + lines.</para> + + <para>With <acronym>NAT</acronym> only a single account is needed + with your ISP. The other four PCs may then be cabled to a switch and + the switch to the NIC in your &os; system which is going to + service your LAN as a gateway. <acronym>NAT</acronym> will + automatically translate the private LAN IP address for each + separate PC on the LAN to the single public IP address as it + exits the firewall bound for the public Internet. It also does + the reverse translation for returning packets.</para> + + <para>There is a special range of IP addresses reserved for + <acronym>NAT</acronym>ed private LANs. According to + RFC 1918, the following IP ranges may be used for private nets + which will never be routed directly to the public + Internet:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"> + + <colspec colwidth="1*"> + + <colspec colwidth="1*"> + + <tbody> + <row> + <entry>Start IP <hostid role="ipaddr">10.0.0.0</hostid></entry> + + <entry>-</entry> + + <entry>Ending IP <hostid role="ipaddr">10.255.255.255</hostid></entry> + </row> + + <row> + <entry>Start IP <hostid role="ipaddr">172.16.0.0</hostid></entry> + + <entry>-</entry> + + <entry>Ending IP <hostid role="ipaddr">172.31.255.255</hostid></entry> + </row> + + <row> + <entry>Start IP <hostid role="ipaddr">192.168.0.0</hostid></entry> + + <entry>-</entry> + + <entry>Ending IP <hostid role="ipaddr">192.168.255.255</hostid></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + + <sect2> + <title>IP<acronym>NAT</acronym></title> + + <indexterm> + <primary>NAT</primary> + + <secondary>and IPFILTER</secondary> + </indexterm> + + <indexterm><primary><command>ipnat</command></primary></indexterm> + + <para><acronym>NAT</acronym> rules are loaded by using the + <command>ipnat</command> command. Typically the + <acronym>NAT</acronym> rules are stored in + <filename>/etc/ipnat.rules</filename>. See &man.ipnat.1; for + details.</para> + + <para>When changing the <acronym>NAT</acronym> rules after + <acronym>NAT</acronym> has been started, make your changes to + the file containing the NAT rules, then run the <command>ipnat</command> command with + the <option>-CF</option> flags to delete the internal in use + <acronym>NAT</acronym> rules and flush the contents of the + translation table of all active entries.</para> + + <para>To reload the <acronym>NAT</acronym> rules issue a command + like this:</para> + + <screen>&prompt.root; <userinput>ipnat -CF -f /etc/ipnat.rules</userinput></screen> + + <para>To display some statistics about your + <acronym>NAT</acronym>, use this command:</para> + + <screen>&prompt.root; <userinput>ipnat -s</userinput></screen> + + <para>To list the <acronym>NAT</acronym> table's current + mappings, use this command:</para> + + <screen>&prompt.root; <userinput>ipnat -l</userinput></screen> + + <para>To turn verbose mode on, and display information relating + to rule processing and active rules/table entries:</para> + + <screen>&prompt.root; <userinput>ipnat -v</userinput></screen> + </sect2> + + <sect2> + <title>IP<acronym>NAT</acronym> Rules</title> + + <para><acronym>NAT</acronym> rules are very flexible and can + accomplish many different things to fit the needs of commercial + and home users.</para> + + <para>The rule syntax presented here has been simplified to what + is most commonly used in a non-commercial environment. For a + complete rule syntax description see the &man.ipnat.5; manual + page.</para> + + <para>The syntax for a <acronym>NAT</acronym> rule looks + something like this:</para> + + <programlisting>map <replaceable>IF</replaceable> <replaceable>LAN_IP_RANGE</replaceable> -> <replaceable>PUBLIC_ADDRESS</replaceable></programlisting> + + <para>The keyword <literal>map</literal> starts the rule.</para> + + <para>Replace <replaceable>IF</replaceable> with the external + interface.</para> + + <para>The <replaceable>LAN_IP_RANGE</replaceable> is what your + internal clients use for IP Addressing, usually this is + something like <hostid + role="ipaddr">192.168.1.0/24</hostid>.</para> + + <para>The <replaceable>PUBLIC_ADDRESS</replaceable> can either + be the external IP address or the special keyword + <literal>0/32</literal>, which means to use the IP address + assigned to <replaceable>IF</replaceable>.</para> + </sect2> + + <sect2> + <title>How <acronym>NAT</acronym> works</title> + + <para>A packet arrives at the firewall from the LAN with a public + destination. It passes through the outbound filter rules, + <acronym>NAT</acronym> gets its turn at the packet and applies + its rules top down, first matching rule wins. + <acronym>NAT</acronym> tests each of its rules against the + packet's interface name and source IP address. When a packet's + interface name matches a <acronym>NAT</acronym> rule then the + source IP address (i.e.: private LAN IP address) of the packet + is checked to see if it falls within the IP address range + specified to the left of the arrow symbol on the + <acronym>NAT</acronym> rule. On a match the packet has its + source IP address rewritten with the public IP address + obtained by the <literal>0/32</literal> keyword. + <acronym>NAT</acronym> posts an entry in its internal + <acronym>NAT</acronym> table so when the packet returns from + the public Internet it can be mapped back to its original + private IP address and then passed to the filter rules for + processing.</para> + </sect2> + + <sect2> + <title>Enabling IP<acronym>NAT</acronym></title> + + <para>To enable IP<acronym>NAT</acronym> add these statements to + <filename>/etc/rc.conf</filename>.</para> + + <para>To enable your machine to route traffic between + interfaces:</para> + + <programlisting>gateway_enable="YES"</programlisting> + + <para>To start IP<acronym>NAT</acronym> automatically each + time:</para> + + <programlisting>ipnat_enable="YES"</programlisting> + + <para>To specify where to load the IP<acronym>NAT</acronym> rules + from:</para> + + <programlisting>ipnat_rules="/etc/ipnat.rules"</programlisting> + </sect2> + + <sect2> + <title><acronym>NAT</acronym> for a Large LAN</title> + + <para>For networks that have large numbers of PC's on the LAN or + networks with more than a single LAN, the process of funneling + all those private IP addresses into a single public IP address + becomes a resource problem that may cause problems with the + same port numbers being used many times across many + <acronym>NAT</acronym>ed LAN PC's, causing collisions. There + are two ways to relieve this resource problem.</para> + + <sect3> + <title>Assigning Ports to Use</title> + + <!-- What does it mean ? Is there something missing ?--> + <!-- XXXBLAH <- Apparently you can't start a sect + with a <programlisting> tag ?--> + + <para>A normal NAT rule would look like:</para> + + <programlisting>map dc0 192.168.1.0/24 -> 0/32</programlisting> + + <para>In the above rule the packet's source port is unchanged + as the packet passes through IP<acronym>NAT</acronym>. By + adding the <literal>portmap</literal> keyword, + IP<acronym>NAT</acronym> can be directed to only use source ports in the specified range. + For example the following rule will tell + IP<acronym>NAT</acronym> to modify the source port to be + within the range shown:</para> + + <programlisting>map dc0 192.168.1.0/24 -> 0/32 portmap tcp/udp 20000:60000</programlisting> + + <para>Additionally we can make things even easier by using the + <literal>auto</literal> keyword to tell + IP<acronym>NAT</acronym> to determine by itself which ports + are available to use:</para> + + <programlisting>map dc0 192.168.1.0/24 -> 0/32 portmap tcp/udp auto</programlisting> + </sect3> + + <sect3> + <title>Using a Pool of Public Addresses</title> + + <para>In very large LANs there comes a point where there are just too + many LAN addresses to fit into a single public address. If a block + of public IP addresses is available, these addresses can be used as + a <quote>pool</quote>, and IP<acronym>NAT</acronym> may pick one of + the public IP addresses as packet-addresses are mapped on their way + out.</para> + + <para>For example, instead of mapping all packets through a single + public IP address, as in:</para> + + <programlisting>map dc0 192.168.1.0/24 -> 204.134.75.1</programlisting> + + <para>A range of public IP addresses can be specified either with a + netmask:</para> + + <programlisting>map dc0 192.168.1.0/24 -> 204.134.75.0/255.255.255.0</programlisting> + + <para>or using CIDR notation:</para> + + <programlisting>map dc0 192.168.1.0/24 -> 204.134.75.0/24</programlisting> + </sect3> + </sect2> + + <sect2> + <title>Port Redirection</title> + + <para>A very common practice is to have a web server, email + server, database server and DNS server each segregated to a + different PC on the LAN. In this case the traffic from these + servers still have to be <acronym>NAT</acronym>ed, but there + has to be some way to direct the inbound traffic to the + correct LAN PCs. IP<acronym>NAT</acronym> has the redirection + facilities of <acronym>NAT</acronym> to solve this problem. + For example, assuming a web server operating on LAN address <hostid + role="ipaddr">10.0.10.25</hostid> and using a single public IP + address of <hostid role="ipaddr">20.20.20.5</hostid> the rule would + be coded as follows:</para> + + <programlisting>rdr dc0 20.20.20.5/32 port 80 -> 10.0.10.25 port 80</programlisting> + + <para>or:</para> + + <programlisting>rdr dc0 0.0.0.0/0 port 80 -> 10.0.10.25 port 80</programlisting> + + <para>or for a LAN DNS Server on LAN address of <hostid + role="ipaddr">10.0.10.33</hostid> that needs to receive + public DNS requests:</para> + + <programlisting>rdr dc0 20.20.20.5/32 port 53 -> 10.0.10.33 port 53 udp</programlisting> + </sect2> + + <sect2> + <title>FTP and <acronym>NAT</acronym></title> + + <para>FTP is a dinosaur left over from the time before the + Internet as it is known today, when research universities were + leased lined together and FTP was used to share files among + research Scientists. This was a time when data security was + not a consideration. Over the years the FTP protocol became + buried into the backbone of the emerging Internet and its + username and password being sent in clear text was never + changed to address new security concerns. FTP has two flavors, + it can run in active mode or passive mode. The difference is + in how the data channel is acquired. Passive mode is more + secure as the data channel is acquired by the ordinal ftp + session requester. For a real good explanation of FTP and the + different modes see <ulink + url="http://www.slacksite.com/other/ftp.html"></ulink>.</para> + + <sect3> + <title>IP<acronym>NAT</acronym> Rules</title> + + <para>IP<acronym>NAT</acronym> has a special built in FTP proxy + option which can be specified on the <acronym>NAT</acronym> + map rule. It can monitor all outbound packet traffic for FTP + active or passive start session requests and dynamically + create temporary filter rules containing only the port number + really in use for the data channel. This eliminates the + security risk FTP normally exposes the firewall to from + having large ranges of high order port numbers open.</para> + + <para>This rule will handle all the traffic for the internal + LAN:</para> + + <programlisting>map dc0 10.0.10.0/29 -> 0/32 proxy port 21 ftp/tcp</programlisting> + + <para>This rule handles the FTP traffic from the + gateway:</para> + + <programlisting>map dc0 0.0.0.0/0 -> 0/32 proxy port 21 ftp/tcp</programlisting> + + <para>This rule handles all non-FTP traffic from the internal + LAN:</para> + + <programlisting>map dc0 10.0.10.0/29 -> 0/32</programlisting> + + <para>The FTP map rule goes before our regular map rule. All + packets are tested against the first rule from the top. + Matches on interface name, then private LAN source IP + address, and then is it a FTP packet. If all that matches + then the special FTP proxy creates temp filter rules to let + the FTP session packets pass in and out, in addition to also + <acronym>NAT</acronym>ing the FTP packets. All LAN packets + that are not FTP do not match the first rule and fall + through to the third rule and are tested, matching on + interface and source IP, then are + <acronym>NAT</acronym>ed.</para> + </sect3> + + <sect3> + <title>IP<acronym>NAT</acronym> FTP Filter Rules</title> + + <para>Only one filter rule is needed for FTP if the + <acronym>NAT</acronym> FTP proxy is used.</para> + + <para>Without the FTP Proxy, the following three rules will be + needed:</para> + + <programlisting># Allow out LAN PC client FTP to public Internet +# Active and passive modes +pass out quick on rl0 proto tcp from any to any port = 21 flags S keep state + +# Allow out passive mode data channel high order port numbers +pass out quick on rl0 proto tcp from any to any port > 1024 flags S keep state + +# Active mode let data channel in from FTP server +pass in quick on rl0 proto tcp from any to any port = 20 flags S keep state</programlisting> + </sect3> + </sect2> + </sect1> + + <sect1 id="firewalls-ipfw"> + <title>IPFW</title> + + <indexterm> + <primary>firewall</primary> + + <secondary>IPFW</secondary> + </indexterm> + + <para>The IPFIREWALL (<acronym>IPFW</acronym>) is a &os; sponsored firewall software + application authored and maintained by &os; volunteer staff + members. It uses the legacy stateless rules and a legacy rule + coding technique to achieve what is referred to as Simple + Stateful logic.</para> + + <para>The IPFW sample ruleset (found in + <filename>/etc/rc.firewall</filename> and + <filename>/etc/rc.firewall6</filename>) in the standard &os; + install is rather simple and it is not expected to be used + directly without modifications. The example does not use + stateful filtering, which is beneficial in most setups, so it + will not be used as base for this section.</para> + + <para>The IPFW stateless rule syntax is empowered with technically + sophisticated selection capabilities which far surpasses the + knowledge level of the customary firewall installer. IPFW is + targeted at the professional user or the advanced technical + computer hobbyist who have advanced packet selection + requirements. A high degree of detailed knowledge into how + different protocols use and create their unique packet header + information is necessary before the power of the IPFW rules can + be unleashed. Providing that level of explanation is out of the + scope of this section of the Handbook.</para> + + <para>IPFW is composed of seven components, the primary component + is the kernel firewall filter rule processor and its integrated + packet accounting facility, the logging facility, the <literal>divert</literal> + rule which triggers the <acronym>NAT</acronym> facility, and the + advanced special purpose facilities, the dummynet traffic shaper + facilities, the <literal>fwd rule</literal> forward facility, the bridge + facility, and the ipstealth facility. IPFW supports both IPv4 + and IPv6.</para> + + <sect2 id="firewalls-ipfw-enable"> + <title>Enabling IPFW</title> + + <indexterm> + <primary>IPFW</primary> + + <secondary>enabling</secondary> + </indexterm> + + <para>IPFW is included in the basic &os; install as a separate + run time loadable module. The system will dynamically load the + kernel module when the <filename>rc.conf</filename> statement + <literal>firewall_enable="YES"</literal> is used. There is no + need to compile IPFW into the &os; kernel unless + <acronym>NAT</acronym> functionality is desired.</para> + + <para>After rebooting your system with + <literal>firewall_enable="YES"</literal> in + <filename>rc.conf</filename> the following white highlighted + message is displayed on the screen as part of the boot + process:</para> + + <screen>ipfw2 initialized, divert disabled, rule-based forwarding disabled, default to deny, logging disabled</screen> + + <para>The loadable module does have logging ability + compiled in. To enable logging and set the verbose logging + limit, there is a knob that can be set in + <filename>/etc/sysctl.conf</filename>. By adding these + statements, logging will be enabled on future reboots:</para> + + <programlisting>net.inet.ip.fw.verbose=1 +net.inet.ip.fw.verbose_limit=5</programlisting> + </sect2> + + <sect2 id="firewalls-ipfw-kernel"> + <title>Kernel Options</title> + + <indexterm> + <primary>kernel options</primary> + + <secondary>IPFIREWALL</secondary> + </indexterm> + + <indexterm> + <primary>kernel options</primary> + + <secondary>IPFIREWALL_VERBOSE</secondary> + </indexterm> + + <indexterm> + <primary>kernel options</primary> + + <secondary>IPFIREWALL_VERBOSE_LIMIT</secondary> + </indexterm> + + <indexterm> + <primary>IPFW</primary> + + <secondary>kernel options</secondary> + </indexterm> + + <para>It is not a mandatory requirement to enable IPFW by + compiling the following options into the &os; kernel, unless + <acronym>NAT</acronym> functionality is required. It is presented here + as background information.</para> + + <programlisting>options IPFIREWALL</programlisting> + + <para>This option enables IPFW as part of the kernel</para> + + <programlisting>options IPFIREWALL_VERBOSE</programlisting> + + <para>Enables logging of packets that pass through IPFW and have + the <literal>log</literal> keyword specified in the ruleset.</para> + + <programlisting>options IPFIREWALL_VERBOSE_LIMIT=5</programlisting> + + <para>Limits the number of packets logged through &man.syslogd.8; + on a per entry basis. This option may be used in + hostile environments, when firewall activity logging is desired. + This will close a possible denial of service attack via syslog + flooding.</para> + + <indexterm> + <primary>kernel options</primary> + + <secondary>IPFIREWALL_DEFAULT_TO_ACCEPT</secondary> + </indexterm> + + <programlisting>options IPFIREWALL_DEFAULT_TO_ACCEPT</programlisting> + + <para>This option will allow everything to pass through the + firewall by default, which is a good idea when the firewall is being + set up for the first time.</para> + + <indexterm> + <primary>kernel options</primary> + + <secondary>IPDIVERT</secondary> + </indexterm> + + <programlisting>options IPDIVERT</programlisting> + + <para>This enables the use of <acronym>NAT</acronym> + functionality.</para> + + <note> + <para>The firewall will block all incoming and outgoing packets if + either the <literal>IPFIREWALL_DEFAULT_TO_ACCEPT</literal> kernel + option or a rule to explicitly allow these connections are + missing.</para> + </note> + </sect2> + + <sect2 id="firewalls-ipfw-rc"> + <title><filename>/etc/rc.conf</filename> Options</title> + + <para>Enable the firewall:</para> + + <programlisting>firewall_enable="YES"</programlisting> + + <para>To select one of the default firewall types provided by + &os;, select one by reading the + <filename>/etc/rc.firewall</filename> file and place it in + the following:</para> + + <programlisting>firewall_type="open"</programlisting> + + <para>Available values for this setting are:</para> + + <itemizedlist> + <listitem> + <para><literal>open</literal> — pass all traffic.</para> + </listitem> + <listitem> + <para><literal>client</literal> — will protect only this + machine.</para> + </listitem> + <listitem> + <para><literal>simple</literal> — protect the whole + network.</para> + </listitem> + <listitem> + <para><literal>closed</literal> — entirely disables IP + traffic except for the loopback interface.</para> + </listitem> + <listitem> + <para><literal>UNKNOWN</literal> — disables the loading + of firewall rules.</para> + </listitem> + <listitem> + <para><filename><replaceable>filename</replaceable></filename> — absolute path of + file containing firewall rules.</para> + </listitem> + </itemizedlist> + + <para>It is possible to use two different ways to load custom + rules for <application>ipfw</application> firewall. One is + by setting <literal>firewall_type</literal> variable to absolute + path of file, which contains <emphasis>firewall rules</emphasis> + without any command-line options for &man.ipfw.8; itself. + The following is a simple example of a ruleset file that blocks + all incoming and outgoing traffic:</para> + + <programlisting>add deny in +add deny out</programlisting> + + <para>On the other hand, it is possible to set the + <literal>firewall_script</literal> variable to the absolute path of an + executable script that includes <command>ipfw</command> commands + being executed at system boot time. A valid ruleset script that + would be equivalent to the ruleset file shown above would + be the following:</para> + + <programlisting>#!/bin/sh + +ipfw -q flush + +ipfw add deny in +ipfw add deny out</programlisting> + + <note> + <para>If <literal>firewall_type</literal> is set to either + <literal>client</literal> or <literal>simple</literal>, the + default rules found in <filename>/etc/rc.firewall</filename> + should be reviewed to fit to the configuration of the given + machine. Also note that the examples used in this chapter + expect that the <literal>firewall_script</literal> is set to + <filename>/etc/ipfw.rules</filename>.</para> + </note> + + <para>Enable logging:</para> + + <programlisting>firewall_logging="YES"</programlisting> + + <warning> + <para>The only thing that the + <varname>firewall_logging</varname> variable will do is + setting the <varname>net.inet.ip.fw.verbose</varname> sysctl + variable to the value of <literal>1</literal> (see <xref + linkend="firewalls-ipfw-enable">). There is no + <filename>rc.conf</filename> variable to set log limitations, + but it can be set via sysctl variable, manually or from the + <filename>/etc/sysctl.conf</filename> file:</para> + + <programlisting>net.inet.ip.fw.verbose_limit=5</programlisting> + </warning> + + <para>If your machine is acting as a gateway, i.e., providing + Network Address Translation (NAT) via &man.natd.8;, please + refer to <xref linkend="network-natd"> for information + regarding the required <filename>/etc/rc.conf</filename> + options.</para> + </sect2> + + <sect2 id="firewalls-ipfw-cmd"> + <title>The IPFW Command</title> + + <indexterm><primary><command>ipfw</command></primary></indexterm> + + <para>The <command>ipfw</command> command is the normal vehicle for making manual + single rule additions or deletions to the active firewall + internal rules while it is running. The problem with using + this method is once your system is shutdown or halted all the + rules that were added, changed or deleted are lost. Writing all + your rules in a file and using that file to load the rules at + boot time, or to replace in mass the currently running firewall + rules with changes you made to the files content, is the + recommended method used here.</para> + + <para>The <command>ipfw</command> command is still a very useful way to display the + running firewall rules to the console screen. The IPFW + accounting facility dynamically creates a counter for each + rule that counts each packet that matches the rule. During the + process of testing a rule, listing the rule with its counter + is one of the ways of determining if the rule is + functioning.</para> + + <para>To list all the rules in sequence:</para> + + <screen>&prompt.root; <userinput>ipfw list</userinput></screen> + + <para>To list all the rules with a time stamp of when the last + time the rule was matched:</para> + + <screen>&prompt.root; <userinput>ipfw -t list</userinput></screen> + + <para>The next example lists accounting information, the packet count for + matched rules along with the rules themselves. The first + column is the rule number, followed by the number of outgoing + matched packets, followed by the number of incoming matched + packets, and then the rule itself.</para> + + <screen>&prompt.root; <userinput>ipfw -a list</userinput></screen> + + <para>List the dynamic rules in addition to the static + rules:</para> + + <screen>&prompt.root; <userinput>ipfw -d list</userinput></screen> + + <para>Also show the expired dynamic rules:</para> + + <screen>&prompt.root; <userinput>ipfw -d -e list</userinput></screen> + + <para>Zero the counters:</para> + + <screen>&prompt.root; <userinput>ipfw zero</userinput></screen> + + <para>Zero the counters for just the rule with number + <replaceable>NUM</replaceable>:</para> + + <screen>&prompt.root; <userinput>ipfw zero <replaceable>NUM</replaceable></userinput></screen> + </sect2> + + <sect2 id="firewalls-ipfw-rules"> + <title>IPFW Rulesets</title> + + <!-- This has already appeared once --> + + <para>A ruleset is a group of IPFW rules coded to allow or deny + packets based on the values contained in the packet. The + bi-directional exchange of packets between hosts comprises a + session conversation. The firewall ruleset processes both the + packets arriving from the public Internet, as well as the packets + originating from the system as a response to them. + Each <acronym>TCP/IP</acronym> service (i.e.: telnet, www, + mail, etc.) is predefined by its protocol and privileged (listening) + port. Packets destined for a specific service, originate from the + source address using an unprivileged (high order) port and target + the specific service port on the destination address. All the above + parameters (i.e., ports and addresses) can be used as selection + criteria to create rules which will pass or block services.</para> + + <indexterm> + <primary>IPFW</primary> + + <secondary>rule processing order</secondary> + </indexterm> + + <!-- Needs rewording to include note below --> + + <para>When a packet enters the firewall it is compared against + the first rule in the ruleset and progresses one rule at a time + moving from top to bottom of the set in ascending rule number + sequence order. When the packet matches the selection parameters + of a rule, the rules' action field value is executed and the + search of the ruleset terminates for that packet. This is + referred to as <quote>the first match wins</quote> search + method. If the packet does not match any of the rules, it gets + caught by the mandatory IPFW default rule, number 65535 which + denies all packets and discards them without any reply back to + the originating destination.</para> + + <note> + <para>The search continues after <literal>count</literal>, + <literal>skipto</literal> and <literal>tee</literal> + rules.</para> + </note> + + <para>The instructions contained here are based on using rules + that contain the stateful <literal>keep state</literal>, <literal>limit</literal>, <literal>in</literal>, <literal>out</literal> + and <literal>via</literal> options. This is the basic framework for coding an + inclusive type firewall ruleset.</para> + + <warning> + <para>Be careful when working with firewall rules, as it is easy to + end up locking yourself out.</para> + </warning> + + <sect3 id="firewalls-ipfw-rules-syntax"> + <title>Rule Syntax</title> + + <indexterm> + <primary>IPFW</primary> + + <secondary>rule syntax</secondary> + </indexterm> + + <para>The rule syntax presented here has been simplified to + what is necessary to create a standard inclusive type + firewall ruleset. For a complete rule syntax description + see the &man.ipfw.8; manual page.</para> + + <para>Rules contain keywords: these keywords have to be coded + in a specific order from left to right on the line. Keywords + are identified in bold type. Some keywords have sub-options + which may be keywords them selves and also include more + sub-options.</para> + + <para><literal>#</literal> is used to mark the start of a + comment and may appear at the end of a rule line or on its + own lines. Blank lines are ignored.</para> + + <para><replaceable>CMD RULE_NUMBER ACTION LOGGING SELECTION + STATEFUL</replaceable></para> + + <sect4> + <title>CMD</title> + + <para>Each new rule has to be prefixed with + <parameter>add</parameter> to add the + rule to the internal table.</para> + </sect4> + + <sect4> + <title>RULE_NUMBER</title> + + <para>Each rule is associated with a rule_number in the range + 1..65535.</para> + </sect4> + + <sect4> + <title>ACTION</title> + + <para>A rule can be associated with one of the following + actions, which will be executed when the packet matches + the selection criterion of the rule.</para> + + <para><parameter>allow | accept | pass | + permit</parameter></para> + + <para>These all mean the same thing which is to allow packets + that match the rule to exit the firewall rule processing. + The search terminates at this rule.</para> + + <para><parameter>check-state</parameter></para> + + <para>Checks the packet against the dynamic rules table. If + a match is found, execute the action associated with the + rule which generated this dynamic rule, otherwise move to + the next rule. The check-state rule does not have + selection criterion. If no check-state rule is present in + the ruleset, the dynamic rules table is checked at the + first keep-state or limit rule.</para> + + <para><parameter>deny | drop</parameter></para> + + <para>Both words mean the same thing which is to discard + packets that match this rule. The search + terminates.</para> + </sect4> + + <sect4> + <title>Logging</title> + + <para><parameter>log</parameter> or + <parameter>logamount</parameter></para> + + <para>When a packet matches a rule with the <literal>log</literal> keyword, a + message will be logged to &man.syslogd.8; with a facility name of + SECURITY. The logging only occurs if the number of + packets logged so far for that particular rule does not + exceed the <literal>logamount</literal> parameter. If no <literal>logamount</literal> is + specified, the limit is taken from the sysctl variable + <literal>net.inet.ip.fw.verbose_limit</literal>. In both cases, a value of + zero removes the logging limit. Once the limit is + reached, logging can be re-enabled by clearing the + logging counter or the packet counter for that rule, see + the <command>ipfw reset log</command> command.</para> + + <note> + <para>Logging is done after + all other packet matching conditions have been + successfully verified, and before performing the final + action (accept, deny) on the packet. It is up to you to + decide which rules you want to enable logging on.</para> + </note> + </sect4> + + <sect4> + <title>Selection</title> + + <para>The keywords described in this section are used to + describe attributes of the packet to be checked when + determining whether rules match the packet or not. + The following general-purpose attributes are provided for + matching, and must be used in this order:</para> + + <para><parameter>udp | tcp | icmp</parameter></para> + + <para>Any other protocol names found in + <filename>/etc/protocols</filename> are also recognized and may + be used. The value specified is the protocol to be matched + against. This is a mandatory requirement.</para> + + <para><parameter>from src to dst</parameter></para> + + <para>The <literal>from</literal> and <literal>to</literal> keywords are used to match against IP + addresses. Rules must specify <emphasis>both</emphasis> source and destination + parameters. <literal>any</literal> is a special keyword + that matches any IP address. <literal>me</literal> is a + special keyword that matches any IP address configured on + an interface in your &os; system to represent the PC the + firewall is running on (i.e.: this box) as in <literal>from me to + any</literal> or <literal>from any to me</literal> or <literal>from 0.0.0.0/0 to any</literal> or + <literal>from any to 0.0.0.0/0</literal> or <literal>from 0.0.0.0 to any</literal> or <literal>from + any to 0.0.0.0</literal> or <literal>from me to 0.0.0.0</literal>. IP addresses are + specified as a dotted IP address numeric form/mask-length (CIDR notation), + or as single dotted IP address numeric form. This is a + mandatory requirement. The <filename + role="package">net-mgmt/ipcalc</filename> port may be used to + ease up the calculations. Additional + information is available in the utility's web page: <ulink + url="http://jodies.de/ipcalc"></ulink>.</para> + + <para><parameter>port number</parameter></para> + + <para>For protocols which support port numbers (such as + <acronym>TCP</acronym> and <acronym>UDP</acronym>), it is mandatory to + code the port number of the service that will be matched. + Service names (from + <filename>/etc/services</filename>) may be used instead of + numeric port values.</para> + + <para><parameter>in | out</parameter></para> + + <para>Matches incoming or outgoing packets, respectively. + The <literal>in</literal> and <literal>out</literal> are keywords and it is mandatory that + one or the other is coded as part of your rule matching + criterion.</para> + + <para><parameter>via IF</parameter></para> + + <para>Matches packets going through the interface specified + by exact name. The <literal>via</literal> keyword causes + the interface to always be checked as part of the match + process.</para> + + <para><parameter>setup</parameter></para> + + <para>This is a mandatory keyword that identifies the session + start request for <acronym>TCP</acronym> packets.</para> + + <para><parameter>keep-state</parameter></para> + + <para>This is a mandatory keyword. Upon a match, the + firewall will create a dynamic rule, whose default behavior + is to match bidirectional traffic between source and + destination IP/port using the same protocol.</para> + + <para><parameter>limit {src-addr | src-port | dst-addr | + dst-port}</parameter></para> + + <para>The firewall will only allow + <replaceable>N</replaceable> connections with the same set + of parameters as specified in the rule. One or more of + source and destination addresses and ports can be + specified. The <literal>limit</literal> and <literal>keep-state</literal> can not be used on the + same rule. The <literal>limit</literal> option provides the same stateful function as + <literal>keep-state</literal>, plus its own functions.</para> + </sect4> + </sect3> + + <sect3> + <title>Stateful Rule Option</title> + + <indexterm> + <primary>IPFW</primary> + + <secondary>stateful filtering</secondary> + </indexterm> + + <!-- XXX: duplicated --> + + <para>Stateful filtering treats traffic as a bi-directional + exchange of packets comprising a session conversation. It + has the matching capabilities to determine if the session + conversation between the originating sender and the + destination are following the valid procedure of + bi-directional packet exchange. Any packets that do not + properly fit the session conversation template are + automatically rejected as impostors.</para> + + <para>The <literal>check-state</literal> option is used to identify where in the IPFW rules + set the packet is to be tested against the dynamic rules + facility. On a match the packet exits the firewall to + continue on its way and a new rule is dynamically created for + the next anticipated packet being exchanged during this + bi-directional session conversation. On a no match the + packet advances to the next rule in the ruleset for + testing.</para> + + <para>The dynamic rules facility is vulnerable to resource + depletion from a SYN-flood attack which would open a huge + number of dynamic rules. To counter this attack, &os; + added another new option named <literal>limit</literal>. This + option is used to limit the number of simultaneous session + conversations by checking the rules source or + destinations fields as directed by the <literal>limit</literal> option and + using the packet's IP address found there, in a search of + the open dynamic rules counting the number of times this + rule and IP address combination occurred, if this count is + greater that the value specified on the <literal>limit</literal> option, the + packet is discarded.</para> + </sect3> + + <sect3> + <title>Logging Firewall Messages</title> + + <indexterm> + <primary>IPFW</primary> + + <secondary>logging</secondary> + </indexterm> + + <para>The benefits of logging are obvious: it provides the + ability to review after the fact the rules you activated + logging on which provides information like, what packets had + been dropped, what addresses they came from and where they were + going, giving you a significant edge in tracking down + attackers.</para> + + <para>Even with the logging facility enabled, IPFW will not + generate any rule logging on it's own. The firewall + administrator decides what rules in the ruleset will be + logged, and adds the <literal>log</literal> verb to those rules. Normally only + deny rules are logged, like the deny rule for incoming + <acronym>ICMP</acronym> pings. It is very customary to + duplicate the <quote>ipfw default deny everything</quote> rule with the + <literal>log</literal> verb included as your last rule in the ruleset. This + way it is possible to see all the packets that did not match any + of the rules in the ruleset.</para> + + <para>Logging is a two edged sword, if you are not careful, you + can lose yourself in the over abundance of log data and fill + your disk up with growing log files. DoS attacks that fill + up disk drives is one of the oldest attacks around. These + log messages are not only written to <application>syslogd</application>, but also are + displayed on the root console screen and soon become very + annoying.</para> + + <para>The <literal>IPFIREWALL_VERBOSE_LIMIT=5</literal> + kernel option limits the number of consecutive messages + sent to the system logger &man.syslogd.8;, concerning the packet + matching of a given rule. When this option is enabled in + the kernel, the number of consecutive messages concerning + a particular rule is capped at the number specified. There + is nothing to be gained from 200 log messages saying the + same identical thing. For instance, five consecutive + messages concerning a particular rule would be logged to + <application>syslogd</application>, the remainder identical consecutive messages would + be counted and posted to <application>syslogd</application> with a phrase like + the following:</para> + + <programlisting>last message repeated 45 times</programlisting> + + <para>All logged packets messages are written by default to + <filename>/var/log/security</filename> file, which is defined + in the <filename>/etc/syslog.conf</filename> file.</para> + </sect3> + + <sect3 id="firewalls-ipfw-rules-script"> + <title>Building a Rule Script</title> + + <para>Most experienced IPFW users create a file containing the + rules and code them in a manner compatible with running them + as a script. The major benefit of doing this is the firewall + rules can be refreshed in mass without the need of rebooting + the system to activate them. This method is very + convenient in testing new rules as the procedure can be + executed as many times as needed. Being a script, + symbolic substitution can be used to code frequent used values and + substitute them in multiple rules. This is shown in + the following example.</para> + + <para>The script syntax used here is compatible with the &man.sh.1;, + &man.csh.1;, &man.tcsh.1; shells. Symbolic substitution fields are + prefixed with a dollar sign $. Symbolic fields do not + have the $ prefix. The value to populate the symbolic + field must be enclosed in "double quotes".</para> + + <para>Start your rules file like this:</para> + + <programlisting>############### start of example ipfw rules script ############# +# +ipfw -q -f flush # Delete all rules +# Set defaults +oif="tun0" # out interface +odns="192.0.2.11" # ISP's DNS server IP address +cmd="ipfw -q add " # build rule prefix +ks="keep-state" # just too lazy to key this each time +$cmd 00500 check-state +$cmd 00502 deny all from any to any frag +$cmd 00501 deny tcp from any to any established +$cmd 00600 allow tcp from any to any 80 out via $oif setup $ks +$cmd 00610 allow tcp from any to $odns 53 out via $oif setup $ks +$cmd 00611 allow udp from any to $odns 53 out via $oif $ks +################### End of example ipfw rules script ############</programlisting> + + <para>That is all there is to it. The rules are not important + in this example, how the symbolic substitution field are + populated and used are.</para> + + <para>If the above example was in the + <filename>/etc/ipfw.rules</filename> file, the rules could be + reloaded by entering the following on the command line.</para> + + <screen>&prompt.root; <userinput>sh /etc/ipfw.rules</userinput></screen> + + <para>The <filename>/etc/ipfw.rules</filename> file could be + located anywhere you want and the file could be named any + thing you would like.</para> + + <para>The same thing could also be accomplished by running + these commands by hand:</para> + + <screen>&prompt.root; <userinput>ipfw -q -f flush</userinput> +&prompt.root; <userinput>ipfw -q add check-state</userinput> +&prompt.root; <userinput>ipfw -q add deny all from any to any frag</userinput> +&prompt.root; <userinput>ipfw -q add deny tcp from any to any established</userinput> +&prompt.root; <userinput>ipfw -q add allow tcp from any to any 80 out via tun0 setup keep-state</userinput> +&prompt.root; <userinput>ipfw -q add allow tcp from any to 192.0.2.11 53 out via tun0 setup keep-state</userinput> +&prompt.root; <userinput>ipfw -q add 00611 allow udp from any to 192.0.2.11 53 out via tun0 keep-state</userinput></screen> + </sect3> + + <sect3> + <title>Stateful Ruleset</title> + + <para>The following non-<acronym>NAT</acronym>ed ruleset is an + example of how to code a very secure 'inclusive' type of + firewall. An inclusive firewall only allows services + matching pass rules through and blocks all other by default. + Firewalls designed to protect entire network segments, have at minimum two interfaces which must + have rules to allow the firewall to function.</para> + + <para>All &unix; flavored operating systems, &os; included, are + designed to use interface <devicename>lo0</devicename> and IP + address <hostid role="ipaddr">127.0.0.1</hostid> for internal + communication with in the operating system. The firewall + rules must contain rules to allow free unmolested movement of + these special internally used packets.</para> + + <para>The interface which faces the public Internet is the one + to place the rules that authorize and control access of the + outbound and inbound connections. This can be your user + <acronym>PPP</acronym> + <devicename>tun0</devicename> interface or your NIC that is + connected to your DSL or cable modem.</para> + + <para>In cases where one or more than one NICs are connected to + a private LAN behind the firewall, those interfaces must + have rules coded to allow free unmolested movement of + packets originating from those LAN interfaces.</para> + + <para>The rules should be first organized into three major + sections, all the free unmolested interfaces, public + interface outbound, and the public interface inbound.</para> + + <para>The order of the rules in each of the public interface + sections should be in order of the most used rules being + placed before less often used rules with the last rule in + the section blocking and logging all packets on that interface + and direction.</para> + + <para>The Outbound section in the following ruleset only + contains <literal>allow</literal> rules which contain selection values that + uniquely identify the service that is authorized for public + Internet access. All the rules have the <literal>proto</literal>, <literal>port</literal>, + <literal>in/out</literal>, <literal>via</literal> and <literal>keep state</literal> option coded. The <literal>proto tcp</literal> + rules have the <literal>setup</literal> option included to identify the start + session request as the trigger packet to be posted to the + keep state stateful table.</para> + + <para>The Inbound section has all the blocking of undesirable + packets first, for two different reasons. The first is that + malicious packets may be partial matches for legitimate traffic. + These packets have to be discarded rather than allowed in, based on + their partial matches against <literal>allow</literal> rules. + The second reason is that known and uninteresting rejects may be + blocked silently, rather than being caught and logged by the last + rules in the section. The final rule in each section, blocks and + logs all packets and can be used to create the legal evidence needed + to prosecute the people who are attacking your system.</para> + + <para>Another thing that should be taken care of, is to insure there + is no response returned for any of the undesirable stuff. Invalid + packets should just get dropped and vanish. This way the attacker + has no knowledge if his packets have reached your system. + The less the attackers can learn about your system, the more + secure it is. Packets with unrecognized port numbers may be looked + up in <filename>/etc/services/</filename> or go to <ulink + url="http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers"></ulink> + and do a port number lookup to find the purpose of the particular + port number is. Check out this link for port numbers used by + Trojans: <ulink + url="http://www.sans.org/security-resources/idfaq/oddports.php"></ulink>.</para> + </sect3> + + <sect3> + <title>An Example Inclusive Ruleset</title> + + <para>The following non-<acronym>NAT</acronym>ed ruleset is a + complete inclusive type ruleset. It is safe to use this ruleset + on your own systems. Just comment out any <literal>pass</literal> + rules for services that are not required. To avoid logging + undesired messages, add a <literal>deny</literal> rule in the + inbound section. The <devicename>dc0</devicename> interface will + have to be changed in every rule, with the actual name of the + interface (NIC) that connects your system to the public Internet. + For user <acronym>PPP</acronym>, this would be + <devicename>tun0</devicename>.</para> + + <para>There is a noticeable pattern in the usage of these + rules.</para> + + <itemizedlist> + <listitem> + <para>All statements that are a request to start a session + to the public Internet use <literal>keep-state</literal>.</para> + </listitem> + + <listitem> + <para>All the authorized services that originate from the + public Internet have the <literal>limit</literal> option to stop + flooding.</para> + </listitem> + + <listitem> + <para>All rules use <literal>in</literal> or <literal>out</literal> to clarify direction.</para> + </listitem> + + <listitem> + <para>All rules use <literal>via</literal> <replaceable>interface-name</replaceable> to specify the + interface the packet is traveling over.</para> + </listitem> + </itemizedlist> + + <para>The following rules go into + <filename>/etc/ipfw.rules</filename>.</para> + + <programlisting>################ Start of IPFW rules file ############################### +# Flush out the list before we begin. +ipfw -q -f flush + +# Set rules command prefix +cmd="ipfw -q add" +pif="dc0" # public interface name of NIC + # facing the public Internet + +################################################################# +# No restrictions on Inside LAN Interface for private network +# Not needed unless you have LAN. +# Change xl0 to your LAN NIC interface name +################################################################# +#$cmd 00005 allow all from any to any via xl0 + +################################################################# +# No restrictions on Loopback Interface +################################################################# +$cmd 00010 allow all from any to any via lo0 + +################################################################# +# Allow the packet through if it has previous been added to the +# the "dynamic" rules table by a allow keep-state statement. +################################################################# +$cmd 00015 check-state + +################################################################# +# Interface facing Public Internet (Outbound Section) +# Interrogate session start requests originating from behind the +# firewall on the private network or from this gateway server +# destined for the public Internet. +################################################################# + +# Allow out access to my ISP's Domain name server. +# x.x.x.x must be the IP address of your ISP.s DNS +# Dup these lines if your ISP has more than one DNS server +# Get the IP addresses from /etc/resolv.conf file +$cmd 00110 allow tcp from any to x.x.x.x 53 out via $pif setup keep-state +$cmd 00111 allow udp from any to x.x.x.x 53 out via $pif keep-state + +# Allow out access to my ISP's DHCP server for cable/DSL configurations. +# This rule is not needed for .user ppp. connection to the public Internet. +# so you can delete this whole group. +# Use the following rule and check log for IP address. +# Then put IP address in commented out rule & delete first rule +$cmd 00120 allow log udp from any to any 67 out via $pif keep-state +#$cmd 00120 allow udp from any to x.x.x.x 67 out via $pif keep-state + +# Allow out non-secure standard www function +$cmd 00200 allow tcp from any to any 80 out via $pif setup keep-state + +# Allow out secure www function https over TLS SSL +$cmd 00220 allow tcp from any to any 443 out via $pif setup keep-state + +# Allow out send & get email function +$cmd 00230 allow tcp from any to any 25 out via $pif setup keep-state +$cmd 00231 allow tcp from any to any 110 out via $pif setup keep-state + +# Allow out FBSD (make install & CVSUP) functions +# Basically give user root "GOD" privileges. +$cmd 00240 allow tcp from me to any out via $pif setup keep-state uid root + +# Allow out ping +$cmd 00250 allow icmp from any to any out via $pif keep-state + +# Allow out Time +$cmd 00260 allow tcp from any to any 37 out via $pif setup keep-state + +# Allow out nntp news (i.e., news groups) +$cmd 00270 allow tcp from any to any 119 out via $pif setup keep-state + +# Allow out secure FTP, Telnet, and SCP +# This function is using SSH (secure shell) +$cmd 00280 allow tcp from any to any 22 out via $pif setup keep-state + +# Allow out whois +$cmd 00290 allow tcp from any to any 43 out via $pif setup keep-state + +# deny and log everything else that.s trying to get out. +# This rule enforces the block all by default logic. +$cmd 00299 deny log all from any to any out via $pif + +################################################################# +# Interface facing Public Internet (Inbound Section) +# Check packets originating from the public Internet +# destined for this gateway server or the private network. +################################################################# + +# Deny all inbound traffic from non-routable reserved address spaces +$cmd 00300 deny all from 192.168.0.0/16 to any in via $pif #RFC 1918 private IP +$cmd 00301 deny all from 172.16.0.0/12 to any in via $pif #RFC 1918 private IP +$cmd 00302 deny all from 10.0.0.0/8 to any in via $pif #RFC 1918 private IP +$cmd 00303 deny all from 127.0.0.0/8 to any in via $pif #loopback +$cmd 00304 deny all from 0.0.0.0/8 to any in via $pif #loopback +$cmd 00305 deny all from 169.254.0.0/16 to any in via $pif #DHCP auto-config +$cmd 00306 deny all from 192.0.2.0/24 to any in via $pif #reserved for docs +$cmd 00307 deny all from 204.152.64.0/23 to any in via $pif #Sun cluster interconnect +$cmd 00308 deny all from 224.0.0.0/3 to any in via $pif #Class D & E multicast + +# Deny public pings +$cmd 00310 deny icmp from any to any in via $pif + +# Deny ident +$cmd 00315 deny tcp from any to any 113 in via $pif + +# Deny all Netbios service. 137=name, 138=datagram, 139=session +# Netbios is MS/Windows sharing services. +# Block MS/Windows hosts2 name server requests 81 +$cmd 00320 deny tcp from any to any 137 in via $pif +$cmd 00321 deny tcp from any to any 138 in via $pif +$cmd 00322 deny tcp from any to any 139 in via $pif +$cmd 00323 deny tcp from any to any 81 in via $pif + +# Deny any late arriving packets +$cmd 00330 deny all from any to any frag in via $pif + +# Deny ACK packets that did not match the dynamic rule table +$cmd 00332 deny tcp from any to any established in via $pif + +# Allow traffic in from ISP's DHCP server. This rule must contain +# the IP address of your ISP.s DHCP server as it.s the only +# authorized source to send this packet type. +# Only necessary for cable or DSL configurations. +# This rule is not needed for .user ppp. type connection to +# the public Internet. This is the same IP address you captured +# and used in the outbound section. +#$cmd 00360 allow udp from any to x.x.x.x 67 in via $pif keep-state + +# Allow in standard www function because I have apache server +$cmd 00400 allow tcp from any to me 80 in via $pif setup limit src-addr 2 + +# Allow in secure FTP, Telnet, and SCP from public Internet +$cmd 00410 allow tcp from any to me 22 in via $pif setup limit src-addr 2 + +# Allow in non-secure Telnet session from public Internet +# labeled non-secure because ID & PW are passed over public +# Internet as clear text. +# Delete this sample group if you do not have telnet server enabled. +$cmd 00420 allow tcp from any to me 23 in via $pif setup limit src-addr 2 + +# Reject & Log all incoming connections from the outside +$cmd 00499 deny log all from any to any in via $pif + +# Everything else is denied by default +# deny and log all packets that fell through to see what they are +$cmd 00999 deny log all from any to any +################ End of IPFW rules file ###############################</programlisting> + </sect3> + + <sect3> + <title>An Example <acronym>NAT</acronym> and Stateful + Ruleset</title> + + <indexterm> + <primary>NAT</primary> + + <secondary>and IPFW</secondary> + </indexterm> + + <para>There are some additional configuration statements that + need to be enabled to activate the <acronym>NAT</acronym> + function of IPFW. The kernel source needs <literal>option IPDIVERT</literal> + statement added to the other IPFIREWALL statements compiled + into a custom kernel.</para> + + <para>In addition to the normal IPFW options in + <filename>/etc/rc.conf</filename>, the following are + needed.</para> + + <programlisting>natd_enable="YES" # Enable <acronym>NAT</acronym>D function +natd_interface="rl0" # interface name of public Internet NIC +natd_flags="-dynamic -m" # -m = preserve port numbers if possible</programlisting> + + <para>Utilizing stateful rules with <literal>divert natd</literal> rule (Network + Address Translation) greatly complicates the ruleset coding + logic. The positioning of the <literal>check-state</literal>, and <literal>divert natd</literal> + rules in the ruleset becomes very critical. This is no + longer a simple fall-through logic flow. A new action type + is used, called <literal>skipto</literal>. To use the <literal>skipto</literal> command it is + mandatory that each rule is numbered, so the + <literal>skipto</literal> rule number knows exactly where it is jumping + to.</para> + + <para>The following is an uncommented example of one coding + method, selected here to explain the sequence of the packet + flow through the rulesets.</para> + + <para>The processing flow starts with the first rule from the + top of the rule file and progress one rule at a time deeper + into the file until the end is reached or the packet being + tested to the selection criteria matches and the packet is + released out of the firewall. It is important to take notice + of the location of rule numbers 100 101, 450, 500, and 510. + These rules control the translation of the outbound and + inbound packets so their entries in the keep-state dynamic + table always register the private LAN IP address. Next + notice that all the allow and deny rules specify the + direction the packet is going (i.e.: outbound or inbound) and + the interface. Also notice that the start outbound + session requests, all <literal>skipto rule 500</literal> for the network address + translation.</para> + + <para>Lets say a LAN user uses their web browser to get a web + page. Web pages are transmitted over port 80. So the + packet enters the firewall. It does not match rule 100 because it + is headed out rather than in. It passes rule 101 because this is the + first packet, so it has not been posted to the keep-state + dynamic table yet. The packet finally comes to rule 125 a + matches. It is outbound through the NIC facing the public + Internet. The packet still has it's source IP address as a + private LAN IP address. On the match to this rule, two + actions take place. The <literal>keep-state</literal> option will post this + rule into the keep-state dynamic rules table and the + specified action is executed. The action is part of the info + posted to the dynamic table. In this case it is <literal>skipto rule + 500</literal>. Rule 500 <acronym>NAT</acronym>s the packet IP address + and out it goes. Remember this, this is very important. + This packet makes its way to the destination, where a response + packet is generated and sent back. This new packet + enters the top of the ruleset. This time it does match rule + 100 and has it destination IP address mapped back to its + corresponding LAN IP address. It then is processed by the + <literal>check-state</literal> rule, it is found in the table as an existing + session conversation and released to the LAN. It goes to the + LAN PC that sent it and a new packet is sent requesting + another segment of the data from the remote server. This + time it gets checked by the <literal>check-state</literal> rule and its outbound + entry is found, the associated action, <literal>skipto 500</literal>, is + executed. The packet jumps to rule 500 gets + <acronym>NAT</acronym>ed and released on it's way out.</para> + + <para>On the inbound side, everything coming in that is part + of an existing session conversation is being automatically + handled by the <literal>check-state</literal> rule and the properly placed + <literal>divert natd</literal> rules. All we have to address is denying all the + bad packets and only allowing in the authorized services. + Lets say there is an apache server running on the firewall box + and we want people on the public Internet to be able to + access the local web site. The new inbound start request + packet matches rule 100 and its IP address is mapped to LAN + IP for the firewall box. The packet is then matched against + all the nasty things that need to be checked for and finally matches + against rule 425. On a match two things occur. The packet + rule is posted to the keep-state dynamic table but this time + any new session requests originating from that source IP + address is limited to 2. This defends against DoS attacks of + service running on the specified port number. The action is + <literal>allow</literal> so the packet is released to the LAN. + The packet generated as a response, is recognized by the + <literal>check-state</literal> as belonging to an + existing session conversation. It is then sent to rule 500 for + <acronym>NAT</acronym>ing and released to the outbound + interface.</para> + + <para>Example Ruleset #1:</para> + + <programlisting>#!/bin/sh +cmd="ipfw -q add" +skip="skipto 500" +pif=rl0 +ks="keep-state" +good_tcpo="22,25,37,43,53,80,443,110,119" + +ipfw -q -f flush + +$cmd 002 allow all from any to any via xl0 # exclude LAN traffic +$cmd 003 allow all from any to any via lo0 # exclude loopback traffic + +$cmd 100 divert natd ip from any to any in via $pif +$cmd 101 check-state + +# Authorized outbound packets +$cmd 120 $skip udp from any to xx.168.240.2 53 out via $pif $ks +$cmd 121 $skip udp from any to xx.168.240.5 53 out via $pif $ks +$cmd 125 $skip tcp from any to any $good_tcpo out via $pif setup $ks +$cmd 130 $skip icmp from any to any out via $pif $ks +$cmd 135 $skip udp from any to any 123 out via $pif $ks + + +# Deny all inbound traffic from non-routable reserved address spaces +$cmd 300 deny all from 192.168.0.0/16 to any in via $pif #RFC 1918 private IP +$cmd 301 deny all from 172.16.0.0/12 to any in via $pif #RFC 1918 private IP +$cmd 302 deny all from 10.0.0.0/8 to any in via $pif #RFC 1918 private IP +$cmd 303 deny all from 127.0.0.0/8 to any in via $pif #loopback +$cmd 304 deny all from 0.0.0.0/8 to any in via $pif #loopback +$cmd 305 deny all from 169.254.0.0/16 to any in via $pif #DHCP auto-config +$cmd 306 deny all from 192.0.2.0/24 to any in via $pif #reserved for docs +$cmd 307 deny all from 204.152.64.0/23 to any in via $pif #Sun cluster +$cmd 308 deny all from 224.0.0.0/3 to any in via $pif #Class D & E multicast + +# Authorized inbound packets +$cmd 400 allow udp from xx.70.207.54 to any 68 in $ks +$cmd 420 allow tcp from any to me 80 in via $pif setup limit src-addr 1 + + +$cmd 450 deny log ip from any to any + +# This is skipto location for outbound stateful rules +$cmd 500 divert natd ip from any to any out via $pif +$cmd 510 allow ip from any to any + +######################## end of rules ##################</programlisting> + + <para>The following is pretty much the same as above, but uses + a self documenting coding style full of description comments + to help the inexperienced IPFW rule writer to better + understand what the rules are doing.</para> + + <para>Example Ruleset #2:</para> + + <programlisting>#!/bin/sh +################ Start of IPFW rules file ############################### +# Flush out the list before we begin. +ipfw -q -f flush + +# Set rules command prefix +cmd="ipfw -q add" +skip="skipto 800" +pif="rl0" # public interface name of NIC + # facing the public Internet + +################################################################# +# No restrictions on Inside LAN Interface for private network +# Change xl0 to your LAN NIC interface name +################################################################# +$cmd 005 allow all from any to any via xl0 + +################################################################# +# No restrictions on Loopback Interface +################################################################# +$cmd 010 allow all from any to any via lo0 + +################################################################# +# check if packet is inbound and nat address if it is +################################################################# +$cmd 014 divert natd ip from any to any in via $pif + +################################################################# +# Allow the packet through if it has previous been added to the +# the "dynamic" rules table by a allow keep-state statement. +################################################################# +$cmd 015 check-state + +################################################################# +# Interface facing Public Internet (Outbound Section) +# Check session start requests originating from behind the +# firewall on the private network or from this gateway server +# destined for the public Internet. +################################################################# + +# Allow out access to my ISP's Domain name server. +# x.x.x.x must be the IP address of your ISP's DNS +# Dup these lines if your ISP has more than one DNS server +# Get the IP addresses from /etc/resolv.conf file +$cmd 020 $skip tcp from any to x.x.x.x 53 out via $pif setup keep-state + + +# Allow out access to my ISP's DHCP server for cable/DSL configurations. +$cmd 030 $skip udp from any to x.x.x.x 67 out via $pif keep-state + +# Allow out non-secure standard www function +$cmd 040 $skip tcp from any to any 80 out via $pif setup keep-state + +# Allow out secure www function https over TLS SSL +$cmd 050 $skip tcp from any to any 443 out via $pif setup keep-state + +# Allow out send & get email function +$cmd 060 $skip tcp from any to any 25 out via $pif setup keep-state +$cmd 061 $skip tcp from any to any 110 out via $pif setup keep-state + +# Allow out FreeBSD (make install & CVSUP) functions +# Basically give user root "GOD" privileges. +$cmd 070 $skip tcp from me to any out via $pif setup keep-state uid root + +# Allow out ping +$cmd 080 $skip icmp from any to any out via $pif keep-state + +# Allow out Time +$cmd 090 $skip tcp from any to any 37 out via $pif setup keep-state + +# Allow out nntp news (i.e., news groups) +$cmd 100 $skip tcp from any to any 119 out via $pif setup keep-state + +# Allow out secure FTP, Telnet, and SCP +# This function is using SSH (secure shell) +$cmd 110 $skip tcp from any to any 22 out via $pif setup keep-state + +# Allow out whois +$cmd 120 $skip tcp from any to any 43 out via $pif setup keep-state + +# Allow ntp time server +$cmd 130 $skip udp from any to any 123 out via $pif keep-state + +################################################################# +# Interface facing Public Internet (Inbound Section) +# Check packets originating from the public Internet +# destined for this gateway server or the private network. +################################################################# + +# Deny all inbound traffic from non-routable reserved address spaces +$cmd 300 deny all from 192.168.0.0/16 to any in via $pif #RFC 1918 private IP +$cmd 301 deny all from 172.16.0.0/12 to any in via $pif #RFC 1918 private IP +$cmd 302 deny all from 10.0.0.0/8 to any in via $pif #RFC 1918 private IP +$cmd 303 deny all from 127.0.0.0/8 to any in via $pif #loopback +$cmd 304 deny all from 0.0.0.0/8 to any in via $pif #loopback +$cmd 305 deny all from 169.254.0.0/16 to any in via $pif #DHCP auto-config +$cmd 306 deny all from 192.0.2.0/24 to any in via $pif #reserved for docs +$cmd 307 deny all from 204.152.64.0/23 to any in via $pif #Sun cluster +$cmd 308 deny all from 224.0.0.0/3 to any in via $pif #Class D & E multicast + +# Deny ident +$cmd 315 deny tcp from any to any 113 in via $pif + +# Deny all Netbios service. 137=name, 138=datagram, 139=session +# Netbios is MS/Windows sharing services. +# Block MS/Windows hosts2 name server requests 81 +$cmd 320 deny tcp from any to any 137 in via $pif +$cmd 321 deny tcp from any to any 138 in via $pif +$cmd 322 deny tcp from any to any 139 in via $pif +$cmd 323 deny tcp from any to any 81 in via $pif + +# Deny any late arriving packets +$cmd 330 deny all from any to any frag in via $pif + +# Deny ACK packets that did not match the dynamic rule table +$cmd 332 deny tcp from any to any established in via $pif + +# Allow traffic in from ISP's DHCP server. This rule must contain +# the IP address of your ISP's DHCP server as it's the only +# authorized source to send this packet type. +# Only necessary for cable or DSL configurations. +# This rule is not needed for 'user ppp' type connection to +# the public Internet. This is the same IP address you captured +# and used in the outbound section. +$cmd 360 allow udp from x.x.x.x to any 68 in via $pif keep-state + +# Allow in standard www function because I have Apache server +$cmd 370 allow tcp from any to me 80 in via $pif setup limit src-addr 2 + +# Allow in secure FTP, Telnet, and SCP from public Internet +$cmd 380 allow tcp from any to me 22 in via $pif setup limit src-addr 2 + +# Allow in non-secure Telnet session from public Internet +# labeled non-secure because ID & PW are passed over public +# Internet as clear text. +# Delete this sample group if you do not have telnet server enabled. +$cmd 390 allow tcp from any to me 23 in via $pif setup limit src-addr 2 + +# Reject & Log all unauthorized incoming connections from the public Internet +$cmd 400 deny log all from any to any in via $pif + +# Reject & Log all unauthorized out going connections to the public Internet +$cmd 450 deny log all from any to any out via $pif + +# This is skipto location for outbound stateful rules +$cmd 800 divert natd ip from any to any out via $pif +$cmd 801 allow ip from any to any + +# Everything else is denied by default +# deny and log all packets that fell through to see what they are +$cmd 999 deny log all from any to any +################ End of IPFW rules file ###############################</programlisting> + </sect3> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/geom/Makefile b/en_US.ISO8859-1/books/handbook/geom/Makefile new file mode 100644 index 0000000000..59e5759cdc --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/geom/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= geom/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/geom/chapter.sgml b/en_US.ISO8859-1/books/handbook/geom/chapter.sgml new file mode 100644 index 0000000000..cf3b0065b3 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/geom/chapter.sgml @@ -0,0 +1,991 @@ +<!-- + The FreeBSD Documentation Project + $FreeBSD$ + +--> + +<chapter id="GEOM"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>GEOM: Modular Disk Transformation Framework</title> + + <sect1 id="GEOM-synopsis"> + <title>Synopsis</title> + + <indexterm> + <primary>GEOM</primary> + </indexterm> + <indexterm> + <primary>GEOM Disk Framework</primary> + <see>GEOM</see> + </indexterm> + + <para>This chapter covers the use of disks under the GEOM + framework in &os;. This includes the major <acronym + role="Redundant Array of Inexpensive Disks">RAID</acronym> + control utilities which use the framework for configuration. + This chapter will not go into in depth discussion on how GEOM + handles or controls I/O, the underlying subsystem, or code. + This information is provided through the &man.geom.4; manual + page and its various SEE ALSO references. This chapter is also + not a definitive guide to <acronym>RAID</acronym> + configurations. Only GEOM-supported <acronym>RAID</acronym> + classifications will be discussed.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>What type of <acronym>RAID</acronym> support is + available through GEOM.</para> + </listitem> + + <listitem> + <para>How to use the base utilities to configure, maintain, + and manipulate the various <acronym>RAID</acronym> + levels.</para> + </listitem> + + <listitem> + <para>How to mirror, stripe, encrypt, and remotely connect + disk devices through GEOM.</para> + </listitem> + + <listitem> + <para>How to troubleshoot disks attached to the GEOM + framework.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand how &os; treats disk devices + (<xref linkend="disks">).</para> + </listitem> + + <listitem> + <para>Know how to configure and install a new &os; kernel + (<xref linkend="kernelconfig">).</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="GEOM-intro"> + <title>GEOM Introduction</title> + + <para>GEOM permits access and control to classes — Master + Boot Records, <acronym>BSD</acronym> labels, etc — through + the use of providers, or the special files in + <filename class="directory">/dev</filename>. Supporting various + software <acronym>RAID</acronym> configurations, GEOM will + transparently provide access to the operating system and + operating system utilities.</para> + </sect1> + + <sect1 id="GEOM-striping"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + </author> + </authorgroup> + </sect1info> + + <title>RAID0 - Striping</title> + + <indexterm> + <primary>GEOM</primary> + </indexterm> + <indexterm> + <primary>Striping</primary> + </indexterm> + + <para>Striping is a method used to combine several disk drives + into a single volume. In many cases, this is done through the + use of hardware controllers. The GEOM disk subsystem provides + software support for <acronym>RAID</acronym>0, also known as + disk striping.</para> + + <para>In a <acronym>RAID</acronym>0 system, data are split up in + blocks that get written across all the drives in the array. + Instead of having to wait on the system to write 256k to one + disk, a <acronym>RAID</acronym>0 system can simultaneously write + 64k to each of four different disks, offering superior I/O + performance. This performance can be enhanced further by using + multiple disk controllers.</para> + + <para>Each disk in a <acronym>RAID</acronym>0 stripe must be of + the same size, since I/O requests are interleaved to read or + write to multiple disks in parallel.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="geom/striping" align="center"> + </imageobject> + + <textobject> + <phrase>Disk Striping Illustration</phrase> + </textobject> + </mediaobject> + + <procedure> + <title>Creating a Stripe of Unformatted ATA Disks</title> + + <step> + <para>Load the <filename>geom_stripe.ko</filename> + module:</para> + + <screen>&prompt.root; <userinput>kldload geom_stripe</userinput></screen> + </step> + + <step> + <para>Ensure that a suitable mount point exists. If this + volume will become a root partition, then temporarily use + another mount point such as <filename + class="directory">/mnt</filename>:</para> + + <screen>&prompt.root; <userinput>mkdir /mnt</userinput></screen> + </step> + + <step> + <para>Determine the device names for the disks which will + be striped, and create the new stripe device. For example, + to stripe two unused and unpartitioned + <acronym>ATA</acronym> disks, for example + <filename>/dev/ad2</filename> and + <filename>/dev/ad3</filename>:</para> + + <screen>&prompt.root; <userinput>gstripe label -v st0 /dev/ad2 /dev/ad3</userinput> +Metadata value stored on /dev/ad2. +Metadata value stored on /dev/ad3. +Done.</screen> + </step> + + <step> + <para>Write a standard label, also known as a partition + table, on the new volume and install the default + bootstrap code:</para> + + <screen>&prompt.root; <userinput>bsdlabel -wB /dev/stripe/st0</userinput></screen> + </step> + + <step> + <para>This process should have created two other devices + in the <filename class="directory">/dev/stripe</filename> + directory in addition to the <devicename>st0</devicename> + device. Those include <devicename>st0a</devicename> and + <devicename>st0c</devicename>. At this point a file system + may be created on the <devicename>st0a</devicename> device + with the <command>newfs</command> utility:</para> + + <screen>&prompt.root; <userinput>newfs -U /dev/stripe/st0a</userinput></screen> + + <para>Many numbers will glide across the screen, and after a + few seconds, the process will be complete. The volume has + been created and is ready to be mounted.</para> + </step> + </procedure> + + <para>To manually mount the created disk stripe:</para> + + <screen>&prompt.root; <userinput>mount /dev/stripe/st0a /mnt</userinput></screen> + + <para>To mount this striped file system automatically during the + boot process, place the volume information in + <filename>/etc/fstab</filename> file. For this purpose, a + permanent mount point, named + <filename class="directory">stripe</filename>, is + created:</para> + + <screen>&prompt.root; <userinput>mkdir /stripe</userinput> +&prompt.root; <userinput>echo "/dev/stripe/st0a /stripe ufs rw 2 2" \</userinput> + <userinput>>> /etc/fstab</userinput></screen> + + <para>The <filename>geom_stripe.ko</filename> module must also be + automatically loaded during system initialization, by adding a + line to <filename>/boot/loader.conf</filename>:</para> + + <screen>&prompt.root; <userinput>echo 'geom_stripe_load="YES"' >> /boot/loader.conf</userinput></screen> + </sect1> + + <sect1 id="GEOM-mirror"> + <title>RAID1 - Mirroring</title> + + <indexterm> + <primary>GEOM</primary> + </indexterm> + <indexterm> + <primary>Disk Mirroring</primary> + </indexterm> + + <para>Mirroring is a technology used by many corporations and home + users to back up data without interruption. When a mirror + exists, it simply means that diskB replicates diskA. Or, + perhaps diskC+D replicates diskA+B. Regardless of the disk + configuration, the important aspect is that information on one + disk or partition is being replicated. Later, that information + could be more easily restored, backed up without causing service + or access interruption, and even be physically stored in a data + safe.</para> + + <para>To begin, ensure the system has two disk drives of equal + size, these exercises assume they are direct access (&man.da.4;) + <acronym>SCSI</acronym> disks.</para> + + <sect2> + <title>Mirroring Primary Disks</title> + + <para>Assuming &os; has been installed on the first, + <devicename>da0</devicename> disk device, &man.gmirror.8; + should be told to store its primary data there.</para> + + <para>Before building the mirror, enable additional debugging + information and opening access to the device by setting the + <varname>kern.geom.debugflags</varname> &man.sysctl.8; option + to the following value:</para> + + <screen>&prompt.root; <userinput>sysctl kern.geom.debugflags=17</userinput></screen> + + <para>Now create the mirror. Begin the process by storing + meta-data information on the primary disk device, + effectively creating the + <filename class="devicefile">/dev/mirror/gm</filename> device + using the following command:</para> + + <warning> + <para>Creating a mirror out of the boot drive may result in + data loss if any data has been stored on the last sector of + the disk. This risk is reduced if creating the mirror is + done promptly after a fresh install of &os;. The following + procedure is also incompatible with the default installation + settings of &os; 9.<replaceable>X</replaceable> which + use the new <acronym>GPT</acronym> partition scheme. GEOM + will overwrite <acronym>GPT</acronym> metadata, causing data + loss and possibly an unbootable system.</para> + </warning> + + <screen>&prompt.root; <userinput>gmirror label -vb round-robin gm0 /dev/da0</userinput></screen> + + <para>The system should respond with:</para> + + <screen>Metadata value stored on /dev/da0. +Done.</screen> + + <para>Initialize GEOM, this will load the + <filename>/boot/kernel/geom_mirror.ko</filename> kernel + module:</para> + + <screen>&prompt.root; <userinput>gmirror load</userinput></screen> + + <note> + <para>When this command completes successfully, it creates the + <devicename>gm0</devicename> device node under the + <filename class="directory">/dev/mirror</filename> + directory.</para> + </note> + + <para>Enable loading of the <filename>geom_mirror.ko</filename> + kernel module during system initialization:</para> + + <screen>&prompt.root; <userinput>echo 'geom_mirror_load="YES"' >> /boot/loader.conf</userinput></screen> + + <para>Edit the <filename>/etc/fstab</filename> file, replacing + references to the old <devicename>da0</devicename> with the + new device nodes of the <devicename>gm0</devicename> mirror + device.</para> + + <note> + <para>If &man.vi.1; is your preferred editor, the following is + an easy way to accomplish this task:</para> + + <screen>&prompt.root; <userinput>vi /etc/fstab</userinput></screen> + + <para>In &man.vi.1; back up the current contents of + <filename>fstab</filename> by typing + <userinput>:w /etc/fstab.bak</userinput>. Then + replace all old <devicename>da0</devicename> references + with <devicename>gm0</devicename> by typing + <userinput>:%s/da/mirror\/gm/g</userinput>.</para> + </note> + + <para>The resulting <filename>fstab</filename> file should look + similar to the following. It does not matter if the disk + drives are <acronym>SCSI</acronym> or <acronym>ATA</acronym>, + the <acronym>RAID</acronym> device will be + <devicename>gm</devicename> regardless.</para> + + <programlisting># Device Mountpoint FStype Options Dump Pass# +/dev/mirror/gm0s1b none swap sw 0 0 +/dev/mirror/gm0s1a / ufs rw 1 1 +/dev/mirror/gm0s1d /usr ufs rw 0 0 +/dev/mirror/gm0s1f /home ufs rw 2 2 +#/dev/mirror/gm0s2d /store ufs rw 2 2 +/dev/mirror/gm0s1e /var ufs rw 2 2 +/dev/acd0 /cdrom cd9660 ro,noauto 0 0</programlisting> + + <para>Reboot the system:</para> + + <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen> + + <para>During system initialization, the + <devicename>gm0</devicename> should be used in place of the + <devicename>da0</devicename> device. Once fully initialized, + this may be checked by visually inspecting the output from + the <command>mount</command> command:</para> + + <screen>&prompt.root; <userinput>mount</userinput> +Filesystem 1K-blocks Used Avail Capacity Mounted on +/dev/mirror/gm0s1a 1012974 224604 707334 24% / +devfs 1 1 0 100% /dev +/dev/mirror/gm0s1f 45970182 28596 42263972 0% /home +/dev/mirror/gm0s1d 6090094 1348356 4254532 24% /usr +/dev/mirror/gm0s1e 3045006 2241420 559986 80% /var +devfs 1 1 0 100% /var/named/dev</screen> + + <para>The output looks good, as expected. Finally, to begin + synchronization, insert the <devicename>da1</devicename> disk + into the mirror using the following command:</para> + + <screen>&prompt.root; <userinput>gmirror insert gm0 /dev/da1</userinput></screen> + + <para>As the mirror is built the status may be checked using + the following command:</para> + + <screen>&prompt.root; <userinput>gmirror status</userinput></screen> + + <para>Once the mirror has been built and all current data + has been synchronized, the output from the above command + should look like:</para> + + <screen> Name Status Components +mirror/gm0 COMPLETE da0 + da1</screen> + + <para>If there are any issues, or the mirror is still + completing the build process, the example will show + <literal>DEGRADED</literal> in place of + <literal>COMPLETE</literal>.</para> + </sect2> + + <sect2> + <title>Troubleshooting</title> + + <sect3> + <title>System Refuses to Boot</title> + + <para>If the system boots up to a prompt similar to:</para> + + <programlisting>ffs_mountroot: can't find rootvp +Root mount failed: 6 +mountroot></programlisting> + + <para>Reboot the machine using the power or reset button. At + the boot menu, select option six (6). This will drop the + system to a &man.loader.8; prompt. Load the kernel module + manually:</para> + + <screen>OK? <userinput>load geom_mirror</userinput> +OK? <userinput>boot</userinput></screen> + + <para>If this works then for whatever reason the module was + not being loaded properly. Check whether the relevant entry + in <filename>/boot/loader.conf</filename> is correct. If + the problem persists, place:</para> + + <programlisting>options GEOM_MIRROR</programlisting> + + <para>in the kernel configuration file, rebuild and reinstall. + That should remedy this issue.</para> + </sect3> + </sect2> + + <sect2> + <title>Recovering from Disk Failure</title> + + <para>The wonderful part about disk mirroring is that when a + disk fails, it may be replaced, presumably, without losing + any data.</para> + + <para>Considering the previous <acronym>RAID</acronym>1 + configuration, assume that <devicename>da1</devicename> + has failed and now needs to be replaced. To replace it, + determine which disk has failed and power down the system. + At this point, the disk may be swapped with a new one and + the system brought back up. After the system has restarted, + the following commands may be used to replace the disk:</para> + + <screen>&prompt.root; <userinput>gmirror forget gm0</userinput></screen> + + <screen>&prompt.root; <userinput>gmirror insert gm0 /dev/da1</userinput></screen> + + <para>Use the <command>gmirror</command> <option>status</option> + command to monitor the progress of the rebuild. It is that + simple.</para> + </sect2> + </sect1> + + <sect1 id="GEOM-raid3"> + <sect1info> + <authorgroup> + <author> + <firstname>Mark</firstname> + <surname>Gladman</surname> + <contrib>Written by </contrib> + </author> + <author> + <firstname>Daniel</firstname> + <surname>Gerzo</surname> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Based on documentation by </contrib> + </author> + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + </author> + </authorgroup> + </sect1info> + + <indexterm> + <primary>GEOM</primary> + </indexterm> + <indexterm> + <primary>RAID3</primary> + </indexterm> + + <title><acronym>RAID</acronym>3 - Byte-level Striping with Dedicated + Parity</title> + + <para><acronym>RAID</acronym>3 is a method used to combine several + disk drives into a single volume with a dedicated parity + disk. In a <acronym>RAID</acronym>3 system, data is split up + into a number of bytes that are written across all the drives in + the array except for one disk which acts as a dedicated parity + disk. This means that reading 1024KB from a + <acronym>RAID</acronym>3 implementation will access all disks in + the array. Performance can be enhanced by using multiple + disk controllers. The <acronym>RAID</acronym>3 array provides a + fault tolerance of 1 drive, while providing a capacity of 1 - 1/n + times the total capacity of all drives in the array, where n is the + number of hard drives in the array. Such a configuration is + mostly suitable for storing data of larger sizes, e.g. + multimedia files.</para> + + <para>At least 3 physical hard drives are required to build a + <acronym>RAID</acronym>3 array. Each disk must be of the same + size, since I/O requests are interleaved to read or write to + multiple disks in parallel. Also, due to the nature of + <acronym>RAID</acronym>3, the number of drives must be + equal to 3, 5, 9, 17, etc. (2^n + 1).</para> + + <sect2> + <title>Creating a Dedicated <acronym>RAID</acronym>3 Array</title> + + <para>In &os;, support for <acronym>RAID</acronym>3 is + implemented by the &man.graid3.8; <acronym>GEOM</acronym> + class. Creating a dedicated + <acronym>RAID</acronym>3 array on &os; requires the following + steps.</para> + + <note> + <para>While it is theoretically possible to boot from a + <acronym>RAID</acronym>3 array on &os;, that configuration + is uncommon and is not advised.</para> + </note> + + <procedure> + <step> + <para>First, load the <filename>geom_raid3.ko</filename> + kernel module by issuing the following command:</para> + + <screen>&prompt.root; <userinput>graid3 load</userinput></screen> + + <para>Alternatively, it is possible to manually load the + <filename>geom_raid3.ko</filename> module:</para> + + <screen>&prompt.root; <userinput>kldload geom_raid3.ko</userinput></screen> + </step> + + <step> + <para>Create or ensure that a suitable mount point + exists:</para> + + <screen>&prompt.root; <userinput>mkdir <replaceable>/multimedia/</replaceable></userinput></screen> + </step> + + <step> + <para>Determine the device names for the disks which will be + added to the array, and create the new + <acronym>RAID</acronym>3 device. The final device listed + will act as the dedicated parity disk. This + example uses three unpartitioned + <acronym>ATA</acronym> drives: + <devicename><replaceable>ada1</replaceable></devicename> + and <devicename><replaceable>ada2</replaceable></devicename> + for data, and + <devicename><replaceable>ada3</replaceable></devicename> + for parity.</para> + + <screen>&prompt.root; <userinput>graid3 label -v gr0 /dev/ada1 /dev/ada2 /dev/ada3</userinput> +Metadata value stored on /dev/ada1. +Metadata value stored on /dev/ada2. +Metadata value stored on /dev/ada3. +Done.</screen> + </step> + + <step> + <para>Partition the newly created + <devicename>gr0</devicename> device and put a UFS file + system on it:</para> + + <screen>&prompt.root; <userinput>gpart create -s GPT /dev/raid3/gr0</userinput> +&prompt.root; <userinput>gpart add -t freebsd-ufs /dev/raid3/gr0</userinput> +&prompt.root; <userinput>newfs -j /dev/raid3/gr0p1</userinput></screen> + + <para>Many numbers will glide across the screen, and after a + bit of time, the process will be complete. The volume has + been created and is ready to be mounted.</para> + </step> + + <step> + <para>The last step is to mount the file system:</para> + + <screen>&prompt.root; <userinput>mount /dev/raid3/gr0p1 /multimedia/</userinput></screen> + + <para>The <acronym>RAID</acronym>3 array is now ready to + use.</para> + </step> + </procedure> + + <para>Additional configuration is needed to retain the above + setup across system reboots.</para> + + <procedure> + <step> + <para>The <filename>geom_raid3.ko</filename> module must be + loaded before the array can be mounted. To automatically + load the kernel module during the system initialization, add + the following line to the + <filename>/boot/loader.conf</filename> file:</para> + + <programlisting>geom_raid3_load="YES"</programlisting> + </step> + + <step> + <para>The following volume information must be added to the + <filename>/etc/fstab</filename> file in order to + automatically mount the array's file system during + the system boot process:</para> + + <programlisting>/dev/raid3/gr0p1 /multimedia ufs rw 2 2</programlisting> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="geom-ggate"> + <title>GEOM Gate Network Devices</title> + + <para>GEOM supports the remote use of devices, such as disks, + CD-ROMs, files, etc. through the use of the gate utilities. + This is similar to <acronym>NFS</acronym>.</para> + + <para>To begin, an exports file must be created. This file + specifies who is permitted to access the exported resources and + what level of access they are offered. For example, to export + the fourth slice on the first <acronym>SCSI</acronym> disk, the + following <filename>/etc/gg.exports</filename> is more than + adequate:</para> + + <programlisting>192.168.1.0/24 RW /dev/da0s4d</programlisting> + + <para>It will allow all hosts inside the private network access + the file system on the <devicename>da0s4d</devicename> + partition.</para> + + <para>To export this device, ensure it is not currently mounted, + and start the &man.ggated.8; server daemon:</para> + + <screen>&prompt.root; <userinput>ggated</userinput></screen> + + <para>Now to <command>mount</command> the device on the client + machine, issue the following commands:</para> + + <screen>&prompt.root; <userinput>ggatec create -o rw 192.168.1.1 /dev/da0s4d</userinput> +ggate0 +&prompt.root; <userinput>mount /dev/ggate0 /mnt</userinput></screen> + + <para>From here on, the device may be accessed through the + <filename class="directory">/mnt</filename> mount point.</para> + + <note> + <para>It should be pointed out that this will fail if the device + is currently mounted on either the server machine or any other + machine on the network.</para> + </note> + + <para>When the device is no longer needed, it may be safely + unmounted with the &man.umount.8; command, similar to any other + disk device.</para> + </sect1> + + <sect1 id="geom-glabel"> + <title>Labeling Disk Devices</title> + + <indexterm> + <primary>GEOM</primary> + </indexterm> + <indexterm> + <primary>Disk Labels</primary> + </indexterm> + + <para>During system initialization, the &os; kernel will create + device nodes as devices are found. This method of probing for + devices raises some issues, for instance what if a new disk + device is added via <acronym>USB</acronym>? It is very likely + that a flash device may be handed the device name of + <devicename>da0</devicename> and the original + <devicename>da0</devicename> shifted to + <devicename>da1</devicename>. This will cause issues mounting + file systems if they are listed in + <filename>/etc/fstab</filename>, effectively, this may also + prevent the system from booting.</para> + + <para>One solution to this issue is to chain the + <acronym>SCSI</acronym> devices in order so a new device added + to the <acronym>SCSI</acronym> card will be issued unused device + numbers. But what about <acronym>USB</acronym> devices which + may replace the primary <acronym>SCSI</acronym> disk? This + happens because <acronym>USB</acronym> devices are usually + probed before the <acronym>SCSI</acronym> card. One solution is + to only insert these devices after the system has been booted. + Another method could be to use only a single + <acronym>ATA</acronym> drive and never list the + <acronym>SCSI</acronym> devices in + <filename>/etc/fstab</filename>.</para> + + <para>A better solution is available. By using the + <command>glabel</command> utility, an administrator or user may + label their disk devices and use these labels in + <filename>/etc/fstab</filename>. Because + <command>glabel</command> stores the label in the last sector of + a given provider, the label will remain persistent across + reboots. By using this label as a device, the file system may + always be mounted regardless of what device node it is accessed + through.</para> + + <note> + <para>This goes without saying that a label be permanent. The + <command>glabel</command> utility may be used to create both a + transient and permanent label. Only the permanent label will + remain consistent across reboots. See the &man.glabel.8; + manual page for more information on the differences between + labels.</para> + </note> + + <sect2> + <title>Label Types and Examples</title> + + <para>There are two types of labels, a generic label and a + file system label. Labels can be permanent or temporary. + Permanent labels can be created with the &man.tunefs.8; + or &man.newfs.8; commands. They will then be created + in a sub-directory of + <filename class="directory">/dev</filename>, which will be + named according to their file system type. For example, + <acronym>UFS</acronym>2 file system labels will be created in + the <filename class="directory">/dev/ufs</filename> directory. + Permanent labels can also be created with the <command>glabel + label</command> command. These are not file system specific, + and will be created in the + <filename class="directory">/dev/label</filename> + directory.</para> + + <para>A temporary label will go away with the next reboot. + These labels will be created in the + <filename class="directory">/dev/label</filename> directory + and are perfect for experimentation. A temporary label can be + created using the <command>glabel create</command> command. + For more information, please read the manual page of + &man.glabel.8;.</para> + +<!-- XXXTR: How do you create a file system label without running newfs + or when there is no newfs (e.g.: cd9660)? --> + + <para>To create a permanent label for a + <acronym>UFS</acronym>2 file system without destroying any + data, issue the following command:</para> + + <screen>&prompt.root; <userinput>tunefs -L <replaceable>home</replaceable> <replaceable>/dev/da3</replaceable></userinput></screen> + + <warning> + <para>If the file system is full, this may cause data + corruption; however, if the file system is full then the + main goal should be removing stale files and not adding + labels.</para> + </warning> + + <para>A label should now exist in + <filename class="directory">/dev/ufs</filename> which may be + added to <filename>/etc/fstab</filename>:</para> + + <programlisting>/dev/ufs/home /home ufs rw 2 2</programlisting> + + <note> + <para>The file system must not be mounted while attempting + to run <command>tunefs</command>.</para> + </note> + + <para>Now the file system may be mounted like normal:</para> + + <screen>&prompt.root; <userinput>mount /home</userinput></screen> + + <para>From this point on, so long as the + <filename>geom_label.ko</filename> kernel module is loaded at + boot with <filename>/boot/loader.conf</filename> or the + <literal>GEOM_LABEL</literal> kernel option is present, + the device node may change without any ill effect on the + system.</para> + + <para>File systems may also be created with a default label + by using the <option>-L</option> flag with + <command>newfs</command>. See the &man.newfs.8; manual page + for more information.</para> + + <para>The following command can be used to destroy the + label:</para> + + <screen>&prompt.root; <userinput>glabel destroy home</userinput></screen> + + <para>The following example shows how to label the partitions of + a boot disk.</para> + + <example> + <title>Labeling Partitions on the Boot Disk</title> + + <para>By permanently labeling the partitions on the boot disk, + the system should be able to continue to boot normally, even + if the disk is moved to another controller or transferred to + a different system. For this example, it is assumed that a + single <acronym>ATA</acronym> disk is used, which is + currently recognized by the system as + <devicename>ad0</devicename>. It is also assumed that the + standard &os; partition scheme is used, with + <filename class="directory">/</filename>, + <filename class="directory">/var</filename>, + <filename class="directory">/usr</filename> and + <filename class="directory">/tmp</filename> file systems, as + well as a swap partition.</para> + + <para>Reboot the system, and at the &man.loader.8; prompt, + press <keycap>4</keycap> to boot into single user mode. + Then enter the following commands:</para> + + <screen>&prompt.root; <userinput>glabel label rootfs /dev/ad0s1a</userinput> +GEOM_LABEL: Label for provider /dev/ad0s1a is label/rootfs +&prompt.root; <userinput>glabel label var /dev/ad0s1d</userinput> +GEOM_LABEL: Label for provider /dev/ad0s1d is label/var +&prompt.root; <userinput>glabel label usr /dev/ad0s1f</userinput> +GEOM_LABEL: Label for provider /dev/ad0s1f is label/usr +&prompt.root; <userinput>glabel label tmp /dev/ad0s1e</userinput> +GEOM_LABEL: Label for provider /dev/ad0s1e is label/tmp +&prompt.root; <userinput>glabel label swap /dev/ad0s1b</userinput> +GEOM_LABEL: Label for provider /dev/ad0s1b is label/swap +&prompt.root; <userinput>exit</userinput></screen> + + <para>The system will continue with multi-user boot. After + the boot completes, edit <filename>/etc/fstab</filename> and + replace the conventional device names, with their respective + labels. The final <filename>/etc/fstab</filename> file will + look like the following:</para> + + <programlisting># Device Mountpoint FStype Options Dump Pass# +/dev/label/swap none swap sw 0 0 +/dev/label/rootfs / ufs rw 1 1 +/dev/label/tmp /tmp ufs rw 2 2 +/dev/label/usr /usr ufs rw 2 2 +/dev/label/var /var ufs rw 2 2</programlisting> + + <para>The system can now be rebooted. If everything went + well, it will come up normally and <command>mount</command> + will show:</para> + + <screen>&prompt.root; <userinput>mount</userinput> +/dev/label/rootfs on / (ufs, local) +devfs on /dev (devfs, local) +/dev/label/tmp on /tmp (ufs, local, soft-updates) +/dev/label/usr on /usr (ufs, local, soft-updates) +/dev/label/var on /var (ufs, local, soft-updates)</screen> + </example> + + <para>Starting with &os; 7.2, the &man.glabel.8; class + supports a new label type for <acronym>UFS</acronym> file + systems, based on the unique file system id, + <literal>ufsid</literal>. These labels may be found in the + <filename class="directory">/dev/ufsid</filename> directory + and are created automatically during system startup. It is + possible to use <literal>ufsid</literal> labels to mount + partitions using the <filename>/etc/fstab</filename> facility. + Use the <command>glabel status</command> command to receive a + list of file systems and their corresponding + <literal>ufsid</literal> labels:</para> + + <screen>&prompt.user; <userinput>glabel status</userinput> + Name Status Components +ufsid/486b6fc38d330916 N/A ad4s1d +ufsid/486b6fc16926168e N/A ad4s1f</screen> + + <para>In the above example <devicename>ad4s1d</devicename> + represents the <filename class="directory">/var</filename> + file system, while <devicename>ad4s1f</devicename> represents + the <filename class="directory">/usr</filename> file system. + Using the <literal>ufsid</literal> values shown, these + partitions may now be mounted with the following entries in + <filename>/etc/fstab</filename>:</para> + + <programlisting>/dev/ufsid/486b6fc38d330916 /var ufs rw 2 2 +/dev/ufsid/486b6fc16926168e /usr ufs rw 2 2</programlisting> + + <para>Any partitions with <literal>ufsid</literal> labels can be + mounted in this way, eliminating the need to create permanent + labels for them manually, while still enjoying the benefits of + device-name independent mounting.</para> + </sect2> + </sect1> + + <sect1 id="geom-gjournal"> + <title>UFS Journaling Through GEOM</title> + + <indexterm> + <primary>GEOM</primary> + </indexterm> + <indexterm> + <primary>Journaling</primary> + </indexterm> + + <para>With the release of &os; 7.0, the long awaited feature + of journals has been implemented. The implementation itself is + provided through the <acronym>GEOM</acronym> subsystem and is + easily configured via the &man.gjournal.8; utility.</para> + + <para>What is journaling? Journaling capability stores a log of + file system transactions, i.e.: changes that make up a complete + disk write operation, before meta-data and file writes are + committed to the disk proper. This transaction log can later + be replayed to redo file system transactions, preventing file + system inconsistencies.</para> + + <para>This method is yet another mechanism to protect against data + loss and inconsistencies of the file system. Unlike Soft + Updates which tracks and enforces meta-data updates and + Snapshots which is an image of the file system, an actual log is + stored in disk space specifically reserved for this task, and in + some cases may be stored on another disk entirely.</para> + + <para>Unlike other file system journaling implementations, the + <command>gjournal</command> method is block based and not + implemented as part of the file system - only as a + <acronym>GEOM</acronym> extension.</para> + + <para>To enable support for <command>gjournal</command>, the + &os; kernel must have the following option - which is the + default on &os; 7.0 and later systems:</para> + + <programlisting>options UFS_GJOURNAL</programlisting> + + <para>If journaled volumes need to be mounted during startup, the + <filename>geom_journal.ko</filename> kernel module will also + have to be loaded, by adding the following line in + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>geom_journal_load="YES"</programlisting> + + <para>Alternatively, this function can also be built into a custom + kernel, by adding the following line in the kernel configuration + file:</para> + + <programlisting>options GEOM_JOURNAL</programlisting> + + <para>Creating a journal on a free file system may now be done + using the following steps, considering that the + <devicename>da4</devicename> is a new <acronym>SCSI</acronym> + disk:</para> + + <screen>&prompt.root; <userinput>gjournal load</userinput> +&prompt.root; <userinput>gjournal label /dev/da4</userinput></screen> + + <para>At this point, there should be a + <devicename>/dev/da4</devicename> device node and a + <devicename>/dev/da4.journal</devicename> device node. + A file system may now be created on this device:</para> + + <screen>&prompt.root; <userinput>newfs -O 2 -J /dev/da4.journal</userinput></screen> + + <para>The previously issued command will create a + <acronym>UFS</acronym>2 file system on the journaled + device.</para> + + <para>Effectively <command>mount</command> the device at the + desired point with:</para> + + <screen>&prompt.root; <userinput>mount /dev/da4.journal <replaceable>/mnt</replaceable></userinput></screen> + + <note> + <para>In the case of several slices, a journal will be created + for each individual slice. For instance, if + <devicename>ad4s1</devicename> and + <devicename>ad4s2</devicename> are both slices, then + <command>gjournal</command> will create + <devicename>ad4s1.journal</devicename> and + <devicename>ad4s2.journal</devicename>.</para> + </note> + + <para>For better performance, keeping the journal on another disk + may be desired. For these cases, the journal provider or + storage device should be listed after the device to enable + journaling on. Journaling may also be enabled on current file + systems by using <command>tunefs</command>; however, always make + a backup before attempting to alter a file system. In most + cases, the <command>gjournal</command> will fail if it is unable + to create the actual journal but this does not protect against + data loss incurred as a result of misusing + <command>tunefs</command>.</para> + + <para>It is also possible to journal the boot disk of a &os; + system. Please refer to the article <ulink + url="&url.articles.gjournal-desktop;">Implementing UFS + Journaling on a Desktop PC</ulink> for detailed instructions + on this task.</para> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/install/Makefile b/en_US.ISO8859-1/books/handbook/install/Makefile new file mode 100644 index 0000000000..738cdb647d --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/install/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= install/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.sgml b/en_US.ISO8859-1/books/handbook/install/chapter.sgml new file mode 100644 index 0000000000..eb974729fd --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/install/chapter.sgml @@ -0,0 +1,5022 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="install"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Mock</surname> + <contrib>Restructured, reorganized, and parts + rewritten by </contrib> + </author> + </authorgroup> + + <authorgroup> + <author> + <firstname>Randy</firstname> + <surname>Pratt</surname> + <contrib>The sysinstall walkthrough, screenshots, and general + copy by </contrib> + </author> + </authorgroup> + <!-- January 2000 --> + </chapterinfo> + + <title>Installing &os; 8.<replaceable>x</replaceable> and Earlier</title> + + <sect1 id="install-synopsis"> + <title>Synopsis</title> + + <indexterm><primary>installation</primary></indexterm> + + <para>FreeBSD is provided with a text-based, easy to use installation + program. &os; 9.0-RELEASE and later use the installation program + known as <application>bsdinstall</application>, with releases prior + to 9.0-RELEASE using <application>sysinstall</application> for + installation. This chapter describes the use of <application>sysinstall</application> + to install &os;. The use of <application>bsdinstall</application> + is covered in <xref linkend="bsdinstall">.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to create the FreeBSD installation disks.</para> + </listitem> + + <listitem> + <para>How FreeBSD refers to, and subdivides, your hard disks.</para> + </listitem> + + <listitem> + <para>How to start <application>sysinstall</application>.</para> + </listitem> + + <listitem> + <para>The questions <application>sysinstall</application> will ask + you, what they mean, and how to answer them.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Read the supported hardware list that shipped with the version + of FreeBSD you are installing, and verify that your hardware is + supported.</para> + </listitem> + </itemizedlist> + + <note> + <para>In general, these installation instructions are written + for &i386; (<quote>PC compatible</quote>) architecture + computers. Where applicable, instructions specific to other + platforms will be listed. Although this + guide is kept as up to date as possible, you may find minor + differences between the installer and what is shown here. It is + suggested that you use this chapter as a general guide rather + than a literal installation manual.</para> + </note> + + </sect1> + + <sect1 id="install-hardware"> + <title>Hardware Requirements</title> + + <sect2 id="install-hardware-minimal"> + <title>Minimal Configuration</title> + + <para>The minimal configuration to install &os; varies with the + &os; version and the hardware architecture.</para> + + <para>A summary of this information is given in the following sections. + Depending on the method you choose to install &os;, you may + also need a floppy drive, a supported CDROM drive, and in some + case a network adapter. This will be covered by the <xref + linkend="install-boot-media">.</para> + + <sect3> + <title>&os;/&arch.i386; and &os;/&arch.pc98;</title> + + <para>Both &os;/&arch.i386; and &os;/&arch.pc98; require a 486 or + better processor and at least 24 MB of RAM. You will + need at least 150 MB of free hard drive space for the + most minimal installation.</para> + + <note> + <para>In case of old configurations, most of time, getting + more RAM and more hard drive space is more important than + getting a faster processor.</para> + </note> + </sect3> + + <sect3> + <title>&os;/&arch.amd64;</title> + + <para>There are two classes of processors capable of running + &os;/&arch.amd64;. The first are AMD64 processors, + including the &amd.athlon;64, + &amd.athlon;64-FX, &amd.opteron; or better + processors.</para> + + <para>The second class of processors that can use + &os;/&arch.amd64; includes those using the &intel; EM64T + architecture. Examples of these processors include the + &intel; &core; 2 Duo, Quad, Extreme processor + families, and the &intel; &xeon; 3000, 5000, and 7000 + sequences of processors.</para> + + <para>If you have a machine based on an nVidia nForce3 + Pro-150, you <emphasis>must</emphasis> use the BIOS setup to + disable the IO APIC. If you do not have an option to do + this, you will likely have to disable ACPI instead. There + are bugs in the Pro-150 chipset that we have not found a + workaround for yet.</para> + </sect3> + + <sect3> + <title>&os;/&arch.sparc64;</title> + + <para>To install &os;/&arch.sparc64;, you will need a supported + platform (see <xref + linkend="install-hardware-supported">).</para> + + <para>You will need a dedicated disk for &os;/&arch.sparc64;. It + is not possible to share a disk with another operating + system at this time.</para> + </sect3> + </sect2> + + <sect2 id="install-hardware-supported"> + <title>Supported Hardware</title> + + <para>A list of supported hardware is provided with each &os; + release in the &os; Hardware Notes. This document can usually + be found in a file named <filename>HARDWARE.TXT</filename>, in + the top-level directory of a CDROM or FTP distribution or in + <application>sysinstall</application>'s documentation menu. + It lists, for a given architecture, what hardware devices are + known to be supported by each release of &os;. Copies of the + supported hardware list for various releases and architectures + can also be found on the <ulink + url="http://www.FreeBSD.org/releases/index.html">Release + Information</ulink> page of the &os; Web site.</para> + </sect2> + </sect1> + + <sect1 id="install-pre"> + <title>Pre-installation Tasks</title> + + <sect2 id="install-inventory"> + <title>Inventory Your Computer</title> + + <para>Before installing FreeBSD you should attempt to inventory the + components in your computer. The FreeBSD installation routines will + show you the components (hard disks, network cards, CDROM drives, and + so forth) with their model number and manufacturer. FreeBSD will also + attempt to determine the correct configuration for these devices, + which includes information about IRQ and IO port usage. Due to the + vagaries of PC hardware this process is not always completely + successful, and you may need to correct FreeBSD's determination of + your configuration.</para> + + <para>If you already have another operating system installed, such as + &windows; or Linux, it is a good idea to use the facilities provided + by those operating systems to see how your hardware is already + configured. If you are not sure what settings an expansion + card is using, you may find it printed on the card itself. Popular IRQ + numbers are 3, 5, and 7, and IO port addresses are normally written as + hexadecimal numbers, such as 0x330.</para> + + <para>We recommend you print or write down this information before + installing FreeBSD. It may help to use a table, like this:</para> + + <table pgwide="1" frame="none"> + <title>Sample Device Inventory</title> + + <tgroup cols="4"> + <colspec colwidth="2*"> + <colspec colwidth="1*"> + <colspec colwidth="1*"> + <colspec colwidth="4*"> + <thead> + <row> + <entry>Device Name</entry> + + <entry>IRQ</entry> + + <entry>IO port(s)</entry> + + <entry>Notes</entry> + </row> + </thead> + + <tbody> + <row> + <entry>First hard disk</entry> + + <entry>N/A</entry> + + <entry>N/A</entry> + + <entry>40 GB, made by Seagate, first IDE master</entry> + </row> + + <row> + <entry>CDROM</entry> + + <entry>N/A</entry> + + <entry>N/A</entry> + + <entry>First IDE slave</entry> + </row> + + <row> + <entry>Second hard disk</entry> + + <entry>N/A</entry> + + <entry>N/A</entry> + + <entry>20 GB, made by IBM, second IDE master</entry> + </row> + + <row> + <entry>First IDE controller</entry> + + <entry>14</entry> + + <entry>0x1f0</entry> + + <entry></entry> + </row> + + <row> + <entry>Network card</entry> + + <entry>N/A</entry> + + <entry>N/A</entry> + + <entry>&intel; 10/100</entry> + </row> + + <row> + <entry>Modem</entry> + + <entry>N/A</entry> + + <entry>N/A</entry> + + <entry>&tm.3com; 56K faxmodem, on COM1</entry> + </row> + + <row> + <entry>…</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Once the inventory of the components in your computer is + done, you have to check if they match the hardware + requirements of the &os; release you want to install.</para> + </sect2> + + <sect2> + <title>Backup Your Data</title> + + <para>If the computer you will be installing FreeBSD on contains + valuable data, then ensure you have it backed up, and that you have + tested the backups before installing FreeBSD. The FreeBSD + installation routine will prompt you before writing any + data to your disk, but once that process has started it cannot be + undone.</para> + </sect2> + + <sect2 id="install-where"> + <title>Decide Where to Install FreeBSD</title> + + <para>If you want FreeBSD to use your entire hard disk, then there is nothing + more to concern yourself with at this point — you can skip this + section.</para> + + <para>However, if you need FreeBSD to co-exist with other operating + systems then you need to have a rough understanding of how data is + laid out on the disk, and how this affects you.</para> + + <sect3 id="install-where-i386"> + <title>Disk Layouts for &os;/&arch.i386;</title> + + <para>A PC disk can be divided into discrete chunks. These chunks are + called <firstterm>partitions</firstterm>. Since + &os; internally also has partitions, the naming + can become confusing very quickly, therefore these + disk chunks are referred to as disk slices or simply slices + in &os; itself. For example, the FreeBSD utility + <command>fdisk</command> which operates on the PC disk partitions, + refers to slices instead of partitions. By design, the PC only + supports four partitions per disk. These partitions are called + <firstterm>primary partitions</firstterm>. To work around this + limitation and allow more than four partitions, a new partition type + was created, the <firstterm>extended partition</firstterm>. A disk + may contain only one extended partition. Special partitions, called + <firstterm>logical partitions</firstterm>, can be created inside this + extended partition.</para> + + <para>Each partition has a <firstterm>partition ID</firstterm>, which is + a number used to identify the type of data on the partition. FreeBSD + partitions have the partition ID of <literal>165</literal>.</para> + + <para>In general, each operating system that you use will identify + partitions in a particular way. For example, &ms-dos;, and its + descendants, like &windows;, assign each primary and logical partition a + <firstterm>drive letter</firstterm>, starting with + <devicename>C:</devicename>.</para> + + <para>FreeBSD must be installed into a primary partition. FreeBSD can + keep all its data, including any files that you create, on this one + partition. However, if you have multiple disks, then you can create a + FreeBSD partition on all, or some, of them. When you install FreeBSD, + you must have one partition available. This might be a blank + partition that you have prepared, or it might be an existing partition + that contains data that you no longer care about.</para> + + <para>If you are already using all the partitions on all your disks, then + you will have to free one of them for FreeBSD using the tools + provided by the other operating systems you use (e.g., + <command>fdisk</command> on &ms-dos; or &windows;).</para> + + <para>If you have a spare partition then you can use that. However, you + may need to shrink one or more of your existing partitions + first.</para> + + <para>A minimal installation of FreeBSD takes as little as 100 MB + of disk + space. However, that is a <emphasis>very</emphasis> minimal install, + leaving almost no space for your own files. A more realistic minimum + is 250 MB without a graphical environment, and 350 MB or + more if you + want a graphical user interface. If you intend to install a lot of + third-party software as well, then you will need more space.</para> + + <para>You can use a commercial tool such as <application>&partitionmagic;</application>, + or a free tool such as <application>GParted</application>, + to resize your partitions and make space for + &os;. Both + <application>&partitionmagic;</application> and + <application>GParted</application> are known to work on + <acronym>NTFS</acronym>. <application>GParted</application> + is available on a number of Live CD Linux distributions, such as + <ulink url="http://www.sysresccd.org/">SystemRescueCD</ulink>.</para> + + <para>Problems have been reported resizing µsoft; Vista + partitions. Having a Vista installation CDROM handy when + attempting such an operation is recommended. As with all + such disk maintenance tasks, a current set of backups is + also strongly advised.</para> + + <warning> + <para>Incorrect use of these tools can delete the data on your disk. + Be sure that you have recent, working backups before using + them.</para> + </warning> + + <example> + <title>Using an Existing Partition Unchanged</title> + + <para>Suppose that you have a computer with a single 4 GB disk + that + already has a version of &windows; installed, and you have split the + disk into two drive letters, <devicename>C:</devicename> and + <devicename>D:</devicename>, each of which is 2 GB in size. + You have 1 GB of data on <devicename>C:</devicename>, and + 0.5 GB of data on + <devicename>D:</devicename>.</para> + + <para>This means that your disk has two partitions on it, one per + drive letter. You can copy all your existing data from + <devicename>D:</devicename> to <devicename>C:</devicename>, which + will free up the second partition, ready for FreeBSD.</para> + </example> + + <example> + <title>Shrinking an Existing Partition</title> + + <para>Suppose that you have a computer with a single 4 GB disk + that already has a version of &windows; installed. When you installed + &windows; you created one large partition, giving you a + <devicename>C:</devicename> drive that is 4 GB in size. You are + currently using 1.5 GB of space, and want FreeBSD to have 2 GB + of space.</para> + + <para>In order to install FreeBSD you will need to either:</para> + + <orderedlist> + <listitem> + <para>Backup your &windows; data, and then reinstall &windows;, + asking for a 2 GB partition at install time.</para> + </listitem> + + <listitem> + <para>Use one of the tools such as <application>&partitionmagic;</application>, + described above, to shrink your &windows; + partition.</para> + </listitem> + </orderedlist> + </example> + + </sect3> + </sect2> + + <sect2> + <title>Collect Your Network Configuration Details</title> + + <para>If you intend to connect to a network as part of your FreeBSD + installation (for example, if you will be installing from an FTP + site or an + NFS server), then you need to know your network configuration. You + will be prompted for this information during the installation so that + FreeBSD can connect to the network to complete the install.</para> + + <sect3> + <title>Connecting to an Ethernet Network or Cable/DSL Modem</title> + + <para>If you connect to an Ethernet network, or you have an Internet + connection using an Ethernet adapter via cable or DSL, then you will + need the following information:</para> + + <orderedlist> + <listitem> + <para>IP address</para> + </listitem> + + <listitem> + <para>IP address of the default gateway</para> + </listitem> + + <listitem> + <para>Hostname</para> + </listitem> + + <listitem> + <para>DNS server IP addresses</para> + </listitem> + + <listitem> + <para>Subnet Mask</para> + </listitem> + </orderedlist> + + <para>If you do not know this information, then ask your system + administrator or service provider. They may say that this + information is assigned automatically, using + <firstterm>DHCP</firstterm>. If so, make a note of this.</para> + </sect3> + + <sect3> + <title>Connecting Using a Modem</title> + + <para>If you dial up to an ISP using a regular modem then you can + still install FreeBSD over the Internet, it will just take a very + long time.</para> + + <para>You will need to know:</para> + + <orderedlist> + <listitem> + <para>The phone number to dial for your ISP</para> + </listitem> + + <listitem> + <para>The COM: port your modem is connected to</para> + </listitem> + + <listitem> + <para>The username and password for your ISP account</para> + </listitem> + </orderedlist> + </sect3> + </sect2> + <sect2> + <title>Check for FreeBSD Errata</title> + + <para>Although the FreeBSD project strives to ensure that each release + of FreeBSD is as stable as possible, bugs do occasionally creep into + the process. On very rare occasions those bugs affect the + installation process. As these problems are discovered and fixed, they + are noted in the <ulink url="http://www.FreeBSD.org/releases/&rel.current;R/errata.html">FreeBSD Errata</ulink>, + which is found on the FreeBSD web site. You + should check the errata before installing to make sure that there are + no late-breaking problems which you should be aware of.</para> + + <para>Information about all the releases, including the errata for each + release, can be found on the + <ulink + url="&url.base;/releases/index.html">release + information</ulink> section of the + <ulink + url="&url.base;/index.html">FreeBSD web site</ulink>.</para> + </sect2> + + <sect2> + <title>Obtain the FreeBSD Installation Files</title> + + <para>The FreeBSD installation process can install FreeBSD from files + located in any of the following places:</para> + + <itemizedlist> + <title>Local Media</title> + + <listitem> + <para>A CDROM or DVD</para> + </listitem> + + <listitem> + <para>A USB Memory Stick</para> + </listitem> + + <listitem> + <para>A &ms-dos; partition on the same computer</para> + </listitem> + + <listitem> + <para>A SCSI or QIC tape</para> + </listitem> + + <listitem> + <para>Floppy disks</para> + </listitem> + </itemizedlist> + + <itemizedlist> + <title>Network</title> + + <listitem> + <para>An FTP site, going through a firewall, or using an HTTP proxy, + as necessary</para> + </listitem> + + <listitem> + <para>An NFS server</para> + </listitem> + + <listitem> + <para>A dedicated parallel or serial connection</para> + </listitem> + </itemizedlist> + + <para>If you have purchased FreeBSD on CD or DVD then you already have + everything you need, and should proceed to the next section + (<xref linkend="install-boot-media">).</para> + + <para>If you have not obtained the FreeBSD installation files you should + skip ahead to <xref linkend="install-diff-media"> which explains how + to prepare to install FreeBSD from any of the above. After reading + that section, you should come back here, and read on to + <xref linkend="install-boot-media">.</para> + </sect2> + + <sect2 id="install-boot-media"> + <title>Prepare the Boot Media</title> + + <para>The FreeBSD installation process is started by booting your + computer into the FreeBSD installer—it is not a program you run + within another operating system. Your computer normally boots using + the operating system installed on your hard disk, but it can also be + configured to use a <quote>bootable</quote> floppy disk. + Most modern computers can also + boot from a CDROM in the CDROM drive or from a USB disk.</para> + + <tip> + <para>If you have FreeBSD on CDROM or DVD (either one you purchased + or you prepared yourself), and your computer allows you to boot from + the CDROM or DVD (typically a BIOS option called <quote>Boot + Order</quote> or similar), then you can skip this section. The + FreeBSD CDROM and DVD images are bootable and can be used to install + FreeBSD without any other special preparation.</para> + </tip> + + <para>To create a bootable memory stick, follow these + steps:</para> + + <procedure> + <step> + <title>Acquire the Memory Stick Image</title> + + <para>Memory stick images for + &os; 8.<replaceable>X</replaceable> and earlier can be downloaded from + the <filename class="directory">ISO-IMAGES/</filename> + directory at + <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/<replaceable>arch</replaceable>/ISO-IMAGES/<replaceable>version</replaceable>/&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-memstick.img</literal>. + Replace <replaceable>arch</replaceable> and + <replaceable>version</replaceable> with the + architecture and the version number which you want to + install, respectively. For example, the memory stick + images for &os;/&arch.i386; &rel2.current;-RELEASE are + available from <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-memstick.img"></ulink>.</para> + + <tip> + <para>A different directory path is used for + &os; 9.0-RELEASE and later versions. Details of + download and installation of &os; 9.0-RELEASE and + later is covered in <xref linkend="bsdinstall">.</para> + </tip> + + <para>The memory stick image has a <filename>.img</filename> + extension. The <filename + class="directory">ISO-IMAGES/</filename> directory + contains a number of different images, and the one you + will need to use will depend on the version of &os; you + are installing, and in some cases, the hardware you are + installing to.</para> + + <important> + <para>Before proceeding, <emphasis>back up</emphasis> the + data you currently have on your USB stick, as this + procedure will <emphasis>erase</emphasis> it.</para> + </important> + </step> + + <step> + <title>Write The Image File to the Memory Stick</title> + + <procedure> + <title>Using FreeBSD To Write the Image</title> + + <warning> + <para>The example below + lists <filename class="devicefile">/dev/da0</filename> as the + target device where the image will be written. Be very careful + that you have the correct device as the output target, or you + may destroy your existing data.</para> + </warning> + + <step> + <title>Writing the Image with &man.dd.1;</title> + + <para>The <filename>.img</filename> file + is <emphasis>not</emphasis> a regular file you copy to the + memory stick. It is an image of the complete contents of the + disk. This means that you <emphasis>cannot</emphasis> simply + copy files from one disk to another. Instead, you must use + &man.dd.1; to write the image directly to the disk:</para> + + <screen>&prompt.root; <userinput>dd if=&os;-&rel2.current;-RELEASE-&arch.i386;-memstick.img of=/dev/<replaceable>da0</replaceable> bs=64k</userinput></screen> + + <para>If an + <computeroutput>Operation not permitted</computeroutput> + error is displayed, make certain that the target device + is not in use, mounted, or being automounted by some + well-intentioned utility program. Then try + again.</para> + </step> + </procedure> + + <procedure> + <title>Using &windows; To Write the Image</title> + + <warning> + <para>Make sure you use the correct drive letter as the output + target, or you may overwrite and destroy existing data.</para> + </warning> + + <step> + <title>Obtaining <application>Image Writer for Windows</application></title> + + <para><application>Image Writer for Windows</application> is a + free application that can correctly write an image file to a + memory stick. Download it from + <ulink url="https://launchpad.net/win32-image-writer/"></ulink> + and extract it into a folder.</para> + </step> + + <step> + <title>Writing The Image with Image Writer</title> + + <para>Double-click + the <application>Win32DiskImager</application> icon to start + the program. Verify that the drive letter shown + under <computeroutput>Device</computeroutput> is the drive + with the memory stick. Click the folder icon and select the + image to be written to the memory stick. + Click <guibutton>Save</guibutton> to accept the image file + name. Verify that everything is correct, and that no folders + on the memory stick are open in other windows. Finally, + click <guibutton>Write</guibutton> to write the image file to + the drive.</para> + </step> + </procedure> + </step> + </procedure> + + <para>To create boot floppy images, follow these steps:</para> + + <procedure> + <step> + <title>Acquire the Boot Floppy Images</title> + + <important> + <para>Please note, as of &os; 8.<replaceable>X</replaceable>, floppy disk images are + no longer available. Please see above for instructions + on how to install &os; using a USB memory stick or just + use a CDROM or a DVD.</para> + </important> + + <para>The boot disks are available on your installation media + in the <filename>floppies/</filename> directory, and + can also be downloaded from the floppies directory, + <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>version</replaceable>-RELEASE/floppies/</literal>. + Replace <replaceable>arch</replaceable> and + <replaceable>version</replaceable> + with the architecture and the version number + which you want to install, respectively. + For example, the boot floppy images for + &os;/&arch.i386; &rel2.current;-RELEASE are available + from <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/floppies/"></ulink>.</para> + + <para>The floppy images have a <filename>.flp</filename> extension. + The <filename>floppies/</filename> directory contains a number of + different images, and the ones you will need to use depends on the + version of FreeBSD you are installing, and in some cases, the + hardware you are installing to. + In most cases you will need four + floppies, <filename>boot.flp</filename>, + <filename>kern1.flp</filename>, + <filename>kern2.flp</filename>, and + <filename>kern3.flp</filename>. Check + <filename>README.TXT</filename> in the same directory for the + most up to date information about these floppy images.</para> + + <important> + <para>Your FTP program must use <emphasis>binary mode</emphasis> + to download these disk images. Some web browsers have been + known to use <emphasis>text</emphasis> (or + <emphasis>ASCII</emphasis>) mode, which will be apparent if you + cannot boot from the disks.</para> + </important> + </step> + + <step> + <title>Prepare the Floppy Disks</title> + + <para>You must prepare one floppy disk per image file you had to + download. It is imperative that these disks are free from + defects. The easiest way to test this is to format the disks + for yourself. Do not trust pre-formatted floppies. The format + utility in &windows; will not tell about the presence of + bad blocks, it simply marks them as <quote>bad</quote> + and ignores them. It is advised that you use brand new + floppies if choosing this installation route.</para> + + <important> + <para>If you try to install FreeBSD and the installation + program crashes, freezes, or otherwise misbehaves, one of + the first things to suspect is the floppies. Try writing + the floppy image files to new disks and try + again.</para> + </important> + </step> + + <step> + <title>Write the Image Files to the Floppy Disks</title> + + <para>The <filename>.flp</filename> files are + <emphasis>not</emphasis> regular files you copy to the disk. + They are images of the complete contents of the + disk. This means that you <emphasis>cannot</emphasis> simply + copy files from one disk to another. + Instead, you must use specific tools to write the + images directly to the disk.</para> + + <indexterm><primary>DOS</primary></indexterm> + <para>If you are creating the floppies on a computer running + &ms-dos; / &windows;, then we provide a tool to do + this called <command>fdimage</command>.</para> + + <para>If you are using the floppies from the CDROM, and your + CDROM is the <devicename>E:</devicename> drive, then you would + run this:</para> + + <screen><prompt>E:\></prompt> <userinput>tools\fdimage floppies\boot.flp A:</userinput></screen> + + <para>Repeat this command for each <filename>.flp</filename> + file, replacing the floppy disk each time, being sure to label + the disks with the name of the file that you copied to them. + Adjust the command line as necessary, depending on where you have + placed the <filename>.flp</filename> files. If you do not have + the CDROM, then <command>fdimage</command> can be downloaded from + the <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/"><filename class="directory">tools</filename> + directory</ulink> on the FreeBSD FTP site.</para> + + <para>If you are writing the floppies on a &unix; system (such as + another FreeBSD system) you can use the &man.dd.1; command to + write the image files directly to disk. On FreeBSD, you would + run:</para> + + <screen>&prompt.root; <userinput>dd if=boot.flp of=/dev/fd0</userinput></screen> + + <para>On FreeBSD, <filename>/dev/fd0</filename> refers to the + first floppy disk (the <devicename>A:</devicename> drive). + <filename>/dev/fd1</filename> would be the + <devicename>B:</devicename> drive, and so on. Other &unix; + variants might have different names for the floppy disk + devices, and you will need to check the documentation for the + system as necessary.</para> + </step> + </procedure> + + <para>You are now ready to start installing FreeBSD.</para> + </sect2> + </sect1> + + <sect1 id="install-start"> + <title>Starting the Installation</title> + + <important> + <para>By default, the installation will not make any changes to your + disk(s) until you see the following message:</para> + + <literallayout class="monospaced">Last Chance: Are you SURE you want continue the installation? + +If you're running this on a disk with data you wish to save then WE +STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding! + +We can take no responsibility for lost disk contents!</literallayout> + + <para>The install can be exited at any time prior to the final + warning without changing the contents of the hard drive. If you are + concerned that you have configured something incorrectly you can just + turn the computer off before this point, and no damage will be + done.</para> + </important> + + <sect2 id="install-starting"> + <title>Booting</title> + + <sect3 id="install-starting-i386"> + <title>Booting for the &i386;</title> + + <procedure> + <step> + <para>Start with your computer turned off.</para> + </step> + + <step> + <para>Turn on the computer. As it starts it should display an + option to enter the system set up menu, or BIOS, commonly reached + by keys like <keycap>F2</keycap>, <keycap>F10</keycap>, + <keycap>Del</keycap>, or + <keycombo action="simul"> + <keycap>Alt</keycap> + <keycap>S</keycap> + </keycombo>. Use whichever keystroke is indicated on screen. In + some cases your computer may display a graphic while it starts. + Typically, pressing <keycap>Esc</keycap> will dismiss the graphic + and allow you to see the necessary messages.</para> + </step> + + <step> + <para>Find the setting that controls which devices the system boots + from. This is usually labeled as the <quote>Boot Order</quote> + and commonly shown as a list of devices, such as + <literal>Floppy</literal>, <literal>CDROM</literal>, + <literal>First Hard Disk</literal>, and so on.</para> + + <para>If you are booting from the CDROM then make sure that + the CDROM is selected. If you are booting from a USB disk or + a floppy disk then + make sure that is selected instead. In case of doubt, you + should consult the manual that came with your computer, and/or its + motherboard.</para> + + <para>Make the change, then save and exit. The computer should now + restart.</para> + </step> + + <step> + <para>If you prepared a <quote>bootable</quote> USB stick, as described in + <xref linkend="install-boot-media">, then plug in your USB + stick before turning on the computer.</para> + + <para>If you are booting from CDROM, then you will need to turn on + the computer, and insert the CDROM at the first + opportunity.</para> + + <note> + <para>For &os; 7.<replaceable>X</replaceable>, installation + boot floppies are available and can be prepared as + described in <xref linkend="install-boot-media">. One of + them will be the first boot disc: + <filename>boot.flp</filename>. Put this disc in your + floppy drive and boot the computer.</para> + </note> + + <para>If your computer starts up as normal and loads your existing + operating system, then either:</para> + + <orderedlist> + <listitem> + <para>The disks were not inserted early enough in the boot + process. Leave them in, and try restarting your + computer.</para> + </listitem> + + <listitem> + <para>The BIOS changes earlier did not work correctly. You + should redo that step until you get the right option.</para> + </listitem> + + <listitem> + <para>Your particular BIOS does not support booting from + the desired media.</para> + </listitem> + </orderedlist> + </step> + + <step> + <para>FreeBSD will start to boot. If you are booting from CDROM you + will see a display similar to this (version information + omitted):</para> + + <screen>Booting from CD-Rom... +645MB medium detected +CD Loader 1.2 + +Building the boot loader arguments +Looking up /BOOT/LOADER... Found +Relocating the loader and the BTX +Starting the BTX loader + +BTX loader 1.00 BTX version is 1.02 +Consoles: internal video/keyboard +BIOS CD is cd0 +BIOS drive C: is disk0 +BIOS drive D: is disk1 +BIOS 636kB/261056kB available memory + +FreeBSD/i386 bootstrap loader, Revision 1.1 + +Loading /boot/defaults/loader.conf +/boot/kernel/kernel text=0x64daa0 data=0xa4e80+0xa9e40 syms=[0x4+0x6cac0+0x4+0x88e9d] +\</screen> + + <para>If you are booting from floppy disc, you will see a display + similar to this (version information omitted):</para> + + <screen>Booting from Floppy... +Uncompressing ... done + +BTX loader 1.00 BTX version is 1.01 +Console: internal video/keyboard +BIOS drive A: is disk0 +BIOS drive C: is disk1 +BIOS 639kB/261120kB available memory + +FreeBSD/i386 bootstrap loader, Revision 1.1 + +Loading /boot/defaults/loader.conf +/kernel text=0x277391 data=0x3268c+0x332a8 | + +Insert disk labelled "Kernel floppy 1" and press any key...</screen> + + <para>Follow these instructions by removing the + <filename>boot.flp</filename> disc, insert the + <filename>kern1.flp</filename> disc, and press + <keycap>Enter</keycap>. Boot from first floppy; + when prompted, insert the other disks as required.</para> + </step> + + <step> + <para>Whether you booted from CDROM, USB stick or floppy, the + boot process will then get to the &os; boot loader + menu:</para> + + <figure id="boot-loader-menu"> + <title>&os; Boot Loader Menu</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/boot-loader-menu" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Either wait ten seconds, or press <keycap>Enter</keycap>.</para> + </step> + </procedure> + + </sect3> + + <sect3> + <title>Booting for &sparc64;</title> + + <para>Most &sparc64; systems are set up to boot automatically + from disk. To install &os;, you need to boot over the + network or from a CDROM, which requires you to break into + the PROM (OpenFirmware).</para> + + <para>To do this, reboot the system, and wait until the boot + message appears. It depends on the model, but should look + about like:</para> + + <screen>Sun Blade 100 (UltraSPARC-IIe), Keyboard Present +Copyright 1998-2001 Sun Microsystems, Inc. All rights reserved. +OpenBoot 4.2, 128 MB memory installed, Serial #51090132. +Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.</screen> + + <para>If your system proceeds to boot from disk at this point, + you need to press + <keycombo action="simul"><keycap>L1</keycap><keycap>A</keycap></keycombo> + or + <keycombo action="simul"><keycap>Stop</keycap><keycap>A</keycap></keycombo> + on the keyboard, or send a <command>BREAK</command> over the + serial console (using for example <command>~#</command> in + &man.tip.1; or &man.cu.1;) to get to the PROM prompt. It + looks like this:</para> + + <screenco> + <areaspec> + <area id="prompt-single" coords="1 5"> + <area id="prompt-smp" coords="2 5"> + </areaspec> + + <screen><prompt>ok </prompt> +<prompt>ok {0} </prompt></screen> + + <calloutlist> + <callout arearefs="prompt-single"> + <para>This is the prompt used on systems with just one + CPU.</para> + </callout> + + <callout arearefs="prompt-smp"> + <para>This is the prompt used on SMP systems, the digit + indicates the number of the active CPU.</para> + </callout> + </calloutlist> + </screenco> + + <para>At this point, place the CDROM into your drive, and from + the PROM prompt, type <command>boot cdrom</command>.</para> + + </sect3> + + </sect2> + + <sect2 id="view-probe"> + <title>Reviewing the Device Probe Results</title> + + <para>The last few hundred lines that have been displayed on screen are + stored and can be reviewed.</para> + + <para>To review the buffer, press <keycap>Scroll Lock</keycap>. This + turns on scrolling in the display. You can then use the arrow keys, or + <keycap>PageUp</keycap> and <keycap>PageDown</keycap> to view the + results. Press <keycap>Scroll Lock</keycap> again to stop + scrolling.</para> + + <para>Do this now, to review the text that scrolled off the screen when + the kernel was carrying out the device probes. You will see text + similar to <xref linkend="install-dev-probe">, although the precise + text will differ depending on the devices that you have in your + computer.</para> + + <figure id="install-dev-probe"> + <title>Typical Device Probe Results</title> + + <screen>avail memory = 253050880 (247120K bytes) +Preloaded elf kernel "kernel" at 0xc0817000. +Preloaded mfs_root "/mfsroot" at 0xc0817084. +md0: Preloaded image </mfsroot> 4423680 bytes at 0xc03ddcd4 + +md1: Malloc disk +Using $PIR table, 4 entries at 0xc00fde60 +npx0: <math processor> on motherboard +npx0: INT 16 interface +pcib0: <Host to PCI bridge> on motherboard +pci0: <PCI bus> on pcib0 +pcib1:<VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge> at device 1.0 on pci0 +pci1: <PCI bus> on pcib1 +pci1: <Matrox MGA G200 AGP graphics accelerator> at 0.0 irq 11 +isab0: <VIA 82C586 PCI-ISA bridge> at device 7.0 on pci0 +isa0: <iSA bus> on isab0 +atapci0: <VIA 82C586 ATA33 controller> port 0xe000-0xe00f at device 7.1 on pci0 +ata0: at 0x1f0 irq 14 on atapci0 +ata1: at 0x170 irq 15 on atapci0 +uhci0 <VIA 83C572 USB controller> port 0xe400-0xe41f irq 10 at device 7.2 on pci +0 +usb0: <VIA 83572 USB controller> on uhci0 +usb0: USB revision 1.0 +uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr1 +uhub0: 2 ports with 2 removable, self powered +pci0: <unknown card> (vendor=0x1106, dev=0x3040) at 7.3 +dc0: <ADMtek AN985 10/100BaseTX> port 0xe800-0xe8ff mem 0xdb000000-0xeb0003ff ir +q 11 at device 8.0 on pci0 +dc0: Ethernet address: 00:04:5a:74:6b:b5 +miibus0: <MII bus> on dc0 +ukphy0: <Generic IEEE 802.3u media interface> on miibus0 +ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto +ed0: <NE2000 PCI Ethernet (RealTek 8029)> port 0xec00-0xec1f irq 9 at device 10. +0 on pci0 +ed0 address 52:54:05:de:73:1b, type NE2000 (16 bit) +isa0: too many dependant configs (8) +isa0: unexpected small tag 14 +orm0: <Option ROM> at iomem 0xc0000-0xc7fff on isa0 +fdc0: <NEC 72065B or clone> at port 0x3f0-0x3f5,0x3f7 irq 6 drq2 on isa0 +fdc0: FIFO enabled, 8 bytes threshold +fd0: <1440-KB 3.5” drive> on fdc0 drive 0 +atkbdc0: <Keyboard controller (i8042)> at port 0x60,0x64 on isa0 +atkbd0: <AT Keyboard> flags 0x1 irq1 on atkbdc0 +kbd0 at atkbd0 +psm0: <PS/2 Mouse> irq 12 on atkbdc0 +psm0: model Generic PS/@ mouse, device ID 0 +vga0: <Generic ISA VGA> at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0 +sc0: <System console> at flags 0x100 on isa0 +sc0: VGA <16 virtual consoles, flags=0x300> +sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0 +sio0: type 16550A +sio1 at port 0x2f8-0x2ff irq 3 on isa0 +sio1: type 16550A +ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0 +pppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode +ppc0: FIFO with 16/16/15 bytes threshold +plip0: <PLIP network interface> on ppbus0 +ad0: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata0-master UDMA33 +acd0: CD-RW <LITE-ON LTR-1210B> at ata1-slave PIO4 +Mounting root from ufs:/dev/md0c +/stand/sysinstall running as init on vty0</screen> + </figure> + + <para>Check the probe results carefully to make sure that FreeBSD found + all the devices you expected. If a device was not found, then it will + not be listed. A <link linkend="kernelconfig">custom kernel</link> + allows you to add in support for devices which are not in the + <filename>GENERIC</filename> kernel, such as sound cards.</para> + + <para>After the procedure of device + probing, you will see <xref linkend="config-country">. Use the + arrow key to choose a country, region, or group. Then press + <keycap>Enter</keycap>, it will set your country + easily.</para> + + <figure id="config-country"> + <title>Selecting Country Menu</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/config-country" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>If you selected <guimenuitem>United States</guimenuitem> + as country, the standard American keyboard map will be used, + if a different country is chosen the following menu will be + displayed. Use the arrow keys to choose the correct keyboard + map and press <keycap>Enter</keycap>.</para> + + <figure id="config-keymap"> + <title>Selecting Keyboard Menu</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/config-keymap" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>After the country selecting, the <application>sysinstall</application> + main menu will display.</para> + </sect2> + </sect1> + + <sect1 id="using-sysinstall"> + <title>Introducing Sysinstall</title> + + <para>The <application>sysinstall</application> utility is the installation + application provided by the FreeBSD Project. It is console based and is + divided into a number of menus and screens that you can use to + configure and control the installation process.</para> + + <para>The <application>sysinstall</application> menu system is controlled + by the arrow keys, <keycap>Enter</keycap>, <keycap>Tab</keycap>, + <keycap>Space</keycap>, and + other keys. A detailed description of these keys and what they do is + contained in <application>sysinstall</application>'s usage + information.</para> + + <para>To review this information, ensure that the + <guimenuitem>Usage</guimenuitem> entry is highlighted and that the + <guibutton>[Select]</guibutton> button is selected, as shown in <xref + linkend="sysinstall-main3">, then press <keycap>Enter</keycap>.</para> + + <para>The instructions for using the menu system will be displayed. After + reviewing them, press <keycap>Enter</keycap> to return to the Main + Menu.</para> + + <figure id="sysinstall-main3"> + <title>Selecting Usage from Sysinstall Main Menu</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/main1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <sect2 id="select-doc"> + <title>Selecting the Documentation Menu</title> + + <para>From the Main Menu, select <guimenuitem>Doc</guimenuitem> with + the arrow keys and + press <keycap>Enter</keycap>.</para> + + <figure id="main-doc"> + <title>Selecting Documentation Menu</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/main-doc" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>This will display the Documentation Menu.</para> + + <figure id="docmenu1"> + <title>Sysinstall Documentation Menu</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/docmenu1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>It is important to read the documents provided.</para> + + <para>To view a document, select it with the arrow keys and + press <keycap>Enter</keycap>. When finished reading a document, + pressing <keycap>Enter</keycap> will return to the Documentation + Menu.</para> + + <para>To return to the Main Installation Menu, select + <guimenuitem>Exit</guimenuitem> with the + arrow keys and press <keycap>Enter</keycap>.</para> + </sect2> + + <sect2 id="keymap"> + <title>Selecting the Keymap Menu</title> + + <para>To change the keyboard mapping, use the arrow keys to select + <guimenuitem>Keymap</guimenuitem> from the menu and press + <keycap>Enter</keycap>. This is only required if you are + using a non-standard or non-US keyboard.</para> + + <figure id="sysinstall-keymap"> + <title>Sysinstall Main Menu</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/main-keymap" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>A different keyboard mapping may be chosen by selecting the + menu item using up/down arrow keys and pressing <keycap>Space</keycap>. + Pressing <keycap>Space</keycap> again will unselect the item. + When finished, choose the &gui.ok; using the arrow keys and press + <keycap>Enter</keycap>.</para> + + <para>Only a partial list is shown in this screen representation. + Selecting &gui.cancel; by pressing <keycap>Tab</keycap> will use the + default keymap and return to the Main Install Menu.</para> + + <figure id="sysinstall-keymap-menu"> + <title>Sysinstall Keymap Menu</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/keymap" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + </sect2> + + <sect2 id="viewsetoptions"> + <title>Installation Options Screen</title> + + <para>Select <guimenuitem>Options</guimenuitem> and press + <keycap>Enter</keycap>.</para> + + <figure id="sysinstall-options"> + <title>Sysinstall Main Menu</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/main-options" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <figure id="options"> + <title>Sysinstall Options</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/options" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The default values are usually fine for most users and do + not need to be changed. The release name will vary according + to the version being installed.</para> + + <para>The description of the selected item will appear at the + bottom of the screen highlighted in blue. Notice that one of the + options is <guimenuitem>Use Defaults</guimenuitem> to reset all + values to startup defaults.</para> + + <para>Press <keycap>F1</keycap> to read the help screen about the + various options.</para> + + <para>Pressing <keycap>Q</keycap> will return to the Main Install + menu.</para> + </sect2> + + <sect2 id="start-install"> + <title>Begin a Standard Installation</title> + + <para>The <guimenuitem>Standard</guimenuitem> installation is the + option recommended for those new to &unix; or FreeBSD. Use the arrow + keys to select <guimenuitem>Standard</guimenuitem> and + then press <keycap>Enter</keycap> to start the installation.</para> + + <figure id="sysinstall-standard"> + <title>Begin Standard Installation</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/main-std" format="PNG"> + </imageobject> + </mediaobject> + </figure> + </sect2> + </sect1> + + <sect1 id="install-steps"> + <title>Allocating Disk Space</title> + + <para>Your first task is to allocate disk space for FreeBSD, and label + that space so that <application>sysinstall</application> can prepare + it. In order to do this you need to know how FreeBSD expects to find + information on the disk.</para> + + <sect2 id="install-drive-bios-numbering"> + <title>BIOS Drive Numbering</title> + + <para>Before you install and configure FreeBSD on your system, there is an + important subject that you should be aware of, especially if you have + multiple hard drives.</para> + + <indexterm><primary>MS-DOS</primary></indexterm> + <indexterm><primary>Microsoft Windows</primary></indexterm> + <para>In a PC running a BIOS-dependent operating system such as + &ms-dos; or µsoft.windows;, the BIOS is able to abstract the + normal disk drive order, and + the operating system goes along with the change. This allows the user + to boot from a disk drive other than the so-called <quote>primary + master</quote>. This is especially convenient for some users who have + found that the simplest and cheapest way to keep a system backup is to + buy an identical second hard drive, and perform routine copies of the + first drive to the second drive using + <application><trademark class="registered">Ghost</trademark></application> or <application>XCOPY</application> + . Then, if the + first drive fails, or is attacked by a virus, or is scribbled upon by an + operating system defect, he can easily recover by instructing the BIOS + to logically swap the drives. It is like switching the cables on the + drives, but without having to open the case.</para> + + <indexterm><primary>SCSI</primary></indexterm> + <indexterm><primary>BIOS</primary></indexterm> + <para>More expensive systems with SCSI controllers often include BIOS + extensions which allow the SCSI drives to be re-ordered in a similar + fashion for up to seven drives.</para> + + <para>A user who is accustomed to taking advantage of these features may + become surprised when the results with FreeBSD are not as expected. + FreeBSD does not use the BIOS, and does not know the <quote>logical BIOS + drive mapping</quote>. This can lead to very perplexing situations, + especially when drives are physically identical in geometry, and have + also been made as data clones of one another.</para> + + <para>When using FreeBSD, always restore the BIOS to natural drive + numbering before installing FreeBSD, and then leave it that way. If you + need to switch drives around, then do so, but do it the hard way, and + open the case and move the jumpers and cables.</para> + + <sidebar> + <title>An Illustration from the Files of Bill and Fred's Exceptional + Adventures:</title> + + <para>Bill breaks-down an older Wintel box to make another FreeBSD box + for Fred. Bill installs a single SCSI drive as SCSI unit zero and + installs FreeBSD on it.</para> + + <para>Fred begins using the system, but after several days notices that + the older SCSI drive is reporting numerous soft errors and reports + this fact to Bill.</para> + + <para>After several more days, Bill decides it is time to address the + situation, so he grabs an identical SCSI drive from the disk drive + <quote>archive</quote> in the back room. An initial surface scan + indicates that + this drive is functioning well, so Bill installs this drive as SCSI + unit four and makes an image copy from drive zero to drive four. Now + that the new drive is installed and functioning nicely, Bill decides + that it is a good idea to start using it, so he uses features in the + SCSI BIOS to re-order the disk drives so that the system boots from + SCSI unit four. FreeBSD boots and runs just fine.</para> + + <para>Fred continues his work for several days, and soon Bill and Fred + decide that it is time for a new adventure — time to upgrade + to a + newer version of FreeBSD. Bill removes SCSI unit zero because it was + a bit flaky and replaces it with another identical disk drive from + the <quote>archive</quote>. Bill then installs the new version of + FreeBSD onto the new SCSI unit zero using Fred's magic Internet FTP + floppies. The installation goes well.</para> + + <para>Fred uses the new version of FreeBSD for a few days, and certifies + that it is good enough for use in the engineering department. It is + time to copy all of his work from the old version. So Fred mounts + SCSI unit four (the latest copy of the older FreeBSD version). Fred + is dismayed to find that none of his precious work is present on SCSI + unit four.</para> + + <para>Where did the data go?</para> + + <para>When Bill made an image copy of the original SCSI unit zero onto + SCSI unit four, unit four became the <quote>new clone</quote>. + When Bill re-ordered the SCSI BIOS so that he could boot from + SCSI unit four, he was only fooling himself. + FreeBSD was still running on SCSI unit zero. + Making this kind of BIOS change will cause some or all of the Boot and + Loader code to be fetched from the selected BIOS drive, but when the + FreeBSD kernel drivers take-over, the BIOS drive numbering will be + ignored, and FreeBSD will transition back to normal drive numbering. + In the illustration at hand, the system continued to operate on the + original SCSI unit zero, and all of Fred's data was there, not on SCSI + unit four. The fact that the system appeared to be running on SCSI + unit four was simply an artifact of human expectations.</para> + + <para>We are delighted to mention that no data bytes were killed or + harmed in any way by our discovery of this phenomenon. The older SCSI + unit zero was retrieved from the bone pile, and all of Fred's work was + returned to him, (and now Bill knows that he can count as high as + zero).</para> + + <para>Although SCSI drives were used in this illustration, the concepts + apply equally to IDE drives.</para> + </sidebar> + </sect2> + + <sect2 id="main-fdisk"> + <title>Creating Slices Using FDisk</title> + + <note> + <para>No changes you make at this point will be written to the disk. + If you think you have made a mistake and want to start again you can + use the menus to exit <application>sysinstall</application> and try + again or press <keycap>U</keycap> to use the + <guimenuitem>Undo</guimenuitem> option. + If you get confused and can not see how to exit you can + always turn your computer off.</para> + </note> + + <para>After choosing to begin a standard installation in + <application>sysinstall</application> you will be shown this + message:</para> + + <screen> Message + In the next menu, you will need to set up a DOS-style ("fdisk") + partitioning scheme for your hard disk. If you simply wish to devote + all disk space to FreeBSD (overwriting anything else that might be on + the disk(s) selected) then use the (A)ll command to select the default + partitioning scheme followed by a (Q)uit. If you wish to allocate only + free space to FreeBSD, move to a partition marked "unused" and use the + (C)reate command. + [ OK ] + + [ Press enter or space ]</screen> + + <para>Press <keycap>Enter</keycap> as instructed. You will then be + shown a list of all the hard drives that the kernel found when it + carried out the device probes. + <xref linkend="sysinstall-fdisk-drive1"> shows an example from a + system with two IDE disks. They have been called + <devicename>ad0</devicename> and <devicename>ad2</devicename>.</para> + + <figure id="sysinstall-fdisk-drive1"> + <title>Select Drive for FDisk</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/fdisk-drive1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>You might be wondering why <devicename>ad1</devicename> is not + listed here. Why has it been missed?</para> + + <para>Consider what would happen if you had two IDE hard disks, one + as the master on the first IDE controller, and one as the master on + the second IDE controller. If FreeBSD numbered these as it found + them, as <devicename>ad0</devicename> and + <devicename>ad1</devicename> then everything would work.</para> + + <para>But if you then added a third disk, as the slave device on the + first IDE controller, it would now be <devicename>ad1</devicename>, + and the previous <devicename>ad1</devicename> would become + <devicename>ad2</devicename>. Because device names (such as + <devicename>ad1s1a</devicename>) are used to find filesystems, you + may suddenly discover that some of your filesystems no longer + appear correctly, and you would need to change your FreeBSD + configuration.</para> + + <para>To work around this, the kernel can be configured to name IDE + disks based on where they are, and not the order in which they were + found. With this scheme the master disk on the second IDE + controller will <emphasis>always</emphasis> be + <devicename>ad2</devicename>, even if there are no + <devicename>ad0</devicename> or <devicename>ad1</devicename> + devices.</para> + + <para>This configuration is the default for the FreeBSD kernel, which + is why this display shows <devicename>ad0</devicename> and + <devicename>ad2</devicename>. The machine on which this screenshot + was taken had IDE disks on both master channels of the IDE + controllers, and no disks on the slave channels.</para> + + <para>You should select the disk on which you want to install FreeBSD, + and then press &gui.ok;. + <application>FDisk</application> will start, with a display similar to + that shown in <xref linkend="sysinstall-fdisk1">.</para> + + <para>The <application>FDisk</application> display is broken into three + sections.</para> + + <para>The first section, covering the first two lines of the display, + shows details about the currently selected disk, including its FreeBSD + name, the disk geometry, and the total size of the disk.</para> + + <para>The second section shows the slices that are currently on the + disk, where they start and end, how large they are, the name FreeBSD + gives them, and their description and sub-type. This example shows two + small unused slices, which are artifacts of disk layout schemes on the + PC. It also shows one large <acronym>FAT</acronym> slice, which + almost certainly appears as <devicename>C:</devicename> in + &ms-dos; / &windows;, and an extended slice, which may contain other + drive letters for &ms-dos; / &windows;.</para> + + <para>The third section shows the commands that are available in + <application>FDisk</application>.</para> + + <figure id="sysinstall-fdisk1"> + <title>Typical <command>fdisk</command> Partitions Before Editing</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/fdisk-edit1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>What you do now will depend on how you want to slice up your + disk.</para> + + <para>If you want to use FreeBSD for the entire disk (which will delete + all the other data on this disk when you confirm that you want + <application>sysinstall</application> to continue later in the + installation process) then you can press <keycap>A</keycap>, which + corresponds to the <guimenuitem>Use Entire Disk</guimenuitem> option. + The existing slices will be removed, and replaced with a small area + flagged as <literal>unused</literal> (again, an artifact of PC disk + layout), and then one large slice for FreeBSD. If you do this, then + you should select the newly created FreeBSD slice using the arrow + keys, and press <keycap>S</keycap> to mark the slice as being + bootable. The screen will then look very similar to + <xref linkend="sysinstall-fdisk2">. Note the + <literal>A</literal> in the <literal>Flags</literal> column, which + indicates that this slice is <emphasis>active</emphasis>, and will be + booted from.</para> + + <para>If you will be deleting an existing slice to make space for + FreeBSD then you should select the slice using the arrow keys, and + then press <keycap>D</keycap>. You can then press <keycap>C</keycap>, + and be prompted for size of slice you want to create. Enter the + appropriate figure and press <keycap>Enter</keycap>. The default + value in this box represents the largest possible slice you can + make, which could be the largest contiguous block of unallocated + space or the size of the entire hard disk.</para> + + <para>If you have already made space for FreeBSD (perhaps by using a + tool such as <application>&partitionmagic;</application>) then you can + press <keycap>C</keycap> to create a new slice. Again, you will be + prompted for the size of slice you would like to create.</para> + + <figure id="sysinstall-fdisk2"> + <title>Fdisk Partition Using Entire Disk</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/fdisk-edit2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>When finished, press <keycap>Q</keycap>. Your changes will be + saved in <application>sysinstall</application>, but will not yet be + written to disk.</para> + </sect2> + + <sect2 id="bootmgr"> + <title>Install a Boot Manager</title> + + <para>You now have the option to install a boot manager. In general, + you should choose to install the FreeBSD boot manager if:</para> + + <itemizedlist> + <listitem> + <para>You have more than one drive, and have installed FreeBSD onto + a drive other than the first one.</para> + </listitem> + + <listitem> + <para>You have installed FreeBSD alongside another operating system + on the same disk, and you want to choose whether to start FreeBSD + or the other operating system when you start the computer.</para> + </listitem> + </itemizedlist> + + <para>If FreeBSD is going to be the only operating system on + this machine, installed on the first hard disk, then the + <guimenuitem>Standard</guimenuitem> boot manager will suffice. + Choose <guimenuitem>None</guimenuitem> if you are using a + third-party boot manager capable of booting FreeBSD.</para> + + <para>Make your choice and press <keycap>Enter</keycap>.</para> + + <figure id="sysinstall-bootmgr"> + <title>Sysinstall Boot Manager Menu</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/boot-mgr" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The help screen, reached by pressing <keycap>F1</keycap>, + discusses the problems that can be encountered when trying to share + the hard disk between operating systems.</para> + </sect2> + + <sect2> + <title>Creating Slices on Another Drive</title> + + <para>If there is more than one drive, it will return to the + Select Drives screen after the boot manager selection. If you wish to + install FreeBSD on to more than one disk, then you can select another + disk here and repeat the slice process using + <application>FDisk</application>.</para> + + <important> + <para>If you are installing FreeBSD on a drive other than your + first, then the FreeBSD boot manager needs to be installed on + both drives.</para> + </important> + + <figure id="sysinstall-fdisk-drive2"> + <title>Exit Select Drive</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/fdisk-drive2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The <keycap>Tab</keycap> key toggles between the last drive + selected, &gui.ok;, and + &gui.cancel;.</para> + + <para>Press the <keycap>Tab</keycap> once to toggle to the + &gui.ok;, then + press <keycap>Enter</keycap> + to continue with the installation.</para> + </sect2> + + <sect2 id="bsdlabeleditor"> + <title>Creating Partitions Using + <application>Disklabel</application></title> + + <para>You must now create some partitions inside each slice that you + have just created. Remember that each partition is lettered, from + <literal>a</literal> through to <literal>h</literal>, and that + partitions <literal>b</literal>, <literal>c</literal>, and + <literal>d</literal> have conventional meanings that you should adhere + to.</para> + + <para>Certain applications can benefit from particular partition + schemes, especially if you are laying out partitions across more than + one disk. However, for this, your first FreeBSD installation, you do + not need to give too much thought to how you partition the disk. It + is more important that you install FreeBSD and start learning how to + use it. You can always re-install FreeBSD to change your partition + scheme when you are more familiar with the operating system.</para> + + <para>This scheme features four partitions—one for swap space, and + three for filesystems.</para> + + <table frame="none" pgwide="1"> + <title>Partition Layout for First Disk</title> + + <tgroup cols="4"> + <colspec colwidth="1*"> + <colspec colwidth="1*"> + <colspec colwidth="1*"> + <colspec colwidth="4*"> + + <thead> + <row> + <entry>Partition</entry> + + <entry>Filesystem</entry> + + <entry>Size</entry> + + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>a</literal></entry> + + <entry><filename>/</filename></entry> + + <entry>1 GB</entry> + + <entry>This is the root filesystem. Every other filesystem + will be mounted somewhere under this one. 1 GB is a + reasonable size for this filesystem. You will not be storing + too much data on it, as a regular FreeBSD install will put + about 128 MB of data here. The remaining space is for + temporary data, and also leaves expansion space if future + versions of + FreeBSD need more space in <filename>/</filename>.</entry> + </row> + + <row> + <entry><literal>b</literal></entry> + + <entry>N/A</entry> + + <entry>2-3 x RAM</entry> + + <entry><para>The system's swap space is kept on the <literal>b</literal> partition. + Choosing the right amount of swap space can be a bit of an + art. A good rule of thumb is that your swap + space should be two or three times as much as the + available physical memory (RAM). + You should also have at least 64 MB of swap, so if you + have less than 32 MB of RAM in your computer then set + the swap amount to 64 MB.</para><para> + + If you have more than one disk then you can put swap + space on each disk. FreeBSD will then use each disk for + swap, which effectively speeds up the act of swapping. In + this case, calculate the total amount of swap you need + (e.g., 128 MB), and then divide this by the number of + disks you have (e.g., two disks) to give the amount of swap + you should put on each disk, in this example, 64 MB of + swap per disk.</para></entry> + </row> + + <row> + <entry><literal>e</literal></entry> + + <entry><filename>/var</filename></entry> + + <entry>512 MB to 4096 MB</entry> + + <entry>The <filename>/var</filename> directory contains + files that are constantly varying; + log files, and other administrative files. Many + of these files are read-from or written-to extensively during + FreeBSD's day-to-day running. Putting these files on another + filesystem allows FreeBSD to optimize the access of these + files without affecting other files in other directories that + do not have the same access pattern.</entry> + </row> + + <row> + <entry><literal>f</literal></entry> + + <entry><filename>/usr</filename></entry> + + <entry>Rest of disk (at least 8 GB)</entry> + + <entry>All your other files will typically be stored in + <filename>/usr</filename> and its subdirectories.</entry> + </row> + </tbody> + </tgroup> + </table> + + <warning> + <para>The values above are given as example and should be used + by experienced users only. Users are encouraged to use the + automatic partition layout called <literal>Auto + Defaults</literal> by the &os; partition editor.</para> + </warning> + + <para>If you will be installing FreeBSD on to more than one disk then + you must also create partitions in the other slices that you + configured. The easiest way to do this is to create two partitions on + each disk, one for the swap space, and one for a filesystem.</para> + + <table frame="none" pgwide="1"> + <title>Partition Layout for Subsequent Disks</title> + + <tgroup cols="4"> + <colspec colwidth="1*"> + <colspec colwidth="1*"> + <colspec colwidth="2*"> + <colspec colwidth="3*"> + + <thead> + <row> + <entry>Partition</entry> + + <entry>Filesystem</entry> + + <entry>Size</entry> + + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><literal>b</literal></entry> + + <entry>N/A</entry> + + <entry>See description</entry> + + <entry>As already discussed, you can split swap space across + each disk. Even though the <literal>a</literal> partition is + free, convention dictates that swap space stays on the + <literal>b</literal> partition.</entry> + </row> + + <row> + <entry><literal>e</literal></entry> + + <entry>/disk<replaceable>n</replaceable></entry> + + <entry>Rest of disk</entry> + + <entry>The rest of the disk is taken up with one big partition. + This could easily be put on the <literal>a</literal> + partition, instead of the <literal>e</literal> partition. + However, convention says that the <literal>a</literal> + partition on a slice is reserved for the filesystem that will + be the root (<filename>/</filename>) filesystem. You do not + have to follow this convention, but + <application>sysinstall</application> does, so following it + yourself makes the installation slightly cleaner. You can + choose to mount this filesystem anywhere; this example + suggests that you mount them as directories + <filename>/disk<replaceable>n</replaceable></filename>, where + <replaceable>n</replaceable> is a number that changes for each + disk. But you can use another scheme if you prefer.</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Having chosen your partition layout you can now create it using + <application>sysinstall</application>. You will see this + message:</para> + + <screen> Message + Now, you need to create BSD partitions inside of the fdisk + partition(s) just created. If you have a reasonable amount of disk + space (1GB or more) and don't have any special requirements, simply + use the (A)uto command to allocate space automatically. If you have + more specific needs or just don't care for the layout chosen by + (A)uto, press F1 for more information on manual layout. + + [ OK ] + [ Press enter or space ]</screen> + + <para>Press <keycap>Enter</keycap> to start the FreeBSD partition + editor, called <application>Disklabel</application>.</para> + + <para><xref linkend="sysinstall-label"> shows the display when you first + start <application>Disklabel</application>. The display is divided in + to three sections.</para> + + <para>The first few lines show the name of the disk you are currently + working on, and the slice that contains the partitions you are + creating (at this point <application>Disklabel</application> calls + this the <literal>Partition name</literal> rather than slice name). + This display also shows the amount of free space within the slice; + that is, space that was set aside in the slice, but that has not yet + been assigned to a partition.</para> + + <para>The middle of the display shows the partitions that have been + created, the name of the filesystem that each partition contains, + their size, and some options pertaining to the creation of the + filesystem.</para> + + <para>The bottom third of the screen shows the keystrokes that are valid + in <application>Disklabel</application>.</para> + + <figure id="sysinstall-label"> + <title>Sysinstall Disklabel Editor</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/disklabel-ed1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para><application>Disklabel</application> can automatically create + partitions for you and assign them default sizes. The default sizes + are calculated with the help of an internal partition sizing algorithm + based on the disk size. Try this now, by + Pressing <keycap>A</keycap>. You will see a display similar to that + shown in <xref linkend="sysinstall-label2">. Depending on the size of + the disk you are using, the defaults may or may not be appropriate. + This does not matter, as you do not have to accept the + defaults.</para> + + <note> + <para>The default partitioning assigns + the <filename>/tmp</filename> directory its own partition instead + of being part of the <filename>/</filename> partition. This + helps avoid filling the <filename>/</filename> partition with + temporary files.</para> + </note> + + <figure id="sysinstall-label2"> + <title>Sysinstall Disklabel Editor with Auto Defaults</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/disklabel-auto" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>If you choose to not use the default partitions and wish to + replace them with your + own, use the arrow keys to select the first partition, and press + <keycap>D</keycap> to delete it. Repeat this to delete all the + suggested partitions.</para> + + <para>To create the first partition (<literal>a</literal>, mounted as + <filename>/</filename> — root), make sure the proper disk slice + at the top of + the screen is selected and press <keycap>C</keycap>. A dialog box + will appear prompting you for the size of the new partition (as shown + in <xref linkend="sysinstall-label-add">). You can enter the size as + the number of disk blocks you want to use, or as a + number followed by either <literal>M</literal> for megabytes, + <literal>G</literal> for gigabytes, or <literal>C</literal> for + cylinders.</para> + + <figure id="sysinstall-label-add"> + <title>Free Space for Root Partition</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/disklabel-root1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The default size shown will create a partition that takes up the + rest of the slice. If you are using the partition sizes described + in the earlier example, then delete the existing figure using + <keycap>Backspace</keycap>, and then type in + <userinput>512M</userinput>, as shown in + <xref linkend="sysinstall-label-add2">. Then press + &gui.ok;.</para> + + <figure id="sysinstall-label-add2"> + <title>Edit Root Partition Size</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/disklabel-root2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Having chosen the partition's size you will then be asked whether + this partition will contain a filesystem or swap space. The dialog + box is shown in <xref linkend="sysinstall-label-type">. This first + partition will contain a filesystem, so check that + <guimenuitem>FS</guimenuitem> is selected and press + <keycap>Enter</keycap>.</para> + + <figure id="sysinstall-label-type"> + <title>Choose the Root Partition Type</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/disklabel-fs" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Finally, because you are creating a filesystem, you must tell + <application>Disklabel</application> where the filesystem is to be + mounted. The dialog box is shown in + <xref linkend="sysinstall-label-mount">. The root filesystem's mount + point is <filename>/</filename>, so type <userinput>/</userinput>, and + then press <keycap>Enter</keycap>.</para> + + <figure id="sysinstall-label-mount"> + <title>Choose the Root Mount Point</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/disklabel-root3" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The display will then update to show you the newly created + partition. You should repeat this procedure for the other + partitions. When you create the swap partition, you will not be + prompted for the filesystem mount point, as swap partitions are never + mounted. When you create the final partition, + <filename>/usr</filename>, you can leave the suggested size as is, to + use the rest of the slice.</para> + + <para>Your final FreeBSD DiskLabel Editor screen will appear similar to + <xref linkend="sysinstall-label4">, although your values chosen may + be different. Press <keycap>Q</keycap> to finish.</para> + + <figure id="sysinstall-label4"> + <title>Sysinstall Disklabel Editor</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/disklabel-ed2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + </sect2> + </sect1> + + <sect1 id="install-choosing"> + <title>Choosing What to Install</title> + + <sect2 id="distset"> + <title>Select the Distribution Set</title> + + <para>Deciding which distribution set to install will depend largely + on the intended use of the system and the amount of disk space + available. The predefined options range from installing the + smallest possible configuration to everything. Those who are + new to &unix; and/or FreeBSD should almost certainly select one + of these canned options. Customizing a distribution set is + typically for the more experienced user.</para> + + <para>Press <keycap>F1</keycap> for more information on the + distribution set options and what they contain. When finished + reviewing the help, pressing <keycap>Enter</keycap> will return + to the Select Distributions Menu.</para> + + <para>If a graphical user interface is desired then the + configuration of the X server and selection of a default + desktop must be done after the installation of &os;. More + information regarding the installation and configuration of a + X server can be found in <xref linkend="x11">.</para> + + <para>If compiling a custom kernel is anticipated, select an option + which includes the source code. For more information on why a + custom kernel should be built or how to build a custom kernel, see + <xref linkend="kernelconfig">.</para> + + <para>Obviously, the most versatile system is one that includes + everything. If there is adequate disk space, select + <guimenuitem>All</guimenuitem> as shown in + <xref linkend="distribution-set1"> by using the arrow keys and + press <keycap>Enter</keycap>. If there is a concern about disk + space consider using an option that is more suitable for the + situation. + Do not fret over the perfect choice, as other distributions can be + added after installation.</para> + + <figure id="distribution-set1"> + <title>Choose Distributions</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/dist-set" format="PNG"> + </imageobject> + </mediaobject> + </figure> + </sect2> + + <sect2 id="portscol"> + <title>Installing the Ports Collection</title> + + <para>After selecting the desired distribution, an opportunity to + install the FreeBSD Ports Collection is presented. The ports + collection is an easy and convenient way to install software. + The Ports Collection does not contain the source code necessary + to compile the software. Instead, it is a collection of files which + automates the downloading, compiling and installation + of third-party software packages. + <xref linkend="ports"> discusses how to use the ports + collection.</para> + + <para>The installation program does not check to see if you have + adequate space. Select this option only if you have + adequate hard disk space. As of FreeBSD &rel.current;, the FreeBSD + Ports Collection takes up about &ports.size; of disk space. + You can safely assume a larger value for more recent versions + of FreeBSD.</para> + +<screen> User Confirmation Requested + Would you like to install the FreeBSD ports collection? + + This will give you ready access to over &os.numports; ported software packages, + at a cost of around &ports.size; of disk space when "clean" and possibly much + more than that if a lot of the distribution tarballs are loaded + (unless you have the extra CDs from a FreeBSD CD/DVD distribution + available and can mount it on /cdrom, in which case this is far less + of a problem). + + The Ports Collection is a very valuable resource and well worth having + on your /usr partition, so it is advisable to say Yes to this option. + + For more information on the Ports Collection & the latest ports, + visit: + http://www.FreeBSD.org/ports + + [ Yes ] No</screen> + + <para>Select &gui.yes; with the arrow keys to + install the Ports Collection or &gui.no; to + skip this option. Press <keycap>Enter</keycap> to continue. + The Choose Distributions menu will redisplay.</para> + + <figure id="distribution-set2"> + <title>Confirm Distributions</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/dist-set2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>If satisfied with the options, select + <guimenuitem>Exit</guimenuitem> with the arrow keys, ensure that + &gui.ok; is highlighted, and pressing + <keycap>Enter</keycap> to continue.</para> + + </sect2> + </sect1> + + <sect1 id="install-media"> + <title>Choosing Your Installation Media</title> + + <para>If Installing from a CDROM or DVD, use the arrow keys to highlight + <guimenuitem>Install from a FreeBSD CD/DVD</guimenuitem>. Ensure + that &gui.ok; is highlighted, then press + <keycap>Enter</keycap> to proceed with the installation.</para> + + <para>For other methods of installation, select the appropriate + option and follow the instructions.</para> + + <para>Press <keycap>F1</keycap> to display the Online Help for + installation media. Press <keycap>Enter</keycap> to return + to the media selection menu.</para> + + <figure id="choose-media"> + <title>Choose Installation Media</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/media" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <note> + <title>FTP Installation Modes</title> + + <indexterm> + <primary>installation</primary> + <secondary>network</secondary> + <tertiary>FTP</tertiary> + </indexterm> + + <para>There are three FTP installation modes you can choose from: + active FTP, passive FTP, or via a HTTP proxy.</para> + + <variablelist> + <varlistentry> + <term>FTP Active: <guimenuitem>Install from an FTP + server</guimenuitem></term> + + <listitem> + <para>This option will make all FTP transfers + use <quote>Active</quote> + mode. This will not work through firewalls, but will + often work with older FTP servers that do not support + passive mode. If your connection hangs with passive + mode (the default), try active!</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FTP Passive: <guimenuitem>Install from an FTP server through a + firewall</guimenuitem></term> + + <listitem> + <indexterm> + <primary>FTP</primary> + <secondary>passive mode</secondary> + </indexterm> + + <para>This option instructs <application>sysinstall</application> + to <quote>Passive</quote> mode for all FTP operations. + This allows the user to pass through firewalls + that do not allow incoming connections on random TCP ports. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FTP via a HTTP proxy: <guimenuitem>Install from an FTP server + through a http proxy</guimenuitem></term> + + <listitem> + <indexterm> + <primary>FTP</primary> + <secondary>via a HTTP proxy</secondary> + </indexterm> + + <para>This option instructs <application>sysinstall</application> + to use the HTTP + protocol (like a web browser) to connect to a proxy + for all FTP operations. The proxy will translate + the requests and send them to the FTP server. + This allows the user to pass through firewalls + that do not allow FTP at all, but offer a HTTP + proxy. + In this case, you have to specify the proxy in + addition to the FTP server.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>For a proxy FTP server, you should usually give the name of the + server you really want as a part of the username, after an + <quote>@</quote> sign. The proxy server then <quote>fakes</quote> + the real server. For example, assuming you want to install from + <hostid role="fqdn">ftp.FreeBSD.org</hostid>, using the proxy FTP + server <hostid role="fqdn">foo.example.com</hostid>, listening on port + 1234.</para> + + <para>In this case, you go to the options menu, set the FTP username + to <literal>ftp@ftp.FreeBSD.org</literal>, and the password to your + email address. As your installation media, you specify FTP (or + passive FTP, if the proxy supports it), and the URL + <literal>ftp://foo.example.com:1234/pub/FreeBSD</literal>.</para> + + <para>Since <filename>/pub/FreeBSD</filename> from + <hostid role="fqdn">ftp.FreeBSD.org</hostid> is proxied under + <hostid role="fqdn">foo.example.com</hostid>, you are able to install + from <emphasis>that</emphasis> machine (which will fetch the files + from <hostid role="fqdn">ftp.FreeBSD.org</hostid> as your + installation requests them).</para> + </note> + </sect1> + + <sect1 id="install-final-warning"> + <title>Committing to the Installation</title> + + <para>The installation can now proceed if desired. This is also + the last chance for aborting the installation to prevent changes + to the hard drive.</para> + + <screen> User Confirmation Requested + Last Chance! Are you SURE you want to continue the installation? + + If you're running this on a disk with data you wish to save then WE + STRONGLY ENCOURAGE YOU TO MAKE PROPER BACKUPS before proceeding! + + We can take no responsibility for lost disk contents! + + [ Yes ] No</screen> + + <para>Select &gui.yes; and press + <keycap>Enter</keycap> to proceed.</para> + + <para>The installation time will vary according to the distribution + chosen, installation media, and the speed of the computer. + There will be a series of + messages displayed indicating the status.</para> + + <para>The installation is complete when the following message is + displayed:</para> + + <screen> Message + +Congratulations! You now have FreeBSD installed on your system. + +We will now move on to the final configuration questions. +For any option you do not wish to configure, simply select No. + +If you wish to re-enter this utility after the system is up, you may +do so by typing: /usr/sbin/sysinstall. + + [ OK ] + + [ Press enter or space ]</screen> + + <para>Press <keycap>Enter</keycap> to proceed with post-installation + configurations.</para> + + <para>Selecting &gui.no; and pressing + <keycap>Enter</keycap> will abort + the installation so no changes will be made to your system. The + following message will appear:</para> + + <screen> Message +Installation complete with some errors. You may wish to scroll +through the debugging messages on VTY1 with the scroll-lock feature. +You can also choose "No" at the next prompt and go back into the +installation menus to retry whichever operations have failed. + + [ OK ]</screen> + + <para>This message is generated because nothing was installed. + Pressing <keycap>Enter</keycap> will return to the + Main Installation Menu to exit the installation.</para> + </sect1> + + <sect1 id="install-post"> + <title>Post-installation</title> + + <para>Configuration of various options follows the successful + installation. An option can be configured by re-entering the + configuration options before booting the new FreeBSD + system or after installation using + <command>sysinstall</command> + and selecting + <guimenuitem>Configure</guimenuitem>.</para> + + <sect2 id="inst-network-dev"> + <title>Network Device Configuration</title> + + <para>If you previously configured PPP for an FTP install, this screen + will not display and can be configured later as described + above.</para> + + <para>For detailed information on Local Area Networks and + configuring FreeBSD as a gateway/router refer to the + <link linkend="advanced-networking">Advanced Networking</link> + chapter.</para> + + <screen> User Confirmation Requested + Would you like to configure any Ethernet or PPP network devices? + + [ Yes ] No</screen> + + <para>To configure a network device, select + &gui.yes; and press <keycap>Enter</keycap>. + Otherwise, select &gui.no; to continue.</para> + + <figure id="ed-config1"> + <title>Selecting an Ethernet Device</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/ed0-conf" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Select the interface to be configured with the arrow keys and press + <keycap>Enter</keycap>.</para> + + <screen> User Confirmation Requested + Do you want to try IPv6 configuration of the interface? + + Yes [ No ]</screen> + + <para>In this private local area network, the current Internet + type protocol (<acronym>IPv4</acronym>) was sufficient and &gui.no; + was selected with the arrow keys and <keycap>Enter</keycap> + pressed.</para> + + <para>If you are connected to an existing <acronym>IPv6</acronym> network + with an <acronym>RA</acronym> server, then choose + &gui.yes; and press <keycap>Enter</keycap>. + It will take several seconds to scan for RA servers.</para> + + <screen> User Confirmation Requested + Do you want to try DHCP configuration of the interface? + + Yes [ No ]</screen> + + <para>If DHCP (Dynamic Host Configuration Protocol) is not required + select &gui.no; with the arrow keys and press + <keycap>Enter</keycap>.</para> + + <para>Selecting &gui.yes; will execute + <application>dhclient</application>, and if successful, will fill + in the network configuration information automatically. Refer to + <xref linkend="network-dhcp"> for more information.</para> + + <para>The following Network Configuration screen shows the + configuration of the Ethernet device for a system that will act + as the gateway for a Local Area Network.</para> + + <figure id="ed-config2"> + <title>Set Network Configuration for <replaceable>ed0</replaceable></title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/ed0-conf2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Use <keycap>Tab</keycap> to select the information fields and + fill in appropriate information:</para> + + <variablelist> + <varlistentry> + <term>Host</term> + + <listitem> + <para>The fully-qualified hostname, such as + <hostid role="fqdn">k6-2.example.com</hostid> in + this case.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Domain</term> + + <listitem> + <para>The name of the domain that your machine is + in, such as <hostid role="domainname">example.com</hostid> + for this case.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IPv4 Gateway</term> + + <listitem> + <para>IP address of host forwarding packets to non-local + destinations. You must fill this in if the machine is a node + on the network. <emphasis>Leave this field blank</emphasis> + if the machine is the gateway to the Internet for the + network. The IPv4 Gateway is also known as the default + gateway or default route.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Name server</term> + + <listitem> + <para>IP address of your local DNS server. There is no local + DNS server on this private local area network so the IP + address of the provider's DNS server + (<hostid role="ipaddr">208.163.10.2</hostid>) was used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>IPv4 address</term> + + <listitem> + <para>The IP address to be used for this interface was + <hostid role="ipaddr">192.168.0.1</hostid></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Netmask</term> + + <listitem> + <para>The address block being used for this local area + network is + <hostid role="ipaddr">192.168.0.0</hostid> - + <hostid role="ipaddr">192.168.0.255</hostid> + with a netmask of + <hostid role="netmask">255.255.255.0</hostid>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Extra options to ifconfig</term> + + <listitem> + <para>Any interface-specific options to <command>ifconfig</command> + you would like to add. There were none in this case.</para> + </listitem> + </varlistentry> + + </variablelist> + + <para>Use <keycap>Tab</keycap> to select &gui.ok; + when finished and press <keycap>Enter</keycap>.</para> + + + <screen> User Confirmation Requested + Would you like to bring the ed0 interface up right now? + + [ Yes ] No</screen> + + <para>Choosing &gui.yes; and pressing + <keycap>Enter</keycap> will bring + the machine up on the network and be ready for use. However, + this does not accomplish much during installation, since + the machine still needs to be rebooted.</para> + </sect2> + + <sect2 id="gateway"> + <title>Configure Gateway</title> + + <screen> User Confirmation Requested + Do you want this machine to function as a network gateway? + + [ Yes ] No</screen> + + <para>If the machine will be acting as the gateway for a local area + network and forwarding packets between other machines then select + &gui.yes; and press <keycap>Enter</keycap>. + If the machine is a node on a network then + select &gui.no; and press + <keycap>Enter</keycap> to continue.</para> + </sect2> + + <sect2 id="inetd-services"> + <title>Configure Internet Services</title> + + <screen> User Confirmation Requested +Do you want to configure inetd and the network services that it provides? + + Yes [ No ]</screen> + + <para>If &gui.no; is selected, various services + such <application>telnetd</application> will not be enabled. This + means that remote users will not be able to + <application>telnet</application> into this machine. Local users + will still be able to access remote machines with + <application>telnet</application>.</para> + + <para>These services can be enabled after installation by editing + <filename>/etc/inetd.conf</filename> with your favorite text editor. + See <xref linkend="network-inetd-overview"> for more information.</para> + + <para>Select &gui.yes; if you wish to + configure these services during install. An additional + confirmation will display:</para> + + <screen> User Confirmation Requested +The Internet Super Server (inetd) allows a number of simple Internet +services to be enabled, including finger, ftp and telnetd. Enabling +these services may increase risk of security problems by increasing +the exposure of your system. + +With this in mind, do you wish to enable inetd? + + [ Yes ] No</screen> + + <para>Select &gui.yes; to continue.</para> + + <screen> User Confirmation Requested +inetd(8) relies on its configuration file, /etc/inetd.conf, to determine +which of its Internet services will be available. The default FreeBSD +inetd.conf(5) leaves all services disabled by default, so they must be +specifically enabled in the configuration file before they will +function, even once inetd(8) is enabled. Note that services for +IPv6 must be separately enabled from IPv4 services. + +Select [Yes] now to invoke an editor on /etc/inetd.conf, or [No] to +use the current settings. + + [ Yes ] No</screen> + + <para>Selecting &gui.yes; will allow adding + services by deleting the <literal>#</literal> at the beginning + of a line.</para> + + <figure id="inetd-edit"> + <title>Editing <filename>inetd.conf</filename></title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/edit-inetd-conf" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>After adding the desired services, pressing <keycap>Esc</keycap> + will display a menu which will allow exiting and saving + the changes.</para> + + </sect2> + + <sect2 id="ssh-login"> + <title>Enabling SSH login</title> + + <indexterm> + <primary>SSH</primary> + <secondary>sshd</secondary> + </indexterm> + + <screen> User Confirmation Requested + Would you like to enable SSH login? + Yes [ No ]</screen> + + <para>Selecting &gui.yes; will enable &man.sshd.8;, the daemon + program for <application>OpenSSH</application>. This will + allow secure remote access to your machine. For more + information about <application>OpenSSH</application> see <xref + linkend="openssh">.</para> + </sect2> + + <sect2 id="ftpanon"> + <title>Anonymous FTP</title> + + <indexterm> + <primary>FTP</primary> + <secondary>anonymous</secondary> + </indexterm> + + <screen> User Confirmation Requested + Do you want to have anonymous FTP access to this machine? + + Yes [ No ]</screen> + + <sect3 id="deny-anon"> + <title>Deny Anonymous FTP</title> + + <para>Selecting the default &gui.no; and pressing + <keycap>Enter</keycap> will still allow users who have accounts + with passwords to use FTP to access the machine.</para> + </sect3> + + <sect3 id="ftpallow"> + <title>Allow Anonymous FTP</title> + + <para>Anyone can access your machine if you elect to allow + anonymous FTP connections. The security implications should be + considered before enabling this option. For more information + about security see <xref linkend="security">.</para> + + <para>To allow anonymous FTP, use the arrow keys to select + &gui.yes; and press <keycap>Enter</keycap>. + An additional confirmation will display:</para> + + <screen> User Confirmation Requested + Anonymous FTP permits un-authenticated users to connect to the system + FTP server, if FTP service is enabled. Anonymous users are + restricted to a specific subset of the file system, and the default + configuration provides a drop-box incoming directory to which uploads + are permitted. You must separately enable both inetd(8), and enable + ftpd(8) in inetd.conf(5) for FTP services to be available. If you + did not do so earlier, you will have the opportunity to enable inetd(8) + again later. + + If you want the server to be read-only you should leave the upload + directory option empty and add the -r command-line option to ftpd(8) + in inetd.conf(5) + + Do you wish to continue configuring anonymous FTP? + + [ Yes ] No</screen> + + <para>This message informs you that the FTP service will also + have to be enabled in <filename>/etc/inetd.conf</filename> + if you want to allow anonymous FTP connections, see <xref + linkend="inetd-services">. Select &gui.yes; and press + <keycap>Enter</keycap> to continue; the following screen + will display:</para> + + <figure id="anon-ftp2"> + <title>Default Anonymous FTP Configuration</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/ftp-anon1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Use <keycap>Tab</keycap> to select the information + fields and fill in appropriate information:</para> + + <variablelist> + <varlistentry> + <term>UID</term> + + <listitem> + <para>The user ID you wish to assign to the anonymous + FTP user. All files uploaded will be owned by this + ID.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Group</term> + + <listitem> + <para>Which group you wish the anonymous FTP user to be + in.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Comment</term> + + <listitem> + <para>String describing this user in + <filename>/etc/passwd</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>FTP Root Directory</term> + + <listitem> + <para>Where files available for anonymous FTP will be + kept.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Upload Subdirectory</term> + + <listitem> + <para>Where files uploaded by anonymous FTP users will + go.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The FTP root directory will be put in <filename>/var</filename> + by default. If you do not have enough room there for the + anticipated FTP needs, the <filename>/usr</filename> directory + could be used by setting the FTP root directory to + <filename>/usr/ftp</filename>.</para> + + <para>When you are satisfied with the values, press + <keycap>Enter</keycap> to continue.</para> + + <screen> User Confirmation Requested + Create a welcome message file for anonymous FTP users? + + [ Yes ] No</screen> + + <para>If you select &gui.yes; and press + <keycap>Enter</keycap>, an editor will automatically start + allowing you to edit the message.</para> + + <figure id="anon-ftp4"> + <title>Edit the FTP Welcome Message</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/ftp-anon2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>This is a text editor called <command>ee</command>. Use the + instructions to change the message or change the message later + using a text editor of your choice. Note the file name/location + at the bottom of the editor screen.</para> + + <para>Press <keycap>Esc</keycap> and a pop-up menu will default + to <guimenuitem>a) leave editor</guimenuitem>. Press + <keycap>Enter</keycap> to exit and continue. Press + <keycap>Enter</keycap> again to save changes if you made + any.</para> + </sect3> + </sect2> + + <sect2 id="nfsconf"> + <title>Configure Network File System</title> + + <para>Network File System (NFS) allows sharing of files across a + network. A machine can be configured as a server, a client, or + both. Refer to <xref linkend="network-nfs"> for a more information.</para> + + <sect3 id="nsf-server-options"> + <title>NFS Server</title> + + <screen> User Confirmation Requested + Do you want to configure this machine as an NFS server? + + Yes [ No ]</screen> + + <para>If there is no need for a Network File System server, + select &gui.no; and press + <keycap>Enter</keycap>.</para> + + <para>If &gui.yes; is chosen, a message will + pop-up indicating that the <filename>exports</filename> file must be + created.</para> + + <screen> Message +Operating as an NFS server means that you must first configure an +/etc/exports file to indicate which hosts are allowed certain kinds of +access to your local filesystems. +Press [Enter] now to invoke an editor on /etc/exports + [ OK ]</screen> + + <para>Press <keycap>Enter</keycap> to continue. A text editor will + start allowing the <filename>exports</filename> file to be created + and edited.</para> + + <figure id="nfs-server-edit"> + <title>Editing <filename>exports</filename></title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/nfs-server-edit" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Use the instructions to add the actual exported filesystems + now or later using a text editor of your choice. Note the + file name/location at the bottom of the editor screen.</para> + + <para>Press <keycap>Esc</keycap> and a pop-up menu will default to + <guimenuitem>a) leave editor</guimenuitem>. Press + <keycap>Enter</keycap> to exit and continue.</para> + </sect3> + + <sect3 id="nfs-client-options"> + <title>NFS Client</title> + + <para>The NFS client allows your machine to access NFS servers.</para> + + <screen> User Confirmation Requested + Do you want to configure this machine as an NFS client? + + Yes [ No ]</screen> + + <para>With the arrow keys, select &gui.yes; + or &gui.no; as appropriate and + press <keycap>Enter</keycap>.</para> + </sect3> + </sect2> + + <sect2 id="console"> + <title>System Console Settings</title> + + <para>There are several options available to customize the system + console.</para> + + <screen> User Confirmation Requested + Would you like to customize your system console settings? + + [ Yes ] No</screen> + + <para>To view and configure the options, select + &gui.yes; and press + <keycap>Enter</keycap>.</para> + + <figure id="saver-options"> + <title>System Console Configuration Options</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/console-saver1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>A commonly used option is the screen saver. Use the arrow keys + to select <guimenuitem>Saver</guimenuitem> and then press + <keycap>Enter</keycap>.</para> + + <figure id="saver-select"> + <title>Screen Saver Options</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/console-saver2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Select the desired screen saver using the arrow keys + and then press <keycap>Enter</keycap>. The System Console + Configuration menu will redisplay.</para> + + <para>The default time interval is 300 seconds. To change the time + interval, select <guimenuitem>Saver</guimenuitem> again. At the + Screen Saver Options menu, select <guimenuitem>Timeout</guimenuitem> + using the arrow keys and press <keycap>Enter</keycap>. A pop-up + menu will appear:</para> + + <figure id="saver-timeout"> + <title>Screen Saver Timeout</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/console-saver3" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The value can be changed, then select &gui.ok; + and press <keycap>Enter</keycap> to return to the System Console + Configuration menu.</para> + + <figure id="saver-exit"> + <title>System Console Configuration Exit</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/console-saver4" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Selecting <guimenuitem>Exit</guimenuitem> and pressing + <keycap>Enter</keycap> will continue with the post-installation + configurations.</para> + </sect2> + + <sect2 id="timezone"> + <title>Setting the Time Zone</title> + + <para>Setting the time zone for your machine will allow it to + automatically correct for any regional time changes and perform + other time zone related functions properly.</para> + + <para>The example shown is for a machine located in the Eastern + time zone of the United States. Your selections will vary according + to your geographical location.</para> + + <screen> User Confirmation Requested + Would you like to set this machine's time zone now? + + [ Yes ] No</screen> + + <para>Select &gui.yes; and press + <keycap>Enter</keycap> to set the time zone.</para> + + <screen> User Confirmation Requested + Is this machine's CMOS clock set to UTC? If it is set to local time + or you don't know, please choose NO here! + + Yes [ No ]</screen> + + <para>Select &gui.yes; + or &gui.no; according to how the machine's + clock is configured and press <keycap>Enter</keycap>.</para> + + <figure id="set-timezone-region"> + <title>Select Your Region</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/timezone1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The appropriate region is selected using the arrow keys + and then pressing <keycap>Enter</keycap>.</para> + + <figure id="set-timezone-country"> + <title>Select Your Country</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/timezone2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Select the appropriate country using the arrow keys + and press <keycap>Enter</keycap>.</para> + + <figure id="set-timezone-locality"> + <title>Select Your Time Zone</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/timezone3" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The appropriate time zone is selected using the arrow + keys and pressing <keycap>Enter</keycap>.</para> + + <screen> Confirmation + Does the abbreviation 'EDT' look reasonable? + + [ Yes ] No</screen> + + <para>Confirm the abbreviation for the time zone is correct. + If it looks okay, press <keycap>Enter</keycap> to continue with + the post-installation configuration.</para> + </sect2> + + <sect2 id="linuxcomp"> + <title>Linux Compatibility</title> + + <note> + <para>This part only applies to &os; 7.<replaceable>X</replaceable> + installation, if you install &os; 8.<replaceable>X</replaceable> + this screen will not be proposed.</para> + </note> + + <screen> User Confirmation Requested + Would you like to enable Linux binary compatibility? + + [ Yes ] No</screen> + + <para>Selecting &gui.yes; and pressing + <keycap>Enter</keycap> will allow + running Linux software on FreeBSD. The install will add + the appropriate packages for Linux compatibility.</para> + + <para>If installing by FTP, the machine will need to be connected to + the Internet. Sometimes a remote ftp site will not have all the + distributions like the Linux binary compatibility. This can + be installed later if necessary.</para> + </sect2> + + <sect2 id="mouse"> + <title>Mouse Settings</title> + + <para>This option will allow you to cut and paste text in the + console and user programs with a 3-button mouse. If using a 2-button + mouse, refer to manual page, &man.moused.8;, after installation for + details on emulating the 3-button style. This example depicts a + non-USB mouse configuration (such as a PS/2 or COM port mouse):</para> + + <screen> User Confirmation Requested + Does this system have a PS/2, serial, or bus mouse? + + [ Yes ] No </screen> + + <para>Select &gui.yes; for a PS/2, serial or bus mouse, or + &gui.no; for a USB mouse and press + <keycap>Enter</keycap>.</para> + + <figure id="mouse-protocol"> + <title>Select Mouse Protocol Type</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/mouse1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Use the arrow keys to select <guimenuitem>Type</guimenuitem> and + press <keycap>Enter</keycap>.</para> + + <figure id="set-mouse-protocol"> + <title>Set Mouse Protocol</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/mouse2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The mouse used in this example is a PS/2 type, so the default + <guimenuitem>Auto</guimenuitem> was appropriate. To change protocol, + use the arrow keys to select another option. Ensure that &gui.ok; is + highlighted and press <keycap>Enter</keycap> to exit this menu.</para> + + <figure id="config-mouse-port"> + <title>Configure Mouse Port</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/mouse3" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Use the arrow keys to select <guimenuitem>Port</guimenuitem> and + press <keycap>Enter</keycap>.</para> + + <figure id="set-mouse-port"> + <title>Setting the Mouse Port</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/mouse4" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>This system had a PS/2 mouse, so the default + <guimenuitem>PS/2</guimenuitem> was appropriate. To change the port, + use the arrow keys and then press <keycap>Enter</keycap>.</para> + + <figure id="test-daemon"> + <title>Enable the Mouse Daemon</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/mouse5" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Last, use the arrow keys to select + <guimenuitem>Enable</guimenuitem>, and press + <keycap>Enter</keycap> to enable and test the mouse + daemon.</para> + + + <figure id="test-mouse-daemon"> + <title>Test the Mouse Daemon</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/mouse6" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Move the mouse around the screen and verify the cursor + shown responds properly. If it does, select + &gui.yes; and press <keycap>Enter</keycap>. If + not, the mouse has not been configured correctly — select + &gui.no; and try using different configuration + options.</para> + + <para>Select <guimenuitem>Exit</guimenuitem> with the arrow keys + and press <keycap>Enter</keycap> to return to continue with the + post-installation configuration.</para> + </sect2> + + <sect2 id="packages"> + <title>Install Packages</title> + + <para>Packages are pre-compiled binaries and are a convenient + way to install software.</para> + + <para>Installation of one package is shown for purposes of + illustration. Additional packages can also be added at this + time if desired. After installation + <command>sysinstall</command> can be used to add additional + packages.</para> + + <screen> User Confirmation Requested + The FreeBSD package collection is a collection of hundreds of + ready-to-run applications, from text editors to games to WEB servers + and more. Would you like to browse the collection now? + + [ Yes ] No</screen> + + <para>Selecting &gui.yes; and pressing + <keycap>Enter</keycap> will be + followed by the Package Selection screens:</para> + + <figure id="package-category"> + <title>Select Package Category</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/pkg-cat" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Only packages on the current installation media are + available for installation at any given time.</para> + + <para>All packages available will be displayed if + <guimenuitem>All</guimenuitem> is selected or you can select a + particular category. Highlight your selection with the arrow + keys and press <keycap>Enter</keycap>.</para> + + <para>A menu will display showing all the packages available for + the selection made:</para> + + <figure id="package-select"> + <title>Select Packages</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/pkg-sel" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The <application>bash</application> shell is shown selected. + Select as many as desired by highlighting the package and pressing the + <keycap>Space</keycap> key. A short description of each package will + appear in the lower left corner of the screen.</para> + + <para>Pressing the <keycap>Tab</keycap> key will toggle between the last + selected package, &gui.ok;, and &gui.cancel;.</para> + + <para>When you have finished marking the packages for installation, + press <keycap>Tab</keycap> once to toggle to the &gui.ok; and press + <keycap>Enter</keycap> to return to the Package Selection menu.</para> + + <para>The left and right arrow keys will also toggle between &gui.ok; + and &gui.cancel;. This method can also be used to select &gui.ok; and + press <keycap>Enter</keycap> to return to the Package Selection + menu.</para> + + <figure id="package-install"> + <title>Install Packages</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/pkg-install" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Use the <keycap>Tab</keycap> and arrow keys to select <guibutton>[ Install ]</guibutton> + and press <keycap>Enter</keycap>. You will then need to confirm + that you want to install the packages:</para> + + <figure id="package-install-confirm"> + <title>Confirm Package Installation</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/pkg-confirm" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Selecting &gui.ok; and pressing <keycap>Enter</keycap> will start + the package installation. Installing messages will appear until + completed. Make note if there are any error messages.</para> + + <para>The final configuration continues after packages are + installed. If you end up not selecting any packages, and wish + to return to the final configuration, select + <guibutton>Install</guibutton> anyways.</para> + </sect2> + + <sect2 id="addusers"> + <title>Add Users/Groups</title> + + <para>You should add at least one user during the installation so + that you can use the system without being logged in as + <username>root</username>. The root partition is generally small + and running applications as <username>root</username> can quickly + fill it. A bigger danger is noted below:</para> + + <screen> User Confirmation Requested + Would you like to add any initial user accounts to the system? Adding + at least one account for yourself at this stage is suggested since + working as the "root" user is dangerous (it is easy to do things which + adversely affect the entire system). + + [ Yes ] No</screen> + + <para>Select &gui.yes; and press + <keycap>Enter</keycap> to continue with adding a user.</para> + + <figure id="add-user2"> + <title>Select User</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/adduser1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Select <guimenuitem>User</guimenuitem> with the arrow keys + and press <keycap>Enter</keycap>.</para> + + <figure id="add-user3"> + <title>Add User Information</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/adduser2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The following descriptions will appear in the lower part of + the screen as the items are selected with <keycap>Tab</keycap> + to assist with entering the required information:</para> + + <variablelist> + <varlistentry> + <term>Login ID</term> + + <listitem> + <para>The login name of the new user (mandatory).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>UID</term> + + <listitem> + <para>The numerical ID for this user (leave blank for + automatic choice).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Group</term> + + <listitem> + <para>The login group name for this user (leave blank for + automatic choice).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Password</term> + + <listitem> + <para>The password for this user (enter this field with + care!).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Full name</term> + + <listitem> + <para>The user's full name (comment).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Member groups</term> + + <listitem> + <para>The groups this user belongs to (i.e., gets access + rights for).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Home directory</term> + + <listitem> + <para>The user's home directory (leave blank for + default).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Login shell</term> + <listitem> + <para>The user's login shell (leave blank for + default, e.g., <filename>/bin/sh</filename>).</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The login shell was changed from <filename>/bin/sh</filename> to + <filename>/usr/local/bin/bash</filename> to use the + <application>bash</application> shell that was previously installed as + a package. Do not try to use a shell that does not exist or you will + not be able to login. The most common shell used in the + BSD-world is the C shell, which can be indicated as + <filename>/bin/tcsh</filename>.</para> + + <para>The user was also added to the <groupname>wheel</groupname> group + to be able to become a superuser with <username>root</username> + privileges.</para> + + <para>When you are satisfied, press &gui.ok; and + the User and Group Management menu will redisplay:</para> + + <figure id="add-user4"> + <title>Exit User and Group Management</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/adduser3" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Groups can also be added at this time if specific needs + are known. Otherwise, this may be accessed through using + <command>sysinstall</command> + after installation is + completed.</para> + + <para>When you are finished adding users, select + <guimenuitem>Exit</guimenuitem> with the arrow keys and press + <keycap>Enter</keycap> to continue the installation.</para> + </sect2> + + <sect2 id="rootpass"> + <title>Set the <username>root</username> Password</title> + + <screen> Message + Now you must set the system manager's password. + This is the password you'll use to log in as "root". + + [ OK ] + + [ Press enter or space ]</screen> + + <para>Press <keycap>Enter</keycap> to set the <username>root</username> + password.</para> + + <para>The password will need to be typed in twice correctly. Needless to + say, make sure you have a way of finding the password if you + forget. Notice that the password you type in is not echoed, nor + are asterisks displayed.</para> + + <screen>New password: +Retype new password :</screen> + + <para>The installation will continue after the password is + successfully entered.</para> + </sect2> + + <sect2 id="exit-inst"> + <title>Exiting Install</title> + + <para>If you need to configure + <link linkend="network-services">additional network services</link> + or any other configuration, you can do it at this point or + after installation with <command>sysinstall</command>.</para> + + <screen> User Confirmation Requested + Visit the general configuration menu for a chance to set any last + options? + + Yes [ No ]</screen> + + <para>Select &gui.no; with the arrow keys + and press <keycap>Enter</keycap> to return to the Main + Installation Menu.</para> + + <figure id="final-main"> + <title>Exit Install</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/mainexit" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Select <guibutton>[X Exit Install]</guibutton> with the arrow + keys and press <keycap>Enter</keycap>. You will be asked to + confirm exiting the installation:</para> + + <screen> User Confirmation Requested + Are you sure you wish to exit? The system will reboot. + + [ Yes ] No</screen> + + <para>Select &gui.yes;. If you are booting from the CDROM drive + the following message will remind you to remove the + disk:</para> + + <screen> Message + Be sure to remove the media from the drive. + + [ OK ] + [ Press enter or space ]</screen> + + <para>The CDROM drive is locked until the machine + starts to reboot then the disk can + be removed from drive (quickly). Press &gui.ok; to reboot.</para> + + <para>The system will reboot so watch for any error messages that + may appear, see <xref linkend="freebsdboot"> for more + details.</para> + </sect2> + + <sect2 id="network-services"> + <sect2info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <title>Configure Additional Network Services</title> + + <para>Configuring network services can be a daunting + task for new users if they lack previous + knowledge in this area. Networking, including the Internet, + is critical to all modern operating systems including &os;; + as a result, it is very useful to have some understanding + &os;'s extensive networking capabilities. Doing this + during the installation will ensure users have some + understanding of the various services available to them.</para> + + <para>Network services are programs that accept input from + anywhere on the network. Every effort is made to make sure + these programs will not do anything <quote>harmful</quote>. + Unfortunately, programmers are not perfect and through time + there have been cases where bugs in network services have been + exploited by attackers to do bad things. It is important that + you only enable the network services you know that you need. If + in doubt it is best if you do not enable a network service until + you find out that you do need it. You can always enable it + later by re-running <application>sysinstall</application> or by + using the features provided by the + <filename>/etc/rc.conf</filename> file.</para> + + <para>Selecting the <guimenu>Networking</guimenu> option will display + a menu similar to the one below:</para> + + <figure id="network-configuration"> + <title>Network Configuration Upper-level</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/net-config-menu1" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The first option, <guimenuitem>Interfaces</guimenuitem>, was + previously covered during the <xref linkend="inst-network-dev">, + thus this option can safely be ignored.</para> + + <para>Selecting the <guimenuitem>AMD</guimenuitem> option adds + support for the <acronym>BSD</acronym> automatic mount utility. + This is usually used in conjunction with the + <acronym>NFS</acronym> protocol (see below) + for automatically mounting remote file systems. + No special configuration is required here.</para> + + <para>Next in line is the <guimenuitem>AMD Flags</guimenuitem> + option. When selected, a menu will pop up for you + to enter specific <acronym>AMD</acronym> flags. + The menu already contains a set of default options:</para> + + <screen>-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map</screen> + + <para>The <option>-a</option> option sets the default mount + location which is specified here as + <filename>/.amd_mnt</filename>. The <option>-l</option> + option specifies the default <filename>log</filename> file; + however, when <literal>syslogd</literal> is used all log + activity will be sent to the system log daemon. The + <filename class="directory">/host</filename> directory is used + to mount an exported file system from a remote + host, while <filename class="directory">/net</filename> + directory is used to mount an exported file system from an + <acronym>IP</acronym> address. The + <filename>/etc/amd.map</filename> file defines the default + options for <acronym>AMD</acronym> exports.</para> + + <indexterm> + <primary>FTP</primary> + <secondary>anonymous</secondary> + </indexterm> + + <para>The <guimenuitem>Anon FTP</guimenuitem> option permits anonymous + <acronym>FTP</acronym> connections. Select this option to + make this machine an anonymous <acronym>FTP</acronym> server. + Be aware of the security risks involved with this option. + Another menu will be displayed to explain the security risks + and configuration in depth.</para> + + <para>The <guimenuitem>Gateway</guimenuitem> configuration menu will set + the machine up to be a gateway as explained previously. This + can be used to unset the <guimenuitem>Gateway</guimenuitem> option if + you accidentally selected it during the installation process.</para> + + <para>The <guimenuitem>Inetd</guimenuitem> option can be used to configure + or completely disable the &man.inetd.8; daemon as discussed + above.</para> + + <para>The <guimenuitem>Mail</guimenuitem> option is used to configure the + system's default <acronym>MTA</acronym> or Mail Transfer Agent. + Selecting this option will bring up the following menu:</para> + + <figure id="mta-selection"> + <title>Select a default MTA</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/mta-main" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>Here you are offered a choice as to which + <acronym>MTA</acronym> to install + and set as the default. An <acronym>MTA</acronym> is nothing + more than a mail server which delivers email to users on the + system or the Internet.</para> + + <para>Selecting <guimenuitem>Sendmail</guimenuitem> will install + the popular <application>sendmail</application> server which + is the &os; default. The <guimenuitem>Sendmail local</guimenuitem> + option will set <application>sendmail</application> to be the default + <acronym>MTA</acronym>, but disable its ability to receive + incoming email from the Internet. The other options here, + <guimenuitem>Postfix</guimenuitem> and + <guimenuitem>Exim</guimenuitem> act similar to + <guimenuitem>Sendmail</guimenuitem>. They both deliver + email; however, some users prefer these alternatives to the + <application>sendmail</application> + <acronym>MTA</acronym>.</para> + + <para>After selecting an <acronym>MTA</acronym>, or choosing + not to select an MTA, the network configuration menu will appear + with the next option being <guimenuitem>NFS client</guimenuitem>.</para> + + <para>The <guimenuitem>NFS client</guimenuitem> option will + configure the system to communicate with a server via + <acronym>NFS</acronym>. An <acronym>NFS</acronym> server + makes file systems available to other machines on the + network via the <acronym>NFS</acronym> protocol. If this is + a stand-alone machine, this option can remain unselected. + The system may require more configuration later; see + <xref linkend="network-nfs"> for more + information about client and server configuration.</para> + + <para>Below that option is the <guimenuitem>NFS server</guimenuitem> + option, permitting you to set the system up as an + <acronym>NFS</acronym> server. This adds the required + information to start up the <acronym>RPC</acronym> remote + procedure call services. <acronym>RPC</acronym> is used to + coordinate connections between hosts and programs.</para> + + <para>Next in line is the <guimenuitem>Ntpdate</guimenuitem> option, + which deals with time synchronization. When selected, a menu + like the one below shows up:</para> + + <figure id="Ntpdate-config"> + <title>Ntpdate Configuration</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/ntp-config" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>From this menu, select the server which is the closest + to your location. Selecting a close one will make the time + synchronization more accurate as a server further from your + location may have more connection latency.</para> + + <para>The next option is the <acronym>PCNFSD</acronym> selection. + This option will install the + <filename role="package">net/pcnfsd</filename> package from + the Ports Collection. This is a useful utility which provides + <acronym>NFS</acronym> authentication services for systems which + are unable to provide their own, such as Microsoft's + &ms-dos; operating system.</para> + + <para>Now you must scroll down a bit to see the other + options:</para> + + <figure id="Network-configuration-cont"> + <title>Network Configuration Lower-level</title> + + <mediaobject> + <imageobject> + <imagedata fileref="install/net-config-menu2" format="PNG"> + </imageobject> + </mediaobject> + </figure> + + <para>The &man.rpcbind.8;, &man.rpc.statd.8;, and + &man.rpc.lockd.8; utilities are all used for Remote Procedure + Calls (<acronym>RPC</acronym>). + The <command>rpcbind</command> utility manages communication + between <acronym>NFS</acronym> servers and clients, and is + required for <acronym>NFS</acronym> servers to operate + correctly. The <application>rpc.statd</application> daemon interacts + with the <application>rpc.statd</application> daemon on other hosts to + provide status monitoring. The reported status is usually held + in the <filename>/var/db/statd.status</filename> file. The + next option listed here is the <guimenuitem>rpc.lockd</guimenuitem> + option, which, when selected, will provide file locking + services. This is usually used with + <application>rpc.statd</application> to monitor what hosts are + requesting locks and how frequently they request them. + While these last two options are marvelous for debugging, they + are not required for <acronym>NFS</acronym> servers and clients + to operate correctly.</para> + + <para>As you progress down the list the next item here is + <guimenuitem>Routed</guimenuitem>, which is the routing daemon. The + &man.routed.8; utility manages network routing tables, + discovers multicast routers, and supplies a copy of the routing + tables to any physically connected host on the network upon + request. This is mainly used for machines which act as a + gateway for the local network. When selected, a menu will be + presented requesting the default location of the utility. + The default location is already defined for you and can be + selected with the <keycap>Enter</keycap> key. You will then + be presented with yet another menu, this time asking for the + flags you wish to pass on to <application>routed</application>. The + default is <option>-q</option> and it should already appear + on the screen.</para> + + <para>Next in line is the <guimenuitem>Rwhod</guimenuitem> option which, + when selected, will start the &man.rwhod.8; daemon + during system initialization. The <command>rwhod</command> + utility broadcasts system messages across the network + periodically, or collects them when in <quote>consumer</quote> + mode. More information can be found in the &man.ruptime.1; and + &man.rwho.1; manual pages.</para> + + <para>The next to the last option in the list is for the + &man.sshd.8; daemon. This is the secure shell server for + <application>OpenSSH</application> and it is highly recommended + over the standard <application>telnet</application> and + <acronym>FTP</acronym> servers. The <application>sshd</application> + server is used to create a secure connection from one host to + another by using encrypted connections.</para> + + <para>Finally there is the <guimenuitem>TCP Extensions</guimenuitem> + option. This enables the <acronym>TCP</acronym> Extensions + defined in <acronym>RFC</acronym> 1323 and + <acronym>RFC</acronym> 1644. While on many hosts this can + speed up connections, it can also cause some connections to be + dropped. It is not recommended for servers, but may be + beneficial for stand alone machines.</para> + + <para>Now that you have configured the network services, you can + scroll up to the very top item which is + <guimenuitem>X Exit</guimenuitem> + and continue on to the next configuration item or simply exit + <application>sysinstall</application> in selecting + <guimenuitem>X Exit</guimenuitem> twice then <guibutton>[X + Exit Install]</guibutton>.</para> + + </sect2> + + <sect2 id="freebsdboot"> + <title>&os; Bootup</title> + + <sect3 id="freebsdboot-i386"> + <title>&os;/&arch.i386; Bootup</title> + + <para>If everything went well, you will see messages scroll + off the screen and you will arrive at a login prompt. You can view + the content of the messages by pressing <keycap>Scroll-Lock</keycap> + and using <keycap>PgUp</keycap> and <keycap>PgDn</keycap>. + Pressing <keycap>Scroll-Lock</keycap> again will return + to the prompt.</para> + + <para>The entire message may not display (buffer limitation) but + it can be viewed from the command line after logging in by typing + <command>dmesg</command> at the prompt.</para> + + <para>Login using the username/password you set during installation + (<username>rpratt</username>, in this example). Avoid logging in as + <username>root</username> except when necessary.</para> + + <para>Typical boot messages (version information omitted):</para> + +<screen>Copyright (c) 1992-2002 The FreeBSD Project. +Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994 + The Regents of the University of California. All rights reserved. + +Timecounter "i8254" frequency 1193182 Hz +CPU: AMD-K6(tm) 3D processor (300.68-MHz 586-class CPU) + Origin = "AuthenticAMD" Id = 0x580 Stepping = 0 + Features=0x8001bf<FPU,VME,DE,PSE,TSC,MSR,MCE,CX8,MMX> + AMD Features=0x80000800<SYSCALL,3DNow!> +real memory = 268435456 (262144K bytes) +config> di sn0 +config> di lnc0 +config> di le0 +config> di ie0 +config> di fe0 +config> di cs0 +config> di bt0 +config> di aic0 +config> di aha0 +config> di adv0 +config> q +avail memory = 256311296 (250304K bytes) +Preloaded elf kernel "kernel" at 0xc0491000. +Preloaded userconfig_script "/boot/kernel.conf" at 0xc049109c. +md0: Malloc disk +Using $PIR table, 4 entries at 0xc00fde60 +npx0: <math processor> on motherboard +npx0: INT 16 interface +pcib0: <Host to PCI bridge> on motherboard +pci0: <PCI bus> on pcib0 +pcib1: <VIA 82C598MVP (Apollo MVP3) PCI-PCI (AGP) bridge> at device 1.0 on pci0 +pci1: <PCI bus> on pcib1 +pci1: <Matrox MGA G200 AGP graphics accelerator> at 0.0 irq 11 +isab0: <VIA 82C586 PCI-ISA bridge> at device 7.0 on pci0 +isa0: <ISA bus> on isab0 +atapci0: <VIA 82C586 ATA33 controller> port 0xe000-0xe00f at device 7.1 on pci0 +ata0: at 0x1f0 irq 14 on atapci0 +ata1: at 0x170 irq 15 on atapci0 +uhci0: <VIA 83C572 USB controller> port 0xe400-0xe41f irq 10 at device 7.2 on pci0 +usb0: <VIA 83C572 USB controller> on uhci0 +usb0: USB revision 1.0 +uhub0: VIA UHCI root hub, class 9/0, rev 1.00/1.00, addr 1 +uhub0: 2 ports with 2 removable, self powered +chip1: <VIA 82C586B ACPI interface> at device 7.3 on pci0 +ed0: <NE2000 PCI Ethernet (RealTek 8029)> port 0xe800-0xe81f irq 9 at +device 10.0 on pci0 +ed0: address 52:54:05:de:73:1b, type NE2000 (16 bit) +isa0: too many dependant configs (8) +isa0: unexpected small tag 14 +fdc0: <NEC 72065B or clone> at port 0x3f0-0x3f5,0x3f7 irq 6 drq 2 on isa0 +fdc0: FIFO enabled, 8 bytes threshold +fd0: <1440-KB 3.5" drive> on fdc0 drive 0 +atkbdc0: <keyboard controller (i8042)> at port 0x60-0x64 on isa0 +atkbd0: <AT Keyboard> flags 0x1 irq 1 on atkbdc0 +kbd0 at atkbd0 +psm0: <PS/2 Mouse> irq 12 on atkbdc0 +psm0: model Generic PS/2 mouse, device ID 0 +vga0: <Generic ISA VGA> at port 0x3c0-0x3df iomem 0xa0000-0xbffff on isa0 +sc0: <System console> at flags 0x1 on isa0 +sc0: VGA <16 virtual consoles, flags=0x300> +sio0 at port 0x3f8-0x3ff irq 4 flags 0x10 on isa0 +sio0: type 16550A +sio1 at port 0x2f8-0x2ff irq 3 on isa0 +sio1: type 16550A +ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0 +ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode +ppc0: FIFO with 16/16/15 bytes threshold +ppbus0: IEEE1284 device found /NIBBLE +Probing for PnP devices on ppbus0: +plip0: <PLIP network interface> on ppbus0 +lpt0: <Printer> on ppbus0 +lpt0: Interrupt-driven port +ppi0: <Parallel I/O> on ppbus0 +ad0: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata0-master using UDMA33 +ad2: 8063MB <IBM-DHEA-38451> [16383/16/63] at ata1-master using UDMA33 +acd0: CDROM <DELTA OTC-H101/ST3 F/W by OIPD> at ata0-slave using PIO4 +Mounting root from ufs:/dev/ad0s1a +swapon: adding /dev/ad0s1b as swap device +Automatic boot in progress... +/dev/ad0s1a: FILESYSTEM CLEAN; SKIPPING CHECKS +/dev/ad0s1a: clean, 48752 free (552 frags, 6025 blocks, 0.9% fragmentation) +/dev/ad0s1f: FILESYSTEM CLEAN; SKIPPING CHECKS +/dev/ad0s1f: clean, 128997 free (21 frags, 16122 blocks, 0.0% fragmentation) +/dev/ad0s1g: FILESYSTEM CLEAN; SKIPPING CHECKS +/dev/ad0s1g: clean, 3036299 free (43175 frags, 374073 blocks, 1.3% fragmentation) +/dev/ad0s1e: filesystem CLEAN; SKIPPING CHECKS +/dev/ad0s1e: clean, 128193 free (17 frags, 16022 blocks, 0.0% fragmentation) +Doing initial network setup: hostname. +ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 + inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 + inet6 fe80::5054::5ff::fede:731b%ed0 prefixlen 64 tentative scopeid 0x1 + ether 52:54:05:de:73:1b +lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 + inet6 fe80::1%lo0 prefixlen 64 scopeid 0x8 + inet6 ::1 prefixlen 128 + inet 127.0.0.1 netmask 0xff000000 +Additional routing options: IP gateway=YES TCP keepalive=YES +routing daemons:. +additional daemons: syslogd. +Doing additional network setup:. +Starting final network daemons: creating ssh RSA host key +Generating public/private rsa1 key pair. +Your identification has been saved in /etc/ssh/ssh_host_key. +Your public key has been saved in /etc/ssh/ssh_host_key.pub. +The key fingerprint is: +cd:76:89:16:69:0e:d0:6e:f8:66:d0:07:26:3c:7e:2d root@k6-2.example.com + creating ssh DSA host key +Generating public/private dsa key pair. +Your identification has been saved in /etc/ssh/ssh_host_dsa_key. +Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub. +The key fingerprint is: +f9:a1:a9:47:c4:ad:f9:8d:52:b8:b8:ff:8c:ad:2d:e6 root@k6-2.example.com. +setting ELF ldconfig path: /usr/lib /usr/lib/compat /usr/X11R6/lib +/usr/local/lib +a.out ldconfig path: /usr/lib/aout /usr/lib/compat/aout /usr/X11R6/lib/aout +starting standard daemons: inetd cron sshd usbd sendmail. +Initial rc.i386 initialization:. +rc.i386 configuring syscons: blank_time screensaver moused. +Additional ABI support: linux. +Local package initialization:. +Additional TCP options:. + +FreeBSD/i386 (k6-2.example.com) (ttyv0) + +login: rpratt +Password:</screen> + + <para>Generating the RSA and DSA keys may take some time on slower + machines. This happens only on the initial boot-up of a new + installation. Subsequent boots will be faster.</para> + + <para>If the X server has been configured and a Default Desktop + chosen, it can be started by typing <command>startx</command> at + the command line.</para> + + </sect3> + </sect2> + + <sect2 id="shutdown"> + <title>FreeBSD Shutdown</title> + + <para>It is important to properly shutdown the operating + system. Do not just turn off power. First, become a superuser by + typing <command>su</command> at the command line and entering the + <username>root</username> password. This will work only if the user + is a member of the <groupname>wheel</groupname> group. + Otherwise, login as <username>root</username> and use + <command>shutdown -h now</command>.</para> + + <screen>The operating system has halted. +Please press any key to reboot.</screen> + + <para>It is safe to turn off the power after the shutdown command + has been issued and the message + <quote>Please press any key to reboot</quote> + appears. If any key is pressed instead of turning off the power + switch, the system will reboot.</para> + + <para>You could also use the + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>Alt</keycap> + <keycap>Del</keycap> + </keycombo> + key combination to reboot the system, however this is not recommended + during normal operation.</para> + + </sect2> + </sect1> + + <sect1 id="install-trouble"> + <title>Troubleshooting</title> + + <indexterm> + <primary>installation</primary> + <secondary>troubleshooting</secondary> + </indexterm> + <para>The following section covers basic installation troubleshooting, + such as common problems people have reported. There are also a few + questions and answers for people wishing to dual-boot FreeBSD with + &ms-dos; or &windows;.</para> + + <sect2> + <title>What to Do If Something Goes Wrong</title> + + <para>Due to various limitations of the PC architecture, it is + impossible for probing to be 100% reliable, however, there are a + few things you can do if it fails.</para> + + <para>Check the <ulink + url="http://www.FreeBSD.org/releases/index.html">Hardware Notes + </ulink> document for your version of &os; to make sure your + hardware is supported.</para> + + <para>If your hardware is supported and you still experience + lock-ups or other problems, you will need to build a <link + linkend="kernelconfig">custom kernel</link>. This will + allow you to add in support for devices which are not present in the + <filename>GENERIC</filename> kernel. The kernel on the boot disks + is configured assuming that most hardware devices are in their + factory default configuration in terms of IRQs, IO addresses, and + DMA channels. If your hardware has been reconfigured, you will most + likely need to edit the kernel configuration and recompile to tell + &os; where to find things.</para> + + <para>It is also possible that a probe for a device not present will + cause a later probe for another device that is present to fail. In + that case, the probes for the conflicting driver(s) should be + disabled.</para> + + <note> + <para>Some installation problems can be avoided or alleviated + by updating the firmware on various hardware components, most notably + the motherboard. The motherboard firmware may also be referred to + as <acronym>BIOS</acronym> and most of the motherboard or computer + manufactures have a website where the upgrades and upgrade + information may be located.</para> + + <para>Most manufacturers strongly advise against upgrading the + motherboard <acronym>BIOS</acronym> unless there is a good reason + for doing so, which + could possibly be a critical update of sorts. The upgrade process + <emphasis>can</emphasis> go wrong, causing permanent damage to the + <acronym>BIOS</acronym> chip.</para> + </note> + </sect2> + + <sect2> + <title>Using &ms-dos; and &windows; File Systems</title> + + <para>At this time, &os; does not support file systems compressed with + the <application>Double Space™</application> application. + Therefore the file system will need to be uncompressed before &os; can + access the data. This + can be done by running the <application>Compression Agent</application> + located in the + <guimenuitem>Start</guimenuitem>> <guimenuitem>Programs</guimenuitem> > + <guimenuitem>System Tools</guimenuitem> menu.</para> + + <para>&os; can support &ms-dos; file systems (sometimes called + FAT file systems). The &man.mount.msdosfs.8; command grafts such file + systems onto the existing directory hierarchy, allowing the file + system's contents to be accessed. The &man.mount.msdosfs.8; program + is not usually + invoked directly; instead, it is called by the system through a line + in <filename>/etc/fstab</filename> or by a call to the &man.mount.8; + utility with the appropriate parameters.</para> + + <para>A typical line in <filename>/etc/fstab</filename> is:</para> + + <programlisting>/dev/ad0sN /dos msdosfs rw 0 0</programlisting> + + <note><para>The <filename>/dos</filename> directory must already + exist for this to work. For details about the format of + <filename>/etc/fstab</filename>, see &man.fstab.5;.</para></note> + + <para>A typical call to &man.mount.8; for a &ms-dos; file system + looks like:</para> + + <screen>&prompt.root; <userinput>mount -t msdosfs /dev/ad0s1 /mnt</userinput></screen> + + <para>In this example, the &ms-dos; file system is located on the first + partition of the primary hard disk. Your situation may be different, + check the output from the <command>dmesg</command>, and + <command>mount</command> commands. They should produce enough + information to give an idea of the partition layout.</para> + + <note><para>&os; may number disk slices (that is, &ms-dos; partitions) + differently than other operating systems. In particular, extended + &ms-dos; partitions are usually given higher slice numbers than + primary &ms-dos; partitions. The &man.fdisk.8; utility can help + determine which slices belong to &os; and which belong to other + operating systems.</para></note> + + <para>NTFS partitions can also be mounted in a similar manner + using the &man.mount.ntfs.8; command.</para> + </sect2> + + <sect2> + <title>Troubleshooting Questions and Answers</title> + + <qandaset> + <qandaentry> + <question> + <para>My system hangs while probing hardware during boot, + or it behaves strangely during install, or the floppy + drive is not probed.</para> + </question> + <answer> + <para>&os; makes extensive use of the system + ACPI service on the i386, amd64 and ia64 platforms to + aid in system configuration if it is detected during + boot. Unfortunately, some bugs still exist in both the + ACPI driver and within system motherboards and BIOS. + The use of ACPI can be disabled by setting + the <literal>hint.acpi.0.disabled</literal> hint in the + third stage boot loader:</para> + + <screen><userinput>set hint.acpi.0.disabled="1"</userinput></screen> + + <para>This is reset each time the system is booted, so it + is necessary to + add <literal>hint.acpi.0.disabled="1"</literal> to the + file + <filename>/boot/loader.conf</filename>. More + information about the boot loader can be found + in <xref linkend="boot-synopsis">.</para> + </answer> + </qandaentry> + <qandaentry> + <question> + <para>I go to boot from the hard disk for the first time + after installing &os;, the kernel loads and probes my + hardware, but stops with messages like:</para> + + <screen>changing root device to ad1s1a panic: cannot mount root</screen> + + <para>What is wrong? What can I do?</para> + + <para>What is this + <literal>bios_drive:interface(unit,partition)kernel_name</literal> + thing that is displayed with the boot help?</para> + </question> + <answer> + <para>There is a longstanding problem in the case where + the boot disk is not the first disk in the system. The + BIOS uses a different numbering scheme to &os;, and + working out which numbers correspond to which is + difficult to get right.</para> + + <para>In the case where the boot disk is not the first + disk in the system, &os; can need some help finding it. + There are two common situations here, and in both of + these cases, you need to tell &os; where the root + filesystem is. You do this by specifying the BIOS disk + number, the disk type and the &os; disk number for that + type.</para> + + <para>The first situation is where you have two IDE disks, + each configured as the master on their respective IDE + busses, and wish to boot &os; from the second disk. The + BIOS sees these as disk 0 and disk 1, while &os; sees + them as <devicename>ad0</devicename> and + <devicename>ad2</devicename>.</para> + + <para>&os; is on BIOS disk 1, of type + <literal>ad</literal> and the &os; disk number is 2, so + you would say:</para> + + <screen><userinput>1:ad(2,a)kernel</userinput></screen> + + <para>Note that if you have a slave on the primary bus, + the above is not necessary (and is effectively + wrong).</para> + + <para>The second situation involves booting from a SCSI + disk when you have one or more IDE disks in the system. + In this case, the &os; disk number is lower than the + BIOS disk number. If you have two IDE disks as well as + the SCSI disk, the SCSI disk is BIOS disk 2, + type <literal>da</literal> and &os; disk number 0, so + you would say:</para> + + <screen><userinput>2:da(0,a)kernel</userinput></screen> + + <para>To tell &os; that you want to boot from BIOS disk 2, + which is the first SCSI disk in the system. If you only + had one IDE disk, you would use <literal>1:</literal> + instead.</para> + + <para>Once you have determined the correct values to use, + you can put the command exactly as you would have typed + it in the <filename>/boot.config</filename> file using a + standard text editor. Unless instructed otherwise, &os; + will use the contents of this file as the default + response to the <literal>boot:</literal> prompt.</para> + </answer> + </qandaentry> + <qandaentry> + <question> + <para>I go to boot from the hard disk for the first time + after installing &os;, but the Boot Manager prompt just + prints <literal>F?</literal> at the boot menu each time + but the boot will not go any further.</para> + </question> + <answer> + <para>The hard disk geometry was set incorrectly in the + partition editor when you installed &os;. Go back into + the partition editor and specify the actual geometry of + your hard disk. You must reinstall &os; again from the + beginning with the correct geometry.</para> + + <para>If you are failing entirely in figuring out the + correct geometry for your machine, here is a tip: Install + a small &ms-dos; partition at the beginning of the disk and + install &os; after that. The install program will see + the &ms-dos; partition and try to infer the correct geometry + from it, which usually works.</para> + + <para>The following tip is no longer recommended, but is + left here for reference:</para> + + <blockquote> + <para>If you are setting up a truly dedicated &os; + server or workstation where you do not care for + (future) compatibility with &ms-dos;, Linux or another + operating system, you also have got the option to use + the entire disk (<guimenuitem>A</guimenuitem> in the partition + editor), selecting the non-standard option where &os; occupies + the entire disk from the very first to the very last + sector. This will leave all geometry considerations + aside, but is somewhat limiting unless you're never + going to run anything other than &os; on a + disk.</para> + </blockquote> + </answer> + </qandaentry> + <qandaentry> + <question> + <para>The system finds my &man.ed.4; network card, but I + keep getting device timeout errors.</para> + </question> + <answer> + <para>Your card is probably on a different IRQ from what + is specified in + the <filename>/boot/device.hints</filename> file. The + &man.ed.4; driver does not use the <quote>soft</quote> + configuration by default (values entered using EZSETUP in + &ms-dos;), + but it will use the software configuration if you + specify <literal>-1</literal> in the hints for the + interface.</para> + + <para>Either move the jumper on the card to a hard + configuration setting (altering the kernel settings if + necessary), or specify the IRQ as <literal>-1</literal> + by setting the hint <literal>hint.ed.0.irq="-1"</literal>. + This will tell the kernel to use the soft + configuration.</para> + + <para>Another possibility is that your card is at IRQ 9, + which is shared by IRQ 2 and frequently a cause of + problems (especially when you have a VGA card using IRQ + 2!). You should not use IRQ 2 or 9 if at all + possible.</para> + </answer> + </qandaentry> + + <qandaentry> + + <indexterm> + <primary>color</primary> + <secondary>contrast</secondary> + </indexterm> + <question> + <para>When <application>sysinstall</application> is used + in an X11 terminal, the yellow font is difficult to read + against the light gray background. Is there a way to + provide higher contrast for this application?</para> + </question> + <answer> + <para>If you already have X11 installed and the default + colors chosen by <application>sysinstall</application> + make text illegible while using &man.xterm.1; or &man.rxvt.1;, + add the following to your <filename>~/.Xdefaults</filename> to + get a darker background gray: <literal>XTerm*color7: + #c0c0c0</literal></para> + </answer> + </qandaentry> + </qandaset> + </sect2> + </sect1> + + <sect1 id="install-advanced"> + <sect1info> + <authorgroup> + <author> + <firstname>Valentino</firstname> + <surname>Vaschetto</surname> + <contrib>Contributed by </contrib> + </author> + <!-- May 2001 --> + </authorgroup> + + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + <contrib>Updated by </contrib> + </author> + </authorgroup> + <!-- August 2010 --> + </sect1info> + + <title>Advanced Installation Guide</title> + + <para>This section describes how to install FreeBSD in exceptional + cases.</para> + + <sect2 id="headless-install"> + <title>Installing FreeBSD on a System without a Monitor or + Keyboard</title> + + <indexterm> + <primary>installation</primary> + <secondary>headless (serial console)</secondary> + </indexterm> + <indexterm><primary>serial console</primary></indexterm> + <para>This type of installation is called a <quote>headless + install</quote>, because the machine that you are trying to install + FreeBSD on either does not have a monitor attached to it, or does not + even have a VGA output. How is this possible you ask? Using a + serial console. A serial console is basically using another + machine to act as the main display and keyboard for a + system. To do this, just follow the steps to create + an installation USB memstick, explained in <xref + linkend="install-boot-media"> or download the correct + installation ISO image, see <xref + linkend="install-cdrom">.</para> + + + <para>To modify these media to boot into a serial console, follow + these steps (If you want to use a CDROM you can skip the first + step):</para> + + <procedure> + <step> + <title>Enabling the Installation USB Stick to Boot into a + Serial Console</title> + <indexterm> + <primary><command>mount</command></primary> + </indexterm> + <para>If you were to boot into the USB stick that you just + made, FreeBSD would boot into its normal install mode. We + want FreeBSD to boot into a serial console for our + install. To do this, you have to mount the + USB disk onto your &os; + system using the &man.mount.8; command.</para> + + <screen>&prompt.root; <userinput>mount /dev/<replaceable>da0a</replaceable> <replaceable>/mnt</replaceable></userinput></screen> + + <note> + <para>Adapt the device node and the mount point to your + situation.</para> + </note> + + <para>Now that you have the stick mounted, you must set + the USB stick to boot into a serial console. You have + to add to the <filename>loader.conf</filename> file of + the USB stick file system a line setting the serial + console as the system console:</para> + + <screen>&prompt.root; <userinput>echo 'console="comconsole"' >> <replaceable>/mnt</replaceable>/boot/loader.conf</userinput></screen> + + <para>Now that you have your USB stick configured correctly, + you must unmount the disk using the &man.umount.8; + command:</para> + + <screen>&prompt.root; <userinput>umount <replaceable>/mnt</replaceable></userinput></screen> + + <para>Now you can unplug the USB stick and jump directly + to the third step of this procedure.</para> + </step> + + <step> + <title>Enabling the Installation CD to Boot into a + Serial Console</title> + <indexterm> + <primary><command>mount</command></primary> + </indexterm> + <para>If you were to boot into the CD that you just + made from the installation ISO image (see <xref + linkend="install-cdrom">), &os; would boot into its + normal install mode. We want &os; to boot into a serial + console for our install. To do this, you have to + extract, modify and regenerate the ISO image before + burning it on a CD-R media.</para> + + <para>From the &os; system where is saved the installation + ISO image, for example + <filename>&os;-<replaceable>&rel.current;</replaceable>-RELEASE-<replaceable>i386</replaceable>-disc1.iso</filename>, + use the &man.tar.1; utility to extract all the files:</para> + + <screen>&prompt.root; <userinput>mkdir <replaceable>/path/to/headless-iso</replaceable></userinput> +&prompt.root; <userinput>tar -C <replaceable>/path/to/headless-iso</replaceable> -pxvf &os;-<replaceable>&rel.current;</replaceable>-RELEASE-<replaceable>i386</replaceable>-disc1.iso</userinput></screen> + + <para>Now you must set the installation media to boot into a + serial console. You have to add to the + <filename>loader.conf</filename> file from the extracted + ISO image a line setting the serial console as the + system console:</para> + + <screen>&prompt.root; <userinput>echo 'console="comconsole"' >> <replaceable>/path/to/headless-iso</replaceable>/boot/loader.conf</userinput></screen> + + <para>Then we can create a new ISO image from the modified + tree. The &man.mkisofs.8; tool from the <filename + role="package">sysutils/cdrtools</filename> port is + used:</para> + + <screen>&prompt.root; <userinput>mkisofs -v -b boot/cdboot -no-emul-boot -r -J -V "<replaceable>Headless_install</replaceable>" \ + -o <replaceable>Headless-</replaceable>&os;-<replaceable>&rel.current;</replaceable>-RELEASE-<replaceable>i386</replaceable>-disc1.iso <replaceable>/path/to/headless-iso</replaceable></userinput></screen> + + <para>Now that you have your ISO image configured correctly, + you can burn it on a CD-R with your favorite burning + application.</para> + </step> + + <step> + <title>Connecting Your Null-modem Cable</title> + + <indexterm><primary>null-modem cable</primary></indexterm> + <para>You now need to connect a + <link linkend="term-cables-null">null-modem cable</link> between + the two machines. Just connect the cable to the serial + ports of the 2 machines. <emphasis>A normal serial cable + will not work here</emphasis>, you need a null-modem + cable because it has some of the wires inside crossed + over.</para> + </step> + + <step> + <title>Booting Up for the Install</title> + + <para>It is now time to go ahead and start the install. Plug in + the USB memstick on + the machine you are doing the headless install + on, and power on the machine. If you are using a + prepared CDROM, power on the machine and insert the disk + to boot on.</para> + </step> + + <step> + <title>Connecting to Your Headless Machine</title> + <indexterm> + <primary><command>cu</command></primary> + </indexterm> + <para>Now you have to connect to that machine with + &man.cu.1;:</para> + + <screen>&prompt.root; <userinput>cu -l /dev/cuau0</userinput></screen> + + <para>On &os; 7.<replaceable>X</replaceable> use the following command + instead:</para> + + <screen>&prompt.root; <userinput>cu -l /dev/cuad0</userinput></screen> + + </step> + </procedure> + + <para>That's it! You should now be able to control the headless machine + through your <command>cu</command> session. It will load the kernel + and then it will come up + with a selection of what kind of terminal to use. Select the + FreeBSD color console and proceed with your install!</para> + + </sect2> + </sect1> + + <sect1 id="install-diff-media"> + <title>Preparing Your Own Installation Media</title> + + <note> + <para>To prevent repetition, <quote>FreeBSD disc</quote> in this context + means a FreeBSD CDROM or DVD that you have purchased or produced + yourself.</para> + </note> + + <para>There may be some situations in which you need to create your own + FreeBSD installation media and/or source. This might be physical media, + such as a tape, or a source that <application>sysinstall</application> + can use to retrieve the files, such as a local FTP site, or an &ms-dos; + partition.</para> + + <para>For example:</para> + + <itemizedlist> + <listitem> + <para>You have many machines connected to your local network, and one + FreeBSD disc. You want to create a local FTP site using the + contents of the FreeBSD disc, and then have your machines use this + local FTP site instead of needing to connect to the Internet.</para> + </listitem> + + <listitem> + <para>You have a FreeBSD disc, and FreeBSD does not recognize your + CD/DVD drive, but &ms-dos; / &windows; does. You want to copy the + FreeBSD installation files to a &ms-dos; partition on the same + computer, and then install FreeBSD using those files.</para> + </listitem> + + <listitem> + <para>The computer you want to install on does not have a CD/DVD + drive or a network card, but you can connect a + <quote>Laplink-style</quote> serial or parallel cable to a computer + that does.</para> + </listitem> + + <listitem> + <para>You want to create a tape that can be used to install + FreeBSD.</para> + </listitem> + </itemizedlist> + + <sect2 id="install-cdrom"> + <title>Creating an Installation CDROM</title> + + <para>As part of each release, the FreeBSD project makes available at + least two CDROM images (<quote>ISO images</quote>) per supported + architecture. These images can be written + (<quote>burned</quote>) to CDs if you have a CD writer, and then used + to install FreeBSD. If you have a CD writer, and bandwidth is cheap, + then this is the easiest way to install FreeBSD.</para> + + <procedure> + <step> + <title>Download the Correct ISO Images</title> + + <para>The ISO images for each release can be downloaded from <filename>ftp://ftp.FreeBSD.org/pub/FreeBSD/ISO-IMAGES-<replaceable>arch</replaceable>/<replaceable>version</replaceable></filename> or the closest mirror. + Substitute <replaceable>arch</replaceable> and + <replaceable>version</replaceable> as appropriate.</para> + + <para>That directory will normally contain the following images:</para> + + <table frame="none"> + <title>FreeBSD 7.<replaceable>X</replaceable> and 8.<replaceable>X</replaceable> + ISO Image Names and Meanings</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Filename</entry> + + <entry>Contents</entry> + </row> + </thead> + + <tbody> + <row> + <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-bootonly.iso</filename></entry> + + <entry>This CD image allows you to start the installation + process by booting from a CD-ROM drive but it does not + contain the support for installing &os; from the CD + itself. You would need to perform a network based install + (e.g. from an FTP server) after booting from this CD.</entry> + </row> + + <row> + <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-dvd1.iso.gz</filename></entry> + + <entry>This DVD image contains everything necessary to + install the base FreeBSD operating system, a + collection of pre-built packages, and the + documentation. It also supports booting into a + <quote>livefs</quote> based rescue mode.</entry> + </row> + + <row> + <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-memstick.img</filename></entry> + + <entry>This image can be written to an USB memory stick + and used to do an install on machines capable of booting + off USB drives. It also supports booting into a + <quote>livefs</quote> based rescue mode. The + documentation packages are provided but no other + packages. This image is not available for &os; 7.<replaceable>X</replaceable>.</entry> + </row> + + <row> + <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc1.iso</filename></entry> + + <entry>This CD image contains the base &os; operating + system and the documentation packages but no other + packages.</entry> + </row> + + <row> + <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc2.iso</filename></entry> + + <entry>A CD image with as many third-party packages + as would fit on the disc. This image is not + available for &os; 8.<replaceable>X</replaceable>.</entry> + </row> + + <row> + <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc3.iso</filename></entry> + + <entry>Another CD image with as many third-party + packages as would fit on the disc. This image is + not available for &os; 8.<replaceable>X</replaceable>.</entry> + </row> + + <row> + <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-docs.iso</filename></entry> + + <entry>The &os; documentation. This image is + not available for &os; 8.<replaceable>X</replaceable>.</entry> + </row> + + <row> + <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-livefs.iso</filename></entry> + + <entry>This CD image contains support for booting into + a <quote>livefs</quote> based rescue mode but does not + support doing an install from the CD itself.</entry> + </row> + </tbody> + </tgroup> + </table> + + <note> + <para>&os; 7.<replaceable>X</replaceable> releases before + &os; 7.3 and &os; 8.0 used a + different naming convention. The names of their ISO + images are not prefixed with + <literal>&os;-</literal>.</para> + </note> + + <para>You <emphasis>must</emphasis> download one of either + the <literal>bootonly</literal> ISO image, + or the image of <literal>disc1</literal>. Do not download + both of them, since the <literal>disc1</literal> image + contains everything that the <literal>bootonly</literal> + ISO image contains.</para> + + <para>Use the <literal>bootonly</literal> ISO if Internet + access is cheap for you. It will let you install &os;, and + you can then install third-party + packages by downloading them using the ports/packages system (see + <xref linkend="ports">) as + necessary.</para> + + <para>Use the image of <literal>dvd1</literal> if you want to + install a &os; + release and want a reasonable selection of third-party packages + on the disc as well.</para> + + <para>The additional disc images are useful, but not essential, + especially if you have high-speed access to the Internet.</para> + </step> + + <step> + <title>Write the CDs</title> + + <para>You must then write the CD images to disc. If you will be + doing this on another FreeBSD system then see + <xref linkend="creating-cds"> for more information (in + particular, <xref linkend="burncd"> and + <xref linkend="cdrecord">).</para> + + <para>If you will be doing this on another platform then you will + need to use whatever utilities exist to control your CD writer on + that platform. The images provided are in the standard ISO format, + which many CD writing applications support.</para> + </step> + </procedure> + + <note><para>If you are interested in building a customized + release of FreeBSD, please see the <ulink + url="&url.articles.releng;">Release Engineering + Article</ulink>.</para></note> + + </sect2> + + <sect2 id="install-ftp"> + <title>Creating a Local FTP Site with a FreeBSD Disc</title> + + <indexterm> + <primary>installation</primary> + <secondary>network</secondary> + <tertiary>FTP</tertiary> + </indexterm> + + <para>FreeBSD discs are laid out in the same way as the FTP site. This + makes it very easy for you to create a local FTP site that can be used + by other machines on your network when installing FreeBSD.</para> + + <procedure> + <step> + <para>On the FreeBSD computer that will host the FTP site, ensure + that the CDROM is in the drive, and mounted on + <filename>/cdrom</filename>.</para> + + <screen>&prompt.root; <userinput>mount /cdrom</userinput></screen> + </step> + + <step> + <para>Create an account for anonymous FTP in + <filename>/etc/passwd</filename>. Do this by editing + <filename>/etc/passwd</filename> using &man.vipw.8; and adding + this line:</para> + + <programlisting>ftp:*:99:99::0:0:FTP:/cdrom:/nonexistent</programlisting> + </step> + + <step> + <para>Ensure that the FTP service is enabled in + <filename>/etc/inetd.conf</filename>.</para> + </step> + </procedure> + + <para>Anyone with network connectivity to your machine can now + chose a media type of FTP and type in + <userinput>ftp://<replaceable>your machine</replaceable></userinput> + after picking <quote>Other</quote> in the FTP sites menu during + the install.</para> + + <note> + <para>If the boot media (floppy disks, usually) for your FTP + clients is not precisely the same version as that provided + by the local FTP site, then <application>sysinstall</application> + will not let you + complete the installation. If the versions are not similar and + you want to override this, you must go into the + <guimenu>Options</guimenu> menu and change distribution name to + <guimenuitem>any</guimenuitem>.</para> + </note> + + <warning> + <para>This approach is OK for a machine that is on your local network, + and that is protected by your firewall. Offering up FTP services to + other machines over the Internet (and not your local network) + exposes your computer to the attention of crackers and other + undesirables. We strongly recommend that you follow good security + practices if you do this.</para> + </warning> + </sect2> + + <sect2> + <title>Creating Installation Floppies</title> + + <indexterm> + <primary>installation</primary> + <secondary>floppies</secondary> + </indexterm> + + <para>If you must install from floppy disk (which we suggest you + do <emphasis>not</emphasis> do), either due to unsupported + hardware or simply because you insist on doing things the hard + way, you must first prepare some floppies for the installation.</para> + + <para>At a minimum, you will need as many 1.44 MB floppies + as it takes to hold all the files in the + <filename>base</filename> (base distribution) directory. If + you are preparing the floppies from &ms-dos;, then they + <emphasis>must</emphasis> be formatted using the &ms-dos; + <command>FORMAT</command> command. If you are using &windows;, + use Explorer to format the disks (right-click on the + <devicename>A:</devicename> drive, and select + <quote>Format</quote>).</para> + + <para>Do <emphasis>not</emphasis> trust factory pre-formatted + floppies. Format them again yourself, just to be sure. Many + problems reported by our users in the past have resulted from + the use of improperly formatted media, which is why we are + making a point of it now.</para> + + <para>If you are creating the floppies on another FreeBSD machine, + a format is still not a bad idea, though you do not need to put + a &ms-dos; filesystem on each floppy. You can use the + <command>bsdlabel</command> and <command>newfs</command> + commands to put a UFS filesystem on them instead, as the + following sequence of commands (for a 3.5" 1.44 MB floppy) + illustrates:</para> + + <screen>&prompt.root; <userinput>fdformat -f 1440 fd0.1440</userinput> +&prompt.root; <userinput>bsdlabel -w fd0.1440 floppy3</userinput> +&prompt.root; <userinput>newfs -t 2 -u 18 -l 1 -i 65536 /dev/fd0</userinput></screen> + + <para>Then you can mount and write to them like any other + filesystem.</para> + + <para>After you have formatted the floppies, you will need to copy + the files to them. The distribution files are split into chunks + conveniently sized so that five of them will fit on a conventional + 1.44 MB floppy. Go through all your floppies, packing as many + files as will fit on each one, until you have all of the + distributions you want packed up in this fashion. Each + distribution should go into a subdirectory on the floppy, e.g.: + <filename>a:\base\base.aa</filename>, + <filename>a:\base\base.ab</filename>, and so on.</para> + + <important> + <para>The <filename>base.inf</filename> file also needs to go on the + first floppy of the <filename>base</filename> set since it is read + by the installation program in order to figure out how many + additional pieces to look for when fetching and concatenating the + distribution.</para> + </important> + + <para>Once you come to the Media screen during the install + process, select <guimenuitem>Floppy</guimenuitem> and you + will be prompted for the rest.</para> + </sect2> + + <sect2 id="install-msdos"> + <title>Installing from an &ms-dos; Partition</title> + + <indexterm> + <primary>installation</primary> + <secondary>from MS-DOS</secondary> + </indexterm> + <para>To prepare for an installation from an &ms-dos; partition, + copy the files from the distribution into a directory + called <filename>freebsd</filename> in the root directory of the + partition. For example, <filename>c:\freebsd</filename>. The + directory structure of the CDROM or FTP site must be partially + reproduced within this directory, so we suggest using the &ms-dos; + <command>xcopy</command> command if you are copying it from a CD. + For example, to prepare for a minimal installation of + FreeBSD:</para> + + <screen><prompt>C:\></prompt> <userinput>md c:\freebsd</userinput> +<prompt>C:\></prompt> <userinput>xcopy e:\bin c:\freebsd\bin\ /s</userinput> +<prompt>C:\></prompt> <userinput>xcopy e:\manpages c:\freebsd\manpages\ /s</userinput></screen> + + <para>Assuming that <devicename>C:</devicename> is where you have + free space and <devicename>E:</devicename> is where your CDROM + is mounted.</para> + + <para>If you do not have a CDROM drive, you can download the + distribution from <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/">ftp.FreeBSD.org</ulink>. + Each distribution is in its own directory; for example, the + <emphasis>base</emphasis> distribution can be found in the <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/base/">&rel.current;/base/</ulink> + directory.</para> + + <para>For as many distributions you wish to install from an &ms-dos; + partition (and you have the free space for), install each one + under <filename>c:\freebsd</filename> — the + <literal>BIN</literal> distribution is the only one required for + a minimum installation.</para> + </sect2> + + <sect2> + <title>Creating an Installation Tape</title> + + <indexterm> + <primary>installation</primary> + <secondary>from QIC/SCSI Tape</secondary> + </indexterm> + <para>Installing from tape is probably the easiest method, short + of an online FTP install or CDROM install. The installation + program expects the files to be simply tarred onto the tape. + After getting all of the distribution files you are interested + in, simply tar them onto the tape:</para> + + <screen>&prompt.root; <userinput>cd /freebsd/distdir</userinput> +&prompt.root; <userinput>tar cvf /dev/rwt0 dist1 ... dist2</userinput></screen> + + <para>When you perform the installation, you should make + sure that you leave enough room in some temporary directory + (which you will be allowed to choose) to accommodate the + <emphasis>full</emphasis> contents of the tape you have created. + Due to the non-random access nature of tapes, this method of + installation requires quite a bit of temporary storage.</para> + + <note> + <para>When starting the installation, the tape must be in the + drive <emphasis>before</emphasis> booting from the boot + floppy. The installation probe may otherwise fail to find + it.</para> + </note> + </sect2> + + <sect2> + <title>Before Installing over a Network</title> + + <indexterm> + <primary>installation</primary> + <secondary>network</secondary> + <tertiary>serial (PPP)</tertiary> + </indexterm> + <indexterm> + <primary>installation</primary> + <secondary>network</secondary> + <tertiary>parallel (PLIP)</tertiary> + </indexterm> + <indexterm> + <primary>installation</primary> + <secondary>network</secondary> + <tertiary>Ethernet</tertiary> + </indexterm> + <para>There are three types of network installations available. + Ethernet (a standard Ethernet controller), Serial port (PPP), or + Parallel port (PLIP (laplink cable)).</para> + + <para>For the fastest possible network installation, an + Ethernet adapter is always a good choice! FreeBSD supports most + common PC Ethernet cards; a table of supported cards (and their + required settings) is provided in the Hardware Notes for each + release of FreeBSD. If you are using one of the supported PCMCIA + Ethernet cards, also be sure that it is plugged in + <emphasis>before</emphasis> the laptop is powered on! FreeBSD does + not, unfortunately, currently support hot insertion of PCMCIA cards + during installation.</para> + + <para>You will also need to know your IP address on the network, + the netmask value for your address class, and the name of your + machine. If you are installing over a PPP connection and do not + have a static IP, fear not, the IP address can be dynamically + assigned by your ISP. Your system administrator can tell you + which values to use for your particular network setup. If you + will be referring to other hosts by name rather than IP address, + you will also need a name server and possibly the address of a + gateway (if you are using PPP, it is your provider's IP address) + to use in talking to it. If you want to install by FTP via a + HTTP proxy, you will also need the proxy's address. + If you do not know the answers to all or most of these questions, + then you should really probably talk to your system administrator + or ISP <emphasis>before</emphasis> trying this type of + installation.</para> + + <para>If you are using a modem, then PPP is almost certainly + your only choice. Make sure that you have your service + provider's information handy as you will need to know it fairly + early in the installation process.</para> + + <para>If you use PAP or CHAP to connect your ISP (in other words, if + you can connect to the ISP in &windows; without using a script), then + all you will need to do is type in <command>dial</command> at the + <application>ppp</application> prompt. Otherwise, you will need to + know how to dial your ISP using the <quote>AT commands</quote> + specific to your modem, as the PPP dialer provides only a very + simple terminal emulator. Please refer to the user-ppp <link + linkend="userppp">handbook</link> and <ulink + url="&url.books.faq;/ppp.html">FAQ</ulink> + entries for further information. + If you have problems, logging can be directed to the screen using + the command <command>set log local ...</command>.</para> + + <para>If a hard-wired connection to another FreeBSD + machine is available, you might also consider installing + over a <quote>laplink</quote> parallel port cable. The data rate + over the parallel port is much higher than what is typically + possible over a serial line (up to 50 kbytes/sec), thus + resulting in a quicker installation.</para> + + <sect3> + <title>Before Installing via NFS</title> + + <indexterm> + <primary>installation</primary> + <secondary>network</secondary> + <tertiary>NFS</tertiary> + </indexterm> + <para>The NFS installation is fairly straight-forward. Simply + copy the FreeBSD distribution files you want onto an NFS server + and then point the NFS media selection at it.</para> + + <para>If this server supports only <quote>privileged port</quote> + (as is generally the default for Sun workstations), you will + need to set the option <literal>NFS Secure</literal> in the + <guimenu>Options</guimenu> menu before installation can + proceed.</para> + + <para>If you have a poor quality Ethernet card which suffers + from very slow transfer rates, you may also wish to toggle the + <literal>NFS Slow</literal> flag.</para> + + <para>In order for NFS installation to work, the server must + support subdir mounts, for example, if your + FreeBSD &rel.current; distribution directory lives on: + <filename>ziggy:/usr/archive/stuff/FreeBSD</filename>, then + <hostid>ziggy</hostid> will have to allow the direct mounting + of <filename>/usr/archive/stuff/FreeBSD</filename>, not just + <filename>/usr</filename> or + <filename>/usr/archive/stuff</filename>.</para> + + <para>In FreeBSD's <filename>/etc/exports</filename> file, this + is controlled by the <option>-alldirs</option> options. Other NFS + servers may have different conventions. If you are getting + <errorname>permission denied</errorname> messages from the + server, then it is likely that you do not have this enabled + properly.</para> + </sect3> + + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/install/disk-layout.kil b/en_US.ISO8859-1/books/handbook/install/disk-layout.kil Binary files differnew file mode 100644 index 0000000000..85820c2878 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/install/disk-layout.kil diff --git a/en_US.ISO8859-1/books/handbook/install/example-dir1.dot b/en_US.ISO8859-1/books/handbook/install/example-dir1.dot new file mode 100644 index 0000000000..f259e8377d --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/install/example-dir1.dot @@ -0,0 +1,7 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/"; +} diff --git a/en_US.ISO8859-1/books/handbook/install/example-dir2.dot b/en_US.ISO8859-1/books/handbook/install/example-dir2.dot new file mode 100644 index 0000000000..b846c82399 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/install/example-dir2.dot @@ -0,0 +1,8 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/" -> "B1/"; + "A1/" -> "B2/"; + root -> "A2/"; +} diff --git a/en_US.ISO8859-1/books/handbook/install/example-dir3.dot b/en_US.ISO8859-1/books/handbook/install/example-dir3.dot new file mode 100644 index 0000000000..178a3a91bb --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/install/example-dir3.dot @@ -0,0 +1,8 @@ +// $FreeBSD$ + +digraph directory { + root [label="Root\n/"]; + root -> "A1/"; + root -> "A2/" -> "B1/"; + "A2/" -> "B2/"; +} diff --git a/en_US.ISO8859-1/books/handbook/install/example-dir4.dot b/en_US.ISO8859-1/books/handbook/install/example-dir4.dot new file mode 100644 index 0000000000..82d12b421a --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/install/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/en_US.ISO8859-1/books/handbook/install/example-dir5.dot b/en_US.ISO8859-1/books/handbook/install/example-dir5.dot new file mode 100644 index 0000000000..f5aa6e01dc --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/install/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/en_US.ISO8859-1/books/handbook/introduction/Makefile b/en_US.ISO8859-1/books/handbook/introduction/Makefile new file mode 100644 index 0000000000..4c22f7ce8a --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/introduction/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= introduction/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml new file mode 100644 index 0000000000..386eb19f90 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.sgml @@ -0,0 +1,1020 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="introduction"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Mock</surname> + <contrib>Restructured, reorganized, and parts + rewritten by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>Introduction</title> + + <sect1 id="introduction-synopsis"> + <title>Synopsis</title> + + <para>Thank you for your interest in &os;! The following chapter + covers various aspects of the &os; Project, such as its history, + goals, development model, and so on.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How &os; relates to other computer operating systems.</para> + </listitem> + + <listitem> + <para>The history of the &os; Project.</para> + </listitem> + + <listitem> + <para>The goals of the &os; Project.</para> + </listitem> + + <listitem> + <para>The basics of the &os; open-source development model.</para> + </listitem> + + <listitem> + <para>And of course: where the name <quote>&os;</quote> comes + from.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="nutshell"> + <title>Welcome to &os;!</title> + <indexterm><primary>4.4BSD-Lite</primary></indexterm> + + <para>&os; is a 4.4BSD-Lite based operating system for + Intel (x86 and &itanium;), AMD64, Sun + &ultrasparc; computers. Ports to other + architectures are also underway. You can also + read about <link linkend="history">the history of &os;</link>, + or the <link linkend="relnotes">current release</link>. If you + are interested in contributing something to the Project (code, + hardware, funding), see the <ulink + url="&url.articles.contributing;/index.html">Contributing to &os;</ulink> article.</para> + + <sect2 id="os-overview"> + <title>What Can &os; Do?</title> + + <para>&os; has many noteworthy features. Some of these + are:</para> + + <itemizedlist> + <indexterm><primary>preemptive multitasking</primary></indexterm> + <listitem> + <para><emphasis>Preemptive multitasking</emphasis> with + dynamic priority adjustment to ensure smooth and fair + sharing of the computer between applications and users, even + under the heaviest of loads.</para> + </listitem> + + <indexterm><primary>multi-user facilities</primary></indexterm> + <listitem> + <para><emphasis>Multi-user facilities</emphasis> which allow many + people to use a &os; system simultaneously for a variety + of things. This means, for example, that system peripherals + such as printers and tape drives are properly shared between + all users on the system or the network and that individual + resource limits can be placed on users or groups of users, + protecting critical system resources from over-use.</para> + </listitem> + + <indexterm><primary>TCP/IP networking</primary></indexterm> + <listitem> + <para>Strong <emphasis>TCP/IP networking</emphasis> with + support for industry standards such as SCTP, DHCP, NFS, + NIS, PPP, SLIP, IPsec, and IPv6. This means that your &os; + machine can interoperate easily with other systems as well as + act as an enterprise server, providing vital functions such as NFS + (remote file access) and email services or putting your + organization on the Internet with WWW, FTP, routing and + firewall (security) services.</para> + </listitem> + + <indexterm><primary>memory protection</primary></indexterm> + <listitem> + <para><emphasis>Memory protection</emphasis> ensures that + applications (or users) cannot interfere with each other. One + application crashing will not affect others in any way.</para> + </listitem> + + <listitem> + <para>&os; is a <emphasis>32-bit</emphasis> operating + system (<emphasis>64-bit</emphasis> on the &itanium;, + AMD64, and &ultrasparc;) and was designed as such from the ground + up.</para> + </listitem> + + <indexterm> + <primary>X Window System</primary> + </indexterm> + + <listitem> + <para>The industry standard <emphasis>X Window System</emphasis> + (X11R7) provides a graphical user interface (GUI) for the cost + of a common VGA card and monitor and comes with full + sources.</para> + </listitem> + + <indexterm> + <primary>binary compatibility</primary> + <secondary>Linux</secondary> + </indexterm> + <indexterm> + <primary>binary compatibility</primary> + <secondary>SCO</secondary> + </indexterm> + <indexterm> + <primary>binary compatibility</primary> + <secondary>SVR4</secondary> + </indexterm> + <indexterm> + <primary>binary compatibility</primary> + <secondary>BSD/OS</secondary> + </indexterm> + <indexterm> + <primary>binary compatibility</primary> + <secondary>NetBSD</secondary> + </indexterm> + <listitem> + <para><emphasis>Binary compatibility</emphasis> with many + programs built for Linux, SCO, SVR4, BSDI and NetBSD.</para> + </listitem> + + <listitem> + <para>Thousands of <emphasis>ready-to-run</emphasis> + applications are available from the &os; + <emphasis>ports</emphasis> and <emphasis>packages</emphasis> + collection. Why search the net when you can find it all right + here?</para> + </listitem> + + <listitem> + <para>Thousands of additional and + <emphasis>easy-to-port</emphasis> applications are available + on the Internet. &os; is source code compatible with most + popular commercial &unix; systems and thus most applications + require few, if any, changes to compile.</para> + </listitem> + + <indexterm><primary>virtual memory</primary></indexterm> + <listitem> + <para>Demand paged <emphasis>virtual memory</emphasis> and + <quote>merged VM/buffer cache</quote> design efficiently + satisfies applications with large appetites for memory while + still maintaining interactive response to other users.</para> + </listitem> + + <indexterm> + <primary>Symmetric Multi-Processing (SMP)</primary> + </indexterm> + <listitem> + <para><emphasis>SMP</emphasis> support for machines with + multiple CPUs.</para> + </listitem> + + <indexterm> + <primary>compilers</primary> + <secondary>C</secondary> + </indexterm> + <indexterm> + <primary>compilers</primary> + <secondary>C++</secondary> + </indexterm> + <listitem> + <para>A full complement of <emphasis>C</emphasis> + and <emphasis>C++</emphasis> + development tools. + Many additional languages for advanced research + and development are also available in the ports and packages + collection.</para> + </listitem> + + <indexterm><primary>source code</primary></indexterm> + <listitem> + <para><emphasis>Source code</emphasis> for the entire system + means you have the greatest degree of control over your + environment. Why be locked into a proprietary solution + at the mercy of your vendor when you can have a truly open + system?</para> + </listitem> + + <listitem> + <para>Extensive <emphasis>online + documentation</emphasis>.</para> + </listitem> + + <listitem> + <para><emphasis>And many more!</emphasis></para> + </listitem> + </itemizedlist> + + <indexterm><primary>4.4BSD-Lite</primary></indexterm> + <indexterm> + <primary>Computer Systems Research Group (CSRG)</primary> + </indexterm> + <indexterm><primary>U.C. Berkeley</primary></indexterm> + <para>&os; is based on the 4.4BSD-Lite release from Computer + Systems Research Group (CSRG) at the University of California at + Berkeley, and carries on the distinguished tradition of BSD + systems development. In addition to the fine work provided by + CSRG, the &os; Project has put in many thousands of hours in + fine tuning the system for maximum performance and reliability in + real-life load situations. As many of the commercial giants + struggle to field PC operating systems with such features, + performance and reliability, &os; can offer them + <emphasis>now</emphasis>!</para> + + <para>The applications to which &os; can be put are truly + limited only by your own imagination. From software development + to factory automation, inventory control to azimuth correction of + remote satellite antennae; if it can be done with a commercial + &unix; product then it is more than likely that you can do it with + &os; too! &os; also benefits significantly from + literally thousands of high quality applications developed by + research centers and universities around the world, often + available at little to no cost. Commercial applications are also + available and appearing in greater numbers every day.</para> + + <para>Because the source code for &os; itself is generally + available, the system can also be customized to an almost unheard + of degree for special applications or projects, and in ways not + generally possible with operating systems from most major + commercial vendors. Here is just a sampling of some of the + applications in which people are currently using &os;:</para> + + <itemizedlist> + <listitem> + <para><emphasis>Internet Services:</emphasis> The robust TCP/IP + networking built into &os; makes it an ideal platform for a + variety of Internet services such as:</para> + + <itemizedlist> + <indexterm><primary>FTP servers</primary></indexterm> + <listitem> + <para>FTP servers</para> + </listitem> + + <indexterm><primary>web servers</primary></indexterm> + <listitem> + <para>World Wide Web servers (standard or secure + [SSL])</para> + </listitem> + + <listitem> + <para>IPv4 and IPv6 routing</para> + </listitem> + + <indexterm><primary>firewall</primary></indexterm> + <indexterm><primary>NAT</primary></indexterm> + <listitem> + <para>Firewalls and NAT (<quote>IP masquerading</quote>) + gateways</para> + </listitem> + + <indexterm> + <primary>electronic mail</primary> + <see>email</see> + </indexterm> + <indexterm> + <primary>email</primary> + </indexterm> + <listitem> + <para>Electronic Mail servers</para> + </listitem> + + <indexterm><primary>USENET</primary></indexterm> + <listitem> + <para>USENET News or Bulletin Board Systems</para> + </listitem> + + <listitem> + <para>And more...</para> + </listitem> + </itemizedlist> + + <para>With &os;, you can easily start out small with an + inexpensive 386 class PC and upgrade all the way up to a + quad-processor Xeon with RAID storage as your enterprise + grows.</para> + </listitem> + + <listitem> + <para><emphasis>Education:</emphasis> Are you a student of + computer science or a related engineering field? There is no + better way of learning about operating systems, computer + architecture and networking than the hands on, under the hood + experience that &os; can provide. A number of freely + available CAD, mathematical and graphic design packages also + make it highly useful to those whose primary interest in a + computer is to get <emphasis>other</emphasis> work + done!</para> + </listitem> + + <listitem> + <para><emphasis>Research:</emphasis> With source code for the + entire system available, &os; is an excellent platform for + research in operating systems as well as other branches of + computer science. &os;'s freely available nature also makes + it possible for remote groups to collaborate on ideas or + shared development without having to worry about special + licensing agreements or limitations on what may be discussed + in open forums.</para> + </listitem> + + <indexterm><primary>router</primary></indexterm> + <indexterm><primary>DNS Server</primary></indexterm> + <listitem> + <para><emphasis>Networking:</emphasis> Need a new router? A + name server (DNS)? A firewall to keep people out of your + internal network? &os; can easily turn that unused 386 or + 486 PC sitting in the corner into an advanced router with + sophisticated packet-filtering capabilities.</para> + </listitem> + + <indexterm> + <primary>X Window System</primary> + </indexterm> + <indexterm> + <primary>X Window System</primary> + <secondary>Accelerated-X</secondary> + </indexterm> + <listitem> + <para><emphasis>X Window workstation:</emphasis> &os; is a + fine choice for an inexpensive X terminal solution, + using the freely available X11 server. + Unlike an X terminal, &os; allows many applications to be run + locally if desired, thus relieving the burden on a central + server. &os; can even boot <quote>diskless</quote>, making + individual workstations even cheaper and easier to + administer.</para> + </listitem> + + <indexterm><primary>GNU Compiler Collection</primary></indexterm> + <listitem> + <para><emphasis>Software Development:</emphasis> The basic + &os; system comes with a full complement of development + tools including the renowned GNU C/C++ compiler and + debugger.</para> + </listitem> + </itemizedlist> + + <para>&os; is available in both source and binary form on CD-ROM, + DVD, and via anonymous FTP. Please see <xref linkend="mirrors"> + for more information about obtaining &os;.</para> + </sect2> + + <sect2 id="introduction-nutshell-users"> + <title>Who Uses &os;?</title> + + <indexterm> + <primary>users</primary> + <secondary>large sites running &os;</secondary> + </indexterm> + + <para>&os; is used as a platform for devices and products from + many of the world's largest IT companies, including:</para> + + <itemizedlist> + <indexterm><primary>Apple</primary></indexterm> + <listitem> + <para><ulink url="http://www.apple.com/">Apple</ulink></para> + </listitem> + + <indexterm><primary>Cisco</primary></indexterm> + <listitem> + <para><ulink url="http://www.cisco.com/">Cisco</ulink></para> + </listitem> + + <indexterm><primary>Juniper</primary></indexterm> + <listitem> + <para><ulink url="http://www.juniper.net/">Juniper</ulink></para> + </listitem> + + <indexterm><primary>NetApp</primary></indexterm> + <listitem> + <para><ulink url="http://www.netapp.com/">NetApp</ulink></para> + </listitem> + </itemizedlist> + + <para>&os; is also used to power some of the biggest sites on the + Internet, including:</para> + + <itemizedlist> + <indexterm><primary>Yahoo!</primary></indexterm> + <listitem> + <para><ulink url="http://www.yahoo.com/">Yahoo!</ulink></para> + </listitem> + + <indexterm><primary>Yandex</primary></indexterm> + <listitem> + <para><ulink url="http://www.yandex.ru/">Yandex</ulink></para> + </listitem> + + <indexterm><primary>Apache</primary></indexterm> + <listitem> + <para><ulink url="http://www.apache.org/">Apache</ulink></para> + </listitem> + + <indexterm><primary>Rambler</primary></indexterm> + <listitem> + <para><ulink url="http://www.rambler.ru/">Rambler</ulink></para> + </listitem> + + <indexterm><primary>Sina</primary></indexterm> + <listitem> + <para><ulink url="http://www.sina.com/">Sina</ulink></para> + </listitem> + + <indexterm><primary>Pair Networks</primary></indexterm> + <listitem> + <para><ulink url="http://www.pair.com/">Pair Networks</ulink></para> + </listitem> + + <indexterm><primary>Sony Japan</primary></indexterm> + <listitem> + <para><ulink url="http://www.sony.co.jp/">Sony Japan</ulink></para> + </listitem> + + <indexterm><primary>Netcraft</primary></indexterm> + <listitem> + <para><ulink url="http://www.netcraft.com/">Netcraft</ulink></para> + </listitem> + + <indexterm><primary>NetEase</primary></indexterm> + <listitem> + <para><ulink url="http://www.163.com/">NetEase</ulink></para> + </listitem> + + <indexterm><primary>Weathernews</primary></indexterm> + <listitem> + <para><ulink url="http://www.wni.com/">Weathernews</ulink></para> + </listitem> + + <indexterm><primary>TELEHOUSE America</primary></indexterm> + <listitem> + <para><ulink url="http://www.telehouse.com/">TELEHOUSE + America</ulink></para> + </listitem> + + <indexterm><primary>Experts Exchange</primary></indexterm> + <listitem> + <para><ulink url="http://www.experts-exchange.com/">Experts + Exchange</ulink></para> + </listitem> + + </itemizedlist> + + <para>and many more.</para> + </sect2> + </sect1> + + <sect1 id="history"> + <title>About the &os; Project</title> + + <para>The following section provides some background information on + the project, including a brief history, project goals, and the + development model of the project.</para> + + <sect2 id="intro-history"> + <sect2info role="firstperson"> + <authorgroup> + <author> + <firstname>Jordan</firstname> + <surname>Hubbard</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>A Brief History of &os;</title> + + <indexterm><primary>386BSD Patchkit</primary></indexterm> + <indexterm><primary>Hubbard, Jordan</primary></indexterm> + <indexterm><primary>Williams, Nate</primary></indexterm> + <indexterm><primary>Grimes, Rod</primary></indexterm> + <indexterm> + <primary>FreeBSD Project</primary> + <secondary>history</secondary> + </indexterm> + <para>The &os; Project had its genesis in the early part of 1993, + partially as an outgrowth of the <quote>Unofficial 386BSD + Patchkit</quote> by the patchkit's last 3 coordinators: Nate + Williams, Rod Grimes and myself.</para> + + <indexterm><primary>386BSD</primary></indexterm> + <para>Our original goal was to produce an intermediate snapshot of + 386BSD in order to fix a number of problems with it that the + patchkit mechanism just was not capable of solving. Some of you + may remember the early working title for the project being + <quote>386BSD 0.5</quote> or <quote>386BSD Interim</quote> in + reference to that fact.</para> + + <indexterm><primary>Jolitz, Bill</primary></indexterm> + <para>386BSD was Bill Jolitz's operating system, which had been up + to that point suffering rather severely from almost a year's worth + of neglect. As the patchkit swelled ever more uncomfortably with + each passing day, we were in unanimous agreement that something + had to be done and decided to assist Bill by providing + this interim <quote>cleanup</quote> snapshot. Those plans came to + a rude halt when Bill Jolitz suddenly decided to withdraw his + sanction from the project without any clear indication of what + would be done instead.</para> + + <indexterm><primary>Greenman, David</primary></indexterm> + <indexterm><primary>Walnut Creek CDROM</primary></indexterm> + <para>It did not take us long to decide that the goal remained + worthwhile, even without Bill's support, and so we adopted the + name <quote>&os;</quote>, coined by David Greenman. Our initial + objectives were set after consulting with the system's current + users and, once it became clear that the project was on the road + to perhaps even becoming a reality, I contacted Walnut Creek CDROM + with an eye toward improving &os;'s distribution channels for + those many unfortunates without easy access to the Internet. + Walnut Creek CDROM not only supported the idea of distributing + &os; on CD but also went so far as to provide the project with a + machine to work on and a fast Internet connection. Without Walnut + Creek CDROM's almost unprecedented degree of faith in what was, at + the time, a completely unknown project, it is quite unlikely that + &os; would have gotten as far, as fast, as it has today.</para> + + <indexterm><primary>4.3BSD-Lite</primary></indexterm> + <indexterm><primary>Net/2</primary></indexterm> + <indexterm><primary>U.C. Berkeley</primary></indexterm> + <indexterm><primary>386BSD</primary></indexterm> + <indexterm><primary>Free Software Foundation</primary></indexterm> + <para>The first CD-ROM (and general net-wide) distribution was + &os; 1.0, released in December of 1993. This was based on the + 4.3BSD-Lite (<quote>Net/2</quote>) tape from U.C. Berkeley, with + many components also provided by 386BSD and the Free Software + Foundation. It was a fairly reasonable success for a first + offering, and we followed it with the highly successful &os; + 1.1 release in May of 1994.</para> + + <indexterm><primary>Novell</primary></indexterm> + <indexterm><primary>U.C. Berkeley</primary></indexterm> + <indexterm><primary>Net/2</primary></indexterm> + <indexterm><primary>AT&T</primary></indexterm> + <para>Around this time, some rather unexpected storm clouds formed + on the horizon as Novell and U.C. Berkeley settled their + long-running lawsuit over the legal status of the Berkeley Net/2 + tape. A condition of that settlement was U.C. Berkeley's + concession that large parts of Net/2 were <quote>encumbered</quote> + code and the property of Novell, who had in turn acquired it from + AT&T some time previously. What Berkeley got in return was + Novell's <quote>blessing</quote> that the 4.4BSD-Lite release, when + it was finally released, would be declared unencumbered and all + existing Net/2 users would be strongly encouraged to switch. This + included &os;, and the project was given until the end of July + 1994 to stop shipping its own Net/2 based product. Under the + terms of that agreement, the project was allowed one last release + before the deadline, that release being &os; 1.1.5.1.</para> + + <para>&os; then set about the arduous task of literally + re-inventing itself from a completely new and rather incomplete + set of 4.4BSD-Lite bits. The <quote>Lite</quote> releases were + light in part because Berkeley's CSRG had removed large chunks of + code required for actually constructing a bootable running system + (due to various legal requirements) and the fact that the Intel + port of 4.4 was highly incomplete. It took the project until + November of 1994 to make this transition, at which point it + released &os; 2.0 to the net and on CD-ROM (in late December). + Despite being still more than a little rough around the edges, + the release was a significant success and was followed by the + more robust and easier to install &os; 2.0.5 release in June of + 1995.</para> + + <para>We released &os; 2.1.5 in August of 1996, and it appeared + to be popular enough among the ISP and commercial communities that + another release along the 2.1-STABLE branch was merited. This was + &os; 2.1.7.1, released in February 1997 and capping the end of + mainstream development on 2.1-STABLE. Now in maintenance mode, + only security enhancements and other critical bug fixes will be + done on this branch (RELENG_2_1_0).</para> + + <para>&os; 2.2 was branched from the development mainline + (<quote>-CURRENT</quote>) in November 1996 as the RELENG_2_2 + branch, and the first full release (2.2.1) was released in April + 1997. Further releases along the 2.2 branch were done in the + summer and fall of '97, the last of which (2.2.8) appeared in + November 1998. The first official 3.0 release appeared in + October 1998 and spelled the beginning of the end for the 2.2 + branch.</para> + + <para>The tree branched again on Jan 20, 1999, leading to the + 4.0-CURRENT and 3.X-STABLE branches. From 3.X-STABLE, 3.1 was + released on February 15, 1999, 3.2 on May 15, 1999, 3.3 on + September 16, 1999, 3.4 on December 20, 1999, and 3.5 on + June 24, 2000, which was followed a few days later by a minor + point release update to 3.5.1, to incorporate some last-minute + security fixes to Kerberos. This will be the final release in the + 3.X branch.</para> + + <para>There was another branch on March 13, 2000, which saw the + emergence of the 4.X-STABLE branch. There have been several releases + from it so far: 4.0-RELEASE was introduced in March 2000, and + the last 4.11-RELEASE came out in January 2005.</para> + + <para>The long-awaited 5.0-RELEASE was announced on January 19, + 2003. The culmination of nearly three years of work, this + release started &os; on the path of advanced multiprocessor + and application thread support and introduced support for the + &ultrasparc; and <literal>ia64</literal> platforms. This release + was followed by 5.1 in June of 2003. The last 5.X release from the + -CURRENT branch was 5.2.1-RELEASE, introduced in February 2004.</para> + + <para>The RELENG_5 branch, created in August 2004, was followed by + 5.3-RELEASE, which marked the beginning of the 5-STABLE branch + releases. The most recent 5.5-RELEASE release came out in May 2006. + There will be no additional releases from the RELENG_5 branch.</para> + + <para>The tree was branched again in July 2005, this time for RELENG_6. + 6.0-RELEASE, the first release of the 6.X branch, was released in + November 2005. The most recent 6.4-RELEASE came out in + November 2008. There will be no additional releases from the + RELENG_6 branch. This branch is the last branch to support the + Alpha architecture.</para> + + <para>The RELENG_7 branch was created in October 2007. The first + release of this branch was 7.0-RELEASE, which came + out in February 2008. The most recent 7.4-RELEASE came out + in February 2011. There will be no additional releases from the + RELENG_7 branch.</para> + + <para>The tree was branched again in August 2009, this time for + RELENG_8. 8.0-RELEASE, the first release of the 8.X branch, was + released in November 2009. The most recent + &rel2.current;-RELEASE came out in &rel2.current.date;. There will + be additional releases from the RELENG_8 branch.</para> + + <para>The RELENG_9 branch was created in September 2011. The first + release of this branch was &rel.current;-RELEASE, which came + out in &rel.current.date;. There will be additional releases + from the RELENG_9 branch.</para> + + <para>For now, long-term development projects continue to take place + in the 10.X-CURRENT (trunk) branch, and SNAPshot releases of 10.X on + CD-ROM (and, of course, on the net) are continually made available + from <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/">the snapshot + server</ulink> as work progresses.</para> + </sect2> + + <sect2 id="goals"> + <sect2info> + <authorgroup> + <author> + <firstname>Jordan</firstname> + <surname>Hubbard</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>&os; Project Goals</title> + + <indexterm> + <primary>FreeBSD Project</primary> + <secondary>goals</secondary> + </indexterm> + <para>The goals of the &os; Project are to provide software that + may be used for any purpose and without strings attached. Many of + us have a significant investment in the code (and project) and + would certainly not mind a little financial compensation now and + then, but we are definitely not prepared to insist on it. We + believe that our first and foremost <quote>mission</quote> is to + provide code to any and all comers, and for whatever purpose, so + that the code gets the widest possible use and provides the widest + possible benefit. This is, I believe, one of the most fundamental + goals of Free Software and one that we enthusiastically + support.</para> + + <indexterm> + <primary>GNU General Public License (GPL)</primary> + </indexterm> + <indexterm> + <primary>GNU Lesser General Public License (LGPL)</primary> + </indexterm> + <indexterm><primary>BSD Copyright</primary></indexterm> + <para>That code in our source tree which falls under the GNU + General Public License (GPL) or Library General Public License + (LGPL) comes with slightly more strings attached, though at + least on the side of enforced access rather than the usual + opposite. Due to the additional complexities that can evolve + in the commercial use of GPL software we do, however, prefer + software submitted under the more relaxed BSD copyright when + it is a reasonable option to do so.</para> + </sect2> + + <sect2 id="development"> + <sect2info> + <authorgroup> + <author> + <firstname>Satoshi</firstname> + <surname>Asami</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>The &os; Development Model</title> + + <indexterm> + <primary>FreeBSD Project</primary> + <secondary>development model</secondary> + </indexterm> + <para>The development of &os; is a very open and flexible + process, being literally built from the contributions + of hundreds of people around the world, as can be seen from + our <ulink + url="&url.articles.contributors;/article.html">list of + contributors</ulink>. &os;'s development infrastructure allow + these hundreds of developers to collaborate over the Internet. + We are constantly on the lookout for + new developers and ideas, and those interested in becoming + more closely involved with the project need simply contact us + at the &a.hackers;. The &a.announce; is also available to + those wishing to make other &os; users aware of major areas + of work.</para> + + <para>Useful things to know about the &os; Project and its + development process, whether working independently or in close + cooperation:</para> + + <variablelist> + <varlistentry> + <term>The SVN and CVS repositories<anchor + id="development-cvs-repository"></term> + + <indexterm> + <primary>CVS</primary> + <secondary>repository</secondary> + </indexterm> + <indexterm> + <primary>Concurrent Versions System</primary> + <see>CVS</see> + </indexterm> + <indexterm> + <primary>SVN</primary> + <secondary>repository</secondary> + </indexterm> + <indexterm> + <primary>Subversion</primary> + <see>SVN</see> + </indexterm> + <listitem> + <para>For several years, the central source tree for &os; + was maintained by + <ulink url="http://www.nongnu.org/cvs/">CVS</ulink> + (Concurrent Versions System), a freely available source code + control tool that comes bundled with &os;. In June 2008, the + Project switched to using <ulink + url="http://subversion.tigris.org">SVN</ulink> (Subversion). + The switch was deemed necessary, as the technical limitations + imposed by <application>CVS</application> were becoming obvious + due to the rapid expansion of the source tree and the amount + of history already stored. While the main repository now uses + <application>SVN</application>, client side tools like + <application>csup</application> that depend on the older + <application>CVS</application> infrastructure, continue to + work normally — changes in the + <application>SVN</application> repository are backported to + <application>CVS</application> for this purpose. + Currently, only the central source tree is controlled by + <application>SVN</application>. + The documentation, World Wide Web, and Ports repositories are + still using <application>CVS</application>. The primary + <ulink + url="http://www.FreeBSD.org/cgi/cvsweb.cgi">repository</ulink> + resides on a machine in Santa Clara CA, USA + from where it is replicated to numerous mirror machines + throughout the world. The <application>SVN</application> tree, + which contains the <link linkend="current">-CURRENT</link> and + <link linkend="stable">-STABLE</link> trees, + can all be easily replicated to your own machine as well. + Please refer to the <link linkend="synching">Synchronizing + your source tree</link> section for more information on + doing this.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>The committers list<anchor + id="development-committers"></term> + + <indexterm><primary>committers</primary></indexterm> + <listitem> + <para>The <firstterm>committers</firstterm> + are the people who have <emphasis>write</emphasis> access to + the CVS tree, and are authorized to make modifications + to the &os; source (the term <quote>committer</quote> + comes from the &man.cvs.1; <command>commit</command> + command, which is used to bring new changes into the CVS + repository). The best way of making submissions for review + by the committers list is to use the &man.send-pr.1; + command. If something appears to be jammed in the + system, then you may also reach them by sending mail to + the &a.committers;.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>The FreeBSD core team<anchor id="development-core"></term> + + <indexterm><primary>core team</primary></indexterm> + <listitem> + <para>The <firstterm>&os; core team</firstterm> + would be equivalent to the board of directors if the + &os; Project were a company. The primary task of the core + team is to make sure the project, as a whole, is in good shape + and is heading in the right directions. Inviting dedicated + and responsible developers to join our group of committers + is one of the functions of the core team, as is the + recruitment of new core team members as others move on. + The current core team was elected from a pool of committer + candidates in July 2010. Elections are held + every 2 years.</para> + + <para>Some core team members also have specific areas of + responsibility, meaning that they are committed to + ensuring that some large portion of the system works as + advertised. For a complete list of &os; developers + and their areas of responsibility, please see the <ulink + url="&url.articles.contributors;/article.html">Contributors + List</ulink></para> + + <note> + <para>Most members of the core team are volunteers when it + comes to &os; development and do not benefit from the + project financially, so <quote>commitment</quote> should + also not be misconstrued as meaning <quote>guaranteed + support.</quote> The <quote>board of directors</quote> + analogy above is not very accurate, and it may be + more suitable to say that these are the people who gave up + their lives in favor of &os; against their better + judgement!</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>Outside contributors</term> + + <indexterm><primary>contributors</primary></indexterm> + <listitem> + <para>Last, but definitely not least, the largest group of + developers are the users themselves who provide feedback and + bug fixes to us on an almost constant basis. The primary + way of keeping in touch with &os;'s more non-centralized + development is to subscribe to the &a.hackers; where such + things are discussed. See <xref linkend="eresources"> for + more information about the various &os; mailing lists.</para> + + <para><citetitle><ulink + url="&url.articles.contributors;/article.html">The + &os; Contributors List</ulink></citetitle> is a long + and growing one, so why not join it by contributing + something back to &os; today?</para> + + <para>Providing code is not the only way of contributing to + the project; for a more complete list of things that need + doing, please refer to the <ulink + url="&url.base;/index.html">&os; Project web + site</ulink>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>In summary, our development model is organized as a loose set + of concentric circles. The centralized model is designed for the + convenience of the <emphasis>users</emphasis> of &os;, who are + provided with an easy way of tracking one central code + base, not to keep potential contributors out! Our desire is to + present a stable operating system with a large set of coherent + <link linkend="ports">application programs</link> that the users + can easily install and use — this model works very well in + accomplishing that.</para> + + <para>All we ask of those who would join us as &os; developers is + some of the same dedication its current people have to its + continued success!</para> + </sect2> + + <sect2 id="relnotes"> + <title>The Current &os; Release</title> + + <indexterm><primary>NetBSD</primary></indexterm> + <indexterm><primary>OpenBSD</primary></indexterm> + <indexterm><primary>386BSD</primary></indexterm> + <indexterm><primary>Free Software Foundation</primary></indexterm> + <indexterm><primary>U.C. Berkeley</primary></indexterm> + <indexterm> + <primary>Computer Systems Research Group (CSRG)</primary> + </indexterm> + <para>&os; is a freely available, full source 4.4BSD-Lite based + release for Intel &i386;, &i486;, &pentium;, + &pentium; Pro, + &celeron;, + &pentium; II, + &pentium; III, + &pentium; 4 (or compatible), + &xeon;, + and Sun &ultrasparc; based computer + systems. It is based primarily on software from U.C. Berkeley's + CSRG group, with some enhancements from NetBSD, OpenBSD, 386BSD, and + the Free Software Foundation.</para> + + <para>Since our release of &os; 2.0 in late 1994, the performance, + feature set, and stability of &os; has improved dramatically. + <!-- XXX is the rest of this paragraph still true ? --> + The largest change is a revamped virtual memory system with a merged + VM/file buffer cache that not only increases performance, but also + reduces &os;'s memory footprint, making a 5 MB configuration a + more acceptable minimum. Other enhancements include full NIS client + and server support, transaction TCP support, dial-on-demand PPP, + integrated DHCP support, an improved SCSI subsystem, ISDN support, + support for ATM, FDDI, Fast and Gigabit Ethernet (1000 Mbit) + adapters, improved support for the latest Adaptec controllers, and + many thousands of bug fixes.</para> + + <para>In addition to the base distributions, &os; offers a + ported software collection with thousands of commonly + sought-after programs. At the time of this printing, there + were over &os.numports; ports! The list of ports ranges from + http (WWW) servers, to games, languages, editors, and almost + everything in between. The entire Ports Collection requires + approximately &ports.size; of storage, all ports being expressed as + <quote>deltas</quote> to their original sources. This makes + it much easier for us to update ports, and greatly reduces the + disk space demands made by the older 1.0 Ports Collection. To + compile a port, you simply change to the directory of the + program you wish to install, type <command>make install</command>, + and let the system do the rest. The full + original distribution for each port you build is retrieved + dynamically off the CD-ROM or a local FTP site, so you need + only enough disk space to build the ports you want. Almost + every port is also provided as a pre-compiled + <quote>package</quote>, which can be installed with a simple + command (<command>pkg_add</command>) by those who do not wish + to compile their own ports from source. More information on + packages and ports can be found in <xref linkend="ports">.</para> + + <para>All recent &os; versions provide an option in the installer + (either &man.sysinstall.8; or &man.bsdinstall.8;) to install + additional documentation under <filename + class="directory">/usr/local/share/doc/freebsd</filename> during + the initial system setup. Documentation may also be installed at + any later time using packages as described in <xref + linkend="doc-ports-install-package">. + You may view the locally installed + manuals with any HTML capable browser using the following + URLs:</para> + + <variablelist> + <varlistentry> + <term>The FreeBSD Handbook</term> + + <listitem> + <para><ulink type="html" + url="file://localhost/usr/local/share/doc/freebsd/handbook/index.html"><filename>/usr/local/share/doc/freebsd/handbook/index.html</filename></ulink></para> + </listitem> + </varlistentry> + + <varlistentry> + <term>The FreeBSD FAQ</term> + + <listitem> + <para><ulink type="html" + url="file://localhost/usr/local/share/doc/freebsd/faq/index.html"><filename>/usr/local/share/doc/freebsd/faq/index.html</filename></ulink></para> + </listitem> + </varlistentry> + </variablelist> + + <para>You can also view the master (and most frequently updated) + copies at <ulink url="http://www.FreeBSD.org/"></ulink>.</para> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/jails/chapter.sgml b/en_US.ISO8859-1/books/handbook/jails/chapter.sgml new file mode 100644 index 0000000000..1f3b8f9b74 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/jails/chapter.sgml @@ -0,0 +1,970 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<chapter id="jails"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Matteo</firstname> + <surname>Riondato</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>Jails</title> + + <indexterm><primary>jails</primary></indexterm> + + <sect1 id="jails-synopsis"> + <title>Synopsis</title> + + <para>This chapter will provide an explanation of what &os; jails + are and how to use them. Jails, sometimes referred to as an + enhanced replacement of <emphasis>chroot environments</emphasis>, + are a very powerful tool for system administrators, but their basic + usage can also be useful for advanced users.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>What a jail is, and what purpose it may serve in &os; + installations.</para> + </listitem> + + <listitem> + <para>How to build, start, and stop a jail.</para> + </listitem> + + <listitem> + <para>The basics of jail administration, both from inside + and outside the jail.</para> + </listitem> + </itemizedlist> + + <para>Other sources of useful information about jails are:</para> + + <itemizedlist> + <listitem> + <para>The &man.jail.8; manual page. This is the full reference + of the <command>jail</command> utility — the + administrative tool which can be used in &os; to start, stop, + and control &os; jails.</para> + </listitem> + + <listitem> + <para>The mailing lists and their archives. The archives of the + &a.questions; and other mailing lists hosted by the + &a.mailman.lists; already contain a wealth of material for + jails. It should always be engaging to search the archives, + or post a new question to the &a.questions.name; mailing + list.</para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1 id="jails-terms"> + <title>Terms Related to Jails</title> + + <para>To facilitate better understanding of parts of the &os; system + related to jails, their internals and the way they interact with + the rest of &os;, the following terms are used further in this + chapter:</para> + + <variablelist> + <varlistentry> + <term>&man.chroot.8; (command)</term> + <listitem> + <para>Utility, which uses &man.chroot.2; &os; system call to change + the root directory of a process and all its descendants.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&man.chroot.2; (environment)</term> + <listitem> + <para>The environment of processes running in + a <quote>chroot</quote>. This includes resources such as the part + of the file system which is visible, user and group IDs which are + available, network interfaces and other IPC mechanisms, + etc.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&man.jail.8; (command)</term> + <listitem> + <para>The system administration utility which allows launching of + processes within a jail environment.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>host (system, process, user, etc.)</term> + <listitem> + <para>The controlling system of a jail environment. The host system + has access to all the hardware resources available, and can + control processes both outside of and inside a jail environment. + One of the important differences of the host system from a jail is + that the limitations which apply to superuser processes inside a + jail are not enforced for processes of the host system.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>hosted (system, process, user, etc.)</term> + <listitem> + <para>A process, user or other entity, whose access to resources is + restricted by a &os; jail.</para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="jails-intro"> + <title>Introduction</title> + + <para>Since system administration is a difficult and perplexing + task, many powerful tools were developed to make life easier for + the administrator. These tools mostly provide enhancements of some sort + to the way systems are installed, configured and maintained. + Part of the tasks which an administrator is + expected to do is to properly configure the security of a system, + so that it can continue serving its real purpose, without allowing + security violations.</para> + + <para>One of the tools which can be used to enhance the security of + a &os; system are <emphasis>jails</emphasis>. Jails were + introduced in &os; 4.X by &a.phk;, but were greatly improved in + &os; 5.X to make them a powerful and flexible subsystem. Their + development still goes on, enhancing their usefulness, performance, reliability, + and security.</para> + + <sect2 id="jails-what"> + <title>What is a Jail</title> + + <para>BSD-like operating systems have had &man.chroot.2; since the + time of 4.2BSD. The &man.chroot.8; utility can be used to + change the root directory + of a set of processes, creating a safe environment, separate + from the rest of the system. Processes created in the chrooted + environment can not access files or resources outside of it. + For that reason, compromising a service running in a chrooted + environment should not allow the attacker to compromise the + entire system. The &man.chroot.8; utility is good for easy + tasks, which do not require a lot of flexibility or complex and + advanced features. Since the inception of the + chroot concept, however, many ways have been found to escape from a + chrooted environment and, although they have been fixed in + modern versions of the &os; kernel, it was clear that + &man.chroot.2; was not the ideal solution for securing services. + A new subsystem had to be implemented.</para> + + <para>This is one of the main reasons why + <emphasis>jails</emphasis> were developed.</para> + + <para>Jails improve on the concept of the traditional + &man.chroot.2; environment, in several ways. In a traditional + &man.chroot.2; environment, processes are only limited in the + part of the file system they can access. The rest of the system + resources (like the set of system users, the running processes, + or the networking subsystem) are shared by the chrooted + processes and the processes of the host system. Jails expand + this model by virtualizing not only access to the file system, + but also the set of users, the networking subsystem of the &os; + kernel and a few other things. A more complete set of + fine-grained controls available for tuning the access of a + jailed environment is described in <xref + linkend="jails-tuning">.</para> + + <para>A jail is characterized by four elements:</para> + + <itemizedlist> + <listitem> + <para>A directory subtree — the starting point from + which a jail is entered. Once inside the jail, a process + is not permitted to escape outside of this subtree. + Traditional security issues which plagued the original + &man.chroot.2; design will not affect &os; jails.</para> + </listitem> + + <listitem> + <para>A hostname — the hostname which will be used + within the jail. Jails are mainly used for hosting network + services, therefore having a descriptive hostname for each + jail can really help the system administrator.</para> + </listitem> + + <listitem> + <para>An <acronym>IP</acronym> address — this will be + assigned to the jail and cannot be changed in any way during + the jail's life span. The IP address of a jail is usually an alias address + for an existing network interface, but this is not strictly necessary.</para> + </listitem> + + <listitem> + <para>A command — the path name of an executable to run + inside the jail. This is relative to the root directory of + the jail environment, and may vary a lot, depending on the + type of the specific jail environment.</para> + </listitem> + </itemizedlist> + + <para>Apart from these, jails can have their own set of users and + their own <username>root</username> user. Naturally, the powers + of the <username>root</username> user are limited within the + jail environment and, from the point of view of the host system, + the jail <username>root</username> user is not an omnipotent user. + In addition, the <username>root</username> user of a jail is not + allowed to perform critical operations to the system outside of + the associated &man.jail.8; environment. More information + about capabilities and restrictions of the + <username>root</username> user will be discussed in <xref + linkend="jails-tuning"> below.</para> + </sect2> + </sect1> + + <sect1 id="jails-build"> + <title>Creating and Controlling Jails</title> + + <para>Some administrators divide jails into the following two types: + <quote>complete</quote> jails, which resemble a real &os; system, + and <quote>service</quote> jails, dedicated to one application or + service, possibly running with privileges. This is only a + conceptual division and the process of building a jail is not + affected by it. The &man.jail.8; manual page is quite clear about + the procedure for building a jail:</para> + + <screen>&prompt.root; <userinput>setenv D <replaceable>/here/is/the/jail</replaceable></userinput> +&prompt.root; <userinput>mkdir -p $D</userinput> <co id="jailpath"> +&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make buildworld</userinput> <co id="jailbuildworld"> +&prompt.root; <userinput>make installworld DESTDIR=$D</userinput> <co id="jailinstallworld"> +&prompt.root; <userinput>make distribution DESTDIR=$D</userinput> <co id="jaildistrib"> +&prompt.root; <userinput>mount -t devfs devfs $D/dev</userinput> <co id="jaildevfs"></screen> + + <calloutlist> + <callout arearefs="jailpath"> + <para>Selecting a location for a jail is the best starting point. + This is where the jail will physically reside within the file system of the jail's host. + A good choice can be <filename + class="directory">/usr/jail/<replaceable>jailname</replaceable></filename>, + where <replaceable>jailname</replaceable> is the hostname + identifying the jail. The <filename + class="directory">/usr/</filename> file system usually has + enough space for the jail file system, which for <quote>complete</quote> jails is, essentially, + a replication of every file present in a default installation + of the &os; base system.</para> + </callout> + + <callout arearefs="jailbuildworld"> + <para>If you have already rebuilt your userland using + <command>make world</command> or <command>make buildworld</command>, + you can skip this step and install your existing userland into the + new jail.</para> + </callout> + + <callout arearefs="jailinstallworld"> + <para>This command will populate the directory subtree chosen + as jail's physical location on the file system with the + necessary binaries, libraries, manual pages and so on.</para> + </callout> + + <callout arearefs="jaildistrib"> + <para>The <maketarget>distribution</maketarget> target for + <application>make</application> installs every needed + configuration file. In simple words, it installs every installable file of + <filename class="directory">/usr/src/etc/</filename> to the + <filename class="directory">/etc</filename> directory of the jail + environment: + <filename class="directory">$D/etc/</filename>.</para> + </callout> + + <callout arearefs="jaildevfs"> + <para>Mounting the &man.devfs.8; file system inside a jail is + not required. On the other hand, any, or almost any + application requires access to at least one device, depending + on the purpose of the given application. It is very important + to control access to devices from inside a jail, as improper + settings could permit an attacker to do nasty things in the + jail. Control over &man.devfs.8; is managed through rulesets + which are described in the &man.devfs.8; and + &man.devfs.conf.5; manual pages.</para> + </callout> + </calloutlist> + + <para>Once a jail is installed, it can be started by using the + &man.jail.8; utility. The &man.jail.8; utility takes four + mandatory arguments which are described in the <xref + linkend="jails-what">. Other arguments may be + specified too, e.g., to run the jailed process with the credentials of a specific + user. The <option><replaceable>command</replaceable></option> argument depends on + the type of the jail; for a <emphasis>virtual system</emphasis>, + <filename>/etc/rc</filename> is a good choice, since it will + replicate the startup sequence of a real &os; system. For a + <emphasis>service</emphasis> jail, it depends on the service or + application that will run within the jail.</para> + + <para>Jails are often started at boot time and the &os; + <filename>rc</filename> mechanism provides an easy way to do + this.</para> + + <procedure> + <step> + <para>A list of the jails which are enabled to start at boot + time should be added to the &man.rc.conf.5; file:</para> + + <programlisting>jail_enable="YES" # Set to NO to disable starting of any jails +jail_list="<replaceable>www</replaceable>" # Space separated list of names of jails</programlisting> + + <note> + <para>Jail names in <varname>jail_list</varname> should + contain alphanumeric characters only.</para> + </note> + </step> + + <step> + <para>For each jail listed in <varname>jail_list</varname>, a + group of &man.rc.conf.5; settings, which describe the + particular jail, should be added:</para> + + <programlisting>jail_<replaceable>www</replaceable>_rootdir="/usr/jail/www" # jail's root directory +jail_<replaceable>www</replaceable>_hostname="<replaceable>www</replaceable>.example.org" # jail's hostname +jail_<replaceable>www</replaceable>_ip="192.168.0.10" # jail's IP address +jail_<replaceable>www</replaceable>_devfs_enable="YES" # mount devfs in the jail +jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</replaceable>" # devfs ruleset to apply to jail</programlisting> + + <para>The default startup of jails configured in + &man.rc.conf.5;, will run the <filename>/etc/rc</filename> + script of the jail, which assumes the jail is a complete + virtual system. For service jails, the default startup + command of the jail should be changed, by setting the + <varname>jail_<replaceable>jailname</replaceable>_exec_start</varname> + option appropriately.</para> + + <note> + <para>For a full list of available options, please see the + &man.rc.conf.5; manual page.</para> + </note> + </step> + </procedure> + + <para>The <filename>/etc/rc.d/jail</filename> script can be used to + start or stop a jail by hand, if an entry for it exists in + <filename>rc.conf</filename>:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/jail start <replaceable>www</replaceable></userinput> +&prompt.root; <userinput>/etc/rc.d/jail stop <replaceable>www</replaceable></userinput></screen> + + <para>A clean way to shut down a &man.jail.8; is not available at + the moment. This is because commands normally used to accomplish + a clean system shutdown cannot be used inside a jail. The best + way to shut down a jail is to run the following command from + within the jail itself or using the &man.jexec.8; utility from + outside the jail:</para> + + <screen>&prompt.root; <userinput>sh /etc/rc.shutdown</userinput></screen> + + <para>More information about this can be found in the &man.jail.8; + manual page.</para> + </sect1> + + <sect1 id="jails-tuning"> + <title>Fine Tuning and Administration</title> + + <para>There are several options which can be set for any jail, and + various ways of combining a host &os; system with jails, to produce + higher level applications. This section presents:</para> + + <itemizedlist> + <listitem> + <para>Some of the options available for tuning the behavior and + security restrictions implemented by a jail + installation.</para> + </listitem> + + <listitem> + <para>Some of the high-level applications for jail management, + which are available through the &os; Ports Collection, and can + be used to implement overall jail-based solutions.</para> + </itemizedlist> + + <sect2 id="jails-tuning-utilities"> + <title>System Tools for Jail Tuning in &os;</title> + + <para>Fine tuning of a jail's configuration is mostly done by + setting &man.sysctl.8; variables. A special subtree of sysctl + exists as a basis for organizing all the relevant options: the + <varname>security.jail.*</varname> hierarchy of &os; kernel + options. Here is a list of the main jail-related sysctls, + complete with their default value. Names should be + self-explanatory, but for more information about them, please + refer to the &man.jail.8; and &man.sysctl.8; manual + pages.</para> + + <itemizedlist> + <listitem> + <para><varname>security.jail.set_hostname_allowed: + 1</varname></para> + </listitem> + + <listitem> + <para><varname>security.jail.socket_unixiproute_only: + 1</varname></para> + </listitem> + + <listitem> + <para><varname>security.jail.sysvipc_allowed: + 0</varname></para> + </listitem> + + <listitem> + <para><varname>security.jail.enforce_statfs: + 2</varname></para> + </listitem> + + <listitem> + <para><varname>security.jail.allow_raw_sockets: + 0</varname></para> + </listitem> + + <listitem> + <para><varname>security.jail.chflags_allowed: + 0</varname></para> + </listitem> + + <listitem> + <para><varname>security.jail.jailed: 0</varname></para> + </listitem> + </itemizedlist> + + <para>These variables can be used by the system administrator of + the <emphasis>host system</emphasis> to add or remove some of + the limitations imposed by default on the + <username>root</username> user. Note that there are some + limitations which cannot be removed. The + <username>root</username> user is not allowed to mount or + unmount file systems from within a &man.jail.8;. The + <username>root</username> inside a jail may not load or unload + &man.devfs.8; rulesets, set firewall rules, or do many other + administrative tasks which require modifications of in-kernel + data, such as setting the <varname>securelevel</varname> of the + kernel.</para> + + <para>The base system of &os; contains a basic set of tools for + viewing information about the active jails, and attaching to a + jail to run administrative commands. The &man.jls.8; and + &man.jexec.8; commands are part of the base &os; system, and can be used + to perform the following simple tasks:</para> + + <itemizedlist> + <listitem> + <para>Print a list of active jails and their corresponding + jail identifier (<acronym>JID</acronym>), + <acronym>IP</acronym> address, hostname and path.</para> + </listitem> + + <listitem> + <para>Attach to a running jail, from its host system, and run + a command inside the jail or perform administrative tasks inside the + jail itself. This is especially useful when the + <username>root</username> user wants to cleanly shut down a + jail. The &man.jexec.8; utility can also be used to start a + shell in a jail to do administration in it; for + example:</para> + + <screen>&prompt.root; <userinput>jexec <replaceable>1</replaceable> tcsh</userinput></screen> + </listitem> + </itemizedlist> + </sect2> + + <sect2 id="jails-tuning-admintools"> + <title>High-Level Administrative Tools in the &os; Ports + Collection</title> + + <para>Among the many third-party utilities for jail administration, + one of the most complete and useful is <filename + role="package">sysutils/jailutils</filename>. It is a set of + small applications that contribute to &man.jail.8; management. + Please refer to its web page for more information.</para> + </sect2> + </sect1> + + <sect1 id="jails-application"> + <title>Application of Jails</title> + + <sect2 id="jails-service-jails"> + <sect2info> + <authorgroup> + <author> + <firstname>Daniel</firstname> + <surname>Gerzo</surname> + <contrib>Contributed by </contrib> + <!-- 15. May 2007 --> + </author> + </authorgroup> + </sect2info> + + <title>Service Jails</title> + + <para>This section is based upon an idea originally presented by + &a.simon; at <ulink + url="http://simon.nitro.dk/service-jails.html"></ulink>, and an + updated article written by Ken Tom + <email>locals@gmail.com</email>. This section illustrates how + to set up a &os; system that adds an additional layer of + security, using the &man.jail.8; feature. It is also assumed + that the given system is at least running RELENG_6_0 and the + information provided earlier in this chapter has been well + understood.</para> + + <sect3 id="jails-service-jails-design"> + <title>Design</title> + + <para>One of the major problems with jails is the management of + their upgrade process. This tends to be a problem because + every jail has to be rebuilt from scratch whenever it is + updated. This is usually not a problem for a single jail, + since the update process is fairly simple, but can be quite + time consuming and tedious if a lot of jails are + created.</para> + + <warning> + <para>This setup requires advanced experience with &os; and + usage of its features. If the presented steps below look + too complicated, it is advised to take a look at a simpler + system such as <filename + role="package">sysutils/ezjail</filename>, which provides + an easier method of administering &os; jails and is not as + sophisticated as this setup.</para> + </warning> + + <para>This idea has been presented to resolve such issues by + sharing as much as is possible between jails, in a safe way + — using read-only &man.mount.nullfs.8; mounts, so that + updating will be simpler, and putting single services into + individual jails will become more attractive. Additionally, + it provides a simple way to add or remove jails as well as a + way to upgrade them.</para> + + <note> + <para>Examples of services in this context are: an + <acronym>HTTP</acronym> server, a <acronym>DNS</acronym> + server, a <acronym>SMTP</acronym> server, and so forth.</para> + </note> + + <para>The goals of the setup described in this section + are:</para> + + <itemizedlist> + <listitem> + <para>Create a simple and easy to understand jail structure. + This implies <emphasis>not</emphasis> having to run a full + installworld on each and every jail.</para> + </listitem> + <listitem> + <para>Make it easy to add new jails or remove existing + ones.</para> + </listitem> + <listitem> + <para>Make it easy to update or upgrade existing + jails.</para> + </listitem> + <listitem> + <para>Make it possible to run a customized &os; + branch.</para> + </listitem> + <listitem> + <para>Be paranoid about security, reducing as much as + possible the possibility of compromise.</para> + </listitem> + <listitem> + <para>Save space and inodes, as much as possible.</para> + </listitem> + </itemizedlist> + + <para>As it has been already mentioned, this design relies + heavily on having a single master template which is read-only + (known as <application>nullfs</application>) mounted into each + jail and one read-write device per jail. A device can be a + separate physical disc, a partition, or a vnode backed + &man.md.4; device. In this example, we will use read-write + <application>nullfs</application> mounts.</para> + + <para>The file system layout is described in the following + list:</para> + + <itemizedlist> + <listitem> + <para>Each jail will be mounted under the <filename + class="directory">/home/j</filename> directory.</para> + </listitem> + <listitem> + <para><filename class="directory">/home/j/mroot</filename> is + the template for each jail and the read-only partition for + all of the jails.</para> + </listitem> + <listitem> + <para>A blank directory will be created for each jail under + the <filename class="directory">/home/j</filename> + directory.</para> + </listitem> + <listitem> + <para>Each jail will have a <filename + class="directory">/s</filename> directory, that will be + linked to the read-write portion of the system.</para> + </listitem> + <listitem> + <para>Each jail shall have its own read-write system that is + based upon <filename + class="directory">/home/j/skel</filename>.</para> + </listitem> + <listitem> + <para>Each jailspace (read-write portion of each jail) shall + be created in <filename + class="directory">/home/js</filename>.</para> + </listitem> + </itemizedlist> + + <note> + <para>This assumes that the jails are based under the + <filename class="directory">/home</filename> partition. This + can, of course, be changed to anything else, but this change + will have to be reflected in each of the examples + below.</para> + </note> + <!-- Insert an image or drawing here to illustrate the example. --> + </sect3> + + <sect3 id="jails-service-jails-template"> + <title>Creating the Template</title> + + <para>This section will describe the steps needed to create the + master template that will be the read-only portion for the + jails to use.</para> + + <para>It is always a good idea to update the &os; system to the + latest -RELEASE branch. Check the corresponding Handbook + <ulink url="&url.books.handbook;/makeworld.html">Chapter</ulink> + to accomplish this task. In the case the update is not + feasible, the buildworld will be required in order to be able + to proceed. Additionally, the <filename + role="package">sysutils/cpdup</filename> package will be + required. We will use the &man.portsnap.8; utility to + download the &os; Ports Collection. The Handbook <ulink + url="&url.books.handbook;/portsnap.html">Portsnap Chapter</ulink> + is always good reading for newcomers.</para> + + <procedure> + <step> + <para>First, create a directory structure for the read-only + file system which will contain the &os; binaries for our + jails, then change directory to the &os; source tree and + install the read-only file system to the jail + template:</para> + + <screen>&prompt.root; <userinput>mkdir /home/j /home/j/mroot</userinput> +&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make installworld DESTDIR=/home/j/mroot</userinput></screen> + </step> + <step> + <para>Next, prepare a &os; Ports Collection for the jails as + well as a &os; source tree, which is required for + <application>mergemaster</application>:</para> + + <screen>&prompt.root; <userinput>cd /home/j/mroot</userinput> +&prompt.root; <userinput>mkdir usr/ports</userinput> +&prompt.root; <userinput>portsnap -p /home/j/mroot/usr/ports fetch extract</userinput> +&prompt.root; <userinput>cpdup /usr/src /home/j/mroot/usr/src</userinput></screen> + </step> + <step> + <para>Create a skeleton for the read-write portion of the + system:</para> + + <screen>&prompt.root; <userinput>mkdir /home/j/skel /home/j/skel/home /home/j/skel/usr-X11R6 /home/j/skel/distfiles</userinput> +&prompt.root; <userinput>mv etc /home/j/skel</userinput> +&prompt.root; <userinput>mv usr/local /home/j/skel/usr-local</userinput> +&prompt.root; <userinput>mv tmp /home/j/skel</userinput> +&prompt.root; <userinput>mv var /home/j/skel</userinput> +&prompt.root; <userinput>mv root /home/j/skel</userinput></screen> + </step> + <step> + <para>Use <application>mergemaster</application> to install + missing configuration files. Then get rid of the extra + directories that <application>mergemaster</application> + creates:</para> + + <screen>&prompt.root; <userinput>mergemaster -t /home/j/skel/var/tmp/temproot -D /home/j/skel -i</userinput> +&prompt.root; <userinput>cd /home/j/skel</userinput> +&prompt.root; <userinput>rm -R bin boot lib libexec mnt proc rescue sbin sys usr dev</userinput></screen> + </step> + <step> + <para>Now, symlink the read-write file system to the + read-only file system. Please make sure that the symlinks + are created in the correct <filename + class="directory">s/</filename> locations. Real + directories or the creation of directories in the wrong + locations will cause the installation to fail.</para> + + <screen>&prompt.root; <userinput>cd /home/j/mroot</userinput> +&prompt.root; <userinput>mkdir s</userinput> +&prompt.root; <userinput>ln -s s/etc etc</userinput> +&prompt.root; <userinput>ln -s s/home home</userinput> +&prompt.root; <userinput>ln -s s/root root</userinput> +&prompt.root; <userinput>ln -s ../s/usr-local usr/local</userinput> +&prompt.root; <userinput>ln -s ../s/usr-X11R6 usr/X11R6</userinput> +&prompt.root; <userinput>ln -s ../../s/distfiles usr/ports/distfiles</userinput> +&prompt.root; <userinput>ln -s s/tmp tmp</userinput> +&prompt.root; <userinput>ln -s s/var var</userinput></screen> + </step> + <step> + <para>As a last step, create a generic + <filename>/home/j/skel/etc/make.conf</filename> with its + contents as shown below:</para> + + <programlisting>WRKDIRPREFIX?= /s/portbuild</programlisting> + + + <para>Having <literal>WRKDIRPREFIX</literal> set up this + way will make it possible to compile &os; ports inside + each jail. Remember that the ports directory is part of + the read-only system. The custom path for + <literal>WRKDIRPREFIX</literal> allows builds to be done + in the read-write portion of every jail.</para> + </step> + </procedure> + </sect3> + + <sect3 id="jails-service-jails-creating"> + <title>Creating Jails</title> + + <para>Now that we have a complete &os; jail template, we can + setup and configure the jails in + <filename>/etc/rc.conf</filename>. This example demonstrates + the creation of 3 jails: <quote>NS</quote>, + <quote>MAIL</quote> and <quote>WWW</quote>.</para> + + <procedure> + <step> + <para>Put the following lines into the + <filename>/etc/fstab</filename> file, so that the + read-only template for the jails and the read-write space + will be available in the respective jails:</para> + + <programlisting>/home/j/mroot /home/j/ns nullfs ro 0 0 +/home/j/mroot /home/j/mail nullfs ro 0 0 +/home/j/mroot /home/j/www nullfs ro 0 0 +/home/js/ns /home/j/ns/s nullfs rw 0 0 +/home/js/mail /home/j/mail/s nullfs rw 0 0 +/home/js/www /home/j/www/s nullfs rw 0 0</programlisting> + + <note> + <para>Partitions marked with a 0 pass number are not + checked by &man.fsck.8; during boot, and partitions + marked with a 0 dump number are not backed up by + &man.dump.8;. We do not want + <application>fsck</application> to check + <application>nullfs</application> mounts or + <application>dump</application> to back up the read-only + nullfs mounts of the jails. This is why they are marked + with <quote>0 0</quote> in the last two columns of + each <filename>fstab</filename> entry above.</para> + </note> + </step> + <step> + <para>Configure the jails in + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>jail_enable="YES" +jail_set_hostname_allow="NO" +jail_list="ns mail www" +jail_ns_hostname="ns.example.org" +jail_ns_ip="192.168.3.17" +jail_ns_rootdir="/usr/home/j/ns" +jail_ns_devfs_enable="YES" +jail_mail_hostname="mail.example.org" +jail_mail_ip="192.168.3.18" +jail_mail_rootdir="/usr/home/j/mail" +jail_mail_devfs_enable="YES" +jail_www_hostname="www.example.org" +jail_www_ip="62.123.43.14" +jail_www_rootdir="/usr/home/j/www" +jail_www_devfs_enable="YES"</programlisting> + + <warning> + <para>The reason why the + <varname>jail_<replaceable>name</replaceable>_rootdir</varname> + variable is set to <filename + class="directory">/usr/home</filename> instead of + <filename class="directory">/home</filename> is that the + physical path of the <filename + class="directory">/home</filename> directory on a + default &os; installation is <filename + class="directory">/usr/home</filename>. The + <varname>jail_<replaceable>name</replaceable>_rootdir</varname> + variable must <emphasis>not</emphasis> be set to a path + which includes a symbolic link, otherwise the jails will + refuse to start. Use the &man.realpath.1; utility to + determine a value which should be set to this variable. + Please see the &os;-SA-07:01.jail Security Advisory for + more information.</para> + </warning> + </step> + <step> + <para>Create the required mount points for the read-only + file system of each jail:</para> + + <screen>&prompt.root; <userinput>mkdir /home/j/ns /home/j/mail /home/j/www</userinput></screen> + </step> + <step> + <para>Install the read-write template into each jail. Note + the use of <filename + role="package">sysutils/cpdup</filename>, which helps to + ensure that a correct copy is done of each + directory:</para> + <!-- keramida: Why is cpdup required here? Doesn't cpio(1) + already include adequate functionality for performing this + job *and* have the advantage of being part of the base + system of FreeBSD? --> + + <screen>&prompt.root; <userinput>mkdir /home/js</userinput> +&prompt.root; <userinput>cpdup /home/j/skel /home/js/ns</userinput> +&prompt.root; <userinput>cpdup /home/j/skel /home/js/mail</userinput> +&prompt.root; <userinput>cpdup /home/j/skel /home/js/www</userinput></screen> + </step> + <step> + <para>In this phase, the jails are built and prepared to + run. First, mount the required file systems for each + jail, and then start them using the + <filename>/etc/rc.d/jail</filename> script:</para> + + <screen>&prompt.root; <userinput>mount -a</userinput> +&prompt.root; <userinput>/etc/rc.d/jail start</userinput></screen> + </step> + </procedure> + + <para>The jails should be running now. To check if they have + started correctly, use the &man.jls.8; command. Its output + should be similar to the following:</para> + + <screen>&prompt.root; <userinput>jls</userinput> + JID IP Address Hostname Path + 3 192.168.3.17 ns.example.org /home/j/ns + 2 192.168.3.18 mail.example.org /home/j/mail + 1 62.123.43.14 www.example.org /home/j/www</screen> + + <para>At this point, it should be possible to log onto each + jail, add new users or configure daemons. The + <literal>JID</literal> column indicates the jail + identification number of each running jail. Use the + following command in order to perform administrative tasks in + the jail whose <literal>JID</literal> is 3:</para> + + <screen>&prompt.root; <userinput>jexec 3 tcsh</userinput></screen> + </sect3> + + <sect3 id="jails-service-jails-upgrading"> + <title>Upgrading</title> + + <para>In time, there will be a need to upgrade the system to a + newer version of &os;, either because of a security issue, or + because new features have been implemented which are useful + for the existing jails. The design of this setup provides an + easy way to upgrade existing jails. Additionally, it + minimizes their downtime, as the jails will be brought down + only in the very last minute. Also, it provides a way to roll + back to the older versions should any problems occur.</para> + + <procedure> + <step> + <para>The first step is to upgrade the host system in the + usual manner. Then create a new temporary read-only + template in <filename + class="directory">/home/j/mroot2</filename>.</para> + + <screen>&prompt.root; <userinput>mkdir /home/j/mroot2</userinput> +&prompt.root; <userinput>cd /usr/src</userinput> +&prompt.root; <userinput>make installworld DESTDIR=/home/j/mroot2</userinput> +&prompt.root; <userinput>cd /home/j/mroot2</userinput> +&prompt.root; <userinput>cpdup /usr/src usr/src</userinput> +&prompt.root; <userinput>mkdir s</userinput></screen> + + <para>The <maketarget>installworld</maketarget> run creates + a few unnecessary directories, which should be + removed:</para> + + <screen>&prompt.root; <userinput>chflags -R 0 var</userinput> +&prompt.root; <userinput>rm -R etc var root usr/local tmp</userinput></screen> + </step> + <step> + <para>Recreate the read-write symlinks for the master file + system:</para> + + <screen>&prompt.root; <userinput>ln -s s/etc etc</userinput> +&prompt.root; <userinput>ln -s s/root root</userinput> +&prompt.root; <userinput>ln -s s/home home</userinput> +&prompt.root; <userinput>ln -s ../s/usr-local usr/local</userinput> +&prompt.root; <userinput>ln -s ../s/usr-X11R6 usr/X11R6</userinput> +&prompt.root; <userinput>ln -s s/tmp tmp</userinput> +&prompt.root; <userinput>ln -s s/var var</userinput></screen> + </step> + <step> + <para>The right time to stop the jails is now:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/jail stop</userinput></screen> + </step> + <step> + <para>Unmount the original file systems:</para> + <!-- keramida: Shouldn't we suggest a short script-based + loop here, instead of tediously copying the same commands + multiple times? --> + + <screen>&prompt.root; <userinput>umount /home/j/ns/s</userinput> +&prompt.root; <userinput>umount /home/j/ns</userinput> +&prompt.root; <userinput>umount /home/j/mail/s</userinput> +&prompt.root; <userinput>umount /home/j/mail</userinput> +&prompt.root; <userinput>umount /home/j/www/s</userinput> +&prompt.root; <userinput>umount /home/j/www</userinput></screen> + + <note> + <para>The read-write systems are attached to the read-only + system (<filename class="directory">/s</filename>) and + must be unmounted first.</para> + </note> + </step> + <step> + <para>Move the old read-only file system and replace it with + the new one. This will serve as a backup and archive of the + old read-only file system should something go wrong. The + naming convention used here corresponds to when a new + read-only file system has been created. Move the original + &os; Ports Collection over to the new file system to save + some space and inodes:</para> + + <screen>&prompt.root; <userinput>cd /home/j</userinput> +&prompt.root; <userinput>mv mroot mroot.20060601</userinput> +&prompt.root; <userinput>mv mroot2 mroot</userinput> +&prompt.root; <userinput>mv mroot.20060601/usr/ports mroot/usr</userinput></screen> + </step> + <step> + <para>At this point the new read-only template is ready, so + the only remaining task is to remount the file systems and + start the jails:</para> + + <screen>&prompt.root; <userinput>mount -a</userinput> +&prompt.root; <userinput>/etc/rc.d/jail start</userinput></screen> + </step> + </procedure> + + <para>Use &man.jls.8; to check if the jails started correctly. + Do not forget to run mergemaster in each jail. The + configuration files will need to be updated as well as the + rc.d scripts.</para> + </sect3> + </sect2> + </sect1> +</chapter> diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/Makefile b/en_US.ISO8859-1/books/handbook/kernelconfig/Makefile new file mode 100644 index 0000000000..95839d340a --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= kernelconfig/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml new file mode 100644 index 0000000000..be0b450363 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.sgml @@ -0,0 +1,1559 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="kernelconfig"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Mock</surname> + <contrib>Updated and restructured by </contrib> + <!-- Mar 2000 --> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Jake</firstname> + <surname>Hamby</surname> + <contrib>Originally contributed by </contrib> + <!-- 6 Oct 1995 --> + </author> + </authorgroup> + </chapterinfo> + + <title>Configuring the FreeBSD Kernel</title> + + <sect1 id="kernelconfig-synopsis"> + <title>Synopsis</title> + + <indexterm> + <primary>kernel</primary> + <secondary>building a custom kernel</secondary> + </indexterm> + + <para>The kernel is the core of the &os; operating system. It is + responsible for managing memory, enforcing security controls, + networking, disk access, and much more. While more and more of &os; + becomes dynamically configurable it is still occasionally necessary to + reconfigure and recompile your kernel.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>Why you might need to build a custom kernel.</para> + </listitem> + + <listitem> + <para>How to write a kernel configuration file, or alter an existing + configuration file.</para> + </listitem> + + <listitem> + <para>How to use the kernel configuration file to create and build a + new kernel.</para> + </listitem> + + <listitem> + <para>How to install the new kernel.</para> + </listitem> + + <listitem> + <para>How to troubleshoot if things go wrong.</para> + </listitem> + </itemizedlist> + + <para>All of the commands listed within this chapter by way of example + should be executed as <username>root</username> in order to + succeed.</para> + </sect1> + + <sect1 id="kernelconfig-custom-kernel"> + <title>Why Build a Custom Kernel?</title> + + <para>Traditionally, &os; has had what is called a + <quote>monolithic</quote> kernel. This means that the kernel was one + large program, supported a fixed list of devices, and if you wanted to + change the kernel's behavior then you had to compile a new kernel, and + then reboot your computer with the new kernel.</para> + + <para>Today, &os; is rapidly moving to a model where much of the + kernel's functionality is contained in modules which can be + dynamically loaded and unloaded from the kernel as necessary. + This allows the kernel to adapt to new hardware suddenly + becoming available (such as PCMCIA cards in a laptop), or for + new functionality to be brought into the kernel that was not + necessary when the kernel was originally compiled. This is + known as a modular kernel.</para> + + <para>Despite this, it is still necessary to carry out some static kernel + configuration. In some cases this is because the functionality is so + tied to the kernel that it can not be made dynamically loadable. In + others it may simply be because no one has yet taken the time to write a + dynamic loadable kernel module for that functionality.</para> + + <para>Building a custom kernel is one of the most important rites of + passage for advanced BSD users. This process, while + time consuming, will provide many benefits to your &os; system. + Unlike the <filename>GENERIC</filename> kernel, which must support a + wide range of hardware, a custom kernel only contains support for + <emphasis>your</emphasis> PC's hardware. This has a number of + benefits, such as:</para> + + <itemizedlist> + <listitem> + <para>Faster boot time. Since the kernel will only probe the + hardware you have on your system, the time it takes your system to + boot can decrease dramatically.</para> + </listitem> + + <listitem> + <para>Lower memory usage. A custom kernel often uses less memory + than the <filename>GENERIC</filename> kernel by omitting unused + features and device drivers. This is important because the kernel + code remains resident in physical memory at all times, preventing + that memory from being used by applications. + For this reason, a custom kernel is especially useful + on a system with a small amount of RAM.</para> + </listitem> + + <listitem> + <para>Additional hardware support. A custom kernel allows you to + add in support for devices which are not + present in the <filename>GENERIC</filename> kernel, such as + sound cards.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="kernelconfig-devices"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Finding the System Hardware</title> + + <para>Before venturing into kernel configuration, it would be wise + to get an inventory of the machine's hardware. In cases where + &os; is not the primary operating system, the inventory list may + easily be created by viewing the current operating system + configuration. For example, µsoft;'s + <application>Device Manager</application> normally contains + important information about installed devices. The + <application>Device Manager</application> is located in the + control panel.</para> + + <note> + <para>Some versions of µsoft.windows; have a + <application>System</application> icon which will display a + screen where <application>Device Manager</application> may + be accessed.</para> + </note> + + <para>If another operating system does not exist on the machine, + the administrator must find this information out manually. One + method is using the &man.dmesg.8; utility and the &man.man.1; + commands. Most device drivers on &os; have a manual page, listing + supported hardware, and during the boot probe, found hardware + will be listed. For example, the following lines indicate that + the <devicename>psm</devicename> driver found a mouse:</para> + + <programlisting>psm0: <PS/2 Mouse> irq 12 on atkbdc0 +psm0: [GIANT-LOCKED] +psm0: [ITHREAD] +psm0: model Generic PS/2 mouse, device ID 0</programlisting> + + <para>This driver will need to be included in the custom kernel + configuration file or loaded using &man.loader.conf.5;.</para> + + <para>On occasion, the data from <command>dmesg</command> will + only show system messages instead of the boot probe output. In + these situations, the output may be obtained by viewing the + <filename>/var/run/dmesg.boot</filename> file.</para> + + <para>Another method of finding hardware is by using the + &man.pciconf.8; utility which provides more verbose output. + For example:</para> + + <programlisting>ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 + vendor = 'Atheros Communications Inc.' + device = 'AR5212 Atheros AR5212 802.11abg wireless' + class = network + subclass = ethernet</programlisting> + + <para>This bit of output, obtained using + <command>pciconf <option>-lv</option></command> shows that the + <devicename>ath</devicename> driver located a wireless Ethernet + device. Using + <command>man <replaceable>ath</replaceable></command> will return + the &man.ath.4; manual page.</para> + + <para>The <option>-k</option> flag, when passed to &man.man.1; + can also be used to provide useful information. From the + above, one can issue:</para> + + <screen>&prompt.root; man -k <replaceable>Atheros</replaceable></screen> + + <para>To get a list of manual pages which contain that particular + word:</para> + + <programlisting>ath(4) - Atheros IEEE 802.11 wireless network driver +ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting> + + <para>Armed with a hardware inventory list, the process of building + a custom kernel should appear less daunting.</para> + </sect1> + + <sect1 id="kernelconfig-modules"> + <title>Kernel Drivers, Subsystems, and Modules</title> + <indexterm> + <primary>kernel</primary> + <secondary>drivers / modules / subsystems</secondary> + </indexterm> + + <para>Before building a custom kernel, consider the reasons for + doing so. If there is a need for specific hardware support, + it may already exist as a module.</para> + + <para>Kernel modules exist in the + <filename class="directory">/boot/kernel</filename> directory + and may be dynamically loaded into the running kernel using + &man.kldload.8;. Most, if not all kernel drivers have a + specific module and manual page. For example, the last section + noted the <devicename>ath</devicename> wireless Ethernet driver. + This device has the following information in its manual + page:</para> + + <programlisting>Alternatively, to load the driver as a module at boot time, place the +following line in &man.loader.conf.5;: + + if_ath_load="YES"</programlisting> + + <para>As instructed, adding the <literal>if_ath_load="YES"</literal> + line to the <filename>/boot/loader.conf</filename> file will + enable loading this module dynamically at boot time.</para> + + <para>In some cases; however, there is no associated module. This + is mostly true for certain subsystems and very important drivers, + for instance, the fast file system (<acronym>FFS</acronym>) is a + required option in the kernel. As is network support (INET). + Unfortunately the only way to tell if a driver is required is to + check for the module itself.</para> + + <warning> + <para>It is easy to remove support for a + device or option and end up with a broken kernel. For example, if + the &man.ata.4; driver is removed from the kernel configuration + file, a system using <acronym>ATA</acronym> disk drivers may + not boot without the module added to + <filename>loader.conf</filename>. When in doubt, check for + the module and then just leave support in the kernel.</para> + </warning> + </sect1> + + <sect1 id="kernelconfig-building"> + <title>Building and Installing a Custom Kernel</title> + <indexterm> + <primary>kernel</primary> + <secondary>building / installing</secondary> + </indexterm> + + <note> + <para>It is required to have the full &os; source tree installed + to build the kernel.</para> + </note> + + <para>First, let us take a quick tour of the kernel build directory. + All directories mentioned will be relative to the main + <filename>/usr/src/sys</filename> directory, which is also + accessible through the path name <filename>/sys</filename>. There are a + number of subdirectories here representing different parts of the + kernel, but the most important for our purposes are + <filename><replaceable>arch</replaceable>/conf</filename>, where you + will edit your custom kernel configuration, and + <filename>compile</filename>, which is the staging area where your + kernel will be built. <replaceable>arch</replaceable> represents + one of <filename>i386</filename>, + <filename>amd64</filename>, <filename>ia64</filename>, + <filename>powerpc</filename>, <filename>sparc64</filename>, or + <filename>pc98</filename> (an alternative development branch of PC + hardware, popular in Japan). Everything inside a particular + architecture's directory deals with that architecture only; the rest + of the code is machine independent code common to all platforms to which + &os; could potentially be ported. Notice the logical organization of the + directory structure, with each supported device, file system, and + option in its own subdirectory.</para> + + <para>The examples in this chapter assume that you are using the i386 + architecture. If your system has a different architecture you need + to change the path names accordingly.</para> + + <note> + <para>If the directory <filename>/usr/src/</filename> does not + exist on your system (or if it is empty), then the sources have + not been installed. The easiest way to install the full source + tree is to run <command>sysinstall</command> as + <username>root</username>, and then choosing + <guimenuitem>Configure</guimenuitem>, then + <guimenuitem>Distributions</guimenuitem>, then + <guimenuitem>src</guimenuitem>, and finally + <guimenuitem>All</guimenuitem>. If it does not exist, you should + also create a symlink to <filename>/usr/src/sys/</filename>:</para> + + <screen>&prompt.root; <userinput>ln -s /usr/src/sys /sys</userinput></screen> + </note> + + <para>Next, change to the + <filename><replaceable>arch</replaceable>/conf</filename> directory + and copy the <filename>GENERIC</filename> configuration file to the + name you want to give your kernel. For example:</para> + + <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput> +&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen> + + <para>Traditionally, this name is in all capital letters and, if you + are maintaining multiple &os; machines with different hardware, + it is a good idea to name it after your machine's hostname. We will + call it <filename><replaceable>MYKERNEL</replaceable></filename> for the + purpose of this example.</para> + + <tip> + <para>Storing your kernel configuration file directly under + <filename>/usr/src</filename> can be a bad idea. If you are + experiencing problems it can be tempting to just delete + <filename>/usr/src</filename> and start again. After doing this, + it usually only takes a few seconds for + you to realize that you have deleted your custom kernel + configuration file. Also, do not edit <filename>GENERIC</filename> + directly, as it may get overwritten the next time you + <link linkend="updating-upgrading">update your source tree</link>, and + your kernel modifications will be lost.</para> + + <para>You might want to keep your kernel configuration file + elsewhere, and then create a symbolic link to the file in + the <filename><replaceable>i386</replaceable></filename> + directory.</para> + + <para>For example:</para> + + <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf</userinput> +&prompt.root; <userinput>mkdir /root/kernels</userinput> +&prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput> +&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen> + </tip> + + <para>Now, edit <filename><replaceable>MYKERNEL</replaceable></filename> + with your favorite text editor. If you are just starting out, the only + editor available will probably be <application>vi</application>, which + is too complex to explain here, but is covered well in many books in + the <link linkend="bibliography">bibliography</link>. However, &os; does + offer an easier editor called <application>ee</application> which, if + you are a beginner, should be your editor of choice. Feel free to + change the comment lines at the top to reflect your configuration or + the changes you have made to differentiate it from + <filename>GENERIC</filename>.</para> + <indexterm><primary>SunOS</primary></indexterm> + + <para>If you have built a kernel under &sunos; or some other BSD + operating system, much of this file will be very familiar to you. + If you are coming from some other operating system such as DOS, on + the other hand, the <filename>GENERIC</filename> configuration file + might seem overwhelming to you, so follow the descriptions in the + <link linkend="kernelconfig-config">Configuration File</link> + section slowly and carefully.</para> + + <note> + <para>If you <link + linkend="updating-upgrading">sync your source tree</link> with the + latest sources of the &os; project, + be sure to always check the file + <filename>/usr/src/UPDATING</filename> before you perform any update + steps. This file describes any important issues or areas + requiring special attention within the updated source code. + <filename>/usr/src/UPDATING</filename> always matches + your version of the &os; source, and is therefore more up to date + with new information than this handbook.</para> + </note> + + <para>You must now compile the source code for the kernel.</para> + + <procedure> + <title>Building a Kernel</title> + + <note> + <para>It is required to have the full &os; source tree installed + to build the kernel.</para> + </note> + + <step> + <para>Change to the <filename + class="directory">/usr/src</filename> directory:</para> + + <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen> + </step> + + <step> + <para>Compile the kernel:</para> + + <screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> + </step> + + <step> + <para>Install the new kernel:</para> + + <screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> + </step> + </procedure> + + <tip> + <para>By default, when you build a custom kernel, + <emphasis>all</emphasis> kernel modules will be rebuilt as well. + If you want to update a kernel faster or to build only custom + modules, you should edit <filename>/etc/make.conf</filename> + before starting to build the kernel:</para> + + <programlisting>MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs</programlisting> + + <para>This variable sets up a list of modules to build instead + of all of them.</para> + + <programlisting>WITHOUT_MODULES = linux acpi sound ntfs</programlisting> + + <para>This variable sets up a list of top level modules to exclude + from the build process. For other variables which you may find useful + in the process of building kernel, refer to &man.make.conf.5; + manual page.</para> + </tip> + + <indexterm> + <primary><filename class="directory">/boot/kernel.old</filename></primary> + </indexterm> + + <para>The new kernel will be copied to the <filename + class="directory">/boot/kernel</filename> directory as + <filename>/boot/kernel/kernel</filename> and the old kernel will be moved + to <filename>/boot/kernel.old/kernel</filename>. Now, shutdown the + system and reboot to use your new kernel. If something goes wrong, there + are some <link linkend="kernelconfig-trouble">troubleshooting</link> + instructions at the end of this chapter that you may find useful. Be + sure to read the section which explains how to recover in case your new + kernel <link linkend="kernelconfig-noboot">does not boot</link>.</para> + + <note> + <para>Other files relating to the boot process, such as the boot + &man.loader.8; and configuration are stored in + <filename>/boot</filename>. Third party or custom modules + can be placed in <filename class="directory">/boot/kernel</filename>, + although users should be aware that keeping modules in sync with the + compiled kernel is very important. Modules not intended + to run with the compiled kernel may result in instability + or incorrectness.</para> + </note> + </sect1> + + <sect1 id="kernelconfig-config"> + <sect1info> + <authorgroup> + <author> + <firstname>Joel</firstname> + <surname>Dahl</surname> + <contrib>Updated by </contrib> + </author> + </authorgroup> + </sect1info> + <title>The Configuration File</title> + <indexterm> + <primary>kernel</primary> + <secondary>NOTES</secondary> + </indexterm> + <indexterm><primary>NOTES</primary></indexterm> + <indexterm> + <primary>kernel</primary> + <secondary>configuration file</secondary> + </indexterm> + + <para>The general format of a configuration file is quite simple. + Each line contains a keyword and one or more arguments. For + simplicity, most lines only contain one argument. Anything + following a <literal>#</literal> is considered a comment and + ignored. The following sections describe each keyword, in + the order they are listed in <filename>GENERIC</filename>. + <anchor + id="kernelconfig-options"> For an exhaustive list of architecture + dependent options and devices, see the <filename>NOTES</filename> + file in the same directory as the <filename>GENERIC</filename> file. For + architecture independent options, see + <filename>/usr/src/sys/conf/NOTES</filename>.</para> + + <para>An <literal>include</literal> directive is + available for use in configuration files. This allows another + configuration file to be logically included in the current one, making + it easy to maintain small changes relative to an existing file. For + example, if you require a <filename>GENERIC</filename> kernel with + only a small number of additional options or drivers, this allows you + to maintain only a delta with respect to GENERIC:</para> + + <programlisting>include GENERIC +ident MYKERNEL + +options IPFIREWALL +options DUMMYNET +options IPFIREWALL_DEFAULT_TO_ACCEPT +options IPDIVERT +</programlisting> + + <para>Many administrators will find that this model offers significant + benefits over the historic writing of configuration files from scratch: + the local configuration file will express only local differences from + a <filename>GENERIC</filename> kernel and as upgrades are performed, + new features added to <filename>GENERIC</filename> will be added to the + local kernel unless specifically prevented using + <literal>nooptions</literal> or <literal>nodevice</literal>. The + remainder of this chapter addresses the contents of a typical + configuration file and the role various options and devices + play.</para> + + <note> + <para>To build a file which contains all available options, + as normally done for testing purposes, run the following + command as <username>root</username>:</para> + + <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf && make LINT</userinput></screen> + </note> + + <indexterm> + <primary>kernel</primary> + <secondary>configuration file</secondary> + </indexterm> + + <para>The following is an example of the <filename>GENERIC</filename> + kernel configuration file with various additional comments where needed + for clarity. This example should match your copy in + <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/GENERIC</filename> + fairly closely.</para> + + <indexterm> + <primary>kernel options</primary> + <secondary>machine</secondary> + </indexterm> + + <programlisting>machine i386</programlisting> + + <para>This is the machine architecture. It must be either + <literal>amd64</literal>, + <literal>i386</literal>, <literal>ia64</literal>, + <literal>pc98</literal>, <literal>powerpc</literal>, or + <literal>sparc64</literal>.</para> + + <indexterm> + <primary>kernel options</primary> + <secondary>cpu</secondary> + </indexterm> + <programlisting>cpu I486_CPU +cpu I586_CPU +cpu I686_CPU</programlisting> + + <para>The above option specifies the type of CPU you have in your + system. You may have multiple instances of the CPU line (if, for + example, you are not sure whether you should use + <literal>I586_CPU</literal> or <literal>I686_CPU</literal>), + but for a custom kernel it is best to specify only the CPU + you have. If you are unsure of your CPU type, you can check the + <filename>/var/run/dmesg.boot</filename> file to view your boot + messages.</para> + + <indexterm> + <primary>kernel options</primary> + <secondary>ident</secondary> + </indexterm> + + <programlisting>ident GENERIC</programlisting> + + <para>This is the identification of the kernel. You should change + this to whatever you named your kernel, + i.e., <literal><replaceable>MYKERNEL</replaceable></literal> if you have + followed the instructions of the previous examples. The value you put + in the <literal>ident</literal> string will print when you boot up the + kernel, so it is useful to give the new kernel a different name if you + want to keep it separate from your usual kernel (e.g., you want to + build an experimental kernel).</para> + + <programlisting>#To statically compile in device wiring instead of /boot/device.hints +#hints "GENERIC.hints" # Default places to look for devices.</programlisting> + + <para>The &man.device.hints.5; is + used to configure options of the device drivers. The default + location that &man.loader.8; will check at boot time is + <filename>/boot/device.hints</filename>. Using the + <literal>hints</literal> option you can compile these hints + statically into your kernel. Then there is no need to create a + <filename>device.hints</filename> file in + <filename>/boot</filename>.</para> + + <!-- XXX: Add a comment here that explains when compiling hints into + the kernel is a good idea and why. --> + + <programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting> + + <para>The normal build process of &os; includes + debugging information when building the kernel with the + <option>-g</option> option, which enables debugging + information when passed to &man.gcc.1;.</para> + + <programlisting>options SCHED_ULE # ULE scheduler</programlisting> + + <para>The default system scheduler for &os;. Keep this.</para> + + <programlisting>options PREEMPTION # Enable kernel thread preemption</programlisting> + + <para>Allows threads that are in the kernel to be preempted + by higher priority threads. It helps with interactivity and + allows interrupt threads to run sooner rather than waiting.</para> + + <programlisting>options INET # InterNETworking</programlisting> + + <para>Networking support. Leave this in, even if you do not plan to + be connected to a network. Most programs require at least loopback + networking (i.e., making network connections within your PC), so + this is essentially mandatory.</para> + + <programlisting>options INET6 # IPv6 communications protocols</programlisting> + + <para>This enables the IPv6 communication protocols.</para> + + <programlisting>options FFS # Berkeley Fast Filesystem</programlisting> + + <para>This is the basic hard drive file system. Leave it in if you + boot from the hard disk.</para> + + <programlisting>options SOFTUPDATES # Enable FFS Soft Updates support</programlisting> + + <para>This option enables Soft Updates in the kernel, this will + help speed up write access on the disks. Even when this + functionality is provided by the kernel, it must be turned on + for specific disks. Review the output from &man.mount.8; to see + if Soft Updates is enabled for your system disks. If you do not + see the <literal>soft-updates</literal> option then you will + need to activate it using the &man.tunefs.8; (for existing + file systems) or &man.newfs.8; (for new file systems) + commands.</para> + + <programlisting>options UFS_ACL # Support for access control lists</programlisting> + + <para>This option enables kernel support + for access control lists. This relies on the use of extended + attributes and <acronym>UFS2</acronym>, and the feature is described + in detail in <xref linkend="fs-acl">. <acronym>ACL</acronym>s are + enabled by default and should not be + disabled in the kernel if they have been used previously on a file + system, as this will remove the access control lists, changing the + way files are protected in unpredictable ways.</para> + + <programlisting>options UFS_DIRHASH # Improve performance on big directories</programlisting> + + <para>This option includes functionality to speed up disk + operations on large directories, at the expense of using + additional memory. You would normally keep this for a large + server, or interactive workstation, and remove it if you are + using &os; on a smaller system where memory is at a premium and + disk access speed is less important, such as a firewall.</para> + + <programlisting>options MD_ROOT # MD is a potential root device</programlisting> + + <para>This option enables support for a memory backed virtual disk + used as a root device.</para> + + <indexterm> + <primary>kernel options</primary> + <secondary>NFS</secondary> + </indexterm> + <indexterm> + <primary>kernel options</primary> + <secondary>NFS_ROOT</secondary> + </indexterm> + <programlisting>options NFSCLIENT # Network Filesystem Client +options NFSSERVER # Network Filesystem Server +options NFS_ROOT # NFS usable as /, requires NFSCLIENT</programlisting> + + <para>The network file system. Unless you plan to mount partitions + from a &unix; file server over TCP/IP, you can comment these + out.</para> + + <indexterm> + <primary>kernel options</primary> + <secondary>MSDOSFS</secondary> + </indexterm> + <programlisting>options MSDOSFS # MSDOS Filesystem</programlisting> + + <para>The &ms-dos; file system. Unless you plan to mount a DOS formatted + hard drive partition at boot time, you can safely comment this out. + It will be automatically loaded the first time you mount a DOS + partition, as described above. Also, the excellent + <filename role="package">emulators/mtools</filename> software + allows you to access DOS floppies without having to mount and + unmount them (and does not require <literal>MSDOSFS</literal> at + all).</para> + + <programlisting>options CD9660 # ISO 9660 Filesystem</programlisting> + + <para>The ISO 9660 file system for CDROMs. Comment it out if you do + not have a CDROM drive or only mount data CDs occasionally (since it + will be dynamically loaded the first time you mount a data CD). + Audio CDs do not need this file system.</para> + + <programlisting>options PROCFS # Process filesystem (requires PSEUDOFS)</programlisting> + + <para>The process file system. This is a <quote>pretend</quote> + file system mounted on <filename>/proc</filename> which allows + programs like &man.ps.1; to give you more information on what + processes are running. Use of <literal>PROCFS</literal> + is not required under most circumstances, as most + debugging and monitoring tools have been adapted to run without + <literal>PROCFS</literal>: installs will not mount this file + system by default.</para> + + <programlisting>options PSEUDOFS # Pseudo-filesystem framework</programlisting> + + <para>Kernels making use of <literal>PROCFS</literal> must also + include support for <literal>PSEUDOFS</literal>.</para> + + <programlisting>options GEOM_PART_GPT # GUID Partition Tables.</programlisting> + + <para>This option brings the ability to have a large number of + partitions on a single disk.</para> + + <programlisting>options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!]</programlisting> + + <para>Compatibility with 4.3BSD. Leave this in; some programs will + act strangely if you comment this out.</para> + + <programlisting>options COMPAT_FREEBSD4 # Compatible with &os;4</programlisting> + + <para>This option is required + to support applications compiled on older versions of &os; + that use older system call interfaces. It is recommended that + this option be used on all &i386; systems that may + run older applications; platforms that gained support only in + 5.X, such as ia64 and &sparc64;, do not require this option.</para> + + <programlisting>options COMPAT_FREEBSD5 # Compatible with &os;5</programlisting> + + <para>This option is required to + support applications compiled on &os; 5.X versions that use + &os; 5.X system call interfaces.</para> + + <programlisting>options COMPAT_FREEBSD6 # Compatible with &os;6</programlisting> + + <para>This option is required to + support applications compiled on &os; 6.X versions that use + &os; 6.X system call interfaces.</para> + + <programlisting>options COMPAT_FREEBSD7 # Compatible with &os;7</programlisting> + + <para>This option is required on &os; 8 and above to + support applications compiled on &os; 7.X versions that use + &os; 7.X system call interfaces.</para> + + <programlisting>options SCSI_DELAY=5000 # Delay (in ms) before probing SCSI</programlisting> + + <para>This causes the kernel to pause for 5 seconds before probing + each SCSI device in your system. If you only have IDE hard drives, + you can ignore this, otherwise you can try to lower this + number, to speed up booting. Of course, if + you do this and &os; has trouble recognizing your SCSI devices, + you will have to raise it again.</para> + + <programlisting>options KTRACE # ktrace(1) support</programlisting> + + <para>This enables kernel process tracing, which is useful in + debugging.</para> + + <programlisting>options SYSVSHM # SYSV-style shared memory</programlisting> + + <para>This option provides for System V shared memory. The most + common use of this is the XSHM extension in X, which many + graphics-intensive programs will automatically take advantage of for + extra speed. If you use X, you will definitely want to include + this.</para> + + <programlisting>options SYSVMSG # SYSV-style message queues</programlisting> + + <para>Support for System V messages. This option only adds + a few hundred bytes to the kernel.</para> + + <programlisting>options SYSVSEM # SYSV-style semaphores</programlisting> + + <para>Support for System V semaphores. Less commonly used but only + adds a few hundred bytes to the kernel.</para> + + <note> + <para>The <option>-p</option> option of the &man.ipcs.1; command will + list any processes using each of these System V facilities.</para> + </note> + + <programlisting>options _KPOSIX_PRIORITY_SCHEDULING # POSIX P1003_1B real-time extensions</programlisting> + + <para>Real-time extensions added in the 1993 &posix;. Certain + applications in the Ports Collection use these + (such as <application>&staroffice;</application>).</para> + + <programlisting>options KBD_INSTALL_CDEV # install a CDEV entry in /dev</programlisting> + + <para>This option is required to allow the creation of keyboard device + nodes in <filename>/dev</filename>.</para> + + <programlisting>options ADAPTIVE_GIANT # Giant mutex is adaptive.</programlisting> + + <para>Giant is the name of a mutual exclusion mechanism (a sleep mutex) + that protects a large set of kernel resources. Today, this is an + unacceptable performance bottleneck which is actively being replaced + with locks that protect individual resources. The + <literal>ADAPTIVE_GIANT</literal> option causes Giant to be included + in the set of mutexes adaptively spun on. That is, when a thread + wants to lock the Giant mutex, but it is already locked by a thread + on another CPU, the first thread will keep running and wait for the + lock to be released. Normally, the thread would instead go back to + sleep and wait for its next chance to run. If you are not sure, + leave this in.</para> + + <note> + <para>Note that on &os; 8.0-RELEASE and later versions, all mutexes are + adaptive by default, unless explicitly set to non-adaptive by + compiling with the <literal>NO_ADAPTIVE_MUTEXES</literal> option. As + a result, Giant is adaptive by default now, and the + <literal>ADAPTIVE_GIANT</literal> option has been removed from the + kernel configuration.</para> + </note> + + <indexterm> + <primary>kernel options</primary> + <secondary>SMP</secondary> + </indexterm> + <programlisting>device apic # I/O APIC</programlisting> + + <para>The apic device enables the use of the I/O APIC for interrupt + delivery. The apic device can be used in both UP and SMP kernels, but + is required for SMP kernels. Add <literal>options SMP</literal> to + include support for multiple processors.</para> + + <note> + <para>The apic device exists only on the i386 architecture, this + configuration line should not be used on other + architectures.</para> + </note> + + <programlisting>device eisa</programlisting> + + <para>Include this if you have an EISA motherboard. This enables + auto-detection and configuration support for all devices on the EISA + bus.</para> + + <programlisting>device pci</programlisting> + + <para>Include this if you have a PCI motherboard. This enables + auto-detection of PCI cards and gatewaying from the PCI to ISA + bus.</para> + + <programlisting># Floppy drives +device fdc</programlisting> + + <para>This is the floppy drive controller.</para> + + <programlisting># ATA and ATAPI devices +device ata</programlisting> + + <para>This driver supports all ATA and ATAPI devices. You only need + one <literal>device ata</literal> line for the kernel to detect all + PCI ATA/ATAPI devices on modern machines.</para> + + <programlisting>device atadisk # ATA disk drives</programlisting> + + <para>This is needed along with <literal>device ata</literal> for + ATA disk drives.</para> + + <programlisting>device ataraid # ATA RAID drives</programlisting> + + <para>This is needed along with <literal>device ata</literal> for ATA + RAID drives.</para> + + <programlisting><anchor id="kernelconfig-atapi"> +device atapicd # ATAPI CDROM drives</programlisting> + + <para>This is needed along with <literal>device ata</literal> for + ATAPI CDROM drives.</para> + + <programlisting>device atapifd # ATAPI floppy drives</programlisting> + + <para>This is needed along with <literal>device ata</literal> for + ATAPI floppy drives.</para> + + <programlisting>device atapist # ATAPI tape drives</programlisting> + + <para>This is needed along with <literal>device ata</literal> for + ATAPI tape drives.</para> + + <programlisting>options ATA_STATIC_ID # Static device numbering</programlisting> + + <para>This makes the controller number static; without this, + the device numbers are dynamically allocated.</para> + + <programlisting># SCSI Controllers +device ahb # EISA AHA1742 family +device ahc # AHA2940 and onboard AIC7xxx devices +options AHC_REG_PRETTY_PRINT # Print register bitfields in debug + # output. Adds ~128k to driver. +device ahd # AHA39320/29320 and onboard AIC79xx devices +options AHD_REG_PRETTY_PRINT # Print register bitfields in debug + # output. Adds ~215k to driver. +device amd # AMD 53C974 (Teckram DC-390(T)) +device isp # Qlogic family +#device ispfw # Firmware for QLogic HBAs- normally a module +device mpt # LSI-Logic MPT-Fusion +#device ncr # NCR/Symbios Logic +device sym # NCR/Symbios Logic (newer chipsets + those of `ncr') +device trm # Tekram DC395U/UW/F DC315U adapters + +device adv # Advansys SCSI adapters +device adw # Advansys wide SCSI adapters +device aha # Adaptec 154x SCSI adapters +device aic # Adaptec 15[012]x SCSI adapters, AIC-6[23]60. +device bt # Buslogic/Mylex MultiMaster SCSI adapters + +device ncv # NCR 53C500 +device nsp # Workbit Ninja SCSI-3 +device stg # TMC 18C30/18C50</programlisting> + + <para>SCSI controllers. Comment out any you do not have in your + system. If you have an IDE only system, you can remove these + altogether. The <literal>*_REG_PRETTY_PRINT</literal> lines are + debugging options for their respective drivers.</para> + + <programlisting># SCSI peripherals +device scbus # SCSI bus (required for SCSI) +device ch # SCSI media changers +device da # Direct Access (disks) +device sa # Sequential Access (tape etc) +device cd # CD +device pass # Passthrough device (direct SCSI access) +device ses # SCSI Environmental Services (and SAF-TE)</programlisting> + + <para>SCSI peripherals. Again, comment out any you do not have, or if + you have only IDE hardware, you can remove them completely.</para> + + <note> + <para>The USB &man.umass.4; driver and a few other drivers use + the SCSI subsystem even though they are not real SCSI devices. + Therefore make sure not to remove SCSI support, if any such + drivers are included in the kernel configuration.</para> + </note> + + <programlisting># RAID controllers interfaced to the SCSI subsystem +device amr # AMI MegaRAID +device arcmsr # Areca SATA II RAID +device asr # DPT SmartRAID V, VI and Adaptec SCSI RAID +device ciss # Compaq Smart RAID 5* +device dpt # DPT Smartcache III, IV - See NOTES for options +device hptmv # Highpoint RocketRAID 182x +device hptrr # Highpoint RocketRAID 17xx, 22xx, 23xx, 25xx +device iir # Intel Integrated RAID +device ips # IBM (Adaptec) ServeRAID +device mly # Mylex AcceleRAID/eXtremeRAID +device twa # 3ware 9000 series PATA/SATA RAID + +# RAID controllers +device aac # Adaptec FSA RAID +device aacp # SCSI passthrough for aac (requires CAM) +device ida # Compaq Smart RAID +device mfi # LSI MegaRAID SAS +device mlx # Mylex DAC960 family +device pst # Promise Supertrak SX6000 +device twe # 3ware ATA RAID</programlisting> + + <para>Supported RAID controllers. If you do not have any of these, + you can comment them out or remove them.</para> + + <programlisting># atkbdc0 controls both the keyboard and the PS/2 mouse +device atkbdc # AT keyboard controller</programlisting> + + <para>The keyboard controller (<literal>atkbdc</literal>) provides I/O + services for the AT keyboard and PS/2 style pointing devices. This + controller is required by the keyboard driver + (<literal>atkbd</literal>) and the PS/2 pointing device driver + (<literal>psm</literal>).</para> + + <programlisting>device atkbd # AT keyboard</programlisting> + + <para>The <literal>atkbd</literal> driver, together with + <literal>atkbdc</literal> controller, provides access to the AT 84 + keyboard or the AT enhanced keyboard which is connected to the AT + keyboard controller.</para> + + <programlisting>device psm # PS/2 mouse</programlisting> + + <para>Use this device if your mouse plugs into the PS/2 mouse + port.</para> + + <programlisting>device kbdmux # keyboard multiplexer</programlisting> + + <para>Basic support for keyboard multiplexing. If you do not plan + to use more than one keyboard on the system, you can safely + remove that line.</para> + + <programlisting>device vga # VGA video card driver</programlisting> + + <para>The video card driver.</para> + + <programlisting> +device splash # Splash screen and screen saver support</programlisting> + + <para>Splash screen at start up! Screen savers require this + too.</para> + + <programlisting># syscons is the default console driver, resembling an SCO console +device sc</programlisting> + + <para><literal>sc</literal> is the default console driver and + resembles a SCO console. Since most full-screen programs access the + console through a terminal database library like + <filename>termcap</filename>, it should not matter whether you use + this or <literal>vt</literal>, the <literal>VT220</literal> + compatible console driver. When you log in, set your + <envar>TERM</envar> variable to <literal>scoansi</literal> if + full-screen programs have trouble running under this console.</para> + + <programlisting># Enable this for the pcvt (VT220 compatible) console driver +#device vt +#options XSERVER # support for X server on a vt console +#options FAT_CURSOR # start with block cursor</programlisting> + + <para>This is a VT220-compatible console driver, backward compatible to + VT100/102. It works well on some laptops which have hardware + incompatibilities with <literal>sc</literal>. Also set your + <envar>TERM</envar> variable to <literal>vt100</literal> or + <literal>vt220</literal> when you log in. This driver might also + prove useful when connecting to a large number of different machines + over the network, where <filename>termcap</filename> or + <filename>terminfo</filename> entries for the <literal>sc</literal> + device are often not available — <literal>vt100</literal> + should be available on virtually any platform.</para> + + <programlisting>device agp</programlisting> + + <para>Include this if you have an AGP card in the system. This + will enable support for AGP, and AGP GART for boards which + have these features.</para> + + <indexterm> + <primary>APM</primary> + </indexterm> + + <programlisting># Power management support (see NOTES for more options) +#device apm</programlisting> + + <para>Advanced Power Management support. Useful for laptops, + although this is disabled in + <filename>GENERIC</filename> by default.</para> + + <programlisting># Add suspend/resume support for the i8254. +device pmtimer</programlisting> + + <para>Timer device driver for power management events, such as APM and + ACPI.</para> + + <programlisting># PCCARD (PCMCIA) support +# PCMCIA and cardbus bridge support +device cbb # cardbus (yenta) bridge +device pccard # PC Card (16-bit) bus +device cardbus # CardBus (32-bit) bus</programlisting> + + <para>PCMCIA support. You want this if you are using a + laptop.</para> + + <programlisting># Serial (COM) ports +device sio # 8250, 16[45]50 based serial ports</programlisting> + + <para>These are the serial ports referred to as + <devicename>COM</devicename> ports in the &ms-dos;/&windows; + world.</para> + + <note> + <para>If you have an internal modem on <devicename>COM4</devicename> + and a serial port at <devicename>COM2</devicename>, you will have + to change the IRQ of the modem to 2 (for obscure technical reasons, + IRQ2 = IRQ 9) in order to access it + from &os;. If you have a multiport serial card, check the + manual page for &man.sio.4; for more information on the proper + values to add to your <filename>/boot/device.hints</filename>. + Some video cards (notably those based on + S3 chips) use IO addresses in the form of + <literal>0x*2e8</literal>, and since many cheap serial cards do + not fully decode the 16-bit IO address space, they clash with + these cards making the <devicename>COM4</devicename> port + practically unavailable.</para> + + <para>Each serial port is required to have a unique IRQ (unless you + are using one of the multiport cards where shared interrupts are + supported), so the default IRQs for <devicename>COM3</devicename> + and <devicename>COM4</devicename> cannot be used.</para> + </note> + + <programlisting># Parallel port +device ppc</programlisting> + + <para>This is the ISA-bus parallel port interface.</para> + + <programlisting>device ppbus # Parallel port bus (required)</programlisting> + + <para>Provides support for the parallel port bus.</para> + + <programlisting>device lpt # Printer</programlisting> + + <para>Support for parallel port printers.</para> + + <note> + <para>All three of the above are required to enable parallel printer + support.</para> + </note> + + <programlisting>device plip # TCP/IP over parallel</programlisting> + + <para>This is the driver for the parallel network interface.</para> + + <programlisting>device ppi # Parallel port interface device</programlisting> + + <para>The general-purpose I/O (<quote>geek port</quote>) + IEEE1284 + I/O.</para> + + <programlisting>#device vpo # Requires scbus and da</programlisting> + + <indexterm><primary>zip drive</primary></indexterm> + <para>This is for an Iomega Zip drive. It requires + <literal>scbus</literal> and <literal>da</literal> support. Best + performance is achieved with ports in EPP 1.9 mode.</para> + + <programlisting>#device puc</programlisting> + + <para>Uncomment this device if you have a <quote>dumb</quote> serial + or parallel PCI card that is supported by the &man.puc.4; glue + driver.</para> + + <programlisting># PCI Ethernet NICs. +device de # DEC/Intel DC21x4x (<quote>Tulip</quote>) +device em # Intel PRO/1000 adapter Gigabit Ethernet Card +device ixgb # Intel PRO/10GbE Ethernet Card +device txp # 3Com 3cR990 (<quote>Typhoon</quote>) +device vx # 3Com 3c590, 3c595 (<quote>Vortex</quote>)</programlisting> + + <para>Various PCI network card drivers. Comment out or remove any of + these not present in your system.</para> + + <programlisting># PCI Ethernet NICs that use the common MII bus controller code. +# NOTE: Be sure to keep the 'device miibus' line in order to use these NICs! +device miibus # MII bus support</programlisting> + + <para>MII bus support is required for some PCI 10/100 Ethernet NICs, + namely those which use MII-compliant transceivers or implement + transceiver control interfaces that operate like an MII. Adding + <literal>device miibus</literal> to the kernel config pulls in + support for the generic miibus API and all of the PHY drivers, + including a generic one for PHYs that are not specifically handled + by an individual driver.</para> + + <programlisting>device bce # Broadcom BCM5706/BCM5708 Gigabit Ethernet +device bfe # Broadcom BCM440x 10/100 Ethernet +device bge # Broadcom BCM570xx Gigabit Ethernet +device dc # DEC/Intel 21143 and various workalikes +device fxp # Intel EtherExpress PRO/100B (82557, 82558) +device lge # Level 1 LXT1001 gigabit ethernet +device msk # Marvell/SysKonnect Yukon II Gigabit Ethernet +device nge # NatSemi DP83820 gigabit ethernet +device nve # nVidia nForce MCP on-board Ethernet Networking +device pcn # AMD Am79C97x PCI 10/100 (precedence over 'lnc') +device re # RealTek 8139C+/8169/8169S/8110S +device rl # RealTek 8129/8139 +device sf # Adaptec AIC-6915 (<quote>Starfire</quote>) +device sis # Silicon Integrated Systems SiS 900/SiS 7016 +device sk # SysKonnect SK-984x & SK-982x gigabit Ethernet +device ste # Sundance ST201 (D-Link DFE-550TX) +device stge # Sundance/Tamarack TC9021 gigabit Ethernet +device ti # Alteon Networks Tigon I/II gigabit Ethernet +device tl # Texas Instruments ThunderLAN +device tx # SMC EtherPower II (83c170 <quote>EPIC</quote>) +device vge # VIA VT612x gigabit ethernet +device vr # VIA Rhine, Rhine II +device wb # Winbond W89C840F +device xl # 3Com 3c90x (<quote>Boomerang</quote>, <quote>Cyclone</quote>)</programlisting> + + <para>Drivers that use the MII bus controller code.</para> + + <programlisting># ISA Ethernet NICs. pccard NICs included. +device cs # Crystal Semiconductor CS89x0 NIC +# 'device ed' requires 'device miibus' +device ed # NE[12]000, SMC Ultra, 3c503, DS8390 cards +device ex # Intel EtherExpress Pro/10 and Pro/10+ +device ep # Etherlink III based cards +device fe # Fujitsu MB8696x based cards +device ie # EtherExpress 8/16, 3C507, StarLAN 10 etc. +device lnc # NE2100, NE32-VL Lance Ethernet cards +device sn # SMC's 9000 series of Ethernet chips +device xe # Xircom pccard Ethernet + +# ISA devices that use the old ISA shims +#device le</programlisting> + + <para>ISA Ethernet drivers. See + <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename> + for details of which cards are supported by which driver.</para> + + <programlisting># Wireless NIC cards +device wlan # 802.11 support</programlisting> + + <para>Generic 802.11 support. This line is required for wireless + networking.</para> + + <programlisting>device wlan_wep # 802.11 WEP support +device wlan_ccmp # 802.11 CCMP support +device wlan_tkip # 802.11 TKIP support</programlisting> + + <para>Crypto support for 802.11 devices. These lines are needed + if you intend to use encryption and 802.11i security + protocols.</para> + + <programlisting>device an # Aironet 4500/4800 802.11 wireless NICs. +device ath # Atheros pci/cardbus NIC's +device ath_hal # Atheros HAL (Hardware Access Layer) +device ath_rate_sample # SampleRate tx rate control for ath +device awi # BayStack 660 and others +device ral # Ralink Technology RT2500 wireless NICs. +device wi # WaveLAN/Intersil/Symbol 802.11 wireless NICs. +#device wl # Older non 802.11 Wavelan wireless NIC.</programlisting> + + <para>Support for various wireless cards.</para> + + <programlisting># Pseudo devices +device loop # Network loopback</programlisting> + + <para>This is the generic loopback device for TCP/IP. If you telnet + or FTP to <hostid>localhost</hostid> (aka <hostid + role="ipaddr">127.0.0.1</hostid>) it will come back at you through + this device. This is <emphasis>mandatory</emphasis>.</para> + + <programlisting>device random # Entropy device</programlisting> + + <para>Cryptographically secure random number generator.</para> + + <programlisting>device ether # Ethernet support</programlisting> + + <para><literal>ether</literal> is only needed if you have an Ethernet + card. It includes generic Ethernet protocol code.</para> + + <programlisting>device sl # Kernel SLIP</programlisting> + + <para><literal>sl</literal> is for SLIP support. This has been almost + entirely supplanted by PPP, which is easier to set up, better suited + for modem-to-modem connection, and more powerful.</para> + + <programlisting>device ppp # Kernel PPP</programlisting> + + <para>This is for kernel PPP support for dial-up connections. There + is also a version of PPP implemented as a userland application that + uses <literal>tun</literal> and offers more flexibility and features + such as demand dialing.</para> + + <programlisting>device tun # Packet tunnel.</programlisting> + + <para>This is used by the userland PPP software. + See + the <link linkend="userppp">PPP</link> section of this book for more + information.</para> + + <programlisting><anchor id="kernelconfig-ptys"> +device pty # Pseudo-ttys (telnet etc)</programlisting> + + <para>This is a <quote>pseudo-terminal</quote> or simulated login port. + It is used by incoming <command>telnet</command> and + <command>rlogin</command> sessions, + <application>xterm</application>, and some other applications such + as <application>Emacs</application>.</para> + + <programlisting>device md # Memory <quote>disks</quote></programlisting> + + <para>Memory disk pseudo-devices.</para> + + <programlisting>device gif # IPv6 and IPv4 tunneling</programlisting> + + <para>This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, + IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. The + <literal>gif</literal> device is + <quote>auto-cloning</quote>, and will create device nodes as + needed.</para> + + <programlisting>device faith # IPv6-to-IPv4 relaying (translation)</programlisting> + + <para>This pseudo-device captures packets that are sent to it and + diverts them to the IPv4/IPv6 translation daemon.</para> + + <programlisting># The `bpf' device enables the Berkeley Packet Filter. +# Be aware of the administrative consequences of enabling this! +# Note that 'bpf' is required for DHCP. +device bpf # Berkeley packet filter</programlisting> + + <para>This is the Berkeley Packet Filter. This pseudo-device allows + network interfaces to be placed in promiscuous mode, capturing every + packet on a broadcast network (e.g., an Ethernet). These packets + can be captured to disk and or examined with the &man.tcpdump.1; + program.</para> + + <note> + <para>The &man.bpf.4; device is also used by + &man.dhclient.8; to obtain the IP address of the default router + (gateway) and so on. If you use DHCP, leave this + uncommented.</para> + </note> + + <programlisting># USB support +device uhci # UHCI PCI->USB interface +device ohci # OHCI PCI->USB interface +device ehci # EHCI PCI->USB interface (USB 2.0) +device usb # USB Bus (required) +#device udbp # USB Double Bulk Pipe devices +device ugen # Generic +device uhid # <quote>Human Interface Devices</quote> +device ukbd # Keyboard +device ulpt # Printer +device umass # Disks/Mass storage - Requires scbus and da +device ums # Mouse +device ural # Ralink Technology RT2500USB wireless NICs +device urio # Diamond Rio 500 MP3 player +device uscanner # Scanners +# USB Ethernet, requires mii +device aue # ADMtek USB Ethernet +device axe # ASIX Electronics USB Ethernet +device cdce # Generic USB over Ethernet +device cue # CATC USB Ethernet +device kue # Kawasaki LSI USB Ethernet +device rue # RealTek RTL8150 USB Ethernet</programlisting> + + <para>Support for various USB devices.</para> + + <programlisting># FireWire support +device firewire # FireWire bus code +device sbp # SCSI over FireWire (Requires scbus and da) +device fwe # Ethernet over FireWire (non-standard!)</programlisting> + + <para>Support for various Firewire devices.</para> + + <para>For more information and additional devices supported by + &os;, see + <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename>.</para> + + <sect2> + <title>Large Memory Configurations (<acronym>PAE</acronym>)</title> + <indexterm> + <primary>Physical Address Extensions + (<acronym>PAE</acronym>)</primary> + <secondary>large memory</secondary> + </indexterm> + + <para>Large memory configuration machines require access to + more than the 4 gigabyte limit on User+Kernel Virtual + Address (<acronym>KVA</acronym>) space. Due to this + limitation, Intel added support for 36-bit physical address + space access in the &pentium; Pro and later line of CPUs.</para> + + <para>The Physical Address Extension (<acronym>PAE</acronym>) + capability of the &intel; &pentium; Pro and later CPUs + allows memory configurations of up to 64 gigabytes. + &os; provides support for this capability via the + <option>PAE</option> kernel configuration option, available + in all current release versions of &os;. Due to + the limitations of the Intel memory architecture, no distinction + is made for memory above or below 4 gigabytes. Memory allocated + above 4 gigabytes is simply added to the pool of available + memory.</para> + + <para>To enable <acronym>PAE</acronym> support in the kernel, + simply add the following line to your kernel configuration + file:</para> + + <programlisting>options PAE</programlisting> + + <note> + <para>The <acronym>PAE</acronym> support in &os; is only + available for &intel; IA-32 processors. It should also be + noted, that the <acronym>PAE</acronym> support in &os; has + not received wide testing, and should be considered beta + quality compared to other stable features of &os;.</para> + </note> + + <para><acronym>PAE</acronym> support in &os; has a few limitations:</para> + + <itemizedlist> + <listitem> + <para>A process is not able to access more than 4 + gigabytes of VM space.</para> + </listitem> + + <listitem> + <para>Device drivers that do not use the &man.bus.dma.9; + interface will cause data corruption in a + <acronym>PAE</acronym> enabled kernel and are not + recommended for use. For this reason, a + <filename>PAE</filename> kernel + configuration file is provided in &os; which + excludes all drivers not known to work in a + <acronym>PAE</acronym> enabled kernel.</para> + </listitem> + + <listitem> + <para>Some system tunables determine memory resource usage + by the amount of available physical memory. Such + tunables can unnecessarily over-allocate due to the + large memory nature of a <acronym>PAE</acronym> system. + One such example is the <option>kern.maxvnodes</option> + sysctl, which controls the maximum number of vnodes allowed + in the kernel. It is advised to adjust this and other + such tunables to a reasonable value.</para> + </listitem> + + <listitem> + <para>It might be necessary to increase the kernel virtual + address (<acronym>KVA</acronym>) space or to reduce the + amount of specific kernel resource that is heavily used + (see above) in order to avoid <acronym>KVA</acronym> + exhaustion. The <option>KVA_PAGES</option> kernel option + can be used for increasing the + <acronym>KVA</acronym> space.</para> + </listitem> + </itemizedlist> + + <para>For performance and stability concerns, it is advised to + consult the &man.tuning.7; manual page. The &man.pae.4; + manual page contains up-to-date information on &os;'s + <acronym>PAE</acronym> support.</para> + </sect2> + </sect1> + + <sect1 id="kernelconfig-trouble"> + <title>If Something Goes Wrong</title> + + <para>There are four categories of trouble that can occur when + building a custom kernel. They are:</para> + + <variablelist> + <varlistentry> + <term><command>config</command> fails:</term> + + <listitem> + <para>If the &man.config.8; command fails when you + give it your kernel description, you have probably made a + simple error somewhere. Fortunately, + &man.config.8; will print the line number that it + had trouble with, so that you can quickly locate the line + containing the error. For example, if you see:</para> + + <screen>config: line 17: syntax error</screen> + + <para>Make sure the + keyword is typed correctly by comparing it to the + <filename>GENERIC</filename> kernel or another + reference.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>make</command> fails:</term> + + <listitem> + <para>If the <command>make</command> command fails, it usually + signals an error in your kernel description which is not severe + enough for &man.config.8; to catch. Again, look + over your configuration, and if you still cannot resolve the + problem, send mail to the &a.questions; with your kernel + configuration, and it should be diagnosed quickly.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>The kernel does not boot:<anchor + id="kernelconfig-noboot"></term> + + <listitem> + <para>If your new kernel does not boot, or fails to + recognize your devices, do not panic! Fortunately, &os; has + an excellent mechanism for recovering from incompatible + kernels. Simply choose the kernel you want to boot from at + the &os; boot loader. You can access this when the system + boot menu appears. Select the <quote>Escape to a loader + prompt</quote> option, number six. At the prompt, type + <command>boot <replaceable>kernel.old</replaceable></command>, + or the name of any other kernel that will boot properly. + When reconfiguring a kernel, it is always a good idea to keep + a kernel that is known to work on hand.</para> + + <para>After booting with a good kernel you can check over your + configuration file and try to build it again. One helpful + resource is the <filename>/var/log/messages</filename> file + which records, among other things, all of the kernel messages + from every successful boot. Also, the &man.dmesg.8; command + will print the kernel messages from the current boot.</para> + + <note> + <para>If you are having trouble building a kernel, make sure + to keep a <filename>GENERIC</filename>, or some other kernel + that is known to work on hand as a different name that will + not get erased on the next build. You cannot rely on + <filename>kernel.old</filename> because when installing a + new kernel, <filename>kernel.old</filename> is overwritten + with the last installed kernel which may be non-functional. + Also, as soon as possible, move the working kernel to the + proper <filename class="directory">/boot/kernel</filename> + location or commands such + as &man.ps.1; may not work properly. To do this, simply + rename the directory containing the good kernel:</para> + + <screen>&prompt.root; <userinput>mv /boot/kernel <replaceable>/boot/kernel.bad</replaceable></userinput> +&prompt.root; <userinput>mv /boot/<replaceable>kernel.good</replaceable> /boot/kernel</userinput></screen> + + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>The kernel works, but &man.ps.1; does not work + any more:</term> + + <listitem> + <para>If you have installed a different version of the kernel + from the one that the system utilities have been built with, + for example, a -CURRENT kernel on a -RELEASE, many system-status + commands like &man.ps.1; and &man.vmstat.8; will not work any + more. You should <link linkend="makeworld">recompile and install + a world</link> built with the same version of the source tree as + your kernel. This is one reason it is + not normally a good idea to use a different version of the + kernel from the rest of the operating system.</para> + </listitem> + </varlistentry> + </variablelist> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/l10n/Makefile b/en_US.ISO8859-1/books/handbook/l10n/Makefile new file mode 100644 index 0000000000..c6741a2341 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/l10n/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= l10n/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml new file mode 100644 index 0000000000..47e9070f35 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.sgml @@ -0,0 +1,952 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="l10n"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Andrey</firstname> + <surname>Chernov</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Michael C.</firstname> + <surname>Wu</surname> + <contrib>Rewritten by </contrib> + </author> + <!-- 30 Nv 2000 --> + </authorgroup> + </chapterinfo> + + <title>Localization - I18N/L10N Usage and Setup</title> + + <sect1 id="l10n-synopsis"> + <title>Synopsis</title> + + <para>FreeBSD is a very distributed project with users and + contributors located all over the world. This chapter discusses + the internationalization and localization features of FreeBSD + that allow non-English speaking users to get real work done. + There are many aspects of the i18n implementation in both the system + and application levels, so where applicable we refer the reader + to more specific sources of documentation.</para> + + <para>After reading this chapter, you will know:</para> + <itemizedlist> + <listitem><para>How different languages and locales are encoded + on modern operating systems.</para></listitem> + <listitem><para>How to set the locale for your login + shell.</para></listitem> + <listitem><para>How to configure your console for non-English + languages.</para></listitem> + <listitem><para>How to use X Window System effectively with different + languages.</para></listitem> + <listitem><para>Where to find more information about writing + i18n-compliant applications.</para></listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem><para>Know how to install additional third-party + applications (<xref linkend="ports">).</para></listitem> + </itemizedlist> + </sect1> + + <sect1 id="l10n-basics"> + <title>The Basics</title> + + <sect2> + <title>What Is I18N/L10N?</title> + <indexterm> + <primary>internationalization</primary> + <see>localization</see> + </indexterm> + <indexterm><primary>localization</primary></indexterm> + + <para>Developers shortened internationalization into the term I18N, + counting the number of letters between the first and the last + letters of internationalization. L10N uses the same naming + scheme, coming from <quote>localization</quote>. Combined + together, I18N/L10N methods, protocols, and applications allow + users to use languages of their choice.</para> + + <para>I18N applications are programmed using I18N kits under + libraries. It allows for developers to write a simple file and + translate displayed menus and texts to each language. We strongly + encourage programmers to follow this convention.</para> + </sect2> + + <sect2> + <title>Why Should I Use I18N/L10N?</title> + + <para>I18N/L10N is used whenever you wish to either view, input, or + process data in non-English languages.</para> + </sect2> + + <sect2> + <title>What Languages Are Supported in the I18N Effort?</title> + + <para>I18N and L10N are not FreeBSD specific. Currently, one can + choose from most of the major languages of the World, including + but not limited to: Chinese, German, Japanese, Korean, French, + Russian, Vietnamese and others.</para> + </sect2> + </sect1> + + <sect1 id="using-localization"> + <title>Using Localization</title> + + <para>In all its splendor, I18N is not FreeBSD-specific and is a + convention. We encourage you to help FreeBSD in following this + convention.</para> + <indexterm><primary>locale</primary></indexterm> + + <para>Localization settings are based on three main terms: + Language Code, Country Code, and Encoding. Locale names are + constructed from these parts as follows:</para> + + <programlisting><replaceable>LanguageCode</replaceable>_<replaceable>CountryCode</replaceable>.<replaceable>Encoding</replaceable></programlisting> + + <sect2> + <title>Language and Country Codes</title> + <indexterm><primary>language codes</primary></indexterm> + <indexterm><primary>country codes</primary></indexterm> + + <para>In order to localize a FreeBSD system to a specific language + (or any other I18N-supporting &unix; like systems), the user needs to find out + the codes for the specific country and language (country + codes tell applications what variation of given + language to use). In addition, web + browsers, SMTP/POP servers, web servers, etc. make decisions based on + them. The following are examples of language/country codes:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Language/Country Code</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry>en_US</entry> + <entry>English - United States</entry> + </row> + + <row> + <entry>ru_RU</entry> + <entry>Russian for Russia</entry> + </row> + + <row> + <entry>zh_TW</entry> + <entry>Traditional Chinese for Taiwan</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + </sect2> + + <sect2> + <title>Encodings</title> + <indexterm><primary>encodings</primary></indexterm> + <indexterm><primary>ASCII</primary></indexterm> + + <para>Some languages use non-ASCII encodings that are 8-bit, wide + or multibyte characters, see &man.multibyte.3; for more + details. Older applications do not recognize them + and mistake them for control characters. Newer applications + usually do recognize 8-bit characters. Depending on the + implementation, users may be required to compile an application + with wide or multibyte characters support, or configure it correctly. + To be able to input and process wide or multibyte characters, the <ulink + url="&url.base;/ports/index.html">FreeBSD Ports Collection</ulink> has provided + each language with different programs. Refer to the I18N + documentation in the respective FreeBSD Port.</para> + + <para>Specifically, the user needs to look at the application + documentation to decide on how to configure it correctly or to + pass correct values into the configure/Makefile/compiler.</para> + + <para>Some things to keep in mind are:</para> + + <itemizedlist> + <listitem> + <para>Language specific single C chars character sets + (see &man.multibyte.3;), e.g. + ISO8859-1, ISO8859-15, KOI8-R, CP437.</para> + </listitem> + + <listitem> + <para>Wide or multibyte encodings, e.g., EUC, Big5.</para> + </listitem> + </itemizedlist> + + <para>You can check the active list of character sets at the + <ulink + url="http://www.iana.org/assignments/character-sets">IANA Registry</ulink>.</para> + + <note> + <para>&os; uses X11-compatible locale encodings instead.</para> + </note> + + </sect2> + + <sect2> + <title>I18N Applications</title> + + <para>In the FreeBSD Ports and Package system, I18N applications + have been named with <literal>I18N</literal> in their names for + easy identification. However, they do not always support the + language needed.</para> + </sect2> + + <sect2 id="setting-locale"> + <title>Setting Locale</title> + + <para>Usually it is sufficient to export the value of the locale name + as <envar>LANG</envar> in the login shell. This could be done in + the user's <filename>~/.login_conf</filename> file or in the + startup file of the user's shell (<filename>~/.profile</filename>, + <filename>~/.bashrc</filename>, <filename>~/.cshrc</filename>). + There is no need to set the locale subsets such as + <envar>LC_CTYPE</envar>, <envar>LC_CTIME</envar>. Please + refer to language-specific FreeBSD documentation for more + information.</para> + + <para>You should set the following two environment variables in your configuration + files:</para> + + <itemizedlist> + <indexterm><primary>POSIX</primary></indexterm> + <listitem> + <para><envar>LANG</envar> for &posix; &man.setlocale.3; family + functions</para> + </listitem> + + <indexterm><primary>MIME</primary></indexterm> + <listitem> + <para><envar>MM_CHARSET</envar> for applications' MIME character + set</para> + </listitem> + </itemizedlist> + + <para>This includes the user shell configuration, the specific application + configuration, and the X11 configuration.</para> + + <sect3> + <title>Setting Locale Methods</title> + <indexterm><primary>locale</primary></indexterm> + <indexterm><primary>login class</primary></indexterm> + + <para>There are two methods for setting locale, and both are + described below. The first (recommended one) is by assigning + the environment variables in <link linkend="login-class">login + class</link>, and the second is by adding the environment + variable assignments to the system's shell <link + linkend="startup-file">startup file</link>.</para> + + <sect4 id="login-class"> + <title>Login Classes Method</title> + + <para>This method allows environment variables needed for locale + name and MIME character sets to be assigned once for every + possible shell instead of adding specific shell assignments to + each shell's startup file. <link linkend="usr-setup">User + Level Setup</link> can be done by an user himself and <link + linkend="adm-setup">Administrator Level Setup</link> require + superuser privileges.</para> + + <sect5 id="usr-setup"> + <title>User Level Setup</title> + + <para>Here is a minimal example of a + <filename>.login_conf</filename> file in user's home + directory which has both variables set for Latin-1 + encoding:</para> + + <programlisting>me:\ + :charset=ISO-8859-1:\ + :lang=de_DE.ISO8859-1:</programlisting> + + <indexterm><primary>Traditional Chinese</primary><secondary>BIG-5 encoding</secondary></indexterm> + <para>Here is an example of a + <filename>.login_conf</filename> that sets the variables + for Traditional Chinese in BIG-5 encoding. Notice the many + more variables set because some software does not respect + locale variables correctly for Chinese, Japanese, and Korean.</para> + + <programlisting>#Users who do not wish to use monetary units or time formats +#of Taiwan can manually change each variable +me:\ + :lang=zh_TW.Big5:\ + :setenv=LC_ALL=zh_TW.Big5:\ + :setenv=LC_COLLATE=zh_TW.Big5:\ + :setenv=LC_CTYPE=zh_TW.Big5:\ + :setenv=LC_MESSAGES=zh_TW.Big5:\ + :setenv=LC_MONETARY=zh_TW.Big5:\ + :setenv=LC_NUMERIC=zh_TW.Big5:\ + :setenv=LC_TIME=zh_TW.Big5:\ + :charset=big5:\ + :xmodifiers="@im=gcin": #Set gcin as the XIM Input Server</programlisting> + + <para>See <link linkend="adm-setup">Administrator Level + Setup</link> and &man.login.conf.5; for more details.</para> + </sect5> + + <sect5 id="adm-setup"> + <title>Administrator Level Setup</title> + + <para>Verify that the user's login class in + <filename>/etc/login.conf</filename> sets the correct + language. Make sure these settings + appear in <filename>/etc/login.conf</filename>:</para> + + <programlisting><replaceable>language_name</replaceable>|<replaceable>Account Type Description</replaceable>:\ + :charset=<replaceable>MIME_charset</replaceable>:\ + :lang=<replaceable>locale_name</replaceable>:\ + :tc=default:</programlisting> + + <para>So sticking with our previous example using Latin-1, it + would look like this:</para> + + <programlisting>german|German Users Accounts:\ + :charset=ISO-8859-1:\ + :lang=de_DE.ISO8859-1:\ + :tc=default:</programlisting> + + <para>Before changing users Login Classes execute + the following command:</para> + + <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen> + + <para>to make new configuration in + <filename>/etc/login.conf</filename> visible to the system.</para> + + <bridgehead renderas=sect4>Changing Login Classes with &man.vipw.8;</bridgehead> + + <indexterm> + <primary><command>vipw</command></primary> + </indexterm> + <para>Use <command>vipw</command> to add new users, and make + the entry look like this:</para> + + <programlisting>user:password:1111:11:<replaceable>language</replaceable>:0:0:User Name:/home/user:/bin/sh</programlisting> + + <bridgehead renderas=sect4>Changing Login Classes with &man.adduser.8;</bridgehead> + + <indexterm> + <primary><command>adduser</command></primary> + </indexterm> + <indexterm><primary>login class</primary></indexterm> + <para>Use <command>adduser</command> to add new users, and do + the following:</para> + + <itemizedlist> + <listitem> + <para>Set <literal>defaultclass = + <replaceable>language</replaceable></literal> in + <filename>/etc/adduser.conf</filename>. Keep in mind + you must enter a <literal>default</literal> class for + all users of other languages in this case.</para> + </listitem> + + <listitem> + <para>An alternative variant is answering the specified + language each time that +<screen><prompt>Enter login class: default []: </prompt></screen> + appears from &man.adduser.8;.</para> + </listitem> + + <listitem> + <para>Another alternative is to use the following for each + user of a different language that you wish to + add:</para> + + <screen>&prompt.root; <userinput>adduser -class <replaceable>language</replaceable></userinput></screen> + </listitem> + </itemizedlist> + + <bridgehead renderas=sect4>Changing Login Classes with &man.pw.8;</bridgehead> + <indexterm> + <primary><command>pw</command></primary> + </indexterm> + <para>If you use &man.pw.8; for adding new users, call it in + this form:</para> + + <screen>&prompt.root; <userinput>pw useradd <replaceable>user_name</replaceable> -L <replaceable>language</replaceable></userinput></screen> + </sect5> + </sect4> + + <sect4 id="startup-file"> + <title>Shell Startup File Method</title> + + <note> + <para>This method is not recommended because it requires a + different setup for each possible shell program chosen. Use + the <link linkend="login-class">Login Class Method</link> + instead.</para> + </note> + + <indexterm><primary>MIME</primary></indexterm> + <indexterm><primary>locale</primary></indexterm> + <para>To add the locale name and MIME character set, just set + the two environment variables shown below in the + <filename>/etc/profile</filename> and/or + <filename>/etc/csh.login</filename> shell startup files. We + will use the German language as an example below:</para> + + <para>In <filename>/etc/profile</filename>:</para> + + <programlisting><envar>LANG=de_DE.ISO8859-1; export LANG</envar> +<envar>MM_CHARSET=ISO-8859-1; export MM_CHARSET</envar></programlisting> + + <para>Or in <filename>/etc/csh.login</filename>:</para> + + <programlisting><envar>setenv LANG de_DE.ISO8859-1</envar> +<envar>setenv MM_CHARSET ISO-8859-1</envar></programlisting> + + <para>Alternatively, you can add the above instructions to + <filename>/usr/share/skel/dot.profile</filename> (similar to + what was used in <filename>/etc/profile</filename> above), or + <filename>/usr/share/skel/dot.login</filename> (similar to + what was used in <filename>/etc/csh.login</filename> + above).</para> + + <para>For X11:</para> + + <para>In <filename>$HOME/.xinitrc</filename>:</para> + + <programlisting><envar>LANG=de_DE.ISO8859-1; export LANG</envar></programlisting> + + <para>Or:</para> + + <programlisting><envar>setenv LANG de_DE.ISO8859-1</envar></programlisting> + + <para>Depending on your shell (see above).</para> + + </sect4> + </sect3> + </sect2> + + <sect2 id="setting-console"> + <title>Console Setup</title> + + <para>For all single C chars character sets, set the correct + console fonts in <filename>/etc/rc.conf</filename> for the + language in question with:</para> + + <programlisting>font8x16=<replaceable>font_name</replaceable> +font8x14=<replaceable>font_name</replaceable> +font8x8=<replaceable>font_name</replaceable></programlisting> + + <para>The <replaceable>font_name</replaceable> here is taken from + the <filename>/usr/share/syscons/fonts</filename> directory, + without the <filename>.fnt</filename> suffix.</para> + + <indexterm> + <primary><application>sysinstall</application></primary> + </indexterm> + <indexterm><primary>keymap</primary></indexterm> + <indexterm><primary>screenmap</primary></indexterm> + <para>If required, set the keymap and screenmap for your + single C chars character set through + <command>sysinstall</command>. + Once inside <application>sysinstall</application>, choose <guimenuitem>Configure</guimenuitem>, then + <guimenuitem>Console</guimenuitem>. Alternatively, you can add the + following to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>scrnmap=<replaceable>screenmap_name</replaceable> +keymap=<replaceable>keymap_name</replaceable> +keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting> + + <para>The <replaceable>screenmap_name</replaceable> here is taken + from the <filename>/usr/share/syscons/scrnmaps</filename> + directory, without the <filename>.scm</filename> suffix. A + screenmap with a corresponding mapped font is usually needed as a + workaround for expanding bit 8 to bit 9 on a VGA adapter's font + character matrix in pseudographics area, i.e., to move letters out + of that area if screen font uses a bit 8 column.</para> + + <para>If you have the <application>moused</application> daemon + enabled by setting the following + in your <filename>/etc/rc.conf</filename>:</para> + +<programlisting>moused_enable="YES"</programlisting> + + <para>then examine the mouse cursor information in the next + paragraph.</para> + + <indexterm> + <primary><application>moused</application></primary> + </indexterm> + <para>By default the mouse cursor of the &man.syscons.4; driver occupies the + 0xd0-0xd3 range in the character set. If your language uses this + range, you need to move the cursor's range outside of it. To enable + the workaround for &os;, add the following line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>mousechar_start=3</programlisting> + + <para>The <replaceable>keymap_name</replaceable> here is taken from + the <filename>/usr/share/syscons/keymaps</filename> directory, + without the <filename>.kbd</filename> suffix. If you are + uncertain which keymap to use, you use can &man.kbdmap.1; to test + keymaps without rebooting.</para> + + <para>The <literal>keychange</literal> is usually needed to program + function keys to match the selected terminal type because + function key sequences cannot be defined in the key map.</para> + + <para>Also be sure to set the correct console terminal type in + <filename>/etc/ttys</filename> for all <literal>ttyv*</literal> + entries. Current pre-defined correspondences are:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Character Set</entry> + <entry>Terminal Type</entry> + </row> + </thead> + + <tbody> + <row> + <entry>ISO8859-1 or ISO8859-15</entry> + <entry><literal>cons25l1</literal></entry> + </row> + + <row> + <entry>ISO8859-2</entry> + <entry><literal>cons25l2</literal></entry> + </row> + + <row> + <entry>ISO8859-7</entry> + <entry><literal>cons25l7</literal></entry> + </row> + + <row> + <entry>KOI8-R</entry> + <entry><literal>cons25r</literal></entry> + </row> + + <row> + <entry>KOI8-U</entry> + <entry><literal>cons25u</literal></entry> + </row> + + <row> + <entry>CP437 (VGA default)</entry> + <entry><literal>cons25</literal></entry> + </row> + + <row> + <entry>US-ASCII</entry> + <entry><literal>cons25w</literal></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>For wide or multibyte characters languages, use the correct + FreeBSD port in your + <filename>/usr/ports/<replaceable>language</replaceable></filename> + directory. Some ports appear as console while the system sees it + as serial vtty's, hence you must reserve enough vtty's for both + X11 and the pseudo-serial console. Here is a partial list of + applications for using other languages in console:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Language</entry> + <entry>Location</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Traditional Chinese (BIG-5)</entry> + <entry><filename role="package">chinese/big5con</filename></entry> + </row> + + <row> + <entry>Japanese</entry> + <entry><filename role="package">japanese/kon2-16dot</filename> or + <filename role="package">japanese/mule-freewnn</filename></entry> + </row> + + <row> + <entry>Korean</entry> + <entry><filename role="package">korean/han</filename></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> + + <sect2> + <title>X11 Setup</title> + + <para>Although X11 is not part of the FreeBSD Project, we have + included some information here for FreeBSD users. For more + details, refer to the <ulink + url="http://www.x.org/">&xorg; + web site</ulink> or whichever X11 Server you use.</para> + + <para>In <filename>~/.Xresources</filename>, you can additionally + tune application specific I18N settings (e.g., fonts, menus, + etc.).</para> + + <sect3> + <title>Displaying Fonts</title> + <indexterm><primary>X11 True Type font server</primary></indexterm> + <para>Install <application>&xorg;</application> server + (<filename role="package">x11-servers/xorg-server</filename>), + then install the language &truetype; fonts. Setting the correct + locale should allow you to view your selected language in menus + and such.</para> + </sect3> + + <sect3> + <title>Inputting Non-English Characters</title> + <indexterm><primary>X11 Input Method (XIM)</primary></indexterm> + <para>The X11 Input Method (XIM) Protocol is a new standard for + all X11 clients. All X11 applications should be written as XIM + clients that take input from XIM Input servers. There are + several XIM servers available for different languages.</para> + </sect3> + </sect2> + + <sect2> + <title>Printer Setup</title> + + <para>Some single C chars character sets are usually hardware + coded into printers. Wide or multibyte + character sets require special setup and we recommend using + <application>apsfilter</application>. You may also convert the + document to &postscript; or PDF formats using language specific + converters.</para> + </sect2> + + <sect2> + <title>Kernel and File Systems</title> + + <para>The FreeBSD fast filesystem (FFS) is 8-bit clean, so it can be used + with any single C chars character set (see &man.multibyte.3;), + but there is no character set + name stored in the filesystem; i.e., it is raw 8-bit and does not + know anything about encoding order. Officially, FFS does not + support any form of wide or multibyte character sets yet. However, some + wide or multibyte character sets have independent patches for FFS + enabling such support. They are only temporary unportable + solutions or hacks and we have decided to not include them in the + source tree. Refer to respective languages' web sites for more + information and the patch files.</para> + + <indexterm><primary>DOS</primary></indexterm> + <indexterm><primary>Unicode</primary></indexterm> + <para>The FreeBSD &ms-dos; filesystem has the configurable ability to + convert between &ms-dos;, Unicode character sets and chosen + FreeBSD filesystem character sets. See &man.mount.msdosfs.8; for + details.</para> + </sect2> + </sect1> + + <sect1 id="l10n-compiling"> + <title>Compiling I18N Programs</title> + + <para>Many FreeBSD Ports have been ported with I18N support. Some + of them are marked with -I18N in the port name. These and many + other programs have built in support for I18N and need no special + consideration.</para> + + <indexterm> + <primary><application>MySQL</application></primary> + </indexterm> + <para>However, some applications such as + <application>MySQL</application> need to have their + <filename>Makefile</filename> configured with the specific + charset. This is usually done in the + <filename>Makefile</filename> or done by passing a value to + <application>configure</application> in the source.</para> + </sect1> + + <sect1 id="lang-setup"> + <title>Localizing FreeBSD to Specific Languages</title> + + <sect2 id="ru-localize"> + <sect2info> + <authorgroup> + <author> + <firstname>Andrey</firstname> + <surname>Chernov</surname> + <contrib>Originally contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <title>Russian Language (KOI8-R Encoding)</title> + <indexterm> + <primary>localization</primary> + <secondary>Russian</secondary> + </indexterm> + + <para>For more information about KOI8-R encoding, see the <ulink + url="http://koi8.pp.ru/">KOI8-R References + (Russian Net Character Set)</ulink>.</para> + + <sect3> + <title>Locale Setup</title> + + <para>Put the following lines into your + <filename>~/.login_conf</filename> file:</para> + + <programlisting>me:My Account:\ + :charset=KOI8-R:\ + :lang=ru_RU.KOI8-R:</programlisting> + + <para>See earlier in this chapter for examples of setting up the + <link linkend="setting-locale">locale</link>.</para> + </sect3> + + <sect3> + <title>Console Setup</title> + + <itemizedlist> + <listitem> + <para>Add the following line + to your <filename>/etc/rc.conf</filename> file:</para> + + <programlisting>mousechar_start=3</programlisting> + </listitem> + + <listitem> + <para>Also, use following settings in + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>keymap="ru.koi8-r" +scrnmap="koi8-r2cp866" +font8x16="cp866b-8x16" +font8x14="cp866-8x14" +font8x8="cp866-8x8"</programlisting> + + </listitem> + + <listitem> + <para>For each <literal>ttyv*</literal> entry in + <filename>/etc/ttys</filename>, use + <literal>cons25r</literal> as the terminal type.</para> + </listitem> + </itemizedlist> + + <para>See earlier in this chapter for examples of setting up the + <link linkend="setting-console">console</link>.</para> + </sect3> + + <sect3> + <title>Printer Setup</title> + <indexterm><primary>printers</primary></indexterm> + <para>Since most printers with Russian characters come with + hardware code page CP866, a special output filter is needed + to convert from KOI8-R to CP866. Such a filter is installed by + default as <filename>/usr/libexec/lpr/ru/koi2alt</filename>. + A Russian printer <filename>/etc/printcap</filename> entry + should look like:</para> + + <programlisting>lp|Russian local line printer:\ + :sh:of=/usr/libexec/lpr/ru/koi2alt:\ + :lp=/dev/lpt0:sd=/var/spool/output/lpd:lf=/var/log/lpd-errs:</programlisting> + + <para>See &man.printcap.5; for a detailed description.</para> + </sect3> + + <sect3> + <title>&ms-dos; FS and Russian Filenames</title> + + <para>The following example &man.fstab.5; entry enables support + for Russian filenames in mounted &ms-dos; filesystems:</para> + + <programlisting>/dev/ad0s2 /dos/c msdos rw,-Wkoi2dos,-Lru_RU.KOI8-R 0 0</programlisting> + + <para>The option <option>-L</option> selects the locale name + used, and <option>-W</option> sets the character conversion + table. To use the <option>-W</option> option, be sure to + mount <filename>/usr</filename> before the &ms-dos; partition + because the conversion tables are located in + <filename>/usr/libdata/msdosfs</filename>. For more + information, see the &man.mount.msdosfs.8; manual + page.</para> + </sect3> + + <sect3> + <title>X11 Setup</title> + + <orderedlist> + <listitem> + <para>Do <link linkend="setting-locale">non-X locale + setup</link> first as described.</para> + </listitem> + + <listitem> + <para>If you use <application>&xorg;</application>, + install + <filename role="package">x11-fonts/xorg-fonts-cyrillic</filename> + package.</para> + + <para>Check the <literal>"Files"</literal> section + in your <filename>/etc/X11/xorg.conf</filename> file. + The following + line must be added <emphasis>before</emphasis> any other + <literal>FontPath</literal> entries:</para> + + <programlisting>FontPath "/usr/local/lib/X11/fonts/cyrillic"</programlisting> + + <note> + <para>See ports for more cyrillic fonts.</para></note> + </listitem> + + <listitem> + <para>To activate a Russian keyboard, add the following to the + <literal>"Keyboard"</literal> section of your + <filename>xorg.conf</filename> file:</para> + + <programlisting>Option "XkbLayout" "us,ru" +Option "XkbOptions" "grp:toggle"</programlisting> + + <para>Also make sure that <literal>XkbDisable</literal> is + turned off (commented out) there.</para> + + <para>For <literal>grp:toggle</literal> + the RUS/LAT switch will be <keycap>Right Alt</keycap>, + for <literal>grp:ctrl_shift_toggle</literal> switch will be + <keycombo action="simul"><keycap>Ctrl</keycap><keycap>Shift</keycap></keycombo>. + For <literal>grp:caps_toggle</literal> + the RUS/LAT switch will be <keycap>CapsLock</keycap>. + The old <keycap>CapsLock</keycap> function is still + available via <keycombo action="simul"><keycap>Shift</keycap><keycap>CapsLock</keycap></keycombo> (in LAT mode + only). + <literal>grp:caps_toggle</literal> does not work in + <application>&xorg;</application> for unknown reason.</para> + + <para>If you have <quote>&windows;</quote> keys on your keyboard, + and notice that some non-alphabetical keys are mapped + incorrectly in RUS mode, add the following line in your + <filename>xorg.conf</filename> file:</para> + + <programlisting>Option "XkbVariant" ",winkeys"</programlisting> + + <note> + <para>The Russian XKB keyboard may not work with non-localized + applications.</para> + </note> + </listitem> + </orderedlist> + <note> + <para>Minimally localized applications + should call a <function>XtSetLanguageProc (NULL, NULL, + NULL);</function> function early in the program.</para> + <para>See <ulink + url="http://koi8.pp.ru/xwin.html"> + KOI8-R for X Window</ulink> for more instructions on + localizing X11 applications.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>Traditional Chinese Localization for Taiwan</title> + <indexterm> + <primary>localization</primary> + <secondary>Traditional Chinese</secondary> + </indexterm> + <para>The FreeBSD-Taiwan Project has an Chinese HOWTO for + FreeBSD at <ulink url="http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/"></ulink> + using many Chinese ports. + Current editor for the <literal>FreeBSD Chinese HOWTO</literal> is + Shen Chuan-Hsing <email>statue@freebsd.sinica.edu.tw</email>. + </para> + + <para>Chuan-Hsing Shen <email>statue@freebsd.sinica.edu.tw</email> has + created the <ulink url="http://netlab.cse.yzu.edu.tw/~statue/cfc/"> + Chinese FreeBSD Collection (CFC)</ulink> using FreeBSD-Taiwan's + <literal>zh-L10N-tut</literal>. The packages and the script files + are available at <ulink url="ftp://freebsd.csie.nctu.edu.tw/pub/taiwan/CFC/"></ulink>.</para> + </sect2> + + <sect2> + <title>German Language Localization (for All ISO 8859-1 + Languages)</title> + <indexterm> + <primary>localization</primary> + <secondary>German</secondary> + </indexterm> + + <para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a + tutorial on using umlauts on a FreeBSD machine. The tutorial + is written in German and is available at + <ulink url="http://user.cs.tu-berlin.de/~eserte/FreeBSD/doc/umlaute/umlaute.html"></ulink>.</para> + </sect2> + + <sect2> + <title>Greek Language Localization</title> + + <indexterm> + <primary>localization</primary> + <secondary>Greek</secondary> + </indexterm> + <para>Nikos Kokkalis <email>nickkokkalis@gmail.com</email> has written + a complete article on Greek support in &os;. It is available as + part of the official &os; Greek documentation, in <ulink + url="&url.doc.base;/el_GR.ISO8859-7/articles/greek-language-support/index.html">http://www.freebsd.org/doc/el_GR.ISO8859-7/articles/greek-language-support/index.html</ulink>. + Please note this is in Greek <emphasis>only</emphasis>.</para> + </sect2> + + <sect2> + <title>Japanese and Korean Language Localization</title> + <indexterm> + <primary>localization</primary> + <secondary>Japanese</secondary> + </indexterm> + <indexterm> + <primary>localization</primary> + <secondary>Korean</secondary> + </indexterm> + <para>For Japanese, refer to + <ulink url="http://www.jp.FreeBSD.org/"></ulink>, + and for Korean, refer to + <ulink url="http://www.kr.FreeBSD.org/"></ulink>.</para> + </sect2> + + <sect2> + <title>Non-English FreeBSD Documentation</title> + + <para>Some FreeBSD contributors have translated parts of FreeBSD documentation to + other languages. They are available through links on the <ulink + url="&url.base;/index.html">main site</ulink> or in + <filename>/usr/share/doc</filename>.</para> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/Makefile b/en_US.ISO8859-1/books/handbook/linuxemu/Makefile new file mode 100644 index 0000000000..37adfa9af6 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/linuxemu/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= linuxemu/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml new file mode 100644 index 0000000000..2c346aa4ec --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.sgml @@ -0,0 +1,1356 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="linuxemu"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Mock</surname> + <contrib>Restructured and parts updated by </contrib> + </author> + <!-- 22 Mar 2000 --> + </authorgroup> + <authorgroup> + <author> + <firstname>Brian N.</firstname> + <surname>Handy</surname> + <contrib>Originally contributed by </contrib> + </author> + <author> + <firstname>Rich</firstname> + <surname>Murphey</surname> + </author> + </authorgroup> + </chapterinfo> + + <title>Linux Binary Compatibility</title> + + <sect1 id="linuxemu-synopsis"> + <title>Synopsis</title> + <indexterm><primary>Linux binary compatibility</primary></indexterm> + <indexterm> + <primary>binary compatibility</primary> + <secondary>Linux</secondary> + </indexterm> + + <para>FreeBSD provides binary compatibility with several other + &unix; like operating systems, including Linux. At this point, + you may be asking yourself why exactly, does + FreeBSD need to be able to run Linux binaries? The answer to that + question is quite simple. Many companies and developers develop + only for Linux, since it is the latest <quote>hot thing</quote> in + the computing world. That leaves the rest of us FreeBSD users + bugging these same companies and developers to put out native + FreeBSD versions of their applications. The problem is, that most + of these companies do not really realize how many people would use + their product if there were FreeBSD versions too, and most continue + to only develop for Linux. So what is a FreeBSD user to do? This + is where the Linux binary compatibility of FreeBSD comes into + play.</para> + + <para>In a nutshell, the compatibility allows FreeBSD users to run + about 90% of all Linux applications without modification. This + includes applications such as <application>&staroffice;</application>, + the Linux version of <application>&netscape;</application>, + <application>&adobe; &acrobat;</application>, + <application>&realplayer;</application>, + <application>&oracle;</application>, + <application>&wordperfect;</application>, <application>Doom</application>, + <application>Quake</application>, and more. It is also reported + that in some situations, Linux binaries perform better on FreeBSD + than they do under Linux.</para> + + <para>There are, however, some Linux-specific operating system + features that are not supported under FreeBSD. Linux binaries will + not work on FreeBSD if they overly use &i386; specific + calls, such as enabling virtual 8086 mode.</para> + + <para>After reading this chapter, you will know:</para> + <itemizedlist> + <listitem> + <para>How to enable Linux binary compatibility on your system.</para> + </listitem> + + <listitem> + <para>How to install additional Linux shared + libraries.</para> + </listitem> + + <listitem> + <para>How to install Linux applications on your FreeBSD system.</para> + </listitem> + + <listitem> + <para>The implementation details of Linux compatibility in FreeBSD.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Know how to install additional third-party + software (<xref linkend="ports">).</para> + </listitem> + </itemizedlist> + + </sect1> + + <sect1 id="linuxemu-lbc-install"> + <title>Installation</title> + + <indexterm><primary>KLD (kernel loadable object)</primary></indexterm> + + <para>Linux binary compatibility is not turned on by default. The + easiest way to enable this functionality is to load the + <literal>linux</literal> KLD object (<quote>Kernel LoaDable + object</quote>). You can load this module by typing the + following as <username>root</username>:</para> + + <screen>&prompt.root; <userinput>kldload linux</userinput></screen> + + <para>If you would like Linux compatibility to always be enabled, + then you should add the following line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>linux_enable="YES"</programlisting> + + <para>The &man.kldstat.8; command can be used to verify that the + KLD is loaded:</para> + + <screen>&prompt.user; <userinput>kldstat</userinput> +Id Refs Address Size Name + 1 2 0xc0100000 16bdb8 kernel + 7 1 0xc24db000 d000 linux.ko</screen> + <indexterm> + <primary>kernel options</primary> + <secondary>COMPAT_LINUX</secondary> + </indexterm> + + <para>If for some reason you do not want to or cannot load the KLD, + then you may statically link Linux binary compatibility into the kernel + by adding <literal>options COMPAT_LINUX</literal> to your kernel + configuration file. Then install your new kernel as described in + <xref linkend="kernelconfig">.</para> + + <sect2> + <title>Installing Linux Runtime Libraries</title> + <indexterm> + <primary>Linux</primary> + <secondary>installing Linux libraries</secondary> + </indexterm> + + <para>This can be done one of two ways, either by using the + <link linkend="linuxemu-libs-port">linux_base</link> port, or + by installing them <link + linkend="linuxemu-libs-manually">manually</link>.</para> + + <sect3 id="linuxemu-libs-port"> + <title>Installing Using the linux_base Port</title> + <indexterm><primary>Ports Collection</primary></indexterm> + + <para>This is by far the easiest method to use when installing the + runtime libraries. It is just like installing any other port + from the <link linkend="ports">Ports Collection</link>:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/emulators/linux_base-f10</userinput> +&prompt.root; <userinput>make install distclean</userinput></screen> + + <note> + <para>On &os; systems prior to &os; 8.0, you will have + to use the <filename + role="package">emulators/linux_base-fc4</filename> port + instead of <filename + role="package">emulators/linux_base-f10</filename>.</para> + </note> + + <para>You should now have working Linux binary compatibility. + Some programs may complain about incorrect minor versions of the + system libraries. In general, however, this does not seem to be + a problem.</para> + + <note><para>There may be multiple versions of the <filename + role="package">emulators/linux_base</filename> port available, + corresponding to different versions of various Linux distributions. + You should install the port most closely resembling the + requirements of the Linux applications you would like to + install.</para></note> + + </sect3> + + <sect3 id="linuxemu-libs-manually"> + <title>Installing Libraries Manually</title> + + <para>If you do not have the <quote>ports</quote> collection + installed, you can install the libraries by hand instead. You + will need the Linux shared libraries that the program depends on + and the runtime linker. Also, you will need to create a + <quote>shadow root</quote> directory, + <filename>/compat/linux</filename>, for Linux libraries on your + FreeBSD system. Any shared libraries opened by Linux programs + run under FreeBSD will look in this tree first. So, if a Linux + program loads, for example, <filename>/lib/libc.so</filename>, + FreeBSD will first try to open + <filename>/compat/linux/lib/libc.so</filename>, and if that does + not exist, it will then try <filename>/lib/libc.so</filename>. + Shared libraries should be installed in the shadow tree + <filename>/compat/linux/lib</filename> rather than the paths + that the Linux <command>ld.so</command> reports.</para> + + <para>Generally, you will need to look for the shared libraries + that Linux binaries depend on only the first few times that you + install a Linux program on your FreeBSD system. After a while, + you will have a sufficient set of Linux shared libraries on your + system to be able to run newly imported Linux binaries without + any extra work.</para> + </sect3> + + <sect3> + <title>How to Install Additional Shared Libraries</title> + <indexterm><primary>shared libraries</primary></indexterm> + + <para>What if you install the <filename>linux_base</filename> port + and your application still complains about missing shared + libraries? How do you know which shared libraries Linux + binaries need, and where to get them? Basically, there are 2 + possibilities (when following these instructions you will need + to be <username>root</username> on your FreeBSD system).</para> + + <para>If you have access to a Linux system, see what shared + libraries the application needs, and copy them to your FreeBSD + system. Look at the following example:</para> + + <informalexample> + <para>Let us assume you used FTP to get the Linux binary of + <application>Doom</application>, and put it on a Linux system you have access to. You + then can check which shared libraries it needs by running + <command>ldd linuxdoom</command>, like so:</para> + + <screen>&prompt.user; <userinput>ldd linuxdoom</userinput> +libXt.so.3 (DLL Jump 3.1) => /usr/X11/lib/libXt.so.3.1.0 +libX11.so.3 (DLL Jump 3.1) => /usr/X11/lib/libX11.so.3.1.0 +libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29</screen> + + <indexterm><primary>symbolic links</primary></indexterm> + <para>You would need to get all the files from the last column, + and put them under <filename>/compat/linux</filename>, with + the names in the first column as symbolic links pointing to + them. This means you eventually have these files on your + FreeBSD system:</para> + + <screen>/compat/linux/usr/X11/lib/libXt.so.3.1.0 +/compat/linux/usr/X11/lib/libXt.so.3 -> libXt.so.3.1.0 +/compat/linux/usr/X11/lib/libX11.so.3.1.0 +/compat/linux/usr/X11/lib/libX11.so.3 -> libX11.so.3.1.0 +/compat/linux/lib/libc.so.4.6.29 +/compat/linux/lib/libc.so.4 -> libc.so.4.6.29</screen> + + <blockquote> + <note> + <para>Note that if you already have a Linux shared library + with a matching major revision number to the first column + of the <command>ldd</command> output, you will not need to + copy the file named in the last column to your system, the + one you already have should work. It is advisable to copy + the shared library anyway if it is a newer version, + though. You can remove the old one, as long as you make + the symbolic link point to the new one. So, if you have + these libraries on your system:</para> + + <screen>/compat/linux/lib/libc.so.4.6.27 +/compat/linux/lib/libc.so.4 -> libc.so.4.6.27</screen> + + <para>and you find a new binary that claims to require a + later version according to the output of + <command>ldd</command>:</para> + + <screen>libc.so.4 (DLL Jump 4.5pl26) -> libc.so.4.6.29</screen> + + <para>If it is only one or two versions out of date in the + trailing digit then do not worry about copying + <filename>/lib/libc.so.4.6.29</filename> too, because the + program should work fine with the slightly older version. + However, if you like, you can decide to replace the + <filename>libc.so</filename> anyway, and that should leave + you with:</para> + + <screen>/compat/linux/lib/libc.so.4.6.29 +/compat/linux/lib/libc.so.4 -> libc.so.4.6.29</screen> + </note> + </blockquote> + + <blockquote> + <note> + <para>The symbolic link mechanism is + <emphasis>only</emphasis> needed for Linux binaries. The + FreeBSD runtime linker takes care of looking for matching + major revision numbers itself and you do not need to worry + about it.</para> + </note> + </blockquote> + </informalexample> + </sect3> + </sect2> + + <sect2> + <title>Installing Linux ELF Binaries</title> + <indexterm> + <primary>Linux</primary> + <secondary>ELF binaries</secondary> + </indexterm> + + <para>ELF binaries sometimes require an extra step of + <quote>branding</quote>. If you attempt to run an unbranded ELF + binary, you will get an error message like the following:</para> + + <screen>&prompt.user; <userinput>./my-linux-elf-binary</userinput> +ELF binary type not known +Abort</screen> + + <para>To help the FreeBSD kernel distinguish between a FreeBSD ELF + binary and a Linux binary, use the &man.brandelf.1; + utility.</para> + + <screen>&prompt.user; <userinput>brandelf -t Linux my-linux-elf-binary</userinput></screen> + + <indexterm><primary>GNU toolchain</primary></indexterm> + <para>The GNU toolchain now places the appropriate branding + information into ELF binaries automatically, so this step + should become increasingly unnecessary in the future.</para> + </sect2> + + <sect2> + <title>Installing a Random Linux RPM Based Application</title> + + <para>FreeBSD has its own package database and it is used to track + all ports (&linux; ports as well). So the &linux; RPM database is not + used (not supported).</para> + + <para>However if you need to install a random &linux; RPM-based + application it can be achieved by:</para> + + <screen>&prompt.root; <userinput>cd /compat/linux</userinput> +&prompt.root; <userinput>rpm2cpio -q < /path/to/linux.archive.rpm | cpio -id</userinput></screen> + + <para>Then brandelf installed ELF binaries (not libraries!). + You will not be able to do a clean uninstall, but it may help you + to do tests.</para> + </sect2> + + <sect2> + <title>Configuring the Hostname Resolver</title> + + <para>If DNS does not work or you get this message:</para> + + <screen>resolv+: "bind" is an invalid keyword resolv+: +"hosts" is an invalid keyword</screen> + + <para>You will need to configure a + <filename>/compat/linux/etc/host.conf</filename> file + containing:</para> + + <programlisting>order hosts, bind +multi on</programlisting> + + <para>The order here specifies that <filename>/etc/hosts</filename> + is searched first and DNS is searched second. When + <filename>/compat/linux/etc/host.conf</filename> is not + installed, Linux applications find FreeBSD's + <filename>/etc/host.conf</filename> and complain about the + incompatible FreeBSD syntax. You should remove + <literal>bind</literal> if you have not configured a name server + using the <filename>/etc/resolv.conf</filename> file.</para> + </sect2> + </sect1> + + <sect1 id="linuxemu-mathematica"> + <sect1info> + <authorgroup> + <author> + <firstname>Boris</firstname> + <surname>Hollas</surname> + <contrib>Updated for Mathematica 5.X by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Installing &mathematica;</title> + + <indexterm> + <primary>applications</primary> + <secondary><application>Mathematica</application></secondary> + </indexterm> + + <para>This document describes the process of installing the Linux + version of <application>&mathematica; 5.X</application> onto + a FreeBSD system.</para> + + <para>The Linux version of <application>&mathematica;</application> + or <application>&mathematica; for Students</application> can + be ordered directly from Wolfram at + <ulink url="http://www.wolfram.com/"></ulink>.</para> + + <sect2> + <title>Running the &mathematica; Installer</title> + + <para>First, you have to tell &os; that + <application>&mathematica;</application>'s Linux + binaries use the Linux ABI. The easiest way to do so is to + set the default ELF brand + to Linux for all unbranded binaries with the command:</para> + + <screen>&prompt.root; <userinput>sysctl kern.fallback_elf_brand=3</userinput></screen> + + <para>This will make &os; assume that unbranded ELF binaries + use the Linux ABI and so you should be able to run the + installer straight from the CDROM.</para> + + <para>Now, copy the file <filename>MathInstaller</filename> to + your hard drive:</para> + + <screen>&prompt.root; <userinput>mount /cdrom</userinput> +&prompt.root; <userinput>cp /cdrom/Unix/Installers/Linux/MathInstaller /localdir/</userinput></screen> + + <para>and in this file, replace <literal>/bin/sh</literal> in + the first line by <literal>/compat/linux/bin/sh</literal>. + This makes sure that the installer is executed by the Linux + version of &man.sh.1;. Next, replace all occurrences of + <literal>Linux)</literal> by <literal>FreeBSD)</literal> with + a text editor or the script below in the next section. This + tells the <application>&mathematica;</application> installer, + who calls <command>uname -s</command> to determine the + operating system, to treat &os; as a Linux-like operating + system. Invoking <command>MathInstaller</command> will now + install <application>&mathematica;</application>.</para> + </sect2> + + <sect2> + <title>Modifying the &mathematica; Executables</title> + + <para>The shell scripts that + <application>&mathematica;</application> created during + installation have to be modified before you can use them. If + you chose <filename class="directory">/usr/local/bin</filename> + as the directory to place the + <application>&mathematica;</application> executables in, you + will find symlinks in this directory to files called + <filename>math</filename>, <filename>mathematica</filename>, + <filename>Mathematica</filename>, and + <filename>MathKernel</filename>. In each of these, replace + <literal>Linux)</literal> by <literal>FreeBSD)</literal> with + a text editor or the following shell script:</para> + + <programlisting>#!/bin/sh +cd /usr/local/bin +for i in math mathematica Mathematica MathKernel + do sed 's/Linux)/FreeBSD)/g' $i > $i.tmp + sed 's/\/bin\/sh/\/compat\/linux\/bin\/sh/g' $i.tmp > $i + rm $i.tmp + chmod a+x $i +done</programlisting> + </sect2> + + <sect2> + <title>Obtaining Your &mathematica; Password</title> + + <indexterm> + <primary>Ethernet</primary> + <secondary>MAC address</secondary> + </indexterm> + + <para>When you start <application>&mathematica;</application> + for the first time, you will be asked for a password. If you + have not yet obtained a password from Wolfram, run the program + <command>mathinfo</command> in the installation directory to + obtain your <quote>machine ID</quote>. This machine ID is + based solely on the MAC address of your first Ethernet card, + so you cannot run your copy of + <application>&mathematica;</application> on different + machines.</para> + + <para>When you register with Wolfram, either by email, phone or fax, + you will give them the <quote>machine ID</quote> and they will + respond with a corresponding password consisting of groups of + numbers.</para> + </sect2> + + <sect2> + <title>Running the &mathematica; Frontend over a Network</title> + + <para><application>&mathematica;</application> uses some special + fonts to display characters not + present in any of the standard font sets (integrals, sums, Greek + letters, etc.). The X protocol requires these fonts to be install + <emphasis>locally</emphasis>. This means you will have to copy + these fonts from the CDROM or from a host with + <application>&mathematica;</application> + installed to your local machine. These fonts are normally stored + in <filename>/cdrom/Unix/Files/SystemFiles/Fonts</filename> on the + CDROM, or + <filename>/usr/local/mathematica/SystemFiles/Fonts</filename> on + your hard drive. The actual fonts are in the subdirectories + <filename>Type1</filename> and <filename>X</filename>. There are + several ways to use them, as described below.</para> + + <para>The first way is to copy them into one of the existing font + directories in <filename>/usr/X11R6/lib/X11/fonts</filename>. + This will require editing the <filename>fonts.dir</filename> file, + adding the font names to it, and changing the number of fonts on + the first line. Alternatively, you should also just be able to + run &man.mkfontdir.1; in the directory you have copied + them to.</para> + + <para>The second way to do this is to copy the directories to + <filename>/usr/X11R6/lib/X11/fonts</filename>:</para> + + <screen>&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts</userinput> +&prompt.root; <userinput>mkdir X</userinput> +&prompt.root; <userinput>mkdir MathType1</userinput> +&prompt.root; <userinput>cd /cdrom/Unix/Files/SystemFiles/Fonts</userinput> +&prompt.root; <userinput>cp X/* /usr/X11R6/lib/X11/fonts/X</userinput> +&prompt.root; <userinput>cp Type1/* /usr/X11R6/lib/X11/fonts/MathType1</userinput> +&prompt.root; <userinput>cd /usr/X11R6/lib/X11/fonts/X</userinput> +&prompt.root; <userinput>mkfontdir</userinput> +&prompt.root; <userinput>cd ../MathType1</userinput> +&prompt.root; <userinput>mkfontdir</userinput></screen> + + <para>Now add the new font directories to your font path:</para> + + <screen>&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/X</userinput> +&prompt.root; <userinput>xset fp+ /usr/X11R6/lib/X11/fonts/MathType1</userinput> +&prompt.root; <userinput>xset fp rehash</userinput></screen> + + <para>If you are using the <application>&xorg;</application> server, you can have these font + directories loaded automatically by adding them to your + <filename>xorg.conf</filename> file.</para> + + <indexterm><primary>fonts</primary></indexterm> + + <para>If you <emphasis>do not</emphasis> already have a directory + called <filename>/usr/X11R6/lib/X11/fonts/Type1</filename>, you + can change the name of the <filename>MathType1</filename> + directory in the example above to + <filename>Type1</filename>.</para> + </sect2> + </sect1> + + <sect1 id="linuxemu-maple"> + <sect1info> + <authorgroup> + <author> + <firstname>Aaron</firstname> + <surname>Kaplan</surname> +<!-- <address><email>aaron@lo-res.org</email></address>--> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Robert</firstname> + <surname>Getschmann</surname> +<!-- <address><email>rob@getschmann.org</email></address>--> + <contrib>Thanks to </contrib> + </author> + </authorgroup> + </sect1info> + <title>Installing &maple;</title> + + <indexterm> + <primary>applications</primary> + <secondary><application>Maple</application></secondary> + </indexterm> + + <para><application>&maple;</application> is a commercial mathematics program similar to + <application>&mathematica;</application>. You must purchase this software from <ulink + url="http://www.maplesoft.com/"></ulink> and then register there + for a license file. To install this software on FreeBSD, please + follow these simple steps.</para> + + <procedure> + <step><para>Execute the <filename>INSTALL</filename> shell + script from the product distribution. Choose the + <quote>RedHat</quote> option when prompted by the + installation program. A typical installation directory + might be <filename + class="directory">/usr/local/maple</filename>.</para></step> + + <step><para>If you have not done so, order a license for <application>&maple;</application> + from Maple Waterloo Software (<ulink url="http://register.maplesoft.com/"></ulink>) + and copy it to + <filename>/usr/local/maple/license/license.dat</filename>.</para></step> + + <step><para>Install the <application>FLEXlm</application> + license manager by running the + <filename>INSTALL_LIC</filename> install shell script that + comes with <application>&maple;</application>. Specify the + primary hostname for your machine for the license + server.</para></step> + + <step><para>Patch the + <filename>/usr/local/maple/bin/maple.system.type</filename> + file with the following:</para> +<programlisting> ----- snip ------------------ +*** maple.system.type.orig Sun Jul 8 16:35:33 2001 +--- maple.system.type Sun Jul 8 16:35:51 2001 +*************** +*** 72,77 **** +--- 72,78 ---- + # the IBM RS/6000 AIX case + MAPLE_BIN="bin.IBM_RISC_UNIX" + ;; ++ "FreeBSD"|\ + "Linux") + # the Linux/x86 case + # We have two Linux implementations, one for Red Hat and + ----- snip end of patch -----</programlisting> + + <para>Please note that after the <literal>"FreeBSD"|\</literal> no other + whitespace should be present.</para> + + <para>This patch instructs <application>&maple;</application> to + recognize <quote>FreeBSD</quote> as a type of Linux system. + The <filename>bin/maple</filename> shell script calls the + <filename>bin/maple.system.type</filename> shell script + which in turn calls <command>uname -a</command> to find out the operating + system name. Depending on the OS name it will find out which + binaries to use.</para></step> + + <step><para>Start the license server.</para> + + <para>The following script, installed as + <filename>/usr/local/etc/rc.d/lmgrd.sh</filename> is a + convenient way to start up <command>lmgrd</command>:</para> + + <programlisting> ----- snip ------------ + +#! /bin/sh +PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/X11R6/bin +PATH=${PATH}:/usr/local/maple/bin:/usr/local/maple/FLEXlm/UNIX/LINUX +export PATH + +LICENSE_FILE=/usr/local/maple/license/license.dat +LOG=/var/log/lmgrd.log + +case "$1" in +start) + lmgrd -c ${LICENSE_FILE} 2>> ${LOG} 1>&2 + echo -n " lmgrd" + ;; +stop) + lmgrd -c ${LICENSE_FILE} -x lmdown 2>> ${LOG} 1>&2 + ;; +*) + echo "Usage: `basename $0` {start|stop}" 1>&2 + exit 64 + ;; +esac + +exit 0 + ----- snip ------------</programlisting></step> + + + <step><para>Test-start <application>&maple;</application>:</para> + <screen>&prompt.user; <userinput>cd /usr/local/maple/bin</userinput> +&prompt.user; <userinput>./xmaple</userinput></screen> + + <para>You should be up and running. Make sure to write + Maplesoft to let them know you would like a native FreeBSD + version!</para></step> + </procedure> + + <sect2> + <title>Common Pitfalls</title> + + <itemizedlist> + <listitem><para>The <application>FLEXlm</application> license manager can be a difficult + tool to work with. Additional documentation on the subject + can be found at <ulink + url="http://www.globetrotter.com/"></ulink>.</para></listitem> + + <listitem><para><command>lmgrd</command> is known to be very picky + about the license file and to core dump if there are any + problems. A correct license file should look like this:</para> + +<programlisting># ======================================================= +# License File for UNIX Installations ("Pointer File") +# ======================================================= +SERVER chillig ANY +#USE_SERVER +VENDOR maplelmg + +FEATURE Maple maplelmg 2000.0831 permanent 1 XXXXXXXXXXXX \ + PLATFORMS=i86_r ISSUER="Waterloo Maple Inc." \ + ISSUED=11-may-2000 NOTICE=" Technische Universitat Wien" \ + SN=XXXXXXXXX</programlisting> + + <note><para>Serial number and key 'X''ed out. <hostid>chillig</hostid> is a + hostname.</para></note> + + <para>Editing the license file works as long as you do not + touch the <quote>FEATURE</quote> line (which is protected by the + license key).</para></listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="linuxemu-matlab"> + <sect1info> + <authorgroup> + <author> + <firstname>Dan</firstname> + <surname>Pelleg</surname> + <contrib>Contributed by </contrib> + </author> + <!-- daniel+handbook@pelleg.org --> + </authorgroup> + </sect1info> + <title>Installing &matlab;</title> + + <indexterm> + <primary>applications</primary> + <secondary><application>MATLAB</application></secondary> + </indexterm> + + <para>This document describes the process of installing the Linux + version of <application>&matlab; version 6.5</application> onto + a &os; system. It works quite well, with the exception of the + <application>&java.virtual.machine;</application> (see + <xref linkend="matlab-jre">).</para> + + <para>The Linux version of <application>&matlab;</application> can be + ordered directly from The MathWorks at <ulink + url="http://www.mathworks.com"></ulink>. Make sure you also get + the license file or instructions how to create it. While you + are there, let them know you would like a native &os; + version of their software.</para> + + <sect2> + <title>Installing &matlab;</title> + + <para>To install <application>&matlab;</application>, do the + following:</para> + + <procedure> + <step> + <para>Insert the installation CD and mount it. + Become <username>root</username>, as recommended by the + installation script. To start the installation script + type:</para> + + <screen>&prompt.root; <userinput>/compat/linux/bin/sh /cdrom/install</userinput></screen> + + <tip> + <para>The installer is graphical. If you get errors about + not being able to open a display, type + <command>setenv HOME ~<replaceable>USER</replaceable></command>, + where <replaceable>USER</replaceable> is the user you did a + &man.su.1; as.</para> + </tip> + </step> + + <step> + <para> + When asked for the <application>&matlab;</application> root + directory, type: + <userinput>/compat/linux/usr/local/matlab</userinput>.</para> + + <tip> + <para>For easier typing on the rest of the installation + process, type this at your shell prompt: + <command>set MATLAB=/compat/linux/usr/local/matlab</command></para> + </tip> + </step> + + <step> + <para>Edit the license file as instructed when + obtaining the <application>&matlab;</application> license.</para> + + <tip> + <para>You can prepare this file in advance using your + favorite editor, and copy it to + <filename>$MATLAB/license.dat</filename> before the + installer asks you to edit it.</para> + </tip> + </step> + + <step> + <para>Complete the installation process.</para> + </step> + </procedure> + + <para>At this point your <application>&matlab;</application> + installation is complete. The following steps apply + <quote>glue</quote> to connect it to your &os; system.</para> + </sect2> + + <sect2> + <title>License Manager Startup</title> + <procedure> + <step> + <para>Create symlinks for the license manager scripts:</para> + + <screen>&prompt.root; <userinput>ln -s $MATLAB/etc/lmboot /usr/local/etc/lmboot_TMW</userinput> +&prompt.root; <userinput>ln -s $MATLAB/etc/lmdown /usr/local/etc/lmdown_TMW</userinput></screen> + </step> + + <step> + <para>Create a startup file at + <filename>/usr/local/etc/rc.d/flexlm.sh</filename>. The + example below is a modified version of the distributed + <filename>$MATLAB/etc/rc.lm.glnx86</filename>. The changes + are file locations, and startup of the license manager + under Linux emulation.</para> + + <programlisting>#!/bin/sh +case "$1" in + start) + if [ -f /usr/local/etc/lmboot_TMW ]; then + /compat/linux/bin/sh /usr/local/etc/lmboot_TMW -u <replaceable>username</replaceable> && echo 'MATLAB_lmgrd' + fi + ;; + stop) + if [ -f /usr/local/etc/lmdown_TMW ]; then + /compat/linux/bin/sh /usr/local/etc/lmdown_TMW > /dev/null 2>&1 + fi + ;; + *) + echo "Usage: $0 {start|stop}" + exit 1 + ;; +esac + +exit 0</programlisting> + + <important> + <para>The file must be made executable:</para> + + <screen>&prompt.root; <userinput>chmod +x /usr/local/etc/rc.d/flexlm.sh</userinput></screen> + + <para>You must also replace + <replaceable>username</replaceable> above with the name + of a valid user on your system (and not + <username>root</username>).</para> + </important> + </step> + + <step> + <para>Start the license manager with the command:</para> + + <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/flexlm.sh start</userinput></screen> + </step> + </procedure> + </sect2> + + <sect2 id="matlab-jre"> + <title>Linking the &java; Runtime Environment</title> + + <para>Change the <application>&java;</application> Runtime + Environment (JRE) link to one working under &os;:</para> + + <screen>&prompt.root; <userinput>cd $MATLAB/sys/java/jre/glnx86/</userinput> +&prompt.root; <userinput>unlink jre; ln -s ./jre1.1.8 ./jre</userinput></screen> + </sect2> + + <sect2> + <title>Creating a &matlab; Startup Script</title> + + <procedure> + <step> + <para>Place the following startup script in + <filename>/usr/local/bin/matlab</filename>: + </para> + + <programlisting>#!/bin/sh +/compat/linux/bin/sh /compat/linux/usr/local/matlab/bin/matlab "$@"</programlisting> + </step> + + <step> + <para>Then type the command + <command>chmod +x /usr/local/bin/matlab</command>.</para> + </step> + </procedure> + + <tip> + <para>Depending on your version of + <filename role="package">emulators/linux_base</filename>, you + may run into errors when running this script. To avoid that, + edit the file + <filename>/compat/linux/usr/local/matlab/bin/matlab</filename>, + and change the line that says:</para> + + <programlisting>if [ `expr "$lscmd" : '.*->.*'` -ne 0 ]; then</programlisting> + + <para>(in version 13.0.1 it is on line 410) to this + line:</para> + + <programlisting>if test -L $newbase; then</programlisting> + </tip> + </sect2> + + <sect2> + <title>Creating a &matlab; Shutdown Script</title> + + <para>The following is needed to solve a problem with &matlab; + not exiting correctly.</para> + + <procedure> + <step> + <para>Create a file + <filename>$MATLAB/toolbox/local/finish.m</filename>, and + in it put the single line:</para> + + <programlisting>! $MATLAB/bin/finish.sh</programlisting> + + <note><para>The <literal>$MATLAB</literal> is + literal.</para></note> + + <tip> + <para>In the same directory, you will find the files + <filename>finishsav.m</filename> and + <filename>finishdlg.m</filename>, which let you save + your workspace before quitting. If you use either of + them, insert the line above immediately after the + <literal>save</literal> command.</para></tip> + </step> + + <step> + <para>Create a file + <filename>$MATLAB/bin/finish.sh</filename>, which will + contain the following:</para> + + <programlisting>#!/compat/linux/bin/sh +(sleep 5; killall -1 matlab_helper) & +exit 0</programlisting> + </step> + + <step> + <para>Make the file executable:</para> + + <screen>&prompt.root; <userinput>chmod +x $MATLAB/bin/finish.sh</userinput></screen> + </step> + </procedure> + </sect2> + + <sect2 id="matlab-using"> + <title>Using &matlab;</title> + + <para>At this point you are ready to type + <command>matlab</command> and start using it.</para> + </sect2> + </sect1> + + <sect1 id="linuxemu-oracle"> + <sect1info> + <authorgroup> + <author> + <firstname>Marcel</firstname> + <surname>Moolenaar</surname> + <contrib>Contributed by </contrib> + </author> + <!-- marcel@cup.hp.com --> + </authorgroup> + </sect1info> + <title>Installing &oracle;</title> + + <indexterm> + <primary>applications</primary> + <secondary><application>Oracle</application></secondary> + </indexterm> + + <sect2> + <title>Preface</title> + <para>This document describes the process of installing <application>&oracle; 8.0.5</application> and + <application>&oracle; 8.0.5.1 Enterprise Edition</application> for Linux onto a FreeBSD + machine.</para> + </sect2> + + <sect2> + <title>Installing the Linux Environment</title> + + <para>Make sure you have both <filename role='package'>emulators/linux_base</filename> and + <filename role='package'>devel/linux_devtools</filename> from the Ports Collection + installed. If you run into difficulties with these ports, + you may have to use + the packages or older versions available in the Ports Collection.</para> + + <para>If you want to run the intelligent agent, you will + also need to install the Red Hat Tcl package: + <filename>tcl-8.0.3-20.i386.rpm</filename>. The general command + for installing packages with the official <application>RPM</application> port (<filename role='package'>archivers/rpm</filename>) is:</para> + + <screen>&prompt.root; <userinput>rpm -i --ignoreos --root /compat/linux --dbpath /var/lib/rpm <replaceable>package</replaceable></userinput></screen> + + <para>Installation of the <replaceable>package</replaceable> should not generate any errors.</para> + </sect2> + + <sect2> + <title>Creating the &oracle; Environment</title> + + <para>Before you can install <application>&oracle;</application>, you need to set up a proper + environment. This document only describes what to do + <emphasis>specially</emphasis> to run <application>&oracle;</application> for Linux on FreeBSD, not + what has been described in the <application>&oracle;</application> installation guide.</para> + + <sect3 id="linuxemu-kernel-tuning"> + <title>Kernel Tuning</title> + <indexterm><primary>kernel tuning</primary></indexterm> + + <para>As described in the <application>&oracle;</application> installation guide, you need to set + the maximum size of shared memory. Do not use + <literal>SHMMAX</literal> under FreeBSD. <literal>SHMMAX</literal> + is merely calculated out of <literal>SHMMAXPGS</literal> and + <literal>PGSIZE</literal>. Therefore define + <literal>SHMMAXPGS</literal>. All other options can be used as + described in the guide. For example:</para> + + <programlisting>options SHMMAXPGS=10000 +options SHMMNI=100 +options SHMSEG=10 +options SEMMNS=200 +options SEMMNI=70 +options SEMMSL=61</programlisting> + + <para>Set these options to suit your intended use of <application>&oracle;</application>.</para> + + <para>Also, make sure you have the following options in your kernel + configuration file:</para> + +<programlisting>options SYSVSHM #SysV shared memory +options SYSVSEM #SysV semaphores +options SYSVMSG #SysV interprocess communication</programlisting> + </sect3> + + <sect3 id="linuxemu-oracle-account"> + + <title>&oracle; Account</title> + + <para>Create an <username>oracle</username> account just as you would create any other + account. The <username>oracle</username> account is special only that you need to give + it a Linux shell. Add <literal>/compat/linux/bin/bash</literal> to + <filename>/etc/shells</filename> and set the shell for the <username>oracle</username> + account to <filename>/compat/linux/bin/bash</filename>.</para> + </sect3> + + <sect3 id="linuxemu-environment"> + <title>Environment</title> + + <para>Besides the normal <application>&oracle;</application> variables, such as + <envar>ORACLE_HOME</envar> and <envar>ORACLE_SID</envar> you must + set the following environment variables:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"> + <colspec colwidth="2*"> + <thead> + <row> + <entry>Variable</entry> + + <entry>Value</entry> + </row> + </thead> + <tbody> + <row> + <entry><envar>LD_LIBRARY_PATH</envar></entry> + + <entry><literal>$ORACLE_HOME/lib</literal></entry> + </row> + + <row> + <entry><envar>CLASSPATH</envar></entry> + + <entry><literal>$ORACLE_HOME/jdbc/lib/classes111.zip</literal></entry> + </row> + + <row> + <entry><envar>PATH</envar></entry> + + <entry><literal>/compat/linux/bin +/compat/linux/sbin +/compat/linux/usr/bin +/compat/linux/usr/sbin +/bin +/sbin +/usr/bin +/usr/sbin +/usr/local/bin +$ORACLE_HOME/bin</literal></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>It is advised to set all the environment variables in + <filename>.profile</filename>. A complete example is:</para> + +<programlisting>ORACLE_BASE=/oracle; export ORACLE_BASE +ORACLE_HOME=/oracle; export ORACLE_HOME +LD_LIBRARY_PATH=$ORACLE_HOME/lib +export LD_LIBRARY_PATH +ORACLE_SID=ORCL; export ORACLE_SID +ORACLE_TERM=386x; export ORACLE_TERM +CLASSPATH=$ORACLE_HOME/jdbc/lib/classes111.zip +export CLASSPATH +PATH=/compat/linux/bin:/compat/linux/sbin:/compat/linux/usr/bin +PATH=$PATH:/compat/linux/usr/sbin:/bin:/sbin:/usr/bin:/usr/sbin +PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin +export PATH</programlisting> + </sect3> + </sect2> + + <sect2> + <title>Installing &oracle;</title> + + <para>Due to a slight inconsistency in the Linux emulator, you need to + create a directory named <filename>.oracle</filename> in + <filename>/var/tmp</filename> before you start the installer. + Let it be owned by the <username>oracle</username> user. You + should be able to install <application>&oracle;</application> without any problems. If you have + problems, check your <application>&oracle;</application> distribution and/or configuration first! + After you have installed <application>&oracle;</application>, apply the patches described in the + next two subsections.</para> + + <para>A frequent problem is that the TCP protocol adapter is not + installed right. As a consequence, you cannot start any TCP listeners. + The following actions help solve this problem:</para> + + <screen>&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput> +&prompt.root; <userinput>make -f ins_network.mk ntcontab.o</userinput> +&prompt.root; <userinput>cd $ORACLE_HOME/lib</userinput> +&prompt.root; <userinput>ar r libnetwork.a ntcontab.o</userinput> +&prompt.root; <userinput>cd $ORACLE_HOME/network/lib</userinput> +&prompt.root; <userinput>make -f ins_network.mk install</userinput></screen> + + <para>Do not forget to run <filename>root.sh</filename> again!</para> + + <sect3 id="linuxemu-patch-root"> + <title>Patching root.sh</title> + + <para>When installing <application>&oracle;</application>, some actions, which need to be performed + as <username>root</username>, are recorded in a shell script called + <filename>root.sh</filename>. This script is + written in the <filename>orainst</filename> directory. Apply the + following patch to <filename>root.sh</filename>, to have it use to proper location of + <command>chown</command> or alternatively run the script under a + Linux native shell.</para> + + <programlisting>*** orainst/root.sh.orig Tue Oct 6 21:57:33 1998 +--- orainst/root.sh Mon Dec 28 15:58:53 1998 +*************** +*** 31,37 **** +# This is the default value for CHOWN +# It will redefined later in this script for those ports +# which have it conditionally defined in ss_install.h +! CHOWN=/bin/chown +# +# Define variables to be used in this script +--- 31,37 ---- +# This is the default value for CHOWN +# It will redefined later in this script for those ports +# which have it conditionally defined in ss_install.h +! CHOWN=/usr/sbin/chown +# +# Define variables to be used in this script</programlisting> + + <para>When you do not install <application>&oracle;</application> from CD, you can patch the source + for <filename>root.sh</filename>. It is called + <filename>rthd.sh</filename> and is located in the + <filename>orainst</filename> directory in the source tree.</para> + </sect3> + + <sect3 id="linuxemu-patch-tcl"> + <title>Patching genclntsh</title> + + <para>The script <command>genclntsh</command> is used to create + a single shared client + library. It is used when building the demos. Apply the following + patch to comment out the definition of <envar>PATH</envar>:</para> + + <programlisting>*** bin/genclntsh.orig Wed Sep 30 07:37:19 1998 +--- bin/genclntsh Tue Dec 22 15:36:49 1998 +*************** +*** 32,38 **** +# +# Explicit path to ensure that we're using the correct commands +#PATH=/usr/bin:/usr/ccs/bin export PATH +! PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH +# +# each product MUST provide a $PRODUCT/admin/shrept.lst +--- 32,38 ---- +# +# Explicit path to ensure that we're using the correct commands +#PATH=/usr/bin:/usr/ccs/bin export PATH +! #PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin export PATH +# +# each product MUST provide a $PRODUCT/admin/shrept.lst</programlisting> + </sect3> + </sect2> + + <sect2> + <title>Running &oracle;</title> + + <para>When you have followed the instructions, you should be able to run + <application>&oracle;</application> as if it was run on Linux + itself.</para> + </sect2> + </sect1> + + <sect1 id="linuxemu-advanced"> + <title>Advanced Topics</title> + + <para>If you are curious as to how the Linux binary compatibility + works, this is the section you want to read. Most of what follows + is based heavily on an email written to &a.chat; by Terry Lambert + <email>tlambert@primenet.com</email> (Message ID: + <literal><199906020108.SAA07001@usr09.primenet.com></literal>).</para> + + <sect2> + <title>How Does It Work?</title> + <indexterm><primary>execution class loader</primary></indexterm> + + <para>FreeBSD has an abstraction called an <quote>execution class + loader</quote>. This is a wedge into the &man.execve.2; system + call.</para> + + <para>What happens is that FreeBSD has a list of loaders, instead of + a single loader with a fallback to the <literal>#!</literal> + loader for running any shell interpreters or shell scripts.</para> + + <para>Historically, the only loader on the &unix; platform examined + the magic number (generally the first 4 or 8 bytes of the file) to + see if it was a binary known to the system, and if so, invoked the + binary loader.</para> + + <para>If it was not the binary type for the system, the + &man.execve.2; call returned a failure, and the shell attempted to + start executing it as shell commands.</para> + + <para>The assumption was a default of <quote>whatever the current + shell is</quote>.</para> + + <para>Later, a hack was made for &man.sh.1; to examine the first two + characters, and if they were <literal>:\n</literal>, then it + invoked the &man.csh.1; shell instead (we believe SCO first made + this hack).</para> + + <para>What FreeBSD does now is go through a list of loaders, with a + generic <literal>#!</literal> loader that knows about interpreters + as the characters which follow to the next whitespace next to + last, followed by a fallback to + <filename>/bin/sh</filename>.</para> + <indexterm><primary>ELF</primary></indexterm> + + <para>For the Linux ABI support, FreeBSD sees the magic number as an + ELF binary (it makes no distinction between FreeBSD, &solaris;, + Linux, or any other OS which has an ELF image type, at this + point).</para> + <indexterm><primary>Solaris</primary></indexterm> + + <para>The ELF loader looks for a specialized + <emphasis>brand</emphasis>, which is a comment section in the ELF + image, and which is not present on SVR4/&solaris; ELF + binaries.</para> + + <para>For Linux binaries to function, they must be + <emphasis>branded</emphasis> as type <literal>Linux</literal> + from &man.brandelf.1;:</para> + + <screen>&prompt.root; <userinput>brandelf -t Linux file</userinput></screen> + + <para>When this is done, the ELF loader will see the + <literal>Linux</literal> brand on the file.</para> + <indexterm> + <primary>ELF</primary> + <secondary>branding</secondary> + </indexterm> + + <para>When the ELF loader sees the <literal>Linux</literal> brand, + the loader replaces a pointer in the <literal>proc</literal> + structure. All system calls are indexed through this pointer (in + a traditional &unix; system, this would be the + <literal>sysent[]</literal> structure array, containing the system + calls). In addition, the process is flagged for special handling of + the trap vector for the signal trampoline code, and several other + (minor) fix-ups that are handled by the Linux kernel + module.</para> + + <para>The Linux system call vector contains, among other things, a + list of <literal>sysent[]</literal> entries whose addresses reside + in the kernel module.</para> + + <para>When a system call is called by the Linux binary, the trap + code dereferences the system call function pointer off the + <literal>proc</literal> structure, and gets the Linux, not the + FreeBSD, system call entry points.</para> + + <para>In addition, the Linux mode dynamically + <emphasis>reroots</emphasis> lookups; this is, in effect, what the + <option>union</option> option to file system mounts + (<emphasis>not</emphasis> the <literal>unionfs</literal> file system type!) does. First, an attempt + is made to lookup the file in the + <filename>/compat/linux/<replaceable>original-path</replaceable></filename> + directory, <emphasis>then</emphasis> only if that fails, the + lookup is done in the + <filename>/<replaceable>original-path</replaceable></filename> + directory. This makes sure that binaries that require other + binaries can run (e.g., the Linux toolchain can all run under + Linux ABI support). It also means that the Linux binaries can + load and execute FreeBSD binaries, if there are no corresponding + Linux binaries present, and that you could place a &man.uname.1; + command in the <filename>/compat/linux</filename> directory tree + to ensure that the Linux binaries could not tell they were not + running on Linux.</para> + + <para>In effect, there is a Linux kernel in the FreeBSD kernel; the + various underlying functions that implement all of the services + provided by the kernel are identical to both the FreeBSD system + call table entries, and the Linux system call table entries: file + system operations, virtual memory operations, signal delivery, + System V IPC, etc… The only difference is that FreeBSD + binaries get the FreeBSD <emphasis>glue</emphasis> functions, and + Linux binaries get the Linux <emphasis>glue</emphasis> functions + (most older OS's only had their own <emphasis>glue</emphasis> + functions: addresses of functions in a static global + <literal>sysent[]</literal> structure array, instead of addresses + of functions dereferenced off a dynamically initialized pointer in + the <literal>proc</literal> structure of the process making the + call).</para> + + <para>Which one is the native FreeBSD ABI? It does not matter. + Basically the only difference is that (currently; this could + easily be changed in a future release, and probably will be after + this) the FreeBSD <emphasis>glue</emphasis> functions are + statically linked into the kernel, and the Linux <emphasis>glue</emphasis> functions + can be statically linked, or they can be accessed via a kernel + module.</para> + + <para>Yeah, but is this really emulation? No. It is an ABI + implementation, not an emulation. There is no emulator (or + simulator, to cut off the next question) involved.</para> + + <para>So why is it sometimes called <quote>Linux emulation</quote>? + To make it hard to sell FreeBSD! Really, it + is because the historical implementation was done at a time when + there was really no word other than that to describe what was + going on; saying that FreeBSD ran Linux binaries was not true, if + you did not compile the code in or load a module, and there needed + to be a word to describe what was being loaded—hence + <quote>the Linux emulator</quote>.</para> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO8859-1/books/handbook/mac/Makefile b/en_US.ISO8859-1/books/handbook/mac/Makefile new file mode 100644 index 0000000000..74aca4172f --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/mac/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= mac/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/mac/chapter.sgml b/en_US.ISO8859-1/books/handbook/mac/chapter.sgml new file mode 100644 index 0000000000..8a1082af65 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/mac/chapter.sgml @@ -0,0 +1,2085 @@ +<!-- + The FreeBSD Documentation Project + $FreeBSD$ +--> + +<chapter id="mac"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>Mandatory Access Control</title> + + <sect1 id="mac-synopsis"> + <title>Synopsis</title> + + <indexterm><primary>MAC</primary></indexterm> + <indexterm> + <primary>Mandatory Access Control</primary> + <see>MAC</see> + </indexterm> + + <para>&os; 5.X introduced new security extensions from the + TrustedBSD project based on the &posix;.1e draft. Two of the most + significant new security mechanisms are file system Access Control + Lists (<acronym>ACL</acronym>s) and Mandatory Access Control + (<acronym>MAC</acronym>) facilities. Mandatory Access Control allows + new access control modules to be loaded, implementing new security + policies. Some provide protections of a narrow subset of the + system, hardening a particular service. Others provide + comprehensive labeled security across all subjects and objects. + The mandatory part + of the definition comes from the fact that the enforcement of + the controls is done by administrators and the system, and is + not left up to the discretion of users as is done with + discretionary access control (<acronym>DAC</acronym>, the standard + file and System V <acronym>IPC</acronym> permissions on &os;).</para> + + <para>This chapter will focus on the + Mandatory Access Control Framework (<acronym>MAC</acronym> Framework), and a set + of pluggable security policy modules enabling various security + mechanisms.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>What <acronym>MAC</acronym> security policy modules are currently + included in &os; and their associated mechanisms.</para> + </listitem> + + <listitem> + <para>What <acronym>MAC</acronym> security policy modules implement as + well as the difference between a labeled and non-labeled + policy.</para> + </listitem> + + <listitem> + <para>How to efficiently configure a system to use + the <acronym>MAC</acronym> framework.</para> + </listitem> + + <listitem> + <para>How to configure the different security policy modules included with the + <acronym>MAC</acronym> framework.</para> + </listitem> + + <listitem> + <para>How to implement a more secure environment using the + <acronym>MAC</acronym> framework and the examples + shown.</para> + </listitem> + + <listitem> + <para>How to test the <acronym>MAC</acronym> configuration + to ensure the framework has been properly implemented.</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>The improper use of the + information contained herein may cause loss of system access, + aggravation of users, or inability to access the features + provided by X11. More importantly, <acronym>MAC</acronym> should not + be relied upon to completely secure a system. The + <acronym>MAC</acronym> framework only augments + existing security policy; without sound security practices and + regular security checks, the system will never be completely + secure.</para> + + <para>It should also be noted that the examples contained + within this chapter are just that, examples. It is not + recommended that these particular settings be rolled out + on a production system. Implementing the various security policy modules takes + a good deal of thought and testing. One who does not fully understand + exactly how everything works may find him or herself going + back through the entire system and reconfiguring many files + or directories.</para> + </warning> + + <sect2> + <title>What Will Not Be Covered</title> + + <para>This chapter covers a broad range of security issues relating + to the <acronym>MAC</acronym> framework. The + development of new <acronym>MAC</acronym> security policy modules + will not be covered. A number of security policy modules included with the + <acronym>MAC</acronym> framework have specific characteristics + which are provided for both testing and new module + development. These include the &man.mac.test.4;, + &man.mac.stub.4; and &man.mac.none.4;. + For more information on these security policy modules and the various + mechanisms they provide, please review the manual pages.</para> + </sect2> + </sect1> + + <sect1 id="mac-inline-glossary"> + <title>Key Terms in This Chapter</title> + + <para>Before reading this chapter, a few key terms must be + explained. This will hopefully clear up any confusion that + may occur and avoid the abrupt introduction of new terms + and information.</para> + + <itemizedlist> + <listitem> + <para><emphasis>compartment</emphasis>: A compartment is a + set of programs and data to be partitioned or separated, + where users are given explicit access to specific components + of a system. Also, a compartment represents a grouping, + such as a work group, department, project, or topic. Using + compartments, it is possible to implement a need-to-know + security policy.</para> + </listitem> + + <listitem> + <para><emphasis>high water mark</emphasis>: A high water mark + policy is one which permits the raising of security levels + for the purpose of accessing higher level information. In + most cases, the original level is restored after the process + is complete. Currently, the &os; <acronym>MAC</acronym> + framework does not have a policy for this, but the definition + is included for completeness.</para> + </listitem> + + <listitem> + <para><emphasis>integrity</emphasis>: Integrity, as a key + concept, is the level of trust which can be placed on data. + As the integrity of the data is elevated, so does the ability + to trust that data.</para> + </listitem> + + <listitem> + <para><emphasis>label</emphasis>: A label is a security + attribute which can be applied to files, directories, or + other items in the system. It could be considered + a confidentiality stamp; when a label is placed on + a file it describes the security properties for that specific + file and will only permit access by files, users, resources, + etc. with a similar security setting. The meaning and + interpretation of label values depends on the policy configuration: while + some policies might treat a label as representing the + integrity or secrecy of an object, other policies might use + labels to hold rules for access.</para> + </listitem> + + <listitem> + <para><emphasis>level</emphasis>: The increased or decreased + setting of a security attribute. As the level increases, + its security is considered to elevate as well.</para> + </listitem> + + <listitem> + <para><emphasis>low water mark</emphasis>: A low water mark + policy is one which permits lowering of the security levels + for the purpose of accessing information which is less + secure. In most cases, the original security level of the + user is restored after the process is complete. The only + security policy module in &os; to use this is + &man.mac.lomac.4;.</para> + </listitem> + + <listitem> + <para><emphasis>multilabel</emphasis>: The + <option>multilabel</option> property is a file system option + which can be set in single user mode using the + &man.tunefs.8; utility, during the boot operation + using the &man.fstab.5; file, or during the creation of + a new file system. This option will permit an administrator + to apply different <acronym>MAC</acronym> labels on different + objects. This option + only applies to security policy modules which support labeling.</para> + </listitem> + + <listitem> + <para><emphasis>object</emphasis>: An object or system + object is an entity through which information flows + under the direction of a <emphasis>subject</emphasis>. + This includes directories, files, fields, screens, keyboards, + memory, magnetic storage, printers or any other data + storage/moving device. Basically, an object is a data container or + a system resource; access to an <emphasis>object</emphasis> + effectively means access to the data.</para> + </listitem> + + <listitem> + <para><emphasis>policy</emphasis>: A collection of rules + which defines how objectives are to be achieved. A + <emphasis>policy</emphasis> usually documents how certain + items are to be handled. This chapter will + consider the term <emphasis>policy</emphasis> in this + context as a <emphasis>security policy</emphasis>; i.e. + a collection of rules which will control the flow of data + and information and define whom will have access to that + data and information.</para> + </listitem> + + <listitem> + <para><emphasis>sensitivity</emphasis>: Usually used when + discussing <acronym>MLS</acronym>. A sensitivity level is + a term used to describe how important or secret the data + should be. As the sensitivity level increases, so does the + importance of the secrecy, or confidentiality of the data.</para> + </listitem> + + <listitem> + <para><emphasis>single label</emphasis>: A single label is + when the entire file system uses one label to + enforce access control over the flow of data. When a file + system has this set, which is any time when the + <option>multilabel</option> option is not set, all + files will conform to the same label setting.</para> + </listitem> + + <listitem> + <para><emphasis>subject</emphasis>: a subject is any + active entity that causes information to flow between + <emphasis>objects</emphasis>; e.g., a user, user process, + system process, etc. On &os;, this is almost always a thread + acting in a process on behalf of a user.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="mac-initial"> + <title>Explanation of MAC</title> + + <para>With all of these new terms in mind, consider how the + <acronym>MAC</acronym> framework augments the security of + the system as a whole. The various security policy modules provided by + the <acronym>MAC</acronym> framework could be used to + protect the network and file systems, block users from + accessing certain ports and sockets, and more. Perhaps + the best use of the policy modules is to blend them together, by loading + several security policy modules at a time for a multi-layered + security environment. In a multi-layered security environment, + multiple policy modules are in effect to keep security in check. This + is different to a hardening policy, which typically hardens + elements of a system that is used only for specific purposes. + The only downside is administrative overhead in cases of + multiple file system labels, setting network access control + user by user, etc.</para> + + <para>These downsides are minimal when compared to the lasting + effect of the framework; for instance, the ability to pick and choose + which policies are required for a specific configuration keeps + performance overhead down. The reduction of support for unneeded + policies can increase the overall performance of the system as well as + offer flexibility of choice. A good implementation would + consider the overall security requirements and effectively implement + the various security policy modules offered by the framework.</para> + + <para>Thus a system utilizing <acronym>MAC</acronym> features + should at least guarantee that a user will not be permitted + to change security attributes at will; all user utilities, + programs and scripts must work within the constraints of + the access rules provided by the selected security policy modules; and + that total control of the <acronym>MAC</acronym> access + rules are in the hands of the system administrator.</para> + + <para>It is the sole duty of the system administrator to + carefully select the correct security policy modules. Some environments + may need to limit access control over the network; in these + cases, the &man.mac.portacl.4;, &man.mac.ifoff.4; and even + &man.mac.biba.4; policy modules might make good starting points. In other + cases, strict confidentiality of file system objects might + be required. Policy modules such as &man.mac.bsdextended.4; + and &man.mac.mls.4; exist for this purpose.</para> + + <para>Policy decisions could be made based on network + configuration. Perhaps only certain users should be permitted + access to facilities provided by &man.ssh.1; to access the + network or the Internet. The &man.mac.portacl.4; would be + the policy module of choice for these situations. But what should be + done in the case of file systems? Should all access to certain + directories be severed from other groups or specific + users? Or should we limit user or utility access to specific + files by setting certain objects as classified?</para> + + <para>In the file system case, access to objects might be + considered confidential to some users, but not to others. + For an example, a large development team might be broken + off into smaller groups of individuals. Developers in + project A might not be permitted to access objects written + by developers in project B. Yet they might need to access + objects created by developers in project C; that is quite a + situation indeed. Using the different security policy modules provided by + the <acronym>MAC</acronym> framework; users could + be divided into these groups and then given access to the + appropriate areas without fear of information + leakage.</para> + + <para>Thus, each security policy module has a unique way of dealing with + the overall security of a system. Module selection should be based + on a well thought out security policy. In many cases, the + overall policy may need to be revised and reimplemented on + the system. Understanding the different security policy modules offered by + the <acronym>MAC</acronym> framework will help administrators + choose the best policies for their situations.</para> + + <para>The default &os; kernel does not include the option for + the <acronym>MAC</acronym> framework; thus the following + kernel option must be added before trying any of the examples or + information in this chapter:</para> + + <programlisting>options MAC</programlisting> + + <para>And the kernel will require a rebuild and a reinstall.</para> + + <caution> + <para>While the various manual pages for <acronym>MAC</acronym> + policy modules state that they may be built into the kernel, + it is possible to lock the system out of + the network and more. Implementing <acronym>MAC</acronym> + is much like implementing a firewall, care must be taken + to prevent being completely locked out of the system. The + ability to revert back to a previous configuration should be + considered while the implementation of <acronym>MAC</acronym> + remotely should be done with extreme caution.</para> + </caution> + </sect1> + + <sect1 id="mac-understandlabel"> + <title>Understanding MAC Labels</title> + + <para>A <acronym>MAC</acronym> label is a security attribute + which may be applied to subjects and objects throughout + the system.</para> + + <para>When setting a label, the user must be able to comprehend + what it is, exactly, that is being done. The attributes + available on an object depend on the policy module loaded, and that + policy modules interpret their attributes in different + ways. If improperly configured due to lack of comprehension, or + the inability to understand the implications, the result will + be the unexpected and perhaps, undesired, behavior of the + system.</para> + + <para>The security label on an object is used as a part of a + security access control decision by a policy. With some + policies, the label by itself contains all information necessary + to make a decision; in other models, the labels may be processed + as part of a larger rule set, etc.</para> + + <para>For instance, setting the label of <literal>biba/low</literal> + on a file will represent a label maintained by the Biba security policy module, + with a value of <quote>low</quote>.</para> + + <para>A few policy modules which support the labeling feature in + &os; offer three specific predefined labels. These + are the low, high, and equal labels. Although they enforce + access control in a different manner with each policy module, you + can be sure that the low label will be the lowest setting, + the equal label will set the subject or object to be disabled + or unaffected, and the high label will enforce the highest + setting available in the Biba and <acronym>MLS</acronym> + policy modules.</para> + + <para>Within single label file system environments, only one label may be + used on objects. This will enforce one set of + access permissions across the entire system and in many + environments may be all that is required. There are a few + cases where multiple labels may be set on objects + or subjects in the file system. For those cases, the + <option>multilabel</option> option may be passed to + &man.tunefs.8;.</para> + + <para>In the case of Biba and <acronym>MLS</acronym>, a numeric + label may be set to indicate the precise level of hierarchical + control. This numeric level is used to partition or sort + information into different groups of say, classification only + permitting access to that group or a higher group level.</para> + + <para>In most cases the administrator will only be setting up a + single label to use throughout the file system.</para> + + <para><emphasis>Hey wait, this is similar to <acronym>DAC</acronym>! + I thought <acronym>MAC</acronym> gave control strictly to the + administrator.</emphasis> That statement still holds true, to some + extent as <username>root</username> is the one in control and who + configures the policies so that users are placed in the + appropriate categories/access levels. Alas, many policy modules can + restrict the <username>root</username> user as well. Basic + control over objects will then be released to the group, but + <username>root</username> may revoke or modify the settings + at any time. This is the hierarchal/clearance model covered + by policies such as Biba and <acronym>MLS</acronym>.</para> + + <sect2> + <title>Label Configuration</title> + + <para>Virtually all aspects of label policy module configuration + will be performed using the base system utilities. These + commands provide a simple interface for object or subject + configuration or the manipulation and verification of + the configuration.</para> + + <para>All configuration may be done by use of the + &man.setfmac.8; and &man.setpmac.8; utilities. + The <command>setfmac</command> command is used to set + <acronym>MAC</acronym> labels on system objects while the + <command>setpmac</command> command is used to set the labels + on system subjects. Observe:</para> + + <screen>&prompt.root; <userinput>setfmac biba/high test</userinput></screen> + + <para>If no errors occurred with the command above, a prompt + will be returned. The only time these commands are not + quiescent is when an error occurred; similarly to the + &man.chmod.1; and &man.chown.8; commands. In some cases this + error may be a <errorname>Permission denied</errorname> and + is usually obtained when the label is being set or modified + on an object which is restricted.<footnote><para>Other conditions + may produce different failures. For instance, the file may not + be owned by the user attempting to relabel the object, the + object may not exist or may be read only. A mandatory policy + will not allow the process to relabel the file, maybe because + of a property of the file, a property of the process, or a + property of the proposed new label value. For example: a user + running at low integrity tries to change the label of a high + integrity file. Or perhaps a user running at low integrity + tries to change the label of a low integrity file to a high + integrity label.</para></footnote> The system administrator + may use the following commands to overcome this:</para> + + <screen>&prompt.root; <userinput>setfmac biba/high test</userinput> +<errorname>Permission denied</errorname> +&prompt.root; <userinput>setpmac biba/low setfmac biba/high test</userinput> +&prompt.root; <userinput>getfmac test</userinput> +test: biba/high</screen> + + <para>As we see above, <command>setpmac</command> + can be used to override the policy module's settings by assigning + a different label to the invoked process. The + <command>getpmac</command> utility is usually used with currently + running processes, such as <application>sendmail</application>: + although it takes a process ID in place of + a command the logic is extremely similar. If users + attempt to manipulate a file not in their access, subject to the + rules of the loaded policy modules, the + <errorname>Operation not permitted</errorname> error + will be displayed by the <function>mac_set_link</function> + function.</para> + + <sect3> + <title>Common Label Types</title> + + <para>For the &man.mac.biba.4;, &man.mac.mls.4; and + &man.mac.lomac.4; policy modules, the ability to assign + simple labels is provided. These take the form of high, + equal and low, what follows is a brief description of + what these labels provide:</para> + + <itemizedlist> + <listitem> + <para>The <literal>low</literal> label is considered the + lowest label setting an object or subject may have. + Setting this on objects or subjects will block their + access to objects or subjects marked high.</para> + </listitem> + + <listitem> + <para>The <literal>equal</literal> label should only be + placed on objects considered to be exempt from the + policy.</para> + </listitem> + + <listitem> + <para>The <literal>high</literal> label grants an object or + subject the highest possible setting.</para> + </listitem> + </itemizedlist> + + <para>With respect to each policy module, each of those settings + will instate a different information flow directive. Reading + the proper manual pages will further explain the traits of + these generic label configurations.</para> + + <sect4> + <title>Advanced Label Configuration</title> + + <para>Numeric grade labels are used for + <literal>comparison:compartment+compartment</literal>; thus + the following:</para> + + <programlisting>biba/10:2+3+6(5:2+3-20:2+3+4+5+6)</programlisting> + + <para>May be interpreted as:</para> + + <para><quote>Biba Policy Label</quote>/<quote>Grade 10</quote> + :<quote>Compartments 2, 3 and 6</quote>: + (<quote>grade 5 ...</quote>)</para> + + <para>In this example, the first grade would be considered + the <quote>effective grade</quote> with + <quote>effective compartments</quote>, the second grade + is the low grade and the last one is the high grade. + In most configurations these settings will not be used; + indeed, they offered for more advanced + configurations.</para> + + <para>When applied to system objects, they will only have a + current grade/compartments as opposed to system subjects + as they reflect the range of available rights in the system, + and network interfaces, where they are used for access + control.</para> + + <para>The grade and compartments in a subject and object pair + are used to construct a relationship referred to as + <quote>dominance</quote>, in which a subject dominates an + object, the object dominates the subject, neither dominates + the other, or both dominate each other. The + <quote>both dominate</quote> case occurs when the two labels + are equal. Due to the information flow nature of Biba, you + have rights to a set of compartments, + <quote>need to know</quote>, that might correspond to + projects, but objects also have a set of compartments. + Users may have to subset their rights using + <command>su</command> or <command>setpmac</command> in order + to access objects in a compartment from which they are not + restricted.</para> + </sect4> + </sect3> + + <sect3> + <title>Users and Label Settings</title> + + <para>Users themselves are required to have labels so that + their files and processes may properly interact with the + security policy defined on the system. This is + configured through the <filename>login.conf</filename> file + by use of login classes. Every policy module that uses labels + will implement the user class setting.</para> + + <para>An example entry containing every policy module setting is displayed + below:</para> + + <programlisting>default:\ + :copyright=/etc/COPYRIGHT:\ + :welcome=/etc/motd:\ + :setenv=MAIL=/var/mail/$,BLOCKSIZE=K:\ + :path=~/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin:\ + :manpath=/usr/share/man /usr/local/man:\ + :nologin=/usr/sbin/nologin:\ + :cputime=1h30m:\ + :datasize=8M:\ + :vmemoryuse=100M:\ + :stacksize=2M:\ + :memorylocked=4M:\ + :memoryuse=8M:\ + :filesize=8M:\ + :coredumpsize=8M:\ + :openfiles=24:\ + :maxproc=32:\ + :priority=0:\ + :requirehome:\ + :passwordtime=91d:\ + :umask=022:\ + :ignoretime@:\ + :label=partition/13,mls/5,biba/10(5-15),lomac/10[2]:</programlisting> + + <para>The <literal>label</literal> option is used to set the + user class default label which will be enforced by + <acronym>MAC</acronym>. Users will never be permitted to + modify this value, thus it can be considered not optional + in the user case. In a real configuration, however, the + administrator will never wish to enable every policy module. + It is recommended that the rest of this chapter be reviewed + before any of this configuration is implemented.</para> + + <note> + <para>Users may change their label after the initial login; + however, this change is subject constraints of the policy. + The example above tells the Biba policy that a process's + minimum integrity is 5, its maximum is 15, but the default + effective label is 10. The process will run at 10 until + it chooses to change label, perhaps due to the user using + the setpmac command, which will be constrained by Biba to + the range set at login.</para> + </note> + + <para>In all cases, after a change to + <filename>login.conf</filename>, the login class capability + database must be rebuilt using <command>cap_mkdb</command> + and this will be reflected throughout every forthcoming + example or discussion.</para> + + <para>It is useful to note that many sites may have a + particularly large number of users requiring several + different user classes. In depth planning is required + as this may get extremely difficult to manage.</para> + </sect3> + + <sect3> + <title>Network Interfaces and Label Settings</title> + + <para>Labels may also be set on network interfaces to help + control the flow of data across the network. In all cases + they function in the same way the policies function with + respect to objects. Users at high settings in + <literal>biba</literal>, for example, will not be permitted + to access network interfaces with a label of low.</para> + + <para>The <option>maclabel</option> may be passed to + <command>ifconfig</command> when setting the + <acronym>MAC</acronym> label on network interfaces. For + example:</para> + + <screen>&prompt.root; <userinput>ifconfig bge0 maclabel biba/equal</userinput></screen> + + <para>will set the <acronym>MAC</acronym> label of + <literal>biba/equal</literal> on the &man.bge.4; interface. + When using a setting similar to + <literal>biba/high(low-high)</literal> the entire label should + be quoted; otherwise an error will be returned.</para> + + <para>Each policy module which supports labeling has a tunable + which may be used to disable the <acronym>MAC</acronym> + label on network interfaces. Setting the label to + <option>equal</option> will have a similar effect. Review + the output from <command>sysctl</command>, the policy manual + pages, or even the information found later in this chapter + for those tunables.</para> + </sect3> + </sect2> + + <sect2> + <title>Singlelabel or Multilabel?</title> +<!-- Stopped here with my edits --> + <para>By default the system will use the + <option>singlelabel</option> option. But what does this + mean to the administrator? There are several differences + which, in their own right, offer pros and cons to the + flexibility in the systems security model.</para> + + <para>The <option>singlelabel</option> only permits for one + label, for instance <literal>biba/high</literal> to be used + for each subject or object. It provides for lower + administration overhead but decreases the flexibility of + policies which support labeling. Many administrators may + want to use the <option>multilabel</option> option in + their security policy.</para> + + <para>The <option>multilabel</option> option will permit each + subject or object to have its own independent + <acronym>MAC</acronym> label in + place of the standard <option>singlelabel</option> option + which will allow only one label throughout the partition. + The <option>multilabel</option> and <option>single</option> + label options are only required for the policies which + implement the labeling feature, including the Biba, Lomac, + <acronym>MLS</acronym> and <acronym>SEBSD</acronym> + policies.</para> + + <para>In many cases, the <option>multilabel</option> may not need + to be set at all. Consider the following situation and + security model:</para> + + <itemizedlist> + <listitem> + <para>&os; web-server using the <acronym>MAC</acronym> + framework and a mix of the various policies.</para> + </listitem> + + <listitem> + <para>This machine only requires one label, + <literal>biba/high</literal>, for everything in the system. + Here the file system would not require the + <option>multilabel</option> option as a single label + will always be in effect.</para> + </listitem> + + <listitem> + <para>But, this machine will be a web server and should have + the web server run at <literal>biba/low</literal> to prevent + write up capabilities. The Biba policy and how it works + will be discussed later, so if the previous comment was + difficult to interpret just continue reading and return. + The server could use a separate partition set at + <literal>biba/low</literal> for most if not all of its + runtime state. Much is lacking from this example, for + instance the restrictions on data, configuration and user + settings; however, this is just a quick example to prove the + aforementioned point.</para> + </listitem> + </itemizedlist> + + <para>If any of the non-labeling policies are to be used, + then the <option>multilabel</option> option would never + be required. These include the <literal>seeotheruids</literal>, + <literal>portacl</literal> and <literal>partition</literal> + policies.</para> + + <para>It should also be noted that using + <option>multilabel</option> with a partition and establishing + a security model based on <option>multilabel</option> + functionality could open the doors for higher administrative + overhead as everything in the file system would have a label. + This includes directories, files, and even device + nodes.</para> + + <para>The following command will set <option>multilabel</option> + on the file systems to have multiple labels. This may only be + done in single user mode:</para> + + <screen>&prompt.root; <userinput>tunefs -l enable /</userinput></screen> + + <para>This is not a requirement for the swap file + system.</para> + + <note> + <para>Some users have experienced problems with setting the + <option>multilabel</option> flag on the root partition. + If this is the case, please review the + <xref linkend="mac-troubleshoot"> of this chapter.</para> + </note> + </sect2> + </sect1> + + <sect1 id="mac-planning"> + <title>Planning the Security Configuration</title> + + <para>Whenever a new technology is implemented, a planning phase is + always a good idea. During the planning stages, an administrator + should in general look at the <quote>big picture</quote>, trying + to keep in view at least the following:</para> + + <itemizedlist> + <listitem> + <para>The implementation requirements;</para> + </listitem> + + <listitem> + <para>The implementation goals;</para> + </listitem> + </itemizedlist> + + <para>For <acronym>MAC</acronym> installations, these include:</para> + + <itemizedlist> + <listitem> + <para>How to classify information and resources available on + the target systems.</para> + </listitem> + + <listitem> + <para>What sorts of information or resources to restrict + access to along with the type of restrictions that should be + applied.</para> + </listitem> + + <listitem> + <para>Which <acronym>MAC</acronym> module or modules will be + required to achieve this goal.</para> + </listitem> + </itemizedlist> + + <para>It is always possible to reconfigure and change the + system resources and security settings, it is quite often very inconvenient to + search through the system and fix existing files and user + accounts. Planning helps to ensure a trouble-free and efficient + trusted system implementation. A trial run of the trusted system, + including the configuration, is often vital and definitely + beneficial <emphasis>before</emphasis> a <acronym>MAC</acronym> + implementation is used on production systems. The idea of just + letting loose on a system + with <acronym>MAC</acronym> is like setting up for failure.</para> + + <para>Different environments may have explicit needs and + requirements. Establishing an in depth and complete security + profile will decrease the need of changes once the system + goes live. As such, the future sections will cover the + different modules available to administrators; describe their + use and configuration; and in some cases provide insight on + what situations they would be most suitable for. For instance, + a web server might roll out the &man.mac.biba.4; and + &man.mac.bsdextended.4; policies. In other cases, a machine + with very few local users, the &man.mac.partition.4; might + be a good choice.</para> + </sect1> + + <sect1 id="mac-modules"> + <title>Module Configuration</title> + + <para>Every module included with the <acronym>MAC</acronym> + framework may be either compiled into the kernel as noted above + or loaded as a run-time kernel module. + The recommended method is to add the module name to the + <filename>/boot/loader.conf</filename> file so that it will load + during the initial boot operation.</para> + + <para>The following sections will discuss the various + <acronym>MAC</acronym> modules and cover their features. + Implementing them into a specific environment will also + be a consideration of this chapter. Some modules support + the use of labeling, which is controlling access by enforcing + a label such as <quote>this is allowed and this is not</quote>. + A label configuration file may control how files may be accessed, + network communication can be exchanged, and more. The previous + section showed how the <option>multilabel</option> flag could + be set on file systems to enable per-file or per-partition + access control.</para> + + <para>A single label configuration would enforce only one label + across the system, that is why the <command>tunefs</command> + option is called <option>multilabel</option>.</para> + </sect1> + + <sect1 id="mac-seeotheruids"> + <title>The MAC seeotheruids Module</title> + + <indexterm> + <primary>MAC See Other UIDs Policy</primary> + </indexterm> + <para>Module name: <filename>mac_seeotheruids.ko</filename></para> + + <para>Kernel configuration line: + <literal>options MAC_SEEOTHERUIDS</literal></para> + + <para>Boot option: + <literal>mac_seeotheruids_load="YES"</literal></para> + + <para>The &man.mac.seeotheruids.4; module mimics and extends + the <literal>security.bsd.see_other_uids</literal> and + <literal>security.bsd.see_other_gids</literal> + <command>sysctl</command> tunables. This option does + not require any labels to be set before configuration and + can operate transparently with the other modules.</para> + + <para>After loading the module, the following + <command>sysctl</command> tunables may be used to control + the features:</para> + + <itemizedlist> + <listitem> + <para><literal>security.mac.seeotheruids.enabled</literal> + will enable the module's features and use the default + settings. These default settings will deny users the + ability to view processes and sockets owned by other + users.</para> + </listitem> + + <listitem> + <para> + <literal>security.mac.seeotheruids.specificgid_enabled</literal> + will allow a certain group to be exempt from this policy. + To exempt specific groups from this policy, use the + <literal>security.mac.seeotheruids.specificgid=<replaceable>XXX</replaceable></literal> + <command>sysctl</command> tunable. In the above example, + the <replaceable>XXX</replaceable> should be replaced with the + numeric group ID to be exempted.</para> + </listitem> + + <listitem> + <para> + <literal>security.mac.seeotheruids.primarygroup_enabled</literal> + is used to exempt specific primary groups from this policy. + When using this tunable, the + <literal>security.mac.seeotheruids.specificgid_enabled</literal> + may not be set.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="mac-bsdextended"> + <title>The MAC bsdextended Module</title> + + <indexterm> + <primary>MAC</primary> + <secondary>File System Firewall Policy</secondary> + </indexterm> + <para>Module name: <filename>mac_bsdextended.ko</filename></para> + + <para>Kernel configuration line: + <literal>options MAC_BSDEXTENDED</literal></para> + + <para>Boot option: + <literal>mac_bsdextended_load="YES"</literal></para> + + <para>The &man.mac.bsdextended.4; module enforces the file system + firewall. This module's policy provides an extension to the + standard file system permissions model, permitting an + administrator to create a firewall-like ruleset to protect files, + utilities, and directories in the file system hierarchy. When + access to a file system object is attempted, the list of rules + is iterated until either a matching rule is located or the end + is reached. This behavior may be changed by the use of a + &man.sysctl.8; parameter, + security.mac.bsdextended.firstmatch_enabled. Similar to + other firewall modules in &os;, a file containing access control + rules can be created and read by the system at boot time using + an &man.rc.conf.5; variable.</para> + + <para>The rule list may be entered using a utility, &man.ugidfw.8;, + that has a syntax similar to that of &man.ipfw.8;. More tools + can be written by using the functions in the + &man.libugidfw.3; library.</para> + + <para>Extreme caution should be taken when working with this + module; incorrect use could block access to certain parts of + the file system.</para> + + <sect2> + <title>Examples</title> + + <para>After the &man.mac.bsdextended.4; module has + been loaded, the following command may be used to list the + current rule configuration:</para> + + <screen>&prompt.root; <userinput>ugidfw list</userinput> +0 slots, 0 rules</screen> + + <para>As expected, there are no rules defined. This means that + everything is still completely accessible. To create a rule + which will block all access by users but leave + <username>root</username> unaffected, simply run the + following command:</para> + + <screen>&prompt.root; <userinput>ugidfw add subject not uid root new object not uid root mode n</userinput></screen> + + <para>This is a very bad idea as it will block all users from + issuing even the most simple commands, such as + <command>ls</command>. A more patriotic list of rules + might be:</para> + + <screen>&prompt.root; <userinput>ugidfw set 2 subject uid <replaceable>user1</replaceable> object uid <replaceable>user2</replaceable> mode n</userinput> +&prompt.root; <userinput>ugidfw set 3 subject uid <replaceable>user1</replaceable> object gid <replaceable>user2</replaceable> mode n</userinput></screen> + + <para>This will block any and all access, including directory + listings, to <username><replaceable>user2</replaceable></username>'s home + directory from the username <username>user1</username>.</para> + + <para>In place of <username>user1</username>, the + <option>not uid <replaceable>user2</replaceable></option> could + be passed. This will enforce the same access restrictions + above for all users in place of just one user.</para> + + <note> + <para>The <username>root</username> user will be unaffected + by these changes.</para> + </note> + + <para>This should provide a general idea of how the + &man.mac.bsdextended.4; module may be used to help fortify + a file system. For more information, see the + &man.mac.bsdextended.4; and the &man.ugidfw.8; manual + pages.</para> + </sect2> + </sect1> + + <sect1 id="mac-ifoff"> + <title>The MAC ifoff Module</title> + + <indexterm> + <primary>MAC Interface Silencing Policy</primary> + </indexterm> + <para>Module name: <filename>mac_ifoff.ko</filename></para> + + <para>Kernel configuration line: + <literal>options MAC_IFOFF</literal></para> + + <para>Boot option: <literal>mac_ifoff_load="YES"</literal></para> + + <para>The &man.mac.ifoff.4; module exists solely to disable network + interfaces on the fly and keep network interfaces from being + brought up during the initial system boot. It does not require + any labels to be set up on the system, nor does it have a + dependency on other <acronym>MAC</acronym> modules.</para> + + <para>Most of the control is done through the + <command>sysctl</command> tunables listed below.</para> + + <itemizedlist> + <listitem> + <para><literal>security.mac.ifoff.lo_enabled</literal> will + enable/disable all traffic on the loopback (&man.lo.4;) + interface.</para> + </listitem> + + <listitem> + <para><literal>security.mac.ifoff.bpfrecv_enabled</literal> will + enable/disable all traffic on the Berkeley Packet Filter + interface (&man.bpf.4;)</para> + </listitem> + + <listitem> + <para><literal>security.mac.ifoff.other_enabled</literal> will + enable/disable traffic on all other interfaces.</para> + </listitem> + </itemizedlist> + + <para>One of the most common uses of &man.mac.ifoff.4; is network + monitoring in an environment where network traffic should not + be permitted during the boot sequence. Another suggested use + would be to write a script which uses + <filename role="package">security/aide</filename> to automatically + block network traffic if it finds new or altered files in + protected directories.</para> + </sect1> + + <sect1 id="mac-portacl"> + <title>The MAC portacl Module</title> + + <indexterm> + <primary>MAC Port Access Control List Policy</primary> + </indexterm> + <para>Module name: <filename>mac_portacl.ko</filename></para> + + <para>Kernel configuration line: + <literal>MAC_PORTACL</literal></para> + + <para>Boot option: <literal>mac_portacl_load="YES"</literal></para> + + <para>The &man.mac.portacl.4; module is used to limit binding to + local <acronym>TCP</acronym> and <acronym>UDP</acronym> ports + using a variety of <command>sysctl</command> variables. In + essence &man.mac.portacl.4; makes it possible to allow + non-<username>root</username> users to bind to specified + privileged ports, i.e., ports below 1024.</para> + + <para>Once loaded, this module will enable the + <acronym>MAC</acronym> policy on all sockets. The following + tunables are available:</para> + + <itemizedlist> + <listitem> + <para><literal>security.mac.portacl.enabled</literal> will + enable/disable the policy completely.</para> + </listitem> + + <listitem> + <para><literal>security.mac.portacl.port_high</literal> will set + the highest port number that &man.mac.portacl.4; + will enable protection for.</para> + </listitem> + + <listitem> + <para><literal>security.mac.portacl.suser_exempt</literal> will, + when set to a non-zero value, exempt the + <username>root</username> user from this policy.</para> + </listitem> + + <listitem> + <para><literal>security.mac.portacl.rules</literal> will + specify the actual mac_portacl policy; see below.</para> + </listitem> + </itemizedlist> + + <para>The actual <literal>mac_portacl</literal> policy, as + specified in the <literal>security.mac.portacl.rules</literal> + sysctl, is a text string of the form: + <literal>rule[,rule,...]</literal> with as many rules as + needed. Each rule is of the form: + <literal>idtype:id:protocol:port</literal>. The + <parameter>idtype</parameter> parameter can be + <literal>uid</literal> or <literal>gid</literal> and used to + interpret the <parameter>id</parameter> parameter as either a + user id or group id, respectively. The + <parameter>protocol</parameter> parameter is used to determine if + the rule should apply to <acronym>TCP</acronym> or + <acronym>UDP</acronym> by setting the parameter to + <literal>tcp</literal> or <literal>udp</literal>. The final + <parameter>port</parameter> parameter is the port number to allow + the specified user or group to bind to.</para> + + <note> + <para>Since the ruleset is interpreted directly by the kernel + only numeric values can be used for the user ID, group ID, and + port parameters. Names cannot be used for users, groups, or + services.</para> + </note> + + <para>By default, on &unix;-like systems, ports below 1024 + can only be used by/bound to privileged processes, + i.e., those run as <username>root</username>. For + &man.mac.portacl.4; to allow non-privileged processes to bind + to ports below 1024 this standard &unix; restriction has to be + disabled. This can be accomplished by setting the &man.sysctl.8; + variables <literal>net.inet.ip.portrange.reservedlow</literal> and + <literal>net.inet.ip.portrange.reservedhigh</literal> + to zero.</para> + + <para>See the examples below or review the &man.mac.portacl.4; + manual page for further information.</para> + + <sect2> + <title>Examples</title> + + <para>The following examples should illuminate the above + discussion a little better:</para> + + <screen>&prompt.root; <userinput>sysctl security.mac.portacl.port_high=1023</userinput> +&prompt.root; <userinput>sysctl net.inet.ip.portrange.reservedlow=0 net.inet.ip.portrange.reservedhigh=0</userinput></screen> + + <para>First we set &man.mac.portacl.4; to cover the standard + privileged ports and disable the normal &unix; bind + restrictions.</para> + + <screen>&prompt.root; <userinput>sysctl security.mac.portacl.suser_exempt=1</userinput></screen> + + <para>The <username>root</username> user should not be crippled + by this policy, thus set the + <literal>security.mac.portacl.suser_exempt</literal> to a + non-zero value. The &man.mac.portacl.4; module + has now been set up to behave the same way &unix;-like systems + behave by default.</para> + + <screen>&prompt.root; <userinput>sysctl security.mac.portacl.rules=uid:80:tcp:80</userinput></screen> + + <para>Allow the user with <acronym>UID</acronym> 80 (normally + the <username>www</username> user) to bind to port 80. + This can be used to allow the <username>www</username> + user to run a web server without ever having + <username>root</username> privilege.</para> + + <screen>&prompt.root; <userinput>sysctl security.mac.portacl.rules=uid:1001:tcp:110,uid:1001:tcp:995</userinput></screen> + + <para>Permit the user with the <acronym>UID</acronym> of + 1001 to bind to the <acronym>TCP</acronym> ports 110 + (<quote>pop3</quote>) and 995 (<quote>pop3s</quote>). + This will permit this user to start a server that accepts + connections on ports 110 and 995.</para> + </sect2> + </sect1> + + <sect1 id="mac-partition"> + <title>The MAC partition Module</title> + + <indexterm> + <primary>MAC Process Partition Policy</primary> + </indexterm> + <para>Module name: <filename>mac_partition.ko</filename></para> + + <para>Kernel configuration line: + <literal>options MAC_PARTITION</literal></para> + + <para>Boot option: + <literal>mac_partition_load="YES"</literal></para> + + <para>The &man.mac.partition.4; policy will drop processes into + specific <quote>partitions</quote> based on their + <acronym>MAC</acronym> label. Think of it as a special + type of &man.jail.8;, though that is hardly a worthy + comparison.</para> + + <para>This is one module that should be added to the + &man.loader.conf.5; file so that it loads + and enables the policy during the boot process.</para> + + <para>Most configuration for this policy is done using + the &man.setpmac.8; utility which will be explained below. + The following <command>sysctl</command> tunable is + available for this policy:</para> + + <itemizedlist> + <listitem> + <para><literal>security.mac.partition.enabled</literal> will + enable the enforcement of <acronym>MAC</acronym> process + partitions.</para> + </listitem> + </itemizedlist> + + <para>When this policy is enabled, users will only be permitted + to see their processes, and any others within their partition, + but will not be permitted to work with + utilities outside the scope of this partition. For instance, a user in the + <literal>insecure</literal> class above will not be permitted + to access the <command>top</command> command as well as many + other commands that must spawn a process.</para> + + <para>To set or drop utilities into a partition label, use the + <command>setpmac</command> utility:</para> + + <screen>&prompt.root; <userinput>setpmac partition/13 top</userinput></screen> + + <para>This will add the <command>top</command> command to the + label set on users in the <literal>insecure</literal> class. + Note that all processes spawned by users + in the <literal>insecure</literal> class will stay in the + <literal>partition/13</literal> label.</para> + + <sect2> + <title>Examples</title> + + <para>The following command will show you the partition label + and the process list:</para> + + <screen>&prompt.root; <userinput>ps Zax</userinput></screen> + + <para>This next command will allow the viewing of another + user's process partition label and that user's currently + running processes:</para> + + <screen>&prompt.root; <userinput>ps -ZU trhodes</userinput></screen> + + <note> + <para>Users can see processes in <username>root</username>'s + label unless the &man.mac.seeotheruids.4; policy is + loaded.</para> + </note> + + <para>A really crafty implementation could have all of the + services disabled in <filename>/etc/rc.conf</filename> and + started by a script that starts them with the proper + labeling set.</para> + + <note> + <para>The following policies support integer settings + in place of the three default labels offered. These options, + including their limitations, are further explained in + the module manual pages.</para> + </note> + </sect2> + </sect1> + + <sect1 id="mac-mls"> + <title>The MAC Multi-Level Security Module</title> + + <indexterm> + <primary>MAC Multi-Level Security Policy</primary> + </indexterm> + <para>Module name: <filename>mac_mls.ko</filename></para> + + <para>Kernel configuration line: + <literal>options MAC_MLS</literal></para> + + <para>Boot option: <literal>mac_mls_load="YES"</literal></para> + + <para>The &man.mac.mls.4; policy controls access between subjects + and objects in the system by enforcing a strict information + flow policy.</para> + + <para>In <acronym>MLS</acronym> environments, a + <quote>clearance</quote> level is set in each subject or objects + label, along with compartments. Since these clearance or + sensibility levels can reach numbers greater than six thousand; + it would be a daunting task for any system administrator to + thoroughly configure each subject or object. Thankfully, three + <quote>instant</quote> labels are already included in this + policy.</para> + + <para>These labels are <literal>mls/low</literal>, + <literal>mls/equal</literal> and <literal>mls/high</literal>. + Since these labels are described in depth in the manual page, + they will only get a brief description here:</para> + + <itemizedlist> + <listitem> + <para>The <literal>mls/low</literal> label contains a low + configuration which permits it to be dominated by all other + objects. Anything labeled with <literal>mls/low</literal> + will have a low clearance level and not be permitted to access + information of a higher level. In addition, this label will + prevent objects of a higher clearance level from writing or + passing information on to them.</para> + </listitem> + + <listitem> + <para>The <literal>mls/equal</literal> label should be + placed on objects considered to be exempt from the + policy.</para> + </listitem> + + <listitem> + <para>The <literal>mls/high</literal> label is the highest level + of clearance possible. Objects assigned this label will + hold dominance over all other objects in the system; however, + they will not permit the leaking of information to objects + of a lower class.</para> + </listitem> + </itemizedlist> + + <para><acronym>MLS</acronym> provides for:</para> + + <itemizedlist> + <listitem> + <para>A hierarchical security level with a set of non + hierarchical categories;</para> + </listitem> + + <listitem> + <para>Fixed rules: no read up, no write down (a subject can + have read access to objects on its own level or below, but + not above. Similarly, a subject can have write access to + objects on its own level or above but not beneath.);</para> + </listitem> + + <listitem> + <para>Secrecy (preventing inappropriate disclosure + of data);</para> + </listitem> + + <listitem> + <para>Basis for the design of systems that concurrently handle + data at multiple sensitivity levels (without leaking + information between secret and confidential).</para> + </listitem> + </itemizedlist> + + <para>The following <command>sysctl</command> tunables are + available for the configuration of special services and + interfaces:</para> + + <itemizedlist> + <listitem> + <para><literal>security.mac.mls.enabled</literal> is used to + enable/disable the <acronym>MLS</acronym> policy.</para> + </listitem> + + <listitem> + <para><literal>security.mac.mls.ptys_equal</literal> will label + all &man.pty.4; devices as <literal>mls/equal</literal> during + creation.</para> + </listitem> + + <listitem> + <para><literal>security.mac.mls.revocation_enabled</literal> is + used to revoke access to objects after their label changes + to a label of a lower grade.</para> + </listitem> + + <listitem> + <para><literal>security.mac.mls.max_compartments</literal> is + used to set the maximum number of compartment levels with + objects; basically the maximum compartment number allowed + on a system.</para> + </listitem> + </itemizedlist> + + <para>To manipulate the <acronym>MLS</acronym> labels, the + &man.setfmac.8; command has been provided. To assign a label + to an object, issue the following command:</para> + + <screen>&prompt.root; <userinput>setfmac mls/5 test</userinput></screen> + + <para>To get the <acronym>MLS</acronym> label for the file + <filename>test</filename> issue the following command:</para> + + <screen>&prompt.root; <userinput>getfmac test</userinput></screen> + + <para>This is a summary of the <acronym>MLS</acronym> + policy's features. Another approach is to create a master policy + file in <filename class="directory">/etc</filename> which + specifies the <acronym>MLS</acronym> policy information and to + feed that file into the <command>setfmac</command> command. This + method will be explained after all policies are covered.</para> + + <sect2> + <title>Planning Mandatory Sensitivity</title> + + <para>With the Multi-Level Security Policy Module, an + administrator plans for controlling the flow of sensitive + information. By default, with its block read up block write + down nature, the system defaults everything to a low state. + Everything is accessible and an administrator + slowly changes this during the configuration stage; augmenting + the confidentiality of the information.</para> + + <para>Beyond the three basic label options above, an administrator + may group users and groups as required to block the information + flow between them. It might be easier to look at the + information in clearance levels familiarized with words, for + instance classifications such as + <literal>Confidential</literal>, <literal>Secret</literal>, + and <literal>Top Secret</literal>. Some administrators might + just create different groups based on project levels. + Regardless of classification method, a well thought out plan + must exist before implementing such a restrictive policy.</para> + + <para>Some example situations for this security policy module + could be an e-commerce web server, a file server holding critical + company information, and financial institution environments. + The most unlikely place would be a personal workstation with + only two or three users.</para> + </sect2> + </sect1> + + <sect1 id="mac-biba"> + <title>The MAC Biba Module</title> + + <indexterm> + <primary>MAC Biba Integrity Policy</primary> + </indexterm> + <para>Module name: <filename>mac_biba.ko</filename></para> + + <para>Kernel configuration line: <literal>options MAC_BIBA</literal></para> + + <para>Boot option: <literal>mac_biba_load="YES"</literal></para> + + <para>The &man.mac.biba.4; module loads the <acronym>MAC</acronym> + Biba policy. This policy works much like that of the + <acronym>MLS</acronym> policy with the exception that the rules + for information flow + are slightly reversed. This is said to prevent the downward + flow of sensitive information whereas the <acronym>MLS</acronym> + policy prevents the upward flow of sensitive information; thus, + much of this section can apply to both policies.</para> + + <para>In Biba environments, an <quote>integrity</quote> label is + set on each subject or object. These labels are made up of + hierarchal grades, and non-hierarchal components. As an object's + or subject's grade ascends, so does its integrity.</para> + + <para>Supported labels are <literal>biba/low</literal>, + <literal>biba/equal</literal>, and <literal>biba/high</literal>; + as explained below:</para> + + <itemizedlist> + <listitem> + <para>The <literal>biba/low</literal> label is considered the + lowest integrity an object or subject may have. Setting + this on objects or subjects will block their write access + to objects or subjects marked high. They still have read + access though.</para> + </listitem> + + <listitem> + <para>The <literal>biba/equal</literal> label should only be + placed on objects considered to be exempt from the + policy.</para> + </listitem> + + <listitem> + <para>The <literal>biba/high</literal> label will permit + writing to objects set at a lower label, but not + permit reading that object. It is recommended that this + label be placed on objects that affect the integrity of + the entire system.</para> + </listitem> + </itemizedlist> + + <para>Biba provides for:</para> + + <itemizedlist> + <listitem> + <para>Hierarchical integrity level with a set of non + hierarchical integrity categories;</para> + </listitem> + + <listitem> + <para>Fixed rules: no write up, no read down (opposite of + <acronym>MLS</acronym>). A subject can have write access + to objects on its own level or below, but not above. Similarly, a + subject can have read access to objects on its own level + or above, but not below;</para> + </listitem> + + <listitem> + <para>Integrity (preventing inappropriate modification of + data);</para> + </listitem> + + <listitem> + <para>Integrity levels (instead of MLS sensitivity + levels).</para> + </listitem> + </itemizedlist> + + <para>The following <command>sysctl</command> tunables can + be used to manipulate the Biba policy.</para> + + <itemizedlist> + <listitem> + <para><literal>security.mac.biba.enabled</literal> may be used + to enable/disable enforcement of the Biba policy on the + target machine.</para> + </listitem> + + <listitem> + <para><literal>security.mac.biba.ptys_equal</literal> may be + used to disable the Biba policy on &man.pty.4; + devices.</para> + </listitem> + + <listitem> + <para><literal>security.mac.biba.revocation_enabled</literal> + will force the revocation of access to objects if the label + is changed to dominate the subject.</para> + </listitem> + </itemizedlist> + + <para>To access the Biba policy setting on system objects, use + the <command>setfmac</command> and <command>getfmac</command> + commands:</para> + + <screen>&prompt.root; <userinput>setfmac biba/low test</userinput> +&prompt.root; <userinput>getfmac test</userinput> +test: biba/low</screen> + + <sect2> + <title>Planning Mandatory Integrity</title> + + <para>Integrity, different from sensitivity, guarantees that the + information will never be manipulated by untrusted parties. + This includes information passed between subjects, objects, + and both. It ensures that users will only be able to modify + and in some cases even access information they explicitly need + to.</para> + + <para>The &man.mac.biba.4; security policy module permits an + administrator to address which files and programs a user or + users may see and invoke while assuring that the programs and + files are free from threats and trusted by the system for that + user, or group of users.</para> + + <para>During the initial planning phase, an administrator must be + prepared to partition users into grades, levels, and areas. + Users will be blocked access not only to data but programs + and utilities both before and after they start. The system will + default to a high label once this policy module is enabled, and + it is up to the administrator to configure the different grades + and levels for users. Instead of using clearance levels as + described above, a good planning method could include topics. + For instance, only allow developers modification access to the source code + repository, source code compiler, and other development + utilities. While other users would be grouped into other + categories such as testers, designers, or just ordinary + users and would only be permitted read access.</para> + + <para>With its natural security control, a lower integrity subject + is unable to write to a higher integrity subject; a higher + integrity subject cannot observe or read a lower integrity + object. Setting a label at the lowest possible grade could make + it inaccessible to subjects. Some prospective environments for + this security policy module would include a constrained web + server, development and test machine, and source code + repository. A less useful implementation would be a personal + workstation, a machine used as a router, or a network + firewall.</para> + </sect2> + </sect1> + + <sect1 id="mac-lomac"> + <title>The MAC LOMAC Module</title> + + <indexterm> + <primary>MAC LOMAC</primary> + </indexterm> + <para>Module name: <filename>mac_lomac.ko</filename></para> + + <para>Kernel configuration line: <literal>options MAC_LOMAC</literal></para> + <para>Boot option: <literal>mac_lomac_load="YES"</literal></para> + + <para>Unlike the <acronym>MAC</acronym> Biba policy, the + &man.mac.lomac.4; policy permits access to lower integrity + objects only after decreasing the integrity level to not disrupt + any integrity rules.</para> + + <para>The <acronym>MAC</acronym> version of the Low-watermark + integrity policy, not to be confused with the older &man.lomac.4; + implementation, works almost identically to Biba, but with the + exception of using floating labels to support subject + demotion via an auxiliary grade compartment. This secondary + compartment takes the form of <literal>[auxgrade]</literal>. + When assigning a lomac policy with an auxiliary grade, it + should look a little bit like: <literal>lomac/10[2]</literal> + where the number two (2) is the auxiliary grade.</para> + + <para>The <acronym>MAC</acronym> LOMAC policy relies on the + ubiquitous labeling of all system objects with integrity labels, + permitting subjects to read from low integrity objects and then + downgrading the label on the subject to prevent future writes to + high integrity objects. This is the + <literal>[auxgrade]</literal> option discussed above, thus the + policy may provide for greater compatibility and require less + initial configuration than Biba.</para> + + <sect2> + <title>Examples</title> + + <para>Like the Biba and <acronym>MLS</acronym> policies; + the <command>setfmac</command> and <command>setpmac</command> + utilities may be used to place labels on system objects:</para> + + <screen>&prompt.root; <userinput>setfmac /usr/home/trhodes lomac/high[low]</userinput> +&prompt.root; <userinput>getfmac /usr/home/trhodes</userinput> lomac/high[low]</screen> + + <para>Notice the auxiliary grade here is <literal>low</literal>, + this is a feature provided only by the <acronym>MAC</acronym> + LOMAC policy.</para> + </sect2> + </sect1> + + <sect1 id="mac-implementing"> + <title>Nagios in a MAC Jail</title> + + <indexterm> + <primary>Nagios in a MAC Jail</primary> + </indexterm> + + <para>The following demonstration will implement a secure + environment using various <acronym>MAC</acronym> modules + with properly configured policies. This is only a test and + should not be considered the complete answer to everyone's + security woes. Just implementing a policy and ignoring it + never works and could be disastrous in a production + environment.</para> + + <para>Before beginning this process, the + <literal>multilabel</literal> option must be set on each file + system as stated at the beginning of this chapter. Not doing + so will result in errors. While at it, ensure that the + <filename role="package">net-mngt/nagios-plugins</filename>, + <filename role="package">net-mngt/nagios</filename>, and + <filename role="package">www/apache22</filename> ports are all + installed, configured, and working correctly.</para> + + <sect2> + <title>Create an insecure User Class</title> + + <para>Begin the procedure by adding the following user class + to the <filename>/etc/login.conf</filename> file:</para> + + <programlisting>insecure:\ +:copyright=/etc/COPYRIGHT:\ +:welcome=/etc/motd:\ +:setenv=MAIL=/var/mail/$,BLOCKSIZE=K:\ +:path=~/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin +:manpath=/usr/share/man /usr/local/man:\ +:nologin=/usr/sbin/nologin:\ +:cputime=1h30m:\ +:datasize=8M:\ +:vmemoryuse=100M:\ +:stacksize=2M:\ +:memorylocked=4M:\ +:memoryuse=8M:\ +:filesize=8M:\ +:coredumpsize=8M:\ +:openfiles=24:\ +:maxproc=32:\ +:priority=0:\ +:requirehome:\ +:passwordtime=91d:\ +:umask=022:\ +:ignoretime@:\ +:label=biba/10(10-10):</programlisting> + + <para>And adding the following line to the default user + class:</para> + + <programlisting>:label=biba/high:</programlisting> + + <para>Once this is completed, the following command must be + issued to rebuild the database:</para> + + <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen> + </sect2> + + <sect2> + <title>Boot Configuration</title> + + <para>Do not reboot yet, just add the following lines to + <filename>/boot/loader.conf</filename> so the required + modules will load during system initialization:</para> + + <programlisting>mac_biba_load="YES" +mac_seeotheruids_load="YES"</programlisting> + </sect2> + + <sect2> + <title>Configure Users</title> + + <para>Set the <username>root</username> user to the default + class using:</para> + + <screen>&prompt.root; <userinput>pw usermod root -L default</userinput></screen> + + <para>All user accounts that are not <username>root</username> + or system users will now require a login class. The login + class is required otherwise users will be refused access + to common commands such as &man.vi.1;. + The following <command>sh</command> script should do the + trick:</para> + + <screen>&prompt.root; <userinput>for x in `awk -F: '($3 >= 1001) && ($3 != 65534) { print $1 }' \</userinput> + <userinput>/etc/passwd`; do pw usermod $x -L default; done;</userinput></screen> + + <para>Drop the <username>nagios</username> and + <username>www</username> users into the insecure class:</para> + + <screen>&prompt.root; <userinput>pw usermod nagios -L insecure</userinput></screen> + <screen>&prompt.root; <userinput>pw usermod www -L insecure</userinput></screen> + </sect2> + + <sect2> + <title>Create the Contexts File</title> + + <para>A contexts file should now be created; the following example + file should be placed in + <filename>/etc/policy.contexts</filename>.</para> + + <programlisting># This is the default BIBA policy for this system. + +# System: +/var/run biba/equal +/var/run/* biba/equal + +/dev biba/equal +/dev/* biba/equal + +/var biba/equal +/var/spool biba/equal +/var/spool/* biba/equal + +/var/log biba/equal +/var/log/* biba/equal + +/tmp biba/equal +/tmp/* biba/equal +/var/tmp biba/equal +/var/tmp/* biba/equal + +/var/spool/mqueue biba/equal +/var/spool/clientmqueue biba/equal + +# For Nagios: +/usr/local/etc/nagios +/usr/local/etc/nagios/* biba/10 + +/var/spool/nagios biba/10 +/var/spool/nagios/* biba/10 + +# For apache +/usr/local/etc/apache biba/10 +/usr/local/etc/apache/* biba/10</programlisting> + + <para>This policy will enforce security by setting restrictions + on the flow of information. In this specific configuration, + users, <username>root</username> and others, should never be + allowed to access <application>Nagios</application>. + Configuration files and processes that are a part of + <application>Nagios</application> will be completely self + contained or jailed.</para> + + <para>This file may now be read into our system by issuing the + following command:</para> + + <screen>&prompt.root; <userinput>setfsmac -ef /etc/policy.contexts /</userinput> +&prompt.root; <userinput>setfsmac -ef /etc/policy.contexts /</userinput></screen> + + <note> + <para>The above file system layout may be different depending + on environment; however, it must be run on every single file + system.</para> + </note> + + <para>The <filename>/etc/mac.conf</filename> file requires + the following modifications in the main section:</para> + + <programlisting>default_labels file ?biba +default_labels ifnet ?biba +default_labels process ?biba +default_labels socket ?biba</programlisting> + </sect2> + + <sect2> + <title>Enable Networking</title> + + <para>Add the following line to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>security.mac.biba.trust_all_interfaces=1</programlisting> + + <para>And the following to the network card configuration stored + in <filename>rc.conf</filename>. If the primary Internet + configuration is done via <acronym>DHCP</acronym>, this may + need to be configured manually after every system boot:</para> + + <programlisting>maclabel biba/equal</programlisting> + </sect2> + + <sect2> + <title>Testing the Configuration</title> + + <indexterm> + <primary>MAC Configuration Testing</primary> + </indexterm> + + <para>Ensure that the web server and + <application>Nagios</application> will not be started + on system initialization, and reboot. Ensure the + <username>root</username> user cannot access any of the files + in the <application>Nagios</application> configuration + directory. If <username>root</username> can issue an &man.ls.1; + command on <filename>/var/spool/nagios</filename>, then something + is wrong. Otherwise a <quote>permission denied</quote> error + should be returned.</para> + + <para>If all seems well, <application>Nagios</application>, + <application>Apache</application>, and + <application>Sendmail</application> can now be started in a way + fitting of the security policy. The following commands will + make this happen:</para> + + <screen>&prompt.root; <userinput>cd /etc/mail && make stop && \ +setpmac biba/equal make start && setpmac biba/10\(10-10\) apachectl start && \ +setpmac biba/10\(10-10\) /usr/local/etc/rc.d/nagios.sh forcestart</userinput></screen> + + <para>Double check to ensure that everything is working + properly. If not, check the log files or error messages. Use + the &man.sysctl.8; utility to disable the &man.mac.biba.4; + security policy module enforcement and try starting everything + again, like normal.</para> + + <note> + <para>The <username>root</username> user can change the security + enforcement and edit the configuration files without fear. + The following command will permit the degradation of the + security policy to a lower grade for a newly spawned + shell:</para> + + <screen>&prompt.root; <userinput>setpmac biba/10 csh</userinput></screen> + + <para>To block this from happening, force the user into a range + via &man.login.conf.5;. If &man.setpmac.8; attempts to run + a command outside of the compartment's range, an error will + be returned and the command will not be executed. In this + case, setting root to + <literal>biba/high(high-high)</literal>.</para> + </note> + </sect2> + </sect1> + + <sect1 id="mac-userlocked"> + <title>User Lock Down</title> + + <para>This example considers a relatively small, fewer than fifty + users, storage system. Users would have login capabilities, and + be permitted to not only store data but access resources as + well.</para> + + <para>For this scenario, the &man.mac.bsdextended.4; mixed with + &man.mac.seeotheruids.4; could co-exist and block access not + only to system objects, but to hide user processes as + well.</para> + + <para>Begin by adding the following line to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>mac_seeotheruids_load="YES"</programlisting> + + <para>The &man.mac.bsdextended.4; security policy module may be + activated through the use of the following rc.conf + variable:</para> + + <programlisting>ugidfw_enable="YES"</programlisting> + + <para>Default rules stored in + <filename>/etc/rc.bsdextended</filename> will be loaded at system + initialization; however, the default entries may need + modification. Since this machine is expected only to service + users, everything may be left commented out except the last + two. These will force the loading of user owned system objects + by default.</para> + + <para>Add the required users to this machine and reboot. For + testing purposes, try logging in as a different user across two + consoles. Run the <command>ps aux</command> command to see if + processes of other users are visible. Try to run &man.ls.1; on + another users home directory, it should fail.</para> + + <para>Do not try to test with the <username>root</username> user + unless the specific <command>sysctl</command>s have been modified + to block super user access.</para> + + <note> + <para>When a new user is added, their &man.mac.bsdextended.4; + rule will not be in the ruleset list. To update the ruleset + quickly, simply unload the security policy module and reload + it again using the &man.kldunload.8; and &man.kldload.8; + utilities.</para> + </note> + </sect1> + + <sect1 id="mac-troubleshoot"> + <title>Troubleshooting the MAC Framework</title> + + <indexterm> + <primary>MAC Troubleshooting</primary> + </indexterm> + + <para>During the development stage, a few users reported problems + with normal configuration. Some of these problems + are listed below:</para> + + <sect2> + <title>The <option>multilabel</option> option cannot be enabled on + <filename>/</filename></title> + + <para>The <option>multilabel</option> flag does not stay + enabled on my root (<filename>/</filename>) partition!</para> + + + <para>It seems that one out of every fifty users has this + problem, indeed, we had this problem during our initial + configuration. Further observation of this so called + <quote>bug</quote> has lead me to believe that it is a + result of either incorrect documentation or misinterpretation + of the documentation. Regardless of why it happened, the + following steps may be taken to resolve it:</para> + + <procedure> + <step> + <para>Edit <filename>/etc/fstab</filename> and set the root + partition at <option>ro</option> for read-only.</para> + </step> + + <step> + <para>Reboot into single user mode.</para> + </step> + + <step> + <para>Run <command>tunefs</command> <option>-l enable</option> + on <filename>/</filename>.</para> + </step> + + <step> + <para>Reboot the system into normal mode.</para> + </step> + + <step> + <para>Run <command>mount</command> <option>-urw</option> + <filename>/</filename> and change the <option>ro</option> + back to <option>rw</option> in <filename>/etc/fstab</filename> + and reboot the system again.</para> + </step> + + <step> + <para>Double-check the output from the + <command>mount</command> to ensure that + <option>multilabel</option> has been properly set on the + root file system.</para> + </step> + </procedure> + </sect2> + + <sect2> + <title>X11 Server Will Not Start After <acronym>MAC</acronym></title> + + <para>After establishing a secure environment with + <acronym>MAC</acronym>, I am no longer able to start + X!</para> + + <para>This could be caused by the <acronym>MAC</acronym> + <literal>partition</literal> policy or by a mislabeling in + one of the <acronym>MAC</acronym> labeling policies. To + debug, try the following:</para> + + <procedure> + <step> + <para>Check the error message; if the user is in the + <literal>insecure</literal> class, the + <literal>partition</literal> policy may be the culprit. + Try setting the user's class back to the + <literal>default</literal> class and rebuild the database + with the <command>cap_mkdb</command> command. If this + does not alleviate the problem, go to step two.</para> + </step> + + <step> + <para>Double-check the label policies. Ensure that the + policies are set correctly for the user in question, the + X11 application, and + the <filename class="directory">/dev</filename> + entries.</para> + </step> + + <step> + <para>If neither of these resolve the problem, send the + error message and a description of your environment to + the TrustedBSD discussion lists located at the + <ulink url="http://www.TrustedBSD.org">TrustedBSD</ulink> + website or to the &a.questions; + mailing list.</para> + </step> + </procedure> + </sect2> + + <sect2> + <title>Error: &man..secure.path.3; cannot stat <filename>.login_conf</filename></title> + + <para>When I attempt to switch from the <username>root</username> user + to another user in the system, the error message + <errorname>_secure_path: unable to state .login_conf</errorname> appears.</para> + + <para>This message is usually shown when the user has a higher + label setting then that of the user whom they are attempting to + become. For instance a user on the system, + <username>joe</username>, has a default label of + <option>biba/low</option>. The <username>root</username> user, + who has a label of <option>biba/high</option>, cannot view + <username>joe</username>'s home directory. This will happen + regardless if <username>root</username> has used the + <command>su</command> command to become <username>joe</username>, + or not. In this scenario, the Biba integrity model will not + permit <username>root</username> to view objects set at a lower + integrity level.</para> + </sect2> + + <sect2> + <title>The <username>root</username> username is broken!</title> + + <para>In normal or even single user mode, the + <username>root</username> is not recognized. The + <command>whoami</command> command returns 0 (zero) and + <command>su</command> returns <errorname>who are you?</errorname>. + What could be going on?</para> + + <para>This can happen if a labeling policy has been disabled, + either by a &man.sysctl.8; or the policy module was unloaded. + If the policy is being disabled or has been temporarily + disabled, then the login capabilities database needs to be + reconfigured with the <option>label</option> option being + removed. Double check the <filename>login.conf</filename> + file to ensure that all <option>label</option> options have + been removed and rebuild the database with the + <command>cap_mkdb</command> command.</para> + + <para>This may also happen if a policy restricts access to the + <filename>master.passwd</filename> file or database. Usually + caused by an administrator altering the file under a label + which conflicts with the general policy being used by the + system. In these cases, the user information would be read + by the system and access would be blocked as the file has + inherited the new label. Disable the policy via a + &man.sysctl.8; and everything should return to normal.</para> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/mail/Makefile b/en_US.ISO8859-1/books/handbook/mail/Makefile new file mode 100644 index 0000000000..538dff091f --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/mail/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= mail/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/mail/chapter.sgml b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml new file mode 100644 index 0000000000..ff745fbe09 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/mail/chapter.sgml @@ -0,0 +1,2241 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="mail"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Bill</firstname> + <surname>Lloyd</surname> + <contrib>Original work by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Mock</surname> + <contrib>Rewritten by </contrib> + <!-- 2 Dec 1999 --> + </author> + </authorgroup> + </chapterinfo> + + <title>Electronic Mail</title> + + <sect1 id="mail-synopsis"> + <title>Synopsis</title> + <indexterm><primary>email</primary></indexterm> + + <para><quote>Electronic Mail</quote>, better known as email, is one of the + most widely used forms of communication today. This chapter provides + a basic introduction to running a mail server on &os;, as well as an + introduction to sending and receiving email using &os;; however, + it is not a complete reference and in fact many important + considerations are omitted. For more complete coverage of the + subject, the reader is referred to the many excellent books listed + in <xref linkend="bibliography">.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>What software components are involved in sending and receiving + electronic mail.</para> + </listitem> + + <listitem> + <para>Where basic <application>sendmail</application> configuration + files are located in FreeBSD.</para> + </listitem> + + <listitem> + <para>The difference between remote and + local mailboxes.</para> + </listitem> + + <listitem> + <para>How to block spammers from illegally using your mail server as a + relay.</para> + </listitem> + + <listitem> + <para>How to install and configure an alternate Mail Transfer Agent on + your system, replacing <application>sendmail</application>.</para> + </listitem> + + <listitem> + <para>How to troubleshoot common mail server problems.</para> + </listitem> + + <listitem> + <para>How to use SMTP with UUCP.</para> + </listitem> + + <listitem> + <para>How to set up the system to send mail only.</para> + </listitem> + + <listitem> + <para>How to use mail with a dialup connection.</para> + </listitem> + + <listitem> + <para>How to configure SMTP Authentication for added security.</para> + </listitem> + + <listitem> + <para>How to install and use a Mail User Agent, such as + <application>mutt</application> to send and receive email.</para> + </listitem> + + <listitem> + + <para>How to download your mail from a remote <acronym>POP</acronym> + or <acronym>IMAP</acronym> server.</para> + </listitem> + + <listitem> + <para>How to automatically apply filters and rules to incoming + email.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Properly set up your network connection + (<xref linkend="advanced-networking">).</para> + </listitem> + + <listitem> + <para>Properly set up the DNS information for your mail host + (<xref linkend="network-servers">).</para> + </listitem> + + <listitem> + <para>Know how to install additional third-party software + (<xref linkend="ports">).</para></listitem> + </itemizedlist> + </sect1> + + <sect1 id="mail-using"> + <title>Using Electronic Mail</title> + <indexterm><primary>POP</primary></indexterm> + <indexterm><primary>IMAP</primary></indexterm> + <indexterm><primary>DNS</primary></indexterm> + + <para>There are five major parts involved in an email exchange. They + are: <link linkend="mail-mua">the user program</link>, <link + linkend="mail-mta">the server daemon</link>, <link + linkend="mail-dns">DNS</link>, <link linkend="mail-receive">a + remote or local mailbox</link>, and of course, <link linkend="mail-host">the + mailhost itself</link>.</para> + + <sect2 id="mail-mua"> + <title>The User Program</title> + + <para>This includes command line programs such as + <application>mutt</application>, + <application>alpine</application>, <application>elm</application>, + and <command>mail</command>, and <acronym>GUI</acronym> programs such as + <application>balsa</application>, + <application>xfmail</application> to name a few, and something + more <quote>sophisticated</quote> like a WWW browser. These + programs simply pass off the email transactions to the local + <link linkend="mail-host"><quote>mailhost</quote></link>, either + by calling one of the <link linkend="mail-mta">server + daemons</link> available, or delivering it over <acronym>TCP</acronym>.</para> + </sect2> + + <sect2 id="mail-mta"> + <title>Mailhost Server Daemon</title> + <indexterm> + <primary>mail server daemons</primary> + <secondary><application>sendmail</application></secondary> + </indexterm> + <indexterm> + <primary>mail server daemons</primary> + <secondary><application>postfix</application></secondary> + </indexterm> + <indexterm> + <primary>mail server daemons</primary> + <secondary><application>qmail</application></secondary> + </indexterm> + <indexterm> + <primary>mail server daemons</primary> + <secondary><application>exim</application></secondary> + </indexterm> + + <para>&os; ships with <application>sendmail</application> by + default, but also support numerous other mail server daemons, + just some of which include:</para> + + <itemizedlist> + <listitem> + <para><application>exim</application>;</para> + </listitem> + + <listitem> + <para><application>postfix</application>;</para> + </listitem> + + <listitem> + <para><application>qmail</application>.</para> + </listitem> + </itemizedlist> + + <para>The server daemon usually has two functions—it is responsible + for receiving incoming mail as well as delivering outgoing mail. It is + <emphasis>not</emphasis> responsible for the collection of mail using protocols + such as <acronym>POP</acronym> or <acronym>IMAP</acronym> to + read your email, nor does it allow connecting to local + <filename>mbox</filename> or Maildir mailboxes. You may require + an additional <link linkend="mail-receive">daemon</link> for + that.</para> + + <warning> + <para>Older versions of <application>sendmail</application> + have some serious security issues which may result in an + attacker gaining local and/or remote access to your machine. + Make sure that you are running a current version to avoid + these problems. Optionally, install an alternative + <acronym>MTA</acronym> from the <link linkend="ports">&os; + Ports Collection</link>.</para> + </warning> + </sect2> + + <sect2 id="mail-dns"> + <title>Email and DNS</title> + + <para>The Domain Name System (DNS) and its daemon + <command>named</command> play a large role in the delivery of + email. In order to deliver mail from your site to another, the + server daemon will look up the remote site in the DNS to determine the + host that will receive mail for the destination. This process + also occurs when mail is sent from a remote host to your mail + server.</para> + + <indexterm> + <primary>MX record</primary> + </indexterm> + + <para><acronym>DNS</acronym> is responsible for mapping + hostnames to IP addresses, as well as for storing information + specific to mail delivery, known as MX records. The MX (Mail + eXchanger) record specifies which host, or hosts, will receive + mail for a particular domain. If you do not have an MX record + for your hostname or domain, the mail will be delivered + directly to your host provided you have an A record pointing + your hostname to your IP address.</para> + + <para>You may view the MX records for any domain by using the + &man.host.1; command, as seen in the example below:</para> + + <screen>&prompt.user; <userinput>host -t mx FreeBSD.org</userinput> +FreeBSD.org mail is handled (pri=10) by mx1.FreeBSD.org</screen> + </sect2> + + <sect2 id="mail-receive"> + <title>Receiving Mail</title> + <indexterm> + <primary>email</primary> + <secondary>receiving</secondary> + </indexterm> + + <para>Receiving mail for your domain is done by the mail host. It + will collect all mail sent to your domain and store it + either in <filename>mbox</filename> (the default method for storing mail) or Maildir format, depending + on your configuration. + Once mail has been stored, it may either be read locally using + applications such as &man.mail.1; or + <application>mutt</application>, or remotely accessed and + collected using protocols such as + <acronym>POP</acronym> or <acronym>IMAP</acronym>. + This means that should you only + wish to read mail locally, you are not required to install a + <acronym>POP</acronym> or <acronym>IMAP</acronym> server.</para> + + <sect3 id="pop-and-imap"> + <title>Accessing remote mailboxes using <acronym>POP</acronym> and <acronym>IMAP</acronym></title> + + <indexterm><primary>POP</primary></indexterm> + <indexterm><primary>IMAP</primary></indexterm> + <para>In order to access mailboxes remotely, you are required to + have access to a <acronym>POP</acronym> or <acronym>IMAP</acronym> + server. These protocols allow users to connect to their mailboxes from + remote locations with ease. Though both + <acronym>POP</acronym> and <acronym>IMAP</acronym> allow users + to remotely access mailboxes, <acronym>IMAP</acronym> offers + many advantages, some of which are:</para> + + <itemizedlist> + <listitem> + <para><acronym>IMAP</acronym> can store messages on a remote + server as well as fetch them.</para> + </listitem> + + <listitem> + <para><acronym>IMAP</acronym> supports concurrent updates.</para> + </listitem> + + <listitem> + <para><acronym>IMAP</acronym> can be extremely useful over + low-speed links as it allows users to fetch the structure + of messages without downloading them; it can also + perform tasks such as searching on the server in + order to minimize data transfer between clients and + servers.</para> + </listitem> + + </itemizedlist> + + <para>In order to install a <acronym>POP</acronym> or + <acronym>IMAP</acronym> server, the following steps should be + performed:</para> + + <procedure> + <step> + <para>Choose an <acronym>IMAP</acronym> or + <acronym>POP</acronym> server that best suits your needs. + The following <acronym>POP</acronym> and + <acronym>IMAP</acronym> servers are well known and serve + as some good examples:</para> + + <itemizedlist> + <listitem> + <para><application>qpopper</application>;</para> + </listitem> + + <listitem> + <para><application>teapop</application>;</para> + </listitem> + + <listitem> + <para><application>imap-uw</application>;</para> + </listitem> + + <listitem> + <para><application>courier-imap</application>;</para> + </listitem> + + <listitem> + <para><application>dovecot</application>;</para> + </listitem> + </itemizedlist> + + </step> + + <step> + <para>Install the <acronym>POP</acronym> or + <acronym>IMAP</acronym> daemon of your choosing from the + ports + collection.</para> + </step> + + <step> + <para>Where required, modify <filename>/etc/inetd.conf</filename> + to load the <acronym>POP</acronym> or + <acronym>IMAP</acronym> server.</para> + </step> + </procedure> + + <warning> + <para>It should be noted that both <acronym>POP</acronym> and + <acronym>IMAP</acronym> transmit information, including + username and password credentials in clear-text. This means + that if you wish to secure the transmission of information + across these protocols, you should consider tunneling + sessions over &man.ssh.1; or using SSL. Tunneling sessions is + described in <xref linkend="security-ssh-tunneling"> and SSL is + described in <xref linkend="openssl">.</para> + </warning> + </sect3> + + <sect3 id="local"> + <title>Accessing Local Mailboxes</title> + + <para>Mailboxes may be accessed locally by directly utilizing + <acronym>MUA</acronym>s on the server on which the mailbox + resides. This can be done using applications such as + <application>mutt</application> or &man.mail.1;. + </para> + </sect3> + </sect2> + + <sect2 id="mail-host"> + <title>The Mail Host</title> + <indexterm><primary>mail host</primary></indexterm> + + <para>The mail host is the name given to a server that is + responsible for delivering and receiving mail for your host, and + possibly your network.</para> + </sect2> + </sect1> + + <sect1 id="sendmail"> + <sect1info> + <authorgroup> + <author> + <firstname>Christopher</firstname> + <surname>Shumway</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title><application>sendmail</application> Configuration</title> + + <indexterm> + <primary><application>sendmail</application></primary> + </indexterm> + + <para>&man.sendmail.8; is the default Mail Transfer Agent (MTA) in + FreeBSD. <application>sendmail</application>'s job is to accept + mail from Mail User Agents (<acronym>MUA</acronym>) and deliver it + to the appropriate mailer as defined by its configuration file. + <application>sendmail</application> can also accept network + connections and deliver mail to local mailboxes or deliver it to + another program.</para> + + <para><application>sendmail</application> uses the following + configuration files:</para> + + <indexterm> + <primary><filename>/etc/mail/access</filename></primary> + </indexterm> + <indexterm> + <primary><filename>/etc/mail/aliases</filename></primary> + </indexterm> + <indexterm> + <primary><filename>/etc/mail/local-host-names</filename></primary> + </indexterm> + <indexterm> + <primary><filename>/etc/mail/mailer.conf</filename></primary> + </indexterm> + <indexterm> + <primary><filename>/etc/mail/mailertable</filename></primary> + </indexterm> + <indexterm> + <primary><filename>/etc/mail/sendmail.cf</filename></primary> + </indexterm> + <indexterm> + <primary><filename>/etc/mail/virtusertable</filename></primary> + </indexterm> + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Filename</entry> + <entry>Function</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <filename>/etc/mail/access</filename> + </entry> + <entry><application>sendmail</application> access database + file</entry> + </row> + <row> + <entry> + <filename>/etc/mail/aliases</filename> + </entry> + <entry>Mailbox aliases</entry> + </row> + <row> + <entry> + <filename>/etc/mail/local-host-names</filename> + </entry> + <entry>Lists of hosts <application>sendmail</application> + accepts mail for</entry> + </row> + <row> + <entry> + <filename>/etc/mail/mailer.conf</filename> + </entry> + <entry>Mailer program configuration</entry> + </row> + <row> + <entry> + <filename>/etc/mail/mailertable</filename> + </entry> + <entry>Mailer delivery table</entry> + </row> + <row> + <entry> + <filename>/etc/mail/sendmail.cf</filename> + </entry> + <entry><application>sendmail</application> master + configuration file</entry> + </row> + <row> + <entry> + <filename>/etc/mail/virtusertable</filename> + </entry> + <entry>Virtual users and domain tables</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <sect2> + <title><filename>/etc/mail/access</filename></title> + + <para>The access database defines what host(s) or IP addresses + have access to the local mail server and what kind of access + they have. Hosts can be listed as <option>OK</option>, + <option>REJECT</option>, <option>RELAY</option> or simply passed + to <application>sendmail</application>'s error handling routine with a given mailer error. + Hosts that are listed as <option>OK</option>, which is the + default, are allowed to send mail to this host as long as the + mail's final destination is the local machine. Hosts that are + listed as <option>REJECT</option> are rejected for all mail + connections. Hosts that have the <option>RELAY</option> option + for their hostname are allowed to send mail for any destination + through this mail server.</para> + + <example> + <title>Configuring the <application>sendmail</application> + Access Database</title> + + <programlisting>cyberspammer.com 550 We do not accept mail from spammers +FREE.STEALTH.MAILER@ 550 We do not accept mail from spammers +another.source.of.spam REJECT +okay.cyberspammer.com OK +128.32 RELAY</programlisting> + </example> + + <para>In this example we have five entries. Mail senders that + match the left hand side of the table are affected by the action + on the right side of the table. The first two examples give an + error code to <application>sendmail</application>'s error + handling routine. The message is printed to the remote host when + a mail matches the left hand side of the table. The next entry + rejects mail from a specific host on the Internet, + <hostid>another.source.of.spam</hostid>. The next entry accepts + mail connections from a host + <hostid role="fqdn">okay.cyberspammer.com</hostid>, which is more exact than + the <hostid role="domainname">cyberspammer.com</hostid> line above. More specific + matches override less exact matches. The last entry allows + relaying of electronic mail from hosts with an IP address that + begins with <hostid>128.32</hostid>. These hosts would be able + to send mail through this mail server that are destined for other + mail servers.</para> + + <para>When this file is updated, you need to run + <command>make</command> in <filename>/etc/mail/</filename> to + update the database.</para> + + </sect2> + <sect2> + <title><filename>/etc/mail/aliases</filename></title> + + <para>The aliases database contains a list of virtual mailboxes + that are expanded to other user(s), files, programs or other + aliases. Here are a few examples that can be used in + <filename>/etc/mail/aliases</filename>:</para> + + <example> + <title>Mail Aliases</title> + <programlisting>root: localuser +ftp-bugs: joe,eric,paul +bit.bucket: /dev/null +procmail: "|/usr/local/bin/procmail"</programlisting> + </example> + + <para>The file format is simple; the mailbox name on the left + side of the colon is expanded to the target(s) on the right. + The + first example expands the mailbox <username>root</username> + to the mailbox <username>localuser</username>, which is then + looked up again in the aliases database. If no match is found, + then the message is delivered to the local user + <username>localuser</username>. The next example shows a mail + list. Mail to the mailbox <username>ftp-bugs</username> is + expanded to the three local mailboxes <username>joe</username>, + <username>eric</username>, and <username>paul</username>. Note + that a remote mailbox could be specified as <email>user@example.com</email>. The + next example shows writing mail to a file, in this case + <filename>/dev/null</filename>. The last example shows sending + mail to a program, in this case the mail message is written to the + standard input of <filename>/usr/local/bin/procmail</filename> + through a &unix; pipe.</para> + + <para>When this file is updated, you need to run + <command>make</command> in <filename>/etc/mail/</filename> to + update the database.</para> + </sect2> + <sect2> + <title><filename>/etc/mail/local-host-names</filename></title> + + <para>This is a list of hostnames &man.sendmail.8; is to accept as + the local host name. Place any domains or hosts that + <application>sendmail</application> is to be receiving mail for. + For example, if this mail server was to accept mail for the + domain <hostid role="domainname">example.com</hostid> and the host + <hostid role="fqdn">mail.example.com</hostid>, its + <filename>local-host-names</filename> might look something like + this:</para> + + <programlisting>example.com +mail.example.com</programlisting> + + <para>When this file is updated, &man.sendmail.8; needs to be + restarted to read the changes.</para> + + </sect2> + + <sect2> + <title><filename>/etc/mail/sendmail.cf</filename></title> + + <para><application>sendmail</application>'s master configuration + file, <filename>sendmail.cf</filename> controls the overall + behavior of <application>sendmail</application>, including everything + from rewriting e-mail addresses to printing rejection messages to + remote mail servers. Naturally, with such a diverse role, this + configuration file is quite complex and its details are a bit + out of the scope of this section. Fortunately, this file rarely + needs to be changed for standard mail servers.</para> + + <para>The master <application>sendmail</application> configuration + file can be built from &man.m4.1; macros that define the features + and behavior of <application>sendmail</application>. Please see + <filename>/usr/src/contrib/sendmail/cf/README</filename> for + some of the details.</para> + + <para>When changes to this file are made, + <application>sendmail</application> needs to be restarted for + the changes to take effect.</para> + + </sect2> + <sect2> + <title><filename>/etc/mail/virtusertable</filename></title> + + <para>The <filename>virtusertable</filename> maps mail addresses for + virtual domains and + mailboxes to real mailboxes. These mailboxes can be local, + remote, aliases defined in + <filename>/etc/mail/aliases</filename> or files.</para> + + <example> + <title>Example Virtual Domain Mail Map</title> + + <programlisting>root@example.com root +postmaster@example.com postmaster@noc.example.net +@example.com joe</programlisting> + </example> + + <para>In the above example, we have a mapping for a domain + <hostid role="domainname">example.com</hostid>. This file is processed in a + first match order down the file. The first item maps + <email>root@example.com</email> to the local mailbox <username>root</username>. The next entry maps + <email>postmaster@example.com</email> to the mailbox <username>postmaster</username> on the host + <hostid role="fqdn">noc.example.net</hostid>. Finally, if nothing from <hostid role="domainname">example.com</hostid> has + matched so far, it will match the last mapping, which matches + every other mail message addressed to someone at + <hostid role="domainname">example.com</hostid>. + This will be mapped to the local mailbox <username>joe</username>.</para> + + </sect2> + </sect1> + + <sect1 id="mail-changingmta"> + <sect1info> + <authorgroup> + <author> + <firstname>Andrew</firstname> + <surname>Boothman</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Gregory</firstname> + <surname>Neil Shapiro</surname> + <contrib>Information taken from e-mails written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Changing Your Mail Transfer Agent</title> + <indexterm> + <primary>email</primary> + <secondary>change mta</secondary> + </indexterm> + + <para>As already mentioned, FreeBSD comes with + <application>sendmail</application> already installed as your + MTA (Mail Transfer Agent). Therefore by default it is + in charge of your outgoing and incoming mail.</para> + + <para>However, for a variety of reasons, some system + administrators want to change their system's MTA. These + reasons range from merely wanting to try out another MTA to + needing a specific feature or package which relies on another + mailer. Fortunately, whatever the reason, FreeBSD makes it + easy to make the change.</para> + + <sect2> + <title>Install a New MTA</title> + + <para>You have a wide choice of MTAs available. A good + starting point is the + <link linkend="ports">FreeBSD Ports Collection</link> where + you will be able to find many. Of course you are free to use + any MTA you want from any location, as long as you can make + it run under FreeBSD.</para> + + <para>Start by installing your new MTA. Once it is installed + it gives you a chance to decide if it really fulfills your + needs, and also gives you the opportunity to configure your + new software before getting it to take over from + <application>sendmail</application>. When doing this, you + should be sure that installing the new software will not attempt + to overwrite system binaries such as + <filename>/usr/bin/sendmail</filename>. Otherwise, your new + mail software has essentially been put into service before + you have configured it.</para> + + <para>Please refer to your chosen MTA's documentation for + information on how to configure the software you have + chosen.</para> + </sect2> + + <sect2 id="mail-disable-sendmail"> + <title>Disable <application>sendmail</application></title> + + <warning> + <para>If you disable <application>sendmail</application>'s + outgoing mail service, it is important that you replace it + with an alternative mail delivery system. If + you choose not to, system functions such as &man.periodic.8; + will be unable to deliver their results by e-mail as they + would normally expect to. Many parts of your system may + expect to have a functional + <application>sendmail</application>-compatible system. If + applications continue to use + <application>sendmail</application>'s binaries to try to send + e-mail after you have disabled them, mail could go into an + inactive <application>sendmail</application> queue, and + never be delivered.</para> + </warning> + + <para>In order to completely disable + <application>sendmail</application>, including the outgoing + mail service, you must use</para> + + <programlisting>sendmail_enable="NO" +sendmail_submit_enable="NO" +sendmail_outbound_enable="NO" +sendmail_msp_queue_enable="NO"</programlisting> + + <para>in <filename>/etc/rc.conf.</filename></para> + + <para>If you only want to disable + <application>sendmail</application>'s incoming mail service, + you should set</para> + + <programlisting>sendmail_enable="NO"</programlisting> + + <para>in <filename>/etc/rc.conf</filename>. More information on + <application>sendmail</application>'s startup options is + available from the &man.rc.sendmail.8; manual page.</para> + </sect2> + + <sect2> + <title>Running Your New MTA on Boot</title> + + <para>The new MTA can be started during boot by adding a + configuration line to <filename>/etc/rc.conf</filename> + like the following example for postfix:</para> + + <screen>&prompt.root; echo '<replaceable>postfix</replaceable>_enable=<quote>YES</quote>' >> /etc/rc.conf</screen> + + <para>The MTA will now be automatically started during + boot.</para> + </sect2> + + <sect2> + <title>Replacing <application>sendmail</application> as + the System's Default Mailer</title> + + <para>The program <application>sendmail</application> is so ubiquitous + as standard software on &unix; systems that some software + just assumes it is already installed and configured. + For this reason, many alternative MTA's provide their own compatible + implementations of the <application>sendmail</application> + command-line interface; this facilitates using them as + <quote>drop-in</quote> replacements for <application>sendmail</application>.</para> + + <para>Therefore, if you are using an alternative mailer, + you will need to make sure that software trying to execute + standard <application>sendmail</application> binaries such as + <filename>/usr/bin/sendmail</filename> actually executes + your chosen mailer instead. Fortunately, FreeBSD provides + a system called &man.mailwrapper.8; that does this job for + you.</para> + + <para>When <application>sendmail</application> is operating as installed, you will + find something like the following + in <filename>/etc/mail/mailer.conf</filename>:</para> + +<programlisting>sendmail /usr/libexec/sendmail/sendmail +send-mail /usr/libexec/sendmail/sendmail +mailq /usr/libexec/sendmail/sendmail +newaliases /usr/libexec/sendmail/sendmail +hoststat /usr/libexec/sendmail/sendmail +purgestat /usr/libexec/sendmail/sendmail</programlisting> + + <para>This means that when any of these common commands + (such as <filename>sendmail</filename> itself) are run, + the system actually invokes a copy of mailwrapper named <filename>sendmail</filename>, which + checks <filename>mailer.conf</filename> and + executes <filename>/usr/libexec/sendmail/sendmail</filename> + instead. This system makes it easy to change what binaries + are actually executed when these default <filename>sendmail</filename> functions + are invoked.</para> + + <para>Therefore if you wanted + <filename>/usr/local/supermailer/bin/sendmail-compat</filename> + to be run instead of <application>sendmail</application>, you could change + <filename>/etc/mail/mailer.conf</filename> to read:</para> + +<programlisting>sendmail /usr/local/supermailer/bin/sendmail-compat +send-mail /usr/local/supermailer/bin/sendmail-compat +mailq /usr/local/supermailer/bin/mailq-compat +newaliases /usr/local/supermailer/bin/newaliases-compat +hoststat /usr/local/supermailer/bin/hoststat-compat +purgestat /usr/local/supermailer/bin/purgestat-compat</programlisting> + + </sect2> + + <sect2> + <title>Finishing</title> + + <para>Once you have everything configured the way you want it, you should + either kill the <application>sendmail</application> processes that + you no longer need and start the processes belonging to your new + software, or simply reboot. Rebooting will also + give you the opportunity to ensure that you have correctly + configured your system to start your new MTA automatically on boot.</para> + + </sect2> + </sect1> + + <sect1 id="mail-trouble"> + <title>Troubleshooting</title> + <indexterm> + <primary>email</primary> + <secondary>troubleshooting</secondary> + </indexterm> + + <qandaset> + <qandaentry> + <question> + <para>Why do I have to use the FQDN for hosts on my site?</para> + </question> + + <answer> + <para>You will probably find that the host is actually in a + different domain; for example, if you are in + <hostid role="fqdn">foo.bar.edu</hostid> and you wish to reach + a host called <hostid>mumble</hostid> in the <hostid + role="domainname">bar.edu</hostid> domain, you will have to + refer to it by the fully-qualified domain name, <hostid + role="fqdn">mumble.bar.edu</hostid>, instead of just + <hostid>mumble</hostid>.</para> + + <indexterm><primary>BIND</primary></indexterm> + <para>Traditionally, this was allowed by BSD BIND resolvers. + However the current version of <application>BIND</application> + that ships with FreeBSD no longer provides default abbreviations + for non-fully qualified domain names other than the domain you + are in. So an unqualified host <hostid>mumble</hostid> must + either be found as <hostid + role="fqdn">mumble.foo.bar.edu</hostid>, or it will be searched + for in the root domain.</para> + + <para>This is different from the previous behavior, where the + search continued across <hostid + role="domainname">mumble.bar.edu</hostid>, and <hostid + role="domainname">mumble.edu</hostid>. Have a look at RFC 1535 + for why this was considered bad practice, or even a security + hole.</para> + + <para>As a good workaround, you can place the line: + + <programlisting>search foo.bar.edu bar.edu</programlisting> + + instead of the previous: + + <programlisting>domain foo.bar.edu</programlisting> + + into your <filename>/etc/resolv.conf</filename>. However, make + sure that the search order does not go beyond the + <quote>boundary between local and public administration</quote>, + as RFC 1535 calls it.</para> + </answer> + </qandaentry> + + <indexterm> + <primary>MX record</primary> + </indexterm> + + <qandaentry> + <question> + <para><application>sendmail</application> says <errorname>mail + loops back to myself</errorname></para> + </question> + + <answer> + <para>This is answered in the + <application>sendmail</application> FAQ as follows:</para> + + <programlisting>I'm getting these error messages: + +553 MX list for domain.net points back to relay.domain.net +554 <user@domain.net>... Local configuration error + +How can I solve this problem? + +You have asked mail to the domain (e.g., domain.net) to be +forwarded to a specific host (in this case, relay.domain.net) +by using an MX record, but the relay machine does not recognize +itself as domain.net. Add domain.net to /etc/mail/local-host-names +[known as /etc/sendmail.cw prior to version 8.10] +(if you are using FEATURE(use_cw_file)) or add <quote>Cw domain.net</quote> +to /etc/mail/sendmail.cf.</programlisting> + + <para>The <application>sendmail</application> FAQ can be found at + <ulink url="http://www.sendmail.org/faq/"></ulink> and is + recommended reading if you want to do any + <quote>tweaking</quote> of your mail setup.</para> + </answer> + </qandaentry> + + <indexterm><primary>PPP</primary></indexterm> + <qandaentry> + <question> + <para>How can I run a mail server on a dial-up PPP host?</para> + </question> + + <answer> + <para>You want to connect a FreeBSD box on a LAN to the + Internet. The FreeBSD box will be a mail gateway for the LAN. + The PPP connection is non-dedicated.</para> + + <indexterm><primary>UUCP</primary></indexterm> + <indexterm> + <primary>MX record</primary> + </indexterm> + + <para>There are at least two ways to do this. One way is to use + UUCP.</para> + + <para>Another way is to get a full-time Internet server to provide secondary MX + services for your domain. For example, if your company's domain is + <hostid role="domainname">example.com</hostid> and your Internet service provider has + set <hostid role="domainname">example.net</hostid> up to provide secondary MX services + to your domain:</para> + + <programlisting>example.com. MX 10 example.com. + MX 20 example.net.</programlisting> + + <para>Only one host should be specified as the final recipient + (add <literal>Cw example.com</literal> in + <filename>/etc/mail/sendmail.cf</filename> on <hostid role="domainname">example.com</hostid>).</para> + + <para>When the sending <command>sendmail</command> is trying to + deliver the mail it will try to connect to you (<hostid role="domainname">example.com</hostid>) over the modem + link. It will most likely time out because you are not online. + The program <application>sendmail</application> will automatically deliver it to the + secondary MX site, i.e., your Internet provider (<hostid role="domainname">example.net</hostid>). The secondary MX + site will then periodically try to connect to + your host and deliver the mail to the primary MX host (<hostid role="domainname">example.com</hostid>).</para> + + <para>You might want to use something like this as a login + script:</para> + + <programlisting>#!/bin/sh +# Put me in /usr/local/bin/pppmyisp +( sleep 60 ; /usr/sbin/sendmail -q ) & +/usr/sbin/ppp -direct pppmyisp</programlisting> + + <para>If you are going to create a separate login script for a + user you could use <command>sendmail -qRexample.com</command> + instead in the script above. This will force all mail in your + queue for <hostid role="domainname">example.com</hostid> to be processed immediately.</para> + + <para>A further refinement of the situation is as follows:</para> + + <para>Message stolen from the &a.isp;.</para> + + <programlisting>> we provide the secondary MX for a customer. The customer connects to +> our services several times a day automatically to get the mails to +> his primary MX (We do not call his site when a mail for his domains +> arrived). Our sendmail sends the mailqueue every 30 minutes. At the +> moment he has to stay 30 minutes online to be sure that all mail is +> gone to the primary MX. +> +> Is there a command that would initiate sendmail to send all the mails +> now? The user has not root-privileges on our machine of course. + +In the <quote>privacy flags</quote> section of sendmail.cf, there is a +definition Opgoaway,restrictqrun + +Remove restrictqrun to allow non-root users to start the queue processing. +You might also like to rearrange the MXs. We are the 1st MX for our +customers like this, and we have defined: + +# If we are the best MX for a host, try directly instead of generating +# local config error. +OwTrue + +That way a remote site will deliver straight to you, without trying +the customer connection. You then send to your customer. Only works for +<quote>hosts</quote>, so you need to get your customer to name their mail +machine <quote>customer.com</quote> as well as +<quote>hostname.customer.com</quote> in the DNS. Just put an A record in +the DNS for <quote>customer.com</quote>.</programlisting> + </answer> + </qandaentry> + + <qandaentry> + <question> + <para>Why do I keep getting <errorname>Relaying + Denied</errorname> errors when sending mail from other + hosts?</para> + </question> + + <answer> + <para>In default FreeBSD installations, + <application>sendmail</application> is configured to only + send mail from the host it is running on. For example, if + a <acronym>POP</acronym> server is available, then users + will be able to check mail from school, work, or other + remote locations but they still will not be able to send + outgoing emails from outside locations. Typically, a few + moments after the attempt, an email will be sent from + <application>MAILER-DAEMON</application> with a + <errorname>5.7 Relaying Denied</errorname> error + message.</para> + + <para>There are several ways to get around this. The most + straightforward solution is to put your ISP's address in + a relay-domains file at + <filename>/etc/mail/relay-domains</filename>. A quick way + to do this would be:</para> + + <screen>&prompt.root; <userinput>echo "your.isp.example.com" > /etc/mail/relay-domains</userinput></screen> + + <para>After creating or editing this file you must restart + <application>sendmail</application>. This works great if + you are a server administrator and do not wish to send mail + locally, or would like to use a point and click + client/system on another machine or even another ISP. It + is also very useful if you only have one or two email + accounts set up. If there are a large number of addresses + to add, open this file in your favorite + text editor and then add the domains, one per line:</para> + + <programlisting>your.isp.example.com +other.isp.example.net +users-isp.example.org +www.example.org</programlisting> + + <para>Now any mail sent through your system, by any host in + this list (provided the user has an account on your + system), will succeed. This is a very nice way to allow + users to send mail from your system remotely without + allowing people to send SPAM through your system.</para> + + </answer> + </qandaentry> + </qandaset> + </sect1> + + <sect1 id="mail-advanced"> + <title>Advanced Topics</title> + + <para>The following section covers more involved topics such as mail + configuration and setting up mail for your entire domain.</para> + + <sect2 id="mail-config"> + <title>Basic Configuration</title> + <indexterm> + <primary>email</primary> + <secondary>configuration</secondary> + </indexterm> + + <para>Out of the box, you should be able to send email to external + hosts as long as you have set up + <filename>/etc/resolv.conf</filename> or are running your own + name server. If you would like to have mail for your host + delivered to the MTA (e.g., <application>sendmail</application>) on your own FreeBSD host, there are two methods:</para> + + <itemizedlist> + <listitem> + <para>Run your own name server and have your own domain. For + example, <hostid + role="domainname">FreeBSD.org</hostid></para> + </listitem> + + <listitem> + <para>Get mail delivered directly to your host. This is done by + delivering mail directly to the current DNS name for your + machine. For example, <hostid + role="fqdn">example.FreeBSD.org</hostid>.</para> + </listitem> + </itemizedlist> + + <indexterm><primary>SMTP</primary></indexterm> + <para>Regardless of which of the above you choose, in order to have + mail delivered directly to your host, it must have a permanent + static IP address (not a dynamic address, as with most PPP dial-up configurations). If you are behind a + firewall, it must pass SMTP traffic on to you. If you want to + receive mail directly at your host, you need to be sure of either of two + things:</para> + + <itemizedlist> + <indexterm><primary>MX record</primary></indexterm> + <listitem> + <para>Make sure that the (lowest-numbered) MX record in your DNS points to your + host's IP address.</para> + </listitem> + + <listitem> + <para>Make sure there is no MX entry in your DNS for your + host.</para> + </listitem> + </itemizedlist> + + <para>Either of the above will allow you to receive mail directly at + your host.</para> + + <para>Try this:</para> + + <screen>&prompt.root; <userinput>hostname</userinput> +example.FreeBSD.org +&prompt.root; <userinput>host example.FreeBSD.org</userinput> +example.FreeBSD.org has address 204.216.27.XX</screen> + + <para>If that is what you see, mail directly to + <email role="nolink">yourlogin@example.FreeBSD.org</email> should work without + problems (assuming <application>sendmail</application> is + running correctly on <hostid role="fqdn">example.FreeBSD.org</hostid>).</para> + + <para>If instead you see something like this:</para> + + <screen>&prompt.root; <userinput>host example.FreeBSD.org</userinput> +example.FreeBSD.org has address 204.216.27.XX +example.FreeBSD.org mail is handled (pri=10) by hub.FreeBSD.org</screen> + + <para>All mail sent to your host (<hostid + role="fqdn">example.FreeBSD.org</hostid>) will end up being + collected on <hostid>hub</hostid> under the same username instead + of being sent directly to your host.</para> + + <para>The above information is handled by your DNS server. The DNS + record that carries mail routing information is the + <emphasis>M</emphasis>ail e<emphasis>X</emphasis>change entry. If + no MX record exists, mail will be delivered directly to the host by + way of its IP address.</para> + + <para>The MX entry for <hostid + role="fqdn">freefall.FreeBSD.org</hostid> at one time looked like + this:</para> + + <programlisting>freefall MX 30 mail.crl.net +freefall MX 40 agora.rdrop.com +freefall MX 10 freefall.FreeBSD.org +freefall MX 20 who.cdrom.com</programlisting> + + <para>As you can see, <hostid>freefall</hostid> had many MX entries. + The lowest MX number is the host that receives mail directly if + available; if it is not accessible for some reason, the others + (sometimes called <quote>backup MXes</quote>) accept messages + temporarily, and pass it along when a lower-numbered host becomes + available, eventually to the lowest-numbered host.</para> + + <para>Alternate MX sites should have separate Internet connections + from your own in order to be most useful. Your ISP or another + friendly site should have no problem providing this service for + you.</para> + </sect2> + + <sect2 id="mail-domain"> + <title>Mail for Your Domain</title> + + <para>In order to set up a <quote>mailhost</quote> (aka mail + server) you need to have any mail sent to various workstations + directed to it. Basically, you want to <quote>claim</quote> any + mail for any hostname in your domain (in this case <hostid + role="fqdn">*.FreeBSD.org</hostid>) and divert it to your mail + server so your users can receive their mail on + the master mail server.</para> + + <indexterm><primary>DNS</primary></indexterm> + <para>To make life easiest, a user account with the same + <emphasis>username</emphasis> should exist on both machines. Use + &man.adduser.8; to do this.</para> + + <para>The mailhost you will be using must be the designated mail + exchanger for each workstation on the network. This is done in + your DNS configuration like so:</para> + + <programlisting>example.FreeBSD.org A 204.216.27.XX ; Workstation + MX 10 hub.FreeBSD.org ; Mailhost</programlisting> + + <para>This will redirect mail for the workstation to the mailhost no + matter where the A record points. The mail is sent to the MX + host.</para> + + <para>You cannot do this yourself unless you are running a DNS + server. If you are not, or cannot run your own DNS server, talk + to your ISP or whoever provides your DNS.</para> + + <para>If you are doing virtual email hosting, the following + information will come in handy. For this example, we + will assume you have a customer with his own domain, in this + case <hostid role="domainname">customer1.org</hostid>, and you want + all the mail for <hostid role="domainname">customer1.org</hostid> + sent to your mailhost, <hostid + role="fqdn">mail.myhost.com</hostid>. The entry in your DNS + should look like this:</para> + + <programlisting>customer1.org MX 10 mail.myhost.com</programlisting> + + <para>You do <emphasis>not</emphasis> need an A record for <hostid role="domainname">customer1.org</hostid> if you only + want to handle email for that domain.</para> + + <note> + <para>Be aware that pinging <hostid + role="domainname">customer1.org</hostid> will not work unless + an A record exists for it.</para> + </note> + + <para>The last thing that you must do is tell + <application>sendmail</application> on your mailhost what domains + and/or hostnames it should be accepting mail for. There are a few + different ways this can be done. Either of the following will + work:</para> + + <itemizedlist> + <listitem> + <para>Add the hosts to your + <filename>/etc/mail/local-host-names</filename> file if you are using the + <literal>FEATURE(use_cw_file)</literal>. If you are using + a version of <application>sendmail</application> earlier than 8.10, the file is + <filename>/etc/sendmail.cw</filename>.</para> + </listitem> + + <listitem> + <para>Add a <literal>Cwyour.host.com</literal> line to your + <filename>/etc/sendmail.cf</filename> or + <filename>/etc/mail/sendmail.cf</filename> if you are using + <application>sendmail</application> 8.10 or higher.</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="SMTP-UUCP"> + <title>SMTP with UUCP</title> + + <para>The <application>sendmail</application> configuration that ships with FreeBSD is + designed for sites that connect directly to the Internet. Sites + that wish to exchange their mail via UUCP must install another + <application>sendmail</application> configuration file.</para> + + <para>Tweaking <filename>/etc/mail/sendmail.cf</filename> manually + is an advanced topic. <application>sendmail</application> version 8 generates config files + via &man.m4.1; preprocessing, where the actual configuration + occurs on a higher abstraction level. The &man.m4.1; + configuration files can be found under + <filename>/usr/share/sendmail/cf</filename>. The file + <filename>README</filename> in the <filename>cf</filename> + directory can serve as a basic introduction to &man.m4.1; + configuration.</para> + + <para>The best way to support UUCP delivery is to use the + <literal>mailertable</literal> feature. This creates a database + that <application>sendmail</application> can use to make routing decisions.</para> + + <para>First, you have to create your <filename>.mc</filename> + file. The directory + <filename>/usr/share/sendmail/cf/cf</filename> contains a + few examples. Assuming you have named your file + <filename>foo.mc</filename>, all you need to do in order to + convert it into a valid <filename>sendmail.cf</filename> + is:</para> + + <screen>&prompt.root; <userinput>cd /etc/mail</userinput> +&prompt.root; <userinput>make foo.cf</userinput> +&prompt.root; <userinput>cp foo.cf /etc/mail/sendmail.cf</userinput></screen> + + <para>A typical <filename>.mc</filename> file might look + like:</para> + + <programlisting>VERSIONID(`<replaceable>Your version number</replaceable>') OSTYPE(bsd4.4) + +FEATURE(accept_unresolvable_domains) +FEATURE(nocanonify) +FEATURE(mailertable, `hash -o /etc/mail/mailertable') + +define(`UUCP_RELAY', <replaceable>your.uucp.relay</replaceable>) +define(`UUCP_MAX_SIZE', 200000) +define(`confDONT_PROBE_INTERFACES') + +MAILER(local) +MAILER(smtp) +MAILER(uucp) + +Cw <replaceable>your.alias.host.name</replaceable> +Cw <replaceable>youruucpnodename.UUCP</replaceable></programlisting> + + <para>The lines containing + <literal>accept_unresolvable_domains</literal>, + <literal>nocanonify</literal>, and + <literal>confDONT_PROBE_INTERFACES</literal> features will + prevent any usage of the DNS during mail delivery. The + <literal>UUCP_RELAY</literal> clause is needed to support UUCP + delivery. Simply put an Internet hostname there that is able to + handle .UUCP pseudo-domain addresses; most likely, you will + enter the mail relay of your ISP there.</para> + + <para>Once you have this, you need an + <filename>/etc/mail/mailertable</filename> file. If you have + only one link to the outside that is used for all your mails, + the following file will suffice:</para> + + <programlisting># +# makemap hash /etc/mail/mailertable.db < /etc/mail/mailertable +. uucp-dom:<replaceable>your.uucp.relay</replaceable></programlisting> + + <para>A more complex example might look like this:</para> + + <programlisting># +# makemap hash /etc/mail/mailertable.db < /etc/mail/mailertable +# +horus.interface-business.de uucp-dom:horus +.interface-business.de uucp-dom:if-bus +interface-business.de uucp-dom:if-bus +.heep.sax.de smtp8:%1 +horus.UUCP uucp-dom:horus +if-bus.UUCP uucp-dom:if-bus +. uucp-dom:</programlisting> + + + <para>The first three lines handle special cases where + domain-addressed mail should not be sent out to the default + route, but instead to some UUCP neighbor in order to + <quote>shortcut</quote> the delivery path. The next line handles + mail to the local Ethernet domain that can be delivered using + SMTP. Finally, the UUCP neighbors are mentioned in the .UUCP + pseudo-domain notation, to allow for a + <literal><replaceable>uucp-neighbor + </replaceable>!<replaceable>recipient</replaceable></literal> + override of the default rules. The last line is always a single + dot, matching everything else, with UUCP delivery to a UUCP + neighbor that serves as your universal mail gateway to the + world. All of the node names behind the + <literal>uucp-dom:</literal> keyword must be valid UUCP + neighbors, as you can verify using the command + <literal>uuname</literal>.</para> + + <para>As a reminder that this file needs to be converted into a + DBM database file before use. The command line to accomplish + this is best placed as a comment at the top of the <filename>mailertable</filename> file. + You always have to execute this command each time you change + your <filename>mailertable</filename> file.</para> + + <para>Final hint: if you are uncertain whether some particular + mail routing would work, remember the <option>-bt</option> + option to <application>sendmail</application>. It starts <application>sendmail</application> in <emphasis>address test + mode</emphasis>; enter <literal>3,0</literal>, followed + by the address you wish to test for the mail routing. The last + line tells you the used internal mail agent, the destination + host this agent will be called with, and the (possibly + translated) address. Leave this mode by typing <keycombo + action="simul"><keycap>Ctrl</keycap><keycap>D</keycap></keycombo>.</para> + + <screen>&prompt.user; <userinput>sendmail -bt</userinput> +ADDRESS TEST MODE (ruleset 3 NOT automatically invoked) +Enter <ruleset> <address> +<prompt>></prompt> <userinput>3,0 foo@example.com</userinput> +canonify input: foo @ example . com +... +parse returns: $# uucp-dom $@ <replaceable>your.uucp.relay</replaceable> $: foo < @ example . com . > +<prompt>></prompt> <userinput>^D</userinput></screen> + </sect1> + + <sect1 id="outgoing-only"> + <sect1info> + <authorgroup> + <author> + <firstname>Bill</firstname> + <surname>Moran</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>Setting Up to Send Only</title> + + <para>There are many instances where you may only want to send + mail through a relay. Some examples are:</para> + + <itemizedlist> + <listitem> + <para>Your computer is a desktop machine, but you want + to use programs such as &man.send-pr.1;. To do so, you should use + your ISP's mail relay.</para> + </listitem> + + <listitem> + <para>The computer is a server that does not handle mail + locally, but needs to pass off all mail to a relay for + processing.</para> + </listitem> + </itemizedlist> + + <para>Just about any <acronym>MTA</acronym> is capable of filling + this particular niche. Unfortunately, it can be very difficult + to properly configure a full-featured <acronym>MTA</acronym> + just to handle offloading mail. Programs such as + <application>sendmail</application> and + <application>postfix</application> are largely overkill for + this use.</para> + + <para>Additionally, if you are using a typical Internet access + service, your agreement may forbid you from running a + <quote>mail server</quote>.</para> + + <para>The easiest way to fulfill those needs is to install the + <filename role="package">mail/ssmtp</filename> port. Execute + the following commands as <username>root</username>:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/mail/ssmtp</userinput> +&prompt.root; <userinput>make install replace clean</userinput></screen> + + <para>Once installed, + <filename role="package">mail/ssmtp</filename> can be configured + with a four-line file located at + <filename>/usr/local/etc/ssmtp/ssmtp.conf</filename>:</para> + + <programlisting>root=yourrealemail@example.com +mailhub=mail.example.com +rewriteDomain=example.com +hostname=_HOSTNAME_</programlisting> + + <para>Make sure you use your real email address for + <username>root</username>. Enter your ISP's outgoing mail relay + in place of <hostid role="fqdn">mail.example.com</hostid> (some ISPs call + this the <quote>outgoing mail server</quote> or + <quote>SMTP server</quote>).</para> + + <para>Make sure you disable <application>sendmail</application>, + including the outgoing mail service. See + <xref linkend="mail-disable-sendmail"> for details.</para> + + <para><filename role="package">mail/ssmtp</filename> has some + other options available. See the example configuration file in + <filename>/usr/local/etc/ssmtp</filename> or the manual page of + <application>ssmtp</application> for some examples and more + information.</para> + + <para>Setting up <application>ssmtp</application> in this manner + will allow any software on your computer that needs to send + mail to function properly, while not violating your ISP's usage + policy or allowing your computer to be hijacked for spamming.</para> + </sect1> + + <sect1 id="SMTP-dialup"> + <title>Using Mail with a Dialup Connection</title> + + <para>If you have a static IP address, you should not need to + adjust anything from the defaults. Set your host name to your + assigned Internet name and <application>sendmail</application> will do the rest.</para> + + <para>If you have a dynamically assigned IP number and use a + dialup PPP connection to the Internet, you will probably have a + mailbox on your ISPs mail server. Let's assume your ISP's domain + is <hostid role="domainname">example.net</hostid>, and that your + user name is <username>user</username>, you have called your + machine <hostid role="fqdn">bsd.home</hostid>, and your ISP has + told you that you may use <hostid + role="fqdn">relay.example.net</hostid> as a mail relay.</para> + + <para>In order to retrieve mail from your mailbox, you must + install a retrieval agent. The + <application>fetchmail</application> utility is a good choice as + it supports many different protocols. This program is available + as a package or from the Ports Collection (<filename + role="package">mail/fetchmail</filename>). Usually, your <acronym>ISP</acronym> will + provide <acronym>POP</acronym>. If you are using user <acronym>PPP</acronym>, you can + automatically fetch your mail when an Internet connection is + established with the following entry in + <filename>/etc/ppp/ppp.linkup</filename>:</para> + + <programlisting>MYADDR: +!bg su user -c fetchmail</programlisting> + + <para>If you are using <application>sendmail</application> (as + shown below) to deliver mail to non-local accounts, you probably + want to have <application>sendmail</application> process your + mailqueue as soon as your Internet connection is established. + To do this, put this command after the + <command>fetchmail</command> command in + <filename>/etc/ppp/ppp.linkup</filename>:</para> + + <programlisting> !bg su user -c "sendmail -q"</programlisting> + + <para>Assume that you have an account for + <username>user</username> on <hostid + role="fqdn">bsd.home</hostid>. In the home directory of + <username>user</username> on <hostid + role="fqdn">bsd.home</hostid>, create a + <filename>.fetchmailrc</filename> file:</para> + + <programlisting>poll example.net protocol pop3 fetchall pass MySecret</programlisting> + + <para>This file should not be readable by anyone except + <username>user</username> as it contains the password + <literal>MySecret</literal>.</para> + + <para>In order to send mail with the correct + <literal>from:</literal> header, you must tell + <application>sendmail</application> to use + <email>user@example.net</email> rather than + <email role="nolink">user@bsd.home</email>. You may also wish to tell + <application>sendmail</application> to send all mail via <hostid + role="fqdn">relay.example.net</hostid>, allowing quicker mail + transmission.</para> + + <para>The following <filename>.mc</filename> file should + suffice:</para> + + <programlisting>VERSIONID(`bsd.home.mc version 1.0') +OSTYPE(bsd4.4)dnl +FEATURE(nouucp)dnl +MAILER(local)dnl +MAILER(smtp)dnl +Cwlocalhost +Cwbsd.home +MASQUERADE_AS(`example.net')dnl +FEATURE(allmasquerade)dnl +FEATURE(masquerade_envelope)dnl +FEATURE(nocanonify)dnl +FEATURE(nodns)dnl +define(`SMART_HOST', `relay.example.net') +Dmbsd.home +define(`confDOMAIN_NAME',`bsd.home')dnl +define(`confDELIVERY_MODE',`deferred')dnl</programlisting> + + <para>Refer to the previous section for details of how to turn + this <filename>.mc</filename> file into a + <filename>sendmail.cf</filename> file. Also, do not forget to + restart <application>sendmail</application> after updating + <filename>sendmail.cf</filename>.</para> + </sect1> + + <sect1 id="SMTP-Auth"> + <sect1info> + <authorgroup> + <author> + <firstname>James</firstname> + <surname>Gorham</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>SMTP Authentication</title> + + <para>Having <acronym>SMTP</acronym> Authentication in place on + your mail server has a number of benefits. + <acronym>SMTP</acronym> Authentication can add another layer + of security to <application>sendmail</application>, and has the benefit of giving mobile + users who switch hosts the ability to use the same mail server + without the need to reconfigure their mail client settings + each time.</para> + + <procedure> + <step> + <para>Install <filename role="package">security/cyrus-sasl2</filename> + from the ports. You can find this port in + <filename role="package">security/cyrus-sasl2</filename>. The + <filename role="package">security/cyrus-sasl2</filename> port + supports a number of compile-time options. For the SMTP + Authentication method we will be using here, make sure that + the <option>LOGIN</option> option is not disabled.</para> + </step> + + + <step> + <para>After installing <filename role="package">security/cyrus-sasl2</filename>, + edit <filename>/usr/local/lib/sasl2/Sendmail.conf</filename> + (or create it if it does not exist) and add the following + line:</para> + + <programlisting>pwcheck_method: saslauthd</programlisting> + </step> + + <step> + <para>Next, install <filename role="package">security/cyrus-sasl2-saslauthd</filename>, + edit <filename>/etc/rc.conf</filename> to add the following + line:</para> + + <programlisting>saslauthd_enable="YES"</programlisting> + + <para>and finally start the saslauthd daemon:</para> + + <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/saslauthd start</userinput></screen> + + <para>This daemon serves as a broker for <application>sendmail</application> to + authenticate against your FreeBSD <filename>passwd</filename> + database. This saves the trouble of creating a new set of usernames + and passwords for each user that needs to use + <acronym>SMTP</acronym> authentication, and keeps the login + and mail password the same.</para> + </step> + + <step> + <para>Now edit <filename>/etc/make.conf</filename> and add the + following lines:</para> + + <programlisting>SENDMAIL_CFLAGS=-I/usr/local/include/sasl -DSASL +SENDMAIL_LDFLAGS=-L/usr/local/lib +SENDMAIL_LDADD=-lsasl2</programlisting> + + <para>These lines will give <application>sendmail</application> + the proper configuration options for linking + to <filename role="package">cyrus-sasl2</filename> at compile time. + Make sure that <filename role="package">cyrus-sasl2</filename> + has been installed before recompiling + <application>sendmail</application>.</para> + </step> + + <step> + <para>Recompile <application>sendmail</application> by executing the following commands:</para> + + <screen>&prompt.root; <userinput>cd /usr/src/lib/libsmutil</userinput> +&prompt.root; <userinput>make cleandir && make obj && make</userinput> +&prompt.root; <userinput>cd /usr/src/lib/libsm</userinput> +&prompt.root; <userinput>make cleandir && make obj && make</userinput> +&prompt.root; <userinput>cd /usr/src/usr.sbin/sendmail</userinput> +&prompt.root; <userinput>make cleandir && make obj && make && make install</userinput></screen> + + <para>The compile of <application>sendmail</application> should not have any problems + if <filename>/usr/src</filename> has not been changed extensively + and the shared libraries it needs are available.</para> + </step> + + <step> + <para>After <application>sendmail</application> has been compiled + and reinstalled, edit your <filename>/etc/mail/freebsd.mc</filename> + file (or whichever file you use as your <filename>.mc</filename> file. Many administrators + choose to use the output from &man.hostname.1; as the <filename>.mc</filename> file for + uniqueness). Add these lines to it:</para> + + <programlisting>dnl set SASL options +TRUST_AUTH_MECH(`GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl +define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl</programlisting> + + <para>These options configure the different methods available to + <application>sendmail</application> for authenticating users. + If you would like to use a method other than + <application>pwcheck</application>, please see the + included documentation.</para> + </step> + + <step> + <para>Finally, run &man.make.1; while in <filename>/etc/mail</filename>. + That will run your new <filename>.mc</filename> file and create a <filename>.cf</filename> file named + <filename>freebsd.cf</filename> (or whatever name you have used + for your <filename>.mc</filename> file). Then use the + command <command>make install restart</command>, which will + copy the file to <filename>sendmail.cf</filename>, and will + properly restart <application>sendmail</application>. + For more information about this process, you should refer + to <filename>/etc/mail/Makefile</filename>.</para> + </step> + </procedure> + + <para>If all has gone correctly, you should be able to enter your login + information into the mail client and send a test message. + For further investigation, set the <option>LogLevel</option> of + <application>sendmail</application> to 13 and watch + <filename>/var/log/maillog</filename> for any errors.</para> + + <para>For more information, please see the <application>sendmail</application> + page regarding + <ulink url="http://www.sendmail.org/~ca/email/auth.html"> + <acronym>SMTP</acronym> authentication</ulink>.</para> + + </sect1> + + <sect1 id="mail-agents"> + <sect1info> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Silver</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Mail User Agents</title> + + <indexterm> + <primary>Mail User Agents</primary> + </indexterm> + + <para>A Mail User Agent (<acronym>MUA</acronym>) is an application + that is used to send and receive email. Furthermore, as email + <quote>evolves</quote> and becomes more complex, + <acronym>MUA</acronym>'s are becoming increasingly powerful in the + way they interact with email; this gives users increased + functionality and flexibility. &os; contains support for + numerous mail user agents, all of which can be easily installed + using the <link linkend="ports">FreeBSD Ports Collection</link>. + Users may choose between graphical email clients such as + <application>evolution</application> or + <application>balsa</application>, console based clients such as + <application>mutt</application>, <application>alpine</application> + or <command>mail</command>, or the web interfaces used by some + large organizations.</para> + + <sect2 id="mail-command"> + <title>mail</title> + + <para>&man.mail.1; is the default Mail User Agent + (<acronym>MUA</acronym>) in &os;. It is a + console based <acronym>MUA</acronym> that offers all the basic + functionality required to send and receive text-based email, + though it is limited in interaction abilities with attachments + and can only support local mailboxes.</para> + + <para>Although <command>mail</command> does not natively support + interaction with <acronym>POP</acronym> or + <acronym>IMAP</acronym> servers, these mailboxes may be + downloaded to a local <filename>mbox</filename> file using an + application such as <application>fetchmail</application>, which + will be discussed later in this chapter (<xref + linkend="mail-fetchmail">).</para> + + <para>In order to send and receive email, run + <command>mail</command>:</para> + + <screen>&prompt.user; <userinput>mail</userinput></screen> + + <para>The contents of the user mailbox in + <filename class="directory">/var/mail</filename> are + automatically read by the <command>mail</command> utility. + Should the mailbox be empty, the utility exits with a + message indicating that no mails could be found. Once the + mailbox has been read, the application interface is started, and + a list of messages will be displayed. Messages are automatically + numbered, as can be seen in the following example:</para> + + <screen>Mail version 8.1 6/6/93. Type ? for help. +"/var/mail/marcs": 3 messages 3 new +>N 1 root@localhost Mon Mar 8 14:05 14/510 "test" + N 2 root@localhost Mon Mar 8 14:05 14/509 "user account" + N 3 root@localhost Mon Mar 8 14:05 14/509 "sample"</screen> + + <para>Messages can now be read by using the <keycap>t</keycap> + <command>mail</command> command, suffixed by the message number + that should be displayed. In this example, we will read the + first email:</para> + + <screen>& <userinput>t 1</userinput> +Message 1: +From root@localhost Mon Mar 8 14:05:52 2004 +X-Original-To: marcs@localhost +Delivered-To: marcs@localhost +To: marcs@localhost +Subject: test +Date: Mon, 8 Mar 2004 14:05:52 +0200 (SAST) +From: root@localhost (Charlie Root) + +This is a test message, please reply if you receive it.</screen> + + <para>As can be seen in the example above, the <keycap>t</keycap> + key will cause the message to be displayed with full headers. + To display the list of messages again, the <keycap>h</keycap> + key should be used.</para> + + <para>If the email requires a response, you may use + <command>mail</command> to reply, by using either the + <keycap>R</keycap> or <keycap>r</keycap> <command>mail</command> + keys. The <keycap>R</keycap> key instructs + <command>mail</command> to reply only to the sender of the + email, while <keycap>r</keycap> replies not only to the sender, + but also to other recipients of the message. You may also + suffix these commands with the mail number which you would like + make a reply to. Once this has been done, the response should + be entered, and the end of the message should be marked by a + single <keycap>.</keycap> on a new line. An example can be seen + below:</para> + + <screen>& <userinput>R 1</userinput> +To: root@localhost +Subject: Re: test + +<userinput>Thank you, I did get your email. +.</userinput> +EOT</screen> + + <para>In order to send new email, the <keycap>m</keycap> + key should be used, followed by the + recipient email address. Multiple recipients may also be + specified by separating each address with the <keycap>,</keycap> + delimiter. The subject of the message may then be entered, + followed by the message contents. The end of the message should + be specified by putting a single <keycap>.</keycap> on a new + line.</para> + + <screen>& <userinput>mail root@localhost</userinput> +Subject: <userinput>I mastered mail + +Now I can send and receive email using mail ... :) +.</userinput> +EOT</screen> + + <para>While inside the <command>mail</command> utility, the + <keycap>?</keycap> command may be used to display help at any + time, the &man.mail.1; manual page should also be consulted for + more help with <command>mail</command>.</para> + + <note> + <para>As previously mentioned, the &man.mail.1; command was not + originally designed to handle attachments, and thus deals with + them very poorly. Newer <acronym>MUA</acronym>s such as + <application>mutt</application> handle attachments in a much + more intelligent way. But should you still wish to use the + <command>mail</command> command, the <filename + role="package">converters/mpack</filename> port may be of + considerable use.</para> + </note> + </sect2> + + <sect2 id="mutt-command"> + <title>mutt</title> + + <para><application>mutt</application> is a small yet very + powerful Mail User Agent, with excellent features, + just some of which include:</para> + + <itemizedlist> + <listitem> + <para>The ability to thread messages;</para> + </listitem> + + <listitem> + <para>PGP support for digital signing and encryption of + email;</para> + </listitem> + + <listitem> + <para>MIME Support;</para> + </listitem> + + <listitem> + <para>Maildir Support;</para> + </listitem> + + <listitem> + <para>Highly customizable.</para> + </listitem> + </itemizedlist> + + <para>All of these features help to make + <application>mutt</application> one of the most advanced mail + user agents available. See <ulink + url="http://www.mutt.org"></ulink> for more + information on <application>mutt</application>.</para> + + <para>The stable version of <application>mutt</application> may be + installed using the <filename + role="package">mail/mutt</filename> port, while the current + development version may be installed via the <filename + role="package">mail/mutt-devel</filename> port. After the port + has been installed, <application>mutt</application> can be + started by issuing the following command:</para> + + <screen>&prompt.user; <userinput>mutt</userinput></screen> + + <para><application>mutt</application> will automatically read the + contents of the user mailbox in <filename + class="directory">/var/mail</filename> and display the contents + if applicable. If no mails are found in the user mailbox, then + <application>mutt</application> will wait for commands from the + user. The example below shows <application>mutt</application> + displaying a list of messages:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="mail/mutt1" format="PNG"> + </imageobject> + </mediaobject> + + <para>In order to read an email, select it using the cursor + keys and press the <keycap>Enter</keycap> key. An example of + <application>mutt</application> displaying email can be seen + below:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="mail/mutt2" format="PNG"> + </imageobject> + </mediaobject> + + <para>As with the &man.mail.1; command, + <application>mutt</application> allows users to reply only to + the sender of the message as well as to all recipients. To + reply only to the sender of the email, use the + <keycap>r</keycap> keyboard shortcut. To send a group reply, + which will be sent to the original sender as well as all the + message recipients, use the <keycap>g</keycap> shortcut.</para> + + <note> + <para><application>mutt</application> makes use of the + &man.vi.1; command as an editor for creating and replying to + emails. This may be customized by the user by creating or + editing their own <filename>.muttrc</filename> file in their home directory and setting the + <literal>editor</literal> variable or by setting the + <envar>EDITOR</envar> environment variable. See + <ulink url="http://www.mutt.org/"></ulink> for more + information about configuring + <application>mutt</application>.</para> + </note> + + <para>In order to compose a new mail message, press + <keycap>m</keycap>. After a valid subject has been given, + <application>mutt</application> will start &man.vi.1; and the + mail can be written. Once the contents of the mail are + complete, save and quit from <command>vi</command> and + <application>mutt</application> will resume, displaying a + summary screen of the mail that is to be delivered. In order to + send the mail, press <keycap>y</keycap>. An example of the + summary screen can be seen below:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="mail/mutt3" format="PNG"> + </imageobject> + </mediaobject> + + <para><application>mutt</application> also contains extensive + help, which can be accessed from most of the menus by pressing + the <keycap>?</keycap> key. The top line also displays the + keyboard shortcuts where appropriate.</para> + + </sect2> + + <sect2 id="alpine-command"> + <title>alpine</title> + + <para><application>alpine</application> is aimed at a beginner + user, but also includes some advanced features.</para> + + <warning> + <para>The <application>alpine</application> software has had several remote vulnerabilities + discovered in the past, which allowed remote attackers to + execute arbitrary code as users on the local system, by the + action of sending a specially-prepared email. All such + <emphasis>known</emphasis> problems have been fixed, but the + <application>alpine</application> code is written in a very insecure style and the &os; + Security Officer believes there are likely to be other + undiscovered vulnerabilities. You install + <application>alpine</application> at your own risk.</para> + </warning> + + <para>The current version of <application>alpine</application> may + be installed using the <filename + role="package">mail/alpine</filename> port. Once the port has + installed, <application>alpine</application> can be started by + issuing the following command:</para> + + <screen>&prompt.user; <userinput>alpine</userinput></screen> + + <para>The first time that <application>alpine</application> is run + it displays a greeting page with a brief introduction, as well + as a request from the <application>alpine</application> + development team to send an anonymous email message allowing + them to judge how many users are using their client. To send + this anonymous message, press <keycap>Enter</keycap>, or + alternatively press <keycap>E</keycap> to exit the greeting + without sending an anonymous message. An example of the + greeting page can be seen below:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="mail/pine1" format="PNG"> + </imageobject> + </mediaobject> + + <para>Users are then presented with the main menu, which can be + easily navigated using the cursor keys. This main menu provides + shortcuts for the composing new mails, browsing of mail directories, + and even the administration of address book entries. Below the + main menu, relevant keyboard shortcuts to perform functions + specific to the task at hand are shown.</para> + + <para>The default directory opened by <application>alpine</application> + is the <filename class="directory">inbox</filename>. To view the message index, press + <keycap>I</keycap>, or select the <guimenuitem>MESSAGE INDEX</guimenuitem> + option as seen below:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="mail/pine2" format="PNG"> + </imageobject> + </mediaobject> + + <para>The message index shows messages in the current directory, + and can be navigated by using the cursor keys. Highlighted + messages can be read by pressing the + <keycap>Enter</keycap> key.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="mail/pine3" format="PNG"> + </imageobject> + </mediaobject> + + <para>In the screenshot below, a sample message is displayed by + <application>alpine</application>. Keyboard shortcuts are + displayed as a reference at the bottom of the screen. An + example of one of these shortcuts is the <keycap>r</keycap> key, + which tells the <acronym>MUA</acronym> to reply to the current + message being displayed.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="mail/pine4" format="PNG"> + </imageobject> + </mediaobject> + + <para>Replying to an email in <application>alpine</application> is + done using the <application>pico</application> editor, which is + installed by default with <application>alpine</application>. + The <application>pico</application> utility makes it easy to + navigate around the message and is slightly more forgiving on + novice users than &man.vi.1; or &man.mail.1;. Once the reply + is complete, the message can be sent by pressing + <keycombo action="simul"><keycap>Ctrl</keycap><keycap>X</keycap> + </keycombo>. The <application>alpine</application> application + will ask for confirmation.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="mail/pine5" format="PNG"> + </imageobject> + </mediaobject> + + <para>The <application>alpine</application> application can be + customized using the <guimenuitem>SETUP</guimenuitem> option from the main + menu. Consult <ulink url="http://www.washington.edu/alpine/"></ulink> + for more information.</para> + + </sect2> + </sect1> + + <sect1 id="mail-fetchmail"> + <sect1info> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Silver</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Using fetchmail</title> + + <indexterm> + <primary>fetchmail</primary> + </indexterm> + + <para><application>fetchmail</application> is a full-featured + <acronym>IMAP</acronym> and <acronym>POP</acronym> client which + allows users to automatically download mail from remote + <acronym>IMAP</acronym> and <acronym>POP</acronym> servers and + save it into local mailboxes; there it can be accessed more easily. + <application>fetchmail</application> can be installed using the + <filename role="package">mail/fetchmail</filename> port, and + offers various features, some of which include:</para> + + <itemizedlist> + <listitem> + <para>Support of <acronym>POP3</acronym>, + <acronym>APOP</acronym>, <acronym>KPOP</acronym>, + <acronym>IMAP</acronym>, <acronym>ETRN</acronym> and + <acronym>ODMR</acronym> protocols.</para> + </listitem> + + <listitem> + <para>Ability to forward mail using <acronym>SMTP</acronym>, which + allows filtering, forwarding, and aliasing to function + normally.</para> + </listitem> + + <listitem> + <para>May be run in daemon mode to check periodically for new + messages.</para> + </listitem> + + <listitem> + <para>Can retrieve multiple mailboxes and forward them based + on configuration, to different local users.</para> + </listitem> + </itemizedlist> + + <para>While it is outside the scope of this document to explain + all of <application>fetchmail</application>'s features, some + basic features will be explained. The + <application>fetchmail</application> utility requires a + configuration file known as <filename>.fetchmailrc</filename>, + in order to run correctly. This file includes server information + as well as login credentials. Due to the sensitive nature of the + contents of this file, it is advisable to make it readable only by the owner, + with the following command:</para> + + <screen>&prompt.user; <userinput>chmod 600 .fetchmailrc</userinput></screen> + + <para>The following <filename>.fetchmailrc</filename> serves as an + example for downloading a single user mailbox using + <acronym>POP</acronym>. It tells + <application>fetchmail</application> to connect to <hostid + role="fqdn">example.com</hostid> using a username of + <username>joesoap</username> and a password of + <literal>XXX</literal>. This example assumes that the user + <username>joesoap</username> is also a user on the local + system.</para> + + <programlisting>poll example.com protocol pop3 username "joesoap" password "XXX"</programlisting> + + <para>The next example connects to multiple <acronym>POP</acronym> + and <acronym>IMAP</acronym> servers and redirects to different + local usernames where applicable:</para> + + <programlisting>poll example.com proto pop3: +user "joesoap", with password "XXX", is "jsoap" here; +user "andrea", with password "XXXX"; +poll example2.net proto imap: +user "john", with password "XXXXX", is "myth" here;</programlisting> + + <para>The <application>fetchmail</application> utility can be run in daemon + mode by running it with the <option>-d</option> flag, followed + by the interval (in seconds) that + <application>fetchmail</application> should poll servers listed + in the <filename>.fetchmailrc</filename> file. The following + example would cause <application>fetchmail</application> to poll + every 600 seconds:</para> + + <screen>&prompt.user; <userinput>fetchmail -d 600</userinput></screen> + + <para>More information on <application>fetchmail</application> can + be found at <ulink + url="http://fetchmail.berlios.de/"></ulink>.</para> + </sect1> + + <sect1 id="mail-procmail"> + <sect1info> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Silver</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Using procmail</title> + + <indexterm> + <primary>procmail</primary> + </indexterm> + + <para>The <application>procmail</application> utility is an + incredibly powerful application used to filter incoming mail. + It allows users to define <quote>rules</quote> which can be + matched to incoming mails to perform specific functions or to + reroute mail to alternative mailboxes and/or email addresses. + <application>procmail</application> can be installed using the + <filename role="package">mail/procmail</filename> port. Once + installed, it can be directly integrated into most + <acronym>MTA</acronym>s; consult your <acronym>MTA</acronym> + documentation for more information. Alternatively, + <application>procmail</application> can be integrated by adding + the following line to a <filename>.forward</filename> in the home + directory of the user utilizing + <application>procmail</application> features:</para> + + <programlisting>"|exec /usr/local/bin/procmail || exit 75"</programlisting> + + <para>The following section will display some basic + <application>procmail</application> rules, as well as brief + descriptions on what they do. These rules, and others must be + inserted into a <filename>.procmailrc</filename> file, which + must reside in the user's home directory.</para> + + <para>The majority of these rules can also be found in the + &man.procmailex.5; manual page.</para> + + <para>Forward all mail from <email>user@example.com</email> to an + external address of <email role="nolink">goodmail@example2.com</email>:</para> + + <programlisting>:0 +* ^From.*user@example.com +! goodmail@example2.com</programlisting> + + <para>Forward all mails shorter than 1000 bytes to an external + address of <email role="nolink">goodmail@example2.com</email>:</para> + + <programlisting>:0 +* < 1000 +! goodmail@example2.com</programlisting> + + <para>Send all mail sent to <email>alternate@example.com</email> + into a mailbox called <filename>alternate</filename>:</para> + + <programlisting>:0 +* ^TOalternate@example.com +alternate</programlisting> + + <para>Send all mail with a subject of <quote>Spam</quote> to + <filename>/dev/null</filename>:</para> + + <programlisting>:0 +^Subject:.*Spam +/dev/null</programlisting> + + <para>A useful recipe that parses incoming <hostid role="domainname">&os;.org</hostid> mailing lists + and places each list in its own mailbox:</para> + + <programlisting>:0 +* ^Sender:.owner-freebsd-\/[^@]+@FreeBSD.ORG +{ + LISTNAME=${MATCH} + :0 + * LISTNAME??^\/[^@]+ + FreeBSD-${MATCH} +}</programlisting> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/mirrors/Makefile b/en_US.ISO8859-1/books/handbook/mirrors/Makefile new file mode 100644 index 0000000000..ad5c0e2abe --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/mirrors/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= mirrors/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml new file mode 100644 index 0000000000..bfe03ad5c8 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml @@ -0,0 +1,3343 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<appendix id="mirrors"> + <title>Obtaining &os;</title> + + <sect1 id="mirrors-cdrom"> + <title>CDROM and DVD Publishers</title> + + <sect2> + <title>Retail Boxed Products</title> + + <para>&os; is available as a boxed product (&os; CDs, + additional software, and printed documentation) from several + retailers:</para> + + <itemizedlist> + <listitem> + <address> + <otheraddr>CompUSA</otheraddr> + WWW: <otheraddr><ulink url="http://www.compusa.com/"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>Frys Electronics</otheraddr> + WWW: <otheraddr><ulink url="http://www.frys.com/"></ulink></otheraddr> + </address> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>CD and DVD Sets</title> + + <para>&os; CD and DVD sets are available from many online + retailers:</para> + + <itemizedlist> + <listitem> + <address> + <otheraddr>&os; Mall, Inc.</otheraddr> + <street>700 Harvest Park Ste F</street> + <city>Brentwood</city>, <state>CA</state> <postcode>94513</postcode> + <country>USA</country> + Phone: <phone>+1 925 240-6652</phone> + Fax: <fax>+1 925 674-0821</fax> + Email: <email>info@freebsdmall.com</email> + WWW: <otheraddr><ulink url="http://www.freebsdmall.com/"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>Dr. Hinner EDV</otheraddr> + <street>St. Augustinus-Str. 10</street> + <postcode>D-81825</postcode> <city>München</city> + <country>Germany</country> + Phone: <phone>(089) 428 419</phone> + WWW: <otheraddr><ulink url="http://www.hinner.de/linux/freebsd.html"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>Ikarios</otheraddr> + <street>22-24 rue Voltaire</street> + <postcode>92000</postcode> <city>Nanterre</city> + <country>France</country> + WWW: <otheraddr><ulink url="http://ikarios.com/form/#freebsd"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>JMC Software</otheraddr> + <country>Ireland</country> + Phone: <phone>353 1 6291282</phone> + WWW: <otheraddr><ulink url="http://www.thelinuxmall.com"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>Linux Distro UK</otheraddr> + <street>42 Wharfedale Road</street> + <city>Margate</city> + <postcode>CT9 2TB</postcode> + <country>United Kingdom</country> + WWW: <otheraddr><ulink url="https://linux-distro.co.uk/"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>The Linux Emporium</otheraddr> + <street>Hilliard House, Lester Way</street> + <city>Wallingford</city> + <postcode>OX10 9TA</postcode> + <country>United Kingdom</country> + Phone: <phone>+44 1491 837010</phone> + Fax: <fax>+44 1491 837016</fax> + WWW: <otheraddr><ulink url="http://www.linuxemporium.co.uk/products/bsd/"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>Linux+ DVD Magazine</otheraddr> + <street>Lewartowskiego 6</street> + <city>Warsaw</city> + <postcode>00-190</postcode> + <country>Poland</country> + Phone: <phone>+48 22 860 18 18</phone> + Email: <email>editors@lpmagazine.org</email> + WWW: <otheraddr><ulink url="http://www.lpmagazine.org/"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>Linux System Labs Australia</otheraddr> + <street>21 Ray Drive</street> + <city>Balwyn North</city> + <postcode>VIC - 3104</postcode> + <country>Australia</country> + Phone: <phone>+61 3 9857 5918</phone> + Fax: <fax>+61 3 9857 8974</fax> + WWW: <otheraddr><ulink url="http://www.lsl.com.au"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>LinuxCenter.Ru</otheraddr> + <street>Galernaya Street, 55</street> + <city>Saint-Petersburg</city> + <postcode>190000</postcode> + <country>Russia</country> + Phone: <phone>+7-812-3125208</phone> + Email: <email>info@linuxcenter.ru</email> + WWW: <otheraddr><ulink url="http://linuxcenter.ru/shop/freebsd"></ulink></otheraddr> + </address> + </listitem> + + </itemizedlist> + </sect2> + + <sect2> + <title>Distributors</title> + + <para>If you are a reseller and want to carry &os; CDROM products, + please contact a distributor:</para> + + <itemizedlist> + <listitem> + <address> + <otheraddr>Cylogistics</otheraddr> + <street>809B Cuesta Dr., #2149</street> + <city>Mountain View</city>, <state>CA</state> <postcode>94040</postcode> + <country>USA</country> + Phone: <phone>+1 650 694-4949</phone> + Fax: <fax>+1 650 694-4953</fax> + Email: <email>sales@cylogistics.com</email> + WWW: <otheraddr><ulink url="http://www.cylogistics.com/"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>Ingram Micro</otheraddr> + <street>1600 E. St. Andrew Place</street> + <city>Santa Ana</city>, <state>CA</state> <postcode>92705-4926</postcode> + <country>USA</country> + Phone: <phone>1 (800) 456-8000</phone> + WWW: <otheraddr><ulink url="http://www.ingrammicro.com/"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>Kudzu, LLC</otheraddr> + <street>7375 Washington Ave. S.</street> + <city>Edina</city>, <state>MN</state> <postcode>55439</postcode> + <country>USA</country> + Phone: <phone>+1 952 947-0822</phone> + Fax: <fax>+1 952 947-0876</fax> + Email: <email>sales@kudzuenterprises.com</email> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>LinuxCenter.Ru</otheraddr> + <street>Galernaya Street, 55</street> + <city>Saint-Petersburg</city> + <postcode>190000</postcode> + <country>Russia</country> + Phone: <phone>+7-812-3125208</phone> + Email: <email>info@linuxcenter.ru</email> + WWW: <otheraddr><ulink url="http://linuxcenter.ru/freebsd"></ulink></otheraddr> + </address> + </listitem> + + <listitem> + <address> + <otheraddr>Navarre Corp</otheraddr> + <street>7400 49th Ave South</street> + <city>New Hope</city>, <state>MN</state> <postcode>55428</postcode> + <country>USA</country> + Phone: <phone>+1 763 535-8333</phone> + Fax: <fax>+1 763 535-0341</fax> + WWW: <otheraddr><ulink url="http://www.navarre.com/"></ulink></otheraddr> + </address> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="mirrors-ftp"> + <title>FTP Sites</title> + + <para>The official sources for &os; are available via anonymous FTP + from a worldwide set of mirror sites. The site + <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/"></ulink> is well + connected and allows a large number of connections to it, but + you are probably better off finding a <quote>closer</quote> + mirror site (especially if you decide to set up some sort of + mirror site).</para> + + <para>Additionally, &os; is available via anonymous FTP from the + following mirror sites. If you choose to obtain &os; via anonymous + FTP, please try to use a site near you. The mirror sites listed as + <quote>Primary Mirror Sites</quote> typically have the entire &os; archive (all + the currently available versions for each of the architectures) but + you will probably have faster download times from a site that is + in your country or region. The regional sites carry the most recent + versions for the most popular architecture(s) but might not carry + the entire &os; archive. All sites provide access via anonymous + FTP but some sites also provide access via other methods. The access + methods available for each site are provided in parentheses + after the hostname.</para> + + &chap.mirrors.ftp.inc; + </sect1> + + <sect1 id="mirrors-bittorrent"> + <title>BitTorrent</title> + + <indexterm> + <primary>BitTorrent</primary> + </indexterm> + + <para>The ISO images for the basic release CDs are available via + BitTorrent. A collection of torrent files to download the + images is available at <ulink + url="http://torrents.freebsd.org:8080/">http://torrents.freebsd.org:8080</ulink></para> + + <para>The BitTorrent client software is available from the + <filename role="package">net-p2p/py-bittorrent</filename> port, + or a precompiled package.</para> + + <para>After downloading the ISO image with BitTorrent, you may + burn it to CD or DVD media as described in <xref + linkend="burncd">, burncd.</para> + </sect1> + + <sect1 id="anoncvs"> + <title>Anonymous CVS</title> + + <sect2> + <title><anchor id="anoncvs-intro">Introduction</title> + + <indexterm> + <primary>CVS</primary> + <secondary>anonymous</secondary> + </indexterm> + + <para>Anonymous CVS (or, as it is otherwise known, + <emphasis>anoncvs</emphasis>) is a feature provided by the CVS + utilities bundled with &os; for synchronizing with a remote + CVS repository. Among other things, it allows users of &os; + to perform, with no special privileges, read-only CVS operations + against one of the &os; project's official anoncvs servers. + To use it, one simply sets the <envar>CVSROOT</envar> + environment variable to point at the appropriate anoncvs server, + provides the well-known password <quote>anoncvs</quote> with the + <command>cvs login</command> command, and then uses the + &man.cvs.1; command to access it like any local + repository.</para> + + <note> + <para>The <command>cvs login</command> command, stores the passwords + that are used for authenticating to the CVS server in a file + called <filename>.cvspass</filename> in your + <envar>HOME</envar> directory. If this file does not exist, + you might get an error when trying to use <command>cvs + login</command> for the first time. Just make an empty + <filename>.cvspass</filename> file, and retry to login.</para> + </note> + + <para>While it can also be said that the <link + linkend="cvsup">CVSup</link> and <emphasis>anoncvs</emphasis> + services both perform essentially the same function, there are + various trade-offs which can influence the user's choice of + synchronization methods. In a nutshell, + <application>CVSup</application> is much more efficient in its + usage of network resources and is by far the most technically + sophisticated of the two, but at a price. To use + <application>CVSup</application>, a special client must first be + installed and configured before any bits can be grabbed, and + then only in the fairly large chunks which + <application>CVSup</application> calls + <emphasis>collections</emphasis>.</para> + + <para><application>Anoncvs</application>, by contrast, can be used + to examine anything from an individual file to a specific + program (like <command>ls</command> or <command>grep</command>) + by referencing the CVS module name. Of course, + <application>anoncvs</application> is also only good for + read-only operations on the CVS repository, so if it is your + intention to support local development in one repository shared + with the &os; project bits then + <application>CVSup</application> is really your only + option.</para> + </sect2> + + <sect2> + <title><anchor id="anoncvs-usage">Using Anonymous CVS</title> + + <para>Configuring &man.cvs.1; to use an Anonymous CVS repository + is a simple matter of setting the <envar>CVSROOT</envar> + environment variable to point to one of the &os; project's + <emphasis>anoncvs</emphasis> servers. At the time of this + writing, the following servers are available:</para> + + <itemizedlist> + <listitem> + <para><emphasis>France</emphasis>: + :pserver:anoncvs@anoncvs.fr.FreeBSD.org:/home/ncvs + (For pserver mode, use <command>cvs login</command> and + enter the password <quote>anoncvs</quote> when prompted. + For ssh, no password is required.)</para> + </listitem> + <!-- + <listitem> + <para><emphasis>Japan</emphasis>: + :pserver:anoncvs@anoncvs.jp.FreeBSD.org:/home/ncvs + (Use <command>cvs login</command> and enter the password + <quote>anoncvs</quote> when prompted.)</para> + </listitem> + --> + <listitem> + <para><emphasis>Taiwan</emphasis>: + :pserver:anoncvs@anoncvs.tw.FreeBSD.org:/home/ncvs + (For pserver mode, use <command>cvs login</command> and + enter any password when prompted. For ssh, no password + is required.)</para> + + <programlisting>SSH2 HostKey: 1024 02:ed:1b:17:d6:97:2b:58:5e:5c:e2:da:3b:89:88:26 /etc/ssh/ssh_host_rsa_key.pub +SSH2 HostKey: 1024 e8:3b:29:7b:ca:9f:ac:e9:45:cb:c8:17:ae:9b:eb:55 /etc/ssh/ssh_host_dsa_key.pub</programlisting> + + </listitem> + <listitem> + <para><emphasis>USA</emphasis>: + anoncvs@anoncvs1.FreeBSD.org:/home/ncvs (For ssh, use ssh + version 2 and no password is required.)</para> + + <programlisting>SSH2 HostKey: 2048 53:1f:15:a3:72:5c:43:f6:44:0e:6a:e9:bb:f8:01:62 /etc/ssh/ssh_host_dsa_key.pub</programlisting> + + </listitem> + </itemizedlist> + + <para>Since CVS allows one to <quote>check out</quote> virtually + any version of the &os; sources that ever existed (or, in + some cases, will exist), you need to be + familiar with the revision (<option>-r</option>) flag to + &man.cvs.1; and what some of the permissible values for it in + the &os; Project repository are.</para> + + <para>There are two kinds of tags, revision tags and branch tags. + A revision tag refers to a specific revision. Its meaning stays + the same from day to day. A branch tag, on the other hand, + refers to the latest revision on a given line of development, at + any given time. Because a branch tag does not refer to a + specific revision, it may mean something different tomorrow than + it means today.</para> + + <para><xref linkend="cvs-tags"> contains revision tags that users + might be interested + in. Again, none of these are valid for the Ports Collection + since the Ports Collection does not have multiple + branches of development.</para> + + <para>When you specify a branch tag, you normally receive the + latest versions of the files on that line of development. If + you wish to receive some past version, you can do so by + specifying a date with the <option>-D date</option> flag. + See the &man.cvs.1; manual page for more details.</para> + </sect2> + + <sect2> + <title>Examples</title> + + <para>While it really is recommended that you read the manual page + for &man.cvs.1; thoroughly before doing anything, here are some + quick examples which essentially show how to use Anonymous + CVS:</para> + + <example> + <title>Checking Out Something from -CURRENT (&man.ls.1;):</title> + + <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.tw.FreeBSD.org:/home/ncvs</userinput> +&prompt.user; <userinput>cvs login</userinput> +<emphasis>At the prompt, enter any word for</emphasis> <quote>password</quote>. +&prompt.user; <userinput>cvs co ls</userinput> + </screen> + </example> + + <example> + <title>Using SSH to Check Out the <filename>src/</filename> + Tree:</title> + <screen>&prompt.user; <userinput>cvs -d anoncvs@anoncvs1.FreeBSD.org:/home/ncvs co src</userinput> +The authenticity of host 'anoncvs1.freebsd.org (216.87.78.137)' can't be established. +DSA key fingerprint is 53:1f:15:a3:72:5c:43:f6:44:0e:6a:e9:bb:f8:01:62. +Are you sure you want to continue connecting (yes/no)? <userinput>yes</userinput> +Warning: Permanently added 'anoncvs1.freebsd.org' (DSA) to the list of known hosts.</screen> + </example> + + <example> + <title>Checking Out the Version of &man.ls.1; in the 8-STABLE + Branch:</title> + + <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.tw.FreeBSD.org:/home/ncvs</userinput> +&prompt.user; <userinput>cvs login</userinput> +<emphasis>At the prompt, enter any word for</emphasis> <quote>password</quote>. +&prompt.user; <userinput>cvs co -rRELENG_8 ls</userinput> + </screen> + </example> + + <example> + <title>Creating a List of Changes (as Unified Diffs) to &man.ls.1;</title> + + <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.tw.FreeBSD.org:/home/ncvs</userinput> +&prompt.user; <userinput>cvs login</userinput> +<emphasis>At the prompt, enter any word for</emphasis> <quote>password</quote>. +&prompt.user; <userinput>cvs rdiff -u -rRELENG_8_0_0_RELEASE -rRELENG_8_1_0_RELEASE ls</userinput> + </screen> + </example> + + <example> + <title>Finding Out What Other Module Names Can Be Used:</title> + + <screen>&prompt.user; <userinput>setenv CVSROOT :pserver:anoncvs@anoncvs.tw.FreeBSD.org:/home/ncvs</userinput> +&prompt.user; <userinput>cvs login</userinput> +<emphasis>At the prompt, enter any word for</emphasis> <quote>password</quote>. +&prompt.user; <userinput>cvs co modules</userinput> +&prompt.user; <userinput>more modules/modules</userinput> + </screen> + </example> + </sect2> + + <sect2> + <title>Other Resources</title> + + <para>The following additional resources may be helpful in learning + CVS:</para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://users.csc.calpoly.edu/~gfisher/classes/308/handouts/cvs-basics.html">CVS Tutorial</ulink> from California + Polytechnic State University.</para> + </listitem> + + <listitem> + <para><ulink url="http://www.nongnu.org/cvs/">CVS Home</ulink>, + the CVS development and support community.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.FreeBSD.org/cgi/cvsweb.cgi">CVSweb</ulink> is + the &os; Project web interface for CVS.</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + + <sect1 id="ctm"> + <title>Using CTM</title> + + <indexterm> + <primary>CTM</primary> + </indexterm> + + <para><application>CTM</application> is a method for keeping a + remote directory tree in sync with a central one. It has been + developed for usage with &os;'s source trees, though other + people may find it useful for other purposes as time goes by. + Little, if any, documentation currently exists at this time on the + process of creating deltas, so contact the &a.ctm-users.name; mailing list for more + information and if you wish to use <application>CTM</application> + for other things.</para> + + <sect2> + <title>Why Should I Use <application>CTM</application>?</title> + + <para><application>CTM</application> will give you a local copy of + the &os; source trees. There are a number of + <quote>flavors</quote> of the tree available. Whether you wish + to track the entire CVS tree or just one of the branches, + <application>CTM</application> can provide you the information. + If you are an active developer on &os;, but have lousy or + non-existent TCP/IP connectivity, or simply wish to have the + changes automatically sent to you, + <application>CTM</application> was made for you. You will need + to obtain up to three deltas per day for the most active + branches. However, you should consider having them sent by + automatic email. The sizes of the updates are always kept as + small as possible. This is typically less than 5K, with an + occasional (one in ten) being 10-50K and every now and then a + large 100K+ or more coming around.</para> + + <para>You will also need to make yourself aware of the various + caveats related to working directly from the development sources + rather than a pre-packaged release. This is particularly true + if you choose the <quote>current</quote> sources. It is + recommended that you read <link linkend="current">Staying + current with &os;</link>.</para> + </sect2> + + <sect2> + <title>What Do I Need to Use + <application>CTM</application>?</title> + + <para>You will need two things: The <application>CTM</application> + program, and the initial deltas to feed it (to get up to + <quote>current</quote> levels).</para> + + <para>The <application>CTM</application> program has been part of + &os; ever since version 2.0 was released, and lives in + <filename>/usr/src/usr.sbin/ctm</filename> if you have a copy + of the source available.</para> + + <para>The <quote>deltas</quote> you feed + <application>CTM</application> can be had two ways, FTP or + email. If you have general FTP access to the Internet then the + following FTP sites support access to + <application>CTM</application>:</para> + + <para><ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/"></ulink></para> + + <para>or see section <link + linkend="mirrors-ctm">mirrors</link>.</para> + + <para>FTP the relevant directory and fetch the + <filename>README</filename> file, starting from there.</para> + + <para>If you wish to get your deltas via email:</para> + + <para>Subscribe to one of the + <application>CTM</application> distribution lists. + &a.ctm-cvs-cur.name; supports the entire CVS tree. + &a.ctm-src-cur.name; supports the head of the development + branch. &a.ctm-src-7.name; supports the 7.X release + branch, etc.. (If you do not know how to subscribe yourself + to a list, click on the list name above or go to + &a.mailman.lists.link; and click on the list that you + wish to subscribe to. The list page should contain all of + the necessary subscription instructions.)</para> + + <para>When you begin receiving your <application>CTM</application> + updates in the mail, you may use the + <command>ctm_rmail</command> program to unpack and apply them. + You can actually use the <command>ctm_rmail</command> program + directly from a entry in <filename>/etc/aliases</filename> if + you want to have the process run in a fully automated fashion. + Check the <command>ctm_rmail</command> manual page for more + details.</para> + + <note> + <para>No matter what method you use to get the + <application>CTM</application> deltas, you should subscribe to + the &a.ctm-announce.name; mailing list. In + the future, this will be the only place where announcements + concerning the operations of the + <application>CTM</application> system will be posted. Click + on the list name above and follow the instructions + to subscribe to the + list.</para> + </note> + </sect2> + + <sect2> + <title>Using <application>CTM</application> for the First + Time</title> + + <para>Before you can start using <application>CTM</application> + deltas, you will need to get to a starting point for the deltas + produced subsequently to it.</para> + + <para>First you should determine what you already have. Everyone + can start from an <quote>empty</quote> directory. You must use + an initial <quote>Empty</quote> delta to start off your + <application>CTM</application> supported tree. At some point it + is intended that one of these <quote>started</quote> deltas be + distributed on the CD for your convenience, however, this does + not currently happen.</para> + + <para>Since the trees are many tens of megabytes, you should + prefer to start from something already at hand. If you have a + -RELEASE CD, you can copy or extract an initial source from it. + This will save a significant transfer of data.</para> + + <para>You can recognize these <quote>starter</quote> deltas by the + <literal>X</literal> appended to the number + (<filename>src-cur.3210XEmpty.gz</filename> for instance). The + designation following the <literal>X</literal> corresponds to + the origin of your initial <quote>seed</quote>. + <filename>Empty</filename> is an empty directory. As a rule a + base transition from <literal>Empty</literal> is produced + every 100 deltas. By the way, they are large! 70 to 80 + Megabytes of <command>gzip</command>'d data is common for the + <filename>XEmpty</filename> deltas.</para> + + <para>Once you have picked a base delta to start from, you will also + need all deltas with higher numbers following it.</para> + </sect2> + + <sect2> + <title>Using <application>CTM</application> in Your Daily + Life</title> + + <para>To apply the deltas, simply say:</para> + + <screen>&prompt.root; <userinput>cd /where/ever/you/want/the/stuff</userinput> +&prompt.root; <userinput>ctm -v -v /where/you/store/your/deltas/src-xxx.*</userinput></screen> + + <para><application>CTM</application> understands deltas which have + been put through <command>gzip</command>, so you do not need to + <command>gunzip</command> them first, this saves disk space.</para> + + <para>Unless it feels very secure about the entire process, + <application>CTM</application> will not touch your tree. To + verify a delta you can also use the <option>-c</option> flag and + <application>CTM</application> will not actually touch your + tree; it will merely verify the integrity of the delta and see + if it would apply cleanly to your current tree.</para> + + <para>There are other options to <application>CTM</application> + as well, see the manual pages or look in the sources for more + information.</para> + + <para>That is really all there is to it. Every time you get a new + delta, just run it through <application>CTM</application> to + keep your sources up to date.</para> + + <para>Do not remove the deltas if they are hard to download again. + You just might want to keep them around in case something bad + happens. Even if you only have floppy disks, consider using + <command>fdwrite</command> to make a copy.</para> + </sect2> + + <sect2> + <title>Keeping Your Local Changes</title> + + <para>As a developer one would like to experiment with and change + files in the source tree. <application>CTM</application> + supports local modifications in a limited way: before checking + for the presence of a file <filename>foo</filename>, it first + looks for <filename>foo.ctm</filename>. If this file exists, + <application>CTM</application> will operate on it instead of + <filename>foo</filename>.</para> + + <para>This behavior gives us a simple way to maintain local + changes: simply copy the files you plan to modify to the + corresponding file names with a <filename>.ctm</filename> + suffix. Then you can freely hack the code, while <application>CTM</application> keeps the + <filename>.ctm</filename> file up-to-date.</para> + </sect2> + + <sect2> + <title>Other Interesting <application>CTM</application> Options</title> + + <sect3> + <title>Finding Out Exactly What Would Be Touched by an + Update</title> + + <para>You can determine the list of changes that + <application>CTM</application> will make on your source + repository using the <option>-l</option> option to + <application>CTM</application>.</para> + + <para>This is useful if you would like to keep logs of the + changes, pre- or post- process the modified files in any + manner, or just are feeling a tad paranoid.</para> + </sect3> + + <sect3> + <title>Making Backups Before Updating</title> + + <para>Sometimes you may want to backup all the files that would + be changed by a <application>CTM</application> update.</para> + + <para>Specifying the <option>-B backup-file</option> option + causes <application>CTM</application> to backup all files that + would be touched by a given <application>CTM</application> + delta to <filename>backup-file</filename>.</para> + </sect3> + + <sect3> + <title>Restricting the Files Touched by an Update</title> + + <para>Sometimes you would be interested in restricting the scope + of a given <application>CTM</application> update, or may be + interested in extracting just a few files from a sequence of + deltas.</para> + + <para>You can control the list of files that + <application>CTM</application> would operate on by specifying + filtering regular expressions using the <option>-e</option> + and <option>-x</option> options.</para> + + <para>For example, to extract an up-to-date copy of + <filename>lib/libc/Makefile</filename> from your collection of + saved <application>CTM</application> deltas, run the commands:</para> + + <screen>&prompt.root; <userinput>cd /where/ever/you/want/to/extract/it/</userinput> +&prompt.root; <userinput>ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*</userinput></screen> + + <para>For every file specified in a + <application>CTM</application> delta, the <option>-e</option> + and <option>-x</option> options are applied in the order given + on the command line. The file is processed by + <application>CTM</application> only if it is marked as + eligible after all the <option>-e</option> and + <option>-x</option> options are applied to it.</para> + </sect3> + </sect2> + + <sect2> + <title>Future Plans for <application>CTM</application></title> + + <para>Tons of them:</para> + + <itemizedlist> + <listitem> + <para>Use some kind of authentication into the <application>CTM</application> system, so + as to allow detection of spoofed <application>CTM</application> updates.</para> + </listitem> + + <listitem> + <para>Clean up the options to <application>CTM</application>, + they became confusing and counter intuitive.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Miscellaneous Stuff</title> + + <para>There is a sequence of deltas for the + <literal>ports</literal> collection too, but interest has not + been all that high yet.</para> + </sect2> + + <sect2 id="mirrors-ctm"> + <title>CTM Mirrors</title> + + <para><link linkend="ctm">CTM</link>/&os; is available via anonymous + FTP from the following mirror sites. If you choose to obtain <application>CTM</application> via + anonymous FTP, please try to use a site near you.</para> + + <para>In case of problems, please contact the &a.ctm-users.name; + mailing list.</para> + + <variablelist> + <varlistentry> + <term>California, Bay Area, official source</term> + + <listitem> + <itemizedlist> + <listitem> + <para><ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>South Africa, backup server for old deltas</term> + + <listitem> + <itemizedlist> + <listitem> + <para><ulink url="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/"></ulink></para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>Taiwan/R.O.C.</term> + + <listitem> + <itemizedlist> + <listitem> + <para><ulink url="ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para> + </listitem> + + <listitem> + <para><ulink url="ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para> + </listitem> + + <listitem> + <para><ulink url="ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + + <para>If you did not find a mirror near to you or the mirror is + incomplete, try to use a search engine such as + <ulink url="http://www.alltheweb.com/">alltheweb</ulink>.</para> + </sect2></sect1> + + <sect1 id="cvsup"> + <title>Using CVSup</title> + + <sect2 id="cvsup-intro"> + <title>Introduction</title> + + <para><application>CVSup</application> is a software package for + distributing and updating source trees from a master CVS + repository on a remote server host. The &os; sources are + maintained in a CVS repository on a central development machine + in California. With <application>CVSup</application>, &os; + users can easily keep their own source trees up to date.</para> + + <para><application>CVSup</application> uses the so-called + <emphasis>pull</emphasis> model of updating. Under the pull + model, each client asks the server for updates, if and when they + are wanted. The server waits passively for update requests from + its clients. Thus all updates are instigated by the client. + The server never sends unsolicited updates. Users must either + run the <application>CVSup</application> client manually to get + an update, or they must set up a <command>cron</command> job to + run it automatically on a regular basis.</para> + + <para>The term <application>CVSup</application>, capitalized just + so, refers to the entire software package. Its main components + are the client <command>cvsup</command> which runs on each + user's machine, and the server <command>cvsupd</command> which + runs at each of the &os; mirror sites.</para> + + <para>As you read the &os; documentation and mailing lists, you + may see references to <application>sup</application>. + <application>Sup</application> was the predecessor of + <application>CVSup</application>, and it served a similar + purpose. <application>CVSup</application> is used much in the + same way as sup and, in fact, uses configuration files which are + backward-compatible with <command>sup</command>'s. + <application>Sup</application> is no longer used in the &os; + project, because <application>CVSup</application> is both faster + and more flexible.</para> + + <note> + <para>The <application>csup</application> utility is a rewrite of the + <application>CVSup</application> software in C. Its biggest + advantage is, that it is faster and does not depend on the + Modula-3 language, thus you do not need to install it as a + requirement. Moreover + you can use it out-of-the-box, since it is included in the base + system. + If you decided to use + <application>csup</application>, just skip the steps on the + installation of <application>CVSup</application> and + substitute the references of <application>CVSup</application> with + <application>csup</application> while following the remainder of + this article.</para> + </note> + </sect2> + + <sect2 id="cvsup-install"> + <title>Installation</title> + + <para>The easiest way to install <application>CVSup</application> + is to use the precompiled <filename role="package">net/cvsup</filename> package + from the &os; <link linkend="ports">packages collection</link>. + If you prefer to build <application>CVSup</application> from + source, you can use the <filename role="package">net/cvsup</filename> + port instead. But be forewarned: the + <filename role="package">net/cvsup</filename> port depends on the Modula-3 + system, which takes a substantial amount of time and + disk space to download and build.</para> + + <note> + <para>If you are going to be using + <application>CVSup</application> on a machine which will not have + <application>&xorg;</application> installed, such as a server, be + sure to use the port which does not include the + <application>CVSup</application> <acronym>GUI</acronym>, + <filename role="package">net/cvsup-without-gui</filename>.</para> + </note> + </sect2> + + <sect2 id="cvsup-config"> + <title>CVSup Configuration</title> + + <para><application>CVSup</application>'s operation is controlled + by a configuration file called the <filename>supfile</filename>. + There are some sample <filename>supfiles</filename> in the + directory <ulink type="html" + url="file://localhost/usr/share/examples/cvsup/"><filename>/usr/share/examples/cvsup/</filename></ulink>.</para> + + <para>The information in a <filename>supfile</filename> answers + the following questions for <application>CVSup</application>:</para> + + <itemizedlist> + <listitem> + <para><link linkend="cvsup-config-files">Which files do you + want to receive?</link></para> + </listitem> + + <listitem> + <para><link linkend="cvsup-config-vers">Which versions of them + do you want?</link></para> + </listitem> + + <listitem> + <para><link linkend="cvsup-config-where">Where do you want to + get them from?</link></para> + </listitem> + + <listitem> + <para><link linkend="cvsup-config-dest">Where do you want to + put them on your own machine?</link></para> + </listitem> + + <listitem> + <para><link linkend="cvsup-config-status">Where do you want to + put your status files?</link></para> + </listitem> + </itemizedlist> + + <para>In the following sections, we will construct a typical + <filename>supfile</filename> by answering each of these + questions in turn. First, we describe the overall structure of + a <filename>supfile</filename>.</para> + + <para>A <filename>supfile</filename> is a text file. Comments + begin with <literal>#</literal> and extend to the end of the + line. Lines that are blank and lines that contain only + comments are ignored.</para> + + <para>Each remaining line describes a set of files that the user + wishes to receive. The line begins with the name of a + <quote>collection</quote>, a logical grouping of files defined by + the server. The name of the collection tells the server which + files you want. After the collection name come zero or more + fields, separated by white space. These fields answer the + questions listed above. There are two types of fields: flag + fields and value fields. A flag field consists of a keyword + standing alone, e.g., <literal>delete</literal> or + <literal>compress</literal>. A value field also begins with a + keyword, but the keyword is followed without intervening white + space by <literal>=</literal> and a second word. For example, + <literal>release=cvs</literal> is a value field.</para> + + <para>A <filename>supfile</filename> typically specifies more than + one collection to receive. One way to structure a + <filename>supfile</filename> is to specify all of the relevant + fields explicitly for each collection. However, that tends to + make the <filename>supfile</filename> lines quite long, and it + is inconvenient because most fields are the same for all of the + collections in a <filename>supfile</filename>. + <application>CVSup</application> provides a defaulting mechanism + to avoid these problems. Lines beginning with the special + pseudo-collection name <literal>*default</literal> can be used + to set flags and values which will be used as defaults for the + subsequent collections in the <filename>supfile</filename>. A + default value can be overridden for an individual collection, by + specifying a different value with the collection itself. + Defaults can also be changed or augmented in mid-supfile by + additional <literal>*default</literal> lines.</para> + + <para>With this background, we will now proceed to construct a + <filename>supfile</filename> for receiving and updating the main + source tree of <link + linkend="current">&os;-CURRENT</link>.</para> + + <itemizedlist> + <listitem> + <para><anchor id="cvsup-config-files">Which files do you want + to receive?</para> + + <para>The files available via <application>CVSup</application> + are organized into named groups called + <quote>collections</quote>. The collections that are + available are described in the <link + linkend="cvsup-collec">following section</link>. In this + example, we + wish to receive the entire main source tree for the &os; + system. There is a single large collection + <literal>src-all</literal> which will give us all of that. + As a first step toward constructing our + <filename>supfile</filename>, we + simply list the collections, one per line (in this case, + only one line):</para> + + <programlisting>src-all</programlisting> + </listitem> + + <listitem> + <para><anchor id="cvsup-config-vers">Which version(s) of them + do you want?</para> + + <para>With <application>CVSup</application>, you can receive + virtually any version of the sources that ever existed. + That is possible because the + <application>cvsupd</application> server works directly from + the CVS repository, which contains all of the versions. You + specify which one of them you want using the + <literal>tag=</literal> and <option>date=</option> value + fields.</para> + + <warning> + <para>Be very careful to specify any <literal>tag=</literal> + fields correctly. Some tags are valid only for certain + collections of files. If you specify an incorrect or + misspelled tag, <application>CVSup</application> + will delete files which you probably + do not want deleted. In particular, use <emphasis>only + </emphasis> <literal>tag=.</literal> for the + <literal>ports-*</literal> collections.</para> + </warning> + + <para>The <literal>tag=</literal> field names a symbolic tag + in the repository. There are two kinds of tags, revision + tags and branch tags. A revision tag refers to a specific + revision. Its meaning stays the same from day to day. A + branch tag, on the other hand, refers to the latest revision + on a given line of development, at any given time. Because + a branch tag does not refer to a specific revision, it may + mean something different tomorrow than it means + today.</para> + + <para><xref linkend="cvs-tags"> contains branch tags that + users might be interested in. When specifying a tag in + <application>CVSup</application>'s configuration file, it + must be preceded with <literal>tag=</literal> + (<literal>RELENG_8</literal> will become + <literal>tag=RELENG_8</literal>). + Keep in mind that only the <literal>tag=.</literal> is + relevant for the Ports Collection.</para> + + <warning> + <para>Be very careful to type the tag name exactly as shown. + <application>CVSup</application> cannot distinguish + between valid and invalid tags. If you misspell the tag, + <application>CVSup</application> will behave as though you + had specified a valid tag which happens to refer to no + files at all. It will delete your existing sources in + that case.</para> + </warning> + + <para>When you specify a branch tag, you normally receive the + latest versions of the files on that line of development. + If you wish to receive some past version, you can do so by + specifying a date with the <option>date=</option> value + field. The &man.cvsup.1; manual page explains how to do + that.</para> + + <para>For our example, we wish to receive &os;-CURRENT. We + add this line at the beginning of our + <filename>supfile</filename>:</para> + + <programlisting>*default tag=.</programlisting> + + <para>There is an important special case that comes into play + if you specify neither a <literal>tag=</literal> field nor a + <literal>date=</literal> field. In that case, you receive + the actual RCS files directly from the server's CVS + repository, rather than receiving a particular version. + Developers generally prefer this mode of operation. By + maintaining a copy of the repository itself on their + systems, they gain the ability to browse the revision + histories and examine past versions of files. This gain is + achieved at a large cost in terms of disk space, + however.</para> + </listitem> + + <listitem> + <para><anchor id="cvsup-config-where">Where do you want to get + them from?</para> + + <para>We use the <literal>host=</literal> field to tell + <command>cvsup</command> where to obtain its updates. Any + of the <link linkend="cvsup-mirrors">CVSup mirror + sites</link> will do, though you should try to select one + that is close to you in cyberspace. In this example we will + use a fictional &os; distribution site, + <hostid role="fqdn">cvsup99.FreeBSD.org</hostid>:</para> + + <programlisting>*default host=cvsup99.FreeBSD.org</programlisting> + + <para>You will need to change the host to one that actually + exists before running <application>CVSup</application>. + On any particular run of + <command>cvsup</command>, you can override the host setting + on the command line, with <option>-h + <replaceable>hostname</replaceable></option>.</para> + </listitem> + + <listitem> + <para><anchor id="cvsup-config-dest">Where do you want to put + them on your own machine?</para> + + <para>The <literal>prefix=</literal> field tells + <command>cvsup</command> where to put the files it receives. + In this example, we will put the source files directly into + our main source tree, <filename>/usr/src</filename>. The + <filename>src</filename> directory is already implicit in + the collections we have chosen to receive, so this is the + correct specification:</para> + + <programlisting>*default prefix=/usr</programlisting> + </listitem> + + <listitem> + <para><anchor id="cvsup-config-status">Where should + <command>cvsup</command> maintain its status files?</para> + + <para>The <application>CVSup</application> client maintains + certain status files in what + is called the <quote>base</quote> directory. These files + help <application>CVSup</application> to work more + efficiently, by keeping track of which updates you have + already received. We will use the standard base directory, + <filename>/var/db</filename>:</para> + + <programlisting>*default base=/var/db</programlisting> + + <para>If your base directory does not already exist, now would + be a good time to create it. The <command>cvsup</command> + client will refuse to run if the base directory does not + exist.</para> + </listitem> + + <listitem> + <para>Miscellaneous <filename>supfile</filename> + settings:</para> + + <para>There is one more line of boiler plate that normally + needs to be present in the + <filename>supfile</filename>:</para> + + <programlisting>*default release=cvs delete use-rel-suffix compress</programlisting> + + <para><literal>release=cvs</literal> indicates that the server + should get its information out of the main &os; CVS + repository. This is virtually always the case, but there + are other possibilities which are beyond the scope of this + discussion.</para> + + <para><literal>delete</literal> gives + <application>CVSup</application> permission to delete files. + You should always specify this, so that + <application>CVSup</application> can keep your source tree + fully up-to-date. <application>CVSup</application> is + careful to delete only those files for which it is + responsible. Any extra files you happen to have will be + left strictly alone.</para> + + <para><literal>use-rel-suffix</literal> is ... arcane. If you + really want to know about it, see the &man.cvsup.1; manual + page. Otherwise, just specify it and do not worry about + it.</para> + + <para><literal>compress</literal> enables the use of + gzip-style compression on the communication channel. If + your network link is T1 speed or faster, you probably should + not use compression. Otherwise, it helps + substantially.</para> + </listitem> + + <listitem> + <para>Putting it all together:</para> + + <para>Here is the entire <filename>supfile</filename> for our + example:</para> + + <programlisting>*default tag=. +*default host=cvsup99.FreeBSD.org +*default prefix=/usr +*default base=/var/db +*default release=cvs delete use-rel-suffix compress + +src-all</programlisting> + </listitem> + </itemizedlist> + <sect3 id="cvsup-refuse-file"> + <title>The <filename>refuse</filename> File</title> + + <para>As mentioned above, <application>CVSup</application> uses + a <emphasis>pull method</emphasis>. Basically, this means that + you connect to the <application>CVSup</application> server, and + it says, <quote>Here is what you can download from + me...</quote>, and your client responds <quote>OK, I will take + this, this, this, and this.</quote> In the default + configuration, the <application>CVSup</application> client will + take every file associated with the collection and tag you + chose in the configuration file. However, this is not always + what you want, especially if you are synching the <filename>doc</filename>, <filename>ports</filename>, or + <filename>www</filename> trees — most people cannot read four or five + languages, and therefore they do not need to download the + language-specific files. If you are + <application>CVSup</application>ing the Ports Collection, you + can get around this by specifying each collection individually + (e.g., <emphasis>ports-astrology</emphasis>, + <emphasis>ports-biology</emphasis>, etc instead of simply + saying <emphasis>ports-all</emphasis>). However, since the <filename>doc</filename> + and <filename>www</filename> trees do not have language-specific collections, you + must use one of <application>CVSup</application>'s many nifty + features: the <filename>refuse</filename> file.</para> + + <para>The <filename>refuse</filename> file essentially tells + <application>CVSup</application> that it should not take every + single file from a collection; in other words, it tells the + client to <emphasis>refuse</emphasis> certain files from the + server. The <filename>refuse</filename> file can be found (or, if you do not yet + have one, should be placed) in + <filename><replaceable>base</replaceable>/sup/</filename>. + <replaceable>base</replaceable> is defined in your <filename>supfile</filename>; + our defined <replaceable>base</replaceable> is + <filename>/var/db</filename>, + which means that by default the <filename>refuse</filename> file is + <filename>/var/db/sup/refuse</filename>.</para> + + <para>The <filename>refuse</filename> file has a very simple format; it simply + contains the names of files or directories that you do not wish + to download. For example, if you cannot speak any languages other + than English and some German, and you do not feel the need to read + the German translation of documentation, you can put the following in your + <filename>refuse</filename> file:</para> + + <screen>doc/bn_* +doc/da_* +doc/de_* +doc/el_* +doc/es_* +doc/fr_* +doc/hu_* +doc/it_* +doc/ja_* +doc/mn_* +doc/nl_* +doc/no_* +doc/pl_* +doc/pt_* +doc/ru_* +doc/sr_* +doc/tr_* +doc/zh_*</screen> + + <para>and so forth for the other languages (you can find the + full list by browsing the <ulink + url="http://www.FreeBSD.org/cgi/cvsweb.cgi/">&os; + CVS repository</ulink>).</para> + + <para>With this very useful feature, those users who are on + slow links or pay by the minute for their Internet connection + will be able to save valuable time as they will no longer need + to download files that they will never use. For more + information on <filename>refuse</filename> files and other neat + features of <application>CVSup</application>, please view its + manual page.</para> + </sect3> + </sect2> + + <sect2> + <title>Running <application>CVSup</application></title> + + <para>You are now ready to try an update. The command line for + doing this is quite simple:</para> + + <screen>&prompt.root; <userinput>cvsup <replaceable>supfile</replaceable></userinput></screen> + + <para>where <filename><replaceable>supfile</replaceable></filename> + is of course the name of the <filename>supfile</filename> you have just created. + Assuming you are running under X11, <command>cvsup</command> + will display a GUI window with some buttons to do the usual + things. Press the <guibutton>go</guibutton> button, and watch it + run.</para> + + <para>Since you are updating your actual + <filename>/usr/src</filename> tree in this example, you will + need to run the program as <username>root</username> so that + <command>cvsup</command> has the permissions it needs to update + your files. Having just created your configuration file, and + having never used this program before, that might + understandably make you nervous. There is an easy way to do a + trial run without touching your precious files. Just create an + empty directory somewhere convenient, and name it as an extra + argument on the command line:</para> + + <screen>&prompt.root; <userinput>mkdir /var/tmp/dest</userinput> +&prompt.root; <userinput>cvsup supfile /var/tmp/dest</userinput></screen> + + <para>The directory you specify will be used as the destination + directory for all file updates. + <application>CVSup</application> will examine your usual files + in <filename>/usr/src</filename>, but it will not modify or + delete any of them. Any file updates will instead land in + <filename>/var/tmp/dest/usr/src</filename>. + <application>CVSup</application> will also leave its base + directory status files untouched when run this way. The new + versions of those files will be written into the specified + directory. As long as you have read access to + <filename>/usr/src</filename>, you do not even need to be + <username>root</username> to perform this kind of trial run.</para> + + <para>If you are not running X11 or if you just do not like GUIs, + you should add a couple of options to the command line when you + run <command>cvsup</command>:</para> + + <screen>&prompt.root; <userinput>cvsup -g -L 2 <replaceable>supfile</replaceable></userinput></screen> + + <para>The <option>-g</option> tells + <application>CVSup</application> not to use its GUI. This is + automatic if you are not running X11, but otherwise you have to + specify it.</para> + + <para>The <option>-L 2</option> tells + <application>CVSup</application> to print out the + details of all the file updates it is doing. There are three + levels of verbosity, from <option>-L 0</option> to + <option>-L 2</option>. The default is 0, which means total + silence except for error messages.</para> + + <para>There are plenty of other options available. For a brief + list of them, type <command>cvsup -H</command>. For more + detailed descriptions, see the manual page.</para> + + <para>Once you are satisfied with the way updates are working, you + can arrange for regular runs of <application>CVSup</application> + using &man.cron.8;. + Obviously, you should not let <application>CVSup</application> + use its GUI when running it from &man.cron.8;.</para> + </sect2> + + <sect2 id="cvsup-collec"> + <title><application>CVSup</application> File Collections</title> + + <para>The file collections available via + <application>CVSup</application> are organized hierarchically. + There are a few large collections, and they are divided into + smaller sub-collections. Receiving a large collection is + equivalent to receiving each of its sub-collections. The + hierarchical relationships among collections are reflected by + the use of indentation in the list below.</para> + + <para>The most commonly used collections are + <literal>src-all</literal>, and + <literal>ports-all</literal>. The other collections are used + only by small groups of people for specialized purposes, and + some mirror sites may not carry all of them.</para> + + <variablelist> + <varlistentry> + <term><literal>cvs-all release=cvs</literal></term> + + <listitem> + <para>The main &os; CVS repository, including the + cryptography code.</para> + + <variablelist> + <varlistentry> + <term><literal>distrib release=cvs</literal></term> + + <listitem> + <para>Files related to the distribution and mirroring + of &os;.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>doc-all release=cvs</literal></term> + <listitem> + <para>Sources for the &os; Handbook and other + documentation. This does not include files for + the &os; web site.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-all release=cvs</literal></term> + + <listitem> + <para>The &os; Ports Collection.</para> + + <important id="cvsup-collec-pbase-warn"> + <para>If you do not want to update the whole of + <literal>ports-all</literal> (the whole ports tree), + but use one of the subcollections listed below, + make sure that you <emphasis>always</emphasis> update + the <literal>ports-base</literal> subcollection! + Whenever something changes in the ports build + infrastructure represented by + <literal>ports-base</literal>, it is virtually certain + that those changes will be used by <quote>real</quote> + ports real soon. Thus, if you only update the + <quote>real</quote> ports and they use some of the new + features, there is a very high chance that their build + will fail with some mysterious error message. The + <emphasis>very first</emphasis> thing to do in this + case is to make sure that your + <literal>ports-base</literal> subcollection is up to + date.</para> + </important> + + <important id="cvsup-collec-index-warn"> + <para>If you are going to be building your own local + copy of <filename>ports/INDEX</filename>, you + <emphasis>must</emphasis> accept + <literal>ports-all</literal> (the whole ports tree). + Building <filename>ports/INDEX</filename> with + a partial tree is not supported. See the + <ulink url="&url.books.faq;/applications.html#MAKE-INDEX"> + FAQ</ulink>.</para> + </important> + + <variablelist> + <varlistentry> + <term><literal>ports-accessibility + release=cvs</literal></term> + + <listitem> + <para>Software to help disabled users.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-arabic + release=cvs</literal></term> + + <listitem> + <para>Arabic language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-archivers + release=cvs</literal></term> + + <listitem> + <para>Archiving tools.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-astro + release=cvs</literal></term> + + <listitem> + <para>Astronomical ports.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-audio + release=cvs</literal></term> + + <listitem> + <para>Sound support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-base + release=cvs</literal></term> + + <listitem> + <para>The Ports Collection build infrastructure - + various files located in the + <filename>Mk/</filename> and + <filename>Tools/</filename> subdirectories of + <filename>/usr/ports</filename>.</para> + + <note> + <para>Please see the <link + linkend="cvsup-collec-pbase-warn">important + warning above</link>: you should + <emphasis>always</emphasis> update this + subcollection, whenever you update any part of + the &os; Ports Collection!</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-benchmarks + release=cvs</literal></term> + + <listitem> + <para>Benchmarks.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-biology + release=cvs</literal></term> + + <listitem> + <para>Biology.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-cad + release=cvs</literal></term> + + <listitem> + <para>Computer aided design tools.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-chinese + release=cvs</literal></term> + + <listitem> + <para>Chinese language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-comms + release=cvs</literal></term> + + <listitem> + <para>Communication software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-converters + release=cvs</literal></term> + + <listitem> + <para>character code converters.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-databases + release=cvs</literal></term> + + <listitem> + <para>Databases.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-deskutils + release=cvs</literal></term> + + <listitem> + <para>Things that used to be on the desktop + before computers were invented.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-devel + release=cvs</literal></term> + + <listitem> + <para>Development utilities.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-dns + release=cvs</literal></term> + + <listitem> + <para>DNS related software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-editors + release=cvs</literal></term> + + <listitem> + <para>Editors.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-emulators + release=cvs</literal></term> + + <listitem> + <para>Emulators for other operating + systems.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-finance + release=cvs</literal></term> + + <listitem> + <para>Monetary, financial and related applications.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-ftp + release=cvs</literal></term> + + <listitem> + <para>FTP client and server utilities.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-games + release=cvs</literal></term> + + <listitem> + <para>Games.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-german + release=cvs</literal></term> + + <listitem> + <para>German language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-graphics + release=cvs</literal></term> + + <listitem> + <para>Graphics utilities.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-hebrew + release=cvs</literal></term> + + <listitem> + <para>Hebrew language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-hungarian + release=cvs</literal></term> + + <listitem> + <para>Hungarian language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-irc + release=cvs</literal></term> + + <listitem> + <para>Internet Relay Chat utilities.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-japanese + release=cvs</literal></term> + + <listitem> + <para>Japanese language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-java + release=cvs</literal></term> + + <listitem> + <para>&java; utilities.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-korean + release=cvs</literal></term> + + <listitem> + <para>Korean language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-lang + release=cvs</literal></term> + + <listitem> + <para>Programming languages.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-mail + release=cvs</literal></term> + + <listitem> + <para>Mail software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-math + release=cvs</literal></term> + + <listitem> + <para>Numerical computation software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-misc + release=cvs</literal></term> + + <listitem> + <para>Miscellaneous utilities.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-multimedia + release=cvs</literal></term> + + <listitem> + <para>Multimedia software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-net + release=cvs</literal></term> + + <listitem> + <para>Networking software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-net-im + release=cvs</literal></term> + + <listitem> + <para>Instant messaging software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-net-mgmt + release=cvs</literal></term> + + <listitem> + <para>Network management software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-net-p2p + release=cvs</literal></term> + + <listitem> + <para>Peer to peer networking.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-news + release=cvs</literal></term> + + <listitem> + <para>USENET news software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-palm + release=cvs</literal></term> + + <listitem> + <para>Software support for <trademark class="trade">Palm</trademark> + series.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-polish + release=cvs</literal></term> + + <listitem> + <para>Polish language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-ports-mgmt + release=cvs</literal></term> + + <listitem> + <para>Utilities to manage ports and packages.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-portuguese + release=cvs</literal></term> + + <listitem> + <para>Portuguese language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-print + release=cvs</literal></term> + + <listitem> + <para>Printing software.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-russian + release=cvs</literal></term> + + <listitem> + <para>Russian language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-science + release=cvs</literal></term> + + <listitem> + <para>Science.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-security + release=cvs</literal></term> + + <listitem> + <para>Security utilities.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-shells + release=cvs</literal></term> + + <listitem> + <para>Command line shells.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-sysutils + release=cvs</literal></term> + + <listitem> + <para>System utilities.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-textproc + release=cvs</literal></term> + + <listitem> + <para>text processing utilities (does not + include desktop publishing).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-ukrainian + release=cvs</literal></term> + + <listitem> + <para>Ukrainian language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-vietnamese + release=cvs</literal></term> + + <listitem> + <para>Vietnamese language support.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-www + release=cvs</literal></term> + + <listitem> + <para>Software related to the World Wide + Web.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-x11 + release=cvs</literal></term> + + <listitem> + <para>Ports to support the X window + system.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-x11-clocks + release=cvs</literal></term> + + <listitem> + <para>X11 clocks.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-x11-drivers + release=cvs</literal></term> + + <listitem> + <para>X11 drivers.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-x11-fm + release=cvs</literal></term> + + <listitem> + <para>X11 file managers.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-x11-fonts + release=cvs</literal></term> + + <listitem> + <para>X11 fonts and font utilities.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-x11-toolkits + release=cvs</literal></term> + + <listitem> + <para>X11 toolkits.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-x11-servers + release=cvs</literal></term> + + <listitem> + <para>X11 servers.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-x11-themes + release=cvs</literal></term> + + <listitem> + <para>X11 themes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ports-x11-wm + release=cvs</literal></term> + + <listitem> + <para>X11 window managers.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>projects-all release=cvs</literal></term> + <listitem> + <para>Sources for the &os; projects repository.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-all release=cvs</literal></term> + + <listitem> + <para>The main &os; sources, including the + cryptography code.</para> + + <variablelist> + <varlistentry> + <term><literal>src-base + release=cvs</literal></term> + + <listitem> + <para>Miscellaneous files at the top of + <filename>/usr/src</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-bin + release=cvs</literal></term> + + <listitem> + <para>User utilities that may be needed in + single-user mode + (<filename>/usr/src/bin</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-cddl + release=cvs</literal></term> + + <listitem> + <para>Utilities and libraries covered by the + CDDL license + (<filename>/usr/src/cddl</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-contrib + release=cvs</literal></term> + + <listitem> + <para>Utilities and libraries from outside the + &os; project, used relatively unmodified + (<filename>/usr/src/contrib</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-crypto release=cvs</literal></term> + + <listitem> + <para>Cryptography utilities and libraries from + outside the &os; project, used relatively + unmodified + (<filename>/usr/src/crypto</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-eBones release=cvs</literal></term> + + <listitem> + <para>Kerberos and DES + (<filename>/usr/src/eBones</filename>). Not + used in current releases of &os;.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-etc + release=cvs</literal></term> + + <listitem> + <para>System configuration files + (<filename>/usr/src/etc</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-games + release=cvs</literal></term> + + <listitem> + <para>Games + (<filename>/usr/src/games</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-gnu + release=cvs</literal></term> + + <listitem> + <para>Utilities covered by the GNU Public + License (<filename>/usr/src/gnu</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-include + release=cvs</literal></term> + + <listitem> + <para>Header files + (<filename>/usr/src/include</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-kerberos5 + release=cvs</literal></term> + + <listitem> + <para>Kerberos5 security package + (<filename>/usr/src/kerberos5</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-kerberosIV + release=cvs</literal></term> + + <listitem> + <para>KerberosIV security package + (<filename>/usr/src/kerberosIV</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-lib + release=cvs</literal></term> + + <listitem> + <para>Libraries + (<filename>/usr/src/lib</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-libexec + release=cvs</literal></term> + + <listitem> + <para>System programs normally executed by other + programs + (<filename>/usr/src/libexec</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-release + release=cvs</literal></term> + + <listitem> + <para>Files required to produce a &os; + release + (<filename>/usr/src/release</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-rescue + release=cvs</literal></term> + + <listitem> + <para>Statically linked programs for emergency + recovery; see &man.rescue.8; + (<filename>/usr/src/rescue</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-sbin release=cvs</literal></term> + + <listitem> + <para>System utilities for single-user mode + (<filename>/usr/src/sbin</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-secure + release=cvs</literal></term> + + <listitem> + <para>Cryptographic libraries and commands + (<filename>/usr/src/secure</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-share + release=cvs</literal></term> + + <listitem> + <para>Files that can be shared across multiple + systems + (<filename>/usr/src/share</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-sys + release=cvs</literal></term> + + <listitem> + <para>The kernel + (<filename>/usr/src/sys</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-sys-crypto + release=cvs</literal></term> + + <listitem> + <para>Kernel cryptography code + (<filename>/usr/src/sys/crypto</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-tools + release=cvs</literal></term> + + <listitem> + <para>Various tools for the maintenance of + &os; + (<filename>/usr/src/tools</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-usrbin + release=cvs</literal></term> + + <listitem> + <para>User utilities + (<filename>/usr/src/usr.bin</filename>).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>src-usrsbin + release=cvs</literal></term> + + <listitem> + <para>System utilities + (<filename>/usr/src/usr.sbin</filename>).</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>www release=cvs</literal></term> + + <listitem> + <para>The sources for the &os; WWW site.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>distrib release=self</literal></term> + + <listitem> + <para>The <application>CVSup</application> server's own + configuration files. Used by <application>CVSup</application> + mirror sites.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>gnats release=current</literal></term> + + <listitem> + <para>The GNATS bug-tracking database.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>mail-archive release=current</literal></term> + + <listitem> + <para>&os; mailing list archive.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>www release=current</literal></term> + + <listitem> + <para>The pre-processed &os; WWW site files (not the + source files). Used by WWW mirror sites.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2> + <title>For More Information</title> + + <para>For the <application>CVSup</application> FAQ and other + information about <application>CVSup</application>, see + <ulink url="http://www.cvsup.org">The + CVSup Home Page</ulink>.</para> + + <para>Most &os;-related discussion of + <application>CVSup</application> takes place on the + &a.hackers;. New versions of the software are announced there, + as well as on the &a.announce;.</para> + + <para>For questions or bug reports about + <application>CVSup</application> take a look at the + <ulink url="http://www.cvsup.org/faq.html#bugreports"> + CVSup FAQ</ulink>.</para> + </sect2> + + <sect2 id="cvsup-mirrors"> + <title>CVSup Sites</title> + + <para><link linkend="cvsup">CVSup</link> servers for &os; are running + at the following sites:</para> + + &chap.mirrors.cvsup.inc; + </sect2> + </sect1> + + <sect1 id="cvs-tags"> + <title>CVS Tags</title> + + <para>When obtaining or updating sources using + <application>cvs</application> or + <application>CVSup</application>, a revision tag must be specified. + A revision tag refers to either a particular line of &os; + development, or a specific point in time. The first type are called + <quote>branch tags</quote>, and the second type are called + <quote>release tags</quote>.</para> + + <sect2> + <title>Branch Tags</title> + + <para>All of these, with the exception of <literal>HEAD</literal> (which + is always a valid tag), only apply to the <filename>src/</filename> + tree. The <filename>ports/</filename>, <filename>doc/</filename>, and + <filename>www/</filename> trees are not branched.</para> + + <variablelist> + <varlistentry> + <term>HEAD</term> + + <listitem> + <para>Symbolic name for the main line, or &os;-CURRENT. + Also the default when no revision is specified.</para> + + <para>In <application>CVSup</application>, this tag is represented + by a <literal>.</literal> (not punctuation, but a literal + <literal>.</literal> character).</para> + + <note> + <para>In CVS, this is the default when no revision tag is + specified. It is usually <emphasis>not</emphasis> + a good idea to checkout or update to CURRENT sources + on a STABLE machine, unless that is your intent.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_9</term> + + <listitem> + <para>The line of development for &os;-9.X, also known + as &os; 9-STABLE</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_9_0</term> + + <listitem> + <para>The release branch for &os;-9.0, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_8</term> + + <listitem> + <para>The line of development for &os;-8.X, also known + as &os; 8-STABLE</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_8_3</term> + + <listitem> + <para>The release branch for &os;-8.3, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_8_2</term> + + <listitem> + <para>The release branch for &os;-8.2, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_8_1</term> + + <listitem> + <para>The release branch for &os;-8.1, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_8_0</term> + + <listitem> + <para>The release branch for &os;-8.0, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7</term> + + <listitem> + <para>The line of development for &os;-7.X, also known + as &os; 7-STABLE</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7_4</term> + + <listitem> + <para>The release branch for &os;-7.4, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7_3</term> + + <listitem> + <para>The release branch for &os;-7.3, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7_2</term> + + <listitem> + <para>The release branch for &os;-7.2, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7_1</term> + + <listitem> + <para>The release branch for &os;-7.1, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7_0</term> + + <listitem> + <para>The release branch for &os;-7.0, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6</term> + + <listitem> + <para>The line of development for &os;-6.X, also known + as &os; 6-STABLE</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6_4</term> + + <listitem> + <para>The release branch for &os;-6.4, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6_3</term> + + <listitem> + <para>The release branch for &os;-6.3, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6_2</term> + + <listitem> + <para>The release branch for &os;-6.2, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6_1</term> + + <listitem> + <para>The release branch for &os;-6.1, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6_0</term> + + <listitem> + <para>The release branch for &os;-6.0, used only for + security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5</term> + + <listitem> + <para>The line of development for &os;-5.X, also known + as &os; 5-STABLE.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_5</term> + + <listitem> + <para>The release branch for &os;-5.5, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_4</term> + + <listitem> + <para>The release branch for &os;-5.4, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_3</term> + + <listitem> + <para>The release branch for &os;-5.3, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_2</term> + + <listitem> + <para>The release branch for &os;-5.2 and &os;-5.2.1, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_1</term> + + <listitem> + <para>The release branch for &os;-5.1, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_0</term> + + <listitem> + <para>The release branch for &os;-5.0, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4</term> + + <listitem> + <para>The line of development for &os;-4.X, also known + as &os; 4-STABLE.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_11</term> + + <listitem> + <para>The release branch for &os;-4.11, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_10</term> + + <listitem> + <para>The release branch for &os;-4.10, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_9</term> + + <listitem> + <para>The release branch for &os;-4.9, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_8</term> + + <listitem> + <para>The release branch for &os;-4.8, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_7</term> + + <listitem> + <para>The release branch for &os;-4.7, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_6</term> + + <listitem> + <para>The release branch for &os;-4.6 and &os;-4.6.2, + used only for security advisories and other + critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_5</term> + + <listitem> + <para>The release branch for &os;-4.5, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_4</term> + + <listitem> + <para>The release branch for &os;-4.4, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_3</term> + + <listitem> + <para>The release branch for &os;-4.3, used only + for security advisories and other critical fixes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_3</term> + + <listitem> + <para>The line of development for &os;-3.X, also known + as 3.X-STABLE.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_2_2</term> + + <listitem> + <para>The line of development for &os;-2.2.X, also known + as 2.2-STABLE. This branch is mostly obsolete.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2> + <title>Release Tags</title> + + <para>These tags refer to a specific point in time when a particular + version of &os; was released. The release engineering process is + documented in more detail by the + <ulink url="&url.base;/releng/">Release Engineering + Information</ulink> and + <ulink url="&url.articles.releng;/release-proc.html">Release + Process</ulink> documents. + The <filename class="directory">src</filename> tree uses tag names that + start with <literal>RELENG_</literal> tags. + The <filename class="directory">ports</filename> and + <filename class="directory">doc</filename> trees use tags whose names + begin with <literal>RELEASE</literal> tags. + Finally, the <filename class="directory">www</filename> tree is not + tagged with any special name for releases.</para> + + <variablelist> + <varlistentry> + <term>RELENG_9_0_0_RELEASE</term> + + <listitem> + <para>&os; 9.0</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_8_3_0_RELEASE</term> + + <listitem> + <para>&os; 8.3</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_8_2_0_RELEASE</term> + + <listitem> + <para>&os; 8.2</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_8_1_0_RELEASE</term> + + <listitem> + <para>&os; 8.1</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_8_0_0_RELEASE</term> + + <listitem> + <para>&os; 8.0</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7_4_0_RELEASE</term> + + <listitem> + <para>&os; 7.4</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7_3_0_RELEASE</term> + + <listitem> + <para>&os; 7.3</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7_2_0_RELEASE</term> + + <listitem> + <para>&os; 7.2</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7_1_0_RELEASE</term> + + <listitem> + <para>&os; 7.1</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_7_0_0_RELEASE</term> + + <listitem> + <para>&os; 7.0</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6_4_0_RELEASE</term> + + <listitem> + <para>&os; 6.4</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6_3_0_RELEASE</term> + + <listitem> + <para>&os; 6.3</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6_2_0_RELEASE</term> + + <listitem> + <para>&os; 6.2</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6_1_0_RELEASE</term> + + <listitem> + <para>&os; 6.1</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_6_0_0_RELEASE</term> + + <listitem> + <para>&os; 6.0</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_5_0_RELEASE</term> + + <listitem> + <para>&os; 5.5</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_4_0_RELEASE</term> + + <listitem> + <para>&os; 5.4</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_11_0_RELEASE</term> + + <listitem> + <para>&os; 4.11</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_3_0_RELEASE</term> + + <listitem> + <para>&os; 5.3</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_10_0_RELEASE</term> + + <listitem> + <para>&os; 4.10</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_2_1_RELEASE</term> + + <listitem> + <para>&os; 5.2.1</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_2_0_RELEASE</term> + + <listitem> + <para>&os; 5.2</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_9_0_RELEASE</term> + + <listitem> + <para>&os; 4.9</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_1_0_RELEASE</term> + + <listitem> + <para>&os; 5.1</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_8_0_RELEASE</term> + + <listitem> + <para>&os; 4.8</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_5_0_0_RELEASE</term> + + <listitem> + <para>&os; 5.0</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_7_0_RELEASE</term> + + <listitem> + <para>&os; 4.7</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_6_2_RELEASE</term> + + <listitem> + <para>&os; 4.6.2</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_6_1_RELEASE</term> + + <listitem> + <para>&os; 4.6.1</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_6_0_RELEASE</term> + + <listitem> + <para>&os; 4.6</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_5_0_RELEASE</term> + + <listitem> + <para>&os; 4.5</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_4_0_RELEASE</term> + + <listitem> + <para>&os; 4.4</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_3_0_RELEASE</term> + + <listitem> + <para>&os; 4.3</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_2_0_RELEASE</term> + + <listitem> + <para>&os; 4.2</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_1_1_RELEASE</term> + + <listitem> + <para>&os; 4.1.1</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_1_0_RELEASE</term> + + <listitem> + <para>&os; 4.1</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_4_0_0_RELEASE</term> + + <listitem> + <para>&os; 4.0</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_3_5_0_RELEASE</term> + + <listitem> + <para>&os;-3.5</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_3_4_0_RELEASE</term> + + <listitem> + <para>&os;-3.4</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_3_3_0_RELEASE</term> + + <listitem> + <para>&os;-3.3</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_3_2_0_RELEASE</term> + + <listitem> + <para>&os;-3.2</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_3_1_0_RELEASE</term> + + <listitem> + <para>&os;-3.1</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_3_0_0_RELEASE</term> + + <listitem> + <para>&os;-3.0</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_2_2_8_RELEASE</term> + + <listitem> + <para>&os;-2.2.8</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_2_2_7_RELEASE</term> + + <listitem> + <para>&os;-2.2.7</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_2_2_6_RELEASE</term> + + <listitem> + <para>&os;-2.2.6</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_2_2_5_RELEASE</term> + + <listitem> + <para>&os;-2.2.5</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_2_2_2_RELEASE</term> + + <listitem> + <para>&os;-2.2.2</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_2_2_1_RELEASE</term> + + <listitem> + <para>&os;-2.2.1</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RELENG_2_2_0_RELEASE</term> + + <listitem> + <para>&os;-2.2.0</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + </sect1> + + <sect1 id="mirrors-afs"> + <title>AFS Sites</title> + + <para>AFS servers for &os; are running at the following sites:</para> + + <variablelist> + <varlistentry> + <term>Sweden</term> + + <listitem> + <para>The path to the files are: + <filename>/afs/stacken.kth.se/ftp/pub/FreeBSD/</filename></para> + + <programlisting>stacken.kth.se # Stacken Computer Club, KTH, Sweden +130.237.234.43 #hot.stacken.kth.se +130.237.237.230 #fishburger.stacken.kth.se +130.237.234.3 #milko.stacken.kth.se</programlisting> + + <para>Maintainer <email>ftp@stacken.kth.se</email></para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="mirrors-rsync"> + <title>rsync Sites</title> + + <para>The following sites make &os; available through the rsync + protocol. The <application>rsync</application> utility works in + much the same way as the &man.rcp.1; command, + but has more options and uses the rsync remote-update protocol + which transfers only the differences between two sets of files, + thus greatly speeding up the synchronization over the network. + This is most useful if you are a mirror site for the + &os; FTP server, or the CVS repository. The + <application>rsync</application> suite is available for many + operating systems, on &os;, see the + <filename role="package">net/rsync</filename> + port or use the package.</para> + + <variablelist> + <varlistentry> + <term>Czech Republic</term> + + <listitem> + <para>rsync://ftp.cz.FreeBSD.org/</para> + + <para>Available collections:</para> + <itemizedlist> + <listitem><para>ftp: A partial mirror of the &os; FTP + server.</para></listitem> + <listitem><para>&os;: A full mirror of the &os; FTP + server.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>Netherlands</term> + + <listitem> + <para>rsync://ftp.nl.FreeBSD.org/</para> + + <para>Available collections:</para> + <itemizedlist> + <listitem><para>&os;: A full mirror of the + &os; FTP server.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>Russia</term> + + <listitem> + <para>rsync://ftp.mtu.ru/</para> + + <para>Available collections:</para> + <itemizedlist> + <listitem><para>&os;: A full mirror of the &os; FTP + server.</para></listitem> + <listitem><para>&os;-gnats: The GNATS bug-tracking + database.</para></listitem> + <listitem><para>&os;-Archive: The mirror of &os; Archive FTP + server.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>Sweden</term> + + <listitem> + <para>rsync://ftp4.se.freebsd.org/</para> + + <para>Available collections:</para> + <itemizedlist> + <listitem><para>&os;: A full mirror of the &os; FTP + server.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>Taiwan</term> + + <listitem> + <para>rsync://ftp.tw.FreeBSD.org/</para> + <para>rsync://ftp2.tw.FreeBSD.org/</para> + <para>rsync://ftp6.tw.FreeBSD.org/</para> + + <para>Available collections:</para> + <itemizedlist> + <listitem><para>&os;: A full mirror of the &os; FTP + server.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>United Kingdom</term> + + <listitem> + <para>rsync://rsync.mirrorservice.org/</para> + + <para>Available collections:</para> + <itemizedlist> + <listitem><para>sites/ftp.freebsd.org: A full mirror of the + &os; FTP server.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>United States of America</term> + + <listitem> + <para>rsync://ftp-master.FreeBSD.org/</para> + + <para>This server may only be used by &os; primary mirror + sites.</para> + <para>Available collections:</para> + <itemizedlist> + <listitem><para>&os;: The master archive of the &os; + FTP server.</para></listitem> + <listitem><para>acl: The &os; master ACL + list.</para></listitem> + </itemizedlist> + + <para>rsync://ftp13.FreeBSD.org/</para> + + <para>Available collections:</para> + <itemizedlist> + <listitem><para>&os;: A full mirror of the &os; FTP + server.</para></listitem> + </itemizedlist> + </listitem> + </varlistentry> + </variablelist> + </sect1> +</appendix> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../appendix.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "appendix") + End: +--> + diff --git a/en_US.ISO8859-1/books/handbook/multimedia/Makefile b/en_US.ISO8859-1/books/handbook/multimedia/Makefile new file mode 100644 index 0000000000..f90e1cd2b0 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/multimedia/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= multimedia/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml b/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml new file mode 100644 index 0000000000..5a480e6393 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/multimedia/chapter.sgml @@ -0,0 +1,1948 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="multimedia"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Ross</firstname> + <surname>Lippert</surname> + <contrib>Edited by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>Multimedia</title> + <sect1 id="multimedia-synopsis"> + <title>Synopsis</title> + + <para>FreeBSD supports a wide variety of sound cards, allowing you + to enjoy high fidelity output from your computer. This includes + the ability to record and playback audio in the MPEG Audio Layer + 3 (MP3), WAV, and Ogg Vorbis formats as well as many other + formats. The FreeBSD Ports Collection also contains + applications allowing you to edit your recorded audio, add sound + effects, and control attached MIDI devices.</para> + + <para>With some experimentation, &os; can support + playback of video files and DVDs. The number of applications + to encode, convert, and playback various video media is more + limited than the number of sound applications. For example as + of this writing, there are no good re-encoding applications in the + FreeBSD Ports Collection that could be used to convert + between formats, as there is with <filename + role="package">audio/sox</filename>. However, the software + landscape in this area is changing rapidly.</para> + + <para>This chapter will describe the necessary steps to configure + your sound card. The configuration and installation of X11 + (<xref linkend="x11">) has already taken care of the + hardware issues for your video card, though there may be some + tweaks to apply for better playback.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to configure your system so that your sound card is + recognized.</para> + </listitem> + + <listitem> + <para>Methods to test whether your card is working.</para> + </listitem> + + <listitem> + <para>How to troubleshoot your sound setup.</para> + </listitem> + + <listitem> + <para>How to playback and encode MP3s and other audio.</para> + </listitem> + + <listitem> + <para>How video is supported by the X server.</para> + </listitem> + + <listitem> + <para>Some video player/encoder ports which give good results.</para> + </listitem> + + <listitem> + <para>How to playback DVDs, <filename>.mpg</filename> and + <filename>.avi</filename> files.</para> + </listitem> + + <listitem> + <para>How to rip CD and DVD content into files.</para> + </listitem> + + <listitem> + <para>How to configure a TV card.</para> + </listitem> + + <listitem> + <para>How to configure an image scanner.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem><para>Know how to configure and install a new kernel (<xref + linkend="kernelconfig">).</para></listitem> + </itemizedlist> + + <warning> + <para>Trying to mount audio CDs + with the &man.mount.8; command will + result in an error, at least, and a <emphasis>kernel + panic</emphasis>, at worst. These media have specialized + encodings which differ from the usual ISO-filesystem.</para> + </warning> + + </sect1> + + <sect1 id="sound-setup"> + <sect1info> + <authorgroup> + <author> + <firstname>Moses</firstname> + <surname>Moore</surname> + <contrib>Contributed by </contrib> + <!-- 20 November 2000 --> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + <contrib>Enhanced by </contrib> + <!-- 13 September 2004 --> + </author> + </authorgroup> + </sect1info> + + <title>Setting Up the Sound Card</title> + + <sect2 id="sound-device"> + <title>Configuring the System</title> + + <indexterm><primary>PCI</primary></indexterm> + <indexterm><primary>ISA</primary></indexterm> + <indexterm><primary>sound cards</primary></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. + FreeBSD supports a wide variety of both PCI and ISA cards. + Check the supported audio devices list of the <ulink + url="&rel.current.hardware;">Hardware Notes</ulink> to see if + your card is supported. The Hardware Notes will also mention which + driver supports your card.</para> + + <indexterm> + <primary>kernel</primary> + <secondary>configuration</secondary> + </indexterm> + + <para>To use your sound device, you will need to load the proper + device driver. This may be accomplished in one of two ways. + The easiest way is to simply load a kernel module for your sound + card with &man.kldload.8; which can either be done from the + command line:</para> + + <screen>&prompt.root; <userinput>kldload snd_emu10k1</userinput></screen> + + <para>or by adding the appropriate line to the file + <filename>/boot/loader.conf</filename> like this:</para> + + <programlisting>snd_emu10k1_load="YES"</programlisting> + + <para>These examples are for a Creative &soundblaster; Live! sound + card. Other available loadable sound modules are listed in + <filename>/boot/defaults/loader.conf</filename>. + If you are not sure which driver to use, you may try to load + the <filename>snd_driver</filename> module:</para> + + <screen>&prompt.root; <userinput>kldload snd_driver</userinput></screen> + + <para>This is a metadriver loading the most common device drivers + at once. This speeds up the search for the correct driver. It + is also possible to load all sound drivers via the + <filename>/boot/loader.conf</filename> facility.</para> + + <para>If you wish to find out the driver selected for your + soundcard after loading the <filename>snd_driver</filename> + metadriver, you may check the <filename>/dev/sndstat</filename> + file with the <command>cat /dev/sndstat</command> + command.</para> + + <para>A second method is to statically + compile in support for your sound card in your kernel. The + section below provides the information you need to add support + for your hardware in this manner. For more information about + recompiling your kernel, please see <xref + linkend="kernelconfig">.</para> + + <sect3> + <title>Configuring a Custom Kernel with Sound Support</title> + + <para>The first thing to do is add the audio framework driver + &man.sound.4; to the kernel; for that you will need to + add the following line to the kernel configuration file:</para> + + <programlisting>device sound</programlisting> + + <para>Next, you have to add the support for your sound card. + Therefore, you need to know which driver supports the card. + Check the supported audio devices list of the <ulink + url="&rel.current.hardware;">Hardware Notes</ulink>, to + determine the correct driver for your sound card. For + example, a Creative &soundblaster; Live! sound card is + supported by the &man.snd.emu10k1.4; driver. To add the support + for this card, use the following:</para> + + <programlisting>device snd_emu10k1</programlisting> + + <para>Be sure to read the manual page of the driver for the + syntax to use. The explicit syntax for the kernel configuration + of every supported sound driver can also be found in the + <filename>/usr/src/sys/conf/NOTES</filename> file.</para> + + <para>Non-PnP ISA sound cards may require you to provide the kernel + with information on the card settings (IRQ, I/O port, + etc), as is true of all non-PnP ISA cards. This is done via the + <filename>/boot/device.hints</filename> file. During the boot process, + the &man.loader.8; will read this file and pass the settings + to the kernel. For example, an old + Creative &soundblaster; 16 ISA non-PnP card will use the + &man.snd.sbc.4; driver in conjunction with <literal>snd_sb16</literal>. For this card the following lines must be added to + the kernel configuration file:</para> + + <programlisting>device snd_sbc +device snd_sb16</programlisting> + + <para>and these to + <filename>/boot/device.hints</filename>:</para> + + <programlisting>hint.sbc.0.at="isa" +hint.sbc.0.port="0x220" +hint.sbc.0.irq="5" +hint.sbc.0.drq="1" +hint.sbc.0.flags="0x15"</programlisting> + + <para>In this case, the card uses the <literal>0x220</literal> + I/O port and the IRQ <literal>5</literal>.</para> + + <para>The syntax used in the + <filename>/boot/device.hints</filename> file is covered in the + &man.sound.4; driver manual page and the manual page + for the driver in question.</para> + + <para>The settings shown above are the defaults. In some + cases, you may need to change the IRQ or the other settings to + match your card. See the &man.snd.sbc.4; manual page for more + information about this card.</para> + </sect3> + </sect2> + + <sect2 id="sound-testing"> + <title>Testing the Sound Card</title> + + <para>After rebooting with the modified kernel, or after loading + the required module, the sound card should appear in your system + message buffer (&man.dmesg.8;) as something like:</para> + + <screen>pcm0: <Intel ICH3 (82801CA)> port 0xdc80-0xdcbf,0xd800-0xd8ff irq 5 at device 31.5 on pci0 +pcm0: [GIANT-LOCKED] +pcm0: <Cirrus Logic CS4205 AC97 Codec></screen> + + <para>The status of the sound card may be checked via the + <filename>/dev/sndstat</filename> file:</para> + + <screen>&prompt.root; <userinput>cat /dev/sndstat</userinput> +FreeBSD Audio Driver (newpcm) +Installed devices: +pcm0: <Intel ICH3 (82801CA)> at io 0xd800, 0xdc80 irq 5 bufsz 16384 +kld snd_ich (1p/2r/0v channels duplex default)</screen> + + <para>The output from your system may vary. If no + <devicename>pcm</devicename> devices are listed, go back and review + what was done earlier. Go through your kernel + configuration file again and make sure the correct + device driver was chosen. Common problems are listed in <xref + linkend="troubleshooting">.</para> + + <para>If all goes well, you should now have a functioning sound + card. If your CD-ROM or DVD-ROM drive's audio-out pins are properly connected to + your sound card, you can put a CD in the drive and play it + with &man.cdcontrol.1;:</para> + + <screen>&prompt.user; <userinput>cdcontrol -f /dev/acd0 play 1</userinput></screen> + + <para>Various applications, such as <filename + role="package">audio/workman</filename> can provide a friendlier + interface. You may want to install an application such as + <filename role="package">audio/mpg123</filename> to listen to + MP3 audio files.</para> + + <para>Another quick way to test the card is sending data + to <filename>/dev/dsp</filename>, like this:</para> + + <screen>&prompt.user; <userinput>cat <replaceable>filename</replaceable> > /dev/dsp</userinput></screen> + + <para>where <filename><replaceable>filename</replaceable></filename> can be any file. + This command line should produce some noise, confirming the + sound card is actually working.</para> + + <note> + <para>The device nodes <filename>/dev/dsp*</filename> will be + created automatically when needed. If they are not used, they + do not exist and will not appear in the output of + &man.ls.1;.</para> + </note> + + <para>Sound card mixer levels can be changed via the &man.mixer.8; + command. More details can be found in the &man.mixer.8; manual + page.</para> + + <sect3 id="troubleshooting"> + <title>Common Problems</title> + + <indexterm><primary>device nodes</primary></indexterm> + <indexterm><primary>I/O port</primary></indexterm> + <indexterm><primary>IRQ</primary></indexterm> + <indexterm><primary>DSP</primary></indexterm> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Error</entry> + <entry>Solution</entry> + </row> + </thead> + + <tbody> + <row> + <entry><errorname>sb_dspwr(XX) timed out</errorname></entry> + <entry><para>The I/O port is not set correctly.</para></entry> + </row> + + <row> + <entry><errorname>bad irq XX</errorname></entry> + <entry><para>The IRQ is set incorrectly. Make sure that + the set IRQ and the sound IRQ are the same.</para></entry> + </row> + + <row> + <entry><errorname>xxx: gus pcm not attached, out of memory</errorname></entry> + <entry><para>There is not enough available memory to use + the device.</para></entry> + </row> + + <row> + <entry><errorname>xxx: can't open /dev/dsp!</errorname></entry> + <entry><para>Check with <command>fstat | grep dsp</command> + if another application is holding the device open. + Noteworthy troublemakers are <application>esound</application> and <application>KDE</application>'s sound + support.</para></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Another issue is that modern graphics cards often come with their + own sound driver, for use with <acronym>HDMI</acronym> and similar. + This sound device will sometimes be enumerated before the actual + soundcard and the soundcard will subsequently not be used as the + default playback device. To check if this is the case, run + <application>dmesg</application> and look for <literal>pcm</literal>. + The output looks something like this:</para> + +<programlisting>... +hdac0: HDA Driver Revision: 20100226_0142 +hdac1: HDA Driver Revision: 20100226_0142 +hdac0: HDA Codec #0: NVidia (Unknown) +hdac0: HDA Codec #1: NVidia (Unknown) +hdac0: HDA Codec #2: NVidia (Unknown) +hdac0: HDA Codec #3: NVidia (Unknown) +pcm0: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 0 nid 1 on hdac0 +pcm1: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 1 nid 1 on hdac0 +pcm2: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 2 nid 1 on hdac0 +pcm3: <HDA NVidia (Unknown) PCM #0 DisplayPort> at cad 3 nid 1 on hdac0 +hdac1: HDA Codec #2: Realtek ALC889 +pcm4: <HDA Realtek ALC889 PCM #0 Analog> at cad 2 nid 1 on hdac1 +pcm5: <HDA Realtek ALC889 PCM #1 Analog> at cad 2 nid 1 on hdac1 +pcm6: <HDA Realtek ALC889 PCM #2 Digital> at cad 2 nid 1 on hdac1 +pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 +...</programlisting> + + <para>Here the graphics card (<literal>NVidia</literal>) has been + enumerated before the sound card (<literal>Realtek ALC889</literal>). + To use the sound card as default playback device, change + <literal>hw.snd.default_unit</literal> to the unit that should be used + for playback, enter the following:</para> + + <screen>&prompt.root; <userinput>sysctl hw.snd.default_unit=<replaceable>n</replaceable></userinput></screen> + + <para>Here, <literal>n</literal> is the number of the sound device to + use, in this example <literal>4</literal>. You can make this change + permanent by adding the following line to + <filename>/etc/sysctl.conf</filename>:</para> + + <programlisting>hw.snd.default_unit=<replaceable>4</replaceable></programlisting> + </sect3> + </sect2> + + <sect2 id="sound-multiple-sources"> + <sect2info> + <authorgroup> + <author> + <firstname>Munish</firstname> + <surname>Chopra</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <title>Utilizing Multiple Sound Sources</title> + + <para>It is often desirable to have multiple sources of sound that + are able to play simultaneously, such as when + <application>esound</application> or + <application>artsd</application> do not support sharing of the + sound device with a certain application.</para> + + <para>FreeBSD lets you do this through <emphasis>Virtual Sound + Channels</emphasis>, which can be enabled with the &man.sysctl.8; + facility. Virtual channels allow you to multiplex your sound + card's playback by mixing sound in the kernel.</para> + + <para>To set the number of virtual channels, there are three sysctl + knobs which, if you are the <username>root</username> user, can + be set like this:</para> + <screen>&prompt.root; <userinput>sysctl dev.pcm.0.play.vchans=4</userinput> +&prompt.root; <userinput>sysctl dev.pcm.0.rec.vchans=4</userinput> +&prompt.root; <userinput>sysctl hw.snd.maxautovchans=4</userinput></screen> + + <para>The above example allocates four virtual channels, which is a + practical number for everyday use. Both <varname>dev.pcm.0.play.vchans=4</varname> + and <varname>dev.pcm.0.rec.vchans=4</varname> + are the number of virtual channels <devicename>pcm0</devicename> has for playback and recording, and are configurable + once a device has been attached. + <literal>hw.snd.maxautovchans</literal> is the number of virtual channels + a new audio device is given when it is attached using + &man.kldload.8;. Since the <devicename>pcm</devicename> module + can be loaded independently of the hardware drivers, + <varname>hw.snd.maxautovchans</varname> can store how many + virtual channels any devices which are attached later will be + given. Refer to &man.pcm.4; manual page for more + information.</para> + + <note> + <para>You cannot change the number of virtual channels for a + device while it is in use. First close any programs using the + device, such as music players or sound daemons.</para> + </note> + + <para> + The correct <devicename>pcm</devicename> device will + automatically be allocated transparently to a program + that requests <filename>/dev/dsp0</filename>.</para> + </sect2> + + <sect2> + <sect2info> + <authorgroup> + <author> + <firstname>Josef</firstname> + <surname>El-Rayes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>Setting Default Values for Mixer Channels</title> + + <para>The default values for the different mixer channels are + hardcoded in the sourcecode of the &man.pcm.4; driver. There are + many different applications and daemons that allow + you to set values for the mixer that are remembered between + invocations, but this is not a clean solution. It is possible + to set default mixer values at the driver level — this + is accomplished by defining the appropriate + values in <filename>/boot/device.hints</filename>, e.g.:</para> + +<programlisting>hint.pcm.0.vol="50"</programlisting> + + <para>This will set the volume channel to a default value of + 50 when the &man.pcm.4; module is loaded.</para> + </sect2> +</sect1> + + <sect1 id="sound-mp3"> + <sect1info> + <authorgroup> + <author> + <firstname>Chern</firstname> + <surname>Lee</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <!-- 11 Sept 2001 --> + </sect1info> + + <title>MP3 Audio</title> + + <para>MP3 (MPEG Layer 3 Audio) accomplishes near CD-quality sound, + leaving no reason to let your FreeBSD workstation fall short of + its offerings.</para> + + <sect2 id="mp3-players"> + <title>MP3 Players</title> + + <para>By far, the most popular X11 MP3 player is + <application>XMMS</application> (X Multimedia System). + <application>Winamp</application> + skins can be used with <application>XMMS</application> since the + GUI is almost identical to that of Nullsoft's + <application>Winamp</application>. + <application>XMMS</application> also has native plug-in + support.</para> + + <para><application>XMMS</application> can be installed from the + <filename role="package">multimedia/xmms</filename> port or package.</para> + + <para><application>XMMS</application>'s interface is intuitive, + with a playlist, graphic equalizer, and more. Those familiar + with <application>Winamp</application> will find + <application>XMMS</application> simple to use.</para> + + <para>The <filename role="package">audio/mpg123</filename> port is an alternative, + command-line MP3 player.</para> + + <para><application>mpg123</application> can be run by specifying + the sound device and the MP3 file on the command line. Assuming your + audio device is <devicename>/dev/dsp1.0</devicename> and you want + to play the MP3 file <replaceable>Foobar-GreatestHits.mp3</replaceable> + you would enter the following:</para> + + <screen>&prompt.root; <userinput>mpg123 -a <devicename>/dev/dsp1.0</devicename> <replaceable>Foobar-GreatestHits.mp3</replaceable></userinput> +High Performance MPEG 1.0/2.0/2.5 Audio Player for Layer 1, 2 and 3. +Version 0.59r (1999/Jun/15). Written and copyrights by Michael Hipp. +Uses code from various people. See 'README' for more! +THIS SOFTWARE COMES WITH ABSOLUTELY NO WARRANTY! USE AT YOUR OWN RISK! + + + + + +Playing MPEG stream from Foobar-GreatestHits.mp3 ... +MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo +</screen> + </sect2> + + <sect2 id="rip-cd"> + <title>Ripping CD Audio Tracks</title> + + <para>Before encoding a CD or CD track to MP3, the audio data on + the CD must be ripped onto the hard drive. This is done by + copying the raw CDDA (CD Digital Audio) data to WAV + files.</para> + + <para>The <command>cdda2wav</command> tool, which is a part of + the <filename role="package">sysutils/cdrtools</filename> + suite, is used for ripping audio information from CDs and the + information associated with them.</para> + + <para>With the audio CD in the drive, the following command can + be issued (as <username>root</username>) to rip an entire CD + into individual (per track) WAV files:</para> + + <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -B</userinput></screen> + + <para><application>cdda2wav</application> will support + ATAPI (IDE) CDROM drives. To rip from an IDE drive, specify + the device name in place of the SCSI unit numbers. For + example, to rip track 7 from an IDE drive:</para> + + <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>/dev/acd0</replaceable> -t 7</userinput></screen> + + <para>The <option>-D <replaceable>0,1,0</replaceable></option> + indicates the SCSI device <devicename>0,1,0</devicename>, + which corresponds to the output of <command>cdrecord + -scanbus</command>.</para> + + <para>To rip individual tracks, make use of the + <option>-t</option> option as shown:</para> + + <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -t 7</userinput></screen> + + <para>This example rips track seven of the audio CDROM. To rip + a range of tracks, for example, track one to seven, specify a + range:</para> + + <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -t 1+7</userinput></screen> + + <para>The utility &man.dd.1; can also be used to extract audio tracks + on ATAPI drives, read <xref linkend="duplicating-audiocds"> + for more information on that possibility.</para> + + </sect2> + + <sect2 id="mp3-encoding"> + <title>Encoding MP3s</title> + + <para>Nowadays, the mp3 encoder of choice is + <application>lame</application>. + <application>Lame</application> can be found at + <filename role="package">audio/lame</filename> in the ports tree.</para> + + <para>Using the ripped WAV files, the following command will + convert <filename><replaceable>audio01.wav</replaceable></filename> to + <filename><replaceable>audio01.mp3</replaceable></filename>:</para> + + <screen>&prompt.root; <userinput>lame -h -b <replaceable>128</replaceable> \ +--tt "<replaceable>Foo Song Title</replaceable>" \ +--ta "<replaceable>FooBar Artist</replaceable>" \ +--tl "<replaceable>FooBar Album</replaceable>" \ +--ty "<replaceable>2001</replaceable>" \ +--tc "<replaceable>Ripped and encoded by Foo</replaceable>" \ +--tg "<replaceable>Genre</replaceable>" \ +<replaceable>audio01.wav audio01.mp3</replaceable></userinput></screen> + + <para>128 kbits seems to be the standard MP3 bitrate in use. + Many enjoy the higher quality 160, or 192. The higher the + bitrate, the more disk space the resulting MP3 will + consume--but the quality will be higher. The + <option>-h</option> option turns on the <quote>higher quality + but a little slower</quote> mode. The options beginning with + <option>--t</option> indicate ID3 tags, which usually contain + song information, to be embedded within the MP3 file. + Additional encoding options can be found by consulting the + <application>lame</application> man page.</para> + </sect2> + + <sect2 id="mp3-decoding"> + <title>Decoding MP3s</title> + + <para>In order to burn an audio CD from MP3s, they must be + converted to a non-compressed WAV format. Both + <application>XMMS</application> and + <application>mpg123</application> support the output of MP3 to + an uncompressed file format.</para> + + <para>Writing to Disk in <application>XMMS</application>:</para> + + <procedure> + <step> + <para>Launch <application>XMMS</application>.</para> + </step> + + <step> + <para>Right-click on the window to bring up the + <application>XMMS</application> menu.</para> + </step> + + <step> + <para>Select <literal>Preference</literal> under + <literal>Options</literal>.</para> + </step> + + <step> + <para>Change the Output Plugin to <quote>Disk Writer + Plugin</quote>.</para> + </step> + + <step> + <para>Press <literal>Configure</literal>.</para> + </step> + + <step> + <para>Enter (or choose browse) a directory to write the + uncompressed files to.</para> + </step> + + <step> + <para>Load the MP3 file into <application>XMMS</application> + as usual, with volume at 100% and EQ settings turned + off.</para> + </step> + + <step> + <para>Press <literal>Play</literal> — + <application>XMMS</application> will appear as if it is + playing the MP3, but no music will be heard. It is + actually playing the MP3 to a file.</para> + </step> + + <step> + <para>Be sure to set the default Output Plugin back to what + it was before in order to listen to MP3s again.</para> + </step> + </procedure> + + <para>Writing to stdout in <application>mpg123</application>:</para> + + <procedure> + <step> + <para>Run <command>mpg123 -s <replaceable>audio01.mp3</replaceable> + > <replaceable>audio01.pcm</replaceable></command></para> + </step> + </procedure> + + <para><application>XMMS</application> writes a file in the WAV + format, while <application>mpg123</application> converts the + MP3 into raw PCM audio data. Both of these formats can be + used with <application>cdrecord</application> to create audio CDs. + You have to use raw PCM with &man.burncd.8;. + If you use WAV files, you will notice a small tick sound at the + beginning of each track, this sound is the header of the WAV + file. You can simply remove the header of a WAV file with the + utility <application>SoX</application> (it can be installed from + the <filename role="package">audio/sox</filename> port or + package):</para> + + <screen>&prompt.user; <userinput>sox -t wav -r 44100 -s -w -c 2 <replaceable>track.wav track.raw</replaceable></userinput></screen> + + <para>Read <xref linkend="creating-cds"> for more information on using a + CD burner in FreeBSD.</para> + </sect2> + </sect1> + + <sect1 id="video-playback"> + <sect1info> + <authorgroup> + <author> + <firstname>Ross</firstname> + <surname>Lippert</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <!-- 5 June 2002 --> + </sect1info> + + <title>Video Playback</title> + + <para>Video playback is a very new and rapidly developing application + area. Be patient. Not everything is going to work as smoothly as + it did with sound.</para> + + <para>Before you begin, you should know the model of the video + card you have and the chip it uses. While <application>&xorg;</application> supports a + wide variety of video cards, fewer give good playback + performance. To obtain a list of extensions supported by the + X server using your card use the command &man.xdpyinfo.1; while + X11 is running.</para> + + <para>It is a good idea to have a short MPEG file which can be + treated as a test file for evaluating various players and + options. Since some DVD players will look for DVD media in + <filename>/dev/dvd</filename> by default, or have this device + name hardcoded in them, you might find it useful to make + symbolic links to the proper devices:</para> + + <screen>&prompt.root; <userinput>ln -sf /dev/acd0 /dev/dvd</userinput> +&prompt.root; <userinput>ln -sf /dev/acd0 /dev/rdvd</userinput></screen> + + <para>Note that due to the nature of &man.devfs.5;, + manually created links like these will not persist if you reboot + your system. In order to create the symbolic links + automatically whenever you boot your system, add the following + lines to <filename>/etc/devfs.conf</filename>:</para> + + <programlisting>link acd0 dvd +link acd0 rdvd</programlisting> + + <para>Additionally, DVD decryption, which requires invoking + special DVD-ROM functions, requires write permission on the DVD + devices.</para> + + <para>To enhance the shared memory X11 interface, it is + recommended that the values of some &man.sysctl.8; variables + should be increased:</para> + + <programlisting>kern.ipc.shmmax=67108864 +kern.ipc.shmall=32768</programlisting> + + <sect2 id="video-interface"> + <title>Determining Video Capabilities</title> + + <indexterm><primary>XVideo</primary></indexterm> + <indexterm><primary>SDL</primary></indexterm> + <indexterm><primary>DGA</primary></indexterm> + + <para>There are several possible ways to display video under X11. + What will really work is largely hardware dependent. Each + method described below will have varying quality across + different hardware. Secondly, the rendering of video in X11 is + a topic receiving a lot of attention lately, and with each + version of <application>&xorg;</application>, there may be significant improvement.</para> + + <para>A list of common video interfaces:</para> + + <orderedlist> + <listitem> + <para>X11: normal X11 output using shared memory.</para> + </listitem> + <listitem> + <para>XVideo: an extension to the X11 + interface which supports video in any X11 drawable.</para> + </listitem> + <listitem> + <para>SDL: the Simple Directmedia Layer.</para> + </listitem> + <listitem> + <para>DGA: the Direct Graphics Access.</para> + </listitem> + <listitem> + <para>SVGAlib: low level console graphics layer.</para> + </listitem> + </orderedlist> + + <sect3 id="video-interface-xvideo"> + <title>XVideo</title> + + <para><application>&xorg;</application> has an extension called + <emphasis>XVideo</emphasis> (aka Xvideo, aka Xv, aka xv) which + allows video to be directly displayed in drawable objects + through a special acceleration. This extension provides very + good quality playback even on low-end machines.</para> + + <para>To check whether the extension is running, + use <command>xvinfo</command>:</para> + + <screen>&prompt.user; <userinput>xvinfo</userinput></screen> + + <para>XVideo is supported for your card if the result looks like:</para> +<screen>X-Video Extension version 2.2 +screen #0 + Adaptor #0: "Savage Streams Engine" + number of ports: 1 + port base: 43 + operations supported: PutImage + supported visuals: + depth 16, visualID 0x22 + depth 16, visualID 0x23 + number of attributes: 5 + "XV_COLORKEY" (range 0 to 16777215) + client settable attribute + client gettable attribute (current value is 2110) + "XV_BRIGHTNESS" (range -128 to 127) + client settable attribute + client gettable attribute (current value is 0) + "XV_CONTRAST" (range 0 to 255) + client settable attribute + client gettable attribute (current value is 128) + "XV_SATURATION" (range 0 to 255) + client settable attribute + client gettable attribute (current value is 128) + "XV_HUE" (range -180 to 180) + client settable attribute + client gettable attribute (current value is 0) + maximum XvImage size: 1024 x 1024 + Number of image formats: 7 + id: 0x32595559 (YUY2) + guid: 59555932-0000-0010-8000-00aa00389b71 + bits per pixel: 16 + number of planes: 1 + type: YUV (packed) + id: 0x32315659 (YV12) + guid: 59563132-0000-0010-8000-00aa00389b71 + bits per pixel: 12 + number of planes: 3 + type: YUV (planar) + id: 0x30323449 (I420) + guid: 49343230-0000-0010-8000-00aa00389b71 + bits per pixel: 12 + number of planes: 3 + type: YUV (planar) + id: 0x36315652 (RV16) + guid: 52563135-0000-0000-0000-000000000000 + bits per pixel: 16 + number of planes: 1 + type: RGB (packed) + depth: 0 + red, green, blue masks: 0x1f, 0x3e0, 0x7c00 + id: 0x35315652 (RV15) + guid: 52563136-0000-0000-0000-000000000000 + bits per pixel: 16 + number of planes: 1 + type: RGB (packed) + depth: 0 + red, green, blue masks: 0x1f, 0x7e0, 0xf800 + id: 0x31313259 (Y211) + guid: 59323131-0000-0010-8000-00aa00389b71 + bits per pixel: 6 + number of planes: 3 + type: YUV (packed) + id: 0x0 + guid: 00000000-0000-0000-0000-000000000000 + bits per pixel: 0 + number of planes: 0 + type: RGB (packed) + depth: 1 + red, green, blue masks: 0x0, 0x0, 0x0</screen> + + <para>Also note that the formats listed (YUV2, YUV12, etc) are not + present with every implementation of XVideo and their absence may + hinder some players.</para> + + <para>If the result looks like:</para> +<screen>X-Video Extension version 2.2 +screen #0 +no adaptors present</screen> + + <para>Then XVideo is probably not supported for your card.</para> + + <para>If XVideo is not supported for your card, this only means + that it will be more difficult for your display to meet the + computational demands of rendering video. Depending on your + video card and processor, though, you might still be able to + have a satisfying experience. You should probably read about + ways of improving performance in the advanced reading <xref + linkend="video-further-reading">.</para> + + </sect3> + + <sect3 id="video-interface-SDL"> + <title>Simple Directmedia Layer</title> + + <para>The Simple Directmedia Layer, SDL, was intended to be a + porting layer between µsoft.windows;, BeOS, and &unix;, + allowing cross-platform applications to be developed which made + efficient use of sound and graphics. The SDL layer provides a + low-level abstraction to the hardware which can sometimes be + more efficient than the X11 interface.</para> + + <para>The SDL can be found at <filename role="package">devel/sdl12</filename>.</para> + + </sect3> + + <sect3 id="video-interface-DGA"> + <title>Direct Graphics Access</title> + + <para>Direct Graphics Access is an X11 extension which allows + a program to bypass the X server and directly alter the + framebuffer. Because it relies on a low level memory mapping to + effect this sharing, programs using it must be run as + <username>root</username>.</para> + + <para>The DGA extension can be tested and benchmarked by + &man.dga.1;. When <command>dga</command> is running, it + changes the colors of the display whenever a key is pressed. To + quit, use <keycap>q</keycap>.</para> + + </sect3> + + </sect2> + + <sect2 id="video-ports"> + <title>Ports and Packages Dealing with Video</title> + + <indexterm><primary>video ports</primary></indexterm> + <indexterm><primary>video packages</primary></indexterm> + + <para>This section discusses the software available from the + FreeBSD Ports Collection which can be used for video playback. + Video playback is a very active area of software development, + and the capabilities of various applications are bound to + diverge somewhat from the descriptions given here.</para> + + <para>Firstly, it is important to know that many of the video + applications which run on FreeBSD were developed as Linux + applications. Many of these applications are still + beta-quality. Some of the problems that you may encounter with + video packages on FreeBSD include:</para> + + <orderedlist> + + <listitem> + <para>An application cannot playback a file which another + application produced.</para> + </listitem> + + <listitem> + <para>An application cannot playback a file which the + application itself produced.</para> + </listitem> + + <listitem> + <para>The same application on two different machines, + rebuilt on each machine for that machine, plays back the same + file differently.</para> + </listitem> + + <listitem> + <para>A seemingly trivial filter like rescaling of the image + size results in very bad artifacts from a buggy rescaling + routine.</para> + </listitem> + + <listitem> + <para>An application frequently dumps core.</para> + </listitem> + + <listitem> + <para>Documentation is not installed with the port and can be + found either on the web or under the port's <filename class='directory'>work</filename> + directory.</para> + </listitem> + + </orderedlist> + + <para>Many of these applications may also exhibit + <quote>Linux-isms</quote>. That is, there may be + issues resulting from the way some standard libraries are + implemented in the Linux distributions, or some features of the + Linux kernel which have been assumed by the authors of the + applications. These issues are not always noticed and worked around + by the port maintainers, which can lead to problems like + these:</para> + + <orderedlist> + + <listitem> + <para>The use of <filename>/proc/cpuinfo</filename> to detect + processor characteristics.</para> + </listitem> + + <listitem> + <para>A misuse of threads which causes a program to hang upon + completion instead of truly terminating.</para> + </listitem> + + <listitem> + <para>Software not yet in the FreeBSD Ports Collection + which is commonly used in conjunction with the application.</para> + </listitem> + + </orderedlist> + + <para>So far, these application developers have been cooperative with + port maintainers to minimize the work-arounds needed for + port-ing.</para> + + <sect3 id="video-mplayer"> + <title>MPlayer</title> + + <para><application>MPlayer</application> is a recently developed and rapidly developing + video player. The goals of the <application>MPlayer</application> team are speed and + flexibility on Linux and other Unices. The project was + started when the team founder got fed up with bad playback + performance on then available players. Some would say that + the graphical interface has been sacrificed for a streamlined + design. However, once + you get used to the command line options and the key-stroke + controls, it works very well.</para> + + <sect4 id="video-mplayer-building"> + <title>Building MPlayer</title> + <indexterm><primary>MPlayer</primary> + <secondary>making</secondary></indexterm> + + <para><application>MPlayer</application> resides in <filename + role="package">multimedia/mplayer</filename>. + <application>MPlayer</application> performs a variety of + hardware checks during the build process, resulting in a + binary which will not be portable from one system to + another. Therefore, it is important to build it from + ports and not to use a binary package. Additionally, a + number of options can be specified in the <command>make</command> + command line, as described in the <filename>Makefile</filename> and at the start of the build:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/multimedia/mplayer</userinput> +&prompt.root; <userinput>make</userinput> +N - O - T - E + +Take a careful look into the Makefile in order +to learn how to tune mplayer towards you personal preferences! +For example, +make WITH_GTK1 +builds MPlayer with GTK1-GUI support. +If you want to use the GUI, you can either install +/usr/ports/multimedia/mplayer-skins +or download official skin collections from +http://www.mplayerhq.hu/homepage/dload.html +</screen> + + <para>The default port options should be sufficient for most + users. However, if you need the XviD codec, you have to + specify the <makevar>WITH_XVID</makevar> option in the + command line. The default DVD device can also be defined + with the <makevar>WITH_DVD_DEVICE</makevar> option, by + default <filename>/dev/acd0</filename> will be used.</para> + + <para>As of this writing, the <application>MPlayer</application> port will build its HTML + documentation and two executables, + <command>mplayer</command>, and + <command>mencoder</command>, which is a tool for + re-encoding video.</para> + + <para>The HTML documentation for <application>MPlayer</application> is very informative. + If the reader finds the information on video hardware and + interfaces in this chapter lacking, the <application>MPlayer</application> documentation + is a very thorough supplement. You should definitely take + the time to read the <application>MPlayer</application> + documentation if you are looking for information about video + support in &unix;.</para> + + </sect4> + + <sect4 id="video-mplayer-using"> + <title>Using MPlayer</title> + <indexterm><primary>MPlayer</primary> + <secondary>use</secondary></indexterm> + + <para>Any user of <application>MPlayer</application> must set up a + <filename>.mplayer</filename> subdirectory of her + home directory. To create this necessary subdirectory, + you can type the following:</para> + +<screen>&prompt.user; <userinput>cd /usr/ports/multimedia/mplayer</userinput> +&prompt.user; <userinput>make install-user</userinput></screen> + + <para>The command options for <command>mplayer</command> are + listed in the manual page. For even more detail there is HTML + documentation. In this section, we will describe only a few + common uses.</para> + + <para>To play a file, such as + <filename><replaceable>testfile.avi</replaceable></filename>, + through one of the various video interfaces set the + <option>-vo</option> option:</para> + + <screen>&prompt.user; <userinput>mplayer -vo xv <replaceable>testfile.avi</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mplayer -vo sdl <replaceable>testfile.avi</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mplayer -vo x11 <replaceable>testfile.avi</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mplayer -vo dga <replaceable>testfile.avi</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mplayer -vo 'sdl:dga' <replaceable>testfile.avi</replaceable></userinput></screen> + + <para>It is worth trying all of these options, as their relative + performance depends on many factors and will vary significantly + with hardware.</para> + + <para>To play from a DVD, replace the + <filename><replaceable>testfile.avi</replaceable></filename> with <option>dvd://<replaceable>N</replaceable> -dvd-device + <replaceable>DEVICE</replaceable></option> where <replaceable>N</replaceable> is + the title number to play and + <filename><replaceable>DEVICE</replaceable></filename> is the + device node for the DVD-ROM. For example, to play title 3 + from <filename>/dev/dvd</filename>:</para> + + <screen>&prompt.root; <userinput>mplayer -vo xv dvd://3 -dvd-device /dev/dvd</userinput></screen> + + <note> + <para>The default DVD device can be defined during the build + of the <application>MPlayer</application> port via the + <makevar>WITH_DVD_DEVICE</makevar> option. By default, + this device is <filename>/dev/acd0</filename>. More + details can be found in the port + <filename>Makefile</filename>.</para> + </note> + + <para>To stop, pause, advance and so on, consult the + keybindings, which are output by running <command>mplayer + -h</command> or read the manual page.</para> + + <para>Additional important options for playback are: + <option>-fs -zoom</option> which engages the fullscreen mode + and <option>-framedrop</option> which helps performance.</para> + + <para>In order for the mplayer command line to not become too + large, the user can create a file + <filename>.mplayer/config</filename> and set default options + there:</para> +<programlisting>vo=xv +fs=yes +zoom=yes</programlisting> + + <para>Finally, <command>mplayer</command> can be used to rip a + DVD title into a <filename>.vob</filename> file. To dump + out the second title from a DVD, type this:</para> + + <screen>&prompt.root; <userinput>mplayer -dumpstream -dumpfile out.vob dvd://2 -dvd-device /dev/dvd</userinput></screen> + + <para>The output file, <filename>out.vob</filename>, will be + MPEG and can be manipulated by the other packages described + in this section.</para> + + </sect4> + <sect4 id="video-mencoder"> + <title>mencoder</title> + <indexterm> + <primary>mencoder</primary> + </indexterm> + + <para>Before using + <command>mencoder</command> it is a good idea to + familiarize yourself with the options from the HTML + documentation. There is a manual page, but it is not very + useful without the HTML documentation. There are innumerable ways to + improve quality, lower bitrate, and change formats, and some + of these tricks may make the difference between good + or bad performance. Here are a couple of examples to get + you going. First a simple copy:</para> + + <screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac copy -ovc copy -o <replaceable>output.avi</replaceable></userinput></screen> + + <para>Improper combinations of command line options can yield + output files that are + unplayable even by <command>mplayer</command>. Thus, if you + just want to rip to a file, stick to the <option>-dumpfile</option> + in <command>mplayer</command>.</para> + + <para>To convert <filename><replaceable>input.avi</replaceable></filename> to the MPEG4 + codec with MPEG3 audio encoding (<filename role="package">audio/lame</filename> is required):</para> + + <screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac mp3lame -lameopts br=192 \ + -ovc lavc -lavcopts vcodec=mpeg4:vhq -o <replaceable>output.avi</replaceable></userinput></screen> + + <para>This has produced output playable by <command>mplayer</command> + and <command>xine</command>.</para> + + <para><filename><replaceable>input.avi</replaceable></filename> can be replaced with + <option>dvd://1 -dvd-device /dev/dvd</option> and run as + <username>root</username> to re-encode a DVD title + directly. Since you are likely to be dissatisfied with + your results the first time around, it is recommended you + dump the title to a file and work on the file.</para> + </sect4> + + </sect3> + + <sect3 id="video-xine"> + <title>The xine Video Player</title> + + <para>The <application>xine</application> video player is a project of wide scope aiming not only at being an + all in one video solution, but also in producing a reusable base + library and a modular executable which can be extended with + plugins. It comes both as a package and as a port, <filename + role="package">multimedia/xine</filename>.</para> + + <para>The <application>xine</application> player + is still very rough around the edges, but it is clearly off to a + good start. In practice, <application>xine</application> requires either a fast CPU with a + fast video card, or support for the XVideo extension. The GUI is + usable, but a bit clumsy.</para> + + <para>As of this writing, there is no input module shipped with + <application>xine</application> which will play CSS encoded DVDs. There are third party + builds which do have modules for this built in them, but none + of these are in the FreeBSD Ports Collection.</para> + + <para>Compared to <application>MPlayer</application>, <application>xine</application> does more for the user, but at the + same time, takes some of the more fine-grained control away from + the user. The <application>xine</application> video player + performs best on XVideo interfaces.</para> + + <para>By default, <application>xine</application> player will + start up in a graphical user interface. The menus can then be + used to open a specific file:</para> + + <screen>&prompt.user; <userinput>xine</userinput></screen> + + <para>Alternatively, it may be invoked to play a file immediately + without the GUI with the command:</para> + + <screen>&prompt.user; <userinput>xine -g -p <replaceable>mymovie.avi</replaceable></userinput></screen> + + </sect3> + + <sect3 id="video-ports-transcode"> + <title>The transcode Utilities</title> + + <para>The software <application>transcode</application> is not a player, but a suite of tools for + re-encoding video and audio files. With <application>transcode</application>, one has the + ability to merge video files, repair broken files, using command + line tools with <filename>stdin/stdout</filename> stream + interfaces.</para> + + <para>A great number of options can be specified during + the build from the <filename + role="package">multimedia/transcode</filename> port, we recommend the + following command line to build + <application>transcode</application>:</para> + + <screen>&prompt.root; <userinput>make WITH_OPTIMIZED_CFLAGS=yes WITH_LIBA52=yes WITH_LAME=yes WITH_OGG=yes \ +WITH_MJPEG=yes -DWITH_XVID=yes</userinput></screen> + + <para>The proposed settings should be sufficient for most users.</para> + + <para>To illustrate <command>transcode</command> capacities, one + example to show how to convert a DivX file into a PAL MPEG-1 + file (PAL VCD):</para> + + <screen>&prompt.user; <userinput>transcode -i <replaceable>input.avi</replaceable> -V --export_prof vcd-pal -o output_vcd</userinput> +&prompt.user; <userinput>mplex -f 1 -o <replaceable>output_vcd.mpg output_vcd.m1v output_vcd.mpa</replaceable></userinput></screen> + + <para>The resulting MPEG file, + <filename><replaceable>output_vcd.mpg</replaceable></filename>, is ready to be played with + <application>MPlayer</application>. You could even burn the + file on a CD-R media to create a Video CD, in this case you will + need to install and use both <filename + role="package">multimedia/vcdimager</filename> and <filename + role="package">sysutils/cdrdao</filename> programs.</para> + + <para>There is a manual page for <command>transcode</command>, but + you should also consult the <ulink + url="http://www.transcoding.org/cgi-bin/transcode">transcode + wiki</ulink> for further information and examples.</para> + </sect3> + + </sect2> + + <sect2 id="video-further-reading"> + <title>Further Reading</title> + + <para>The various video software packages for FreeBSD are + developing rapidly. It is quite possible that in the near + future many of the problems discussed here will have been + resolved. In the mean time, those who + want to get the very most out of FreeBSD's A/V capabilities will + have to cobble together knowledge from several FAQs and tutorials + and use a few different applications. This section exists to + give the reader pointers to such additional information.</para> + + <para>The + <ulink url="http://www.mplayerhq.hu/DOCS/">MPlayer documentation</ulink> + is very technically informative. + These documents should probably be consulted by anyone wishing + to obtain a high level of expertise with &unix; video. The + <application>MPlayer</application> mailing list is hostile to anyone who has not bothered + to read the documentation, so if you plan on making bug reports + to them, RTFM.</para> + + <para>The + <ulink url="http://dvd.sourceforge.net/xine-howto/en_GB/html/howto.html"> xine HOWTO</ulink> + contains a chapter on performance improvement + which is general to all players.</para> + + <para>Finally, there are some other promising applications which + the reader may try:</para> + + <itemizedlist> + + <listitem> + <para><ulink + url="http://avifile.sourceforge.net/">Avifile</ulink> which + is also a port <filename + role='package'>multimedia/avifile</filename>.</para> + </listitem> + + <listitem> + <para><ulink + url="http://www.dtek.chalmers.se/groups/dvd/">Ogle</ulink> + which is also a port <filename + role='package'>multimedia/ogle</filename>.</para> + </listitem> + + <listitem> + <para><ulink url="http://xtheater.sourceforge.net/">Xtheater</ulink></para> + </listitem> + + <listitem> + <para><filename + role="package">multimedia/dvdauthor</filename>, an open + source package for authoring DVD content.</para> + </listitem> + + </itemizedlist> + + </sect2> + </sect1> + + <sect1 id="tvcard"> + <sect1info> + <authorgroup> + <author> + <firstname>Josef</firstname> + <surname>El-Rayes</surname> + <contrib>Original contribution by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + <contrib>Enhanced and adapted by </contrib> + <!-- 02 January 2004 --> + </author> + </authorgroup> + </sect1info> + + <title>Setting Up TV Cards</title> + <indexterm> + <primary>TV cards</primary> + </indexterm> + + <sect2> + <title>Introduction</title> + + <para>TV cards allow you to watch broadcast or cable TV on your + computer. Most of them accept composite video via an RCA or + S-video input and some of these cards come with a FM + radio tuner.</para> + + <para>&os; provides support for PCI-based TV cards using a + Brooktree Bt848/849/878/879 or a Conexant CN-878/Fusion 878a + Video Capture Chip with the &man.bktr.4; driver. You must + also ensure the board comes with a supported tuner, consult + the &man.bktr.4; manual page for a list of supported + tuners.</para> + </sect2> + + <sect2> + <title>Adding the Driver</title> + + <para>To use your card, you will need to load the &man.bktr.4; + driver, this can be done by adding the following line to the + <filename>/boot/loader.conf</filename> file like this:</para> + + <programlisting>bktr_load="YES"</programlisting> + + <para>Alternatively, you may statically compile the support for + the TV card in your kernel, in that case add the following + lines to your kernel configuration:</para> + + <programlisting>device bktr +device iicbus +device iicbb +device smbus</programlisting> + + <para>These additional device drivers are necessary because of the + card components being interconnected via an I2C bus. Then build + and install a new kernel.</para> + + <para>Once the support was added to your system, you have to + reboot your machine. During the boot process, your TV card + should show up, like this:</para> + + <programlisting>bktr0: <BrookTree 848A> mem 0xd7000000-0xd7000fff irq 10 at device 10.0 on pci0 +iicbb0: <I2C bit-banging driver> on bti2c0 +iicbus0: <Philips I2C bus> on iicbb0 master-only +iicbus1: <Philips I2C bus> on iicbb0 master-only +smbus0: <System Management Bus> on bti2c0 +bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> + + <para>Of course these messages can differ according to your + hardware. However you should check if the tuner is correctly + detected; it is still possible to override some of the + detected parameters with &man.sysctl.8; MIBs and kernel + configuration file options. For example, if you want to force + the tuner to a Philips SECAM tuner, you should add the + following line to your kernel configuration file:</para> + + <programlisting>options OVERRIDE_TUNER=6</programlisting> + + <para>or you can directly use &man.sysctl.8;:</para> + + <screen>&prompt.root; <userinput>sysctl hw.bt848.tuner=6</userinput></screen> + + <para>See the &man.bktr.4; manual page and the + <filename>/usr/src/sys/conf/NOTES</filename> file for more + details on the available options.</para> + </sect2> + + <sect2> + <title>Useful Applications</title> + + <para>To use your TV card you need to install one of the + following applications:</para> + + <itemizedlist> + <listitem> + <para><filename role="package">multimedia/fxtv</filename> + provides TV-in-a-window and image/audio/video capture + capabilities.</para> + </listitem> + <listitem> + <para><filename role="package">multimedia/xawtv</filename> + is also a TV application, with the same features as + <application>fxtv</application>.</para> + </listitem> + <listitem> + <para><filename role="package">misc/alevt</filename> decodes + and displays Videotext/Teletext.</para> + </listitem> + <listitem> + <para><filename role="package">audio/xmradio</filename>, an + application to use the FM radio tuner coming with some + TV cards.</para> + </listitem> + <listitem> + <para><filename role="package">audio/wmtune</filename>, a handy + desktop application for radio tuners.</para> + </listitem> + </itemizedlist> + + <para>More applications are available in the &os; Ports + Collection.</para> + </sect2> + + <sect2> + <title>Troubleshooting</title> + + <para>If you encounter any problem with your TV card, you should + check at first if the video capture chip and the tuner are + really supported by the &man.bktr.4; driver and if you used the right + configuration options. For more support and various questions + about your TV card you may want to contact and use the + archives of the &a.multimedia.name; mailing list.</para> + </sect2> + </sect1> + + <sect1 id="mythtv"> + <title>MythTV</title> + + <para>MythTV is an open source <acronym + role="Personal Video Recorder">PVR</acronym> software + project.</para> + + <para>It is well-known in the &linux; world as a complex + application with many dependencies, and therefore difficult to + install. The &os; ports system simplifies much of the process, but + some components must be set up manually. This section is intended + to help and guide in setting up MythTV.</para> + + <sect2> + <title>Hardware</title> + + <para>MythTV is designed to utilise <acronym + role="Video for Linux">V4L</acronym> to access video input devices + such as encoders and tuners. At this time, MythTV works best with + <acronym role="Universal Serial Bus">USB</acronym> DVB-S/C/T cards + supported by <filename + role="package">multimedia/webcamd</filename> because + <application>webcamd</application> provides a <acronym + role="Video for Linux">V4L</acronym> userland application. Any + <acronym role="Digital Video Broadcasting">DVB</acronym> card + supported by <application>webcamd</application> should work with + MythTV, but a list of known working cards can be found <ulink + url="http://wiki.freebsd.org/WebcamCompat">here</ulink>. There + are also drivers available for Hauppauge cards in the following + packages: <filename role="package">multimedia/pvr250</filename> + and <filename role="package">multimedia/pvrxxx</filename>, but + they provide a non-standard driver interface that does not work + with versions of MythTV greater than 0.23.</para> + + <para><ulink url="http://wiki.freebsd.org/HTPC">HTPC</ulink> + contains a list of all available <acronym + role="Digital Video Broadcasting">DVB</acronym> drivers.</para> + </sect2> + + <sect2> + <title>Dependencies</title> + + <para>Being flexible and modular, MythTV allows the user to have the + frontend and backend on different machines.</para> + + <para>For the frontend, <filename + role="package">multimedia/mythtv-frontend</filename> is required, + as well as an X server, which can be found in <filename + role="package">x11/xorg</filename>. Ideally, the frontend + computer also has a video card that supports <acronym + role="X-Video Motion Compensation">XvMC</acronym> and, + optionally, a <acronym + role="Linux Infrared Remote Control">LIRC</acronym>-compatible + remote.</para> + + <para>For the backend, <filename + role="package">multimedia/mythtv</filename> is required, as well + as a &mysql; database, and optionally a tuner and storage for + recordings. The &mysql; package should be automatically installed + as a dependency when installing <filename + role="package">multimedia/mythtv</filename>.</para> + </sect2> + + <sect2> + <title>Setting up MythTV</title> + + <para>To install MythTV, use the following steps. First, install + MythTV from the &os; Ports collection:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/multimedia/mythtv</userinput> +&prompt.root; <userinput>make install</userinput></screen> + + <para>Set up the MythTV database:</para> + + <screen>&prompt.root; <userinput>mysql -uroot -p < /usr/local/share/mythtv/database/mc.sql</userinput></screen> + + <para>Configure the backend:</para> + + <screen>&prompt.root; <userinput>mythtv-setup</userinput></screen> + + <para>Start the backend:</para> + + <screen>&prompt.root; <userinput>echo 'mythbackend_enable="YES"' >> /etc/rc.conf</userinput> +&prompt.root; <userinput>/usr/local/etc/rc.d/mythbackend start</userinput></screen> + </sect2> + </sect1> + + <sect1 id="scanners"> + <sect1info> + <authorgroup> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + <contrib>Written by </contrib> + <!-- 04 August 2004 --> + </author> + </authorgroup> + </sect1info> + + <title>Image Scanners</title> + <indexterm> + <primary>image scanners</primary> + </indexterm> + + <sect2> + <title>Introduction</title> + + <para>In &os;, access to image scanners is provided + by the <application>SANE</application> (Scanner Access Now + Easy) <acronym role="Application Programming + Interface">API</acronym> available through the &os; Ports + Collection. <application>SANE</application> will also use + some &os; device drivers to access to the scanner + hardware.</para> + + <para>&os; supports both SCSI and USB scanners. Be sure your + scanner is supported by <application>SANE</application> prior + to performing any configuration. + <application>SANE</application> has a <ulink + url="http://www.sane-project.org/sane-supported-devices.html">supported + devices</ulink> list that can provide you with information + about the support for a scanner and its status. On systems + prior to &os; 8.X the + &man.uscanner.4; manual page also provides a list of supported + USB scanners.</para> + </sect2> + + <sect2> + <title>Kernel Configuration</title> + + <para>As mentioned above both SCSI and USB interfaces are + supported. According to your scanner interface, different + device drivers are required.</para> + + <sect3 id="scanners-kernel-usb"> + <title>USB Interface</title> + + <para>The <filename>GENERIC</filename> kernel by default + includes the device drivers needed to support USB scanners. + Should you decide to use a custom kernel, be sure that the + following lines are present in your kernel configuration + file:</para> + + <programlisting>device usb +device uhci +device ohci +device ehci</programlisting> + + <para>On systems prior to &os; 8.X, the following line is + also needed:</para> + + <programlisting>device uscanner</programlisting> + + <para>On these versions of &os;, the &man.uscanner.4; device + driver provides support for the USB scanners. Since + &os; 8.0, this support is directly provided by + the &man.libusb.3; library.</para> + + <para>After rebooting with the correct kernel, + plug in your USB scanner. A + line showing the detection of your + scanner should appear in the system message buffer + (&man.dmesg.8;):</para> + + <screen>ugen0.2: <EPSON> at usbus0</screen> + + <para>or on a &os; 7.X system:</para> + + <screen>uscanner0: EPSON EPSON Scanner, rev 1.10/3.02, addr 2</screen> + + <para>These messages show that our scanner is using + either <filename>/dev/ugen0.2</filename> or + <filename>/dev/uscanner0</filename> as device node according + to the &os; version we run. For this example, a + &epson.perfection; 1650 USB scanner was used.</para> + </sect3> + + <sect3> + <title>SCSI Interface</title> + + <para>If your scanner comes with a SCSI interface, it is + important to know which SCSI controller board you will use. + According to the SCSI chipset used, you will have to tune + your kernel configuration file. The + <filename>GENERIC</filename> kernel supports the most common + SCSI controllers. Be sure to read the + <filename>NOTES</filename> file + and add the correct line to your kernel + configuration file. In addition to the SCSI adapter driver, + you need to have the following lines in your kernel + configuration file:</para> + + <programlisting>device scbus +device pass</programlisting> + + <para>Once your kernel has been properly compiled and installed, you should + be able to see the devices in the system message buffer, + when booting:</para> + + <screen>pass2 at aic0 bus 0 target 2 lun 0 +pass2: <AGFA SNAPSCAN 600 1.10> Fixed Scanner SCSI-2 device +pass2: 3.300MB/s transfers</screen> + + <para>If your scanner was not powered-on at system boot, it is + still possible to manually force the detection by performing + a SCSI bus scan with the &man.camcontrol.8; command:</para> + + <screen>&prompt.root; <userinput>camcontrol rescan all</userinput> +Re-scan of bus 0 was successful +Re-scan of bus 1 was successful +Re-scan of bus 2 was successful +Re-scan of bus 3 was successful</screen> + + <para>Then the scanner will appear in the SCSI devices + list:</para> + + <screen>&prompt.root; <userinput>camcontrol devlist</userinput> +<IBM DDRS-34560 S97B> at scbus0 target 5 lun 0 (pass0,da0) +<IBM DDRS-34560 S97B> at scbus0 target 6 lun 0 (pass1,da1) +<AGFA SNAPSCAN 600 1.10> at scbus1 target 2 lun 0 (pass3) +<PHILIPS CDD3610 CD-R/RW 1.00> at scbus2 target 0 lun 0 (pass2,cd0)</screen> + + <para>More details about SCSI devices are available in the + &man.scsi.4; and &man.camcontrol.8; manual pages.</para> + </sect3> + </sect2> + + <sect2> + <title>SANE Configuration</title> + + <para>The <application>SANE</application> system is + split in two parts: the backends (<filename + role="package">graphics/sane-backends</filename>) and the + frontends (<filename + role="package">graphics/sane-frontends</filename>). The + backends part provides access to the scanner itself. The + <application>SANE</application>'s <ulink + url="http://www.sane-project.org/sane-supported-devices.html">supported + devices</ulink> list specifies which backend will support your + image scanner. It is mandatory to determine the correct + backend for your scanner if you want to be able to use your + device. The frontends part provides the graphical scanning + interface (<application>xscanimage</application>).</para> + + <para>The first step is to install the <filename + role="package">graphics/sane-backends</filename> port or + package. Then, use the <command>sane-find-scanner</command> + command to check the scanner detection by the + <application>SANE</application> system:</para> + + <screen>&prompt.root; <userinput>sane-find-scanner -q</userinput> +found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3</screen> + + <para>The output will show the interface type of the scanner and + the device node used to attach the scanner to the system. The + vendor and the product model may not appear, it is not + important.</para> + + <note> + <para>Some USB scanners require you to load a firmware, this + is explained in the backend manual page. You should also read + &man.sane-find-scanner.1; and &man.sane.7; manual + pages.</para> + </note> + + <para>Now we have to check if the scanner will be identified by + a scanning frontend. By default, the + <application>SANE</application> backends comes with a command + line tool called &man.scanimage.1;. This command allows you + to list the devices and to perform an image acquisition from + the command line. The <option>-L</option> option is used to + list the scanner devices:</para> + + <screen>&prompt.root; <userinput>scanimage -L</userinput> +device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner</screen> + + <para>Or, for example with the USB scanner used in the <xref + linkend="scanners-kernel-usb">:</para> + + <screen>&prompt.root; <userinput>scanimage -L</userinput> +device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner</screen> + + <para>This output comes from a &os; 8.X system, the + <literal>'epson2:libusb:/dev/usb:/dev/ugen0.2'</literal> item + gives us the backend name (<literal>epson2</literal>) and the + device node (<literal>/dev/ugen0.2</literal>) used by our + scanner.</para> + + <note> + <para>No output or a message saying that no scanners were + identified indicates that &man.scanimage.1; is unable to + identify the scanner. If this happens, you will need to edit + the backend configuration file and define the scanner device + used. The <filename + class="directory">/usr/local/etc/sane.d/</filename> directory + contains all backend configuration files. This + identification problem does appear with certain USB + scanners.</para> + + <para>For example, with the USB scanner used in the <xref + linkend="scanners-kernel-usb">, under &os; 8.X the + scanner is perfectly detected and working but under prior + versions of &os; (where &man.uscanner.4; driver is used) + <command>sane-find-scanner</command> gives us the following + information:</para> + + <screen>&prompt.root; <userinput>sane-find-scanner -q</userinput> +found USB scanner (UNKNOWN vendor and product) at device /dev/uscanner0</screen> + <para>The scanner is correctly detected, it uses the USB + interface and is attached to the + <filename>/dev/uscanner0</filename> device node. We can now + check if the scanner is correctly identified:</para> + + <screen>&prompt.root; <userinput>scanimage -L</userinput> + +No scanners were identified. If you were expecting something different, +check that the scanner is plugged in, turned on and detected by the +sane-find-scanner tool (if appropriate). Please read the documentation +which came with this software (README, FAQ, manpages).</screen> + + <para>Since the scanner is not identified, we will need to edit + the <filename>/usr/local/etc/sane.d/epson2.conf</filename> + file. The scanner model used was the &epson.perfection; 1650, + so we know the scanner will use the <literal>epson2</literal> + backend. Be sure to read the help comments in the backends + configuration files. Line changes are quite simple: comment + out all lines that have the wrong interface for your scanner + (in our case, we will comment out all lines starting with the + word <literal>scsi</literal> as our scanner uses the USB + interface), then add at the end of the file a line specifying + the interface and the device node used. In this case, we add + the following line:</para> + + <programlisting>usb /dev/uscanner0</programlisting> + + <para>Please be sure to read the comments provided in the + backend configuration file as well as the backend manual page + for more details and correct syntax to use. We can now verify + if the scanner is identified:</para> + + <screen>&prompt.root; <userinput>scanimage -L</userinput> +device `epson:/dev/uscanner0' is a Epson GT-8200 flatbed scanner</screen> + + <para>Our USB scanner has been identified. It is not important + if the brand and the model do not match the scanner. The key item to be + concerned with is the + <literal>`epson:/dev/uscanner0'</literal> field, which give us + the right backend name and the right device node.</para> + </note> + + <para>Once the <command>scanimage -L</command> command is able + to see the scanner, the configuration is complete. The device + is now ready to scan.</para> + + <para>While &man.scanimage.1; does allow us to perform an + image acquisition from the command line, it is preferable to + use a graphical user interface to perform image scanning. + <application>SANE</application> offers a simple but efficient + graphical interface: <application>xscanimage</application> + (<filename + role="package">graphics/sane-frontends</filename>).</para> + + <para><application>Xsane</application> (<filename + role="package">graphics/xsane</filename>) is another popular + graphical scanning frontend. This frontend offers advanced + features such as various scanning mode (photocopy, fax, etc.), + color correction, batch scans, etc. Both of these applications + are usable as a <application>GIMP</application> + plugin.</para> + </sect2> + + <sect2> + <title>Giving Other Users Access to the Scanner</title> + + <para>All previous operations have been done with + <username>root</username> privileges. You may however, need + other users to have access + to the scanner. The user will need read and write + permissions to the device node used by the scanner. As an + example, our USB scanner uses the device node + <filename>/dev/ugen0.2</filename> which is in fact just a + symlink to the real device node called + <filename>/dev/usb/0.2.0</filename> (a quick look at the + contents of the <filename class="directory">/dev</filename> + directory will confirm it). Both, the symlink and the + device node, are owned respectively by the + <groupname>wheel</groupname> and the + <groupname>operator</groupname> groups. Adding the user + <username><replaceable>joe</replaceable></username> to these + groups will allow him to use + the scanner but, for obvious security reasons, you should + think twice before adding a user to any group, especially the + <groupname>wheel</groupname> group. A better solution would + be creating a specific group for using the USB devices + and make the scanner device accessible to members of this + group.</para> + + <para>So we will use, for example, a group called + <groupname><replaceable>usb</replaceable></groupname>. The + first step is the creation of this group with the help of the + &man.pw.8; command:</para> + + <screen>&prompt.root; <userinput>pw groupadd usb</userinput></screen> + + <para>Then we have to make the <filename>/dev/ugen0.2</filename> + symlink and the <filename>/dev/usb/0.2.0</filename> device node accessible to the <groupname>usb</groupname> group + with the correct write permissions (<literal>0660</literal> or + <literal>0664</literal>), because by default only the owner of + these files (<username>root</username>) can write to them. + All of this is done by adding the following + lines to the <filename>/etc/devfs.rules</filename> file:</para> + + <programlisting>[system=5] +add path ugen0.2 mode 0660 group usb +add path usb/0.2.0 mode 0666 group usb</programlisting> + + <para>&os; 7.X users will probably need the following lines with the + correct device node <filename>/dev/uscanner0</filename>:</para> + + <programlisting>[system=5] +add path uscanner0 mode 660 group usb</programlisting> + + <para>Then add the following to + <filename>/etc/rc.conf</filename> and reboot the + machine:</para> + + <programlisting>devfs_system_ruleset="system"</programlisting> + + <para>More information regarding these lines can be found in the + &man.devfs.8; manual page.</para> + + <para>Now, one will just have to add users to the + <groupname><replaceable>usb</replaceable></groupname> group to + allow the access to the scanner:</para> + + <screen>&prompt.root; <userinput>pw groupmod usb -m <replaceable>joe</replaceable></userinput></screen> + + <para>For more details read the &man.pw.8; manual page.</para> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/network-servers/Makefile b/en_US.ISO8859-1/books/handbook/network-servers/Makefile new file mode 100644 index 0000000000..150dbe3121 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/network-servers/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= network-servers/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml b/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml new file mode 100644 index 0000000000..937d54c70b --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/network-servers/chapter.sgml @@ -0,0 +1,5917 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="network-servers"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + <contrib>Reorganized by </contrib> + </author> + </authorgroup> + <!-- 23 July 2004 --> + </chapterinfo> + + <title>Network Servers</title> + + <sect1 id="network-servers-synopsis"> + <title>Synopsis</title> + + <para>This chapter will cover some of the more frequently used + network services on &unix; systems. We will cover how to + install, configure, test, and maintain many different types of + network services. Example configuration files are included + throughout this chapter for you to benefit from.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + + <listitem> + <para>How to manage the <application>inetd</application> + daemon.</para> + </listitem> + + <listitem> + <para>How to set up a network file system.</para> + </listitem> + + <listitem> + <para>How to set up a network information server for sharing + user accounts.</para> + </listitem> + + <listitem> + <para>How to set up automatic network settings using + DHCP.</para> + </listitem> + + <listitem> + <para>How to set up a domain name server.</para> + </listitem> + + <listitem> + <para>How to set up the <application>Apache</application> + HTTP Server.</para> + </listitem> + + <listitem> + <para>How to set up a File Transfer Protocol (FTP) + Server.</para> + </listitem> + + <listitem> + <para>How to set up a file and print server for &windows; + clients using <application>Samba</application>.</para> + </listitem> + + <listitem> + <para>How to synchronize the time and date, and set up a + time server, with the NTP protocol.</para> + </listitem> + + <listitem> + <para>How to configure the standard logging daemon, + <command>syslogd</command>, to accept logs from remote + hosts.</para> + </listitem> + + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand the basics of the + <filename>/etc/rc</filename> scripts.</para> + </listitem> + + <listitem> + <para>Be familiar with basic network terminology.</para> + </listitem> + + <listitem> + <para>Know how to install additional third-party + software (<xref linkend="ports">).</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1 id="network-inetd"> + <sect1info> + <authorgroup> + <author> + <firstname>Chern</firstname> + <surname>Lee</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <contrib>Updated by </contrib> + <othername>The &os; Documentation Project</othername> + </author> + </authorgroup> + </sect1info> + + <title>The <application>inetd</application> + <quote>Super-Server</quote></title> + + <sect2 id="network-inetd-overview"> + <title>Overview</title> + + <para>&man.inetd.8; is sometimes referred to as the + <quote>Internet Super-Server</quote> because it manages + connections for several services. When a connection is + received by <application>inetd</application>, it determines + which program the connection is destined for, spawns the + particular process and delegates the socket to it (the program + is invoked with the service socket as its standard input, + output and error descriptors). Running + <application>inetd</application> for servers that are not + heavily used can reduce the overall system load, when compared + to running each daemon individually in stand-alone + mode.</para> + + <para>Primarily, <application>inetd</application> is used to + spawn other daemons, but several trivial protocols are handled + directly, such as <application>chargen</application>, + <application>auth</application>, and + <application>daytime</application>.</para> + + <para>This section will cover the basics in configuring + <application>inetd</application> through its command-line + options and its configuration file, + <filename>/etc/inetd.conf</filename>.</para> + </sect2> + + <sect2 id="network-inetd-settings"> + <title>Settings</title> + + <para><application>inetd</application> is initialized through + the &man.rc.8; system. The + <literal>inetd_enable</literal> option is set to + <literal>NO</literal> by default, but may be turned on + by <application>sysinstall</application> during installation, + depending on the configuration chosen by the user. + Placing:</para> + + <programlisting>inetd_enable="YES"</programlisting> + + <para>or</para> + + <programlisting>inetd_enable="NO"</programlisting> + + <para>into + <filename>/etc/rc.conf</filename> will enable or disable + <application>inetd</application> starting at boot time. + The command:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/inetd rcvar</userinput></screen> + + <para> + can be run to display the current effective setting.</para> + + <para>Additionally, different command-line options can be passed + to <application>inetd</application> via the + <literal>inetd_flags</literal> option.</para> + </sect2> + + <sect2 id="network-inetd-cmdline"> + <title>Command-Line Options</title> + + <para>Like most server daemons, <application>inetd</application> + has a number of options that it can be passed in order to + modify its behaviour. See the &man.inetd.8; manual page for + the full list of options.</para> + + <para>Options can be passed to <application>inetd</application> + using the <literal>inetd_flags</literal> option in + <filename>/etc/rc.conf</filename>. By default, + <literal>inetd_flags</literal> is set to + <literal>-wW -C 60</literal>, which turns on TCP wrapping for + <application>inetd</application>'s services, and prevents any + single IP address from requesting any service more than 60 + times in any given minute.</para> + + <para>Although we mention rate-limiting options below, novice + users may be pleased to note that these parameters usually do + not need to be modified. These options may be useful should + you find that you are receiving an excessive amount of + connections. A full list of options can be found in the + &man.inetd.8; manual.</para> + + <variablelist> + <varlistentry> + <term>-c maximum</term> + + <listitem> + <para>Specify the default maximum number of simultaneous + invocations of each service; the default is unlimited. + May be overridden on a per-service basis with the + <option>max-child</option> parameter.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-C rate</term> + + <listitem> + <para>Specify the default maximum number of times a + service can be invoked from a single IP address in one + minute; the default is unlimited. May be overridden on + a per-service basis with the + <option>max-connections-per-ip-per-minute</option> + parameter.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-R rate</term> + + <listitem> + <para>Specify the maximum number of times a service can be + invoked in one minute; the default is 256. A rate of 0 + allows an unlimited number of invocations.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-s maximum</term> + + <listitem> + <para>Specify the maximum number of times a service can be + invoked from a single IP address at any one time; the + default is unlimited. May be overridden on a + per-service basis with the + <option>max-child-per-ip</option> parameter.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="network-inetd-conf"> + <!-- XXX This section isn't very clear, and could do with some lovin' --> + <title><filename>inetd.conf</filename></title> + + <para>Configuration of <application>inetd</application> is + done via the file <filename>/etc/inetd.conf</filename>.</para> + + <para>When a modification is made to + <filename>/etc/inetd.conf</filename>, + <application>inetd</application> can be forced to re-read its + configuration file by running the command:</para> + + <example id="network-inetd-reread"> + <title>Reloading the <application>inetd</application> + Configuration File</title> + + <screen>&prompt.root; <userinput>/etc/rc.d/inetd reload</userinput></screen> + </example> + + <para>Each line of the configuration file specifies an + individual daemon. Comments in the file are preceded by a + <quote>#</quote>. The format of each entry in + <filename>/etc/inetd.conf</filename> is as follows:</para> + + <programlisting>service-name +socket-type +protocol +{wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]] +user[:group][/login-class] +server-program +server-program-arguments</programlisting> + + <para>An example entry for the &man.ftpd.8; daemon + using IPv4 might read:</para> + + <programlisting>ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l</programlisting> + + <variablelist> + <varlistentry> + <term>service-name</term> + + <listitem> + <para>This is the service name of the particular daemon. + It must correspond to a service listed in + <filename>/etc/services</filename>. This determines + which port <application>inetd</application> must listen + to. If a new service is being created, it must be + placed in <filename>/etc/services</filename> + first.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>socket-type</term> + + <listitem> + <para>Either <literal>stream</literal>, + <literal>dgram</literal>, <literal>raw</literal>, or + <literal>seqpacket</literal>. <literal>stream</literal> + must be used for connection-based, TCP daemons, while + <literal>dgram</literal> is used for daemons utilizing + the <acronym>UDP</acronym> transport protocol.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>protocol</term> + + <listitem> + <para>One of the following:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Protocol</entry> + <entry>Explanation</entry> + </row> + </thead> + <tbody> + <row> + <entry>tcp, tcp4</entry> + <entry>TCP IPv4</entry> + </row> + <row> + <entry>udp, udp4</entry> + <entry>UDP IPv4</entry> + </row> + <row> + <entry>tcp6</entry> + <entry>TCP IPv6</entry> + </row> + <row> + <entry>udp6</entry> + <entry>UDP IPv6</entry> + </row> + <row> + <entry>tcp46</entry> + <entry>Both TCP IPv4 and v6</entry> + </row> + <row> + <entry>udp46</entry> + <entry>Both UDP IPv4 and v6</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </listitem> + </varlistentry> + + <varlistentry> + <term>{wait|nowait}[/max-child[/max-connections-per-ip-per-minute[/max-child-per-ip]]]</term> + + <listitem> + <para><option>wait|nowait</option> indicates whether the + daemon invoked from <application>inetd</application> is + able to handle its own socket or not. + <option>dgram</option> socket types must use the + <option>wait</option> option, while stream socket + daemons, which are usually multi-threaded, should use + <option>nowait</option>. <option>wait</option> usually + hands off multiple sockets to a single daemon, while + <option>nowait</option> spawns a child daemon for each + new socket.</para> + + <para>The maximum number of child daemons + <application>inetd</application> may spawn can be set + using the <option>max-child</option> option. If a limit + of ten instances of a particular daemon is needed, a + <literal>/10</literal> would be placed after + <option>nowait</option>. Specifying + <literal>/0</literal> allows an unlimited number of + children</para> + + <para>In addition to <option>max-child</option>, two other + options which limit the maximum connections from a + single place to a particular daemon can be enabled. + <option>max-connections-per-ip-per-minute</option> + limits the number of connections from any particular IP + address per minutes, e.g., a value of ten would limit + any particular IP address connecting to a particular + service to ten attempts per minute. + <option>max-child-per-ip</option> limits the number of + children that can be started on behalf on any single IP + address at any moment. These options are useful to + prevent intentional or unintentional excessive resource + consumption and Denial of Service (DoS) attacks to a + machine.</para> + + <para>In this field, either of <option>wait</option> or + <option>nowait</option> is mandatory. + <option>max-child</option>, + <option>max-connections-per-ip-per-minute</option> and + <option>max-child-per-ip</option> are + optional.</para> + + <para>A stream-type multi-threaded daemon without any + <option>max-child</option>, + <option>max-connections-per-ip-per-minute</option> or + <option>max-child-per-ip</option> limits + would simply be: <literal>nowait</literal>.</para> + + <para>The same daemon with a maximum limit of ten daemons + would read: <literal>nowait/10</literal>.</para> + + <para>The same setup with a limit of twenty + connections per IP address per minute and a maximum + total limit of ten child daemons would read: + <literal>nowait/10/20</literal>.</para> + + <para>These options are utilized by the default + settings of the &man.fingerd.8; daemon, + as seen here:</para> + + <programlisting>finger stream tcp nowait/3/10 nobody /usr/libexec/fingerd fingerd -s</programlisting> + + <para>Finally, an example of this field with a maximum of + 100 children in total, with a maximum of 5 for any one + IP address would read: + <literal>nowait/100/0/5</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>user</term> + + <listitem> + <para>This is the username that the particular daemon + should run as. Most commonly, daemons run as the + <username>root</username> user. For security purposes, + it is common to find some servers running as the + <username>daemon</username> user, or the least + privileged <username>nobody</username> user.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>server-program</term> + + <listitem> + <para>The full path of the daemon to be executed when a + connection is received. If the daemon is a service + provided by <application>inetd</application> internally, + then <option>internal</option> should be + used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>server-program-arguments</term> + + <listitem> + <para>This works in conjunction with + <option>server-program</option> by specifying the + arguments, starting with <literal>argv[0]</literal>, + passed to the daemon on invocation. If + <command>mydaemon -d</command> is the command line, + <literal>mydaemon -d</literal> would be the value of + <option>server-program-arguments</option>. Again, if + the daemon is an internal service, use + <option>internal</option> here.</para> + </listitem> + </varlistentry> + </variablelist> + </sect2> + + <sect2 id="network-inetd-security"> + <title>Security</title> + + <para>Depending on the choices made at install time, many + of <application>inetd</application>'s services may be enabled + by default. If there is no apparent need for a particular + daemon, consider disabling it. Place a <quote>#</quote> in + front of the daemon in question in + <filename>/etc/inetd.conf</filename>, and then <link + linkend="network-inetd-reread">reload the + inetd configuration</link>. Some daemons, such as + <application>fingerd</application>, may not be desired at all + because they provide + information that may be useful to an attacker.</para> + + <para>Some daemons are not security-conscious and have long, or + non-existent, timeouts for connection attempts. This allows + an attacker to slowly send connections to a particular daemon, + thus saturating available resources. It may be a good idea to + place <option>max-connections-per-ip-per-minute</option>, + <option>max-child</option> or + <option>max-child-per-ip</option> limitations on certain + daemons if you find that you have too many connections.</para> + + <para>By default, TCP wrapping is turned on. Consult the + &man.hosts.access.5; manual page for more information on + placing TCP restrictions on various + <application>inetd</application> invoked daemons.</para> + </sect2> + + <sect2 id="network-inetd-misc"> + <title>Miscellaneous</title> + + <para><application>daytime</application>, + <application>time</application>, + <application>echo</application>, + <application>discard</application>, + <application>chargen</application>, and + <application>auth</application> are all internally provided + services of <application>inetd</application>.</para> + + <para>The <application>auth</application> service provides + identity + network services, and is + configurable to a certain degree, whilst the others are simply + on or off.</para> + + <para>Consult the &man.inetd.8; manual page for more in-depth + information.</para> + </sect2> + </sect1> + + <sect1 id="network-nfs"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Reorganized and enhanced by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Bill</firstname> + <surname>Swingle</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Network File System (NFS)</title> + + <indexterm><primary>NFS</primary></indexterm> + <para>Among the many different file systems that FreeBSD supports + is the Network File System, also known as <acronym role="Network + File System">NFS</acronym>. <acronym role="Network File + System">NFS</acronym> allows a system to share directories and + files with others over a network. By using <acronym + role="Network File System">NFS</acronym>, users and programs can + access files on remote systems almost as if they were local + files.</para> + + <para>Some of the most notable benefits that + <acronym>NFS</acronym> can provide are:</para> + + <itemizedlist> + <listitem> + <para>Local workstations use less disk space because commonly + used data can be stored on a single machine and still remain + accessible to others over the network.</para> + </listitem> + + <listitem> + <para>There is no need for users to have separate home + directories on every network machine. Home directories + could be set up on the <acronym>NFS</acronym> server and + made available throughout the network.</para> + </listitem> + + <listitem> + <para>Storage devices such as floppy disks, CDROM drives, and + &iomegazip; drives can be used by other machines on the + network. This may reduce the number of removable media + drives throughout the network.</para> + </listitem> + </itemizedlist> + + <sect2> + <title>How <acronym>NFS</acronym> Works</title> + + <para><acronym>NFS</acronym> consists of at least two main + parts: a server and one or more clients. The client remotely + accesses the data that is stored on the server machine. In + order for this to function properly a few processes have to be + configured and running.</para> + + <para>The server has to be running the following daemons:</para> + <indexterm> + <primary>NFS</primary> + <secondary>server</secondary> + </indexterm> + <indexterm> + <primary>file server</primary> + <secondary>UNIX clients</secondary> + </indexterm> + + <indexterm> + <primary><application>rpcbind</application></primary> + </indexterm> + <indexterm> + <primary><application>mountd</application></primary> + </indexterm> + <indexterm> + <primary><application>nfsd</application></primary> + </indexterm> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"> + <colspec colwidth="3*"> + + <thead> + <row> + <entry>Daemon</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><application>nfsd</application></entry> + <entry>The <acronym>NFS</acronym> daemon which services + requests from the <acronym>NFS</acronym> + clients.</entry> + </row> + <row> + <entry><application>mountd</application></entry> + <entry>The <acronym>NFS</acronym> mount daemon which + carries out the requests that &man.nfsd.8; passes on + to it.</entry> + </row> + <row> + <entry><application>rpcbind</application></entry> + <entry> This daemon allows + <acronym>NFS</acronym> clients to discover which port + the <acronym>NFS</acronym> server is using.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>The client can also run a daemon, known as + <application>nfsiod</application>. The + <application>nfsiod</application> daemon services the requests + from the <acronym>NFS</acronym> server. This is optional, and + improves performance, but is not required for normal and + correct operation. See the &man.nfsiod.8; manual page for + more information.</para> + </sect2> + + <sect2 id="network-configuring-nfs"> + <title>Configuring <acronym>NFS</acronym></title> + <indexterm> + <primary>NFS</primary> + <secondary>configuration</secondary> + </indexterm> + + <para><acronym>NFS</acronym> configuration is a relatively + straightforward process. The processes that need to be + running can all start at boot time with a few modifications to + your <filename>/etc/rc.conf</filename> file.</para> + + <para>On the <acronym>NFS</acronym> server, make sure that the + following options are configured in the + <filename>/etc/rc.conf</filename> file:</para> + + <programlisting>rpcbind_enable="YES" +nfs_server_enable="YES" +mountd_flags="-r"</programlisting> + + <para><application>mountd</application> runs automatically + whenever the <acronym>NFS</acronym> server is enabled.</para> + + <para>On the client, make sure this option is present in + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>nfs_client_enable="YES"</programlisting> + + <para>The <filename>/etc/exports</filename> file specifies which + file systems <acronym>NFS</acronym> should export (sometimes + referred to as <quote>share</quote>). Each line in + <filename>/etc/exports</filename> specifies a file system to + be exported and which machines have access to that file + system. Along with what machines have access to that file + system, access options may also be specified. There are many + such options that can be used in this file but only a few will + be mentioned here. You can easily discover other options by + reading over the &man.exports.5; manual page.</para> + + <para>Here are a few example <filename>/etc/exports</filename> + entries:</para> + + <indexterm> + <primary>NFS</primary> + <secondary>export examples</secondary> + </indexterm> + + <para>The following examples give an idea of how to export + file systems, although the settings may be different depending + on your environment and network configuration. For instance, + to export the <filename>/cdrom</filename> directory to three + example machines that have the same domain name as the server + (hence the lack of a domain name for each) or have entries in + your <filename>/etc/hosts</filename> file. The + <option>-ro</option> flag makes the exported file system + read-only. With this flag, the remote system will not be able + to write any changes to the exported file system.</para> + + <programlisting>/cdrom -ro host1 host2 host3</programlisting> + + <para>The following line exports <filename>/home</filename> to + three hosts by IP address. This is a useful setup if you have + a private network without a <acronym>DNS</acronym> server + configured. Optionally the <filename>/etc/hosts</filename> + file could be configured for internal hostnames; please review + &man.hosts.5; for more information. The + <option>-alldirs</option> flag allows the subdirectories to be + mount points. In other words, it will not mount the + subdirectories but permit the client to mount only the + directories that are required or needed.</para> + + <programlisting>/home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4</programlisting> + + <para>The following line exports <filename>/a</filename> so that + two clients from different domains may access the file system. + The <option>-maproot=root</option> flag allows the + <username>root</username> user on the remote system to write + data on the exported file system as <username>root</username>. + If the <literal>-maproot=root</literal> flag is not specified, + then even if a user has <username>root</username> access on + the remote system, he will not be able to modify files on + the exported file system.</para> + + <programlisting>/a -maproot=root host.example.com box.example.org</programlisting> + + <para>In order for a client to access an exported file system, + the client must have permission to do so. Make sure the + client is listed in your <filename>/etc/exports</filename> + file.</para> + + <para>In <filename>/etc/exports</filename>, each line represents + the export information for one file system to one host. A + remote host can only be specified once per file system, and + may only have one default entry. For example, assume that + <filename>/usr</filename> is a single file system. The + following <filename>/etc/exports</filename> would be + invalid:</para> + + <programlisting># Invalid when /usr is one file system +/usr/src client +/usr/ports client</programlisting> + + <para>One file system, <filename>/usr</filename>, has two lines + specifying exports to the same host, <hostid>client</hostid>. + The correct format for this situation is:</para> + + <programlisting>/usr/src /usr/ports client</programlisting> + + <para>The properties of one file system exported to a given host + must all occur on one line. Lines without a client specified + are treated as a single host. This limits how you can export + file systems, but for most people this is not an issue.</para> + + <para>The following is an example of a valid export list, where + <filename>/usr</filename> and <filename>/exports</filename> + are local file systems:</para> + + <programlisting># Export src and ports to client01 and client02, but only +# client01 has root privileges on it +/usr/src /usr/ports -maproot=root client01 +/usr/src /usr/ports client02 +# The client machines have root and can mount anywhere +# on /exports. Anyone in the world can mount /exports/obj read-only +/exports -alldirs -maproot=root client01 client02 +/exports/obj -ro</programlisting> + + <para>The <application>mountd</application> daemon must be + forced to recheck the <filename>/etc/exports</filename> file + whenever it has been modified, so the changes can take effect. + This can be accomplished either by sending a HUP signal to the + running daemon:</para> + + <screen>&prompt.root; <userinput>kill -HUP `cat /var/run/mountd.pid`</userinput></screen> + + <para>or by invoking the <command>mountd</command> &man.rc.8; + script with the appropriate parameter:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/mountd onereload</userinput></screen> + + <para>Please refer to <xref linkend="configtuning-rcd"> for more + information about using rc scripts.</para> + + <para>Alternatively, a reboot will make FreeBSD set everything + up properly. A reboot is not necessary though. + Executing the following commands as <username>root</username> + should start everything up.</para> + + <para>On the <acronym>NFS</acronym> server:</para> + + <screen>&prompt.root; <userinput>rpcbind</userinput> +&prompt.root; <userinput>nfsd -u -t -n 4</userinput> +&prompt.root; <userinput>mountd -r</userinput></screen> + + <para>On the <acronym>NFS</acronym> client:</para> + + <screen>&prompt.root; <userinput>nfsiod -n 4</userinput></screen> + + <para>Now everything should be ready to actually mount a remote + file system. In these examples the server's name will be + <hostid>server</hostid> and the client's name will be + <hostid>client</hostid>. If you only want to temporarily + mount a remote file system or would rather test the + configuration, just execute a command like this as + <username>root</username> on the client:</para> + + <indexterm> + <primary>NFS</primary> + <secondary>mounting</secondary> + </indexterm> + <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen> + + <para>This will mount the <filename>/home</filename> directory + on the server at <filename>/mnt</filename> on the client. If + everything is set up correctly you should be able to enter + <filename>/mnt</filename> on the client and see all the files + that are on the server.</para> + + <para>If you want to automatically mount a remote file system + each time the computer boots, add the file system to the + <filename>/etc/fstab</filename> file. Here is an + example:</para> + + <programlisting>server:/home /mnt nfs rw 0 0</programlisting> + + <para>The &man.fstab.5; manual page lists all the available + options.</para> + </sect2> + + <sect2> + <title>Locking</title> + + <para>Some applications (e.g., <application>mutt</application>) + require file locking to operate correctly. In the case of + <acronym>NFS</acronym>, <application>rpc.lockd</application> + can be used for file locking. To enable it, add the following + to the <filename>/etc/rc.conf</filename> file on both client + and server (it is assumed that the <acronym>NFS</acronym> + client and server are configured already):</para> + + <programlisting>rpc_lockd_enable="YES" +rpc_statd_enable="YES"</programlisting> + + <para>Start the application by using:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/lockd start</userinput> +&prompt.root; <userinput>/etc/rc.d/statd start</userinput></screen> + + <para>If real locking between the <acronym>NFS</acronym> clients + and <acronym>NFS</acronym> server is not required, it is + possible to let the <acronym>NFS</acronym> client do locking + locally by passing <option>-L</option> to &man.mount.nfs.8;. + Refer to the &man.mount.nfs.8; manual page for further + details.</para> + </sect2> + + <sect2> + <title>Practical Uses</title> + + <para><acronym>NFS</acronym> has many practical uses. Some of + the more common ones are listed below:</para> + + <indexterm> + <primary>NFS</primary> + <secondary>uses</secondary> + </indexterm> + <itemizedlist> + <listitem> + <para>Set several machines to share a CDROM or other media + among them. This is cheaper and often a more convenient + method to install software on multiple machines.</para> + </listitem> + + <listitem> + <para>On large networks, it might be more convenient to + configure a central <acronym>NFS</acronym> server in which + to store all the user home directories. These home + directories can then be exported to the network so that + users would always have the same home directory, + regardless of which workstation they log in to.</para> + </listitem> + + <listitem> + <para>Several machines could have a common + <filename>/usr/ports/distfiles</filename> directory. That + way, when you need to install a port on several machines, + you can quickly access the source without downloading it + on each machine.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2 id="network-amd"> + <sect2info> + <authorgroup> + <author> + <firstname>Wylie</firstname> + <surname>Stilwell</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Chern</firstname> + <surname>Lee</surname> + <contrib>Rewritten by </contrib> + </author> + </authorgroup> + </sect2info> + <title>Automatic Mounts with + <application>amd</application></title> + + <indexterm><primary>amd</primary></indexterm> + <indexterm> + <primary>automatic mounter daemon</primary> + </indexterm> + + <para>&man.amd.8; (the automatic mounter daemon) + automatically mounts a + remote file system whenever a file or directory within that + file system is accessed. Filesystems that are inactive for a + period of time will also be automatically unmounted by + <application>amd</application>. Using + <application>amd</application> provides a simple alternative + to permanent mounts, as permanent mounts are usually listed in + <filename>/etc/fstab</filename>.</para> + + <para><application>amd</application> operates by attaching + itself as an NFS server to the <filename>/host</filename> and + <filename>/net</filename> directories. When a file is + accessed within one of these directories, + <application>amd</application> looks up the corresponding + remote mount and automatically mounts it. + <filename>/net</filename> is used to mount an exported file + system from an IP address, while <filename>/host</filename> + is used to mount an export from a remote hostname.</para> + + <para>An access to a file within + <filename>/host/foobar/usr</filename> would tell + <application>amd</application> to attempt to mount the + <filename>/usr</filename> export on the host + <hostid>foobar</hostid>.</para> + + <example> + <title>Mounting an Export with + <application>amd</application></title> + + <para>You can view the available mounts of a remote host with + the <command>showmount</command> command. For example, to + view the mounts of a host named <hostid>foobar</hostid>, you + can use:</para> + + <screen>&prompt.user; <userinput>showmount -e foobar</userinput> +Exports list on foobar: +/usr 10.10.10.0 +/a 10.10.10.0 +&prompt.user; <userinput>cd /host/foobar/usr</userinput></screen> + </example> + + <para>As seen in the example, the <command>showmount</command> + shows <filename>/usr</filename> as an export. When changing + directories to <filename>/host/foobar/usr</filename>, + <application>amd</application> attempts to resolve the + hostname <hostid>foobar</hostid> and automatically mount the + desired export.</para> + + <para><application>amd</application> can be started by the + startup scripts by placing the following lines in + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>amd_enable="YES"</programlisting> + + <para>Additionally, custom flags can be passed to + <application>amd</application> from the + <varname>amd_flags</varname> option. By default, + <varname>amd_flags</varname> is set to:</para> + + <programlisting>amd_flags="-a /.amd_mnt -l syslog /host /etc/amd.map /net /etc/amd.map"</programlisting> + + <para>The <filename>/etc/amd.map</filename> file defines the + default options that exports are mounted with. The + <filename>/etc/amd.conf</filename> file defines some of the + more advanced features of + <application>amd</application>.</para> + + <para>Consult the &man.amd.8; and &man.amd.conf.5; manual pages + for more information.</para> + </sect2> + + <sect2 id="network-nfs-integration"> + <sect2info> + <authorgroup> + <author> + <firstname>John</firstname> + <surname>Lind</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + <title>Problems Integrating with Other Systems</title> + + <para>Certain Ethernet adapters for ISA PC systems have + limitations which can lead to serious network problems, + particularly with NFS. This difficulty is not specific to + FreeBSD, but FreeBSD systems are affected by it.</para> + + <para>The problem nearly always occurs when (FreeBSD) PC systems + are networked with high-performance workstations, such as + those made by Silicon Graphics, Inc., and Sun Microsystems, + Inc. The NFS mount will work fine, and some operations may + succeed, but suddenly the server will seem to become + unresponsive to the client, even though requests to and from + other systems continue to be processed. This happens to the + client system, whether the client is the FreeBSD system or the + workstation. On many systems, there is no way to shut down + the client gracefully once this problem has manifested itself. + The only solution is often to reset the client, because the + NFS situation cannot be resolved.</para> + + <para>Though the <quote>correct</quote> solution is to get a + higher performance and capacity Ethernet adapter for the + FreeBSD system, there is a simple workaround that will allow + satisfactory operation. If the FreeBSD system is the + <emphasis>server</emphasis>, include the option + <option>-w=1024</option> on the mount from the client. If the + FreeBSD system is the <emphasis>client</emphasis>, then mount + the NFS file system with the option <option>-r=1024</option>. + These options may be specified using the fourth field of the + <filename>fstab</filename> entry on the client for automatic + mounts, or by using the <option>-o</option> parameter of the + &man.mount.8; command for manual mounts.</para> + + <para>It should be noted that there is a different problem, + sometimes mistaken for this one, when the NFS servers and + clients are on different networks. If that is the case, make + <emphasis>certain</emphasis> that your routers are routing the + necessary <acronym>UDP</acronym> information, or you will not + get anywhere, no matter what else you are doing.</para> + + <para>In the following examples, <hostid>fastws</hostid> is the + host (interface) name of a high-performance workstation, and + <hostid>freebox</hostid> is the host (interface) name of a + FreeBSD system with a lower-performance Ethernet adapter. + Also, <filename>/sharedfs</filename> will be the exported NFS + file system (see &man.exports.5;), and + <filename>/project</filename> will be the mount point on the + client for the exported file system. In all cases, note that + additional options, such as <option>hard</option> or + <option>soft</option> and <option>bg</option> may be desirable + in your application.</para> + + <para>Examples for the FreeBSD system (<hostid>freebox</hostid>) + as the client in <filename>/etc/fstab</filename> on + <hostid>freebox</hostid>:</para> + + <programlisting>fastws:/sharedfs /project nfs rw,-r=1024 0 0</programlisting> + + <para>As a manual mount command on + <hostid>freebox</hostid>:</para> + + <screen>&prompt.root; <userinput>mount -t nfs -o -r=1024 fastws:/sharedfs /project</userinput></screen> + + <para>Examples for the FreeBSD system as the server in + <filename>/etc/fstab</filename> on + <hostid>fastws</hostid>:</para> + + <programlisting>freebox:/sharedfs /project nfs rw,-w=1024 0 0</programlisting> + + <para>As a manual mount command on + <hostid>fastws</hostid>:</para> + + <screen>&prompt.root; <userinput>mount -t nfs -o -w=1024 freebox:/sharedfs /project</userinput></screen> + + <para>Nearly any 16-bit Ethernet adapter will allow operation + without the above restrictions on the read or write + size.</para> + + <para>For anyone who cares, here is what happens when the + failure occurs, which also explains why it is unrecoverable. + NFS typically works with a <quote>block</quote> size of + 8 K (though it may do fragments of smaller sizes). Since + the maximum Ethernet packet is around 1500 bytes, the NFS + <quote>block</quote> gets split into multiple Ethernet + packets, even though it is still a single unit to the + upper-level code, and must be received, assembled, and + <emphasis>acknowledged</emphasis> as a unit. The + high-performance workstations can pump out the packets which + comprise the NFS unit one right after the other, just as close + together as the standard allows. On the smaller, lower + capacity cards, the later packets overrun the earlier packets + of the same unit before they can be transferred to the host + and the unit as a whole cannot be reconstructed or + acknowledged. As a result, the workstation will time out and + try again, but it will try again with the entire 8 K + unit, and the process will be repeated, ad infinitum.</para> + + <para>By keeping the unit size below the Ethernet packet size + limitation, we ensure that any complete Ethernet packet + received can be acknowledged individually, avoiding the + deadlock situation.</para> + + <para>Overruns may still occur when a high-performance + workstations is slamming data out to a PC system, but with the + better cards, such overruns are not guaranteed on NFS + <quote>units</quote>. When an overrun occurs, the units + affected will be retransmitted, and there will be a fair + chance that they will be received, assembled, and + acknowledged.</para> + </sect2> + </sect1> + + <sect1 id="network-nis"> + <sect1info> + <authorgroup> + <author> + <firstname>Bill</firstname> + <surname>Swingle</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Eric</firstname> + <surname>Ogren</surname> + <contrib>Enhanced by </contrib> + </author> + <author> + <firstname>Udo</firstname> + <surname>Erdelhoff</surname> + </author> + </authorgroup> + </sect1info> + <title>Network Information System (NIS/YP)</title> + + <sect2> + <title>What Is It?</title> + <indexterm><primary>NIS</primary></indexterm> + <indexterm><primary>Solaris</primary></indexterm> + <indexterm><primary>HP-UX</primary></indexterm> + <indexterm><primary>AIX</primary></indexterm> + <indexterm><primary>Linux</primary></indexterm> + <indexterm><primary>NetBSD</primary></indexterm> + <indexterm><primary>OpenBSD</primary></indexterm> + + <para><acronym role="Network Information System">NIS</acronym>, + which stands for Network Information Services, was developed + by Sun Microsystems to centralize administration of &unix; + (originally &sunos;) systems. It has now essentially become + an industry standard; all major &unix; like systems + (&solaris;, HP-UX, &aix;, Linux, NetBSD, OpenBSD, FreeBSD, + etc) support <acronym + role="Network Information System">NIS</acronym>.</para> + + <indexterm> + <primary>yellow pages</primary> + <see>NIS</see> + </indexterm> + + <para><acronym role="Network Information System">NIS</acronym> + was formerly known as Yellow Pages, but because of trademark + issues, Sun changed the name. The old term (and yp) is still + often seen and used.</para> + + <indexterm> + <primary>NIS</primary> + <secondary>domains</secondary> + </indexterm> + + <para>It is a RPC-based client/server system that allows a group + of machines within an NIS domain to share a common set of + configuration files. This permits a system administrator to + set up NIS client systems with only minimal configuration data + and add, remove or modify configuration data from a single + location.</para> + + <indexterm><primary>Windows NT</primary></indexterm> + + <para>It is similar to the &windowsnt; domain system; although + the internal implementation of the two are not at all similar, + the basic functionality can be compared.</para> + </sect2> + + <sect2> + <title>Terms/Processes You Should Know</title> + + <para>There are several terms and several important user + processes that you will come across when attempting to + implement NIS on FreeBSD, whether you are trying to create an + NIS server or act as an NIS client:</para> + + <indexterm> + <primary><application>rpcbind</application></primary> + </indexterm> + <indexterm> + <primary><application>portmap</application></primary> + </indexterm> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"> + <colspec colwidth="3*"> + + <thead> + <row> + <entry>Term</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry>NIS domainname</entry> + + <entry>An NIS master server and all of its clients + (including its slave servers) have a NIS domainname. + Similar to an &windowsnt; domain name, the NIS + domainname does not have anything to do with + <acronym>DNS</acronym>.</entry> + </row> + <row> + <entry><application>rpcbind</application></entry> + + <entry>Must be running in order to enable + <acronym>RPC</acronym> (Remote Procedure Call, a + network protocol used by NIS). If + <application>rpcbind</application> is not running, it + will be impossible to run an NIS server, or to act as + an NIS client.</entry> + </row> + <row> + <entry><application>ypbind</application></entry> + + <entry><quote>Binds</quote> an NIS client to its NIS + server. It will take the NIS domainname from the + system, and using <acronym>RPC</acronym>, connect to + the server. <application>ypbind</application> is the + core of client-server communication in an NIS + environment; if <application>ypbind</application> dies + on a client machine, it will not be able to access the + NIS server.</entry> + </row> + <row> + <entry><application>ypserv</application></entry> + <entry>Should only be running on NIS servers; this is + the NIS server process itself. If &man.ypserv.8; + dies, then the server will no longer be able to + respond to NIS requests (hopefully, there is a slave + server to take over for it). There are some + implementations of NIS (but not the FreeBSD one), that + do not try to reconnect to another server if the + server it used before dies. Often, the only thing + that helps in this case is to restart the server + process (or even the whole server) or the + <application>ypbind</application> process on the + client.</entry> + </row> + <row> + <entry><application>rpc.yppasswdd</application></entry> + <entry>Another process that should only be running on + NIS master servers; this is a daemon that will allow + NIS clients to change their NIS passwords. If this + daemon is not running, users will have to login to the + NIS master server and change their passwords + there.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + <!-- XXX Missing: rpc.ypxfrd (not important, though) May only run + on the master --> + + </sect2> + + <sect2> + <title>How Does It Work?</title> + + <para>There are three types of hosts in an NIS environment: + master servers, slave servers, and clients. Servers act as a + central repository for host configuration information. Master + servers hold the authoritative copy of this information, while + slave servers mirror this information for redundancy. Clients + rely on the servers to provide this information to + them.</para> + + <para>Information in many files can be shared in this manner. + The <filename>master.passwd</filename>, + <filename>group</filename>, and <filename>hosts</filename> + files are commonly shared via NIS. Whenever a process on a + client needs information that would normally be found in these + files locally, it makes a query to the NIS server that it is + bound to instead.</para> + + <sect3> + <title>Machine Types</title> + + <itemizedlist> + <indexterm> + <primary>NIS</primary> + <secondary>master server</secondary> + </indexterm> + <listitem> + <para>A <emphasis>NIS master server</emphasis>. This + server, analogous to a &windowsnt; primary domain + controller, maintains the files used by all of the NIS + clients. The <filename>passwd</filename>, + <filename>group</filename>, and other various files used + by the NIS clients live on the master server.</para> + + <note><para>It is possible for one machine to be an NIS + master server for more than one NIS domain. However, + this will not be covered in this introduction, which + assumes a relatively small-scale NIS + environment.</para></note> + </listitem> + <indexterm> + <primary>NIS</primary> + <secondary>slave server</secondary> + </indexterm> + <listitem> + <para><emphasis>NIS slave servers</emphasis>. Similar to + the &windowsnt; backup domain controllers, NIS slave + servers maintain copies of the NIS master's data files. + NIS slave servers provide the redundancy, which is + needed in important environments. They also help to + balance the load of the master server: NIS Clients + always attach to the NIS server whose response they get + first, and this includes slave-server-replies.</para> + </listitem> + <indexterm> + <primary>NIS</primary> + <secondary>client</secondary> + </indexterm> + <listitem> + <para><emphasis>NIS clients</emphasis>. NIS clients, like + most &windowsnt; workstations, authenticate against the + NIS server (or the &windowsnt; domain controller in the + &windowsnt; workstations case) to log on.</para> + </listitem> + </itemizedlist> + </sect3> + </sect2> + + <sect2> + <title>Using NIS/YP</title> + + <para>This section will deal with setting up a sample NIS + environment.</para> + + <sect3> + <title>Planning</title> + + <para>Let us assume that you are the administrator of a small + university lab. This lab, which consists of 15 FreeBSD + machines, currently has no centralized point of + administration; each machine has its own + <filename>/etc/passwd</filename> and + <filename>/etc/master.passwd</filename>. These files are + kept in sync with each other only through manual + intervention; currently, when you add a user to the lab, you + must run <command>adduser</command> on all 15 machines. + Clearly, this has to change, so you have decided to convert + the lab to use NIS, using two of the machines as + servers.</para> + + <para>Therefore, the configuration of the lab now looks + something like:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>Machine name</entry> + <entry>IP address</entry> + <entry>Machine role</entry> + </row> + </thead> + <tbody> + <row> + <entry><hostid>ellington</hostid></entry> + <entry><hostid role="ipaddr">10.0.0.2</hostid></entry> + <entry>NIS master</entry> + </row> + <row> + <entry><hostid>coltrane</hostid></entry> + <entry><hostid role="ipaddr">10.0.0.3</hostid></entry> + <entry>NIS slave</entry> + </row> + <row> + <entry><hostid>basie</hostid></entry> + <entry><hostid role="ipaddr">10.0.0.4</hostid></entry> + <entry>Faculty workstation</entry> + </row> + <row> + <entry><hostid>bird</hostid></entry> + <entry><hostid role="ipaddr">10.0.0.5</hostid></entry> + <entry>Client machine</entry> + </row> + <row> + <entry><hostid>cli[1-11]</hostid></entry> + <entry> + <hostid role="ipaddr">10.0.0.[6-17]</hostid></entry> + <entry>Other client machines</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>If you are setting up a NIS scheme for the first time, + it is a good idea to think through how you want to go about + it. No matter what the size of your network, there are a + few decisions that need to be made.</para> + + <sect4> + <title>Choosing a NIS Domain Name</title> + + <indexterm> + <primary>NIS</primary> + <secondary>domainname</secondary> + </indexterm> + <para>This might not be the <quote>domainname</quote> that + you are used to. It is more accurately called the + <quote>NIS domainname</quote>. When a client broadcasts + its requests for info, it includes the name of the NIS + domain that it is part of. This is how multiple servers + on one network can tell which server should answer which + request. Think of the NIS domainname as the name for a + group of hosts that are related in some way.</para> + + <para>Some organizations choose to use their Internet + domainname for their NIS domainname. This is not + recommended as it can cause confusion when trying to debug + network problems. The NIS domainname should be unique + within your network and it is helpful if it describes the + group of machines it represents. For example, the Art + department at Acme Inc. might be in the + <quote>acme-art</quote> NIS domain. For this example, + assume you have chosen the name + <literal>test-domain</literal>.</para> + + <indexterm><primary>SunOS</primary></indexterm> + <para>However, some operating systems (notably &sunos;) use + their NIS domain name as their Internet domain name. If + one or more machines on your network have this + restriction, you <emphasis>must</emphasis> use the + Internet domain name as your NIS domain name.</para> + </sect4> + + <sect4> + <title>Physical Server Requirements</title> + + <para>There are several things to keep in mind when choosing + a machine to use as a NIS server. One of the unfortunate + things about NIS is the level of dependency the clients + have on the server. If a client cannot contact the server + for its NIS domain, very often the machine becomes + unusable. The lack of user and group information causes + most systems to temporarily freeze up. With this in mind + you should make sure to choose a machine that will not be + prone to being rebooted regularly, or one that might be + used for development. The NIS server should ideally be a + stand alone machine whose sole purpose in life is to be an + NIS server. If you have a network that is not very + heavily used, it is acceptable to put the NIS server on a + machine running other services, just keep in mind that if + the NIS server becomes unavailable, it will affect + <emphasis>all</emphasis> of your NIS clients + adversely.</para> + </sect4> + </sect3> + + <sect3> + <title>NIS Servers</title> + + <para> The canonical copies of all NIS information are stored + on a single machine called the NIS master server. The + databases used to store the information are called NIS maps. + In FreeBSD, these maps are stored in + <filename>/var/yp/[domainname]</filename> where + <filename>[domainname]</filename> is the name of the NIS + domain being served. A single NIS server can support + several domains at once, therefore it is possible to have + several such directories, one for each supported domain. + Each domain will have its own independent set of + maps.</para> + + <para>NIS master and slave servers handle all NIS requests + with the <command>ypserv</command> daemon. + <command>ypserv</command> is responsible for receiving + incoming requests from NIS clients, translating the + requested domain and map name to a path to the corresponding + database file and transmitting data from the database back + to the client.</para> + + <sect4> + <title>Setting Up a NIS Master Server</title> + <indexterm> + <primary>NIS</primary> + <secondary>server configuration</secondary> + </indexterm> + <para>Setting up a master NIS server can be relatively + straight forward, depending on your needs. FreeBSD comes + with support for NIS out-of-the-box. All you need is to + add the following lines to + <filename>/etc/rc.conf</filename>, and FreeBSD will do the + rest for you.</para> + + <procedure> + <step> + <para><programlisting>nisdomainname="test-domain"</programlisting> + This line will set the NIS domainname to + <literal>test-domain</literal> + upon network setup (e.g., after reboot).</para> + </step> + <step> + <para><programlisting>nis_server_enable="YES"</programlisting> + This will tell FreeBSD to start up the NIS server + processes when the networking is next brought + up.</para> + </step> + <step> + <para><programlisting>nis_yppasswdd_enable="YES"</programlisting> + This will enable the <command>rpc.yppasswdd</command> + daemon which, as mentioned above, will allow users to + change their NIS password from a client + machine.</para> + </step> + </procedure> + + <note> + <para>Depending on your NIS setup, you may need to add + further entries. See the <link + linkend="network-nis-server-is-client">section about + NIS servers that are also NIS clients</link>, below, for + details.</para> + </note> + + <para>After setting up the above entries, run the command + <command>/etc/netstart</command> as superuser. It will + set up everything for you, using the values you defined in + <filename>/etc/rc.conf</filename>. As a last step, before + initializing the NIS maps, start the + <application>ypserv</application> daemon manually:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/ypserv start</userinput></screen> + </sect4> + + <sect4> + <title>Initializing the NIS Maps</title> + <indexterm> + <primary>NIS</primary> + <secondary>maps</secondary> + </indexterm> + <para>The <emphasis>NIS maps</emphasis> are database files, + that are kept in the <filename>/var/yp</filename> + directory. They are generated from configuration files in + the <filename>/etc</filename> directory of the NIS master, + with one exception: the + <filename>/etc/master.passwd</filename> file. This is for + a good reason, you do not want to propagate passwords to + your <username>root</username> and other administrative + accounts to all the servers in the NIS domain. Therefore, + before we initialize the NIS maps, you should:</para> + + <screen>&prompt.root; <userinput>cp /etc/master.passwd /var/yp/master.passwd</userinput> +&prompt.root; <userinput>cd /var/yp</userinput> +&prompt.root; <userinput>vi master.passwd</userinput></screen> + + <para>You should remove all entries regarding system + accounts (<username>bin</username>, + <username>tty</username>, <username>kmem</username>, + <username>games</username>, etc), as well as any accounts + that you do not want to be propagated to the NIS clients + (for example <username>root</username> and any other UID 0 + (superuser) accounts).</para> + + <note><para>Make sure the + <filename>/var/yp/master.passwd</filename> is neither + group nor world readable (mode 600)! Use the + <command>chmod</command> command, if + appropriate.</para></note> + + <indexterm><primary>Tru64 UNIX</primary></indexterm> + + <para>When you have finished, it is time to initialize the + NIS maps! FreeBSD includes a script named + <command>ypinit</command> to do this for you (see its + manual page for more information). Note that this script + is available on most &unix; Operating Systems, but not on + all. On Digital UNIX/Compaq Tru64 UNIX it is called + <command>ypsetup</command>. Because we are generating + maps for an NIS master, we are going to pass the + <option>-m</option> option to <command>ypinit</command>. + To generate the NIS maps, assuming you already performed + the steps above, run:</para> + + <screen>ellington&prompt.root; <userinput>ypinit -m test-domain</userinput> +Server Type: MASTER Domain: test-domain +Creating an YP server will require that you answer a few questions. +Questions will all be asked at the beginning of the procedure. +Do you want this procedure to quit on non-fatal errors? [y/n: n] <userinput>n</userinput> +Ok, please remember to go back and redo manually whatever fails. +If you don't, something might not work. +At this point, we have to construct a list of this domains YP servers. +rod.darktech.org is already known as master server. +Please continue to add any slave servers, one per line. When you are +done with the list, type a <control D>. +master server : ellington +next host to add: <userinput>coltrane</userinput> +next host to add: <userinput>^D</userinput> +The current list of NIS servers looks like this: +ellington +coltrane +Is this correct? [y/n: y] <userinput>y</userinput> + +[..output from map generation..] + +NIS Map update completed. +ellington has been setup as an YP master server without any errors.</screen> + + <para><command>ypinit</command> should have created + <filename>/var/yp/Makefile</filename> from + <filename>/var/yp/Makefile.dist</filename>. + When created, this file assumes that you are operating + in a single server NIS environment with only FreeBSD + machines. Since <literal>test-domain</literal> has + a slave server as well, you must edit + <filename>/var/yp/Makefile</filename>:</para> + + <screen>ellington&prompt.root; <userinput>vi /var/yp/Makefile</userinput></screen> + + <para>You should comment out the line that says</para> + + <programlisting>NOPUSH = "True"</programlisting> + + <para>(if it is not commented out already).</para> + </sect4> + + <sect4> + <title>Setting up a NIS Slave Server</title> + <indexterm> + <primary>NIS</primary> + <secondary>slave server</secondary> + </indexterm> + <para>Setting up an NIS slave server is even more simple + than setting up the master. Log on to the slave server + and edit the file <filename>/etc/rc.conf</filename> as you + did before. The only difference is that we now must use + the <option>-s</option> option when running + <command>ypinit</command>. The <option>-s</option> option + requires the name of the NIS master be passed to it as + well, so our command line looks like:</para> + + <screen>coltrane&prompt.root; <userinput>ypinit -s ellington test-domain</userinput> + +Server Type: SLAVE Domain: test-domain Master: ellington + +Creating an YP server will require that you answer a few questions. +Questions will all be asked at the beginning of the procedure. + +Do you want this procedure to quit on non-fatal errors? [y/n: n] <userinput>n</userinput> + +Ok, please remember to go back and redo manually whatever fails. +If you don't, something might not work. +There will be no further questions. The remainder of the procedure +should take a few minutes, to copy the databases from ellington. +Transferring netgroup... +ypxfr: Exiting: Map successfully transferred +Transferring netgroup.byuser... +ypxfr: Exiting: Map successfully transferred +Transferring netgroup.byhost... +ypxfr: Exiting: Map successfully transferred +Transferring master.passwd.byuid... +ypxfr: Exiting: Map successfully transferred +Transferring passwd.byuid... +ypxfr: Exiting: Map successfully transferred +Transferring passwd.byname... +ypxfr: Exiting: Map successfully transferred +Transferring group.bygid... +ypxfr: Exiting: Map successfully transferred +Transferring group.byname... +ypxfr: Exiting: Map successfully transferred +Transferring services.byname... +ypxfr: Exiting: Map successfully transferred +Transferring rpc.bynumber... +ypxfr: Exiting: Map successfully transferred +Transferring rpc.byname... +ypxfr: Exiting: Map successfully transferred +Transferring protocols.byname... +ypxfr: Exiting: Map successfully transferred +Transferring master.passwd.byname... +ypxfr: Exiting: Map successfully transferred +Transferring networks.byname... +ypxfr: Exiting: Map successfully transferred +Transferring networks.byaddr... +ypxfr: Exiting: Map successfully transferred +Transferring netid.byname... +ypxfr: Exiting: Map successfully transferred +Transferring hosts.byaddr... +ypxfr: Exiting: Map successfully transferred +Transferring protocols.bynumber... +ypxfr: Exiting: Map successfully transferred +Transferring ypservers... +ypxfr: Exiting: Map successfully transferred +Transferring hosts.byname... +ypxfr: Exiting: Map successfully transferred + +coltrane has been setup as an YP slave server without any errors. +Don't forget to update map ypservers on ellington.</screen> + + <para>You should now have a directory called + <filename>/var/yp/test-domain</filename>. Copies of the + NIS master server's maps should be in this directory. You + will need to make sure that these stay updated. The + following <filename>/etc/crontab</filename> entries on + your slave servers should do the job:</para> + + <programlisting>20 * * * * root /usr/libexec/ypxfr passwd.byname +21 * * * * root /usr/libexec/ypxfr passwd.byuid</programlisting> + + <para>These two lines force the slave to sync its maps with + the maps on the master server. These entries are not + mandatory because the master server automatically attempts + to push any map changes to its slaves. However, due to + the importance of correct password information on other + clients depending on the slave server, it is recommended + to specifically force the password map updates frequently. + This is especially important on busy networks where map + updates might not always complete.</para> + + <para>Now, run the command <command>/etc/netstart</command> + on the slave server as well, which again starts the NIS + server.</para> + </sect4> + </sect3> + + <sect3> + <title>NIS Clients</title> + + <para> An NIS client establishes what is called a binding to a + particular NIS server using the + <command>ypbind</command> daemon. + <command>ypbind</command> checks the system's default + domain (as set by the <command>domainname</command> + command), and begins broadcasting RPC requests on the local + network. These requests specify the name of the domain for + which <command>ypbind</command> is attempting to establish a + binding. If a server that has been configured to serve the + requested domain receives one of the broadcasts, it will + respond to <command>ypbind</command>, which will record the + server's address. If there are several servers available (a + master and several slaves, for example), + <command>ypbind</command> will use the address of the first + one to respond. From that point on, the client system will + direct all of its NIS requests to + that server. <command>ypbind</command> will + occasionally <quote>ping</quote> the server to make sure it + is still up and running. If it fails to receive a reply to + one of its pings within a reasonable amount of time, + <command>ypbind</command> will mark the domain as unbound + and begin broadcasting again in the hopes of locating + another server.</para> + + <sect4> + <title>Setting Up a NIS Client</title> <indexterm> + <primary>NIS</primary> <secondary>client + configuration</secondary> + </indexterm> <para>Setting up a FreeBSD machine to be a NIS + client is fairly straightforward.</para> + + <procedure> + <step> + <para>Edit the file <filename>/etc/rc.conf</filename> + and add the following lines in order to set the NIS + domainname and start <command>ypbind</command> upon + network startup:</para> + + <programlisting>nisdomainname="test-domain" +nis_client_enable="YES"</programlisting> + </step> + + <step> + <para>To import all possible password entries from the + NIS server, remove all user accounts from your + <filename>/etc/master.passwd</filename> file and use + <command>vipw</command> to add the following line to + the end of the file:</para> + + <programlisting>+:::::::::</programlisting> + + <note> + <para>This line will afford anyone with a valid + account in the NIS server's password maps an + account. There are many ways to configure your NIS + client by changing this line. See the + <link + linkend="network-netgroups">netgroups + section</link> below for more information. For more + detailed reading see O'Reilly's book on + <literal>Managing NFS and NIS</literal>.</para> + </note> + + <note> + <para>You should keep at least one local account (i.e. + not imported via NIS) in your + <filename>/etc/master.passwd</filename> and this + account should also be a member of the group + <groupname>wheel</groupname>. If there is something + wrong with NIS, this account can be used to log in + remotely, become <username>root</username>, and fix + things.</para> + </note> + </step> + + <step> + <para>To import all possible group entries from the NIS + server, add this line to your + <filename>/etc/group</filename> file:</para> + + <programlisting>+:*::</programlisting> + </step> + </procedure> + + <para>To start the NIS client immediately, execute the + following commands as the superuser:</para> + + <screen>&prompt.root; <userinput>/etc/netstart</userinput> +&prompt.root; <userinput>/etc/rc.d/ypbind start</userinput></screen> + + <para>After completing these steps, you should be able to + run <command>ypcat passwd</command> and see the NIS + server's passwd map.</para> + </sect4> </sect3> + </sect2> + + <sect2> + <title>NIS Security</title> + + <para>In general, any remote user can issue an RPC to + &man.ypserv.8; and retrieve the contents of your NIS maps, + provided the remote user knows your domainname. To prevent + such unauthorized transactions, &man.ypserv.8; supports a + feature called <quote>securenets</quote> which can be used to + restrict access to a given set of hosts. At startup, + &man.ypserv.8; will attempt to load the securenets information + from a file called + <filename>/var/yp/securenets</filename>.</para> + + <note> + <para>This path varies depending on the path specified with + the <option>-p</option> option. This file contains entries + that consist of a network specification and a network mask + separated by white space. Lines starting with + <quote>#</quote> are considered to be comments. A sample + securenets file might look like this:</para> + </note> + + <programlisting># allow connections from local host -- mandatory +127.0.0.1 255.255.255.255 +# allow connections from any host +# on the 192.168.128.0 network +192.168.128.0 255.255.255.0 +# allow connections from any host +# between 10.0.0.0 to 10.0.15.255 +# this includes the machines in the testlab +10.0.0.0 255.255.240.0</programlisting> + + <para>If &man.ypserv.8; receives a request from an address that + matches one of these rules, it will process the request + normally. If the address fails to match a rule, the request + will be ignored and a warning message will be logged. If the + <filename>/var/yp/securenets</filename> file does not exist, + <command>ypserv</command> will allow connections from any + host.</para> + + <para>The <command>ypserv</command> program also has support for + Wietse Venema's <application>TCP Wrapper</application> + package. This allows the administrator to use the + <application>TCP Wrapper</application> configuration files for + access control instead of + <filename>/var/yp/securenets</filename>.</para> + + <note> + <para>While both of these access control mechanisms provide + some security, they, like the privileged port test, are + vulnerable to <quote>IP spoofing</quote> attacks. All + NIS-related traffic should be blocked at your + firewall.</para> + + <para>Servers using <filename>/var/yp/securenets</filename> + may fail to serve legitimate NIS clients with archaic TCP/IP + implementations. Some of these implementations set all host + bits to zero when doing broadcasts and/or fail to observe + the subnet mask when calculating the broadcast address. + While some of these problems can be fixed by changing the + client configuration, other problems may force + the retirement of the client systems in question or the + abandonment of + <filename>/var/yp/securenets</filename>.</para> + + <para>Using <filename>/var/yp/securenets</filename> on a + server with such an archaic implementation of TCP/IP is a + really bad idea and will lead to loss of NIS functionality + for large parts of your network.</para> + + <indexterm><primary>TCP Wrappers</primary></indexterm> + <para>The use of the <application>TCP Wrapper</application> + package increases the latency of your NIS server. The + additional delay may be long enough to cause timeouts in + client programs, especially in busy networks or with slow + NIS servers. If one or more of your client systems + suffers from these symptoms, you should convert the client + systems in question into NIS slave servers and force them + to bind to themselves.</para> + </note> + </sect2> + + <sect2> + <title>Barring Some Users from Logging On</title> + + <para>In our lab, there is a machine <hostid>basie</hostid> that + is supposed to be a faculty only workstation. We do not want + to take this machine out of the NIS domain, yet the + <filename>passwd</filename> file on the master NIS server + contains accounts for both faculty and students. What can we + do?</para> + + <para>There is a way to bar specific users from logging on to a + machine, even if they are present in the NIS database. To do + this, all you must do is add + <literal>-<replaceable>username</replaceable></literal> to the + end of the <filename>/etc/master.passwd</filename> file on the + client machine, where <replaceable>username</replaceable> is + the username of the user you wish to bar from logging in. + This should preferably be done using <command>vipw</command>, + since <command>vipw</command> will sanity check your changes + to <filename>/etc/master.passwd</filename>, as well as + automatically rebuild the password database when you finish + editing. For example, if we wanted to bar user + <username>bill</username> from logging on to + <hostid>basie</hostid> we would:</para> + + <screen>basie&prompt.root; <userinput>vipw</userinput> +<userinput>[add -bill to the end, exit]</userinput> +vipw: rebuilding the database... +vipw: done + +basie&prompt.root; <userinput>cat /etc/master.passwd</userinput> + +root:[password]:0:0::0:0:The super-user:/root:/bin/csh +toor:[password]:0:0::0:0:The other super-user:/root:/bin/sh +daemon:*:1:1::0:0:Owner of many system processes:/root:/sbin/nologin +operator:*:2:5::0:0:System &:/:/sbin/nologin +bin:*:3:7::0:0:Binaries Commands and Source,,,:/:/sbin/nologin +tty:*:4:65533::0:0:Tty Sandbox:/:/sbin/nologin +kmem:*:5:65533::0:0:KMem Sandbox:/:/sbin/nologin +games:*:7:13::0:0:Games pseudo-user:/usr/games:/sbin/nologin +news:*:8:8::0:0:News Subsystem:/:/sbin/nologin +man:*:9:9::0:0:Mister Man Pages:/usr/share/man:/sbin/nologin +bind:*:53:53::0:0:Bind Sandbox:/:/sbin/nologin +uucp:*:66:66::0:0:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico +xten:*:67:67::0:0:X-10 daemon:/usr/local/xten:/sbin/nologin +pop:*:68:6::0:0:Post Office Owner:/nonexistent:/sbin/nologin +nobody:*:65534:65534::0:0:Unprivileged user:/nonexistent:/sbin/nologin ++::::::::: +-bill + +basie&prompt.root;</screen> + </sect2> + + <sect2 id="network-netgroups"> + <sect2info> + <authorgroup> + <author> + <firstname>Udo</firstname> + <surname>Erdelhoff</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>Using Netgroups</title> + <indexterm><primary>netgroups</primary></indexterm> + + <para>The method shown in the previous section works reasonably + well if you need special rules for a very small number of + users and/or machines. On larger networks, you + <emphasis>will</emphasis> forget to bar some users from + logging onto sensitive machines, or you may even have to + modify each machine separately, thus losing the main benefit + of NIS: <emphasis>centralized</emphasis> + administration.</para> + + <para>The NIS developers' solution for this problem is called + <emphasis>netgroups</emphasis>. Their purpose and semantics + can be compared to the normal groups used by &unix; file + systems. The main differences are the lack of a numeric ID + and the ability to define a netgroup by including both user + accounts and other netgroups.</para> + + <para>Netgroups were developed to handle large, complex networks + with hundreds of users and machines. On one hand, this is a + Good Thing if you are forced to deal with such a situation. + On the other hand, this complexity makes it almost impossible + to explain netgroups with really simple examples. The example + used in the remainder of this section demonstrates this + problem.</para> + + <para>Let us assume that your successful introduction of NIS in + your laboratory caught your superiors' interest. Your next + job is to extend your NIS domain to cover some of the other + machines on campus. The two tables contain the names of the + new users and new machines as well as brief descriptions of + them.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>User Name(s)</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><username>alpha</username>, + <username>beta</username></entry> + <entry>Normal employees of the IT department</entry> + </row> + + <row> + <entry><username>charlie</username>, + <username>delta</username></entry> + <entry>The new apprentices of the IT department</entry> + </row> + + <row> + <entry><username>echo</username>, + <username>foxtrott</username>, + <username>golf</username>, ...</entry> + <entry>Ordinary employees</entry> + </row> + + <row> + <entry><username>able</username>, + <username>baker</username>, ...</entry> + <entry>The current interns</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Machine Name(s)</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <!-- Names taken from "Good Omens" by Neil Gaiman and Terry + Pratchett. Many thanks for a brilliant book. --> + <entry><hostid>war</hostid>, + <hostid>death</hostid>, <hostid>famine</hostid>, + <hostid>pollution</hostid></entry> + <entry>Your most important servers. Only the IT + employees are allowed to log onto these + machines.</entry> + </row> + <row> + <!-- gluttony was omitted because it was too fat --> + <entry><hostid>pride</hostid>, <hostid>greed</hostid>, + <hostid>envy</hostid>, <hostid>wrath</hostid>, + <hostid>lust</hostid>, <hostid>sloth</hostid></entry> + <entry>Less important servers. All members of the IT + department are allowed to login onto these + machines.</entry> + </row> + <row> + <entry><hostid>one</hostid>, <hostid>two</hostid>, + <hostid>three</hostid>, <hostid>four</hostid>, + ...</entry> + <entry>Ordinary workstations. Only the + <emphasis>real</emphasis> employees are allowed to use + these machines.</entry> + </row> + + <row> + <entry><hostid>trashcan</hostid></entry> + <entry>A very old machine without any critical data. + Even the intern is allowed to use this box.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>If you tried to implement these restrictions by separately + blocking each user, you would have to add one + <literal>-<replaceable>user</replaceable></literal> line to + each system's <filename>passwd</filename> for each user who is + not allowed to login onto that system. If you forget just one + entry, you could be in trouble. It may be feasible to do this + correctly during the initial setup, however you + <emphasis>will</emphasis> eventually forget to add the lines + for new users during day-to-day operations. After all, Murphy + was an optimist.</para> + + <para>Handling this situation with netgroups offers several + advantages. Each user need not be handled separately; you + assign a user to one or more netgroups and allow or forbid + logins for all members of the netgroup. If you add a new + machine, you will only have to define login restrictions for + netgroups. If a new user is added, you will only have to add + the user to one or more netgroups. Those changes are + independent of each other: no more <quote>for each combination + of user and machine do...</quote> If your NIS setup is planned + carefully, you will only have to modify exactly one central + configuration file to grant or deny access to machines.</para> + + <para>The first step is the initialization of the NIS map + netgroup. FreeBSD's &man.ypinit.8; does not create this map + by default, but its NIS implementation will support it once it + has been created. To create an empty map, simply type</para> + + <screen>ellington&prompt.root; <userinput>vi /var/yp/netgroup</userinput></screen> + + <para>and start adding content. For our example, we need at + least four netgroups: IT employees, IT apprentices, normal + employees and interns.</para> + + <programlisting>IT_EMP (,alpha,test-domain) (,beta,test-domain) +IT_APP (,charlie,test-domain) (,delta,test-domain) +USERS (,echo,test-domain) (,foxtrott,test-domain) \ + (,golf,test-domain) +INTERNS (,able,test-domain) (,baker,test-domain)</programlisting> + + <para><literal>IT_EMP</literal>, <literal>IT_APP</literal> etc. + are the names of the netgroups. Each bracketed group adds + one or more user accounts to it. The three fields inside a + group are:</para> + + <orderedlist> + <listitem> + <para>The name of the host(s) where the following items are + valid. If you do not specify a hostname, the entry is + valid on all hosts. If you do specify a hostname, you + will enter a realm of darkness, horror and utter + confusion.</para> + </listitem> + + <listitem> + <para>The name of the account that belongs to this + netgroup.</para> + </listitem> + + <listitem> + <para>The NIS domain for the account. You can import + accounts from other NIS domains into your netgroup if you + are one of the unlucky fellows with more than one NIS + domain.</para> + </listitem> + </orderedlist> + + <para>Each of these fields can contain wildcards. See + &man.netgroup.5; for details.</para> + + <note> + <indexterm><primary>netgroups</primary></indexterm> + <para>Netgroup names longer than 8 characters should not be + used, especially if you have machines running other + operating systems within your NIS domain. The names are + case sensitive; using capital letters for your netgroup + names is an easy way to distinguish between user, machine + and netgroup names.</para> + + <para>Some NIS clients (other than FreeBSD) cannot handle + netgroups with a large number of entries. For example, some + older versions of &sunos; start to cause trouble if a + netgroup contains more than 15 <emphasis>entries</emphasis>. + You can circumvent this limit by creating several + sub-netgroups with 15 users or less and a real netgroup that + consists of the sub-netgroups:</para> + + <programlisting>BIGGRP1 (,joe1,domain) (,joe2,domain) (,joe3,domain) [...] +BIGGRP2 (,joe16,domain) (,joe17,domain) [...] +BIGGRP3 (,joe31,domain) (,joe32,domain) +BIGGROUP BIGGRP1 BIGGRP2 BIGGRP3</programlisting> + + <para>You can repeat this process if you need more than 225 + users within a single netgroup.</para> + </note> + + <para>Activating and distributing your new NIS map is + easy:</para> + + <screen>ellington&prompt.root; <userinput>cd /var/yp</userinput> +ellington&prompt.root; <userinput>make</userinput></screen> + + <para>This will generate the three NIS maps + <filename>netgroup</filename>, + <filename>netgroup.byhost</filename> and + <filename>netgroup.byuser</filename>. Use &man.ypcat.1; to + check if your new NIS maps are available:</para> + + <screen>ellington&prompt.user; <userinput>ypcat -k netgroup</userinput> +ellington&prompt.user; <userinput>ypcat -k netgroup.byhost</userinput> +ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen> + + <para>The output of the first command should resemble the + contents of <filename>/var/yp/netgroup</filename>. The second + command will not produce output if you have not specified + host-specific netgroups. The third command can be used to + get the list of netgroups for a user.</para> + + <para>The client setup is quite simple. To configure the server + <hostid>war</hostid>, you only have to start + &man.vipw.8; and replace the line</para> + + <programlisting>+:::::::::</programlisting> + + <para>with</para> + + <programlisting>+@IT_EMP:::::::::</programlisting> + + <para>Now, only the data for the users defined in the netgroup + <literal>IT_EMP</literal> is imported into + <hostid>war</hostid>'s password database and only + these users are allowed to login.</para> + + <para>Unfortunately, this limitation also applies to the + <literal>~</literal> function of the shell and all routines + converting between user names and numerical user IDs. In + other words, <command>cd + ~<replaceable>user</replaceable></command> will not work, + <command>ls -l</command> will show the numerical ID instead of + the username and <command>find . -user joe -print</command> + will fail with <errorname>No such user</errorname>. To fix + this, you will have to import all user entries + <emphasis>without allowing them to login onto your + servers</emphasis>.</para> + + <para>This can be achieved by adding another line to + <filename>/etc/master.passwd</filename>. This line should + contain:</para> + + <para><literal>+:::::::::/sbin/nologin</literal>, meaning + <quote>Import all entries but replace the shell with + <filename>/sbin/nologin</filename> in the imported + entries</quote>. You can replace any field in the + <literal>passwd</literal> entry by placing a default value in + your <filename>/etc/master.passwd</filename>.</para> + + <!-- Been there, done that, got the scars to prove it - ue --> + <warning> + <para>Make sure that the line + <literal>+:::::::::/sbin/nologin</literal> is placed after + <literal>+@IT_EMP:::::::::</literal>. Otherwise, all user + accounts imported from NIS will have + <filename>/sbin/nologin</filename> as their login + shell.</para> + </warning> + + <para>After this change, you will only have to change one NIS + map if a new employee joins the IT department. You could use + a similar approach for the less important servers by replacing + the old <literal>+:::::::::</literal> in their local version + of <filename>/etc/master.passwd</filename> with something like + this:</para> + + <programlisting>+@IT_EMP::::::::: ++@IT_APP::::::::: ++:::::::::/sbin/nologin</programlisting> + + <para>The corresponding lines for the normal workstations + could be:</para> + + <programlisting>+@IT_EMP::::::::: ++@USERS::::::::: ++:::::::::/sbin/nologin</programlisting> + + <para>And everything would be fine until there is a policy + change a few weeks later: The IT department starts hiring + interns. The IT interns are allowed to use the normal + workstations and the less important servers; and the IT + apprentices are allowed to login onto the main servers. You + add a new netgroup <literal>IT_INTERN</literal>, add the new + IT interns to this netgroup and start to change the + configuration on each and every machine... As the old saying + goes: <quote>Errors in centralized planning lead to global + mess</quote>.</para> + + <para>NIS' ability to create netgroups from other netgroups can + be used to prevent situations like these. One possibility is + the creation of role-based netgroups. For example, you could + create a netgroup called <literal>BIGSRV</literal> to define + the login restrictions for the important servers, another + netgroup called <literal>SMALLSRV</literal> for the less + important servers and a third netgroup called + <literal>USERBOX</literal> for the normal + workstations. Each of these netgroups contains the netgroups + that are allowed to login onto these machines. The new + entries for your NIS map netgroup should look like + this:</para> + + <programlisting>BIGSRV IT_EMP IT_APP +SMALLSRV IT_EMP IT_APP ITINTERN +USERBOX IT_EMP ITINTERN USERS</programlisting> + + <para>This method of defining login restrictions works + reasonably well if you can define groups of machines with + identical restrictions. Unfortunately, this is the exception + and not the rule. Most of the time, you will need the ability + to define login restrictions on a per-machine basis.</para> + + <para>Machine-specific netgroup definitions are the other + possibility to deal with the policy change outlined above. In + this scenario, the <filename>/etc/master.passwd</filename> of + each box contains two lines starting with <quote>+</quote>. + The first of them adds a netgroup with the accounts allowed to + login onto this machine, the second one adds all other + accounts with <filename>/sbin/nologin</filename> as shell. It + is a good idea to use the <quote>ALL-CAPS</quote> version of + the machine name as the name of the netgroup. In other words, + the lines should look like this:</para> + + <programlisting>+@<replaceable>BOXNAME</replaceable>::::::::: ++:::::::::/sbin/nologin</programlisting> + + <para>Once you have completed this task for all your machines, + you will not have to modify the local versions of + <filename>/etc/master.passwd</filename> ever again. All + further changes can be handled by modifying the NIS map. Here + is an example of a possible netgroup map for this + scenario with some additional goodies:</para> + + <programlisting># Define groups of users first +IT_EMP (,alpha,test-domain) (,beta,test-domain) +IT_APP (,charlie,test-domain) (,delta,test-domain) +DEPT1 (,echo,test-domain) (,foxtrott,test-domain) +DEPT2 (,golf,test-domain) (,hotel,test-domain) +DEPT3 (,india,test-domain) (,juliet,test-domain) +ITINTERN (,kilo,test-domain) (,lima,test-domain) +D_INTERNS (,able,test-domain) (,baker,test-domain) +# +# Now, define some groups based on roles +USERS DEPT1 DEPT2 DEPT3 +BIGSRV IT_EMP IT_APP +SMALLSRV IT_EMP IT_APP ITINTERN +USERBOX IT_EMP ITINTERN USERS +# +# And a groups for a special tasks +# Allow echo and golf to access our anti-virus-machine +SECURITY IT_EMP (,echo,test-domain) (,golf,test-domain) +# +# machine-based netgroups +# Our main servers +WAR BIGSRV +FAMINE BIGSRV +# User india needs access to this server +POLLUTION BIGSRV (,india,test-domain) +# +# This one is really important and needs more access restrictions +DEATH IT_EMP +# +# The anti-virus-machine mentioned above +ONE SECURITY +# +# Restrict a machine to a single user +TWO (,hotel,test-domain) +# [...more groups to follow]</programlisting> + + <para>If you are using some kind of database to manage your user + accounts, you should be able to create the first part of the + map with your database's report tools. This way, new users + will automatically have access to the boxes.</para> + + <para>One last word of caution: It may not always be advisable + to use machine-based netgroups. If you are deploying a couple + of dozen or even hundreds of identical machines for student + labs, you should use role-based netgroups instead of + machine-based netgroups to keep the size of the NIS map within + reasonable limits.</para> + </sect2> + + <sect2> + <title>Important Things to Remember</title> + + <para>There are still a couple of things that you will need to + do differently now that you are in an NIS environment.</para> + + <itemizedlist> + <listitem> + <para>Every time you wish to add a user to the lab, you + must add it to the master NIS server + <emphasis>only</emphasis>, and <emphasis>you must remember + to rebuild the NIS maps</emphasis>. If you forget to do + this, the new user will not be able to login anywhere + except on the NIS master. For example, if we needed to + add a new user <username>jsmith</username> to the lab, we + would:</para> + + <screen>&prompt.root; <userinput>pw useradd jsmith</userinput> +&prompt.root; <userinput>cd /var/yp</userinput> +&prompt.root; <userinput>make test-domain</userinput></screen> + + <para>You could also run <command>adduser jsmith</command> + instead of <command>pw useradd jsmith</command>.</para> + + </listitem> + <listitem> + <para><emphasis>Keep the administration accounts out of the + NIS maps</emphasis>. You do not want to be propagating + administrative accounts and passwords to machines that + will have users that should not have access to those + accounts.</para> + </listitem> + <listitem> + <para><emphasis>Keep the NIS master and slave secure, and + minimize their downtime</emphasis>. If somebody either + hacks or simply turns off these machines, they have + effectively rendered many people without the ability to + login to the lab.</para> + + <para>This is the chief weakness of any centralized + administration system. If you do not protect your NIS + servers, you will have a lot of angry users!</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>NIS v1 Compatibility</title> + + <para> FreeBSD's <application>ypserv</application> has some + support for serving NIS v1 clients. FreeBSD's NIS + implementation only uses the NIS v2 protocol, however other + implementations include support for the v1 protocol for + backwards compatibility with older systems. The + <application>ypbind</application> daemons supplied with these + systems will try to establish a binding to an NIS v1 server + even though they may never actually need it (and they may + persist in broadcasting in search of one even after they + receive a response from a v2 server). Note that while support + for normal client calls is provided, this version of + <application>ypserv</application> does not handle v1 map + transfer requests; consequently, it cannot be used as a master + or slave in conjunction with older NIS servers that only + support the v1 protocol. Fortunately, there probably are not + any such servers still in use today.</para> + </sect2> + + <sect2 id="network-nis-server-is-client"> + <title>NIS Servers That Are Also NIS Clients</title> + + <para> Care must be taken when running + <application>ypserv</application> in a multi-server domain + where the server machines are also NIS clients. It is + generally a good idea to force the servers to bind to + themselves rather than allowing them to broadcast bind + requests and possibly become bound to each other. Strange + failure modes can result if one server goes down and others + are dependent upon it. Eventually all the clients will time + out and attempt to bind to other servers, but the delay + involved can be considerable and the failure mode is still + present since the servers might bind to each other all over + again.</para> + + <para>You can force a host to bind to a particular server by + running <command>ypbind</command> with the <option>-S</option> + flag. If you do not want to do this manually each time you + reboot your NIS server, you can add the following lines to + your <filename>/etc/rc.conf</filename>:</para> + + <programlisting>nis_client_enable="YES" # run client stuff as well +nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</replaceable>"</programlisting> + + <para>See &man.ypbind.8; for further information.</para> + </sect2> + + <sect2> + <title>Password Formats</title> + <indexterm> + <primary>NIS</primary> + <secondary>password formats</secondary> + </indexterm> + <para>One of the most common issues that people run into when + trying to implement NIS is password format compatibility. If + your NIS server is using DES encrypted passwords, it will only + support clients that are also using DES. For example, if you + have &solaris; NIS clients in your network, then you will + almost certainly need to use DES encrypted passwords.</para> + + <para>To check which format your servers and clients are using, + look at <filename>/etc/login.conf</filename>. If the host is + configured to use DES encrypted passwords, then the + <literal>default</literal> class will contain an entry like + this:</para> + + <programlisting>default:\ + :passwd_format=des:\ + :copyright=/etc/COPYRIGHT:\ + [Further entries elided]</programlisting> + + <para>Other possible values for the + <literal>passwd_format</literal> capability include + <literal>blf</literal> and <literal>md5</literal> (for + Blowfish and MD5 encrypted passwords, respectively).</para> + + <para>If you have made changes to + <filename>/etc/login.conf</filename>, you will also need to + rebuild the login capability database, which is achieved by + running the following command as + <username>root</username>:</para> + + <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen> + + <note><para>The format of passwords already in + <filename>/etc/master.passwd</filename> will not be updated + until a user changes his password for the first time + <emphasis>after</emphasis> the login capability database is + rebuilt.</para></note> + + <para>Next, in order to ensure that passwords are encrypted with + the format that you have chosen, you should also check that + the <literal>crypt_default</literal> in + <filename>/etc/auth.conf</filename> gives precedence to your + chosen password format. To do this, place the format that you + have chosen first in the list. For example, when using DES + encrypted passwords, the entry would be:</para> + + <programlisting>crypt_default = des blf md5</programlisting> + + <para>Having followed the above steps on each of the &os; based + NIS servers and clients, you can be sure that they all agree + on which password format is used within your network. If you + have trouble authenticating on an NIS client, this is a pretty + good place to start looking for possible problems. Remember: + if you want to deploy an NIS server for a heterogeneous + network, you will probably have to use DES on all systems + because it is the lowest common standard.</para> + </sect2> + </sect1> + + <sect1 id="network-dhcp"> + <sect1info> + <authorgroup> + <author> + <firstname>Greg</firstname> + <surname>Sutter</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Automatic Network Configuration (DHCP)</title> + + <sect2> + <title>What Is DHCP?</title> + <indexterm> + <primary>Dynamic Host Configuration Protocol</primary> + <see>DHCP</see> + </indexterm> + <indexterm> + <primary>Internet Systems Consortium (ISC)</primary> + </indexterm> + + <para>DHCP, the Dynamic Host Configuration Protocol, describes + the means by which a system can connect to a network and + obtain the necessary information for communication upon that + network. FreeBSD uses the OpenBSD <command>dhclient</command> + taken from OpenBSD 3.7. All information here regarding + <command>dhclient</command> is for use with either of the ISC + or OpenBSD DHCP clients. The DHCP server is the one included + in the ISC distribution.</para> + </sect2> + + <sect2> + <title>What This Section Covers</title> + + <para>This section describes both the client-side components of + the ISC and OpenBSD DHCP client and server-side components of + the ISC DHCP system. The client-side program, + <command>dhclient</command>, comes integrated within FreeBSD, + and the server-side portion is available from the <filename + role="package">net/isc-dhcp42-server</filename> port. The + &man.dhclient.8;, &man.dhcp-options.5;, and + &man.dhclient.conf.5; manual pages, in addition to the + references below, are useful resources.</para> + </sect2> + + <sect2> + <title>How It Works</title> + <indexterm><primary>UDP</primary></indexterm> + <para>When <command>dhclient</command>, the DHCP client, is + executed on the client machine, it begins broadcasting + requests for configuration information. By default, these + requests are on UDP port 68. The server replies on UDP 67, + giving the client an IP address and other relevant network + information such as netmask, router, and DNS servers. All of + this information comes in the form of a DHCP + <quote>lease</quote> and is only valid for a certain time + (configured by the DHCP server maintainer). In this manner, + stale IP addresses for clients no longer connected to the + network can be automatically reclaimed.</para> + + <para>DHCP clients can obtain a great deal of information from + the server. An exhaustive list may be found in + &man.dhcp-options.5;.</para> + </sect2> + + <sect2> + <title>FreeBSD Integration</title> + + <para>&os; fully integrates the OpenBSD DHCP client, + <command>dhclient</command>. DHCP client support is provided + within both the installer and the base system, obviating the + need for detailed knowledge of network configurations on any + network that runs a DHCP server.</para> <indexterm> + <primary><application>sysinstall</application></primary> + </indexterm> + + <para>DHCP is supported by + <application>sysinstall</application>. When configuring a + network interface within + <application>sysinstall</application>, the second question + asked is: <quote>Do you want to try DHCP configuration of + the interface?</quote>. Answering affirmatively will + execute <command>dhclient</command>, and if successful, will + fill in the network configuration information + automatically.</para> + + <para>There are two things you must do to have your system use + DHCP upon startup:</para> + <indexterm> + <primary>DHCP</primary> + <secondary>requirements</secondary> + </indexterm> + <itemizedlist> + <listitem> + <para>Make sure that the <devicename>bpf</devicename> + device is compiled into your kernel. To do this, add + <literal>device bpf</literal> to your kernel + configuration file, and rebuild the kernel. For more + information about building kernels, see <xref + linkend="kernelconfig">.</para> <para>The + <devicename>bpf</devicename> device is already part of + the <filename>GENERIC</filename> kernel that is supplied + with FreeBSD, so if you do not have a custom kernel, you + should not need to create one in order to get DHCP + working.</para> + <note> + <para>For those who are particularly security conscious, + you should be warned that <devicename>bpf</devicename> + is also the device that allows packet sniffers to work + correctly (although they still have to be run as + <username>root</username>). + <devicename>bpf</devicename> <emphasis>is</emphasis> + required to use DHCP, but if you are very sensitive + about security, you probably should not add + <devicename>bpf</devicename> to your + kernel in the expectation that at some point in the + future you will be using DHCP.</para> + </note> + </listitem> + <listitem> + <para>By default, DHCP configuration on &os; runs in the + background, or <firstterm>asynchronously</firstterm>. + Other startup scripts continue to run while DHCP + completes, speeding up system startup.</para> + + <para>Background DHCP works well when the DHCP server + responds quickly to requests and the DHCP configuration + process goes quickly. However, DHCP may take a long + time to complete on some systems. If network services + attempt to run before DHCP has completed, they will + fail. Using DHCP in <firstterm>synchronous</firstterm> + mode prevents the problem, pausing startup until DHCP + configuration has completed.</para> + + <para>To connect to a DHCP server in the background while + other startup continues (asynchronous mode), use the + <quote><literal>DHCP</literal></quote> value in + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ifconfig_<replaceable>fxp0</replaceable>="DHCP"</programlisting> + + <para>To pause startup while DHCP completes, use + synchronous mode with the + <quote><literal>SYNCDHCP</literal></quote> value:</para> + + <programlisting>ifconfig_<replaceable>fxp0</replaceable>="SYNCDHCP"</programlisting> + + <note> + <para>Replace the <replaceable>fxp0</replaceable> shown + in these examples with the name of the interface to be + dynamically configured, as described in + <xref linkend="config-network-setup">.</para> + </note> + + <para>If you are using a different location for + <command>dhclient</command>, or if you wish to pass + additional flags to <command>dhclient</command>, also + include (editing as necessary):</para> + + <programlisting>dhclient_program="/sbin/dhclient" +dhclient_flags=""</programlisting> + </listitem> + </itemizedlist> + + <indexterm> + <primary>DHCP</primary> + <secondary>server</secondary> + </indexterm> + <para>The DHCP server, <application>dhcpd</application>, is + included as part of the <filename + role="package">net/isc-dhcp42-server</filename> port in + the ports collection. This port contains the ISC DHCP + server and documentation.</para> + </sect2> + + <sect2> + <title>Files</title> + <indexterm> + <primary>DHCP</primary> + <secondary>configuration files</secondary> + </indexterm> + <itemizedlist> + <listitem> + <para><filename>/etc/dhclient.conf</filename></para> + <para><command>dhclient</command> requires a configuration + file, <filename>/etc/dhclient.conf</filename>. Typically + the file contains only comments, the defaults being + reasonably sane. This configuration file is described by + the &man.dhclient.conf.5; + manual page.</para> + </listitem> + + <listitem> + <para><filename>/sbin/dhclient</filename></para> + <para><command>dhclient</command> is statically linked and + resides in <filename>/sbin</filename>. The + &man.dhclient.8; manual page gives more information about + <command>dhclient</command>.</para> + </listitem> + + <listitem> + <para><filename>/sbin/dhclient-script</filename></para> + <para><command>dhclient-script</command> is the + FreeBSD-specific DHCP client configuration script. It is + described in &man.dhclient-script.8;, but should not need + any user modification to function properly.</para> + </listitem> + + <listitem> + <para><filename>/var/db/dhclient.leases.<replaceable>interface</replaceable></filename></para> + <para>The DHCP client keeps a database of valid leases in + this file, which is written as a log. + &man.dhclient.leases.5; gives a slightly longer + description.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Further Reading</title> + + <para>The DHCP protocol is fully described in <ulink + url="http://www.freesoft.org/CIE/RFC/2131/">RFC + 2131</ulink>. An informational resource has also been set up + at <ulink url="http://www.dhcp.org/"></ulink>.</para> + </sect2> + + <sect2 id="network-dhcp-server"> + <title>Installing and Configuring a DHCP Server</title> + + <sect3> + <title>What This Section Covers</title> + + <para>This section provides information on how to configure + a FreeBSD system to act as a DHCP server using the ISC + (Internet Systems Consortium) implementation of the DHCP + server.</para> + + <para>The server is not provided as part of FreeBSD, and so + you will need to install the <filename + role="package">net/isc-dhcp42-server</filename> port to + provide this service. See <xref linkend="ports"> for + more information on using the Ports Collection.</para> + </sect3> + + <sect3> + <title>DHCP Server Installation</title> + <indexterm> + <primary>DHCP</primary> + <secondary>installation</secondary> + </indexterm> + <para>In order to configure your FreeBSD system as a DHCP + server, you will need to ensure that the &man.bpf.4; + device is compiled into your kernel. To do this, add + <literal>device bpf</literal> to your kernel + configuration file, and rebuild the kernel. For more + information about building kernels, see <xref + linkend="kernelconfig">.</para> + + <para>The <devicename>bpf</devicename> device is already + part of the <filename>GENERIC</filename> kernel that is + supplied with FreeBSD, so you do not need to create a + custom kernel in order to get DHCP working.</para> + + <note> + <para>Those who are particularly security conscious + should note that <devicename>bpf</devicename> is also + the device that allows packet sniffers to work + correctly (although such programs still need + privileged access). <devicename>bpf</devicename> + <emphasis>is</emphasis> required to use DHCP, but if + you are very sensitive about security, you probably + should not include <devicename>bpf</devicename> in + your kernel purely because you expect to use DHCP at + some point in the future.</para> + </note> + + <para>The next thing that you will need to do is edit the + sample <filename>dhcpd.conf</filename> which was installed + by the <filename + role="package">net/isc-dhcp42-server</filename> port. + By default, this will be + <filename>/usr/local/etc/dhcpd.conf.sample</filename>, and + you should copy this to + <filename>/usr/local/etc/dhcpd.conf</filename> before + proceeding to make changes.</para> + </sect3> + + <sect3> + <title>Configuring the DHCP Server</title> + <indexterm> + <primary>DHCP</primary> + <secondary>dhcpd.conf</secondary> + </indexterm> + <para><filename>dhcpd.conf</filename> is comprised of + declarations regarding subnets and hosts, and is perhaps + most easily explained using an example :</para> + + <programlisting>option domain-name "example.com";<co id="domain-name"> +option domain-name-servers 192.168.4.100;<co id="domain-name-servers"> +option subnet-mask 255.255.255.0;<co id="subnet-mask"> + +default-lease-time 3600;<co id="default-lease-time"> +max-lease-time 86400;<co id="max-lease-time"> +ddns-update-style none;<co id="ddns-update-style"> + +subnet 192.168.4.0 netmask 255.255.255.0 { + range 192.168.4.129 192.168.4.254;<co id="range"> + option routers 192.168.4.1;<co id="routers"> +} + +host mailhost { + hardware ethernet 02:03:04:05:06:07;<co id="hardware"> + fixed-address mailhost.example.com;<co id="fixed-address"> +}</programlisting> + + <calloutlist> + <callout arearefs="domain-name"> + <para>This option specifies the domain that will be + provided to clients as the default search domain. See + &man.resolv.conf.5; for more information on what this + means.</para> + </callout> + + <callout arearefs="domain-name-servers"> + <para>This option specifies a comma separated list of + DNS servers that the client should use.</para> + </callout> + + <callout arearefs="subnet-mask"> + <para>The netmask that will be provided to + clients.</para> + </callout> + + <callout arearefs="default-lease-time"> + <para>A client may request a specific length of time + that a lease will be valid. Otherwise the server will + assign a lease with this expiry value (in + seconds).</para> + </callout> + + <callout arearefs="max-lease-time"> + <para>This is the maximum length of time that the server + will lease for. Should a client request a longer + lease, a lease will be issued, although it will only + be valid for <literal>max-lease-time</literal> + seconds.</para> + </callout> + + <callout arearefs="ddns-update-style"> + <para>This option specifies whether the DHCP server + should attempt to update DNS when a lease is accepted + or released. In the ISC implementation, this option + is <emphasis>required</emphasis>.</para> + </callout> + + <callout arearefs="range"> + <para>This denotes which IP addresses should be used in + the pool reserved for allocating to clients. IP + addresses between, and including, the ones stated are + handed out to clients.</para> + </callout> + + <callout arearefs="routers"> + <para>Declares the default gateway that will be provided + to clients.</para> + </callout> + + <callout arearefs="hardware"> + <para>The hardware MAC address of a host (so that the + DHCP server can recognize a host when it makes a + request).</para> + </callout> + + <callout arearefs="fixed-address"> + <para>Specifies that the host should always be given the + same IP address. Note that using a hostname is + correct here, since the DHCP server will resolve the + hostname itself before returning the lease + information.</para> + </callout> + </calloutlist> + + <para>Once you have finished writing your + <filename>dhcpd.conf</filename>, + you should enable the DHCP server in + <filename>/etc/rc.conf</filename>, i.e., by adding:</para> + + <programlisting>dhcpd_enable="YES" +dhcpd_ifaces="dc0"</programlisting> + + <para>Replace the <literal>dc0</literal> interface name with + the interface (or interfaces, separated by whitespace) + that your DHCP server should listen on for DHCP client + requests.</para> + + <para>Then, you can proceed to start the server by issuing + the following command:</para> + + <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/isc-dhcpd start</userinput></screen> + + <para>Should you need to make changes to the configuration + of your server in the future, it is important to note that + sending a <literal>SIGHUP</literal> signal to + <application>dhcpd</application> does + <emphasis>not</emphasis> result in the configuration being + reloaded, as it does with most daemons. You will need to + send a <literal>SIGTERM</literal> signal to stop the + process, and then restart it using the command + above.</para> + </sect3> + + <sect3> + <title>Files</title> + <indexterm> + <primary>DHCP</primary> + <secondary>configuration files</secondary> + </indexterm> + <itemizedlist> + <listitem> + <para><filename>/usr/local/sbin/dhcpd</filename></para> + <para><application>dhcpd</application> is statically + linked and resides in + <filename>/usr/local/sbin</filename>. The + &man.dhcpd.8; manual page installed with the port + gives more information about + <application>dhcpd</application>.</para> + </listitem> + + <listitem> + <para><filename>/usr/local/etc/dhcpd.conf</filename></para> + <para><application>dhcpd</application> requires a + configuration file, + <filename>/usr/local/etc/dhcpd.conf</filename> before + it will start providing service to clients. This file + needs to contain all the information that should be + provided to clients that are being serviced, along + with information regarding the operation of the + server. This configuration file is described + by the &man.dhcpd.conf.5; manual page installed + by the port.</para> + </listitem> + + <listitem> + <para><filename>/var/db/dhcpd.leases</filename></para> + <para>The DHCP server keeps a database of leases it has + issued in this file, which is written as a log. The + manual page &man.dhcpd.leases.5;, installed by the + port gives a slightly longer description.</para> + </listitem> + + <listitem> + <para><filename>/usr/local/sbin/dhcrelay</filename></para> + <para><application>dhcrelay</application> is used in + advanced environments where one DHCP server forwards a + request from a client to another DHCP server on a + separate network. If you require this functionality, + then install the <filename + role="package">net/isc-dhcp42-relay</filename> port. + The &man.dhcrelay.8; manual page provided with the + port contains more detail.</para> + </listitem> + </itemizedlist> + </sect3> + </sect2> + </sect1> + + <sect1 id="network-dns"> + <sect1info> + <authorgroup> + <author> + <firstname>Chern</firstname> + <surname>Lee</surname> + <contrib>Contributed by </contrib> + </author> + + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + </author> + + <author> + <firstname>Daniel</firstname> + <surname>Gerzo</surname> + </author> + </authorgroup> + </sect1info> + <title>Domain Name System (<acronym>DNS</acronym>)</title> + + <sect2> + <title>Overview</title> + <indexterm><primary>BIND</primary></indexterm> + + <para>&os; utilizes, by default, a version of BIND (Berkeley + Internet Name Domain), which is the most common implementation + of the <acronym>DNS</acronym> protocol. + <acronym>DNS</acronym> is the protocol through which names are + mapped to <acronym>IP</acronym> addresses, and vice versa. + For example, a query for <hostid + role="fqdn">www.FreeBSD.org</hostid> will receive a reply + with the <acronym>IP</acronym> address of The &os; Project's + web server, whereas, a query for <hostid + role="fqdn">ftp.FreeBSD.org</hostid> will return the + <acronym>IP</acronym> address of the corresponding + <acronym>FTP</acronym> machine. Likewise, the opposite can + happen. A query for an <acronym>IP</acronym> address can + resolve its hostname. It is not necessary to run a name + server to perform <acronym>DNS</acronym> lookups on a + system.</para> + + <para>&os; currently comes with <acronym>BIND</acronym>9 + <acronym>DNS</acronym> server software by default. Our + installation provides enhanced security features, a new file + system layout and automated &man.chroot.8; + configuration.</para> + + <indexterm><primary>DNS</primary></indexterm> + <para><acronym>DNS</acronym> is coordinated across the Internet + through a somewhat complex system of authoritative root, Top + Level Domain (<acronym>TLD</acronym>), and other smaller-scale + name servers which host and cache individual domain + information.</para> + + <para>Currently, BIND is maintained by the + Internet Systems Consortium + <ulink url="https://www.isc.org/"></ulink>.</para> + </sect2> + + <sect2> + <title>Terminology</title> + + <para>To understand this document, some terms related to + <acronym>DNS</acronym> must be understood.</para> + + <indexterm><primary>resolver</primary></indexterm> + <indexterm><primary>reverse DNS</primary></indexterm> + <indexterm><primary>root zone</primary></indexterm> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"> + <colspec colwidth="3*"> + + <thead> + <row> + <entry>Term</entry> + <entry>Definition</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Forward <acronym>DNS</acronym></entry> + <entry>Mapping of hostnames to IP addresses.</entry> + </row> + + <row> + <entry>Origin</entry> + <entry>Refers to the domain covered in a particular zone + file.</entry> + </row> + + <row> + <entry><application>named</application>, BIND</entry> + <entry>Common names for the BIND name server package + within &os;.</entry> + </row> + + <row> + <entry>Resolver</entry> + <entry>A system process through which a machine queries + a name server for zone information.</entry> + </row> + + <row> + <entry>Reverse <acronym>DNS</acronym></entry> + <entry>Mapping of <acronym>IP</acronym> addresses to + hostnames.</entry> + </row> + + <row> + <entry>Root zone</entry> + + <entry>The beginning of the Internet zone hierarchy. + All zones fall under the root zone, similar to how + all files in a file system fall under the root + directory.</entry> + </row> + + <row> + <entry>Zone</entry> + <entry>An individual domain, subdomain, or portion of + the <acronym>DNS</acronym> administered by the same + authority.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <indexterm> + <primary>zones</primary> + <secondary>examples</secondary> + </indexterm> + + <para>Examples of zones:</para> + + <itemizedlist> + <listitem> + <para><hostid>.</hostid> is how the root zone is usually + referred to in documentation.</para> + </listitem> + + <listitem> + <para><hostid>org.</hostid> is a Top Level Domain + (<acronym>TLD</acronym>) under the root zone.</para> + </listitem> + + <listitem> + <para><hostid role="domainname">example.org.</hostid> is a + zone under the <hostid>org.</hostid> + <acronym>TLD</acronym>.</para> + </listitem> + + <listitem> + <para><hostid>1.168.192.in-addr.arpa</hostid> is a zone + referencing all <acronym>IP</acronym> addresses which fall + under the <hostid role="ipaddr">192.168.1.*</hostid> + <acronym>IP</acronym> address space.</para> + </listitem> + </itemizedlist> + + <para>As one can see, the more specific part of a hostname + appears to its left. For example, <hostid + role="domainname">example.org.</hostid> is more specific + than <hostid>org.</hostid>, as <hostid>org.</hostid> is more + specific than the root zone. The layout of each part of a + hostname is + much like a file system: the + <filename class="directory">/dev</filename> directory falls + within the root, and so on.</para> + </sect2> + + <sect2> + <title>Reasons to Run a Name Server</title> + + <para>Name servers generally come in two forms: authoritative + name servers, and caching (also known as resolving) + name servers.</para> + + <para>An authoritative name server is needed when:</para> + + <itemizedlist> + <listitem> + <para>One wants to serve <acronym>DNS</acronym> information + to the world, replying authoritatively to queries.</para> + </listitem> + + <listitem> + <para>A domain, such as <hostid + role="domainname">example.org</hostid>, is registered + and <acronym>IP</acronym> addresses need to be assigned + to hostnames under it.</para> + </listitem> + + <listitem> + <para>An <acronym>IP</acronym> address block requires + reverse <acronym>DNS</acronym> entries + (<acronym>IP</acronym> to hostname).</para> + </listitem> + + <listitem> + <para>A backup or second name server, called a slave, will + reply to queries.</para> + </listitem> + </itemizedlist> + + <para>A caching name server is needed when:</para> + + <itemizedlist> + <listitem> + <para>A local <acronym>DNS</acronym> server may cache and + respond more quickly than querying an outside name + server.</para> + </listitem> + </itemizedlist> + + <para>When one queries for <hostid + role="fqdn">www.FreeBSD.org</hostid>, the resolver usually + queries the uplink <acronym>ISP</acronym>'s name server, and + retrieves the reply. With a local, caching + <acronym>DNS</acronym> server, the query only has to be made + once to the outside world by the caching + <acronym>DNS</acronym> server. Additional queries will not + have to go outside the local network, since the information is + cached + locally.</para> + </sect2> + + <sect2> + <title>How It Works</title> + <para>In &os;, the BIND daemon is called + <application>named</application>.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>File</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry>&man.named.8;</entry> + <entry>The BIND daemon.</entry> + </row> + + <row> + <entry>&man.rndc.8;</entry> + <entry>Name server control utility.</entry> + </row> + + <row> + <entry><filename + class="directory">/etc/namedb</filename></entry> + <entry>Directory where BIND zone information + resides.</entry> + </row> + + <row> + <entry><filename>/etc/namedb/named.conf</filename></entry> + <entry>Configuration file of the daemon.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Depending on how a given zone is configured on the server, + the files related to that zone can be found in the <filename + class="directory">master</filename>, <filename + class="directory">slave</filename>, or <filename + class="directory">dynamic</filename> subdirectories of the + <filename class="directory">/etc/namedb</filename> directory. + These files contain the <acronym>DNS</acronym> information + that will be given out by the name server in response to + queries.</para> + </sect2> + + <sect2> + <title>Starting BIND</title> + + <indexterm> + <primary>BIND</primary> + <secondary>starting</secondary> + </indexterm> + + <para>Since BIND is installed by default, configuring it is + relatively simple.</para> + + <para>The default <application>named</application> configuration + is that of a basic resolving name server, running in a + &man.chroot.8; environment, and restricted to listening on + the local IPv4 loopback address (127.0.0.1). + To start the server one time with + this configuration, use the following command:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/named onestart</userinput></screen> + + <para>To ensure the <application>named</application> daemon is + started at boot each time, put the following line into the + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>named_enable="YES"</programlisting> + + <para>There are obviously many configuration options for + <filename>/etc/namedb/named.conf</filename> that are beyond + the scope of this document. However, if you are interested in + the startup options for <application>named</application> on + &os;, take a look at the + <literal>named_<replaceable>*</replaceable></literal> flags in + <filename>/etc/defaults/rc.conf</filename> and consult the + &man.rc.conf.5; manual page. The <xref + linkend="configtuning-rcd"> section is also a good + read.</para> + </sect2> + + <sect2> + <title>Configuration Files</title> + + <indexterm> + <primary>BIND</primary> + <secondary>configuration files</secondary> + </indexterm> + + <para>Configuration files for <application>named</application> + currently reside in <filename + class="directory">/etc/namedb</filename> directory and will + need modification before use unless all that is needed is a + simple resolver. This is where most of the configuration will + be performed.</para> + + <sect3> + <title><filename>/etc/namedb/named.conf</filename></title> + + <programlisting>// $FreeBSD$ +// +// Refer to the named.conf(5) and named(8) man pages, and the documentation +// in /usr/share/doc/bind9 for more details. +// +// If you are going to set up an authoritative server, make sure you +// understand the hairy details of how DNS works. Even with +// simple mistakes, you can break connectivity for affected parties, +// or cause huge amounts of useless Internet traffic. + +options { + // All file and path names are relative to the chroot directory, + // if any, and should be fully qualified. + directory "/etc/namedb/working"; + pid-file "/var/run/named/pid"; + dump-file "/var/dump/named_dump.db"; + statistics-file "/var/stats/named.stats"; + +// If named is being used only as a local resolver, this is a safe default. +// For named to be accessible to the network, comment this option, specify +// the proper IP address, or delete this option. + listen-on { 127.0.0.1; }; + +// If you have IPv6 enabled on this system, uncomment this option for +// use as a local resolver. To give access to the network, specify +// an IPv6 address, or the keyword "any". +// listen-on-v6 { ::1; }; + +// These zones are already covered by the empty zones listed below. +// If you remove the related empty zones below, comment these lines out. + disable-empty-zone "255.255.255.255.IN-ADDR.ARPA"; + disable-empty-zone "0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA"; + disable-empty-zone "1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.IP6.ARPA"; + +// If you've got a DNS server around at your upstream provider, enter +// its IP address here, and enable the line below. This will make you +// benefit from its cache, thus reduce overall DNS traffic in the Internet. +/* + forwarders { + 127.0.0.1; + }; +*/ + +// If the 'forwarders' clause is not empty the default is to 'forward first' +// which will fall back to sending a query from your local server if the name +// servers in 'forwarders' do not have the answer. Alternatively you can +// force your name server to never initiate queries of its own by enabling the +// following line: +// forward only; + +// If you wish to have forwarding configured automatically based on +// the entries in /etc/resolv.conf, uncomment the following line and +// set named_auto_forward=yes in /etc/rc.conf. You can also enable +// named_auto_forward_only (the effect of which is described above). +// include "/etc/namedb/auto_forward.conf";</programlisting> + + <para>Just as the comment says, to benefit from an uplink's + cache, <literal>forwarders</literal> can be enabled here. + Under normal circumstances, a name server will recursively + query the Internet looking at certain name servers until it + finds the answer it is looking for. Having this enabled + will have it query the uplink's name server (or name server + provided) first, taking advantage of its cache. If the + uplink name server in question is a heavily trafficked, fast + name server, enabling this may be worthwhile.</para> + + <warning> + <para><hostid role="ipaddr">127.0.0.1</hostid> will + <emphasis>not</emphasis> work here. Change this + <acronym>IP</acronym> address to a name server at your + uplink.</para> + </warning> + + <programlisting> /* + Modern versions of BIND use a random UDP port for each outgoing + query by default in order to dramatically reduce the possibility + of cache poisoning. All users are strongly encouraged to utilize + this feature, and to configure their firewalls to accommodate it. + + AS A LAST RESORT in order to get around a restrictive firewall + policy you can try enabling the option below. Use of this option + will significantly reduce your ability to withstand cache poisoning + attacks, and should be avoided if at all possible. + + Replace NNNNN in the example with a number between 49160 and 65530. + */ + // query-source address * port NNNNN; +}; + +// If you enable a local name server, don't forget to enter 127.0.0.1 +// first in your /etc/resolv.conf so this server will be queried. +// Also, make sure to enable it in /etc/rc.conf. + +// The traditional root hints mechanism. Use this, OR the slave zones below. +zone "." { type hint; file "/etc/namedb/named.root"; }; + +/* Slaving the following zones from the root name servers has some + significant advantages: + 1. Faster local resolution for your users + 2. No spurious traffic will be sent from your network to the roots + 3. Greater resilience to any potential root server failure/DDoS + + On the other hand, this method requires more monitoring than the + hints file to be sure that an unexpected failure mode has not + incapacitated your server. Name servers that are serving a lot + of clients will benefit more from this approach than individual + hosts. Use with caution. + + To use this mechanism, uncomment the entries below, and comment + the hint zone above. + + As documented at http://dns.icann.org/services/axfr/ these zones: + "." (the root), ARPA, IN-ADDR.ARPA, IP6.ARPA, and ROOT-SERVERS.NET + are available for AXFR from these servers on IPv4 and IPv6: + xfr.lax.dns.icann.org, xfr.cjr.dns.icann.org +*/ +/* +zone "." { + type slave; + file "/etc/namedb/slave/root.slave"; + masters { + 192.5.5.241; // F.ROOT-SERVERS.NET. + }; + notify no; +}; +zone "arpa" { + type slave; + file "/etc/namedb/slave/arpa.slave"; + masters { + 192.5.5.241; // F.ROOT-SERVERS.NET. + }; + notify no; +}; +*/ + +/* Serving the following zones locally will prevent any queries + for these zones leaving your network and going to the root + name servers. This has two significant advantages: + 1. Faster local resolution for your users + 2. No spurious traffic will be sent from your network to the roots +*/ +// RFCs 1912 and 5735 (and BCP 32 for localhost) +zone "localhost" { type master; file "/etc/namedb/master/localhost-forward.db"; }; +zone "127.in-addr.arpa" { type master; file "/etc/namedb/master/localhost-reverse.db"; }; +zone "255.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// RFC 1912-style zone for IPv6 localhost address +zone "0.ip6.arpa" { type master; file "/etc/namedb/master/localhost-reverse.db"; }; + +// "This" Network (RFCs 1912 and 5735) +zone "0.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// Private Use Networks (RFCs 1918 and 5735) +zone "10.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "16.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "17.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "18.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "19.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "20.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "21.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "22.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "23.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "24.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "25.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "26.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "27.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "28.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "29.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "30.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "31.172.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "168.192.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// Link-local/APIPA (RFCs 3927 and 5735) +zone "254.169.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// IETF protocol assignments (RFCs 5735 and 5736) +zone "0.0.192.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// TEST-NET-[1-3] for Documentation (RFCs 5735 and 5737) +zone "2.0.192.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "100.51.198.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "113.0.203.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// IPv6 Range for Documentation (RFC 3849) +zone "8.b.d.0.1.0.0.2.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// Domain Names for Documentation and Testing (BCP 32) +zone "test" { type master; file "/etc/namedb/master/empty.db"; }; +zone "example" { type master; file "/etc/namedb/master/empty.db"; }; +zone "invalid" { type master; file "/etc/namedb/master/empty.db"; }; +zone "example.com" { type master; file "/etc/namedb/master/empty.db"; }; +zone "example.net" { type master; file "/etc/namedb/master/empty.db"; }; +zone "example.org" { type master; file "/etc/namedb/master/empty.db"; }; + +// Router Benchmark Testing (RFCs 2544 and 5735) +zone "18.198.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "19.198.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// IANA Reserved - Old Class E Space (RFC 5735) +zone "240.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "241.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "242.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "243.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "244.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "245.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "246.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "247.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "248.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "249.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "250.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "251.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "252.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "253.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "254.in-addr.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// IPv6 Unassigned Addresses (RFC 4291) +zone "1.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "3.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "4.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "5.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "6.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "7.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "8.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "9.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "a.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "b.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "c.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "d.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "e.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "0.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "1.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "2.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "3.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "4.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "5.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "6.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "7.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "8.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "9.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "a.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "b.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "0.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "1.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "2.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "3.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "4.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "5.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "6.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "7.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// IPv6 ULA (RFC 4193) +zone "c.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "d.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// IPv6 Link Local (RFC 4291) +zone "8.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "9.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "a.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "b.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// IPv6 Deprecated Site-Local Addresses (RFC 3879) +zone "c.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "d.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "e.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; +zone "f.e.f.ip6.arpa" { type master; file "/etc/namedb/master/empty.db"; }; + +// IP6.INT is Deprecated (RFC 4159) +zone "ip6.int" { type master; file "/etc/namedb/master/empty.db"; }; + +// NB: Do not use the IP addresses below, they are faked, and only +// serve demonstration/documentation purposes! +// +// Example slave zone config entries. It can be convenient to become +// a slave at least for the zone your own domain is in. Ask +// your network administrator for the IP address of the responsible +// master name server. +// +// Do not forget to include the reverse lookup zone! +// This is named after the first bytes of the IP address, in reverse +// order, with ".IN-ADDR.ARPA" appended, or ".IP6.ARPA" for IPv6. +// +// Before starting to set up a master zone, make sure you fully +// understand how DNS and BIND work. There are sometimes +// non-obvious pitfalls. Setting up a slave zone is usually simpler. +// +// NB: Don't blindly enable the examples below. :-) Use actual names +// and addresses instead. + +/* An example dynamic zone +key "exampleorgkey" { + algorithm hmac-md5; + secret "sf87HJqjkqh8ac87a02lla=="; +}; +zone "example.org" { + type master; + allow-update { + key "exampleorgkey"; + }; + file "/etc/namedb/dynamic/example.org"; +}; +*/ + +/* Example of a slave reverse zone +zone "1.168.192.in-addr.arpa" { + type slave; + file "/etc/namedb/slave/1.168.192.in-addr.arpa"; + masters { + 192.168.1.1; + }; +}; +*/</programlisting> + + <para>In <filename>named.conf</filename>, these are examples + of slave entries for a forward and reverse zone.</para> + + <para>For each new zone served, a new zone entry must be added + to <filename>named.conf</filename>.</para> + + <para>For example, the simplest zone entry for + <hostid role="domainname">example.org</hostid> can look + like:</para> + + <programlisting>zone "example.org" { + type master; + file "master/example.org"; +};</programlisting> + + <para>The zone is a master, as indicated by the + <option>type</option> statement, holding its zone + information in + <filename>/etc/namedb/master/example.org</filename> + indicated by the <option>file</option> statement.</para> + + <programlisting>zone "example.org" { + type slave; + file "slave/example.org"; +};</programlisting> + + <para>In the slave case, the zone information is transferred + from the master name server for the particular zone, and + saved in the file specified. If and when the master server + dies or is unreachable, the slave name server will have the + transferred zone information and will be able to serve + it.</para> + </sect3> + + <sect3> + <title>Zone Files</title> + <indexterm> + <primary>BIND</primary> + <secondary>zone files</secondary> + </indexterm> + + <para>An example master zone file for <hostid + role="domainname">example.org</hostid> (existing within + <filename>/etc/namedb/master/example.org</filename>) is as + follows:</para> + + <programlisting>$TTL 3600 ; 1 hour default TTL +example.org. IN SOA ns1.example.org. admin.example.org. ( + 2006051501 ; Serial + 10800 ; Refresh + 3600 ; Retry + 604800 ; Expire + 300 ; Negative Response TTL + ) + +; DNS Servers + IN NS ns1.example.org. + IN NS ns2.example.org. + +; MX Records + IN MX 10 mx.example.org. + IN MX 20 mail.example.org. + + IN A 192.168.1.1 + +; Machine Names +localhost IN A 127.0.0.1 +ns1 IN A 192.168.1.2 +ns2 IN A 192.168.1.3 +mx IN A 192.168.1.4 +mail IN A 192.168.1.5 + +; Aliases +www IN CNAME example.org.</programlisting> + + <para>Note that every hostname ending in a <quote>.</quote> is + an exact hostname, whereas everything without a trailing + <quote>.</quote> is relative to the origin. For example, + <literal>ns1</literal> is translated into + <literal>ns1.<replaceable>example.org.</replaceable></literal></para> + + <para>The format of a zone file follows:</para> + + <programlisting>recordname IN recordtype value</programlisting> + + <indexterm> + <primary>DNS</primary> + <secondary>records</secondary> + </indexterm> + + <para>The most commonly used DNS records:</para> + + <variablelist> + <varlistentry> + <term>SOA</term> + + <listitem><para>start of zone authority</para></listitem> + </varlistentry> + + <varlistentry> + <term>NS</term> + + <listitem> + <para>an authoritative name server</para> + </listitem></varlistentry> + + <varlistentry> + <term>A</term> + + <listitem><para>a host address</para></listitem> + </varlistentry> + + <varlistentry> + <term>CNAME</term> + + <listitem><para>the canonical name for an + alias</para></listitem> + </varlistentry> + + <varlistentry> + <term>MX</term> + + <listitem><para>mail exchanger</para></listitem> + </varlistentry> + + <varlistentry> + <term>PTR</term> + + <listitem> + <para>a domain name pointer (used in reverse + DNS)</para> + </listitem> + </varlistentry> + </variablelist> + + <programlisting>example.org. IN SOA ns1.example.org. admin.example.org. ( + 2006051501 ; Serial + 10800 ; Refresh after 3 hours + 3600 ; Retry after 1 hour + 604800 ; Expire after 1 week + 300 ) ; Negative Response TTL</programlisting> + + <variablelist> + <varlistentry> + <term><hostid + role="domainname">example.org.</hostid></term> + + <listitem> + <para>the domain name, also the origin for this + zone file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><hostid role="fqdn">ns1.example.org.</hostid></term> + + <listitem> + <para>the primary/authoritative name server for this + zone.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>admin.example.org.</literal></term> + + <listitem> + <para>the responsible person for this zone, + email address with <quote>@</quote> + replaced. (<email>admin@example.org</email> becomes + <literal>admin.example.org</literal>)</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>2006051501</literal></term> + + <listitem> + <para>the serial number of the file. This + must be incremented each time the zone file is + modified. Nowadays, many admins prefer a + <literal>yyyymmddrr</literal> format for the serial + number. <literal>2006051501</literal> would mean + last modified 05/15/2006, the latter + <literal>01</literal> being the first time the zone + file has been modified this day. The serial number + is important as it alerts slave name servers for a + zone when it is updated.</para> + </listitem> + </varlistentry> + </variablelist> + + <programlisting> IN NS ns1.example.org.</programlisting> + + <para>This is an NS entry. Every name server that is going to + reply authoritatively for the zone must have one of these + entries.</para> + + <programlisting>localhost IN A 127.0.0.1 +ns1 IN A 192.168.1.2 +ns2 IN A 192.168.1.3 +mx IN A 192.168.1.4 +mail IN A 192.168.1.5</programlisting> + + <para>The A record indicates machine names. As seen above, + <hostid role="fqdn">ns1.example.org</hostid> would resolve + to <hostid role="ipaddr">192.168.1.2</hostid>.</para> + + <programlisting> IN A 192.168.1.1</programlisting> + + <para>This line assigns IP address <hostid + role="ipaddr">192.168.1.1</hostid> to the current origin, + in this case <hostid + role="domainname">example.org</hostid>.</para> + + <programlisting>www IN CNAME @</programlisting> + + <para>The canonical name record is usually used for giving + aliases to a machine. In the example, <hostid>www</hostid> + is aliased to the <quote>master</quote> machine whose name + happens to be the same as the domain name <hostid + role="domainname">example.org</hostid> (<hostid + role="ipaddr">192.168.1.1</hostid>). CNAMEs can never be + used together with another kind of record + for the same hostname.</para> + + <indexterm> + <primary>MX record</primary> + </indexterm> + + <programlisting> IN MX 10 mail.example.org.</programlisting> + + <para>The MX record indicates which mail + servers are responsible for handling incoming mail for the + zone. <hostid role="fqdn">mail.example.org</hostid> is the + hostname of a mail server, and 10 is the priority of + that mail server.</para> + + <para>One can have several mail servers, with priorities of + 10, 20 and so on. A mail server attempting to deliver to + <hostid role="domainname">example.org</hostid> would first + try the highest priority MX (the record with the lowest + priority number), then the second highest, etc, until the + mail can be properly delivered.</para> + + <para>For in-addr.arpa zone files (reverse DNS), the same + format is used, except with PTR entries instead of A or + CNAME.</para> + + <programlisting>$TTL 3600 + +1.168.192.in-addr.arpa. IN SOA ns1.example.org. admin.example.org. ( + 2006051501 ; Serial + 10800 ; Refresh + 3600 ; Retry + 604800 ; Expire + 300 ) ; Negative Response TTL + + IN NS ns1.example.org. + IN NS ns2.example.org. + +1 IN PTR example.org. +2 IN PTR ns1.example.org. +3 IN PTR ns2.example.org. +4 IN PTR mx.example.org. +5 IN PTR mail.example.org.</programlisting> + + <para>This file gives the proper IP address to hostname + mappings for the above fictitious domain.</para> + + <para>It is worth noting that all names on the right side + of a PTR record need to be fully qualified (i.e., end in + a <quote>.</quote>).</para> + </sect3> + </sect2> + + <sect2> + <title>Caching Name Server</title> + <indexterm> + <primary>BIND</primary> + <secondary>caching name server</secondary> + </indexterm> + + <para>A caching name server is a name server whose primary role + is to resolve recursive queries. It simply asks queries of + its own, and remembers the answers for later use.</para> + </sect2> + + <sect2> + <title><acronym + role="Domain Name Security Extensions">DNSSEC</acronym></title> + <indexterm> + <primary>BIND</primary> + <secondary>DNS security extensions</secondary> + </indexterm> + + <para>Domain Name System Security Extensions, or <acronym + role="Domain Name Security Extensions">DNSSEC</acronym> for + short, is a suite of specifications to protect resolving name + servers from forged <acronym>DNS</acronym> data, such as + spoofed <acronym>DNS</acronym> records. By using digital + signatures, a resolver can verify the integrity of the record. + Note that <acronym + role="Domain Name Security Extensions">DNSSEC</acronym> only + provides integrity via digitally signing the Resource + Records (<acronym role="Resource Record">RR</acronym>s). It + provides neither confidentiality nor protection against false + end-user assumptions. This means that it cannot protect + against people going to <hostid + role="domainname">example.net</hostid> instead of <hostid + role="domainname">example.com</hostid>. The only thing + <acronym>DNSSEC</acronym> does is authenticate that the data + has not been compromised in transit. The security of + <acronym>DNS</acronym> is an important step in securing the + Internet in general. For more in-depth details of how + <acronym>DNSSEC</acronym> works, the relevant + <acronym>RFC</acronym>s are a good place to start. See the + list in <xref linkend="dns-read">.</para> + + <para>The following sections will demonstrate how to enable + <acronym>DNSSEC</acronym> for an authoritative + <acronym>DNS</acronym> server and a recursive (or caching) + <acronym>DNS</acronym> server running <acronym>BIND</acronym> + 9. While all versions of <acronym>BIND</acronym> 9 support + <acronym>DNSSEC</acronym>, it is necessary to have at least + version 9.6.2 in order to be able to use the signed root zone + when validating <acronym>DNS</acronym> queries. This is + because earlier versions lack the required algorithms to + enable validation using the root zone key. It is strongly + recommended to use the latest version of + <acronym>BIND</acronym> 9.7 or later to take advantage of + automatic key updating for the root key, as well as other + features to automatically keep zones signed and signatures up + to date. Where configurations differ between 9.6.2 and 9.7 + and later, differences will be pointed out.</para> + + <sect3> + <title>Recursive <acronym>DNS</acronym> Server + Configuration</title> + + <para>Enabling <acronym>DNSSEC</acronym> validation of queries + performed by a recursive <acronym>DNS</acronym> server + requires a few changes to <filename>named.conf</filename>. + Before making these changes the root zone key, or trust + anchor, must be acquired. Currently the root zone key is + not available in a file format <acronym>BIND</acronym> + understands, so it has to be manually converted into the + proper format. The key itself can be obtained by querying + the root zone for it using <application>dig</application>. + By running</para> + + <screen>&prompt.user; <userinput>dig +multi +noall +answer DNSKEY . > root.dnskey</userinput></screen> + + <para>the key will end up in <filename>root.dnskey</filename>. + The contents should look something like this:</para> + + <programlisting>. 93910 IN DNSKEY 257 3 8 ( + AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQ + bSEW0O8gcCjFFVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh + /RStIoO8g0NfnfL2MTJRkxoXbfDaUeVPQuYEhg37NZWA + JQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaDX6RS6CXp + oY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3 + LQpzW5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGO + Yl7OyQdXfZ57relSQageu+ipAdTTJ25AsRTAoub8ONGc + LmqrAmRLKBP1dfwhYB4N7knNnulqQxA+Uk1ihz0= + ) ; key id = 19036 +. 93910 IN DNSKEY 256 3 8 ( + AwEAAcaGQEA+OJmOzfzVfoYN249JId7gx+OZMbxy69Hf + UyuGBbRN0+HuTOpBxxBCkNOL+EJB9qJxt+0FEY6ZUVjE + g58sRr4ZQ6Iu6b1xTBKgc193zUARk4mmQ/PPGxn7Cn5V + EGJ/1h6dNaiXuRHwR+7oWh7DnzkIJChcTqlFrXDW3tjt +) ; key id = 34525</programlisting> + + <para>Do not be alarmed if the obtained keys differ from this + example. They might have changed since these instructions + were last updated. This output actually contains two keys. + The first key in the listing, with the value 257 after the + DNSKEY record type, is the one needed. This value indicates + that this is a Secure Entry Point (<acronym + role="Secure Entry Point">SEP</acronym>), commonly known + as a Key Signing Key (<acronym + role="Key Signing Key">KSK</acronym>). The second key, + with value 256, is a subordinate key, commonly called a Zone + Signing Key (<acronym + role="Zone Signing Key">ZSK</acronym>). More on the + different key types later in <xref + linkend="dns-dnssec-auth">.</para> + + <para>Now the key must be verified and formatted so that + <acronym>BIND</acronym> can use it. To verify the key, + generate a <acronym role="Delegation Signer">DS</acronym> + <acronym role="Resource Record">RR</acronym> set. Create a + file containing these <acronym + role="Resource Record">RR</acronym>s with</para> + + <screen>&prompt.user; <userinput>dnssec-dsfromkey -f root-dnskey . > root.ds</userinput></screen> + + <para>These records use SHA-1 and SHA-256 respectively, and + should look similar to the following example, where the + longer is using SHA-256.</para> + + <programlisting>. IN DS 19036 8 1 + B256BD09DC8DD59F0E0F0D8541B8328DD986DF6E +. IN DS 19036 8 2 49AAC11D7B6F6446702E54A1607371607A1A41855200FD2CE1CDDE32F24E8FB5</programlisting> + + <para>The SHA-256 <acronym>RR</acronym> can now be compared to + the digest in <ulink + url="https://data.iana.org/root-anchors/root-anchors.xml">https://data.iana.org/root-anchors/root-anchors.xml</ulink>. + To be absolutely sure that the key has not been tampered + with the data in the <acronym>XML</acronym> file can be + verified using the <acronym>PGP</acronym> signature in + <ulink + url="https://data.iana.org/root-anchors/root-anchors.asc">https://data.iana.org/root-anchors/root-anchors.asc</ulink>.</para> + + <para>Next, the key must be formatted properly. This differs + a little between <acronym>BIND</acronym> versions 9.6.2 and + 9.7 and later. In version 9.7 support was added to + automatically track changes to the key and update it as + necessary. This is done using + <literal>managed-keys</literal> as seen in the example + below. When using the older version, the key is added using + a <literal>trusted-keys</literal> statement and updates must + be done manually. For <acronym>BIND</acronym> 9.6.2 the + format should look like:</para> + + <programlisting>trusted-keys { + "." 257 3 8 + "AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjF + FVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoX + bfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaD + X6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpz + W5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relS + Qageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulq + QxA+Uk1ihz0="; +};</programlisting> + + <para>For 9.7 the format will instead be:</para> + + <programlisting>managed-keys { + "." initial-key 257 3 8 + "AwEAAagAIKlVZrpC6Ia7gEzahOR+9W29euxhJhVVLOyQbSEW0O8gcCjF + FVQUTf6v58fLjwBd0YI0EzrAcQqBGCzh/RStIoO8g0NfnfL2MTJRkxoX + bfDaUeVPQuYEhg37NZWAJQ9VnMVDxP/VHL496M/QZxkjf5/Efucp2gaD + X6RS6CXpoY68LsvPVjR0ZSwzz1apAzvN9dlzEheX7ICJBBtuA6G3LQpz + W5hOA2hzCTMjJPJ8LbqF6dsV6DoBQzgul0sGIcGOYl7OyQdXfZ57relS + Qageu+ipAdTTJ25AsRTAoub8ONGcLmqrAmRLKBP1dfwhYB4N7knNnulq + QxA+Uk1ihz0="; +};</programlisting> + + <para>The root key can now be added to + <filename>named.conf</filename> either directly or by + including a file containing the key. After these steps, + configure <acronym>BIND</acronym> to do + <acronym>DNSSEC</acronym> validation on queries by editing + <filename>named.conf</filename> and adding the following to + the <literal>options</literal> directive:</para> + + <programlisting>dnssec-enable yes; +dnssec-validation yes;</programlisting> + + <para>To verify that it is actually working use + <application>dig</application> to make a query for a signed + zone using the resolver just configured. A successful reply + will contain the <literal>AD</literal> flag to indicate the + data was authenticated. Running a query such as</para> + + <screen>&prompt.user; <userinput>dig @<replaceable>resolver</replaceable> +dnssec se ds </userinput></screen> + + <para>should return the <acronym>DS</acronym> + <acronym>RR</acronym> for the <literal>.se</literal> zone. + In the <literal>flags:</literal> section the + <literal>AD</literal> flag should be set, as seen + in:</para> + + <programlisting>... +;; flags: qr rd ra ad; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 1 +...</programlisting> + + <para>The resolver is now capable of authenticating + <acronym>DNS</acronym> queries.</para> + </sect3> + + <sect3 id="dns-dnssec-auth"> + <title>Authoritative <acronym>DNS</acronym> Server + Configuration</title> + + <para>In order to get an authoritative name server to serve a + <acronym>DNSSEC</acronym> signed zone a little more work is + required. A zone is signed using cryptographic keys which + must be generated. It is possible to use only one key for + this. The preferred method however is to have a strong + well-protected Key Signing Key (<acronym + role="Key Signing Key">KSK</acronym>) that is + not rotated very often and a Zone Signing Key (<acronym + role="Zone Signing Key">ZSK</acronym>) that is rotated more + frequently. Information on recommended operational + practices can be found in <ulink + url="http://tools.ietf.org/rfc/rfc4641.txt"><acronym>RFC</acronym> + 4641: <acronym>DNSSEC</acronym> Operational + Practices</ulink>. Practices regarding the root zone can + be found in <ulink + url="http://www.root-dnssec.org/wp-content/uploads/2010/06/icann-dps-00.txt"><acronym>DNSSEC</acronym> + Practice Statement for the Root Zone + <acronym>KSK</acronym> operator</ulink> and <ulink + url="http://www.root-dnssec.org/wp-content/uploads/2010/06/vrsn-dps-00.txt"><acronym>DNSSEC</acronym> + Practice Statement for the Root Zone + <acronym>ZSK</acronym> operator</ulink>. The <acronym + role="Key Signing Key">KSK</acronym> is used to build a + chain of authority to the data in need of validation and as + such is also called a Secure Entry Point (<acronym + role="Secure Entry Point">SEP</acronym>) key. A message + digest of this key, called a Delegation Signer (<acronym + role="Delegation Signer">DS</acronym>) record, must be + published in the parent zone to establish the trust chain. + How this is accomplished depends on the parent zone owner. + The <acronym + role="Zone Signing Key">ZSK</acronym> is used to sign the + zone, and only needs to be published there.</para> + + <para>To enable <acronym>DNSSEC</acronym> for the <hostid + role="domainname">example.com</hostid> zone depicted in + previous examples, the first step is to use + <application>dnssec-keygen</application> to generate the + <acronym>KSK</acronym> and <acronym>ZSK</acronym> key pair. + This key pair can utilize different cryptographic + algorithms. It is recommended to use RSA/SHA256 for the + keys and 2048 bits key length should be enough. To generate + the <acronym>KSK</acronym> for <hostid + role="domainname">example.com</hostid>, run</para> + + <screen>&prompt.user; <userinput>dnssec-keygen -f KSK -a RSASHA256 -b 2048 -n ZONE example.com</userinput></screen> + + <para>and to generate the <acronym>ZSK</acronym>, run</para> + + <screen>&prompt.user; <userinput>dnssec-keygen -a RSASHA256 -b 2048 -n ZONE example.com</userinput></screen> + + <para><application>dnssec-keygen</application> outputs two + files, the public and the private keys in files named + similar to <filename>Kexample.com.+005+nnnnn.key</filename> + (public) and + <filename>Kexample.com.+005+nnnnn.private</filename> + (private). The <literal>nnnnn</literal> part of the file + name is a five digit key ID. Keep track of which key ID + belongs to which key. This is especially important when + having more than one key in a zone. It is + also possible to rename the keys. For each + <acronym>KSK</acronym> file do:</para> + + <screen>&prompt.user; <userinput>mv Kexample.com.+005+nnnnn.key Kexample.com.+005+nnnnn.KSK.key</userinput> +&prompt.user; <userinput>mv Kexample.com.+005+nnnnn.private Kexample.com.+005+nnnnn.KSK.private</userinput></screen> + + <para>For the <acronym>ZSK</acronym> files, substitute + <literal>KSK</literal> for <literal>ZSK</literal> as + necessary. The files can now be included in the zone file, + using the <literal>$include</literal> statement. It should + look something like this:</para> + + <programlisting>$include Kexample.com.+005+nnnnn.KSK.key ; KSK +$include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> + + <para>Finally, sign the zone and tell <acronym>BIND</acronym> + to use the signed zone file. To sign a zone + <application>dnssec-signzone</application> is used. The + command to sign the zone <hostid + role="domainname">example.com</hostid>, located in + <filename>example.com.db</filename> would look similar + to</para> + + <screen>&prompt.user; <userinput>dnssec-signzone -o + example.com -k Kexample.com.+005+nnnnn.KSK example.com.db + Kexample.com.+005+nnnnn.ZSK.key</userinput></screen> + + <para>The key supplied to the <option>-k</option> argument is + the <acronym>KSK</acronym> and the other key file is the + <acronym>ZSK</acronym> that should be used in the signing. + It is possible to supply more than one + <acronym>KSK</acronym> and <acronym>ZSK</acronym>, which + will result in the zone being signed with all supplied keys. + This can be needed to supply zone data signed using more + than one algorithm. The output of + <application>dnssec-signzone</application> is a zone file + with all <acronym>RR</acronym>s signed. This output will + end up in a file with the extension + <literal>.signed</literal>, such as + <filename>example.com.db.signed</filename>. The <acronym + role="Delegation Signer">DS</acronym> records will also be + written to a separate file + <filename>dsset-example.com</filename>. + To use this signed zone just modify the zone directive in + <filename>named.conf</filename> to use + <filename>example.com.db.signed</filename>. By default, the + signatures are only valid 30 days, meaning that the zone + needs to be resigned in about 15 days to be sure that + resolvers are not caching records with stale signatures. It + is possible to make a script and a cron job to do this. See + relevant manuals for details.</para> + + <para>Be sure to keep private keys confidential, as with all + cryptographic keys. When changing a key it is best to + include the new key into the zone, while still signing with + the old one, and then move over to using the new key to + sign. After these steps are done the old key can be removed + from the zone. Failure to do this might render the + <acronym>DNS</acronym> data unavailable for a time, until + the new key has propagated through the + <acronym>DNS</acronym> hierarchy. For more information on + key rollovers and other <acronym>DNSSEC</acronym> + operational issues, see <ulink + url="http://www.ietf.org/rfc/rfc4641.txt"><acronym>RFC</acronym> + 4641: <acronym>DNSSEC</acronym> Operational + practices</ulink>.</para> + </sect3> + + <sect3> + <title>Automation Using <acronym>BIND</acronym> 9.7 or + Later</title> + + <para>Beginning with <acronym>BIND</acronym> version 9.7 a new + feature called <emphasis>Smart Signing</emphasis> was + introduced. This feature aims to make the key management + and signing process simpler by automating parts of the task. + By putting the keys into a directory called a <emphasis>key + repository</emphasis>, and using the new option + <literal>auto-dnssec</literal>, it is possible to create a + dynamic zone which will be resigned as needed. To update + this zone use <application>nsupdate</application> with the + new option <option>-l</option>. + <application>rndc</application> has also grown the ability + to sign zones with keys in the key repository, using the + option <option>sign</option>. To tell + <acronym>BIND</acronym> to use this automatic signing and + zone updating for <hostid + role="domainname">example.com</hostid>, add the following + to <filename>named.conf</filename>:</para> + + <programlisting>zone example.com { + type master; + key-directory "/etc/named/keys"; + update-policy local; + auto-dnssec maintain; + file "/etc/named/dynamic/example.com.zone"; +};</programlisting> + + <para>After making these changes, generate keys for the zone + as explained in <xref linkend="dns-dnssec-auth">, put those + keys in the key repository given as the argument to the + <literal>key-directory</literal> in the zone configuration + and the zone will be signed automatically. Updates to a + zone configured this way must be done using + <application>nsupdate</application>, which will take care of + re-signing the zone with the new data added. For further + details, see <xref linkend="dns-read"> and the + <acronym>BIND</acronym> documentation.</para> + </sect3> + </sect2> + + <sect2> + <title>Security</title> + + <para>Although BIND is the most common implementation of DNS, + there is always the issue of security. Possible and + exploitable security holes are sometimes found.</para> + + <para>While &os; automatically drops + <application>named</application> into a &man.chroot.8; + environment; there are several other security mechanisms in + place which could help to lure off possible + <acronym>DNS</acronym> service attacks.</para> + + <para>It is always good idea to read <ulink + url="http://www.cert.org/">CERT</ulink>'s security + advisories and to subscribe to the &a.security-notifications; + to stay up to date with the current Internet and &os; security + issues.</para> + + <tip> + <para>If a problem arises, keeping sources up to date and + having a fresh build of <application>named</application> + may help.</para> + </tip> + </sect2> + + <sect2 id="dns-read"> + <title>Further Reading</title> + + <para>BIND/<application>named</application> manual pages: + &man.rndc.8; &man.named.8; &man.named.conf.5; &man.nsupdate.8; + &man.dnssec-signzone.8; &man.dnssec-keygen.8;</para> + + <itemizedlist> + <listitem> + <para><ulink + url="https://www.isc.org/software/bind">Official ISC + BIND Page</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="https://www.isc.org/software/guild">Official ISC + BIND Forum</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://www.oreilly.com/catalog/dns5/">O'Reilly + DNS and BIND 5th Edition</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://www.root-dnssec.org/documentation/">Root + <acronym>DNSSEC</acronym></ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://data.iana.org/root-anchors/draft-icann-dnssec-trust-anchor.html"><acronym>DNSSEC</acronym> + Trust Anchor Publication for the Root + Zone</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://tools.ietf.org/html/rfc1034">RFC1034 + - Domain Names - Concepts and Facilities</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://tools.ietf.org/html/rfc1035">RFC1035 + - Domain Names - Implementation and + Specification</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://tools.ietf.org/html/rfc4033">RFC4033 + - DNS Security Introduction and + Requirements</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://tools.ietf.org/html/rfc4034">RFC4034 + - Resource Records for the DNS Security + Extensions</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://tools.ietf.org/html/rfc4035">RFC4035 + - Protocol Modifications for the DNS Security + Extensions</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://tools.ietf.org/html/rfc4641">RFC4641 + - DNSSEC Operational Practices</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://tools.ietf.org/html/rfc5011">RFC 5011 + - Automated Updates of DNS Security + (<acronym>DNSSEC</acronym> + Trust Anchors</ulink></para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="network-apache"> + <sect1info> + <authorgroup> + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Apache HTTP Server</title> + + <indexterm><primary>web servers</primary> + <secondary>setting up</secondary></indexterm> + <indexterm><primary>Apache</primary></indexterm> + + <sect2> + <title>Overview</title> + + <para>&os; is used to run some of the busiest web sites in the + world. The majority of web servers on the Internet are using + the <application>Apache HTTP Server</application>. + <application>Apache</application> software packages should be + included on your FreeBSD installation media. If you did not + install <application>Apache</application> when you first + installed FreeBSD, then you can install it from the <filename + role="package">www/apache22</filename> port.</para> + + <para>Once <application>Apache</application> has been installed + successfully, it must be configured.</para> + + <note><para>This section covers version 2.2.X of the + <application>Apache HTTP Server</application> as that is the + most widely used version for &os;. For more detailed + information beyond the scope of this document about + <application>Apache</application> 2.X, please see <ulink + url="http://httpd.apache.org/"></ulink>.</para></note> + + </sect2> + + <sect2> + <title>Configuration</title> + + <indexterm><primary>Apache</primary> + <secondary>configuration file</secondary></indexterm> + + <para>The main <application>Apache HTTP Server</application> + configuration file is installed as + <filename>/usr/local/etc/apache22/httpd.conf</filename> on + &os;. This file is a typical &unix; text configuration file + with comment lines beginning with the <literal>#</literal> + character. A comprehensive description of all possible + configuration options is outside the scope of this book, so + only the most frequently modified directives will be described + here.</para> + + <variablelist> + <varlistentry> + <term><literal>ServerRoot "/usr/local"</literal></term> + + <listitem> + <para>This specifies the default directory hierarchy for + the <application>Apache</application> installation. + Binaries are stored in the <filename + class="directory">bin</filename> and + <filename + class="directory">sbin</filename> subdirectories + of the server root, and configuration files are stored + in <filename + class="directory">etc/apache</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ServerAdmin you@your.address</literal></term> + + <listitem> + <para>The address to which problems with the server should + be emailed. This address appears on some + server-generated pages, such as error documents.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ServerName www.example.com</literal></term> + + <listitem> + <para><literal>ServerName</literal> allows you to set a + host name which is sent back to clients for your server + if it is different than the one that the host is + configured with (i.e., use <hostid>www</hostid> instead + of the host's real name).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>DocumentRoot + "/usr/local/www/apache22/data"</literal></term> + + <listitem> + <para><literal>DocumentRoot</literal>: The directory out + of which you will serve your documents. By default, all + requests are taken from this directory, but symbolic + links and aliases may be used to point to other + locations.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>It is always a good idea to make backup copies of your + <application>Apache</application> configuration file before + making changes. Once you are satisfied with your initial + configuration you are ready to start running + <application>Apache</application>.</para> + </sect2> + + <sect2> + <title>Running <application>Apache</application></title> + + <indexterm><primary>Apache</primary> + <secondary>starting or stopping</secondary></indexterm> + + <para>The <filename role="package">www/apache22</filename> port + installs an &man.rc.8; script to aid in starting, stopping, + and restarting <application>Apache</application>, which can be + found in the <filename + class="directory">/usr/local/etc/rc.d/</filename> + directory.</para> + + <para>To launch <application>Apache</application> at system + startup, add the following line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>apache22_enable="YES"</programlisting> + + <para>If <application>Apache</application> should be started + with non-default options, the following line may be added to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>apache22_flags=""</programlisting> + + <para>The <application>Apache</application> configuration can be + tested for errors before starting the <command>httpd</command> + daemon for the first time, or after making subsequent + configuration changes while <command>httpd</command> is + running. This can be done by the &man.rc.8; script directly, + or by the &man.service.8; utility by issuing one of the + following commands:</para> + + <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/apache22 configtest</userinput></screen> + <screen>&prompt.root; <userinput>service apache22 configtest</userinput></screen> + + <note> + <para>It is important to note that the + <literal>configtest</literal> is not an &man.rc.8; standard, + and should not be expected to work for all &man.rc.8; + startup scripts.</para> + </note> + + <para>If <application>Apache</application> does not report + configuration errors, the + <application>Apache</application> <command>httpd</command> + can be started with the same &man.rc.8; and &man.service.8; + mechanisms:</para> + + <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/apache22 start</userinput></screen> + <screen>&prompt.root; <userinput>service apache22 start</userinput></screen> + + <para>The <command>httpd</command> service can be tested by + entering <literal>http://<hostid + role="fqdn"><replaceable>localhost</replaceable></hostid></literal> + in a web browser, replacing + <replaceable>localhost</replaceable> with the fully-qualified + domain name of the machine running <command>httpd</command>, + if it is not the local machine. The default web page that is + displayed is + <filename>/usr/local/www/apache22/data/index.html</filename>.</para> + + </sect2> + + <sect2> + <title>Virtual Hosting</title> + + <para><application>Apache</application> supports two different + types of Virtual Hosting. The first method is Name-based + Virtual Hosting. Name-based virtual hosting uses the clients + HTTP/1.1 headers to figure out the hostname. This allows many + different domains to share the same IP address.</para> + + <para>To setup <application>Apache</application> to use + Name-based Virtual Hosting add an entry like the following to + your <filename>httpd.conf</filename>:</para> + + <programlisting>NameVirtualHost *</programlisting> + + <para>If your webserver was named <hostid + role="fqdn">www.domain.tld</hostid> and you wanted to setup + a virtual domain for <hostid + role="fqdn">www.someotherdomain.tld</hostid> then you would + add the following entries to + <filename>httpd.conf</filename>:</para> + + <screen><VirtualHost *> +ServerName www.domain.tld +DocumentRoot /www/domain.tld +</VirtualHost> + +<VirtualHost *> +ServerName www.someotherdomain.tld +DocumentRoot /www/someotherdomain.tld +</VirtualHost></screen> + + <para>Replace the addresses with the addresses you want to use + and the path to the documents with what you are using.</para> + + <para>For more information about setting up virtual hosts, + please consult the official <application>Apache</application> + documentation at: <ulink + url="http://httpd.apache.org/docs/vhosts/"></ulink>.</para> + </sect2> + + <sect2> + <title>Apache Modules</title> + + <indexterm><primary>Apache</primary> + <secondary>modules</secondary></indexterm> + + <para>There are many different <application>Apache</application> + modules available to add functionality to the basic server. + The FreeBSD Ports Collection provides an easy way to install + <application>Apache</application> together with some of the + more popular add-on modules.</para> + + <sect3> + <title><application>mod_ssl</application></title> + + <indexterm><primary>web servers</primary> + <secondary>secure</secondary></indexterm> + <indexterm><primary>SSL</primary></indexterm> + <indexterm><primary>cryptography</primary></indexterm> + + <para>The <application>mod_ssl</application> module uses the + OpenSSL library to provide strong cryptography via the + Secure Sockets Layer (SSL v2/v3) and Transport Layer + Security (TLS v1) protocols. This module provides + everything necessary to request a signed certificate from + a trusted certificate signing authority so that you can run + a secure web server on &os;.</para> + + <para>The <application>mod_ssl</application> module is built + by default, but can be enabled by specifying + <literal>-DWITH_SSL</literal> at compile time.</para> + </sect3> + + <sect3> + <title>Language Bindings</title> + + <para>There are Apache modules for most major scripting + languages. These modules typically make it possible to + write <application>Apache</application> modules entirely in + a scripting language. They are also often used as a + persistent interpreter embedded into the server that avoids + the overhead of starting an external interpreter and the + startup-time penalty for dynamic websites, as described in + the next section.</para> + </sect3> + </sect2> + + <sect2> + <title>Dynamic Websites</title> + + <indexterm><primary>web servers</primary> + <secondary>dynamic</secondary></indexterm> + + <para>In the last decade, more businesses have turned to the + Internet in order to enhance their revenue and increase + exposure. This has also increased the need for interactive + web content. While some companies, such as µsoft;, + have introduced solutions into their proprietary products, + the open source community answered the call. Modern options + for dynamic web content include Django, Ruby on Rails, + <application>mod_perl2</application>, and + <application>mod_php</application>.</para> + + <sect3> + <title>Django</title> + + <indexterm><primary>Python</primary></indexterm> + <indexterm><primary>Django</primary></indexterm> + + <para>Django is a BSD licensed framework designed to allow + developers to write high performance, elegant web + applications quickly. It provides an object-relational + mapper so that data types are developed as Python objects, + and a rich dynamic database-access API is provided for those + objects without the developer ever having to write SQL. It + also provides an extensible template system so that the + logic of the application is separated from the HTML + presentation.</para> + + <para>Django depends on <application>mod_python</application>, + <application>Apache</application>, and an SQL database + engine of your choice. The FreeBSD Port will install all of + these pre-requisites for you with the appropriate + flags.</para> + + <example id="network-www-django-install"> + <title>Installing Django with + <application>Apache2</application>, + <application>mod_python3</application>, and + <application>PostgreSQL</application></title> + + <screen>&prompt.root; <userinput>cd /usr/ports/www/py-django; make all install clean -DWITH_MOD_PYTHON3 -DWITH_POSTGRESQL</userinput></screen> + </example> + + <para>Once Django and these pre-requisites are installed, you + will need to create a Django project directory and then + configure Apache to use the embedded Python interpreter to + call your application for specific URLs on your site.</para> + + <example id="network-www-django-apache-config"> + <title>Apache Configuration for Django/mod_python</title> + + <para>You will need to add a line to the apache + <filename>httpd.conf</filename> file to configure Apache + to pass requests for certain URLs to your web + application:</para> + + <screen><Location "/"> + SetHandler python-program + PythonPath "['/dir/to/your/django/packages/'] + sys.path" + PythonHandler django.core.handlers.modpython + SetEnv DJANGO_SETTINGS_MODULE mysite.settings + PythonAutoReload On + PythonDebug On +</Location></screen> + </example> + </sect3> + + <sect3> + <title>Ruby on Rails</title> + + <indexterm><primary>Ruby on Rails</primary></indexterm> + + <para>Ruby on Rails is another open source web framework that + provides a full development stack and is optimized to make + web developers more productive and capable of writing + powerful applications quickly. It can be installed easily + from the ports system.</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/www/rubygem-rails; make all install clean</userinput></screen> + </sect3> + + <sect3> + <title><application>mod_perl2</application></title> + + <indexterm> + <primary>mod_perl2</primary> + <secondary>Perl</secondary> + </indexterm> + + <para>The <application>Apache</application>/Perl integration + project brings together the full power of the Perl + programming language and the + <application>Apache HTTP Server</application>. With the + <application>mod_perl2</application> module it is possible + to write <application>Apache</application> modules entirely + in Perl. In addition, the persistent interpreter embedded + in the server avoids the overhead of starting an external + interpreter and the penalty of Perl start-up time.</para> + + <para><application>mod_perl2</application> is available in the + <filename role="package">www/mod_perl2</filename> + port.</para> + </sect3> + + <sect3> + <sect3info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect3info> + <title><application>mod_php</application></title> + + <indexterm> + <primary>mod_php</primary> + <secondary>PHP</secondary> + </indexterm> + + <para><acronym>PHP</acronym>, also known as <quote>PHP: + Hypertext Preprocessor</quote> is a general-purpose + scripting language that is especially suited for Web + development. Capable of being embedded into + <acronym>HTML</acronym> its syntax draws upon C, &java;, + and Perl with the intention of allowing web developers to + write dynamically generated webpages quickly.</para> + + <para>To gain support for <acronym>PHP</acronym>5 for the + <application>Apache</application> web server, begin by + installing the + <filename role="package">lang/php5</filename> + port.</para> + + <para>If the <filename role="package">lang/php5</filename> + port is being installed for the first time, available + <literal>OPTIONS</literal> will be displayed automatically. + If a menu is not displayed, i.e., because the <filename + role="package">lang/php5</filename> port has been installed + some time in the past, it is always possible to bring the + options dialog up again by running:</para> + + <screen>&prompt.root; <userinput>make config</userinput></screen> + + <para>in the port directory.</para> + + <para>In the options dialog, check the + <literal>APACHE</literal> option to build + <application>mod_php5</application> as a loadable module for + the <application>Apache</application> web server.</para> + + <note> + <para>A lot of sites are still using <acronym>PHP</acronym>4 + for various reasons (i.e., compatibility issues or already + deployed web applications). If the + <application>mod_php4</application> is needed instead of + <application>mod_php5</application>, then please use the + <filename role="package">lang/php4</filename> port. The + <filename role="package">lang/php4</filename> port + supports many of the configuration and build-time options + of the <filename role="package">lang/php5</filename> + port.</para> + </note> + + <para>This will install and configure the modules required + to support dynamic <acronym>PHP</acronym> applications. + Check to ensure the following sections have been added to + <filename>/usr/local/etc/apache22/httpd.conf</filename>:</para> + + <programlisting>LoadModule php5_module libexec/apache/libphp5.so</programlisting> + + <programlisting>AddModule mod_php5.c + <IfModule mod_php5.c> + DirectoryIndex index.php index.html + </IfModule> + <IfModule mod_php5.c> + AddType application/x-httpd-php .php + AddType application/x-httpd-php-source .phps + </IfModule></programlisting> + + <para>Once completed, a simple call to the + <command>apachectl</command> command for a graceful + restart is needed to load the <acronym>PHP</acronym> + module:</para> + + <screen>&prompt.root; <userinput>apachectl graceful</userinput></screen> + + <para>For future upgrades of <acronym>PHP</acronym>, the + <command>make config</command> command will not be required; + the selected <literal>OPTIONS</literal> are saved + automatically by the &os; Ports framework.</para> + + <para>The <acronym>PHP</acronym> support in &os; is extremely + modular so the base install is very limited. It is very + easy to add support using the <filename + role="package">lang/php5-extensions</filename> port. + This port provides a menu driven interface to + <acronym>PHP</acronym> extension installation. + Alternatively, individual extensions can be installed using + the appropriate port.</para> + + <para>For instance, to add support for the + <application>MySQL</application> database server to + <acronym>PHP</acronym>5, simply install the port + <filename>databases/php5-mysql</filename>.</para> + + <para>After installing an extension, the + <application>Apache</application> server must be reloaded to + pick up the new configuration changes:</para> + + <screen>&prompt.root; <userinput>apachectl graceful</userinput></screen> + </sect3> + </sect2> + </sect1> + + <sect1 id="network-ftp"> + <sect1info> + <authorgroup> + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>File Transfer Protocol (FTP)</title> + + <indexterm><primary>FTP servers</primary></indexterm> + + <sect2> + <title>Overview</title> + + <para>The File Transfer Protocol (FTP) provides users with a + simple way to transfer files to and from an <acronym + role="File Transfer Protocol">FTP</acronym> server. &os; + includes <acronym role="File Transfer Protocol">FTP</acronym> + server software, <application>ftpd</application>, in the base + system. This makes setting up and administering an <acronym + role="File Transfer Protocol">FTP</acronym> server on FreeBSD + very straightforward.</para> + </sect2> + + <sect2> + <title>Configuration</title> + + <para>The most important configuration step is deciding which + accounts will be allowed access to the FTP server. A normal + FreeBSD system has a number of system accounts used for + various daemons, but unknown users should not be allowed to + log in with these accounts. The + <filename>/etc/ftpusers</filename> file is a list of users + disallowed any FTP access. By default, it includes the + aforementioned system accounts, but it is possible to add + specific users here that should not be allowed access to + FTP.</para> + + <para>You may want to restrict the access of some users without + preventing them completely from using FTP. This can be + accomplished with the <filename>/etc/ftpchroot</filename> + file. This file lists users and groups subject to FTP access + restrictions. The &man.ftpchroot.5; manual page has all of + the details so it will not be described in detail here.</para> + + <indexterm> + <primary>FTP</primary> + <secondary>anonymous</secondary> + </indexterm> + + <para>If you would like to enable anonymous FTP access to your + server, then you must create a user named + <username>ftp</username> on your &os; system. Users will then + be able to log on to your FTP server with a username of + <username>ftp</username> or <username>anonymous</username> and + with any password (by convention an email address for the user + should be used as the password). The FTP server will call + &man.chroot.2; when an anonymous user logs in, to restrict + access to only the home directory of the + <username>ftp</username> user.</para> + + <para>There are two text files that specify welcome messages to + be displayed to FTP clients. The contents of the file + <filename>/etc/ftpwelcome</filename> will be displayed to + users before they reach the login prompt. After a successful + login, the contents of the file + <filename>/etc/ftpmotd</filename> will be displayed. Note + that the path to this file is relative to the login + environment, so the file <filename>~ftp/etc/ftpmotd</filename> + would be displayed for anonymous users.</para> + + <para>Once the FTP server has been configured properly, it must + be enabled in <filename>/etc/inetd.conf</filename>. All that + is required here is to remove the comment symbol + <quote>#</quote> from in front of the existing + <application>ftpd</application> line :</para> + + <programlisting>ftp stream tcp nowait root /usr/libexec/ftpd ftpd -l</programlisting> + + <para>As explained in <xref linkend="network-inetd-reread">, + the <application>inetd</application> configuration must be + reloaded after this configuration file is changed. Please + refer to <xref linkend="network-inetd-settings"> for details + on enabling <application>inetd</application> on your + system.</para> + + <para>Alternatively, <application>ftpd</application> can also be + started as a stand-alone server. In this case, it is + sufficient to set the appropriate variable in + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ftpd_enable="YES"</programlisting> + + <para>After setting the above variable, the stand-alone server + will be started at the next reboot, or it can be started + manually by executing the following command as + <username>root</username>:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/ftpd start</userinput></screen> + + <para>You can now log on to your FTP server by typing:</para> + + <screen>&prompt.user; <userinput>ftp localhost</userinput></screen> + + </sect2> + + <sect2> + <title>Maintaining</title> + + <indexterm><primary>syslog</primary></indexterm> + <indexterm><primary>log files</primary> + <secondary>FTP</secondary></indexterm> + + <para>The <application>ftpd</application> daemon uses + &man.syslog.3; to log messages. By default, the system log + daemon will put messages related to FTP in the + <filename>/var/log/xferlog</filename> file. The location of + the FTP log can be modified by changing the following line in + <filename>/etc/syslog.conf</filename>:</para> + + <programlisting>ftp.info /var/log/xferlog</programlisting> + + <indexterm> + <primary>FTP</primary> + <secondary>anonymous</secondary> + </indexterm> + + <para>Be aware of the potential problems involved with running + an anonymous FTP server. In particular, you should think + twice about allowing anonymous users to upload files. You may + find that your FTP site becomes a forum for the trade of + unlicensed commercial software or worse. If you do need to + allow anonymous FTP uploads, then you should set up the + permissions so that these files can not be read by other + anonymous users until they have been reviewed.</para> + + </sect2> + </sect1> + + <sect1 id="network-samba"> + <sect1info> + <authorgroup> + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>File and Print Services for µsoft.windows; Clients + (Samba)</title> + + <indexterm><primary>Samba server</primary></indexterm> + <indexterm><primary>Microsoft Windows</primary></indexterm> + <indexterm> + <primary>file server</primary> + <secondary>Windows clients</secondary> + </indexterm> + <indexterm> + <primary>print server</primary> + <secondary>Windows clients</secondary> + </indexterm> + + <sect2> + <title>Overview</title> + + <para><application>Samba</application> is a popular open source + software package that provides file and print services for + µsoft.windows; clients. Such clients can connect to and + use FreeBSD filespace as if it was a local disk drive, or + FreeBSD printers as if they were local printers.</para> + + <para><application>Samba</application> software packages should + be included on your FreeBSD installation media. If you did + not install <application>Samba</application> when you first + installed FreeBSD, then you can install it from the <filename + role="package">net/samba34</filename> port or package.</para> + +<!-- mention LDAP, Active Directory, WinBIND, ACL, Quotas, PAM, .. --> + + </sect2> + + <sect2> + <title>Configuration</title> + + <para>A default <application>Samba</application> configuration + file is installed as + <filename>/usr/local/share/examples/samba34/smb.conf.default</filename>. + This file must be copied to + <filename>/usr/local/etc/smb.conf</filename> and customized + before <application>Samba</application> can be used.</para> + + <para>The <filename>smb.conf</filename> file contains runtime + configuration information for + <application>Samba</application>, such as definitions of the + printers and <quote>file system shares</quote> that you would + like to share with &windows; clients. The + <application>Samba</application> package includes a web based + tool called <application>swat</application> which provides a + simple way of configuring the <filename>smb.conf</filename> + file.</para> + + <sect3> + <title>Using the Samba Web Administration Tool (SWAT)</title> + + <para>The Samba Web Administration Tool (SWAT) runs as a + daemon from <application>inetd</application>. Therefore, + the following line in <filename>/etc/inetd.conf</filename> + should be uncommented before <application>swat</application> + can be used to configure + <application>Samba</application>:</para> + + <programlisting>swat stream tcp nowait/400 root /usr/local/sbin/swat swat</programlisting> + <para>As explained in <xref linkend="network-inetd-reread">, + the <application>inetd</application> configuration must be + reloaded after this configuration file is changed.</para> + + <para>Once <application>swat</application> has been enabled in + <filename>inetd.conf</filename>, you can use a browser to + connect to <ulink url="http://localhost:901"></ulink>. You + will first have to log on with the system + <username>root</username> account.</para> + +<!-- XXX screenshots go here, loader is creating them --> + + <para>Once you have successfully logged on to the main + <application>Samba</application> configuration page, you can + browse the system documentation, or begin by clicking on the + <guimenu>Globals</guimenu> tab. The + <guimenu>Globals</guimenu> section corresponds to the + variables that are set in the <literal>[global]</literal> + section of + <filename>/usr/local/etc/smb.conf</filename>.</para> + </sect3> + + <sect3> + <title>Global Settings</title> + + <para>Whether you are using <application>swat</application> or + editing <filename>/usr/local/etc/smb.conf</filename> + directly, the first directives you are likely to encounter + when configuring <application>Samba</application> + are:</para> + + <variablelist> + <varlistentry> + <term><literal>workgroup</literal></term> + + <listitem> + <para>NT Domain-Name or Workgroup-Name for the computers + that will be accessing this server.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>netbios name</literal></term> + <indexterm><primary>NetBIOS</primary></indexterm> + + <listitem> + <para>This sets the NetBIOS name by which a + <application>Samba</application> server is known. + By default it is the same as the first component of + the host's DNS name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>server string</literal></term> + + <listitem> + <para>This sets the string that will be displayed with + the <command>net view</command> command and some other + networking tools that seek to display descriptive text + about the server.</para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3> + <title>Security Settings</title> + + <para>Two of the most important settings in + <filename>/usr/local/etc/smb.conf</filename> are the + security model chosen, and the backend password format for + client users. The following directives control these + options:</para> + + <variablelist> + <varlistentry> + <term><literal>security</literal></term> + + <listitem> + <para>The two most common options here are + <literal>security = share</literal> and + <literal>security = user</literal>. If your clients + use usernames that are the same as their usernames on + your &os; machine then you will want to use user level + security. This is the default security policy and it + requires clients to first log on before they can + access shared resources.</para> + + <para>In share level security, client do not need to log + onto the server with a valid username and password + before attempting to connect to a shared resource. + This was the default security model for older versions + of <application>Samba</application>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>passdb backend</literal></term> + + <indexterm><primary>NIS+</primary></indexterm> + <indexterm><primary>LDAP</primary></indexterm> + <indexterm><primary>SQL database</primary></indexterm> + + <listitem> + <para><application>Samba</application> has several + different backend authentication models. You can + authenticate clients with LDAP, NIS+, a SQL database, + or a modified password file. The default + authentication method is <literal>smbpasswd</literal>, + and that is all that will be covered here.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Assuming that the default <literal>smbpasswd</literal> + backend is used, the + <filename>/usr/local/etc/samba/smbpasswd</filename> file + must be created to allow <application>Samba</application> to + authenticate clients. If you would like to give + your &unix; user accounts access from &windows; clients, use + the following command:</para> + + <screen>&prompt.root; <userinput>smbpasswd -a username</userinput></screen> + <note> + <para>The recommended backend is now + <literal>tdbsam</literal>, and the following command + should be used to add user accounts:</para> + + <screen>&prompt.root; <userinput><command>pdbedit <option>-a</option> <option>-u</option> <replaceable>username</replaceable></command></userinput></screen> + </note> + + <para>Please see the + <ulink + url="http://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/">Official + Samba HOWTO</ulink> + for additional information about configuration + options. With the basics outlined here, you should have + everything you need to start running + <application>Samba</application>.</para> + </sect3> + + </sect2> + <sect2> + <title>Starting <application>Samba</application></title> + + <para>The <filename role="package">net/samba34</filename> port + adds a new startup script, which can be used to control + <application>Samba</application>. To enable this script, so + that it can be used for example to start, stop or restart + <application>Samba</application>, add the following line to + the <filename>/etc/rc.conf</filename> file:</para> + + <programlisting>samba_enable="YES"</programlisting> + + <para>Or, for fine grain control:</para> + + <programlisting>nmbd_enable="YES"</programlisting> + <programlisting>smbd_enable="YES"</programlisting> + + <note> + <para>This will also configure + <application>Samba</application> to automatically start at + system boot time.</para> + </note> + + <para>It is possible then to start + <application>Samba</application> at any time by typing:</para> + + <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/samba start</userinput> +Starting SAMBA: removing stale tdbs : +Starting nmbd. +Starting smbd.</screen> + + <para>Please refer to <xref linkend="configtuning-rcd"> for more + information about using rc scripts.</para> + + <para><application>Samba</application> actually consists of + three separate daemons. You should see that both the + <application>nmbd</application> and + <application>smbd</application> daemons are started by the + <filename>samba</filename> script. If you enabled winbind + name resolution services in <filename>smb.conf</filename>, + then you will also see that the + <application>winbindd</application> daemon is started.</para> + + <para>You can stop <application>Samba</application> at any time + by typing :</para> + + <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/samba stop</userinput></screen> + + <para><application>Samba</application> is a complex software + suite with functionality that allows broad integration with + µsoft.windows; networks. For more information about + functionality beyond the basic installation described here, + please see <ulink url="http://www.samba.org"></ulink>.</para> + </sect2> + + </sect1> + + <sect1 id="network-ntp"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Hukins</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Clock Synchronization with NTP</title> + + <indexterm><primary>NTP</primary></indexterm> + + <sect2> + <title>Overview</title> + + <para>Over time, a computer's clock is prone to drift. The + Network Time Protocol (NTP) is one way to ensure your clock + stays accurate.</para> + + <para>Many Internet services rely on, or greatly benefit from, + computers' clocks being accurate. For example, a web server + may receive requests to send a file if it has been modified + since a certain time. In a local area network environment, it + is essential that computers sharing files from the same file + server have synchronized clocks so that file timestamps stay + consistent. Services such as &man.cron.8; also rely on + an accurate system clock to run commands at the specified + times.</para> + + <indexterm> + <primary>NTP</primary> + <secondary>ntpd</secondary> + </indexterm> + <para>FreeBSD ships with the &man.ntpd.8; <acronym + role="Network Time Protocol">NTP</acronym> server which can + be used to query other <acronym + role="Network Time Protocol">NTP</acronym> servers to set + the clock on your machine or provide time + services to others.</para> + </sect2> + + <sect2> + <title>Choosing Appropriate NTP Servers</title> + + <indexterm> + <primary>NTP</primary> + <secondary>choosing servers</secondary> + </indexterm> + + <para>In order to synchronize your clock, you will need to find + one or more <acronym role="Network Time + Protocol">NTP</acronym> servers to use. Your network + administrator or ISP may have set up an NTP server for this + purpose—check their documentation to see if this is the + case. There is an <ulink + url="http://support.ntp.org/bin/view/Servers/WebHome">online + list of publicly accessible NTP servers</ulink> which you can + use to find an NTP server near to you. Make sure you are + aware of the policy for any servers you choose, and ask for + permission if required.</para> + + <para>Choosing several unconnected NTP servers is a good idea in + case one of the servers you are using becomes unreachable or + its clock is unreliable. &man.ntpd.8; uses the responses it + receives from other servers intelligently—it will favor + unreliable servers less than reliable ones.</para> + </sect2> + + <sect2> + <title>Configuring Your Machine</title> + + <indexterm> + <primary>NTP</primary> + <secondary>configuration</secondary> + </indexterm> + + <sect3> + <title>Basic Configuration</title> + <indexterm><primary>ntpdate</primary></indexterm> + + <para>If you only wish to synchronize your clock when the + machine boots up, you can use &man.ntpdate.8;. This may be + appropriate for some desktop machines which are frequently + rebooted and only require infrequent synchronization, but + most machines should run &man.ntpd.8;.</para> + + <para>Using &man.ntpdate.8; at boot time is also a good idea + for machines that run &man.ntpd.8;. The &man.ntpd.8; + program changes the clock gradually, whereas &man.ntpdate.8; + sets the clock, no matter how great the difference between a + machine's current clock setting and the correct time.</para> + + <para>To enable &man.ntpdate.8; at boot time, add + <literal>ntpdate_enable="YES"</literal> to + <filename>/etc/rc.conf</filename>. You will also need to + specify all servers you wish to synchronize with and any + flags to be passed to &man.ntpdate.8; in + <varname>ntpdate_flags</varname>.</para> + </sect3> + + <sect3> + <indexterm> + <primary>NTP</primary> + <secondary>ntp.conf</secondary> + </indexterm> + + <title>General Configuration</title> + + <para>NTP is configured by the + <filename>/etc/ntp.conf</filename> file in the format + described in &man.ntp.conf.5;. Here is a simple + example:</para> + + <programlisting>server ntplocal.example.com prefer +server timeserver.example.org +server ntp2a.example.net + +driftfile /var/db/ntp.drift</programlisting> + + <para>The <literal>server</literal> option specifies which + servers are to be used, with one server listed on each line. + If a server is specified with the <literal>prefer</literal> + argument, as with <hostid + role="fqdn">ntplocal.example.com</hostid>, that server is + preferred over other servers. A response from a preferred + server will be discarded if it differs significantly from + other servers' responses, otherwise it will be used without + any consideration to other responses. The + <literal>prefer</literal> argument is normally used for NTP + servers that are known to be highly accurate, such as those + with special time monitoring hardware.</para> + + <para>The <literal>driftfile</literal> option specifies which + file is used to store the system clock's frequency offset. + The &man.ntpd.8; program uses this to automatically + compensate for the clock's natural drift, allowing it to + maintain a reasonably correct setting even if it is cut off + from all external time sources for a period of time.</para> + + <para>The <literal>driftfile</literal> option specifies which + file is used to store information about previous responses + from the NTP servers you are using. This file contains + internal information for NTP. It should not be modified by + any other process.</para> + </sect3> + + <sect3> + <title>Controlling Access to Your Server</title> + + <para>By default, your NTP server will be accessible to all + hosts on the Internet. The <literal>restrict</literal> + option in <filename>/etc/ntp.conf</filename> allows you to + control which machines can access your server.</para> + + <para>If you want to deny all machines from accessing your NTP + server, add the following line to + <filename>/etc/ntp.conf</filename>:</para> + + <programlisting>restrict default ignore</programlisting> + + <note> + <para>This will also prevent access from your server to + any servers listed in your local configuration. If you + need to synchronise your NTP server with an external NTP + server you should allow the specific server. See the + &man.ntp.conf.5; manual for more information.</para> + </note> + + <para>If you only want to allow machines within your own + network to synchronize their clocks with your server, but + ensure they are not allowed to configure the server or used + as peers to synchronize against, add</para> + + <programlisting>restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap</programlisting> + + <para>instead, where <hostid + role="ipaddr">192.168.1.0</hostid> is an IP address on + your network and <hostid + role="netmask">255.255.255.0</hostid> is your network's + netmask.</para> + + <para><filename>/etc/ntp.conf</filename> can contain multiple + <literal>restrict</literal> options. For more details, see + the <literal>Access Control Support</literal> subsection of + &man.ntp.conf.5;.</para> + </sect3> + </sect2> + + <sect2> + <title>Running the NTP Server</title> + + <para>To ensure the NTP server is started at boot time, add the + line <literal>ntpd_enable="YES"</literal> to + <filename>/etc/rc.conf</filename>. If you wish to pass + additional flags to &man.ntpd.8;, edit the + <varname>ntpd_flags</varname> parameter in + <filename>/etc/rc.conf</filename>.</para> + + <para>To start the server without rebooting your machine, run + <command>ntpd</command> being sure to specify any additional + parameters from <varname>ntpd_flags</varname> in + <filename>/etc/rc.conf</filename>. For example:</para> + + <screen>&prompt.root; <userinput>ntpd -p /var/run/ntpd.pid</userinput></screen> + </sect2> + + <sect2> + <title>Using <application>ntpd</application> with a Temporary + Internet Connection</title> + + <para>The &man.ntpd.8; program does not need a permanent + connection to the Internet to function properly. However, if + you have a temporary connection that is configured to dial out + on demand, it is a good idea to prevent NTP traffic from + triggering a dial out or keeping the connection alive. If you + are using user PPP, you can use <literal>filter</literal> + directives in <filename>/etc/ppp/ppp.conf</filename>. For + example:</para> + + <programlisting> set filter dial 0 deny udp src eq 123 + # Prevent NTP traffic from initiating dial out + set filter dial 1 permit 0 0 + set filter alive 0 deny udp src eq 123 + # Prevent incoming NTP traffic from keeping the connection open + set filter alive 1 deny udp dst eq 123 + # Prevent outgoing NTP traffic from keeping the connection open + set filter alive 2 permit 0/0 0/0</programlisting> + + <para>For more details see the <literal>PACKET + FILTERING</literal> section in &man.ppp.8; and the examples + in <filename>/usr/share/examples/ppp/</filename>.</para> + + <note> + <para>Some Internet access providers block low-numbered ports, + preventing NTP from functioning since replies never + reach your machine.</para> + </note> + </sect2> + + <sect2> + <title>Further Information</title> + + <para>Documentation for the NTP server can be found in + <filename>/usr/share/doc/ntp/</filename> in HTML + format.</para> + </sect2> + </sect1> + + <sect1 id="network-syslogd"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>Remote Host Logging with <command>syslogd</command></title> + + <para>Interacting with system logs is a crucial aspect of both + security and system administration. Monitoring the log files of + multiple hosts can get very unwieldy when these hosts are + distributed across medium or large networks, or when they are + parts of various different types of networks. In these cases, + configuring remote logging may make the whole process a lot more + comfortable.</para> + + <para>Centralized logging to a specific logging host can reduce + some of the administrative burden of log file administration. + Log file aggregation, merging and rotation can be configured in + one location, using the native tools of &os;, such as + &man.syslogd.8; and &man.newsyslog.8;. In the following example + configuration, host <hostid>A</hostid>, named <hostid + role="fqdn">logserv.example.com</hostid>, will collect + logging information for the local network. Host + <hostid>B</hostid>, named <hostid + role="fqdn">logclient.example.com</hostid> will pass + logging information to the server system. In live + configurations, both hosts require proper forward and reverse + <acronym>DNS</acronym> or entries in + <filename>/etc/hosts</filename>. Otherwise, data will be + rejected by the server.</para> + + <sect2> + <title>Log Server Configuration</title> + + <para>Log servers are machines configured to accept logging + information from remote hosts. In most cases this is to ease + configuration, in other cases it may just be a better + administration move. Regardless of reason, there are a few + requirements before continuing.</para> + + <para>A properly configured logging server has met the following + minimal requirements:</para> + + <itemizedlist> + <listitem> + <para>The firewall ruleset allows for <acronym>UDP</acronym> + to be passed on port 514 on both the client and + server;</para> + </listitem> + + <listitem> + <para>syslogd has been configured to accept remote messages + from client machines;</para> + </listitem> + + <listitem> + <para>The syslogd server and all client machines must have + valid entries for both forward and reverse + <acronym>DNS</acronym>, or be properly configured in + <filename>/etc/hosts</filename>.</para> + </listitem> + </itemizedlist> + + <para>To configure the log server, the client must be listed + in <filename>/etc/syslog.conf</filename>, and the logging + facility must be specified:</para> + + <programlisting>+logclient.example.com +*.* /var/log/logclient.log</programlisting> + + <note> + <para>More information on various supported and available + <emphasis>facilities</emphasis> may be found in the + &man.syslog.conf.5; manual page.</para> + </note> + + <para>Once added, all <literal>facility</literal> messages will + be logged to the file specified previously, + <filename>/var/log/logclient.log</filename>.</para> + + <para>The server machine must also have the following listing + placed inside <filename>/etc/rc.conf</filename>:</para> + + <programlisting>syslogd_enable="YES" +syslogd_flags="-a logclient.example.com -v -v"</programlisting> + + <para>The first option will enable the + <command>syslogd</command> daemon on boot up, and the second + option allows data from the specified client to be accepted on + this server. The latter part, using <option>-v -v</option>, + will increase the verbosity of logged messages. This is + extremely useful for tweaking facilities as administrators are + able to see what type of messages are being logged under which + facility.</para> + + <para>Multiple <option>-a</option> options may be specified to + allow logging from multiple clients. <acronym>IP</acronym> + addresses and whole netblocks may also be specified, see the + &man.syslog.3; manual page for a full list of possible + options.</para> + + <para>Finally, the log file should be created. The method used + does not matter, but &man.touch.1; works great for situations + such as this:</para> + + <screen>&prompt.root; <userinput>touch <filename>/var/log/logclient.log</filename></userinput></screen> + + <para>At this point, the <command>syslogd</command> daemon + should be restarted and verified:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/syslogd restart</userinput> +&prompt.root; <userinput>pgrep syslog</userinput></screen> + + <para>If a <acronym>PID</acronym> is returned, the server has + been restarted successfully, and client configuration may + begin. If the server has not restarted, consult the + <filename>/var/log/messages</filename> log for any + output.</para> + </sect2> + + <sect2> + <title>Log Client Configuration</title> + + <para>A logging client is a machine which sends log information + to a logging server in addition to keeping local + copies.</para> + + <para>Similar to log servers, clients must also meet a few + minimum requirements:</para> + + <itemizedlist> + <listitem> + <para>&man.syslogd.8; must be configured to send messages of + specific types to a log server, which must accept + them;</para> + </listitem> + + <listitem> + <para>The firewall must allow <acronym>UDP</acronym> packets + through on port 514;</para> + </listitem> + + <listitem> + <para>Both forward and reverse <acronym>DNS</acronym> must + be configured or have proper entries in the + <filename>/etc/hosts</filename>.</para> + </listitem> + </itemizedlist> + + <para>Client configuration is a bit more relaxed when compared + to that of the servers. The client machine must have the + following listing placed inside + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>syslogd_enable="YES" +syslogd_flags="-s -v -v"</programlisting> + + <para>As before, these entries will enable the + <command>syslogd</command> daemon on boot up, and increases + the verbosity of logged messages. The <option>-s</option> + option prevents logs from being accepted by this client from + other hosts.</para> + + <para>Facilities describe the system part for which a message + is generated. For an example, <acronym>ftp</acronym> and + <acronym>ipfw</acronym> are both facilities. When log + messages are generated for those two services, they will + normally include those two utilities in any log messages. + Facilities are accompanied with a priority or level, which + is used to mark how important a log message is. The most + common will be the <literal>warning</literal> and + <literal>info</literal>. Please refer to the &man.syslog.3; + manual page for a full list of available facilities and + priorities.</para> + + <para>The logging server must be defined in the client's + <filename>/etc/syslog.conf</filename>. In this instance, + the <literal>@</literal> symbol is used to send logging + data to a remote server and would look similar to the + following entry:</para> + + <programlisting>*.* @logserv.example.com</programlisting> + + <para>Once added, <command>syslogd</command> must be restarted + for the changes to take effect:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/syslogd restart</userinput></screen> + + <para>To test that log messages are being sent across the + network, use &man.logger.1; on the client to send a message to + <command>syslogd</command>:</para> + + <screen>&prompt.root; <userinput>logger "<replaceable>Test message from logclient</replaceable>"</userinput></screen> + + <para>This message should now exist both in + <filename>/var/log/messages</filename> on the client, and + <filename>/var/log/logclient.log</filename> on the + log server.</para> + </sect2> + + <sect2> + <title>Debugging Log Servers</title> + + <para>In certain cases, debugging may be required if messages + are not being received on the log server. There are several + reasons this may occur; however, the most common two are + network connection issues and <acronym>DNS</acronym> issues. + To test these cases, ensure both hosts are able to reach one + another using the hostname specified in + <filename>/etc/rc.conf</filename>. If this appears to be + working properly, an alternation to the + <literal>syslogd_flags</literal> option in + <filename>/etc/rc.conf</filename> will be required.</para> + + <para>In the following example, + <filename>/var/log/logclient.log</filename> is empty, and the + <filename>/var/log/messages</filename> files indicate no + reason for the failure. To increase debugging output, change + the <literal>syslogd_flags</literal> option to look like the + following example, and issue a restart:</para> + + <programlisting>syslogd_flags="-d -a logclien.example.com -v -v"</programlisting> + + <screen>&prompt.root; <userinput>/etc/rc.d/syslogd restart</userinput></screen> + + <para>Debugging data similar to the following will flash on the + screen immediately after the restart:</para> + + <screen>logmsg: pri 56, flags 4, from logserv.example.com, msg syslogd: restart +syslogd: restarted +logmsg: pri 6, flags 4, from logserv.example.com, msg syslogd: kernel boot file is /boot/kernel/kernel +Logging to FILE /var/log/messages +syslogd: kernel boot file is /boot/kernel/kernel +cvthname(192.168.1.10) +validate: dgram from IP 192.168.1.10, port 514, name logclient.example.com; +rejected in rule 0 due to name mismatch.</screen> + + <para>It appears obvious the messages are being rejected due + to a name mismatch. After reviewing the configuration bit + by bit, it appears a typo in the following + <filename>/etc/rc.conf</filename> line has an issue:</para> + + <programlisting>syslogd_flags="-d -a logclien.example.com -v -v"</programlisting> + + <para>The line should contain <literal>logclient</literal>, not + <literal>logclien</literal>. After the proper alterations + are made, a restart is issued with expected results:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/syslogd restart</userinput> +logmsg: pri 56, flags 4, from logserv.example.com, msg syslogd: restart +syslogd: restarted +logmsg: pri 6, flags 4, from logserv.example.com, msg syslogd: kernel boot file is /boot/kernel/kernel +syslogd: kernel boot file is /boot/kernel/kernel +logmsg: pri 166, flags 17, from logserv.example.com, +msg Dec 10 20:55:02 <syslog.err> logserv.example.com syslogd: exiting on signal 2 +cvthname(192.168.1.10) +validate: dgram from IP 192.168.1.10, port 514, name logclient.example.com; +accepted in rule 0. +logmsg: pri 15, flags 0, from logclient.example.com, msg Dec 11 02:01:28 trhodes: Test message 2 +Logging to FILE /var/log/logclient.log +Logging to FILE /var/log/messages</screen> + + <para>At this point, the messages are being properly received + and placed in the correct file.</para> + </sect2> + + <sect2> + <title>Security Considerations</title> + + <para>As with any network service, security requirements should + be considered before implementing this configuration. At + times, log files may contain sensitive data about services + enabled on the local host, user accounts, and configuration + data. Network data sent from the client to the server will + not be encrypted nor password protected. If a need for + encryption exists, it might be possible to use + <filename role="package">security/stunnel</filename>, which + will transmit data over an encrypted tunnel.</para> + + <para>Local security is also an issue. Log files are not + encrypted during use or after log rotation. Local users may + access these files to gain additional insight on system + configuration. In those cases, setting proper permissions + on these files will be critical. The &man.newsyslog.8; + utility supports setting permissions on newly created and + rotated log files. Setting log files to mode + <literal>600</literal> should prevent any unwanted snooping + by local users.</para> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> +<!-- LocalWords: config mnt www --> diff --git a/en_US.ISO8859-1/books/handbook/pgpkeys/Makefile b/en_US.ISO8859-1/books/handbook/pgpkeys/Makefile new file mode 100644 index 0000000000..7c61203aff --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/pgpkeys/Makefile @@ -0,0 +1,19 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= pgpkeys/chapter.sgml + +PGPKEYS!= perl -ne 'm/\"([\w-]+.key)\"/ && print "$$1\n"' \ + ${DOC_PREFIX}/share/pgpkeys/pgpkeys.ent +SRCS+= ${PGPKEYS} + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml b/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml new file mode 100644 index 0000000000..7c1fc562eb --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.sgml @@ -0,0 +1,50 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<!-- + + Do not edit this file except as instructed by the addkey.sh script. + + See the README file in doc/share/pgpkeys for instructions. + +--> +<appendix id="pgpkeys"> + <title>PGP Keys</title> + + <indexterm><primary>pgp keys</primary></indexterm> + <para>In case you need to verify a signature or send encrypted email + to one of the officers or developers a number of keys are provided + here for your convenience. A complete keyring of <hostid role="domainname">FreeBSD.org</hostid> + users is available for download from <ulink url="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</ulink>.</para> + + <sect1 id="pgpkeys-officers"> + <title>Officers</title> + + §ion.pgpkeys-officers; + </sect1> + + <sect1 id="pgpkeys-core"> + <title>Core Team Members</title> + + §ion.pgpkeys-core; + </sect1> + + <sect1 id="pgpkeys-developers"> + <title>Developers</title> + + §ion.pgpkeys-developers; + </sect1> +</appendix> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../appendix.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "appendix") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/ports/Makefile b/en_US.ISO8859-1/books/handbook/ports/Makefile new file mode 100644 index 0000000000..93280bcae8 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/ports/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= ports/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.sgml b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml new file mode 100644 index 0000000000..2801d5290b --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/ports/chapter.sgml @@ -0,0 +1,1569 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="ports"> + <title>Installing Applications: Packages and Ports</title> + + <sect1 id="ports-synopsis"> + <title>Synopsis</title> + + <indexterm><primary>ports</primary></indexterm> + <indexterm><primary>packages</primary></indexterm> + <para>FreeBSD is bundled with a rich collection of system tools as + part of the base system. However, there is only so much one can + do before needing to install an additional third-party + application to get real work done. FreeBSD provides two + complementary technologies for installing third-party software + on your system: the FreeBSD Ports Collection (for installing from + source), and packages (for installing from pre-built binaries). + Either method may be used to install the + newest version of your favorite applications from local media or + straight off the network.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to install third-party binary software packages.</para> + </listitem> + <listitem> + <para>How to build third-party software from source by using the ports + collection.</para> + </listitem> + <listitem> + <para>How to remove previously installed packages or ports.</para> + </listitem> + <listitem> + <para>How to override the default values that the ports + collection uses.</para> + </listitem> + <listitem> + <para>How to find the appropriate software package.</para> + </listitem> + <listitem> + <para>How to upgrade your applications.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="ports-overview"> + <title>Overview of Software Installation</title> + + <para>If you have used a &unix; system before you will know that + the typical procedure for installing third-party software goes + something like this:</para> + + <procedure> + <step> + <para>Download the software, which might be distributed in + source code format, or as a binary.</para> + </step> + + <step> + <para>Unpack the software from its distribution format + (typically a tarball compressed with &man.compress.1;, + &man.gzip.1;, or &man.bzip2.1;).</para> + </step> + + <step> + <para>Locate the documentation (perhaps an + <filename>INSTALL</filename> or <filename>README</filename> + file, or some files in a <filename>doc/</filename> + subdirectory) and read up on how to install the + software.</para> + </step> + + <step> + <para>If the software was distributed in source format, + compile it. This may involve editing a + <filename>Makefile</filename>, or running a + <command>configure</command> script, and other work.</para> + </step> + + <step> + <para>Test and install the software.</para> + </step> + </procedure> + + <para>And that is only if everything goes well. If you are + installing a software package that was not deliberately ported + to FreeBSD you may even have to go in and edit the code to make + it work properly.</para> + + <para>Should you want to, you can continue to install software the + <quote>traditional</quote> way with FreeBSD. However, FreeBSD + provides two technologies which can save you a lot of effort: + packages and ports. At the time of writing, over &os.numports; + third-party applications have been made available in this + way.</para> + + <para>For any given application, the FreeBSD package for that + application is a single file which you must download. The + package contains pre-compiled copies of all the commands for the + application, as well as any configuration files or + documentation. A downloaded package file can be manipulated + with FreeBSD package management commands, such as + &man.pkg.add.1;, &man.pkg.delete.1;, &man.pkg.info.1;, and so + on. Installing a new application can be carried out with a + single command.</para> + + <para>A FreeBSD port for an application is a collection of files + designed to automate the process of compiling an application + from source code.</para> + + <para>Remember that there are a number of steps you would normally + carry out if you compiled a program yourself (downloading, + unpacking, patching, compiling, installing). The files that + make up a port contain all the necessary information to allow + the system to do this for you. You run a handful of simple + commands and the source code for the application is + automatically downloaded, extracted, patched, compiled, and + installed for you.</para> + + <para>In fact, the ports system can also be used to generate packages + which can later be manipulated with <command>pkg_add</command> + and the other package management commands that will be introduced + shortly.</para> + + <para>Both packages and ports understand + <emphasis>dependencies</emphasis>. Suppose you want to install + an application that depends on a specific library being + installed. Both the application and the library have been made + available as FreeBSD ports and packages. If you use the + <command>pkg_add</command> command or the ports system to add + the application, both will notice that the library has not been + installed, and automatically install the library first.</para> + + <para>Given that the two technologies are quite similar, you might + be wondering why FreeBSD bothers with both. Packages and ports + both have their own strengths, and which one you use will depend + on your own preference.</para> + + <itemizedlist> + <title>Package Benefits</title> + + <listitem> + <para>A compressed package tarball is typically smaller than + the compressed tarball containing the source code for the + application.</para> + </listitem> + + <listitem> + <para>Packages do not require any additional compilation. For + large applications, such as + <application>Mozilla</application>, + <application>KDE</application>, or + <application>GNOME</application> this can be important, + particularly if you are on a slow system.</para> + </listitem> + + <listitem> + <para>Packages do not require any understanding of the process + involved in compiling software on FreeBSD.</para> + </listitem> + </itemizedlist> + + <itemizedlist> + <title>Ports Benefits</title> + + <listitem> + <para>Packages are normally compiled with conservative options, + because they have to run on the maximum number of systems. By + installing from the port, you can tweak the compilation options to + (for example) generate code that is specific to a Pentium + 4 or Athlon processor.</para> + </listitem> + + <listitem> + <para>Some applications have compile-time options relating to + what they can and cannot do. For example, + <application>Apache</application> can be configured with a + wide variety of different built-in options. By building + from the port you do not have to accept the default options, + and can set them yourself.</para> + + <para>In some cases, multiple packages will exist for the same + application to specify certain settings. For example, + <application>Ghostscript</application> is available as a + <filename>ghostscript</filename> package and a + <filename>ghostscript-nox11</filename> package, depending on + whether or not you have installed an X11 server. This sort + of rough tweaking is possible with packages, but rapidly + becomes impossible if an application has more than one or + two different compile-time options.</para> + </listitem> + + <listitem> + <para>The licensing conditions of some software distributions forbid + binary distribution. They must be distributed as source + code.</para> + </listitem> + + <listitem> + <para>Some people do not trust binary distributions. At least + with source code, you can (in theory) read through it and + look for potential problems yourself.</para> + </listitem> + + <listitem> + <para>If you have local patches, you will need the source in order to + apply them.</para> + </listitem> + + <listitem> + <para>Some people like having code around, so they can read it + if they get bored, hack it, borrow from it (license + permitting, of course), and so on.</para> + </listitem> + </itemizedlist> + + <para>To keep track of updated ports, subscribe to the + &a.ports; and the &a.ports-bugs;.</para> + + <warning> + <para>Before installing any application, you should check <ulink + url="http://vuxml.freebsd.org/"></ulink> for security issues + related to your application.</para> + + <para>You can also install <filename + role="package">ports-mgmt/portaudit</filename> which will + automatically check all installed applications for known + vulnerabilities; a check will be also performed before any port + build. Meanwhile, you can use the command <command>portaudit + -F -a</command> after you have installed some + packages.</para> + </warning> + + <para>The remainder of this chapter will explain how to use + packages and ports to install and manage third-party software on + FreeBSD.</para> + </sect1> + + <sect1 id="ports-finding-applications"> + <title>Finding Your Application</title> + + <para>Before you can install any applications you need to know what you + want, and what the application is called.</para> + + <para>FreeBSD's list of available applications is growing all the + time. Fortunately, there are a number of ways to find what you + want:</para> + + <itemizedlist> + <listitem> + <para>The FreeBSD web site maintains an up-to-date searchable + list of all the available applications, at <ulink + url="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>. + The ports are divided into categories, and you may either + search for an application by name (if you know it), or see + all the applications available in a category.</para> + </listitem> + + <indexterm><primary>FreshPorts</primary></indexterm> + + <listitem> + <para>Dan Langille maintains FreshPorts, at <ulink + url="http://www.FreshPorts.org/"></ulink>. FreshPorts + tracks changes to the applications in the ports tree as they + happen, allows you to <quote>watch</quote> one or more + ports, and can send you email when they are updated.</para> + </listitem> + + <indexterm><primary>FreshMeat</primary></indexterm> + + <listitem> + <para>If you do not know the name of the application you want, + try using a site like FreshMeat (<ulink + url="http://www.freshmeat.net/"></ulink>) to find an + application, then check back at the FreeBSD site to see if + the application has been ported yet.</para> + </listitem> + + <listitem> + <para>If you know the exact name of the port, but just need to + find out which category it is in, you can use the + &man.whereis.1; command. + Simply type <command>whereis + <replaceable>file</replaceable></command>, where + <replaceable>file</replaceable> is the program you want to + install. If it is found on your system, you will be told + where it is, as follows:</para> + + <screen>&prompt.root; <userinput>whereis lsof</userinput> +lsof: /usr/ports/sysutils/lsof</screen> + + <para>This tells us that <command>lsof</command> (a system + utility) can be found in the + <filename>/usr/ports/sysutils/lsof</filename> + directory.</para></listitem> + + <listitem> + <para>Additionally, you can use a simple &man.echo.1; statement + to find where a port exists in the ports tree. For + example:</para> + + <screen>&prompt.root; <userinput>echo /usr/ports/*/*lsof*</userinput> +/usr/ports/sysutils/lsof</screen> + + <para>Note that this will return any matched files downloaded into the + <filename class="directory">/usr/ports/distfiles</filename> + directory.</para> + </listitem> + + <listitem> + <para>Yet another way to find a particular port is by using the + Ports Collection's built-in search mechanism. To use the + search feature, you will need to be in the + <filename>/usr/ports</filename> directory. Once in that + directory, run <command>make <maketarget>search</maketarget> + name=<replaceable>program-name</replaceable></command> where + <replaceable>program-name</replaceable> is the name of the + program you want to find. For example, if you were looking + for <command>lsof</command>:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports</userinput> +&prompt.root; <userinput>make search name=lsof</userinput> +Port: lsof-4.56.4 +Path: /usr/ports/sysutils/lsof +Info: Lists information about open files (similar to fstat(1)) +Maint: obrien@FreeBSD.org +Index: sysutils +B-deps: +R-deps: </screen> + + <para>The part of the output you want to pay particular + attention to is the <quote>Path:</quote> line, since that + tells you where to find the port. The other information + provided is not needed in order to install the port, so it + will not be covered here.</para> + + <para>For more in-depth searching you can also use <command>make + <maketarget>search</maketarget> key=<replaceable>string</replaceable></command> + where <replaceable>string</replaceable> is some text to search for. + This searches port names, comments, descriptions and + dependencies and can be used to find ports which relate to a + particular subject if you do not know the name of the program + you are looking for.</para> + + <para>In both of these cases, the search string is case-insensitive. + Searching for <quote>LSOF</quote> will yield the same results as + searching for <quote>lsof</quote>.</para> + </listitem> + + </itemizedlist> + </sect1> + + <sect1 id="packages-using"> + <sect1info> + <authorgroup> + <author> + <firstname>Chern</firstname> + <surname>Lee</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <!-- 30 Mar 2001 --> + </sect1info> + + <title>Using the Packages System</title> + + <para>There are several different tools used to manage packages on + FreeBSD:</para> + + <itemizedlist> + <listitem><para>The <command>sysinstall</command> utility can be invoked on a + running system to install, delete, and list available and + installed packages. For more information, see <xref + linkend="packages">.</para></listitem> + <listitem><para>The package management command line tools, which are + the subject of the rest of this section.</para></listitem> + </itemizedlist> + + <sect2> + <title>Installing a Package</title> + <indexterm> + <primary>packages</primary> + <secondary>installing</secondary> + </indexterm> + + <indexterm> + <primary><command>pkg_add</command></primary> + </indexterm> + <para>You can use the &man.pkg.add.1; utility to install a + FreeBSD software package from a local file or from a server on + the network.</para> + + <example> + <title>Downloading a Package Manually and Installing It Locally</title> + + <screen>&prompt.root; <userinput>ftp -a <replaceable>ftp2.FreeBSD.org</replaceable></userinput> +Connected to ftp2.FreeBSD.org. +220 ftp2.FreeBSD.org FTP server (Version 6.00LS) ready. +331 Guest login ok, send your email address as password. +230- +230- This machine is in Vienna, VA, USA, hosted by Verio. +230- Questions? E-mail freebsd@vienna.verio.net. +230- +230- +230 Guest login ok, access restrictions apply. +Remote system type is UNIX. +Using binary mode to transfer files. +<prompt>ftp></prompt> <userinput>cd /pub/FreeBSD/ports/packages/sysutils/</userinput> +250 CWD command successful. +<prompt>ftp></prompt> <userinput>get lsof-4.56.4.tgz</userinput> +local: lsof-4.56.4.tgz remote: lsof-4.56.4.tgz +200 PORT command successful. +150 Opening BINARY mode data connection for 'lsof-4.56.4.tgz' (92375 bytes). +100% |**************************************************| 92375 00:00 ETA +226 Transfer complete. +92375 bytes received in 5.60 seconds (16.11 KB/s) +<prompt>ftp></prompt> <userinput>exit</userinput> +&prompt.root; <userinput>pkg_add <replaceable>lsof-4.56.4.tgz</replaceable></userinput></screen> + </example> + + <para>If you do not have a source of local packages (such as a + FreeBSD CD-ROM set) then it will probably be easier to use the + <option>-r</option> option to &man.pkg.add.1;. This will + cause the utility to automatically determine the correct + object format and release and then fetch and install the + package from an FTP site. + </para> + + <indexterm> + <primary><command>pkg_add</command></primary></indexterm> + <screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen> + + <para>The example above would download the correct package and + add it without any further user intervention. + If you want to specify an alternative &os; Packages Mirror, + instead of the main distribution site, you have to set the + <envar>PACKAGESITE</envar> environment variable accordingly, to + override the default settings. &man.pkg.add.1; + uses &man.fetch.3; to download the files, which honors various + environment variables, including + <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, and + <envar>FTP_PASSWORD</envar>. You may need to set one or more + of these if you are behind a firewall, or need to use an + FTP/HTTP proxy. See &man.fetch.3; for the complete list. + Note that in the example above + <literal>lsof</literal> is used instead of + <literal>lsof-4.56.4</literal>. When the remote fetching + feature is used, the version number of the package must be + removed. &man.pkg.add.1; will automatically fetch the latest + version of the application.</para> + + <note> + <para>&man.pkg.add.1; will download the latest version of + your application if you are using &os.current; or + &os.stable;. If you run a -RELEASE version, it will grab + the version of the package that was built with your + release. It is possible to change this behavior by + overriding <envar>PACKAGESITE</envar>. + For example, if you run a &os; 8.1-RELEASE + system, by default &man.pkg.add.1; will try to fetch + packages from + <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8.1-release/Latest/</literal>. + If you want to force &man.pkg.add.1; to download + &os; 8-STABLE packages, set <envar>PACKAGESITE</envar> + to + <literal>ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-8-stable/Latest/</literal>. + </para> + </note> + + <para>Package files are distributed in <filename>.tgz</filename> + and <filename>.tbz</filename> formats. You can find them at <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink>, + or on the FreeBSD CD-ROM distribution. Every CD on the + FreeBSD 4-CD set (and the PowerPak, etc.) contains packages + in the <filename>/packages</filename> directory. The layout + of the packages is similar to that of the + <filename>/usr/ports</filename> tree. Each category has its + own directory, and every package can be found within the + <filename>All</filename> directory. + </para> + + <para>The directory structure of the package system matches the + ports layout; they work with each other to form the entire + package/port system. + </para> + + </sect2> + + <sect2> + <title>Managing Packages</title> + + <indexterm> + <primary>packages</primary> + <secondary>managing</secondary> + </indexterm> + <para>&man.pkg.info.1; is a utility that lists and describes + the various packages installed. + </para> + + <indexterm> + <primary><command>pkg_info</command></primary> + </indexterm> + <screen>&prompt.root; <userinput>pkg_info</userinput> +cvsup-16.1 A general network file distribution system optimized for CV +docbook-1.2 Meta-port for the different versions of the DocBook DTD +...</screen> + <para>&man.pkg.version.1; is a utility that summarizes the + versions of all installed packages. It compares the package + version to the current version found in the ports tree. + </para> + <indexterm> + <primary><command>pkg_version</command></primary> + </indexterm> + <screen>&prompt.root; <userinput>pkg_version</userinput> +cvsup = +docbook = +...</screen> + + <para>The symbols in the second column indicate the relative age + of the installed version and the version available in the + local ports tree.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Symbol</entry> + <entry>Meaning</entry> + </row> + </thead> + + <tbody> + <row> + <entry>=</entry> <entry>The version of the + installed package matches the one found in the + local ports tree.</entry> + </row> + + <row><entry><</entry> + <entry>The installed version is older than the one available + in the ports tree.</entry> + </row> + + <row><entry>></entry><entry>The installed version is newer + than the one found in the local ports tree. (The local ports + tree is probably out of date.)</entry></row> + + <row><entry>?</entry><entry>The installed package cannot be + found in the ports index. (This can happen, for instance, if an + installed port is removed from the Ports Collection or + renamed.)</entry></row> + + <row><entry>*</entry><entry>There are multiple versions of the + package.</entry></row> + + <row><entry>!</entry><entry>The installed package exists in the + index but for some reason, <command>pkg_version</command> was + unable to compare the version number of the installed package + with the corresponding entry in the index.</entry></row> + + </tbody> + </tgroup> + </informaltable> + </sect2> + + <sect2> + <title>Deleting a Package</title> + <indexterm> + <primary><command>pkg_delete</command></primary> + </indexterm> + <indexterm> + <primary>packages</primary> + <secondary>deleting</secondary> + </indexterm> + <para>To remove a previously installed software package, use the + &man.pkg.delete.1; utility. + </para> + + <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-1.7.1</replaceable></userinput></screen> + + <para>Note that &man.pkg.delete.1; requires the full package + name and number; the above command would not work if + <replaceable>xchat</replaceable> was given instead of + <replaceable>xchat-1.7.1</replaceable>. It is, however, easy + to use &man.pkg.version.1; to find the version of the + installed package. You could instead simply use a wildcard:</para> + + <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat\*</replaceable></userinput></screen> + + <para>in this case, all packages whose names start with + <literal>xchat</literal> will be deleted.</para> + </sect2> + + <sect2> + <title>Miscellaneous</title> + <para>All package information is stored within the + <filename>/var/db/pkg</filename> directory. The installed + file list and descriptions of each package can be found within + files in this directory. + </para> + </sect2> + </sect1> + + <sect1 id="ports-using"> + <title>Using the Ports Collection</title> + + <para>The following sections provide basic instructions on using the + Ports Collection to install or remove programs from your + system. The detailed description of available <command>make</command> + targets and environment variables is available in &man.ports.7;.</para> + + <sect2 id="ports-tree"> + <title>Obtaining the Ports Collection</title> + + <para>Before you can install ports, you must first obtain the + Ports Collection—which is essentially a set of + <filename>Makefiles</filename>, patches, and description files + placed in <filename>/usr/ports</filename>. + </para> + + <para>When installing your FreeBSD system, + <application>sysinstall</application> asked if you would like + to install the Ports Collection. If you chose no, you can + follow these instructions to obtain the ports + collection:</para> + + <procedure> + <title>CVSup Method</title> + + <para>This is a quick method for getting and keeping your copy of the + Ports Collection up to date using <application>CVSup</application> + protocol. If you want to learn more about + <application>CVSup</application>, see <link + linkend="cvsup">Using CVSup</link>.</para> + + <note> + <para>The implementation of <application>CVSup</application> protocol + included with the &os; system is called + <application>csup</application>.</para> + </note> + + <para>Make sure <filename class="directory">/usr/ports</filename> + is empty before you run <application>csup</application> for + the first time! If you already have the Ports Collection present, + obtained from another source, <application>csup</application> + will not prune removed patch files.</para> + + <step> + <para>Run <command>csup</command>:</para> + + <screen>&prompt.root; <userinput>csup -L 2 -h <replaceable>cvsup.FreeBSD.org</replaceable> /usr/share/examples/cvsup/ports-supfile</userinput></screen> + + <para>Change + <replaceable>cvsup.FreeBSD.org</replaceable> to a + <application>CVSup</application> server near you. See + <link linkend="cvsup-mirrors">CVSup Mirrors</link> (<xref + linkend="cvsup-mirrors">) for a complete listing of mirror + sites.</para> + + <note> + <para>One may want to use his own + <filename>ports-supfile</filename>, for example to avoid + the need of passing the <application>CVSup</application> + server on the command line.</para> + + <procedure> + <step> + <para>In this case, as <username>root</username>, copy + <filename>/usr/share/examples/cvsup/ports-supfile</filename> + to a new location, such as + <filename>/root</filename> or your home + directory.</para> + </step> + + <step> + <para>Edit <filename>ports-supfile</filename>.</para> + </step> + + <step> + <para>Change + <replaceable>CHANGE_THIS.FreeBSD.org</replaceable> + to a <application>CVSup</application> server near + you. See <link linkend="cvsup-mirrors">CVSup + Mirrors</link> (<xref linkend="cvsup-mirrors">) for + a complete listing of mirror sites.</para> + </step> + + <step> + <para>And now to run <command>csup</command>, use the + following:</para> + + <screen>&prompt.root; <userinput>csup -L 2 <replaceable>/root/ports-supfile</replaceable></userinput></screen> + </step> + </procedure> + </note> + </step> + + <step> + <para>Running the &man.csup.1; command later will download and apply + all the recent changes to your Ports Collection, except + actually rebuilding the ports for your own system.</para> + </step> + </procedure> + + <procedure> + <title>Portsnap Method</title> + + <para><application>Portsnap</application> is an alternative system for + distributing the Ports Collection. + Please refer to <link linkend="updating-upgrading-portsnap">Using Portsnap</link> + for a detailed description of all <application>Portsnap</application> + features.</para> + + <step> + <para>Download a compressed snapshot of the Ports Collection into + <filename class="directory">/var/db/portsnap</filename>. You can + disconnect from the Internet after this step, if you wish.</para> + + <screen>&prompt.root; <userinput>portsnap fetch</userinput></screen> + </step> + + <step> + <para>If you are running <application>Portsnap</application> for the + first time, extract the snapshot into <filename + class="directory">/usr/ports</filename>: + </para> + + <screen>&prompt.root; <userinput>portsnap extract</userinput></screen> + + <para>If you already have a populated <filename + class="directory">/usr/ports</filename> and you are just updating, + run the following command instead:</para> + + <screen>&prompt.root; <userinput>portsnap update</userinput></screen> + </step> + + </procedure> + + <procedure> + <title>Sysinstall Method</title> + + <para>This method involves using <application>sysinstall</application> + to install the Ports Collection from the installation media. Note + that the old copy of Ports Collection from the date of the release + will be installed. If you have Internet access, you should always + use one of the methods mentioned above.</para> + + <step> + <para>As <username>root</username>, run + <command>sysinstall</command> as shown below:</para> + + <screen>&prompt.root; <userinput>sysinstall</userinput></screen> + </step> + + <step> + <para>Scroll down and select <guimenuitem>Configure</guimenuitem>, + press <keycap>Enter</keycap>.</para> + </step> + + <step> + <para>Scroll down and select + <guimenuitem>Distributions</guimenuitem>, press + <keycap>Enter</keycap>.</para> + </step> + + <step> + <para>Scroll down to <guimenuitem>ports</guimenuitem>, press + <keycap>Space</keycap>.</para> + </step> + + <step> + <para>Scroll up to <guimenuitem>Exit</guimenuitem>, press + <keycap>Enter</keycap>.</para> + </step> + + <step> + <para>Select your desired installation media, such as CDROM, + FTP, and so on.</para> + </step> + + <step> + <para>Scroll up to <guimenuitem>Exit</guimenuitem> and press + <keycap>Enter</keycap>.</para> + </step> + + <step> + <para>Press <keycap>X</keycap> to exit + <application>sysinstall</application>.</para> + </step> + </procedure> + </sect2> + + <sect2 id="ports-skeleton"> + <title>Installing Ports</title> + + <indexterm> + <primary>ports</primary> + <secondary>installing</secondary> + </indexterm> + <para>The first thing that should be explained when it comes to + the Ports Collection is what is actually meant by a + <quote>skeleton</quote>. In a nutshell, a port skeleton is a + minimal set of files that tell your FreeBSD system how to + cleanly compile and install a program. Each port skeleton + includes:</para> + + <itemizedlist> + <listitem> + <para>A <filename>Makefile</filename>. The + <filename>Makefile</filename> contains various statements + that specify how the application should be compiled and + where it should be installed on your system.</para> + </listitem> + + <listitem> + <para>A <filename>distinfo</filename> file. This file + contains information about the files that must be + downloaded to build the port, and their checksums + (using &man.sha256.1;), to + verify that files have not been corrupted during the + download.</para> + </listitem> + + <listitem> + <para>A <filename>files</filename> directory. This + directory contains patches to make the program compile and + install on your FreeBSD system. Patches are basically + small files that specify changes to particular files. + They are in plain text format, and basically say + <quote>Remove line 10</quote> or <quote>Change line 26 to + this ...</quote>. Patches are also known as + <quote>diffs</quote> because they are generated by the + &man.diff.1; program.</para> + + <para>This directory may also contain other files used to build + the port.</para> + </listitem> + + <listitem> + <para>A <filename>pkg-descr</filename> file. This is a more + detailed, often multiple-line, description of the program.</para> + </listitem> + + <listitem> + <para>A <filename>pkg-plist</filename> file. This is a list + of all the files that will be installed by the port. It + also tells the ports system what files to remove upon + deinstallation.</para> + </listitem> + </itemizedlist> + + <para>Some ports have other files, such as + <filename>pkg-message</filename>. The ports system uses these + files to handle special situations. If you want more details + on these files, and on ports in general, check out the <ulink + url="&url.books.porters-handbook;/index.html">FreeBSD Porter's + Handbook</ulink>.</para> + + <para>The port includes instructions on how to build source + code, but does not include the actual source code. You can + get the source code from a CD-ROM or from the Internet. + Source code is distributed in whatever manner the software + author desires. Frequently this is a tarred and gzipped file, + but it might be compressed with some other tool or even + uncompressed. The program source code, whatever form it comes + in, is called a <quote>distfile</quote>. The two methods for + installing a &os; port are described below.</para> + + <note> + <para>You must be logged in as <username>root</username> to + install ports.</para> + </note> + + <warning> + <para>Before installing any port, you should be sure to have + an up-to-date Ports Collection and you should check <ulink + url="http://vuxml.freebsd.org/"></ulink> for security issues + related to your port.</para> + + <para>A security vulnerabilities check can be automatically + done by <application>portaudit</application> before any new + application installation. This tool can be found in the + Ports Collection (<filename + role="package">ports-mgmt/portaudit</filename>). Consider + running <command>portaudit -F</command> before installing a + new port, to fetch the current vulnerabilities database. A + security audit and an update of the database will be + performed during the daily security system check. For more + information read the &man.portaudit.1; and &man.periodic.8; + manual pages.</para> + </warning> + + <para>The Ports Collection makes an assumption that you have a working + Internet connection. If you do not, you will need to put a copy of the + distfile into <filename>/usr/ports/distfiles</filename> + manually.</para> + + <para>To begin, change to the directory for the port you want to + install:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput></screen> + + <para>Once inside the <filename>lsof</filename> directory, you + will see the port skeleton. The next step is to compile, or + <quote>build</quote>, the port. This is done by simply + typing <command>make</command> at the prompt. Once you have + done so, you should see something like this:</para> + + <screen>&prompt.root; <userinput>make</userinput> +>> lsof_4.57D.freebsd.tar.gz doesn't seem to exist in /usr/ports/distfiles/. +>> Attempting to fetch from ftp://lsof.itap.purdue.edu/pub/tools/unix/lsof/. +===> Extracting for lsof-4.57 +... +[extraction output snipped] +... +>> Checksum OK for lsof_4.57D.freebsd.tar.gz. +===> Patching for lsof-4.57 +===> Applying FreeBSD patches for lsof-4.57 +===> Configuring for lsof-4.57 +... +[configure output snipped] +... +===> Building for lsof-4.57 +... +[compilation output snipped] +... +&prompt.root;</screen> + + <para>Notice that once the compile is complete you are + returned to your prompt. The next step is to install the + port. In order to install it, you simply need to tack one word + onto the <command>make</command> command, and that word is + <maketarget>install</maketarget>:</para> + + <screen>&prompt.root; <userinput>make install</userinput> +===> Installing for lsof-4.57 +... +[installation output snipped] +... +===> Generating temporary packing list +===> Compressing manual pages for lsof-4.57 +===> Registering installation for lsof-4.57 +===> SECURITY NOTE: + This port has installed the following binaries which execute with + increased privileges. +&prompt.root;</screen> + + <para>Once you are returned to your prompt, you should be able to + run the application you just installed. Since + <command>lsof</command> is a + program that runs with increased privileges, a security + warning is shown. During the building and installation of + ports, you should take heed of any other warnings that + may appear.</para> + + <para>It is a good idea to delete the working subdirectory, + which contains all the temporary files used during compilation. + Not only does it consume valuable disk space, but it would also + cause problems later when upgrading to the newer version of the + port.</para> + + <screen>&prompt.root; <userinput>make clean</userinput> +===> Cleaning for lsof-4.57 +&prompt.root;</screen> + + <note> + <para>You can save two extra steps by just running <command>make + <maketarget>install clean</maketarget></command> instead of + <command>make</command>, + <command>make <maketarget>install</maketarget></command> and + <command>make <maketarget>clean</maketarget></command> + as three separate steps.</para> + </note> + + <note> + <para>Some shells keep a cache of the commands that are + available in the directories listed in the + <envar>PATH</envar> environment variable, to speed up + lookup operations for the executable file of these + commands. If you are using one of these shells, you might + have to use the <command>rehash</command> command after + installing a port, before the newly installed commands can + be used. This command will work for shells like + <command>tcsh</command>. Use the <command>hash -r</command> + command for shells like <command>sh</command>. Look at the + documentation for your shell for more information.</para> + </note> + + <para>Some third-party DVD-ROM products such as the FreeBSD Toolkit + from the <ulink url="http://www.freebsdmall.com/">FreeBSD + Mall</ulink> contain distfiles. They can be used with the Ports + Collection. Mount the DVD-ROM on <filename>/cdrom</filename>. If + you use a different mount point, set <makevar>CD_MOUNTPTS</makevar> + make variable. The needed distfiles will be automatically used + if they are present on the disk.</para> + + <note> + <para>Please be aware that the licenses of a few ports do + not allow for inclusion on the CD-ROM. This could be + because a registration form needs to be filled out before + downloading or redistribution is not allowed, or for + another reason. If you wish to install a port not + included on the CD-ROM, you will need to be online in + order to do so.</para> + </note> + + <para>The ports system uses &man.fetch.1; to download the + files, which honors various environment variables, including + <envar>FTP_PASSIVE_MODE</envar>, <envar>FTP_PROXY</envar>, + and <envar>FTP_PASSWORD</envar>. You may need to set one or + more of these if you are behind a firewall, or need to use + an FTP/HTTP proxy. See &man.fetch.3; for the complete + list.</para> + + <para>For users which cannot be connected all the time, the + <command>make <maketarget>fetch</maketarget></command> option is + provided. Just run this command at the top level directory + (<filename>/usr/ports</filename>) and the required files + will be downloaded for you. This command will also work in + the lower level categories, for example: + <filename>/usr/ports/net</filename>. + Note that if a port depends on libraries or other ports this will + <emphasis>not</emphasis> fetch the distfiles of those ports too. + Replace <maketarget>fetch</maketarget> with + <maketarget>fetch-recursive</maketarget> + if you want to fetch all the dependencies of a port too.</para> + + <note><para>You can build all the ports in a category or as a + whole by running <command>make</command> in the top level + directory, just like the aforementioned <command>make + <maketarget>fetch</maketarget></command> method. This is + dangerous, however, as some ports cannot co-exist. In other + cases, some ports can install two different files with the + same filename.</para></note> + + <para>In some rare cases, users may need to acquire the + tarballs from a site other than the + <makevar>MASTER_SITES</makevar> (the location where files + are downloaded from). You can override the + <makevar>MASTER_SITES</makevar> option with the following + command:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput> +&prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \ +ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen> + + <para>In this example we change the + <makevar>MASTER_SITES</makevar> option to <hostid + role="fqdn">ftp.FreeBSD.org/pub/FreeBSD/ports/distfiles/</hostid>.</para> + + <note><para>Some ports allow (or even require) you to provide + build options which can enable/disable parts of the + application which are unneeded, certain security options, + and other customizations. A few which come to mind are + <filename role="package">www/firefox</filename>, <filename + role="package">security/gpgme</filename>, and <filename + role="package">mail/sylpheed-claws</filename>. A message + will be displayed when options such as these are + available.</para></note> + + <sect3> + <title>Overriding the Default Ports Directories</title> + + <para>Sometimes it is useful (or mandatory) to use a different + working and target directory. The + <makevar>WRKDIRPREFIX</makevar> and <makevar>PREFIX</makevar> + variables can override the default directories. For + example:</para> + + <screen>&prompt.root; <userinput>make WRKDIRPREFIX=/usr/home/example/ports install</userinput></screen> + + <para>will compile the port in + <filename>/usr/home/example/ports</filename> and install + everything under <filename>/usr/local</filename>.</para> + + <screen>&prompt.root; <userinput>make PREFIX=/usr/home/example/local install</userinput></screen> + + <para>will compile it in <filename>/usr/ports</filename> and + install it in + <filename>/usr/home/example/local</filename>.</para> + + <para>And of course,</para> + + <screen>&prompt.root; <userinput>make WRKDIRPREFIX=../ports PREFIX=../local install</userinput></screen> + + <para>will combine the two (it is too long to completely write + on this page, but it should give you the general + idea).</para> + + <para>Alternatively, these variables can also be set as part + of your environment. Read the manual page for your shell + for instructions on doing so.</para> + </sect3> + + <sect3> + <title>Dealing with <command>imake</command></title> + + <para>Some ports that use <command>imake</command> (a part of + the X Window System) do not work well with + <makevar>PREFIX</makevar>, and will insist on installing + under <filename>/usr/X11R6</filename>. Similarly, some Perl + ports ignore <makevar>PREFIX</makevar> and install in the + Perl tree. Making these ports respect + <makevar>PREFIX</makevar> is a difficult or impossible + job.</para> + + </sect3> + + <sect3> + <title>Reconfiguring Ports</title> + + <para>When building certain ports, you may be presented with a + ncurses-based menu from which you can select certain build options. + It is not uncommon for users to wish to revisit this menu to add, + remove, or change these options after a port has been built. There + are many ways to do this. One option is to go into the directory + containing the port and type <command>make + <maketarget>config</maketarget></command>, which will simply present + the menu again with the same options selected. Another option is to + use <command>make <maketarget>showconfig</maketarget></command>, + which will show you all the configuration options for the port. Yet + another option is to execute <command>make + <maketarget>rmconfig</maketarget></command> which will remove all + selected options and allow you to start over. All of these options, + and others, are explained in great detail in the manual page for + &man.ports.7;.</para> + </sect3> + </sect2> + + <sect2 id="ports-removing"> + <title>Removing Installed Ports</title> + + <indexterm> + <primary>ports</primary> + <secondary>removing</secondary> + </indexterm> + <para>Now that you know how to install ports, you are probably + wondering how to remove them, just in case you install one and + later on decide that you installed the wrong port. + We will remove our previous example (which was + <command>lsof</command> for + those of you not paying attention). Ports are being removed exactly + the same as the packages (discussed in the <link + linkend="packages-using">Packages section</link>), using the + &man.pkg.delete.1; command:</para> + + <screen>&prompt.root; <userinput>pkg_delete lsof-4.57</userinput></screen> + + </sect2> + + <sect2 id="ports-upgrading"> + <title>Upgrading Ports</title> + + <indexterm> + <primary>ports</primary> + <secondary>upgrading</secondary> + </indexterm> + <para>First, list outdated ports that have a newer version available in + the Ports Collection with the &man.pkg.version.1; command:</para> + + <screen>&prompt.root; <userinput>pkg_version -v</userinput></screen> + + <sect3 id="ports-file-updating"> + <title><filename>/usr/ports/UPDATING</filename></title> + + <para>Once you have updated your Ports Collection, before + attempting a port upgrade, you should check + <filename>/usr/ports/UPDATING</filename>. This file + describes various issues and additional steps users may + encounter and need to perform when updating a port, including + such things as file format changes, changes in locations of + configuration files, or other such incompatibilities with + previous versions.</para> + + <para>If <filename>UPDATING</filename> contradicts something you + read here, <filename>UPDATING</filename> takes precedence.</para> + </sect3> + + <sect3 id="portupgrade"> + <title>Upgrading Ports Using Portupgrade</title> + + <indexterm> + <primary>portupgrade</primary> + </indexterm> + + <para>The <application>portupgrade</application> utility is designed + to easily upgrade installed ports. It is available from the <filename + role="package">ports-mgmt/portupgrade</filename> port. Install it like + any other port, using the <command>make <maketarget>install + clean</maketarget></command> command:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portupgrade</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>Scan the list of installed ports with the <command>pkgdb + -F</command> command and fix all the inconsistencies it reports. It is + a good idea to do this regularly, before every upgrade.</para> + + <para>When you run <command>portupgrade -a</command>, + <application>portupgrade</application> will begin to upgrade all the + outdated ports installed on your system. Use the <option>-i</option> + flag if you want to be asked for confirmation of every individual + upgrade.</para> + + <screen>&prompt.root; <userinput>portupgrade -ai</userinput></screen> + + <para>If you want to upgrade only a + certain application, not all available ports, use <command>portupgrade + <replaceable>pkgname</replaceable></command>. Include the + <option>-R</option> flag if <application>portupgrade</application> + should first upgrade all the ports required by the given + application.</para> + + <screen>&prompt.root; <userinput>portupgrade -R firefox</userinput></screen> + + <para>To use packages instead of ports for installation, provide + <option>-P</option> flag. With this option + <application>portupgrade</application> searches + the local directories listed in <envar>PKG_PATH</envar>, or + fetches packages from remote site if it is not found locally. + If packages can not be found locally or fetched remotely, + <application>portupgrade</application> will use ports. + To avoid using ports, specify <option>-PP</option>.</para> + + <screen>&prompt.root; <userinput>portupgrade -PP gnome2</userinput></screen> + + <para>To just fetch distfiles (or packages, if + <option>-P</option> is specified) without building or + installing anything, use <option>-F</option>. + For further information see &man.portupgrade.1;.</para> + </sect3> + + <sect3 id="portmanager"> + <title>Upgrading Ports Using Portmanager</title> + + <indexterm> + <primary>portmanager</primary> + </indexterm> + + <para><application>Portmanager</application> is another utility for + easy upgrading of installed ports. It is available from the + <filename role="package">ports-mgmt/portmanager</filename> + port:</para> + + <screen>&prompt.root; <userinput>cd <filename class="directory">/usr/ports/ports-mgmt/portmanager</filename></userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>All the installed ports can be upgraded using this simple + command:</para> + + <screen>&prompt.root; <userinput>portmanager -u</userinput></screen> + + <para>You can add the <option>-ui</option> flag to the above + command (<userinput>portmanager -u -ui</userinput>) to be + prompted for + confirmation of every step <application>Portmanager</application> + will perform. <application>Portmanager</application> can also be + used to install new ports on the system. Unlike the usual + <command>make <maketarget>install clean</maketarget></command> + command, it will upgrade all the dependencies prior to building and + installing the selected port.</para> + + <screen>&prompt.root; <userinput>portmanager <replaceable>x11/gnome2</replaceable></userinput></screen> + + <para>If there are any problems regarding the dependencies for the + selected port, you can use <application>Portmanager</application> to + rebuild all of them in the correct order. Once finished, the + problematic port will be rebuilt too.</para> + + <screen>&prompt.root; <userinput>portmanager <replaceable>graphics/gimp</replaceable> -f</userinput></screen> + + <para>For further information see &man.portmanager.1;.</para> + </sect3> + + <sect3 id="portmaster"> + <title>Upgrading Ports Using Portmaster</title> + + <indexterm> + <primary>portmaster</primary> + </indexterm> + + <para><application>Portmaster</application> is another utility for + upgrading installed ports. <application>Portmaster</application> + was designed make use of the tools found in the <quote>base</quote> + system (it does not depend upon other ports) and uses the + information in <filename class="directory">/var/db/pkg/</filename> + to determine which ports to upgrade. It is available from the + <filename role="package">ports-mgmt/portmaster</filename> + port:</para> + + <screen>&prompt.root; <userinput>cd <filename class="directory">/usr/ports/ports-mgmt/portmaster</filename></userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para><application>Portmaster</application> groups ports into four + categories:</para> + + <itemizedlist> + <listitem> + <para>Root ports (no dependencies, not depended on)</para> + </listitem> + <listitem> + <para>Trunk ports (no dependencies, are depended on)</para> + </listitem> + <listitem> + <para>Branch ports (have dependencies, are depended on)</para> + </listitem> + <listitem> + <para>Leaf ports (have dependencies, not depended on)</para> + </listitem> + </itemizedlist> + + <para>You can list all the installed ports and search + for updates using the <option>-L</option> option:</para> + +<screen>&prompt.root; <userinput>portmaster -L</userinput> +===>>> Root ports (No dependencies, not depended on) +===>>> ispell-3.2.06_18 +===>>> screen-4.0.3 + ===>>> New version available: screen-4.0.3_1 +===>>> tcpflow-0.21_1 +===>>> 7 root ports +... +===>>> Branch ports (Have dependencies, are depended on) +===>>> apache-2.2.3 + ===>>> New version available: apache-2.2.8 +... +===>>> Leaf ports (Have dependencies, not depended on) +===>>> automake-1.9.6_2 +===>>> bash-3.1.17 + ===>>> New version available: bash-3.2.33 +... +===>>> 32 leaf ports + +===>>> 137 total installed ports + ===>>> 83 have new versions available +</screen> + + <para>All the installed ports can be upgraded using this simple + command:</para> + + <screen>&prompt.root; <userinput>portmaster -a</userinput></screen> + + <note><para>By default, <application>Portmaster</application> + will make a backup package before deleting the existing port. If + the installation of the new version is successful, + <application>Portmaster</application> will delete the backup. + Using the <option>-b</option> will instruct + <application>Portmaster</application> not to automatically delete + the backup. Adding the <option>-i</option> option will start + <application>Portmaster</application> in interactive mode, prompting + you before upgrading each port.</para></note> + + <para>If you encounter errors during the upgrade process, you can use + the <option>-f</option> option to upgrade/rebuild all ports:</para> + + <screen>&prompt.root; <userinput>portmaster -af</userinput></screen> + + <para>You can also use <application>Portmaster</application> to + install new ports on the system, upgrading all dependencies + before building and installing the new port:</para> + + <screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen> + + <para>Please see &man.portmaster.8; for more information.</para> + </sect3> + </sect2> + + <sect2 id="ports-disk-space"> + <title>Ports and Disk Space</title> + + <indexterm> + <primary>ports</primary> + <secondary>disk-space</secondary> + </indexterm> + <para>Using the Ports Collection will use up disk + space over time. After building and installing software from the + ports, you should always remember to clean up + the temporary <filename class="directory">work</filename> directories + using the <command>make <maketarget>clean</maketarget></command> + command. You can sweep the whole Ports Collection with the following + command:</para> + + <screen>&prompt.root; <userinput>portsclean -C</userinput></screen> + + <para>You will accumulate a lot of old source distribution files in the + <filename class="directory">distfiles</filename> directory over time. + You can remove them by hand, or you can use the following command to + delete all the distfiles that are no longer referenced by any + ports:</para> + + <screen>&prompt.root; <userinput>portsclean -D</userinput></screen> + + <para>Or to remove all distfiles not referenced by any port + currently installed on your system:</para> + + <screen>&prompt.root; <userinput>portsclean -DD</userinput></screen> + + <note> + <para>The <command>portsclean</command> utility is part of the + <application>portupgrade</application> suite.</para> + </note> + + <para>Do not forget to remove the installed ports once you no longer need + them. A nice tool to help automate this task is available from the + <filename role="package">ports-mgmt/pkg_cutleaves</filename> + port.</para> + </sect2> + + </sect1> + + <sect1 id="ports-nextsteps"> + <title>Post-installation Activities</title> + + <para>After installing a new application you will normally want to + read any documentation it may have included, edit any + configuration files that are required, ensure that the + application starts at boot time (if it is a daemon), and so + on.</para> + + <para>The exact steps you need to take to configure each + application will obviously be different. However, if you have + just installed a new application and are wondering <quote>What + now?</quote> these tips might help:</para> + + <itemizedlist> + <listitem> + <para>Use &man.pkg.info.1; to find out which files were installed, + and where. For example, if you have just + installed FooPackage version 1.0.0, then this command</para> + + <screen>&prompt.root; <userinput>pkg_info -L foopackage-1.0.0 | less</userinput></screen> + + <para>will show all the files installed by the package. Pay + special attention to files in <filename>man/</filename> + directories, which will be manual pages, + <filename>etc/</filename> directories, which will be + configuration files, and <filename>doc/</filename>, which + will be more comprehensive documentation.</para> + + <para>If you are not sure which version of the application was + just installed, a command like this</para> + + <screen>&prompt.root; <userinput>pkg_info | grep -i <replaceable>foopackage</replaceable></userinput></screen> + + <para>will find all the installed packages that have + <replaceable>foopackage</replaceable> in the package name. + Replace <replaceable>foopackage</replaceable> in your + command line as necessary.</para> + </listitem> + + <listitem> + <para>Once you have identified where the application's manual + pages have been installed, review them using &man.man.1;. + Similarly, look over the sample configuration files, and any + additional documentation that may have been provided.</para> + </listitem> + + <listitem> + <para>If the application has a web site, check it for + additional documentation, frequently asked questions, and so + forth. If you are not sure of the web site address it may + be listed in the output from</para> + + <screen>&prompt.root; <userinput>pkg_info <replaceable>foopackage-1.0.0</replaceable></userinput></screen> + + <para>A <literal>WWW:</literal> line, if present, should provide a URL + for the application's web site.</para> + </listitem> + + <listitem> + <para>Ports that should start at boot (such as Internet + servers) will usually install a sample script in + <filename>/usr/local/etc/rc.d</filename>. You should + review this script for correctness and edit or rename it if + needed. See <link + linkend="configtuning-starting-services">Starting + Services</link> for more information.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="ports-broken"> + <title>Dealing with Broken Ports</title> + + <para>If you come across a port that does not work for you, + there are a few things you can do, including:</para> + + <orderedlist> + <listitem> + <para>Find out if there is a fix pending for the port in + the <ulink url="&url.base;/support.html#gnats">Problem Report + database</ulink>. If so, you may be able to use the + proposed fix.</para> + </listitem> + + <listitem> + <para>Ask the maintainer of the port for help. Type + <command>make <maketarget>maintainer</maketarget></command> or read + the <filename>Makefile</filename> to find the maintainer's + email address. Remember to include the name and version + of the port (send the <literal>$FreeBSD:</literal> + line from the <filename>Makefile</filename>) and the + output leading up to the error when you email the + maintainer.</para> + + <note> + <para>Some ports are not maintained by an individual but + instead by a <ulink + url="&url.articles.mailing-list-faq;/article.html">mailing + list</ulink>. Many, but not all, of these addresses look like + <email role="nolink">freebsd-listname@FreeBSD.org</email>. + Please take this into account when phrasing your + questions.</para> + + <para>In particular, ports shown as maintained by + <email role="nolink">ports@FreeBSD.org</email> are + actually not maintained by anyone. Fixes and support, if + any, come from the general community who subscribe to that + mailing list. More volunteers are always needed!</para> + </note> + + <para>If you do not get a response, + you can use &man.send-pr.1; to submit a bug + report (see <ulink + url="&url.articles.problem-reports;/article.html">Writing + FreeBSD Problem Reports</ulink>).</para> + </listitem> + + <listitem> + <para>Fix it! The <ulink + url="&url.books.porters-handbook;/index.html">Porter's + Handbook</ulink> includes detailed information on the + <quote>Ports</quote> infrastructure so that you can fix the + occasional broken port or even submit your own!</para> + </listitem> + + <listitem> + <para>Grab the package from an FTP site near you. The + <quote>master</quote> package collection is on <hostid + role="fqdn">ftp.FreeBSD.org</hostid> in the <ulink + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">packages + directory</ulink>, but be sure to check your closer <link + linkend="mirrors-ftp">mirror sites</link> + <emphasis>first</emphasis>! These are more likely to work + than trying to compile from source and are a lot faster as + well. Use the &man.pkg.add.1; program to install the + package on your system.</para> + </listitem> + </orderedlist> + </sect1> + +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/Makefile b/en_US.ISO8859-1/books/handbook/ppp-and-slip/Makefile new file mode 100644 index 0000000000..1a44fcbd0c --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/ppp-and-slip/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= ppp-and-slip/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml new file mode 100644 index 0000000000..eddc7863aa --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.sgml @@ -0,0 +1,3242 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="ppp-and-slip"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Mock</surname> + <contrib>Restructured, reorganized, and updated by </contrib> + <!-- 1 Mar 2000 --> + </author> + </authorgroup> + </chapterinfo> + + <title>PPP and SLIP</title> + + <sect1 id="ppp-and-slip-synopsis"> + <title>Synopsis</title> + <indexterm id="ppp-ppp"> + <primary>PPP</primary> + </indexterm> + <indexterm id="ppp-slip"> + <primary>SLIP</primary> + </indexterm> + + <para>FreeBSD has a number of ways to link one computer to + another. To establish a network or Internet connection through a + dial-up modem, or to allow others to do so through you, requires + the use of PPP or SLIP. This chapter describes setting up + these modem-based communication services in detail.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to set up user PPP.</para> + </listitem> + <listitem> + <para>How to set up kernel PPP (&os; 7.X only).</para> + </listitem> + <listitem> + <para>How to set up <acronym>PPPoE</acronym> (PPP over + Ethernet).</para> + </listitem> + <listitem> + <para>How to set up <acronym>PPPoA</acronym> (PPP over + ATM).</para> + </listitem> + <listitem> + <para>How to configure and set up a SLIP client and + server (&os; 7.X only).</para> + </listitem> + </itemizedlist> + + <indexterm id="ppp-ppp-user"> + <primary>PPP</primary> + <secondary>user PPP</secondary> + </indexterm> + <indexterm id="ppp-ppp-kernel"> + <primary>PPP</primary> + <secondary>kernel PPP</secondary> + </indexterm> + <indexterm id="ppp-ppp-ethernet"> + <primary>PPP</primary> + <secondary>over Ethernet</secondary> + </indexterm> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Be familiar with basic network terminology.</para> + </listitem> + <listitem> + <para>Understand the basics and purpose of a dialup connection + and PPP and/or SLIP.</para> + </listitem> + </itemizedlist> + + <para>You may be wondering what the main difference is between user + PPP and kernel PPP. The answer is simple: user PPP processes the + inbound and outbound data in userland rather than in the kernel. + This is expensive in terms of copying the data between the kernel + and userland, but allows a far more feature-rich PPP implementation. + User PPP uses the <devicename>tun</devicename> device to communicate + with the outside world whereas kernel PPP uses the + <devicename>ppp</devicename> device.</para> + + <note> + <para>Throughout in this chapter, user PPP will simply be + referred to as <application>ppp</application> unless a distinction + needs to be made between it and any other PPP software such as + <application>pppd</application> (&os; 7.X only). Unless otherwise stated, all of + the commands explained in this chapter should be executed as + <username>root</username>.</para> + </note> + </sect1> + + <sect1 id="userppp"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Updated and enhanced by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Brian</firstname> + <surname>Somers</surname> + <contrib>Originally contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Nik</firstname> + <surname>Clayton</surname> + <contrib>With input from </contrib> + </author> + <author> + <firstname>Dirk</firstname> + <surname>Frömberg</surname> + </author> + <author> + <firstname>Peter</firstname> + <surname>Childs</surname> + </author> + </authorgroup> + </sect1info> + + <title>Using User PPP</title> + + <warning> + <para>As of &os; 8.0, device nodes for serial ports have been + renamed from + <filename>/dev/cuad<replaceable>N</replaceable></filename> to + <filename>/dev/cuau<replaceable>N</replaceable></filename> and + from + <filename>/dev/ttyd<replaceable>N</replaceable></filename> to + <filename>/dev/ttyu<replaceable>N</replaceable></filename>. + &os; 7.X users will have to adapt the following + documentation according to these changes.</para> + </warning> + + <sect2> + <title>User PPP</title> + + <sect3> + <title>Assumptions</title> + + <para>This document assumes you have the following:</para> + + <itemizedlist> + <indexterm id="ppp-isp"> + <primary>ISP</primary> + </indexterm> + <indexterm id="ppp-ppp2"> + <primary>PPP</primary> + </indexterm> + <listitem> + <para>An account with an Internet Service Provider (ISP) which + you connect to using PPP.</para> + </listitem> + + <listitem> + <para>A modem or + other device connected to your system and properly configured + to allow you to connect to your ISP.</para> + </listitem> + + <listitem> + <para>The dial-up number(s) of your ISP.</para> + </listitem> + + <indexterm id="ppp-pap"> + <primary>PAP</primary> + </indexterm> + <indexterm id="ppp-chap"> + <primary>CHAP</primary> + </indexterm> + <indexterm id="ppp-unix"> + <primary>UNIX</primary> + </indexterm> + <indexterm id="ppp-login"> + <primary>login name</primary> + </indexterm> + <indexterm id="ppp-password"> + <primary>password</primary> + </indexterm> + <listitem> + <para>Your login name and password. (Either a + regular &unix; style login and password pair, or a PAP or CHAP + login and password pair).</para> + </listitem> + + <indexterm id="ppp-nameserver"> + <primary>nameserver</primary> + </indexterm> + <listitem> + <para>The IP address of one or more name servers. + Normally, you will be given two IP addresses by your ISP to + use for this. If they have not given you at least one, then + you can use the <command>enable dns</command> command in + <filename>ppp.conf</filename> and + <application>ppp</application> will set the name servers for + you. This feature depends on your ISPs PPP implementation + supporting DNS negotiation.</para> + </listitem> + </itemizedlist> + + <para>The following information may be supplied by your ISP, but + is not completely necessary:</para> + + <itemizedlist> + <listitem> + <para>The IP address of your ISP's gateway. The gateway is + the machine to which you will connect and will be set up as + your <emphasis>default route</emphasis>. If you do not have + this information, we can make one up and your ISP's PPP + server will tell us the correct value when we connect.</para> + + <para>This IP number is referred to as + <literal>HISADDR</literal> by + <application>ppp</application>.</para> + </listitem> + + <listitem> + <para>The netmask you should use. If your ISP has not + provided you with one, you can safely use <hostid + role="netmask">255.255.255.255</hostid>.</para> + </listitem> + + <indexterm id="ppp-static-ip"> + <primary>static IP address</primary> + </indexterm> + <listitem> + <para>If your ISP provides you with a static IP address and + hostname, you can enter it. Otherwise, we simply let the + peer assign whatever IP address it sees fit.</para> + </listitem> + </itemizedlist> + + <para>If you do not have any of the required information, contact + your ISP.</para> + + <note> + <para>Throughout this section, many of the examples showing + the contents of configuration files are numbered by line. + These numbers serve to aid in the presentation and + discussion only and are not meant to be placed in the actual + file. Proper indentation with tab and space characters is + also important.</para> + </note> + + </sect3> + + <sect3> + <title>Automatic <application>PPP</application> Configuration</title> + + <indexterm> + <primary>PPP</primary> + <secondary>configuration</secondary> + </indexterm> + + <para>Both <command>ppp</command> and <command>pppd</command> + (the kernel level implementation of PPP, &os; 7.X only) use the configuration + files located in the <filename class="directory">/etc/ppp</filename> directory. + Examples for user ppp can be found in + <filename class="directory">/usr/share/examples/ppp/</filename>.</para> + + <para>Configuring <command>ppp</command> requires that you edit a + number of files, depending on your requirements. What you put + in them depends to some extent on whether your ISP allocates IP + addresses statically (i.e., you get given one IP address, and + always use that one) or dynamically (i.e., your IP address + changes each time you connect to your ISP).</para> + + <sect4 id="userppp-staticIP"> + <title>PPP and Static IP Addresses</title> + + <indexterm> + <primary>PPP</primary> + <secondary>with static IP addresses</secondary> + </indexterm> + + <para>You will need to edit the + <filename>/etc/ppp/ppp.conf</filename> configuration file. It + should look similar to the example below.</para> + + <note> + <para>Lines that end in a <literal>:</literal> start in + the first column (beginning of the line)— all other + lines should be indented as shown using spaces or + tabs.</para> + </note> + + <programlisting>1 default: +2 set log Phase Chat LCP IPCP CCP tun command +3 ident user-ppp VERSION (built COMPILATIONDATE) +4 set device /dev/cuau0 +5 set speed 115200 +6 set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 5 \ +7 \"\" AT OK-AT-OK ATE1Q0 OK \\dATDT\\T TIMEOUT 40 CONNECT" +8 set timeout 180 +9 enable dns +10 +11 provider: +12 set phone "(123) 456 7890" +13 set authname foo +14 set authkey bar +15 set login "TIMEOUT 10 \"\" \"\" gin:--gin: \\U word: \\P col: ppp" +16 set timeout 300 +17 set ifaddr <replaceable>x.x.x.x</replaceable> <replaceable>y.y.y.y</replaceable> 255.255.255.255 0.0.0.0 +18 add default HISADDR</programlisting> + + <variablelist> + <varlistentry> + <term>Line 1:</term> + + <listitem> + <para>Identifies the default entry. Commands in this + entry are executed automatically when ppp is run.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 2:</term> + + <listitem> + <para>Enables logging parameters. When the configuration + is working satisfactorily, this line should be reduced + to saying:</para> + + <programlisting>set log phase tun</programlisting> + + <para>in order to avoid excessive log file sizes.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 3:</term> + + <listitem> + <para>Tells PPP how to identify itself to the peer. + PPP identifies itself to the peer if it has any trouble + negotiating and setting up the link, providing information + that the peers administrator may find useful when + investigating such problems.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 4:</term> + + <listitem> + <para>Identifies the device to which the modem is + connected. <devicename>COM1</devicename> is + <filename class="devicefile">/dev/cuau0</filename> + and + <devicename>COM2</devicename> is + <filename class="devicefile">/dev/cuau1</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 5:</term> + + <listitem> + <para>Sets the speed you want to connect at. If 115200 + does not work (it should with any reasonably new modem), + try 38400 instead.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 6 & 7:</term> + + <indexterm> + <primary>PPP</primary> + <secondary>user PPP</secondary> + </indexterm> + + <listitem> + <para>The dial string. User PPP uses an expect-send + syntax similar to the &man.chat.8; program. Refer to + the manual page for information on the features of this + language.</para> + + <para>Note that this command continues onto the next line + for readability. Any command in + <filename>ppp.conf</filename> may do this if the last + character on the line is a <literal>\</literal> character.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 8:</term> + + <listitem> + <para>Sets the idle timeout for the link. 180 seconds + is the default, so this line is purely cosmetic.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 9:</term> + + <listitem> + <para>Tells PPP to ask the peer to confirm the local + resolver settings. If you run a local name server, this + line should be commented out or removed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 10:</term> + + <listitem> + <para>A blank line for readability. Blank lines are ignored + by PPP.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 11:</term> + + <listitem> + <para>Identifies an entry for a provider called + <quote>provider</quote>. This could be changed + to the name of your <acronym>ISP</acronym> so + that later you can use the <option>load <replaceable>ISP</replaceable></option> + to start the connection.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 12:</term> + + <listitem> + <para>Sets the phone number for this provider. Multiple + phone numbers may be specified using the colon + (<literal>:</literal>) or pipe character + (<literal>|</literal>) as a separator. The difference + between the two separators is described in &man.ppp.8;. + To summarize, if you want to rotate through the numbers, + use a colon. If you want to always attempt to dial the + first number first and only use the other numbers if the + first number fails, use the pipe character. Always + quote the entire set of phone numbers as shown.</para> + + <para>You must enclose the phone number in quotation marks + (<literal>"</literal>) if there is any intention on using + spaces in the phone number. This can cause a simple, yet + subtle error.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 13 & 14:</term> + + <listitem> + <para>Identifies the user name and password. When + connecting using a &unix; style login prompt, these + values are referred to by the <command>set + login</command> command using the \U and \P + variables. When connecting using PAP or CHAP, these + values are used at authentication time.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 15:</term> + + <listitem> + <indexterm><primary>PAP</primary></indexterm> + <indexterm><primary>CHAP</primary></indexterm> + <para>If you are using PAP or CHAP, there will be no login + at this point, and this line should be commented out or + removed. See <link linkend="userppp-PAPnCHAP">PAP and CHAP + authentication</link> for further details.</para> + + <para>The login string is of the same chat-like syntax as + the dial string. In this example, the string works for + a service whose login session looks like this:</para> + + <screen>J. Random Provider +login: <replaceable>foo</replaceable> +password: <replaceable>bar</replaceable> +protocol: ppp</screen> + + <para>You will need to alter this script to suit your + own needs. When you write this script for the first + time, you should ensure that you have enabled + <quote>chat</quote> logging so you can determine if + the conversation is going as expected.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 16:</term> + + <indexterm><primary>timeout</primary></indexterm> + <listitem> + <para>Sets the default idle timeout (in seconds) for the + connection. Here, the connection will be closed + automatically after 300 seconds of inactivity. If you + never want to timeout, set this value to zero or use + the <option>-ddial</option> command line switch.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 17:</term> + <indexterm><primary>ISP</primary></indexterm> + <listitem> + <para>Sets the interface addresses. The string + <replaceable>x.x.x.x</replaceable> should be + replaced by the IP address that your provider has + allocated to you. The string + <replaceable>y.y.y.y</replaceable> should be + replaced by the IP address that your ISP indicated + for their gateway (the machine to which you + connect). If your ISP has not given you a gateway + address, use <hostid + role="netmask">10.0.0.2/0</hostid>. If you need to + use a <quote>guessed</quote> address, make sure that + you create an entry in + <filename>/etc/ppp/ppp.linkup</filename> as per the + instructions for <link + linkend="userppp-dynamicIP">PPP and Dynamic IP + addresses</link>. If this line is omitted, + <command>ppp</command> cannot run in + <option>-auto</option> mode.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 18:</term> + + <listitem> + <para>Adds a default route to your ISP's gateway. The + special word <literal>HISADDR</literal> is replaced with + the gateway address specified on line 17. It is + important that this line appears after line 17, + otherwise <literal>HISADDR</literal> will not yet be + initialized.</para> + + <para>If you do not wish to run ppp in <option>-auto</option>, + this line should be moved to the + <filename>ppp.linkup</filename> file.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>It is not necessary to add an entry to + <filename>ppp.linkup</filename> when you have a static IP + address and are running ppp in <option>-auto</option> mode as your + routing table entries are already correct before you connect. + You may however wish to create an entry to invoke programs after + connection. This is explained later with the sendmail + example.</para> + + <para>Example configuration files can be found in the + <filename class="directory">/usr/share/examples/ppp/</filename> directory.</para> + </sect4> + + <sect4 id="userppp-dynamicIP"> + <title>PPP and Dynamic IP Addresses</title> + + <indexterm> + <primary>PPP</primary> + <secondary>with dynamic IP addresses</secondary> + </indexterm> + + <indexterm> + <primary>IPCP</primary> + </indexterm> + + <para>If your service provider does not assign static IP + addresses, <command>ppp</command> can be configured to + negotiate the local and remote addresses. This is done by + <quote>guessing</quote> an IP address and allowing + <command>ppp</command> to set it up correctly using the IP + Configuration Protocol (IPCP) after connecting. The + <filename>ppp.conf</filename> configuration is the same as + <link linkend="userppp-staticIP">PPP and Static IP + Addresses</link>, with the following change:</para> + + <programlisting>17 set ifaddr 10.0.0.1/0 10.0.0.2/0 255.255.255.255 0.0.0.0</programlisting> + + <para>Again, do not include the line number, it is just for + reference. Indentation of at least one space is + required.</para> + + <variablelist> + <varlistentry> + <term>Line 17:</term> + + <listitem> + <para>The number after the <literal>/</literal> character + is the number of bits of the address that ppp will + insist on. You may wish to use IP numbers more + appropriate to your circumstances, but the above example + will always work.</para> + + <para>The last argument (<literal>0.0.0.0</literal>) tells + PPP to start negotiations using address <hostid + role="ipaddr">0.0.0.0</hostid> rather than <hostid + role="ipaddr">10.0.0.1</hostid> and is necessary for some + ISPs. Do not use <literal>0.0.0.0</literal> as the first + argument to <command>set ifaddr</command> as it prevents + PPP from setting up an initial route in + <option>-auto</option> mode.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>If you are not running in <option>-auto</option> mode, you + will need to create an entry in + <filename>/etc/ppp/ppp.linkup</filename>. + <filename>ppp.linkup</filename> is used after a connection has + been established. At this point, <command>ppp</command> will + have assigned the interface addresses and it will now be + possible to add the routing table entries:</para> + + <programlisting>1 provider: +2 add default HISADDR</programlisting> + + <variablelist> + <varlistentry> + <term>Line 1:</term> + + <listitem> + <para>On establishing a connection, + <command>ppp</command> will look for an entry in + <filename>ppp.linkup</filename> according to the + following rules: First, try to match the same label + as we used in <filename>ppp.conf</filename>. If + that fails, look for an entry for the IP address of + our gateway. This entry is a four-octet IP style + label. If we still have not found an entry, look + for the <literal>MYADDR</literal> entry.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 2:</term> + + <listitem> + <para>This line tells <command>ppp</command> to add a + default route that points to + <literal>HISADDR</literal>. + <literal>HISADDR</literal> will be replaced with the + IP number of the gateway as negotiated by the + IPCP.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>See the <literal>pmdemand</literal> entry in the files + <filename>/usr/share/examples/ppp/ppp.conf.sample</filename> + and + <filename>/usr/share/examples/ppp/ppp.linkup.sample</filename> + for a detailed example.</para> + </sect4> + + <sect4> + <title>Receiving Incoming Calls</title> + + <indexterm> + <primary>PPP</primary> + <secondary>receiving incoming calls</secondary> + </indexterm> + + <para>When you configure <application>ppp</application> to + receive incoming calls on a machine connected to a LAN, you + must decide if you wish to forward packets to the LAN. If you + do, you should allocate the peer an IP number from your LAN's + subnet, and use the command <command>enable proxy</command> in + your <filename>/etc/ppp/ppp.conf</filename> file. You should + also confirm that the <filename>/etc/rc.conf</filename> file + contains the following:</para> + + <programlisting>gateway_enable="YES"</programlisting> + </sect4> + + <sect4> + <title>Which getty?</title> + + <para><link linkend="dialup">Configuring FreeBSD for Dial-up + Services</link> provides a good description on enabling + dial-up services using &man.getty.8;.</para> + + <para>An alternative to <command>getty</command> is <ulink + url="http://mgetty.greenie.net/">mgetty</ulink> (from + <filename role="package">comms/mgetty+sendfax</filename> + port), + a smarter version of <command>getty</command> designed + with dial-up lines in mind.</para> + + <para>The advantages of using <command>mgetty</command> is + that it actively <emphasis>talks</emphasis> to modems, + meaning if port is turned off in + <filename>/etc/ttys</filename> then your modem will not answer + the phone.</para> + + <para>Later versions of <command>mgetty</command> (from + 0.99beta onwards) also support the automatic detection of + PPP streams, allowing your clients script-less access to + your server.</para> + + <para>Refer to <link linkend="userppp-mgetty">Mgetty and + AutoPPP</link> for more information on + <command>mgetty</command>.</para> + </sect4> + + <sect4> + <title><application>PPP</application> Permissions</title> + + <para>The <command>ppp</command> command must normally be + run as the <username>root</username> user. If however, + you wish to allow <command>ppp</command> to run in + server mode as a normal user by executing + <command>ppp</command> as described below, that user + must be given permission to run <command>ppp</command> + by adding them to the <groupname>network</groupname> group + in <filename>/etc/group</filename>.</para> + + <para>You will also need to give them access to one or more + sections of the configuration file using the + <command>allow</command> command:</para> + + <programlisting>allow users fred mary</programlisting> + + <para>If this command is used in the <literal>default</literal> + section, it gives the specified users access to + everything.</para> + </sect4> + + <sect4> + <title>PPP Shells for Dynamic-IP Users</title> + + <indexterm> + <primary>PPP shells</primary> + </indexterm> + + <para>Create a file called + <filename>/etc/ppp/ppp-shell</filename> containing the + following:</para> + + <programlisting>#!/bin/sh +IDENT=`echo $0 | sed -e 's/^.*-\(.*\)$/\1/'` +CALLEDAS="$IDENT" +TTY=`tty` + +if [ x$IDENT = xdialup ]; then + IDENT=`basename $TTY` +fi + +echo "PPP for $CALLEDAS on $TTY" +echo "Starting PPP for $IDENT" + +exec /usr/sbin/ppp -direct $IDENT</programlisting> + + <para>This script should be executable. Now make a symbolic + link called <filename>ppp-dialup</filename> to this script + using the following commands:</para> + + <screen>&prompt.root; <userinput>ln -s ppp-shell /etc/ppp/ppp-dialup</userinput></screen> + + <para>You should use this script as the + <emphasis>shell</emphasis> for all of your dialup users. + This is an example from <filename>/etc/passwd</filename> + for a dialup PPP user with username + <username>pchilds</username> (remember do not directly edit + the password file, use &man.vipw.8;).</para> + + <programlisting>pchilds:*:1011:300:Peter Childs PPP:/home/ppp:/etc/ppp/ppp-dialup</programlisting> + + <para>Create a <filename class="directory">/home/ppp</filename> directory that + is world readable containing the following 0 byte + files:</para> + + <screen>-r--r--r-- 1 root wheel 0 May 27 02:23 .hushlogin +-r--r--r-- 1 root wheel 0 May 27 02:22 .rhosts</screen> + + <para>which prevents <filename>/etc/motd</filename> from being + displayed.</para> + </sect4> + + <sect4> + <title>PPP Shells for Static-IP Users</title> + + <indexterm> + <primary>PPP shells</primary> + </indexterm> + + <para>Create the <filename>ppp-shell</filename> file as above, + and for each account with statically assigned IPs create a + symbolic link to <filename>ppp-shell</filename>.</para> + + <para>For example, if you have three dialup customers, + <username>fred</username>, <username>sam</username>, and + <username>mary</username>, that you route /24 CIDR networks + for, you would type the following:</para> + + <screen>&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-fred</userinput> +&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-sam</userinput> +&prompt.root; <userinput>ln -s /etc/ppp/ppp-shell /etc/ppp/ppp-mary</userinput></screen> + + <para>Each of these users dialup accounts should have their + shell set to the symbolic link created above (for example, + <username>mary</username>'s shell should be + <filename>/etc/ppp/ppp-mary</filename>).</para> + </sect4> + + <sect4> + <title>Setting Up <filename>ppp.conf</filename> for Dynamic-IP + Users</title> + + <para>The <filename>/etc/ppp/ppp.conf</filename> file should + contain something along the lines of:</para> + + <programlisting>default: + set debug phase lcp chat + set timeout 0 + +ttyu0: + set ifaddr 203.14.100.1 203.14.100.20 255.255.255.255 + enable proxy + +ttyu1: + set ifaddr 203.14.100.1 203.14.100.21 255.255.255.255 + enable proxy</programlisting> + + <note> + <para>The indenting is important.</para> + </note> + + <para>The <literal>default:</literal> section is loaded for + each session. For each dialup line enabled in + <filename>/etc/ttys</filename> create an entry similar to + the one for <literal>ttyu0:</literal> above. Each line + should get a unique IP address from your pool of IP + addresses for dynamic users.</para> + </sect4> + + <sect4> + <title>Setting Up <filename>ppp.conf</filename> for Static-IP + Users</title> + + <para>Along with the contents of the sample + <filename>/usr/share/examples/ppp/ppp.conf</filename> + above you should add a section for each of the + statically assigned dialup users. We will continue with + our <username>fred</username>, <username>sam</username>, + and <username>mary</username> example.</para> + + <programlisting>fred: + set ifaddr 203.14.100.1 203.14.101.1 255.255.255.255 + +sam: + set ifaddr 203.14.100.1 203.14.102.1 255.255.255.255 + +mary: + set ifaddr 203.14.100.1 203.14.103.1 255.255.255.255</programlisting> + + <para>The file <filename>/etc/ppp/ppp.linkup</filename> + should also contain routing information for each static + IP user if required. The line below would add a route + for the <hostid role="ipaddr">203.14.101.0/24</hostid> + network via the client's ppp link.</para> + + <programlisting>fred: + add 203.14.101.0 netmask 255.255.255.0 HISADDR + +sam: + add 203.14.102.0 netmask 255.255.255.0 HISADDR + +mary: + add 203.14.103.0 netmask 255.255.255.0 HISADDR</programlisting> + </sect4> + + <sect4 id="userppp-mgetty"> + <title><command>mgetty</command> and AutoPPP</title> + + <indexterm> + <primary><command>mgetty</command></primary> + </indexterm> + + <indexterm> + <primary>AutoPPP</primary> + </indexterm> + + <indexterm> + <primary>LCP</primary> + </indexterm> + + <para>By default the <filename + role="package">comms/mgetty+sendfax</filename> port + comes + with the <literal>AUTO_PPP</literal> option enabled + allowing <command>mgetty</command> to detect the LCP phase + of PPP connections and automatically spawn off a ppp + shell. However, since the default login/password + sequence does not occur it is necessary to authenticate + users using either PAP or CHAP.</para> + + <para>This section assumes the user has successfully + compiled, and installed the <filename + role="package">comms/mgetty+sendfax</filename> port on + his system.</para> + + <para>Make sure your + <filename>/usr/local/etc/mgetty+sendfax/login.config</filename> + file has the following in it:</para> + + <programlisting>/AutoPPP/ - - /etc/ppp/ppp-pap-dialup</programlisting> + + <para>This will tell <command>mgetty</command> to run the + <filename>ppp-pap-dialup</filename> script for detected + PPP connections.</para> + + <para>Create a file called + <filename>/etc/ppp/ppp-pap-dialup</filename> containing the + following (the file should be executable):</para> + + <programlisting>#!/bin/sh +exec /usr/sbin/ppp -direct pap$IDENT</programlisting> + + <para>For each dialup line enabled in + <filename>/etc/ttys</filename>, create a corresponding entry + in <filename>/etc/ppp/ppp.conf</filename>. This will + happily co-exist with the definitions we created + above.</para> + + <programlisting>pap: + enable pap + set ifaddr 203.14.100.1 203.14.100.20-203.14.100.40 + enable proxy</programlisting> + + <para>Each user logging in with this method will need to have + a username/password in + <filename>/etc/ppp/ppp.secret</filename> file, or + alternatively add the following option to authenticate users + via PAP from the <filename>/etc/passwd</filename> file.</para> + + <programlisting>enable passwdauth</programlisting> + + <para>If you wish to assign some users a static IP number, + you can specify the number as the third argument in + <filename>/etc/ppp/ppp.secret</filename>. See + <filename>/usr/share/examples/ppp/ppp.secret.sample</filename> + for examples.</para> + </sect4> + + <sect4> + <title>MS Extensions</title> + + <indexterm> + <primary>DNS</primary> + </indexterm> + + <indexterm> + <primary>NetBIOS</primary> + </indexterm> + + <indexterm> + <primary>PPP</primary> + <secondary>Microsoft extensions</secondary> + </indexterm> + + <para>It is possible to configure PPP to supply DNS and + NetBIOS nameserver addresses on demand.</para> + + <para>To enable these extensions with PPP version 1.x, the + following lines might be added to the relevant section of + <filename>/etc/ppp/ppp.conf</filename>.</para> + + <programlisting>enable msext +set ns 203.14.100.1 203.14.100.2 +set nbns 203.14.100.5</programlisting> + + <para>And for PPP version 2 and above:</para> + + <programlisting>accept dns +set dns 203.14.100.1 203.14.100.2 +set nbns 203.14.100.5</programlisting> + + <para>This will tell the clients the primary and secondary + name server addresses, and a NetBIOS nameserver host.</para> + + <para>In version 2 and above, if the + <literal>set dns</literal> line is omitted, PPP will use the + values found in <filename>/etc/resolv.conf</filename>.</para> + </sect4> + + <sect4 id="userppp-PAPnCHAP"> + <title>PAP and CHAP Authentication</title> + <indexterm><primary>PAP</primary></indexterm> + <indexterm><primary>CHAP</primary></indexterm> + <para>Some ISPs set their system up so that the authentication + part of your connection is done using either of the PAP or + CHAP authentication mechanisms. If this is the case, your ISP + will not give a <prompt>login:</prompt> prompt when you + connect, but will start talking PPP immediately.</para> + + <para>PAP is less secure than CHAP, but security is not normally + an issue here as passwords, although being sent as plain text + with PAP, are being transmitted down a serial line only. + There is not much room for crackers to + <quote>eavesdrop</quote>.</para> + + <para>Referring back to the <link linkend="userppp-staticIP">PPP + and Static IP addresses</link> or <link + linkend="userppp-dynamicIP">PPP and Dynamic IP addresses</link> + sections, the following alterations must be made:</para> + + <programlisting>13 set authname <replaceable>MyUserName</replaceable> +14 set authkey <replaceable>MyPassword</replaceable> +15 set login</programlisting> + + <variablelist> + <varlistentry> + <term>Line 13:</term> + + <listitem> + <para>This line specifies your PAP/CHAP user name. You + will need to insert the correct value for + <replaceable>MyUserName</replaceable>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 14:</term> + <indexterm><primary>password</primary></indexterm> + <listitem> + <para>This line specifies your PAP/CHAP password. You + will need to insert the correct value for + <replaceable>MyPassword</replaceable>. You may want to + add an additional line, such as:</para> + + <programlisting>16 accept PAP</programlisting> + + <para>or</para> + + <programlisting>16 accept CHAP</programlisting> + + <para>to make it obvious that this is the intention, but + PAP and CHAP are both accepted by default.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Line 15:</term> + + <listitem> + <para>Your ISP will not normally require that you log into + the server if you are using PAP or CHAP. You must + therefore disable your <quote>set login</quote> + string.</para> + </listitem> + </varlistentry> + </variablelist> + </sect4> + + <sect4> + <title>Changing Your <command>ppp</command> Configuration on the + Fly</title> + + <para>It is possible to talk to the <command>ppp</command> + program while it is running in the background, but only if a + suitable diagnostic port has been set up. To do this, add the + following line to your configuration:</para> + + <programlisting>set server /var/run/ppp-tun<replaceable>%d</replaceable> DiagnosticPassword 0177</programlisting> + + <para>This will tell PPP to listen to the specified + &unix; domain socket, asking clients for the specified + password before allowing access. The + <literal>%d</literal> in the name is replaced with the + <devicename>tun</devicename> device number that is in + use.</para> + + <para>Once a socket has been set up, the &man.pppctl.8; + program may be used in scripts that wish to manipulate the + running program.</para> + </sect4> + </sect3> + + <sect3 id="userppp-nat"> + <title>Using PPP Network Address Translation Capability</title> + + <indexterm> + <primary>PPP</primary><secondary>NAT</secondary> + </indexterm> + + <para>PPP has ability to use internal NAT without kernel diverting + capabilities. This functionality may be enabled by the following + line in <filename>/etc/ppp/ppp.conf</filename>:</para> + + <programlisting>nat enable yes</programlisting> + + <para>Alternatively, PPP NAT may be enabled by command-line + option <literal>-nat</literal>. There is also + <filename>/etc/rc.conf</filename> knob named + <literal>ppp_nat</literal>, which is enabled by default.</para> + + <para>If you use this feature, you may also find useful + the following <filename>/etc/ppp/ppp.conf</filename> options + to enable incoming connections forwarding:</para> + + <programlisting>nat port tcp 10.0.0.2:ftp ftp +nat port tcp 10.0.0.2:http http</programlisting> + + <para>or do not trust the outside at all</para> + + <programlisting>nat deny_incoming yes</programlisting> + </sect3> + + <sect3 id="userppp-final"> + <title>Final System Configuration</title> + + <indexterm> + <primary>PPP</primary><secondary>configuration</secondary> + </indexterm> + + <para>You now have <command>ppp</command> configured, but there + are a few more things to do before it is ready to work. They + all involve editing the <filename>/etc/rc.conf</filename> + file.</para> + + <para>Working from the top down in this file, make sure the + <literal>hostname=</literal> line is set, e.g.:</para> + + <programlisting>hostname="foo.example.com"</programlisting> + + <para>If your ISP has supplied you with a static IP address and + name, it is probably best that you use this name as your host + name.</para> + + <para>Look for the <literal>network_interfaces</literal> variable. + If you want to configure your system to dial your ISP on demand, + make sure the <devicename>tun0</devicename> device is added to + the list, otherwise remove it.</para> + + <programlisting>network_interfaces="lo0 tun0" +ifconfig_tun0=</programlisting> + + <note> + <para>The <literal>ifconfig_tun0</literal> variable should be + empty, and a file called + <filename>/etc/start_if.tun0</filename> should be created. + This file should contain the line:</para> + + <programlisting>ppp -auto mysystem</programlisting> + + <para>This script is executed at network configuration time, + starting your ppp daemon in automatic mode. If you have a LAN + for which this machine is a gateway, you may also wish to use + the <option>-alias</option> switch. Refer to the manual page + for further details.</para> + </note> + + <para>Make sure that the router program is set to + <literal>NO</literal> with the following line in your + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>router_enable="NO"</programlisting> + + <indexterm> + <primary><application>routed</application></primary> + </indexterm> + + <para>It is important that the <command>routed</command> daemon is + not started, as <command>routed</command> tends to delete the default + routing table entries created by <command>ppp</command>.</para> + + <para>It is probably a good idea to ensure that the + <literal>sendmail_flags</literal> line does not include the + <option>-q</option> option, otherwise + <command>sendmail</command> will attempt to do a network lookup + every now and then, possibly causing your machine to dial out. + You may try:</para> + + <programlisting>sendmail_flags="-bd"</programlisting> + + <indexterm> + <primary><application>sendmail</application></primary> + </indexterm> + <para>The downside of this is that you must force + <command>sendmail</command> to re-examine the mail queue + whenever the ppp link is up by typing:</para> + + <screen>&prompt.root; <userinput>/usr/sbin/sendmail -q</userinput></screen> + + <para>You may wish to use the <command>!bg</command> command in + <filename>ppp.linkup</filename> to do this automatically:</para> + + <programlisting>1 provider: +2 delete ALL +3 add 0 0 HISADDR +4 !bg sendmail -bd -q30m</programlisting> + + <indexterm> + <primary>SMTP</primary> + </indexterm> + + <para>If you do not like this, it is possible to set up a + <quote>dfilter</quote> to block SMTP traffic. Refer to the + sample files for further details.</para> + + <para>All that is left is to reboot the machine. After rebooting, + you can now either type:</para> + + <screen>&prompt.root; <userinput>ppp</userinput></screen> + + <para>and then <command>dial provider</command> to start the PPP + session, or, if you want <command>ppp</command> to establish + sessions automatically when there is outbound traffic (and + you have not created the <filename>start_if.tun0</filename> + script), type:</para> + + <screen>&prompt.root; <userinput>ppp -auto provider</userinput></screen> + </sect3> + + <sect3> + <title>Summary</title> + + <para>To recap, the following steps are necessary when setting up + ppp for the first time:</para> + + <para>Client side:</para> + + <procedure> + <step> + <para>Ensure that the <devicename>tun</devicename> device is + built into your kernel.</para> + </step> + + <step> + <para>Ensure that the + <filename class="devicefile">tun<replaceable>N</replaceable></filename> device + file is available in the <filename class="directory">/dev</filename> + directory.</para> + </step> + + <step> + <para>Create an entry in + <filename>/etc/ppp/ppp.conf</filename>. The + <filename>pmdemand</filename> example should suffice for + most ISPs.</para> + </step> + + <step> + <para>If you have a dynamic IP address, create an entry in + <filename>/etc/ppp/ppp.linkup</filename>.</para> + </step> + + <step> + <para>Update your <filename>/etc/rc.conf</filename> + file.</para> + </step> + + <step> + <para>Create a <filename>start_if.tun0</filename> script if + you require demand dialing.</para> + </step> + </procedure> + + <para>Server side:</para> + + <procedure> + <step> + <para>Ensure that the <devicename>tun</devicename> device is + built into your kernel.</para> + </step> + + <step> + <para>Ensure that the + <filename class="devicefile">tun<replaceable>N</replaceable></filename> device + file is available in the <filename class="directory">/dev</filename> + directory.</para> + </step> + + <step> + <para>Create an entry in <filename>/etc/passwd</filename> + (using the &man.vipw.8; program).</para> + </step> + + <step> + <para>Create a profile in this users home directory that runs + <command>ppp -direct direct-server</command> or + similar.</para> + </step> + + <step> + <para>Create an entry in + <filename>/etc/ppp/ppp.conf</filename>. The + <filename>direct-server</filename> example should + suffice.</para> + </step> + + <step> + <para>Create an entry in + <filename>/etc/ppp/ppp.linkup</filename>.</para> + </step> + + <step> + <para>Update your <filename>/etc/rc.conf</filename> + file.</para> + </step> + </procedure> + </sect3> + </sect2> + </sect1> + + <sect1 id="ppp"> + <sect1info> + <authorgroup> + <author> + <firstname>Gennady B.</firstname> + <surname>Sorokopud</surname> + <contrib>Parts originally contributed by </contrib> + </author> + <author> + <firstname>Robert</firstname> + <surname>Huff</surname> + </author> + </authorgroup> + </sect1info> + + <title>Using Kernel PPP</title> + + <warning> + <para>This section applies and is valid only for + &os; 7.X.</para> + </warning> + + <sect2> + <title>Setting Up Kernel PPP</title> + + <indexterm> + <primary>PPP</primary> + <secondary>kernel PPP</secondary> + </indexterm> + + <para>Before you start setting up PPP on your machine, make sure + that <command>pppd</command> is located in + <filename class="directory">/usr/sbin</filename> and the directory + <filename class="directory">/etc/ppp</filename> exists.</para> + + <para><command>pppd</command> can work in two modes:</para> + + <orderedlist> + <listitem> + <para>As a <quote>client</quote> — you want to connect your + machine to the outside world via a PPP serial connection or + modem line.</para> + </listitem> + + <indexterm> + <primary>PPP</primary> + <secondary>server</secondary> + </indexterm> + + <listitem> + <para>As a <quote>server</quote> — your machine is located on + the network, and is used to connect other computers using + PPP.</para> + </listitem> + </orderedlist> + + <para>In both cases you will need to set up an options file + (<filename>/etc/ppp/options</filename> or + <filename>~/.ppprc</filename> if you have more than one user on + your machine that uses PPP).</para> + + <para>You will also need some modem/serial software (preferably + <filename role="package">comms/kermit</filename>), so you can dial and + establish a connection with the remote host.</para> + </sect2> + + <sect2> + <sect2info> + <authorgroup> + <author> + <firstname>Trev</firstname> + <surname>Roydhouse</surname> + <contrib>Based on information provided by </contrib> + <!-- Trev.Roydhouse@f401.n711.z3.fidonet.org --> + </author> + </authorgroup> + </sect2info> + + <title>Using <command>pppd</command> as a Client</title> + + <indexterm> + <primary>PPP</primary> + <secondary>client</secondary> + </indexterm> + + <indexterm> + <primary>Cisco</primary> + </indexterm> + + <para>The following <filename>/etc/ppp/options</filename> might be + used to connect to a Cisco terminal server PPP line.</para> + + <programlisting>crtscts # enable hardware flow control +modem # modem control line +noipdefault # remote PPP server must supply your IP address + # if the remote host does not send your IP during IPCP + # negotiation, remove this option +passive # wait for LCP packets +domain ppp.foo.com # put your domain name here + +:<replaceable>remote_ip</replaceable> # put the IP of remote PPP host here + # it will be used to route packets via PPP link + # if you didn't specified the noipdefault option + # change this line to <replaceable>local_ip</replaceable>:<replaceable>remote_ip</replaceable> + +defaultroute # put this if you want that PPP server will be your + # default router</programlisting> + + <para>To connect:</para> + + <indexterm><primary>Kermit</primary></indexterm> + <indexterm><primary>modem</primary></indexterm> + <procedure> + <step> + <para>Dial to the remote host using + <application>Kermit</application> (or some other modem + program), and enter your user name and password (or whatever + is needed to enable PPP on the remote host).</para> + </step> + + <step> + <para>Exit <application>Kermit</application> (without + hanging up the line).</para> + </step> + + <step> + <para>Enter the following:</para> + + <screen>&prompt.root; <userinput>/usr/sbin/pppd <replaceable>/dev/tty01</replaceable> <replaceable>19200</replaceable></userinput></screen> + + <para>Be sure to use the appropriate speed and device name.</para> + </step> + </procedure> + + <para>Now your computer is connected with PPP. If the connection + fails, you can add the <option>debug</option> option to the + <filename>/etc/ppp/options</filename> file, and check console messages + to track the problem.</para> + + <para>Following <filename>/etc/ppp/pppup</filename> script will make + all 3 stages automatic:</para> + + <programlisting>#!/bin/sh +pgrep -l pppd +pid=`pgrep pppd` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +pgrep -l kermit +pid=`pgrep kermit` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +ifconfig ppp0 down +ifconfig ppp0 delete + +kermit -y /etc/ppp/kermit.dial +pppd /dev/tty01 19200</programlisting> + + <indexterm> + <primary>Kermit</primary> + </indexterm> + + <para><filename>/etc/ppp/kermit.dial</filename> is a + <application>Kermit</application> script that dials and makes all + necessary authorization on the remote host (an example of such a + script is attached to the end of this document).</para> + + <para>Use the following <filename>/etc/ppp/pppdown</filename> script + to disconnect the PPP line:</para> + + <programlisting>#!/bin/sh +pid=`pgrep pppd` +if [ X${pid} != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill -TERM ${pid} +fi + +pgrep -l kermit +pid=`pgrep kermit` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +/sbin/ifconfig ppp0 down +/sbin/ifconfig ppp0 delete +kermit -y /etc/ppp/kermit.hup +/etc/ppp/ppptest</programlisting> + + <para>Check to see if <command>pppd</command> is still running by + executing <filename>/usr/etc/ppp/ppptest</filename>, which should look + like this:</para> + + <programlisting>#!/bin/sh +pid=`pgrep pppd` +if [ X${pid} != "X" ] ; then + echo 'pppd running: PID=' ${pid-NONE} +else + echo 'No pppd running.' +fi +set -x +netstat -n -I ppp0 +ifconfig ppp0</programlisting> + + <para>To hang up the modem, execute + <filename>/etc/ppp/kermit.hup</filename>, which should + contain:</para> + + <programlisting>set line /dev/tty01 ; put your modem device here +set speed 19200 +set file type binary +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none + +pau 1 +out +++ +inp 5 OK +out ATH0\13 +echo \13 +exit</programlisting> + + <para>Here is an alternate method using <command>chat</command> + instead of <command>kermit</command>:</para> + + <para>The following two files are sufficient to accomplish a + <command>pppd</command> connection.</para> + + <para><filename>/etc/ppp/options</filename>:</para> + + <programlisting>/dev/cuad1 115200 + +crtscts # enable hardware flow control +modem # modem control line +connect "/usr/bin/chat -f /etc/ppp/login.chat.script" +noipdefault # remote PPP serve must supply your IP address + # if the remote host doesn't send your IP during + # IPCP negotiation, remove this option +passive # wait for LCP packets +domain <replaceable>your.domain</replaceable> # put your domain name here + +: # put the IP of remote PPP host here + # it will be used to route packets via PPP link + # if you didn't specified the noipdefault option + # change this line to <replaceable>local_ip</replaceable>:<replaceable>remote_ip</replaceable> + +defaultroute # put this if you want that PPP server will be + # your default router</programlisting> + + <para><filename>/etc/ppp/login.chat.script</filename>:</para> + + <note> + <para>The following should go on a single line.</para> + </note> + + <programlisting>ABORT BUSY ABORT 'NO CARRIER' "" AT OK ATDT<replaceable>phone.number</replaceable> + CONNECT "" TIMEOUT 10 ogin:-\\r-ogin: <replaceable>login-id</replaceable> + TIMEOUT 5 sword: <replaceable>password</replaceable></programlisting> + + <para>Once these are installed and modified correctly, all you need + to do is run <command>pppd</command>, like so:</para> + + <screen>&prompt.root; <userinput>pppd</userinput></screen> + </sect2> + + <sect2> + <title>Using <command>pppd</command> as a Server</title> + + <para><filename>/etc/ppp/options</filename> should contain something + similar to the following:</para> + + <programlisting>crtscts # Hardware flow control +netmask 255.255.255.0 # netmask (not required) +192.114.208.20:192.114.208.165 # IP's of local and remote hosts + # local ip must be different from one + # you assigned to the Ethernet (or other) + # interface on your machine. + # remote IP is IP address that will be + # assigned to the remote machine +domain ppp.foo.com # your domain +passive # wait for LCP +modem # modem line</programlisting> + + <para>The following <filename>/etc/ppp/pppserv</filename> script + will tell <application>pppd</application> to behave as a + server:</para> + + <programlisting>#!/bin/sh +pgrep -l pppd +pid=`pgrep pppd` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +pgrep -l kermit +pid=`pgrep kermit` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi + +# reset ppp interface +ifconfig ppp0 down +ifconfig ppp0 delete + +# enable autoanswer mode +kermit -y /etc/ppp/kermit.ans + +# run ppp +pppd /dev/tty01 19200</programlisting> + + <para>Use this <filename>/etc/ppp/pppservdown</filename> script to + stop the server:</para> + + <programlisting>#!/bin/sh +pgrep -l pppd +pid=`pgrep pppd` +if [ "X${pid}" != "X" ] ; then + echo 'killing pppd, PID=' ${pid} + kill ${pid} +fi +pgrep -l kermit +pid=`pgrep kermit` +if [ "X${pid}" != "X" ] ; then + echo 'killing kermit, PID=' ${pid} + kill -9 ${pid} +fi +ifconfig ppp0 down +ifconfig ppp0 delete + +kermit -y /etc/ppp/kermit.noans</programlisting> + + <para>The following <application>Kermit</application> script + (<filename>/etc/ppp/kermit.ans</filename>) will enable/disable + autoanswer mode on your modem. It should look like this:</para> + + <programlisting>set line /dev/tty01 +set speed 19200 +set file type binary +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none + +pau 1 +out +++ +inp 5 OK +out ATH0\13 +inp 5 OK +echo \13 +out ATS0=1\13 ; change this to out ATS0=0\13 if you want to disable + ; autoanswer mode +inp 5 OK +echo \13 +exit</programlisting> + + <para>A script named <filename>/etc/ppp/kermit.dial</filename> is + used for dialing and authenticating on the remote host. You will + need to customize it for your needs. Put your login and password + in this script; you will also need to change the input statement + depending on responses from your modem and remote host.</para> + + <programlisting>; +; put the com line attached to the modem here: +; +set line /dev/tty01 +; +; put the modem speed here: +; +set speed 19200 +set file type binary ; full 8 bit file xfer +set file names literal +set win 8 +set rec pack 1024 +set send pack 1024 +set block 3 +set term bytesize 8 +set command bytesize 8 +set flow none +set modem hayes +set dial hangup off +set carrier auto ; Then SET CARRIER if necessary, +set dial display on ; Then SET DIAL if necessary, +set input echo on +set input timeout proceed +set input case ignore +def \%x 0 ; login prompt counter +goto slhup + +:slcmd ; put the modem in command mode +echo Put the modem in command mode. +clear ; Clear unread characters from input buffer +pause 1 +output +++ ; hayes escape sequence +input 1 OK\13\10 ; wait for OK +if success goto slhup +output \13 +pause 1 +output at\13 +input 1 OK\13\10 +if fail goto slcmd ; if modem doesn't answer OK, try again + +:slhup ; hang up the phone +clear ; Clear unread characters from input buffer +pause 1 +echo Hanging up the phone. +output ath0\13 ; hayes command for on hook +input 2 OK\13\10 +if fail goto slcmd ; if no OK answer, put modem in command mode + +:sldial ; dial the number +pause 1 +echo Dialing. +output atdt9,550311\13\10 ; put phone number here +assign \%x 0 ; zero the time counter + +:look +clear ; Clear unread characters from input buffer +increment \%x ; Count the seconds +input 1 {CONNECT } +if success goto sllogin +reinput 1 {NO CARRIER\13\10} +if success goto sldial +reinput 1 {NO DIALTONE\13\10} +if success goto slnodial +reinput 1 {\255} +if success goto slhup +reinput 1 {\127} +if success goto slhup +if < \%x 60 goto look +else goto slhup + +:sllogin ; login +assign \%x 0 ; zero the time counter +pause 1 +echo Looking for login prompt. + +:slloop +increment \%x ; Count the seconds +clear ; Clear unread characters from input buffer +output \13 +; +; put your expected login prompt here: +; +input 1 {Username: } +if success goto sluid +reinput 1 {\255} +if success goto slhup +reinput 1 {\127} +if success goto slhup +if < \%x 10 goto slloop ; try 10 times to get a login prompt +else goto slhup ; hang up and start again if 10 failures + +:sluid +; +; put your userid here: +; +output ppp-login\13 +input 1 {Password: } +; +; put your password here: +; +output ppp-password\13 +input 1 {Entering SLIP mode.} +echo +quit + +:slnodial +echo \7No dialtone. Check the telephone line!\7 +exit 1 + +; local variables: +; mode: csh +; comment-start: "; " +; comment-start-skip: "; " +; end:</programlisting> + </sect2> + </sect1> + + <sect1 id="ppp-troubleshoot"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <!-- 13 June 2003 --> + </sect1info> + <title>Troubleshooting <acronym>PPP</acronym> Connections</title> + + <indexterm> + <primary>PPP</primary> + <secondary>troubleshooting</secondary> + </indexterm> + + <warning> + <para>As of &os; 8.0, the &man.uart.4; driver replaces the + &man.sio.4; driver. Device nodes for serial ports have been + renamed from + <filename>/dev/cuad<replaceable>N</replaceable></filename> to + <filename>/dev/cuau<replaceable>N</replaceable></filename> and + from + <filename>/dev/ttyd<replaceable>N</replaceable></filename> to + <filename>/dev/ttyu<replaceable>N</replaceable></filename>. + &os; 7.X users will have to adapt the following + documentation according to these changes.</para> + </warning> + + <para>This section covers a few issues which may arise when + using PPP over a modem connection. For instance, perhaps you + need to know exactly what prompts the system you are dialing + into will present. Some <acronym>ISP</acronym>s present the + <literal>ssword</literal> prompt, and others will present + <literal>password</literal>; if the <command>ppp</command> + script is not written accordingly, the login attempt will + fail. The most common way to debug <command>ppp</command> + connections is by connecting manually. The following + information will walk you through a manual connection step by + step.</para> + + <sect2> + <title>Check the Device Nodes</title> + + <para>When using a custom kernel, make sure to include the following + line in your kernel configuration file:</para> + + <programlisting>device uart</programlisting> + + <para>The <devicename>uart</devicename> device is already included + in the <literal>GENERIC</literal> kernel, so no additional steps + are necessary in this case. Just + check the <command>dmesg</command> output for the modem + device with:</para> + + <screen>&prompt.root; <userinput>dmesg | grep uart</userinput></screen> + + <para>You should get some pertinent output about the + <devicename>uart</devicename> devices. These are the COM + ports we need. If your modem acts like a standard serial + port then you should see it listed on + <devicename>uart1</devicename>, or <devicename>COM2</devicename>. If + so, you are not required to rebuild the kernel. + When matching up sio modem is on <devicename>uart1</devicename> or + <devicename>COM2</devicename> if you are in DOS, then your + modem device would be <filename class="devicefile">/dev/cuau1</filename>.</para> + </sect2> + + <sect2> + <title>Connecting Manually</title> + + <para>Connecting to the Internet by manually controlling + <command>ppp</command> is quick, easy, and a great way to + debug a connection or just get information on how your + <acronym>ISP</acronym> treats <command>ppp</command> client + connections. Lets start <application>PPP</application> from + the command line. Note that in all of our examples we will + use <emphasis>example</emphasis> as the hostname of the + machine running <application>PPP</application>. You start + <command>ppp</command> by just typing + <command>ppp</command>:</para> + + <screen>&prompt.root; <userinput>ppp</userinput></screen> + + <para>We have now started <command>ppp</command>.</para> + + <screen>ppp ON example> <userinput>set device <filename class="devicefile">/dev/cuau1</filename></userinput></screen> + + <para>We set our modem device, in this case it is + <devicename>cuau1</devicename>.</para> + + <screen>ppp ON example> <userinput>set speed 115200</userinput></screen> + + <para>Set the connection speed, in this case we + are using 115,200 <acronym>kbps</acronym>.</para> + + <screen>ppp ON example> <userinput>enable dns</userinput></screen> + + <para>Tell <command>ppp</command> to configure our + resolver and add the nameserver lines to + <filename>/etc/resolv.conf</filename>. If <command>ppp</command> + cannot determine our hostname, we can set one manually later.</para> + + <screen>ppp ON example> <userinput>term</userinput></screen> + + <para>Switch to <quote>terminal</quote> mode so that we can manually + control the modem.</para> + + <programlisting>deflink: Entering terminal mode on <filename class="devicefile">/dev/cuau1</filename> +type '~h' for help</programlisting> + + <screen><userinput>at</userinput> +OK +<userinput>atdt<replaceable>123456789</replaceable></userinput></screen> + + <para>Use <command>at</command> to initialize the modem, + then use <command>atdt</command> and the number for your + <acronym>ISP</acronym> to begin the dial in process.</para> + + <screen>CONNECT</screen> + + <para>Confirmation of the connection, if we are going to have + any connection problems, unrelated to hardware, here is where + we will attempt to resolve them.</para> + + <screen>ISP Login:<userinput>myusername</userinput></screen> + + <para>Here you are prompted for a username, return the + prompt with the username that was provided by the + <acronym>ISP</acronym>.</para> + + <screen>ISP Pass:<userinput>mypassword</userinput></screen> + + <para>This time we are prompted for a password, just + reply with the password that was provided by the + <acronym>ISP</acronym>. Just like logging into + &os;, the password will not echo.</para> + + <screen>Shell or PPP:<userinput>ppp</userinput></screen> + + <para>Depending on your <acronym>ISP</acronym> this prompt + may never appear. Here we are being asked if we wish to + use a shell on the provider, or to start + <command>ppp</command>. In this example, we have chosen + to use <command>ppp</command> as we want an Internet + connection.</para> + + <screen>Ppp ON example></screen> + + <para>Notice that in this example the first <option>p</option> + has been capitalized. This shows that we have successfully + connected to the <acronym>ISP</acronym>.</para> + + <screen>PPp ON example></screen> + + <para>We have successfully authenticated with our + <acronym>ISP</acronym> and are waiting for the + assigned <acronym>IP</acronym> address.</para> + + <screen>PPP ON example></screen> + + <para>We have made an agreement on an <acronym>IP</acronym> + address and successfully completed our connection.</para> + + <screen>PPP ON example><userinput>add default HISADDR</userinput></screen> + + <para>Here we add our default route, we need to do this before + we can talk to the outside world as currently the only + established connection is with the peer. If this fails due to + existing routes you can put a bang character + <literal>!</literal> in front of the <option>add</option>. + Alternatively, you can set this before making the actual + connection and it will negotiate a new route + accordingly.</para> + + <para>If everything went good we should now have an active + connection to the Internet, which could be thrown into the + background using <keycombo + action="simul"><keycap>CTRL</keycap> + <keycap>z</keycap></keycombo> If you notice the + <command>PPP</command> return to <command>ppp</command> then + we have lost our connection. This is good to know because it + shows our connection status. Capital P's show that we have a + connection to the <acronym>ISP</acronym> and lowercase p's + show that the connection has been lost for whatever reason. + <command>ppp</command> only has these 2 states.</para> + + <sect3> + <title>Debugging</title> + + <para>If you have a direct line and cannot seem to make a + connection, then turn hardware flow + <acronym>CTS/RTS</acronym> to off with the <option>set + ctsrts off</option>. This is mainly the case if you are + connected to some <application>PPP</application> capable + terminal servers, where <application>PPP</application> hangs + when it tries to write data to your communication link, so + it would be waiting for a <acronym>CTS</acronym>, or Clear + To Send signal which may never come. If you use this option + however, you should also use the <option>set accmap</option> + option, which may be required to defeat hardware dependent + on passing certain characters from end to end, most of the + time XON/XOFF. See the &man.ppp.8; manual page for more + information on this option, and how it is used.</para> + + <para>If you have an older modem, you may need to use the + <option>set parity even</option>. Parity is set at none + be default, but is used for error checking (with a large + increase in traffic) on older modems and some + <acronym>ISP</acronym>s. You may need this option for + the Compuserve <acronym>ISP</acronym>.</para> + + <para><application>PPP</application> may not return to the + command mode, which is usually a negotiation error where + the <acronym>ISP</acronym> is waiting for your side to start + negotiating. At this point, using the <command>~p</command> + command will force ppp to start sending the configuration + information.</para> + + <para>If you never obtain a login prompt, then most likely you + need to use <acronym>PAP</acronym> or + <acronym>CHAP</acronym> authentication instead of the + &unix; style in the example above. To use + <acronym>PAP</acronym> or <acronym>CHAP</acronym> just add + the following options to <application>PPP</application> + before going into terminal mode:</para> + + <screen>ppp ON example> <userinput>set authname <replaceable>myusername</replaceable></userinput></screen> + + <para>Where <replaceable>myusername</replaceable> should be + replaced with the username that was assigned by the + <acronym>ISP</acronym>.</para> + + <screen>ppp ON example> <userinput>set authkey <replaceable>mypassword</replaceable></userinput></screen> + + <para>Where <replaceable>mypassword</replaceable> should be + replaced with the password that was assigned by the + <acronym>ISP</acronym>.</para> + + <para>If you connect fine, but cannot seem to find any domain + name, try to use &man.ping.8; with an <acronym>IP</acronym> + address and see if you can get any return information. If + you experience 100 percent (100%) packet loss, then it is most + likely that you were not assigned a default route. Double + check that the option <option>add default HISADDR</option> + was set during the connection. If you can connect to a + remote <acronym>IP</acronym> address then it is possible + that a resolver address has not been added to the + <filename>/etc/resolv.conf</filename>. This file should + look like:</para> + + <programlisting>domain <replaceable>example.com</replaceable> +nameserver <replaceable>x.x.x.x</replaceable> +nameserver <replaceable>y.y.y.y</replaceable></programlisting> + + <para>Where <replaceable>x.x.x.x</replaceable> and + <replaceable>y.y.y.y</replaceable> should be replaced with + the <acronym>IP</acronym> address of your + <acronym>ISP</acronym>'s DNS servers. This information may + or may not have been provided when you signed up, but a + quick call to your <acronym>ISP</acronym> should remedy + that.</para> + + <para>You could also have &man.syslog.3; provide a logging + function for your <application>PPP</application> connection. + Just add:</para> + + <programlisting>!ppp +*.* /var/log/ppp.log</programlisting> + + <para>to <filename>/etc/syslog.conf</filename>. In most cases, this + functionality already exists.</para> + + </sect3> + </sect2> + </sect1> + + + + + <sect1 id="pppoe"> + <sect1info> + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Mock</surname> + <contrib>Contributed (from http://node.to/freebsd/how-tos/how-to-freebsd-pppoe.html) by </contrib> + </author> + </authorgroup> + <!-- 10 Jan 2000 --> + </sect1info> + + <title>Using PPP over Ethernet (PPPoE)</title> + + <indexterm> + <primary>PPP</primary> + <secondary>over Ethernet</secondary> + </indexterm> + + <indexterm> + <primary>PPPoE</primary> + <see>PPP, over Ethernet</see> + </indexterm> + + <para>This section describes how to set up PPP over Ethernet + (<acronym>PPPoE</acronym>).</para> + + <sect2> + <title>Configuring the Kernel</title> + + <para>No kernel configuration is necessary for PPPoE any longer. If + the necessary netgraph support is not built into the kernel, it will + be dynamically loaded by <application>ppp</application>.</para> + </sect2> + + <sect2> + <title>Setting Up <filename>ppp.conf</filename></title> + + <para>Here is an example of a working + <filename>ppp.conf</filename>:</para> + + <programlisting>default: + set log Phase tun command # you can add more detailed logging if you wish + set ifaddr 10.0.0.1/0 10.0.0.2/0 + +name_of_service_provider: + set device PPPoE:<replaceable>xl1</replaceable> # replace xl1 with your Ethernet device + set authname YOURLOGINNAME + set authkey YOURPASSWORD + set dial + set login + add default HISADDR</programlisting> + + </sect2> + + <sect2> + <title>Running <application>ppp</application></title> + + <para>As <username>root</username>, you can run:</para> + + <screen>&prompt.root; <userinput>ppp -ddial name_of_service_provider</userinput></screen> + + </sect2> + + <sect2> + <title>Starting <application>ppp</application> at Boot</title> + + <para>Add the following to your <filename>/etc/rc.conf</filename> + file:</para> + + <programlisting>ppp_enable="YES" +ppp_mode="ddial" +ppp_nat="YES" # if you want to enable nat for your local network, otherwise NO +ppp_profile="name_of_service_provider"</programlisting> + </sect2> + + <sect2> + <title>Using a PPPoE Service Tag</title> + + <para>Sometimes it will be necessary to use a service tag to establish + your connection. Service tags are used to distinguish between + different PPPoE servers attached to a given network.</para> + + <para>You should have been given any required service tag information + in the documentation provided by your ISP. If you cannot locate + it there, ask your ISP's tech support personnel.</para> + + <para>As a last resort, you could try the method suggested by the + <ulink url="http://www.roaringpenguin.com/pppoe/">Roaring Penguin + PPPoE</ulink> program which can be found in the <link + linkend="ports">Ports Collection</link>. Bear in mind however, + this may de-program your modem and render it useless, so + think twice before doing it. Simply install the program shipped + with the modem by your provider. Then, access the + <guimenu>System</guimenu> menu from the program. The name of your + profile should be listed there. It is usually + <emphasis>ISP</emphasis>.</para> + + <para>The profile name (service tag) will be used in the PPPoE + configuration entry in <filename>ppp.conf</filename> as the provider + part of the <command>set device</command> command (see the &man.ppp.8; + manual page for full details). It should look like this:</para> + + <programlisting>set device PPPoE:<replaceable>xl1</replaceable>:<replaceable>ISP</replaceable></programlisting> + + <para>Do not forget to change <replaceable>xl1</replaceable> + to the proper device for your Ethernet card.</para> + <para>Do not forget to change <replaceable>ISP</replaceable> + to the profile you have just found above.</para> + + <para>For additional information, see:</para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://renaud.waldura.com/doc/freebsd/pppoe/">Cheaper + Broadband with FreeBSD on DSL</ulink> by Renaud + Waldura.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2 id="ppp-3com"> + + <title>PPPoE with a &tm.3com; <trademark + class="registered">HomeConnect</trademark> ADSL Modem Dual + Link</title> + + <para>This modem does not follow <ulink + url="http://www.faqs.org/rfcs/rfc2516.html">RFC 2516</ulink> + (<emphasis>A Method for transmitting PPP over Ethernet + (PPPoE)</emphasis>, written by L. Mamakos, K. Lidl, J. Evarts, + D. Carrel, D. Simone, and R. Wheeler). Instead, different packet + type codes have been used for the Ethernet frames. Please complain + to <ulink url="http://www.3com.com/">3Com</ulink> if you think it + should comply with the PPPoE specification.</para> + + <para>In order to make FreeBSD capable of communicating with this + device, a sysctl must be set. This can be done automatically at + boot time by updating <filename>/etc/sysctl.conf</filename>:</para> + + <programlisting>net.graph.nonstandard_pppoe=1</programlisting> + + <para>or can be done immediately with the command:</para> + + <screen>&prompt.root; <userinput>sysctl net.graph.nonstandard_pppoe=1</userinput></screen> + + <para>Unfortunately, because this is a system-wide setting, it is + not possible to talk to a normal PPPoE client or server and a + &tm.3com; <trademark class="registered">HomeConnect</trademark> + ADSL Modem at the same time.</para> + + </sect2> + </sect1> + + <sect1 id="pppoa"> + <title>Using <application>PPP</application> over ATM (PPPoA)</title> + + <indexterm> + <primary>PPP</primary> + <secondary>over ATM</secondary> + </indexterm> + + <indexterm> + <primary>PPPoA</primary> + <see>PPP, over ATM</see> + </indexterm> + + <para>The following describes how to set up PPP over ATM (PPPoA). + PPPoA is a popular choice among European DSL providers.</para> + + <sect2> + <title>Using PPPoA with the Alcatel &speedtouch; USB</title> + + <para>PPPoA support for this device is supplied as a port in + FreeBSD because the firmware is distributed under <ulink + url="http://www.speedtouchdsl.com/disclaimer_lx.htm">Alcatel's + license agreement</ulink> and can not be redistributed freely + with the base system of FreeBSD.</para> + + <para>To install the software, simply use the <link + linkend="ports">Ports Collection</link>. Install the + <filename role="package">net/pppoa</filename> port and follow the + instructions provided with it.</para> + + <para>Like many USB devices, the Alcatel &speedtouch; USB needs to + download firmware from the host computer to operate properly. + It is possible to automate this process in &os; so that this + transfer takes place whenever the device is plugged into a USB + port. The following information can be added to the + <filename>/etc/usbd.conf</filename> file to enable this + automatic firmware transfer. This file must be edited as the + <username>root</username> user.</para> + + <programlisting>device "Alcatel SpeedTouch USB" + devname "ugen[0-9]+" + vendor 0x06b9 + product 0x4061 + attach "/usr/local/sbin/modem_run -f /usr/local/libdata/mgmt.o"</programlisting> + + <para>To enable the USB daemon, <application>usbd</application>, + put the following the line into + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>usbd_enable="YES"</programlisting> + + <para>It is also possible to set up + <application>ppp</application> to dial up at startup. To do + this add the following lines to + <filename>/etc/rc.conf</filename>. Again, for this procedure + you will need to be logged in as the <username>root</username> + user.</para> + + <programlisting>ppp_enable="YES" +ppp_mode="ddial" +ppp_profile="adsl"</programlisting> + + <para>For this to work correctly you will need to have used the + sample <filename>ppp.conf</filename> which is supplied with the + <filename role="package">net/pppoa</filename> port.</para> + + </sect2> + + <sect2> + <title>Using mpd</title> + + <para>You can use <application>mpd</application> to connect to a + variety of services, in particular PPTP services. You can find + <application>mpd</application> in the Ports Collection, + <filename role="package">net/mpd</filename>. Many ADSL modems + require that a PPTP tunnel is created between the modem and + computer, one such modem is the Alcatel &speedtouch; + Home.</para> + + <para>First you must install the port, and then you can + configure <application>mpd</application> to suit your + requirements and provider settings. The port places a set of + sample configuration files which are well documented in + <filename class="directory"><replaceable>PREFIX</replaceable>/etc/mpd/</filename>. + Note here that <replaceable>PREFIX</replaceable> means the directory + into which your ports are installed, this defaults to + <filename class="directory">/usr/local/</filename>. A complete guide to + configure <application>mpd</application> is available in + HTML format once the port has been installed. It is placed in + <filename class="directory"><replaceable>PREFIX</replaceable>/share/doc/mpd/</filename>. + Here is a sample configuration for connecting to an ADSL + service with <application>mpd</application>. The configuration + is spread over two files, first the + <filename>mpd.conf</filename>:</para> + + <programlisting>default: + load adsl + +adsl: + new -i ng0 adsl adsl + set bundle authname <replaceable>username</replaceable> <co + id="co-mpd-ex-user"> + set bundle password <replaceable>password</replaceable> <co + id="co-mpd-ex-pass"> + set bundle disable multilink + + set link no pap acfcomp protocomp + set link disable chap + set link accept chap + set link keep-alive 30 10 + + set ipcp no vjcomp + set ipcp ranges 0.0.0.0/0 0.0.0.0/0 + + set iface route default + set iface disable on-demand + set iface enable proxy-arp + set iface idle 0 + + open</programlisting> + + <calloutlist> + <callout arearefs="co-mpd-ex-user"> + <para>The username used to authenticate with your ISP.</para> + </callout> + <callout arearefs="co-mpd-ex-pass"> + <para>The password used to authenticate with your ISP.</para> + </callout> + </calloutlist> + + <para>The <filename>mpd.links</filename> file contains information about + the link, or links, you wish to establish. An example + <filename>mpd.links</filename> to accompany the above example is given + beneath:</para> + + <programlisting>adsl: + set link type pptp + set pptp mode active + set pptp enable originate outcall + set pptp self <replaceable>10.0.0.1</replaceable> <co + id="co-mpd-ex-self"> + set pptp peer <replaceable>10.0.0.138</replaceable> <co + id="co-mpd-ex-peer"></programlisting> + + <calloutlist> + <callout arearefs="co-mpd-ex-self"> + <para>The IP address of your &os; computer which you will be + using <application>mpd</application> from.</para> + </callout> + <callout arearefs="co-mpd-ex-peer"> + <para>The IP address of your ADSL modem. For the Alcatel + &speedtouch; Home this address defaults to <hostid + role="ipaddr">10.0.0.138</hostid>.</para> + </callout> + </calloutlist> + + <para>It is possible to initialize the connection easily by issuing the + following command as <username>root</username>:</para> + + <screen>&prompt.root; <userinput>mpd -b <replaceable>adsl</replaceable></userinput></screen> + + <para>You can see the status of the connection with the following + command:</para> + + <screen>&prompt.user; <userinput>ifconfig <replaceable>ng0</replaceable></userinput> +ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500 + inet 216.136.204.117 --> 204.152.186.171 netmask 0xffffffff</screen> + + <para>Using <application>mpd</application> is the recommended way to + connect to an ADSL service with &os;.</para> + + </sect2> + + <sect2> + <title>Using pptpclient</title> + + <para>It is also possible to use FreeBSD to connect to other PPPoA + services using + <filename role="package">net/pptpclient</filename>.</para> + + <para>To use <filename role="package">net/pptpclient</filename> to + connect to a DSL service, install the port or package and edit your + <filename>/etc/ppp/ppp.conf</filename>. You will need to be + <username>root</username> to perform both of these operations. An + example section of <filename>ppp.conf</filename> is given + below. For further information on <filename>ppp.conf</filename> + options consult the <application>ppp</application> manual page, + &man.ppp.8;.</para> + + <programlisting>adsl: + set log phase chat lcp ipcp ccp tun command + set timeout 0 + enable dns + set authname <replaceable>username</replaceable> <co id="co-pptp-ex-user"> + set authkey <replaceable>password</replaceable> <co id="co-pptp-ex-pass"> + set ifaddr 0 0 + add default HISADDR</programlisting> + + <calloutlist> + <callout arearefs="co-pptp-ex-user"> + <para>The username of your account with the DSL provider.</para> + </callout> + <callout arearefs="co-pptp-ex-pass"> + <para>The password for your account.</para> + </callout> + </calloutlist> + + <warning> + <para>Because you must put your account's password in the + <filename>ppp.conf</filename> file in plain text form you should + make sure than nobody can read the contents of this file. The + following series of commands will make sure the file is only + readable by the <username>root</username> account. Refer to the + manual pages for &man.chmod.1; and &man.chown.8; for further + information.</para> + <screen>&prompt.root; <userinput>chown root:wheel /etc/ppp/ppp.conf</userinput> +&prompt.root; <userinput>chmod 600 /etc/ppp/ppp.conf</userinput></screen> + </warning> + + <para>This will open a tunnel for a PPP session to your DSL router. + Ethernet DSL modems have a preconfigured LAN IP address which you + connect to. In the case of the Alcatel &speedtouch; Home this address + is <hostid role="ipaddr">10.0.0.138</hostid>. Your router documentation + should tell you which address your device uses. To open the tunnel and + start a PPP session execute the following + command:</para> + + <screen>&prompt.root; <userinput>pptp <replaceable>address</replaceable> <replaceable>adsl</replaceable></userinput></screen> + + <tip> + <para>You may wish to add an ampersand (<quote>&</quote>) to the + end of the previous command because <application>pptp</application> + will not return your prompt to you otherwise.</para> + </tip> + + <para>A <devicename>tun</devicename> virtual tunnel device will be + created for interaction between the <application>pptp</application> + and <application>ppp</application> processes. Once you have been + returned to your prompt, or the <application>pptp</application> + process has confirmed a connection you can examine the tunnel like + so:</para> + + <screen>&prompt.user; <userinput>ifconfig <replaceable>tun0</replaceable></userinput> +tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500 + inet 216.136.204.21 --> 204.152.186.171 netmask 0xffffff00 + Opened by PID 918</screen> + + <para>If you are unable to connect, check the configuration of + your router, which is usually accessible via + <application>telnet</application> or with a web browser. If you still + cannot connect you should examine the output of the + <command>pptp</command> command and the contents of the + <application>ppp</application> log file, + <filename>/var/log/ppp.log</filename> for clues.</para> + </sect2> + </sect1> + + <sect1 id="slip"> + <sect1info> + <authorgroup> + <author> + <firstname>Satoshi</firstname> + <surname>Asami</surname> + <contrib>Originally contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Guy</firstname> + <surname>Helmer</surname> + <contrib>With input from </contrib> + </author> + <author> + <firstname>Piero</firstname> + <surname>Serini</surname> + </author> + </authorgroup> + </sect1info> + + <title>Using SLIP</title> + <indexterm><primary>SLIP</primary></indexterm> + + <warning> + <para>This section applies and is valid only for + &os; 7.X.</para> + </warning> + + <sect2 id="slipc"> + <title>Setting Up a SLIP Client</title> + + <indexterm> + <primary>SLIP</primary> + <secondary>client</secondary> + </indexterm> + + <para>The following is one way to set up a FreeBSD machine for SLIP + on a static host network. For dynamic hostname assignments (your + address changes each time you dial up), you probably need to + have a more complex setup.</para> + + <para>First, determine which serial port your modem is connected to. + Many people set up a symbolic link, such as + <filename class="devicefile">/dev/modem</filename>, to point to the real device name, + <filename class="devicefile">/dev/cuad<replaceable>N</replaceable></filename>. + This allows you to abstract the actual device + name should you ever need to move the modem to a different port. It + can become quite cumbersome when you need to fix a bunch of files in + <filename class="directory">/etc</filename> and <filename>.kermrc</filename> files all + over the system!</para> + + <note> + <para><filename class="devicefile">/dev/cuad0</filename> + is + <devicename>COM1</devicename>, <filename class="devicefile">/dev/cuad1</filename> + is + <devicename>COM2</devicename>, etc.</para> + </note> + + <para>Make sure you have the following in your kernel configuration + file:</para> + + <programlisting>device sl</programlisting> + + <para>It is included in the <filename>GENERIC</filename> kernel, so + this should not be a problem unless you have deleted it.</para> + + <sect3> + <title>Things You Have to Do Only Once</title> + + <procedure> + <step> + <para>Add your home machine, the gateway and nameservers to + your <filename>/etc/hosts</filename> file. Ours looks like + this:</para> + + <programlisting>127.0.0.1 localhost loghost +136.152.64.181 water.CS.Example.EDU water.CS water +136.152.64.1 inr-3.CS.Example.EDU inr-3 slip-gateway +128.32.136.9 ns1.Example.EDU ns1 +128.32.136.12 ns2.Example.EDU ns2</programlisting> + </step> + + <step> + <para>Make sure you have <literal>files</literal> before + <literal>dns</literal> in the <literal>hosts:</literal> + section of your <filename>/etc/nsswitch.conf</filename> + file. Without these parameters funny things may + happen.</para> + </step> + + <step> + <para>Edit the <filename>/etc/rc.conf</filename> file.</para> + + <orderedlist> + <listitem> + <para>Set your hostname by editing the line that + says:</para> + + <programlisting>hostname="myname.my.domain"</programlisting> + + <para>Your machine's full Internet hostname should be + placed here.</para> + </listitem> + + <indexterm><primary>default route</primary></indexterm> + <listitem> + <para>Designate the default router by changing the + line:</para> + + <programlisting>defaultrouter="NO"</programlisting> + + <para>to:</para> + + <programlisting>defaultrouter="slip-gateway"</programlisting> + </listitem> + </orderedlist> + </step> + + <step> + <para>Make a file <filename>/etc/resolv.conf</filename> which + contains:</para> + + <programlisting>domain CS.Example.EDU +nameserver 128.32.136.9 +nameserver 128.32.136.12</programlisting> + + <indexterm><primary>nameserver</primary></indexterm> + <indexterm><primary>domain name</primary></indexterm> + <para>As you can see, these set up the nameserver hosts. Of + course, the actual domain names and addresses depend on your + environment.</para> + </step> + + <step> + <para>Set the password for <username>root</username> and + <username>toor</username> (and any other + accounts that do not have a password).</para> + </step> + + <step> + <para>Reboot your machine and make sure it comes up with the + correct hostname.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Making a SLIP Connection</title> + + <indexterm> + <primary>SLIP</primary> + <secondary>connecting with</secondary> + </indexterm> + + <procedure> + <step> + <para>Dial up, type <command>slip</command> at the prompt, + enter your machine name and password. What is required to + be entered depends on your environment. If you use + <application>Kermit</application>, you can try a script like + this:</para> + + <programlisting># kermit setup +set modem hayes +set line /dev/modem +set speed 115200 +set parity none +set flow rts/cts +set terminal bytesize 8 +set file type binary +# The next macro will dial up and login +define slip dial 643-9600, input 10 =>, if failure stop, - +output slip\x0d, input 10 Username:, if failure stop, - +output silvia\x0d, input 10 Password:, if failure stop, - +output ***\x0d, echo \x0aCONNECTED\x0a</programlisting> + + <para>Of course, you have to change the username and password + to fit yours. After doing so, you can just type + <command>slip</command> from the + <application>Kermit</application> prompt to connect.</para> + + <note> + <para>Leaving your password in plain text anywhere in the + filesystem is generally a <emphasis>bad</emphasis> idea. + Do it at your own risk.</para> + </note> + </step> + + <step> + <para>Leave the <application>Kermit</application> there (you can + suspend it by + <keycombo> + <keycap>Ctrl</keycap> + <keycap>z</keycap> + </keycombo>) and as <username>root</username>, type:</para> + + <screen>&prompt.root; <userinput>slattach -h -c -s 115200 /dev/modem</userinput></screen> + + <para>If you are able to <command>ping</command> hosts on the + other side of the router, you are connected! If it does not + work, you might want to try <option>-a</option> instead of + <option>-c</option> as an argument to + <command>slattach</command>.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>How to Shutdown the Connection</title> + + <para>Do the following:</para> + + <screen>&prompt.root; <userinput>kill -INT `cat /var/run/slattach.modem.pid`</userinput></screen> + + <para>to kill <command>slattach</command>. Keep in mind you must be + <username>root</username> to do the above. Then go back to + <command>kermit</command> (by running <command>fg</command> if you + suspended it) and exit from it (<keycap>q</keycap>).</para> + + <para>The &man.slattach.8; manual page says you have + to use <command>ifconfig sl0 down</command> + to mark the interface down, but this does not + seem to make any difference. + (<command>ifconfig sl0</command> reports the same thing.)</para> + + <para>Some times, your modem might refuse to drop the carrier. + In that case, simply start <command>kermit</command> and quit + it again. It usually goes out on the second try.</para> + </sect3> + + <sect3> + <title>Troubleshooting</title> + + <para>If it does not work, feel free to ask on &a.net.name; mailing + list. The things that people tripped over so far:</para> + + <itemizedlist> + <listitem> + <para>Not using <option>-c</option> or <option>-a</option> in + <command>slattach</command> (This should not be fatal, + but some users have reported that this solves their + problems.)</para> + </listitem> + + <listitem> + <para>Using <option>s10</option> instead of + <option>sl0</option> (might be hard to see the difference on + some fonts).</para> + </listitem> + + <listitem> + <para>Try <command>ifconfig sl0</command> to see your + interface status. For example, you might get:</para> + + <screen>&prompt.root; <userinput>ifconfig sl0</userinput> +sl0: flags=10<POINTOPOINT> + inet 136.152.64.181 --> 136.152.64.1 netmask ffffff00</screen> + </listitem> + + <listitem> + <para>If you get <errorname>no route to host</errorname> + messages from &man.ping.8;, there may be a problem with your + routing table. You can use the <command>netstat -r</command> + command to display the current routes :</para> + + <screen>&prompt.root; <userinput>netstat -r</userinput> +Routing tables +Destination Gateway Flags Refs Use IfaceMTU Rtt Netmasks: + +(root node) +(root node) + +Route Tree for Protocol Family inet: +(root node) => +default inr-3.Example.EDU UG 8 224515 sl0 - - +localhost.Exampl localhost.Example. UH 5 42127 lo0 - 0.438 +inr-3.Example.ED water.CS.Example.E UH 1 0 sl0 - - +water.CS.Example localhost.Example. UGH 34 47641234 lo0 - 0.438 +(root node)</screen> + + <para>The preceding examples are from a relatively busy system. + The numbers on your system will vary depending on + network activity.</para> + + </listitem> + </itemizedlist> + </sect3> + </sect2> + + <sect2 id="slips"> + <title>Setting Up a SLIP Server</title> + + <indexterm> + <primary>SLIP</primary> + <secondary>server</secondary> + </indexterm> + + <para>This document provides suggestions for setting up SLIP Server + services on a FreeBSD system, which typically means configuring + your system to automatically start up connections upon login for + remote SLIP clients.</para> + + <!-- Disclaimer is not necessarily relevant + <para> The author has written this document based + on his experience; however, as your system and needs may be + different, this document may not answer all of your questions, and + the author cannot be responsible if you damage your system or lose + data due to attempting to follow the suggestions here.</para> + --> + + <sect3 id="slips-prereqs"> + <title>Prerequisites</title> + <indexterm><primary>TCP/IP networking</primary></indexterm> + <para>This section is very technical in nature, so background + knowledge is required. It is assumed that you are familiar with + the TCP/IP network protocol, and in particular, network and node + addressing, network address masks, subnetting, routing, and + routing protocols, such as RIP. Configuring SLIP services on a + dial-up server requires a knowledge of these concepts, and if + you are not familiar with them, please read a copy of either + Craig Hunt's <emphasis>TCP/IP Network Administration</emphasis> + published by O'Reilly & Associates, Inc. (ISBN Number + 0-937175-82-X), or Douglas Comer's books on the TCP/IP + protocol.</para> + + <indexterm><primary>modem</primary></indexterm> + <para>It is further assumed that you have already set up your + modem(s) and configured the appropriate system files to allow + logins through your modems. If you have not prepared your + system for this yet, please see <xref + linkend="dialup"> for details on dialup services + configuration. + You may also want to check the manual pages for &man.sio.4; for + information on the serial port device driver and &man.ttys.5;, + &man.gettytab.5;, &man.getty.8;, & &man.init.8; for + information relevant to configuring the system to accept logins + on modems, and perhaps &man.stty.1; for information on setting + serial port parameters (such as <literal>clocal</literal> for + directly-connected serial interfaces).</para> + </sect3> + + <sect3> + <title>Quick Overview</title> + + <para>In its typical configuration, using FreeBSD as a SLIP server + works as follows: a SLIP user dials up your FreeBSD SLIP Server + system and logs in with a special SLIP login ID that uses + <filename>/usr/sbin/sliplogin</filename> as the special user's + shell. The <command>sliplogin</command> program browses the + file <filename>/etc/sliphome/slip.hosts</filename> to find a + matching line for the special user, and if it finds a match, + connects the serial line to an available SLIP interface and then + runs the shell script + <filename>/etc/sliphome/slip.login</filename> to configure the + SLIP interface.</para> + + <sect4> + <title>An Example of a SLIP Server Login</title> + + <para>For example, if a SLIP user ID were + <username>Shelmerg</username>, <username>Shelmerg</username>'s + entry in <filename>/etc/master.passwd</filename> would look + something like this:</para> + + <programlisting>Shelmerg:password:1964:89::0:0:Guy Helmer - SLIP:/usr/users/Shelmerg:/usr/sbin/sliplogin</programlisting> + + <para>When <username>Shelmerg</username> logs in, + <command>sliplogin</command> will search + <filename>/etc/sliphome/slip.hosts</filename> for a line that + had a matching user ID; for example, there may be a line in + <filename>/etc/sliphome/slip.hosts</filename> that + reads:</para> + + <programlisting>Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting> + + <para><command>sliplogin</command> will find that matching line, + hook the serial line into the next available SLIP interface, + and then execute <filename>/etc/sliphome/slip.login</filename> + like this:</para> + + <programlisting>/etc/sliphome/slip.login 0 19200 Shelmerg dc-slip sl-helmer 0xfffffc00 autocomp</programlisting> + + <para>If all goes well, + <filename>/etc/sliphome/slip.login</filename> will issue an + <command>ifconfig</command> for the SLIP interface to which + <command>sliplogin</command> attached itself (SLIP interface + 0, in the above example, which was the first parameter in the + list given to <filename>slip.login</filename>) to set the + local IP address (<hostid>dc-slip</hostid>), remote IP address + (<hostid>sl-helmer</hostid>), network mask for the SLIP + interface (<hostid role="netmask">0xfffffc00</hostid>), and + any additional flags (<literal>autocomp</literal>). If + something goes wrong, <command>sliplogin</command> usually + logs good informational messages via the + <application>syslogd</application> daemon facility, which usually + logs to <filename>/var/log/messages</filename> (see the manual + pages for &man.syslogd.8; and &man.syslog.conf.5; and perhaps + check <filename>/etc/syslog.conf</filename> to see to what + <application>syslogd</application> is logging and where it is + logging to).</para> + </sect4> + </sect3> + + <sect3> + <title>Kernel Configuration</title> + + <indexterm> + <primary>kernel</primary> + <secondary>configuration</secondary> + </indexterm> + + <indexterm> + <primary>SLIP</primary> + </indexterm> + + <para>&os;'s default kernel (<filename>GENERIC</filename>) + comes with SLIP (&man.sl.4;) support; in case of a custom + kernel, you have to add the following line to your kernel + configuration file:</para> + + <programlisting>device sl</programlisting> + + <para>By default, your &os; machine will not forward packets. + If you want your FreeBSD SLIP Server to act as a router, you + will have to edit the <filename>/etc/rc.conf</filename> file and + change the setting of the <literal>gateway_enable</literal> variable + to <option>YES</option>. This will make sure that setting the + routing option will be persistent after a reboot.</para> + + <para>To apply the settings immediately you can execute the + following command as <username>root</username>:</para> + + <screen>&prompt.root; /etc/rc.d/routing start</screen> + + <para>Please refer to <xref linkend="kernelconfig"> on + Configuring the FreeBSD Kernel for help in + reconfiguring your kernel.</para> + </sect3> + + <sect3> + <title>Sliplogin Configuration</title> + + <para>As mentioned earlier, there are three files in the + <filename class="directory">/etc/sliphome</filename> directory that are part of + the configuration for <filename>/usr/sbin/sliplogin</filename> + (see &man.sliplogin.8; for the actual manual page for + <command>sliplogin</command>): <filename>slip.hosts</filename>, + which defines the SLIP users and their associated IP + addresses; <filename>slip.login</filename>, which usually just + configures the SLIP interface; and (optionally) + <filename>slip.logout</filename>, which undoes + <filename>slip.login</filename>'s effects when the serial + connection is terminated.</para> + + <sect4> + <title><filename>slip.hosts</filename> Configuration</title> + + <para><filename>/etc/sliphome/slip.hosts</filename> contains + lines which have at least four items separated by + whitespace:</para> + + <itemizedlist> + <listitem> + <para>SLIP user's login ID</para> + </listitem> + + <listitem> + <para>Local address (local to the SLIP server) of the SLIP + link</para> + </listitem> + + <listitem> + <para>Remote address of the SLIP link</para> + </listitem> + + <listitem> + <para>Network mask</para> + </listitem> + </itemizedlist> + + <para>The local and remote addresses may be host names + (resolved to IP addresses by + <filename>/etc/hosts</filename> or by the domain name + service, depending on your specifications in the file + <filename>/etc/nsswitch.conf</filename>), and the network mask + may be a name that can be resolved by a lookup into + <filename>/etc/networks</filename>. On a sample system, + <filename>/etc/sliphome/slip.hosts</filename> looks like + this:</para> + + <programlisting># +# login local-addr remote-addr mask opt1 opt2 +# (normal,compress,noicmp) +# +Shelmerg dc-slip sl-helmerg 0xfffffc00 autocomp</programlisting> + + <para>At the end of the line is one or more of the + options:</para> + + <itemizedlist> + <listitem> + <para><option>normal</option> — no header + compression</para> + </listitem> + + <listitem> + <para><option>compress</option> — compress + headers</para> + </listitem> + + <listitem> + <para><option>autocomp</option> — compress headers if + the remote end allows it</para> + </listitem> + + <listitem> + <para><option>noicmp</option> — disable ICMP packets + (so any <quote>ping</quote> packets will be dropped instead + of using up your bandwidth)</para> + </listitem> + </itemizedlist> + + <indexterm><primary>SLIP</primary></indexterm> + <indexterm><primary>TCP/IP networking</primary></indexterm> + <para>Your choice of local and remote addresses for your SLIP + links depends on whether you are going to dedicate a TCP/IP + subnet or if you are going to use <quote>proxy ARP</quote> on + your SLIP server (it is not <quote>true</quote> proxy ARP, but + that is the terminology used in this section to describe it). + If you are not sure which method to select or how to assign IP + addresses, please refer to the TCP/IP books referenced in + the SLIP Prerequisites (<xref linkend="slips-prereqs">) + and/or consult your IP network manager.</para> + + <para>If you are going to use a separate subnet for your SLIP + clients, you will need to allocate the subnet number out of + your assigned IP network number and assign each of your SLIP + client's IP numbers out of that subnet. Then, you will + probably need to configure a static route to the SLIP + subnet via your SLIP server on your nearest IP router.</para> + + <indexterm><primary>Ethernet</primary></indexterm> + <para>Otherwise, if you will use the <quote>proxy ARP</quote> + method, you will need to assign your SLIP client's IP + addresses out of your SLIP server's Ethernet subnet, and you + will also need to adjust your + <filename>/etc/sliphome/slip.login</filename> and + <filename>/etc/sliphome/slip.logout</filename> scripts to use + &man.arp.8; to manage the <quote>proxy ARP</quote> entries in the SLIP + server's ARP table.</para> + </sect4> + + <sect4> + <title><filename>slip.login</filename> Configuration</title> + + <para>The typical <filename>/etc/sliphome/slip.login</filename> + file looks like this:</para> + + <programlisting>#!/bin/sh - +# +# @(#)slip.login 5.1 (Berkeley) 7/1/90 + +# +# generic login file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 inet $4 $5 netmask $6</programlisting> + + <para>This <filename>slip.login</filename> file merely runs + <command>ifconfig</command> for the appropriate SLIP interface + with the local and remote addresses and network mask of the + SLIP interface.</para> + + <para>If you have decided to use the <quote>proxy ARP</quote> + method (instead of using a separate subnet for your SLIP + clients), your <filename>/etc/sliphome/slip.login</filename> + file will need to look something like this:</para> + + <programlisting>#!/bin/sh - +# +# @(#)slip.login 5.1 (Berkeley) 7/1/90 + +# +# generic login file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 inet $4 $5 netmask $6 +# Answer ARP requests for the SLIP client with our Ethernet addr +/usr/sbin/arp -s $5 00:11:22:33:44:55 pub</programlisting> + + <para>The additional line in this + <filename>slip.login</filename>, <command>arp -s + $5 00:11:22:33:44:55 pub</command>, creates an ARP entry + in the SLIP server's ARP table. This ARP entry causes the + SLIP server to respond with the SLIP server's Ethernet MAC + address whenever another IP node on the Ethernet asks to + speak to the SLIP client's IP address.</para> + + <indexterm> + <primary>Ethernet</primary> + <secondary>MAC address</secondary> + </indexterm> + + <para>When using the example above, be sure to replace the + Ethernet MAC address (<hostid + role="mac">00:11:22:33:44:55</hostid>) with the MAC address of + your system's Ethernet card, or your <quote>proxy ARP</quote> + will definitely not work! You can discover your SLIP server's + Ethernet MAC address by looking at the results of running + <command>netstat -i</command>; the second line of the output + should look something like:</para> + + <screen>ed0 1500 <Link>0.2.c1.28.5f.4a 191923 0 129457 0 116</screen> + + <para>This indicates that this particular system's Ethernet MAC + address is <hostid role="mac">00:02:c1:28:5f:4a</hostid> + — the periods in the Ethernet MAC address given by + <command>netstat -i</command> must be changed to colons and + leading zeros should be added to each single-digit hexadecimal + number to convert the address into the form that &man.arp.8; + desires; see the manual page on &man.arp.8; for complete + information on usage.</para> + + <note> + <para>When you create + <filename>/etc/sliphome/slip.login</filename> and + <filename>/etc/sliphome/slip.logout</filename>, the + <quote>execute</quote> bit (i.e., <command>chmod 755 + /etc/sliphome/slip.login /etc/sliphome/slip.logout</command>) + must be set, or <command>sliplogin</command> will be unable + to execute it.</para> + </note> + </sect4> + + <sect4> + <title><filename>slip.logout</filename> Configuration</title> + + <para><filename>/etc/sliphome/slip.logout</filename> is not + strictly needed (unless you are implementing <quote>proxy + ARP</quote>), but if you decide to create it, this is an + example of a basic + <filename>slip.logout</filename> script:</para> + + <programlisting>#!/bin/sh - +# +# slip.logout + +# +# logout file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 down</programlisting> + + <para>If you are using <quote>proxy ARP</quote>, you will want to + have <filename>/etc/sliphome/slip.logout</filename> remove the + ARP entry for the SLIP client:</para> + + <programlisting>#!/bin/sh - +# +# @(#)slip.logout + +# +# logout file for a slip line. sliplogin invokes this with +# the parameters: +# 1 2 3 4 5 6 7-n +# slipunit ttyspeed loginname local-addr remote-addr mask opt-args +# +/sbin/ifconfig sl$1 down +# Quit answering ARP requests for the SLIP client +/usr/sbin/arp -d $5</programlisting> + + <para>The <command>arp -d $5</command> removes the ARP entry + that the <quote>proxy ARP</quote> + <filename>slip.login</filename> added when the SLIP client + logged in.</para> + + <para>It bears repeating: make sure + <filename>/etc/sliphome/slip.logout</filename> has the execute + bit set after you create it (i.e., <command>chmod 755 + /etc/sliphome/slip.logout</command>).</para> + </sect4> + </sect3> + + <sect3> + <title>Routing Considerations</title> + <indexterm> + <primary>SLIP</primary> + <secondary>routing</secondary> + </indexterm> + <para>If you are not using the <quote>proxy ARP</quote> method for + routing packets between your SLIP clients and the rest of your + network (and perhaps the Internet), you will probably + have to add static routes to your closest default router(s) to + route your SLIP clients subnet via your SLIP server.</para> + + <sect4> + <title>Static Routes</title> + <indexterm><primary>static routes</primary></indexterm> + + <para>Adding static routes to your nearest default routers + can be troublesome (or impossible if you do not have + authority to do so...). If you have a multiple-router + network in your organization, some routers, such as those + made by Cisco and Proteon, may not only need to be + configured with the static route to the SLIP subnet, but + also need to be told which static routes to tell other + routers about, so some expertise and + troubleshooting/tweaking may be necessary to get + static-route-based routing to work.</para> + </sect4> + </sect3> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/preface/preface.sgml b/en_US.ISO8859-1/books/handbook/preface/preface.sgml new file mode 100644 index 0000000000..3c7243792e --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/preface/preface.sgml @@ -0,0 +1,718 @@ +<!-- + $FreeBSD$ +--> + +<preface id="book-preface"> + <title>Preface</title> + + <bridgehead id="preface-audience" renderas=sect1>Intended + Audience</bridgehead> + + <para>The &os; newcomer will find that the first section of this + book guides the user through the &os; installation process and + gently introduces the concepts and conventions that underpin &unix;. + Working through this section requires little more than the desire + to explore, and the ability to take on board new concepts as they + are introduced.</para> + + <para>Once you have traveled this far, the second, far larger, + section of the Handbook is a comprehensive reference to all manner + of topics of interest to &os; system administrators. Some of + these chapters may recommend that you do some prior reading, and + this is noted in the synopsis at the beginning of each + chapter.</para> + + <para>For a list of additional sources of information, please see <xref + linkend="bibliography">.</para> + + <bridgehead id="preface-changes-from3" renderas=sect1>Changes from the + Third Edition</bridgehead> + + <para>The current online version of the Handbook represents the + cumulative effort of many hundreds of contributors over the past + 10 years. The following are some of the significant changes since + the two volume third edition was published in 2004:</para> + + <itemizedlist> + <listitem> + <para><xref linkend="dtrace">, &dtrace;, has been added with + information about the powerful &dtrace; performance analysis + tool.</para> + </listitem> + + <listitem> + <para><xref linkend="filesystems">, File Systems Support, has + been added with information about non-native file systems in + &os;, such as ZFS from &sun;.</para> + </listitem> + + <listitem> + <para><xref linkend="audit">, Security Event Auditing, has + been added to cover the new auditing capabilities in &os; + and explain its use.</para> + </listitem> + + <listitem> + <para><xref linkend="virtualization">, Virtualization, has + been added with information about installing &os; on + virtualization software.</para> + </listitem> + + <listitem> + <para><xref linkend="bsdinstall">, Installing + &os; 9.<replaceable>x</replaceable> and Later, has been + added to cover installation of &os; using the new + installation utility, + <application>bsdinstall</application>.</para> + </listitem> + </itemizedlist> + + <bridgehead id="preface-changes-from2" renderas=sect1>Changes from the + Second Edition (2004)</bridgehead> + + <para>The third edition was the culmination of over two years of + work by the dedicated members of the &os; Documentation + Project. The printed edition grew to such a size that it was + necessary to publish as two separate volumes. The following are + the major changes in this new edition:</para> + + <itemizedlist> + <listitem> + <para><xref linkend="config-tuning">, Configuration and + Tuning, has been expanded with new information about the + ACPI power and resource management, the <command>cron</command> system utility, + and more kernel tuning options.</para> + </listitem> + + <listitem> + <para><xref linkend="security">, Security, has been expanded with + new information about virtual private networks (VPNs), file + system access control lists (ACLs), and security + advisories.</para> + </listitem> + + <listitem> + <para><xref linkend="mac">, Mandatory Access Control (MAC), is + a new chapter with this edition. It explains what MAC is + and how this mechanism can be used to secure a &os; + system.</para> + </listitem> + + <listitem> + <para><xref linkend="disks">, Storage, has been expanded with + new information about USB storage devices, file system + snapshots, file system quotas, file and network backed + filesystems, and encrypted disk partitions.</para> + </listitem> + + <listitem> + <para><xref linkend="vinum-vinum">, Vinum, is a new chapter + with this edition. It describes how to use Vinum, a logical + volume manager which provides device-independent logical + disks, and software RAID-0, RAID-1 and RAID-5.</para> + </listitem> + + <listitem> + <para>A troubleshooting section has been added to <xref + linkend="ppp-and-slip">, PPP and SLIP.</para> + </listitem> + + <listitem> + <para><xref linkend="mail">, Electronic Mail, has been + expanded with new information about using alternative + transport agents, SMTP authentication, UUCP, <application>fetchmail</application>, + <application>procmail</application>, and other advanced topics.</para> + </listitem> + + <listitem> + <para><xref linkend="network-servers">, Network Servers, is + all new with this edition. This chapter includes + information about setting up the <application>Apache HTTP Server</application>, <application>ftpd</application>, + and setting up a server for µsoft; &windows; clients with + <application>Samba</application>. Some sections from <xref + linkend="advanced-networking">, Advanced Networking, were + moved here to improve the presentation.</para> + </listitem> + + <listitem> + <para><xref linkend="advanced-networking">, Advanced + Networking, has been expanded with new information about + using &bluetooth; devices with &os;, setting up wireless + networks, and Asynchronous Transfer Mode (ATM) + networking.</para> + </listitem> + + <listitem> + <para>A glossary has been added to provide a central location + for the definitions of technical terms used throughout the + book.</para> + </listitem> + + <listitem> + <para>A number of aesthetic improvements have been made to the + tables and figures throughout the book.</para> + </listitem> + </itemizedlist> + + <bridgehead id="preface-changes" renderas=sect1>Changes from the + First Edition (2001)</bridgehead> + + <para>The second edition was the culmination of over two years of + work by the dedicated members of the &os; Documentation + Project. The following were the major changes in this + edition:</para> + +<!-- Talk a little about justification and other stylesheet changes? --> + + <itemizedlist> + <listitem> + <para>A complete Index has been added.</para> + </listitem> + <listitem> + <para>All ASCII figures have been replaced by graphical diagrams.</para> + </listitem> + <listitem> + <para>A standard synopsis has been added to each chapter to + give a quick summary of what information the chapter contains, + and what the reader is expected to know.</para> + </listitem> + <listitem> + <para>The content has been logically reorganized into three + parts: <quote>Getting Started</quote>, <quote>System Administration</quote>, and + <quote>Appendices</quote>.</para> + </listitem> + <listitem> + <para><xref linkend="install"> (<quote>Installing &os;</quote>) was completely + rewritten with many screenshots to make it much easier for new + users to grasp the text.</para> + </listitem> + <listitem> + <para><xref linkend="basics"> (<quote>&unix; Basics</quote>) has been expanded to contain + additional information about processes, daemons, and + signals.</para> + </listitem> + <listitem> + <para><xref linkend="ports"> (<quote>Installing Applications</quote>) has been expanded + to contain additional information about binary package + management.</para> + </listitem> + <listitem> + <para><xref linkend="x11"> (<quote>The X Window System</quote>) has been completely + rewritten with an emphasis on using modern desktop + technologies such as <application>KDE</application> and <application>GNOME</application> on &xfree86; 4.X.</para> + </listitem> + <listitem> + <para><xref linkend="boot"> (<quote>The &os; Booting Process</quote>) has been + expanded.</para> + </listitem> + <listitem> + <para><xref linkend="disks"> (<quote>Storage</quote>) has been written from what used + to be two separate chapters on <quote>Disks</quote> and <quote>Backups</quote>. We feel + that the topics are easier to comprehend when presented as a + single chapter. A section on RAID (both hardware and + software) has also been added.</para> + </listitem> + <listitem> + <para><xref linkend="serialcomms"> (<quote>Serial Communications</quote>) has been completely + reorganized and updated for &os; 4.X/5.X.</para> + </listitem> + <listitem> + <para><xref linkend="ppp-and-slip"> (<quote>PPP and SLIP</quote>) has been substantially + updated.</para> + </listitem> + <listitem> + <para>Many new sections have been added to <xref linkend="advanced-networking"> + (<quote>Advanced Networking</quote>).</para> + </listitem> + <listitem> + <para><xref linkend="mail"> (<quote>Electronic Mail</quote>) has been expanded to + include more information about configuring + <application>sendmail</application>.</para> + </listitem> + <listitem> + <para><xref linkend="linuxemu"> (<quote>&linux; Compatibility</quote>) has been expanded to + include information about installing + <application>&oracle;</application> and + <application>&sap.r3;</application>.</para> + </listitem> + <listitem> + <para>The following new topics are covered in this second + edition:</para> + <itemizedlist> + <listitem> + <para>Configuration and Tuning (<xref linkend="config-tuning">).</para> + </listitem> + <listitem> + <para>Multimedia (<xref linkend="multimedia">)</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + + <bridgehead id="preface-overview" renderas=sect1>Organization of This + Book</bridgehead> + + <para>This book is split into five logically distinct sections. + The first section, <emphasis>Getting Started</emphasis>, covers + the installation and basic usage of &os;. It is expected that + the reader will follow these chapters in sequence, possibly + skipping chapters covering familiar topics. The second section, + <emphasis>Common Tasks</emphasis>, covers some frequently used + features of &os;. This section, and all subsequent sections, + can be read out of order. Each chapter begins with a succinct + synopsis that + describes what the chapter covers and what the reader is expected + to already know. This is meant to allow the casual reader to skip + around to find chapters of interest. The third section, + <emphasis>System Administration</emphasis>, covers administration + topics. The fourth section, <emphasis>Network + Communication</emphasis>, covers networking and server topics. + The fifth section contains + appendices of reference information.</para> + + <variablelist> + +<!-- Part I - Introduction --> + + <varlistentry> + <term><emphasis><xref linkend="introduction">, Introduction</emphasis></term> + <listitem> + <para>Introduces &os; to a new user. It describes the + history of the &os; Project, its goals and development model.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="install">, Installation of + &os; 8.<replaceable>x</replaceable> and Earlier</emphasis></term> + <listitem> + <para>Walks a user through the entire installation process of + &os; 8.<replaceable>x</replaceable> and earlier using + <application>sysinstall</application>. Some advanced installation + topics, such as installing through a serial console, are also + covered.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="bsdinstall">, Installation of + &os; 9.<replaceable>x</replaceable> and Later</emphasis></term> + <listitem> + <para>Walks a user through the entire installation process of + &os; 9.<replaceable>x</replaceable> and later using + <application>bsdinstall</application>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="basics">, &unix; Basics</emphasis></term> + <listitem> + <para>Covers the basic commands and functionality of the + &os; operating system. If you are familiar with &linux; or + another flavor of &unix; then you can probably skip this + chapter.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="ports">, Installing Applications</emphasis></term> + <listitem> + <para>Covers the installation of third-party software with + both &os;'s innovative <quote>Ports Collection</quote> and standard + binary packages.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="x11">, The X Window System</emphasis></term> + <listitem> + <para>Describes the X Window System in general and using + X11 on &os; in particular. Also describes common + desktop environments such as <application>KDE</application> and <application>GNOME</application>.</para> + </listitem> + </varlistentry> + +<!-- Part II Common Tasks --> + + <varlistentry> + <term><emphasis><xref linkend="desktop">, Desktop Applications</emphasis></term> + <listitem> + <para>Lists some common desktop applications, such as web browsers + and productivity suites, and describes how to install them on + &os;.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="multimedia">, Multimedia</emphasis></term> + <listitem> + <para>Shows how to set up sound and video playback support for your + system. Also describes some sample audio and video applications.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="kernelconfig">, Configuring the &os; + Kernel</emphasis></term> + <listitem> + <para>Explains why you might need to configure a new kernel + and provides detailed instructions for configuring, building, + and installing a custom kernel.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="printing">, Printing</emphasis></term> + <listitem> + <para>Describes managing printers on &os;, including + information about banner pages, printer accounting, and + initial setup.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="linuxemu">, &linux; Binary Compatibility</emphasis></term> + <listitem> + <para>Describes the &linux; compatibility features of &os;. + Also provides detailed installation instructions for many + popular &linux; applications such as <application>&oracle;</application> and + <application>&mathematica;</application>.</para> + </listitem> + </varlistentry> + +<!-- Part III - System Administration --> + + <varlistentry> + <term><emphasis><xref linkend="config-tuning">, Configuration and Tuning</emphasis></term> + <listitem> + <para>Describes the parameters available for system + administrators to tune a &os; system for optimum + performance. Also describes the various configuration files + used in &os; and where to find them.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="boot">, Booting Process</emphasis></term> + <listitem> + <para>Describes the &os; boot process and explains + how to control this process with configuration options.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="users">, Users and Basic Account + Management</emphasis></term> + <listitem> + <para>Describes the creation and manipulation of user + accounts. Also discusses resource limitations that can be + set on users and other account management tasks.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="security">, Security</emphasis></term> + <listitem> + <para>Describes many different tools available to help keep your + &os; system secure, including Kerberos, IPsec and OpenSSH.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="jails">, Jails</emphasis></term> + <listitem> + <para>Describes the jails framework, and the improvements of jails + over the traditional chroot support of &os;.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="mac">, Mandatory Access Control</emphasis></term> + <listitem> + <para>Explains what Mandatory Access Control (MAC) is and how this + mechanism can be used to secure a &os; system.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="audit">, Security Event Auditing</emphasis></term> + <listitem> + <para>Describes what &os; Event Auditing is, how it can be installed, + configured, and how audit trails can be inspected or monitored.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><emphasis><xref linkend="disks">, Storage</emphasis></term> + <listitem> + <para>Describes how to manage storage media and filesystems + with &os;. This includes physical disks, RAID arrays, + optical and tape media, memory-backed disks, and network + filesystems.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="geom">, GEOM</emphasis></term> + <listitem> + <para>Describes what the GEOM framework in &os; is and how + to configure various supported RAID levels.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="filesystems">, File Systems Support</emphasis></term> + <listitem> + <para>Examines support of non-native file systems in &os;, like the Z + File System from &sun;.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="vinum-vinum">, Vinum</emphasis></term> + <listitem> + <para>Describes how to use Vinum, a logical volume manager + which provides device-independent logical disks, and + software RAID-0, RAID-1 and RAID-5.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="virtualization">, Virtualization</emphasis></term> + <listitem> + <para>Describes what virtualization systems offer, and how they + can be used with &os;.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="l10n">, Localization</emphasis></term> + <listitem> + <para>Describes how to use &os; in languages other than + English. Covers both system and application level + localization.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="updating-upgrading">, Updating and Upgrading &os;</emphasis></term> + <listitem> + <para>Explains the differences between &os;-STABLE, + &os;-CURRENT, and &os; releases. Describes which users + would benefit from tracking a development system and outlines + that process. Covers the methods users may take to update their + system to the latest security release.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="dtrace">, &dtrace;</emphasis></term> + <listitem> + <para>Describes how to configure and use the &dtrace; tool from &sun; + in &os;. Dynamic tracing can help locate performance issues, by + performing real time system analysis.</para> + </listitem> + </varlistentry> + +<!-- Part IV - Network Communications --> + + <varlistentry> + <term><emphasis><xref linkend="serialcomms">, Serial Communications</emphasis></term> + <listitem> + <para>Explains how to connect terminals and modems to your + &os; system for both dial in and dial out connections.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="ppp-and-slip">, PPP and SLIP</emphasis></term> + <listitem> + <para>Describes how to use PPP, SLIP, or PPP over Ethernet to + connect to remote systems with &os;.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="mail">, Electronic Mail</emphasis></term> + <listitem> + <para>Explains the different components of an email server and + dives into simple configuration topics for the most popular + mail server software: + <application>sendmail</application>.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="network-servers">, Network Servers</emphasis></term> + <listitem> + <para>Provides detailed instructions and example configuration + files to set up your &os; machine as a network filesystem + server, domain name server, network information system + server, or time synchronization server.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="firewalls">, Firewalls</emphasis></term> + <listitem> + <para>Explains the philosophy behind software-based firewalls and + provides detailed information about the configuration of the + different firewalls available for &os;.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="advanced-networking">, Advanced Networking</emphasis></term> + <listitem> + <para>Describes many networking topics, including sharing an + Internet connection with other computers on your LAN, advanced + routing topics, wireless networking, &bluetooth;, ATM, IPv6, and + much more.</para> + </listitem> + </varlistentry> + +<!-- Part V - Appendices --> + + <varlistentry> + <term><emphasis><xref linkend="mirrors">, Obtaining &os; </emphasis></term> + <listitem> + <para>Lists different sources for obtaining &os; media on CDROM + or DVD as well as different sites on the Internet that allow + you to download and install &os;.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="bibliography">, Bibliography </emphasis></term> + <listitem> + <para>This book touches on many different subjects that may + leave you hungry for a more detailed explanation. The + bibliography lists many excellent books that are referenced in + the text.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="eresources">, Resources on the Internet</emphasis></term> + <listitem> + <para>Describes the many forums available for &os; users to + post questions and engage in technical conversations about + &os;.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><emphasis><xref linkend="pgpkeys">, PGP Keys</emphasis></term> + <listitem> + <para>Lists the PGP fingerprints of several &os; Developers.</para> + </listitem> + </varlistentry> + </variablelist> + + <bridgehead id="preface-conv" renderas=sect1>Conventions used + in this book</bridgehead> + + <para>To provide a consistent and easy to read text, several + conventions are followed throughout the book.</para> + + <bridgehead id="preface-conv-typographic" renderas=sect2>Typographic + Conventions</bridgehead> + + <variablelist> + <varlistentry> + <term><emphasis>Italic</emphasis></term> + <listitem> + <para>An <emphasis>italic</emphasis> font is used for filenames, URLs, + emphasized text, and the first usage of technical terms.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><literal>Monospace</literal></term> + <listitem> + <para>A <literal>monospaced</literal> font is + used for error messages, commands, environment variables, + names of ports, hostnames, user names, group names, device + names, variables, and code fragments.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><application>Bold</application></term> + <listitem> + <para>A <application>bold</application> font is used for + applications, commands, and keys.</para> + </listitem> + </varlistentry> + </variablelist> + +<!-- Var list --> + <bridgehead id="preface-conv-commands" + renderas=sect2>User Input</bridgehead> + + <para>Keys are shown in <keycap>bold</keycap> to stand out from + other text. Key combinations that are meant to be typed + simultaneously are shown with `<literal>+</literal>' between + the keys, such as:</para> + + <para> + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>Alt</keycap> + <keycap>Del</keycap> + </keycombo> + </para> + + <para>Meaning the user should type the <keycap>Ctrl</keycap>, + <keycap>Alt</keycap>, and <keycap>Del</keycap> keys at the same + time.</para> + + <para>Keys that are meant to be typed in sequence will be separated with + commas, for example:</para> + + <para> + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>X</keycap> + </keycombo>, + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>S</keycap> + </keycombo> + </para> + + <para>Would mean that the user is expected to type the + <keycap>Ctrl</keycap> and <keycap>X</keycap> keys simultaneously + and then to type the <keycap>Ctrl</keycap> and <keycap>S</keycap> + keys simultaneously.</para> + +<!-- How to type in key stokes, etc.. --> + <bridgehead id="preface-conv-examples" + renderas=sect2>Examples</bridgehead> + + <para>Examples starting with <devicename>E:\></devicename> + indicate a &ms-dos; command. Unless otherwise noted, these commands + may be executed from a <quote>Command Prompt</quote> window in a modern µsoft.windows; + environment.</para> + + <screen><prompt>E:\></prompt> <userinput>tools\fdimage floppies\kern.flp A:</userinput></screen> + + <para>Examples starting with &prompt.root; indicate a command that + must be invoked as the superuser in &os;. You can login as + <username>root</username> to type the command, or login as your + normal account and use &man.su.1; to gain + superuser privileges.</para> + + <screen>&prompt.root; <userinput>dd if=kern.flp of=/dev/fd0</userinput></screen> + + <para>Examples starting with &prompt.user; indicate a command that + should be invoked from a normal user account. Unless otherwise + noted, C-shell syntax is used for setting environment variables + and other shell commands.</para> + + <screen>&prompt.user; <userinput>top</userinput></screen> + + <bridgehead id="preface-acknowledgements" + renderas=sect1>Acknowledgments</bridgehead> + + <para>The book you are holding represents the efforts of many hundreds of + people around the world. Whether they sent in fixes for typos, or + submitted complete chapters, all the contributions have been + useful.</para> + + <para>Several companies have supported the development of this + document by paying authors to work on it full-time, paying for + publication, etc. In particular, BSDi (subsequently acquired by + <ulink url="http://www.windriver.com">Wind River Systems</ulink>) + paid members of the &os; Documentation Project to work on + improving this book full time leading up to the publication of the + first printed edition in March 2000 (ISBN 1-57176-241-8). Wind + River Systems then paid several additional authors to make a + number of improvements to the print-output infrastructure and to add + additional chapters to the text. This work culminated in the + publication of the second printed edition in November 2001 (ISBN + 1-57176-303-1). In 2003-2004, <ulink + url="http://www.freebsdmall.com">&os; Mall, Inc</ulink>, paid + several contributors to improve the Handbook in preparation for + the third printed edition.</para> + +</preface> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "book" "preface") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/printing/Makefile b/en_US.ISO8859-1/books/handbook/printing/Makefile new file mode 100644 index 0000000000..72d9e9b80a --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/printing/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= printing/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/printing/chapter.sgml b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml new file mode 100644 index 0000000000..0a8f3387f8 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/printing/chapter.sgml @@ -0,0 +1,4895 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="printing"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Sean</firstname> + <surname>Kelly</surname> + <contrib>Contributed by </contrib> + </author> + <!-- 30 Sept 1995 --> + </authorgroup> + <authorgroup> + <author> + <firstname>Jim</firstname> + <surname>Mock</surname> + <contrib>Restructured and updated by </contrib> + <!-- Mar 2000 --> + </author> + </authorgroup> + </chapterinfo> + + <title>Printing</title> + + <sect1 id="printing-synopsis"> + <title>Synopsis</title> + <indexterm><primary>LPD spooling system</primary></indexterm> + <indexterm><primary>printing</primary></indexterm> + + <para>&os; can be used to print with a wide variety of printers, from the + oldest impact printer to the latest laser printers, and everything in + between, allowing you to produce high-quality printed output from the + applications you run.</para> + + <para>&os; can also be configured to act as a print server on a + network; in this capacity &os; can receive print jobs from a variety + of other computers, including other &os; computers, &windows; and + &macos; hosts. &os; will ensure that one job at a time is printed, and + can keep statistics on which users and machines are doing the most + printing, produce <quote>banner</quote> pages showing whose printout is + whose, and more.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to configure the &os; print spooler.</para> + </listitem> + + <listitem> + <para>How to install print filters, to handle special print jobs + differently, including converting incoming documents to print + formats that your printers understand.</para> + </listitem> + + <listitem> + <para>How to enable header, or banner pages on your printout.</para> + </listitem> + + <listitem> + <para>How to print with printers connected to other computers.</para> + </listitem> + + <listitem> + <para>How to print with printers connected directly to the + network.</para> + </listitem> + + <listitem> + <para>How to control printer restrictions, including limiting the size + of print jobs, and preventing certain users from printing.</para> + </listitem> + + <listitem> + <para>How to keep printer statistics, and account for printer + usage.</para> + </listitem> + + <listitem> + <para>How to troubleshoot printing problems.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Know how to configure and install a new kernel + (<xref linkend="kernelconfig">).</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="printing-intro-spooler"> + <title>Introduction</title> + + <para>In order to use printers with &os; you may set + them up to work with the Berkeley line printer spooling system, + also known as the <application>LPD</application> spooling system, + or just <application>LPD</application>. + It is the standard printer control system in &os;. This + chapter introduces <application>LPD</application> and + will guide you through its configuration.</para> + + <para>If you are already familiar with + <application>LPD</application> or another printer spooling + system, you may wish to skip to section <link + linkend="printing-intro-setup">Basic Setup</link>.</para> + + <para><application>LPD</application> controls everything about a + host's printers. It is responsible for a number of things:</para> + + <itemizedlist> + <listitem> + <para>It controls access to attached printers and printers + attached to other hosts on the network.</para> + </listitem> + + <indexterm><primary>print jobs</primary></indexterm> + <listitem> + <para>It enables users to submit files to be printed; these + submissions are known as <emphasis>jobs</emphasis>.</para> + </listitem> + + <listitem> + <para>It prevents multiple users from accessing a printer at the + same time by maintaining a <emphasis>queue</emphasis> for each + printer.</para> + </listitem> + + <listitem> + <para>It can print <emphasis>header pages</emphasis> (also known + as <emphasis>banner</emphasis> or <emphasis>burst</emphasis> + pages) so users can easily find jobs they have printed in a + stack of printouts.</para> + </listitem> + + <listitem> + <para>It takes care of communications parameters for printers + connected on serial ports.</para> + </listitem> + + <listitem> + <para>It can send jobs over the network to a + <application>LPD</application> spooler on another host.</para> + </listitem> + + <listitem> + <para>It can run special filters to format jobs to be printed for + various printer languages or printer capabilities.</para> + </listitem> + + <listitem> + <para>It can account for printer usage.</para> + </listitem> + </itemizedlist> + + <para>Through a configuration file + (<filename>/etc/printcap</filename>), and by providing the special + filter programs, you can enable the <application>LPD</application> + system to do all or some subset of the above for a great variety of + printer hardware.</para> + + <sect2 id="printing-intro-why"> + <title>Why You Should Use the Spooler</title> + + <para>If you are the sole user of your system, you may be wondering + why you should bother with the spooler when you do not need access + control, header pages, or printer accounting. While it is + possible to enable direct access to a printer, you should use the + spooler anyway since:</para> + + <itemizedlist> + <listitem> + <para><application>LPD</application> prints jobs in the background; + you do not have to wait for data to be copied to the + printer.</para> + </listitem> + + <indexterm><primary>&tex;</primary></indexterm> + <listitem> + <para><application>LPD</application> can conveniently run a job + to be printed through filters to add date/time headers or convert + a special file format (such as a &tex; DVI file) into a format + the printer will understand. You will not have to do these steps + manually.</para> + </listitem> + + <listitem> + <para>Many free and commercial programs that provide a print + feature usually expect to talk to the spooler on your system. + By setting up the spooling system, you will more easily + support other software you may later add or already + have.</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="printing-intro-setup"> + <title>Basic Setup</title> + + <warning> + <para>As of &os; 8.0, device nodes for serial ports have been + renamed from + <filename>/dev/ttyd<replaceable>N</replaceable></filename> to + <filename>/dev/ttyu<replaceable>N</replaceable></filename>. + &os; 7.X users will have to adapt the following + documentation according to these changes.</para> + </warning> + + <para>To use printers with the <application>LPD</application> spooling + system, you will need to set up both your printer hardware and the + <application>LPD</application> software. This document describes two + levels of setup:</para> + + <itemizedlist> + <listitem> + <para>See section <link linkend="printing-simple">Simple Printer + Setup</link> to learn how to connect a printer, tell + <application>LPD</application> how to communicate with it, and + print plain text files to the printer.</para> + </listitem> + + <listitem> + <para>See section <link linkend="printing-advanced">Advanced Printer + Setup</link> to learn how to print a variety of special file + formats, to print header pages, to print across a network, to + control access to printers, and to do printer accounting.</para> + </listitem> + </itemizedlist> + + <sect2 id="printing-simple"> + <title>Simple Printer Setup</title> + + <para>This section tells how to configure printer hardware and the + <application>LPD</application> software to use the printer. + It teaches the basics:</para> + + <itemizedlist> + <listitem> + <para>Section <link linkend="printing-hardware">Hardware + Setup</link> gives some hints on connecting the printer to a + port on your computer.</para> + </listitem> + + <listitem> + <para>Section <link linkend="printing-software">Software + Setup</link> shows how to set up the + <application>LPD</application> spooler configuration + file (<filename>/etc/printcap</filename>).</para> + </listitem> + </itemizedlist> + + <para>If you are setting up a printer that uses a network protocol + to accept data to print instead of a computer's local interfaces, + see <link linkend="printing-advanced-network-net-if">Printers With + Networked Data Stream Interfaces</link>.</para> + + <para>Although this section is called <quote>Simple Printer + Setup</quote>, it is actually fairly complex. Getting the printer + to work with your computer and the <application>LPD</application> + spooler is the hardest part. The advanced options like header pages + and accounting are fairly easy once you get the printer + working.</para> + + <sect3 id="printing-hardware"> + <title>Hardware Setup</title> + + <para>This section tells about the various ways you can connect a + printer to your PC. It talks about the kinds of ports and + cables, and also the kernel configuration you may need to enable + &os; to speak to the printer.</para> + + <para>If you have already connected your printer and have + successfully printed with it under another operating system, you + can probably skip to section <link + linkend="printing-software">Software Setup</link>.</para> + + <sect4 id="printing-ports"> + <title>Ports and Cables</title> + + <para>Printers sold for use on PC's today generally come + with one or more of the following three interfaces:</para> + + <itemizedlist> + <indexterm> + <primary>printers</primary> + <secondary>serial</secondary> + </indexterm> + <listitem> + <para><emphasis>Serial</emphasis> interfaces, also known + as RS-232 or COM ports, use a serial port + on your computer to send data to the printer. Serial + interfaces are common in the computer industry and cables + are readily available and also easy to construct. Serial + interfaces sometimes need special cables and might require + you to configure somewhat complex communications + options. Most PC serial ports have a maximum + transmission rate of 115200 bps, which makes printing + large graphic print jobs with them impractical.</para> + </listitem> + + <indexterm> + <primary>printers</primary> + <secondary>parallel</secondary> + </indexterm> + <listitem> + <para><emphasis>Parallel</emphasis> interfaces use a + parallel port on your computer to send data to the + printer. Parallel interfaces are common in the PC market + and are faster than RS-232 serial. + Cables are readily available but more difficult to + construct by hand. There are usually no communications + options with parallel interfaces, making their + configuration exceedingly simple.</para> + + <indexterm> + <primary>centronics</primary> + <see>parallel printers</see> + </indexterm> + <para>Parallel interfaces are sometimes known as + <quote>Centronics</quote> interfaces, named after the + connector type on the printer.</para> + </listitem> + + <indexterm> + <primary>printers</primary> + <secondary>USB</secondary> + </indexterm> + <listitem> + <para>USB interfaces, named for the Universal Serial + Bus, can run at even faster speeds than parallel or + RS-232 serial interfaces. Cables are simple and cheap. + USB is superior to RS-232 Serial and to Parallel for + printing, but it is not as well supported under &unix; + systems. A way to avoid this problem is to purchase a + printer that has both a USB interface and a Parallel + interface, as many printers do.</para> + </listitem> + </itemizedlist> + + <para>In general, Parallel interfaces usually offer just + one-way communication (computer to printer) while serial + and USB gives you two-way. Newer parallel ports (EPP and + ECP) and printers can communicate in both directions under &os; + when a IEEE-1284-compliant cable is used.</para> + + <indexterm><primary>PostScript</primary></indexterm> + + <para>Two-way communication to the printer over a parallel + port is generally done in one of two ways. The first method + uses a custom-built printer driver for &os; that speaks + the proprietary language used by the printer. This is + common with inkjet printers and can be used for reporting + ink levels and other status information. The second + method is used when the printer supports + &postscript;.</para> + + <para>&postscript; jobs are actually programs sent to the printer; + they need not produce paper at all and may return results + directly to the computer. &postscript; also uses two-way + communication to tell the computer about problems, such as errors + in the &postscript; program or paper jams. Your users may be + appreciative of such information. Furthermore, the best way to + do effective accounting with a &postscript; printer requires + two-way communication: you ask the printer for its page count (how + many pages it has printed in its lifetime), then send the + user's job, then ask again for its page count. Subtract the + two values and you know how much paper to charge to the + user.</para> + </sect4> + + <sect4 id="printing-parallel"> + <title>Parallel Ports</title> + + <para>To hook up a printer using a parallel interface, connect + the Centronics cable between the printer and the computer. + The instructions that came with the printer, the computer, or + both should give you complete guidance.</para> + + <para>Remember which parallel port you used on the computer. + The first parallel port is + <filename class="devicefile">ppc0</filename> to &os;; the second + is <filename class="devicefile">ppc1</filename>, and so on. The + printer device name uses the same scheme: + <filename class="devicefile">/dev/lpt0</filename> for the printer + on the first parallel ports etc.</para> + </sect4> + + <sect4 id="printing-serial"> + <title>Serial Ports</title> + + <para>To hook up a printer using a serial interface, connect the + proper serial cable between the printer and the computer. The + instructions that came with the printer, the computer, or both + should give you complete guidance.</para> + + <para>If you are unsure what the <quote>proper serial + cable</quote> is, you may wish to try one of the following + alternatives:</para> + + <itemizedlist> + <listitem> + <para>A <emphasis>modem</emphasis> cable connects each pin + of the connector on one end of the cable straight through + to its corresponding pin of the connector on the other + end. This type of cable is also known as a + <quote>DTE-to-DCE</quote> cable.</para> + </listitem> + + <indexterm><primary>null-modem cable</primary></indexterm> + <listitem> + <para>A <emphasis>null-modem</emphasis> cable connects some + pins straight through, swaps others (send data to receive + data, for example), and shorts some internally in each + connector hood. This type of cable is also known as a + <quote>DTE-to-DTE</quote> cable.</para> + </listitem> + + <listitem> + <para>A <emphasis>serial printer</emphasis> cable, required + for some unusual printers, is like the null-modem cable, + but sends some signals to their counterparts instead of + being internally shorted.</para> + </listitem> + </itemizedlist> + + <indexterm><primary>baud rate</primary></indexterm> + <indexterm><primary>parity</primary></indexterm> + <indexterm><primary>flow control protocol</primary></indexterm> + <para>You should also set up the communications parameters for + the printer, usually through front-panel controls or DIP + switches on the printer. Choose the highest + <literal>bps</literal> (bits per second, sometimes + <emphasis>baud rate</emphasis>) that both your computer + and the printer can support. Choose 7 or 8 data bits; none, + even, or odd parity; and 1 or 2 stop bits. Also choose a flow + control protocol: either none, or XON/XOFF (also known as + <quote>in-band</quote> or <quote>software</quote>) flow control. + Remember these settings for the software configuration that + follows.</para> + </sect4> + </sect3> + + <sect3 id="printing-software"> + <title>Software Setup</title> + + <para>This section describes the software setup necessary to print + with the <application>LPD</application> spooling system in &os;. + </para> + + <para>Here is an outline of the steps involved:</para> + + <procedure> + <step> + <para>Configure your kernel, if necessary, for the port you + are using for the printer; section <link + linkend="printing-kernel">Kernel Configuration</link> tells + you what you need to do.</para> + </step> + + <step> + <para>Set the communications mode for the parallel port, if + you are using a parallel port; section <link + linkend="printing-parallel-port-mode">Setting the + Communication Mode for the Parallel Port</link> gives + details.</para> + </step> + + <step> + <para>Test if the operating system can send data to the printer. + Section <link linkend="printing-testing">Checking Printer + Communications</link> gives some suggestions on how to do + this.</para> + </step> + + <step> + <para>Set up <application>LPD</application> for the printer by + modifying the file <filename>/etc/printcap</filename>. You + will find out how to do this later in this chapter.</para> + </step> + </procedure> + + <sect4 id="printing-kernel"> + <title>Kernel Configuration</title> + + <para>The operating system kernel is compiled to work with a + specific set of devices. The serial or parallel interface for + your printer is a part of that set. Therefore, it might be + necessary to add support for an additional serial or parallel + port if your kernel is not already configured for one.</para> + + <para>To find out if the kernel you are currently using supports + a serial interface, type:</para> + + <screen>&prompt.root; <userinput><command>grep sio<replaceable>N</replaceable> <filename>/var/run/dmesg.boot</filename></command></userinput></screen> + + <para>Where <replaceable>N</replaceable> is the number of the + serial port, starting from zero. If you see output similar to + the following:</para> + + <screen>sio2 at port 0x3e8-0x3ef irq 5 on isa +sio2: type 16550A</screen> + + <para>then the kernel supports the port.</para> + + <para>To find out if the kernel supports a parallel interface, + type:</para> + + <screen>&prompt.root; <userinput><command>grep ppc<replaceable>N</replaceable> /var/run/dmesg.boot</command></userinput></screen> + + <para>Where <replaceable>N</replaceable> is the number of the + parallel port, starting from zero. If you see output similar + to the following:</para> + + <screen>ppc0: <Parallel port> at port 0x378-0x37f irq 7 on isa0 +ppc0: SMC-like chipset (ECP/EPP/PS2/NIBBLE) in COMPATIBLE mode +ppc0: FIFO with 16/16/8 bytes threshold</screen> + + <para>then the kernel supports the port.</para> + + <para>You might have to reconfigure your kernel in order for the + operating system to recognize and use the parallel or serial + port you are using for the printer.</para> + + <para>To add support for a serial port, see the section on + kernel configuration. To add support for a parallel port, see + that section <emphasis>and</emphasis> the section that + follows.</para> + </sect4> + </sect3> + + <sect3 id="printing-parallel-port-mode"> + <title>Setting the Communication Mode for the Parallel + Port</title> + + <para>When you are using the parallel interface, you can choose + whether &os; should use interrupt-driven or polled + communication with the printer. The generic printer + device driver (&man.lpt.4;) on &os; + uses the &man.ppbus.4; system, which controls the port + chipset with the &man.ppc.4; driver.</para> + + <itemizedlist> + <listitem> + <para>The <emphasis>interrupt-driven</emphasis> method is + the default with the GENERIC kernel. With this method, + the operating system uses an IRQ line to determine when + the printer is ready for data.</para> + </listitem> + + <listitem> + <para>The <emphasis>polled</emphasis> method directs the + operating system to repeatedly ask the printer if it is + ready for more data. When it responds ready, the kernel + sends more data.</para> + </listitem> + </itemizedlist> + + <para>The interrupt-driven method is usually somewhat faster + but uses up a precious IRQ line. Some newer HP printers + are claimed not to work correctly in interrupt mode, + apparently due to some (not yet exactly understood) timing + problem. These printers need polled mode. You should use + whichever one works. Some printers will work in both + modes, but are painfully slow in interrupt mode.</para> + + <para>You can set the communications mode in two ways: by + configuring the kernel or by using the &man.lptcontrol.8; + program.</para> + + <para><emphasis>To set the communications mode by configuring + the kernel:</emphasis></para> + + <procedure> + <step> + <para>Edit your kernel configuration file. Look for + an <literal>ppc0</literal> entry. If you are setting up + the second parallel port, use <literal>ppc1</literal> + instead. Use <literal>ppc2</literal> for the third port, + and so on.</para> + + <itemizedlist> + <listitem> + <para>If you want interrupt-driven mode, edit the following + line:</para> + + <programlisting>hint.ppc.0.irq="<replaceable>N</replaceable>"</programlisting> + + <para>in the <filename>/boot/device.hints</filename> file + and replace <replaceable>N</replaceable> with the right + IRQ number. The kernel configuration file must + also contain the &man.ppc.4; driver:</para> + + <screen>device ppc</screen> + </listitem> + + <listitem> + <para>If you want polled mode, remove in your + <filename>/boot/device.hints</filename> file, the + following line:</para> + + <programlisting>hint.ppc.0.irq="<replaceable>N</replaceable>"</programlisting> + + <para>In some cases, this is not enough to put the + port in polled mode under &os;. Most of + time it comes from &man.acpi.4; driver, this latter + is able to probe and attach devices, and therefore, + control the access mode to the printer port. You + should check your &man.acpi.4; configuration to + correct this problem.</para> + </listitem> + </itemizedlist> + </step> + + <step> + <para>Save the file. Then configure, build, and install the + kernel, then reboot. See <link linkend="kernelconfig">kernel + configuration</link> for more details.</para> + </step> + </procedure> + + <para><emphasis>To set the communications mode with</emphasis> + &man.lptcontrol.8;:</para> + + <procedure> + <step> + <para>Type:</para> + + <screen>&prompt.root; <userinput><command>lptcontrol <option>-i</option> <option>-d</option> <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen> + + <para>to set interrupt-driven mode for + <literal>lpt<replaceable>N</replaceable></literal>.</para> + </step> + + <step> + <para>Type:</para> + + <screen>&prompt.root; <userinput><command>lptcontrol <option>-p</option> <option>-d</option> <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen> + + <para>to set polled-mode for + <literal>lpt<replaceable>N</replaceable></literal>.</para> + </step> + </procedure> + + <para>You could put these commands in your + <filename>/etc/rc.local</filename> file to set the mode each + time your system boots. See &man.lptcontrol.8; for more + information.</para> + </sect3> + + <sect3 id="printing-testing"> + <title>Checking Printer Communications</title> + + <para>Before proceeding to configure the spooling system, you + should make sure the operating system can successfully send + data to your printer. It is a lot easier to debug printer + communication and the spooling system separately.</para> + + <para>To test the printer, we will send some text to it. For + printers that can immediately print characters sent to them, + the program &man.lptest.1; is perfect: it generates all 96 + printable ASCII characters in 96 lines.</para> + + <indexterm><primary>PostScript</primary></indexterm> + <para>For a &postscript; (or other language-based) printer, we + will need a more sophisticated test. A small &postscript; + program, such as the following, will suffice:</para> + + <programlisting>%!PS +100 100 moveto 300 300 lineto stroke +310 310 moveto /Helvetica findfont 12 scalefont setfont +(Is this thing working?) show +showpage</programlisting> + + <para>The above &postscript; code can be placed into a file and + used as shown in the examples appearing in the following + sections.</para> + + <indexterm><primary>PCL</primary></indexterm> + <note> + <para>When this document refers to a printer language, it is + assuming a language like &postscript;, and not Hewlett + Packard's PCL. Although PCL has great functionality, you + can intermingle plain text with its escape sequences. + &postscript; cannot directly print plain text, and that is the + kind of printer language for which we must make special + accommodations.</para> + </note> + + <sect4 id="printing-checking-parallel"> + <title>Checking a Parallel Printer</title> + + <indexterm> + <primary>printers</primary> + <secondary>parallel</secondary> + </indexterm> + <para>This section tells you how to check if &os; can + communicate with a printer connected to a parallel + port.</para> + + <para><emphasis>To test a printer on a parallel + port:</emphasis></para> + + <procedure> + <step> + <para>Become <username>root</username> with &man.su.1;.</para> + </step> + + <step> + <para>Send data to the printer.</para> + + <itemizedlist> + <listitem> + <para>If the printer can print plain text, then use + &man.lptest.1;. Type:</para> + + <screen>&prompt.root; <userinput><command>lptest > <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen> + + <para>Where <replaceable>N</replaceable> is the number + of the parallel port, starting from zero.</para> + </listitem> + + <listitem> + <para>If the printer understands &postscript; or other + printer language, then send a small program to the + printer. Type:</para> + + <screen>&prompt.root; <userinput><command>cat > <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen> + + <para>Then, line by line, type the program + <emphasis>carefully</emphasis> as you cannot edit a + line once you have pressed <literal>RETURN</literal> + or <literal>ENTER</literal>. When you have finished + entering the program, press + <literal>CONTROL+D</literal>, or whatever your end + of file key is.</para> + + <para>Alternatively, you can put the program in a file + and type:</para> + + <screen>&prompt.root; <userinput><command>cat <filename><replaceable>file</replaceable></filename> > <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen> + + <para>Where <replaceable>file</replaceable> is the + name of the file containing the program you want to + send to the printer.</para> + </listitem> + </itemizedlist> + </step> + </procedure> + + <para>You should see something print. Do not worry if the + text does not look right; we will fix such things + later.</para> + </sect4> + + <sect4 id="printing-checking-serial"> + <title>Checking a Serial Printer</title> + + <indexterm> + <primary>printers</primary> + <secondary>serial</secondary> + </indexterm> + <para>This section tells you how to check if &os; can + communicate with a printer on a serial port.</para> + + <para><emphasis>To test a printer on a serial + port:</emphasis></para> + + <procedure> + <step> + <para>Become <username>root</username> with &man.su.1;.</para> + </step> + + <step> + <para>Edit the file <filename>/etc/remote</filename>. Add + the following entry:</para> + + <programlisting>printer:dv=<filename class="devicefile">/dev/<replaceable>port</replaceable></filename>:br#<replaceable>bps-rate</replaceable>:pa=<replaceable>parity</replaceable></programlisting> + + <indexterm><primary>bits-per-second</primary></indexterm> + <indexterm><primary>serial port</primary></indexterm> + <indexterm><primary>parity</primary></indexterm> + <para>Where <replaceable>port</replaceable> is the device + entry for the serial port (<literal>ttyu0</literal>, + <literal>ttyu1</literal>, etc.), + <replaceable>bps-rate</replaceable> is the + bits-per-second rate at which the printer communicates, + and <replaceable>parity</replaceable> is the parity + required by the printer (either <literal>even</literal>, + <literal>odd</literal>, <literal>none</literal>, or + <literal>zero</literal>).</para> + + <para>Here is a sample entry for a printer connected via + a serial line to the third serial port at 19200 bps + with no parity:</para> + + <programlisting>printer:dv=<filename class="devicefile">/dev/ttyu2</filename>:br#19200:pa=none</programlisting> + </step> + + <step> + <para>Connect to the printer with &man.tip.1;. + Type:</para> + + <screen>&prompt.root; <userinput><command>tip</command> printer</userinput></screen> + + <para>If this step does not work, edit the file + <filename>/etc/remote</filename> again and try using + <filename class="devicefile">/dev/cuaa<replaceable>N</replaceable></filename> instead of + <filename class="devicefile">/dev/ttyu<replaceable>N</replaceable></filename>.</para> + </step> + + <step> + <para>Send data to the printer.</para> + + <itemizedlist> + <listitem> + <para>If the printer can print plain text, then use + &man.lptest.1;. Type:</para> + + <screen>&prompt.user; <userinput>$lptest</userinput></screen> + </listitem> + + <listitem> + <para>If the printer understands &postscript; or other + printer language, then send a small program to the + printer. Type the program, line by line, + <emphasis>very carefully</emphasis> as backspacing + or other editing keys may be significant to the + printer. You may also need to type a special + end-of-file key for the printer so it knows it + received the whole program. For &postscript; + printers, press <literal>CONTROL+D</literal>.</para> + + <para>Alternatively, you can put the program in a file + and type:</para> + + <screen>&prompt.user; <userinput>><replaceable>file</replaceable></userinput></screen> + + <para>Where <replaceable>file</replaceable> is the + name of the file containing the program. After + &man.tip.1; sends the file, press any required + end-of-file key.</para> + </listitem> + </itemizedlist> + </step> + </procedure> + + <para>You should see something print. Do not worry if the + text does not look right; we will fix that later.</para> + </sect4> + </sect3> + + <sect3 id="printing-printcap"> + <title>Enabling the Spooler: the <filename>/etc/printcap</filename> + File</title> + + <para>At this point, your printer should be hooked up, your kernel + configured to communicate with it (if necessary), and you have + been able to send some simple data to the printer. Now, we are + ready to configure <application>LPD</application> to control access + to your printer.</para> + + <para>You configure <application>LPD</application> by editing the file + <filename>/etc/printcap</filename>. The + <application>LPD</application> spooling system + reads this file each time the spooler is used, so updates to the + file take immediate effect.</para> + + <indexterm> + <primary>printers</primary> + <secondary>capabilities</secondary> + </indexterm> + <para>The format of the &man.printcap.5; file is straightforward. + Use your favorite text editor to make changes to + <filename>/etc/printcap</filename>. The format is identical to + other capability files like + <filename>/usr/share/misc/termcap</filename> and + <filename>/etc/remote</filename>. For complete information + about the format, see the &man.cgetent.3;.</para> + + <para>The simple spooler configuration consists of the following + steps:</para> + + <procedure> + <step> + <para>Pick a name (and a few convenient aliases) for the + printer, and put them in the + <filename>/etc/printcap</filename> file; see the + <link linkend="printing-naming">Naming the Printer</link> + section for more information on naming.</para> + </step> + + <indexterm><primary>header pages</primary></indexterm> + <step> + <para>Turn off header pages (which are on by default) by + inserting the <literal>sh</literal> capability; see the + <link linkend="printing-no-header-pages">Suppressing Header + Pages</link> section for more information.</para> + </step> + + <step> + <para>Make a spooling directory, and specify its location with + the <literal>sd</literal> capability; see the <link + linkend="printing-spooldir">Making the Spooling + Directory</link> section for more information.</para> + </step> + + <step> + <para>Set the <filename class="directory">/dev</filename> entry + to use for the printer, and note it in + <filename>/etc/printcap</filename> with the + <literal>lp</literal> capability; see the <link + linkend="printing-device">Identifying the Printer + Device</link> for more information. Also, if the printer is + on a serial port, set up the communication parameters with + the <literal>ms#</literal> capability which is discussed in the + <link linkend="printing-commparam">Configuring Spooler + Communications Parameters</link> section.</para> + </step> + + <step> + <para>Install a plain text input filter; see the <link + linkend="printing-textfilter">Installing the Text + Filter</link> section for details.</para> + </step> + + <step> + <para>Test the setup by printing something with the + &man.lpr.1; command. More details are available in the + <link linkend="printing-trying">Trying It Out</link> and + <link linkend="printing-troubleshooting">Troubleshooting</link> + sections.</para> + </step> + </procedure> + + <note> + <para>Language-based printers, such as &postscript; printers, + cannot directly print plain text. The simple setup outlined + above and described in the following sections assumes that if + you are installing such a printer you will print only files + that the printer can understand.</para> + </note> + + <para>Users often expect that they can print plain text to any of + the printers installed on your system. Programs that interface + to <application>LPD</application> to do their printing usually + make the same assumption. + If you are installing such a printer and want to be able to + print jobs in the printer language <emphasis>and</emphasis> + print plain text jobs, you are strongly urged to add an + additional step to the simple setup outlined above: install an + automatic plain-text-to-&postscript; (or other printer language) + conversion program. The section entitled <link + linkend="printing-advanced-if-conversion">Accommodating Plain + Text Jobs on &postscript; Printers</link> tells how to do + this.</para> + + <sect4 id="printing-naming"> + <title>Naming the Printer</title> + + <para>The first (easy) step is to pick a name for your printer. + It really does not matter whether you choose functional or + whimsical names since you can also provide a number of aliases + for the printer.</para> + + <para>At least one of the printers specified in the + <filename>/etc/printcap</filename> should have the alias + <literal>lp</literal>. This is the default printer's name. + If users do not have the <envar>PRINTER</envar> environment + variable nor specify a printer name on the command line of any + of the <application>LPD</application> commands, + then <literal>lp</literal> will be the + default printer they get to use.</para> + + <para>Also, it is common practice to make the last alias for a + printer be a full description of the printer, including make + and model.</para> + + <para>Once you have picked a name and some common aliases, put + them in the <filename>/etc/printcap</filename> file. The name + of the printer should start in the leftmost column. Separate + each alias with a vertical bar and put a colon after the last + alias.</para> + + <para>In the following example, we start with a skeletal + <filename>/etc/printcap</filename> that defines two printers + (a Diablo 630 line printer and a Panasonic KX-P4455 &postscript; + laser printer):</para> + + <programlisting># +# /etc/printcap for host rose +# +rattan|line|diablo|lp|Diablo 630 Line Printer: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:</programlisting> + + <para>In this example, the first printer is named + <literal>rattan</literal> and has as aliases + <literal>line</literal>, <literal>diablo</literal>, + <literal>lp</literal>, and <literal>Diablo 630 Line + Printer</literal>. Since it has the alias + <literal>lp</literal>, it is also the default printer. The + second is named <literal>bamboo</literal>, and has as aliases + <literal>ps</literal>, <literal>PS</literal>, + <literal>S</literal>, <literal>panasonic</literal>, and + <literal>Panasonic KX-P4455 PostScript v51.4</literal>.</para> + </sect4> + + <sect4 id="printing-no-header-pages"> + <title>Suppressing Header Pages</title> + <indexterm> + <primary>printing</primary> + <secondary>header pages</secondary> + </indexterm> + + <para>The <application>LPD</application> spooling system will + by default print a + <emphasis>header page</emphasis> for each job. The header + page contains the user name who requested the job, the host + from which the job came, and the name of the job, in nice + large letters. Unfortunately, all this extra text gets in the + way of debugging the simple printer setup, so we will suppress + header pages.</para> + + <para>To suppress header pages, add the <literal>sh</literal> + capability to the entry for the printer in + <filename>/etc/printcap</filename>. Here is an example + <filename>/etc/printcap</filename> with <literal>sh</literal> + added:</para> + + <programlisting># +# /etc/printcap for host rose - no header pages anywhere +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:</programlisting> + + <para>Note how we used the correct format: the first line starts + in the leftmost column, and subsequent lines are indented. + Every line in an entry except the last ends in + a backslash character.</para> + </sect4> + + <sect4 id="printing-spooldir"> + <title>Making the Spooling Directory</title> + <indexterm><primary>printer spool</primary></indexterm> + <indexterm><primary>print jobs</primary></indexterm> + + <para>The next step in the simple spooler setup is to make a + <emphasis>spooling directory</emphasis>, a directory where + print jobs reside until they are printed, and where a number + of other spooler support files live.</para> + + <para>Because of the variable nature of spooling directories, it + is customary to put these directories under + <filename class="directory">/var/spool</filename>. It is not + necessary to backup the contents of spooling directories, either. + Recreating them is as simple as running &man.mkdir.1;.</para> + + <para>It is also customary to make the directory with a name + that is identical to the name of the printer, as shown + below:</para> + + <screen>&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/<replaceable>printer-name</replaceable></filename></command></userinput></screen> + + <para>However, if you have a lot of printers on your network, + you might want to put the spooling directories under a single + directory that you reserve just for printing with + <application>LPD</application>. We + will do this for our two example printers + <literal>rattan</literal> and + <literal>bamboo</literal>:</para> + + <screen>&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/lpd</filename></command></userinput> +&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/lpd/rattan</filename></command></userinput> +&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput></screen> + + <note> + <para>If you are concerned about the privacy of jobs that + users print, you might want to protect the spooling + directory so it is not publicly accessible. Spooling + directories should be owned and be readable, writable, and + searchable by user <username>daemon</username> and group + <groupname>daemon</groupname>, and no one else. We will do + this for our example printers:</para> + + <screen>&prompt.root; <userinput><command>chown daemon:daemon <filename class="directory">/var/spool/lpd/rattan</filename></command></userinput> +&prompt.root; <userinput><command>chown daemon:daemon <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput> +&prompt.root; <userinput><command>chmod 770 <filename class="directory">/var/spool/lpd/rattan</filename></command></userinput> +&prompt.root; <userinput><command>chmod 770 <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput></screen> + </note> + + <para>Finally, you need to tell <application>LPD</application> + about these directories + using the <filename>/etc/printcap</filename> file. You + specify the pathname of the spooling directory with the + <literal>sd</literal> capability:</para> + + <programlisting># +# /etc/printcap for host rose - added spooling directories +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:</programlisting> + + <para>Note that the name of the printer starts in the first + column but all other entries describing the printer should be + indented and each line end escaped with a + backslash.</para> + + <para>If you do not specify a spooling directory with + <literal>sd</literal>, the spooling system will use + <filename class="directory">/var/spool/lpd</filename> as a + default.</para> + </sect4> + + <sect4 id="printing-device"> + <title>Identifying the Printer Device</title> + + <para>In the <link linkend="printing-hardware">Hardware Setup</link> + section, we identified the port and the relevant + <filename class="directory">/dev</filename> directory entry that + &os; will use to communicate with the printer. Now, we tell + <application>LPD</application> that information. When the + spooling system has a job to print, it will open the specified + device on behalf of the filter program (which is responsible for + passing data to the printer).</para> + + <para>List the <filename class="directory">/dev</filename> entry + pathname in the <filename>/etc/printcap</filename> file using the + <literal>lp</literal> capability.</para> + + <para>In our running example, let us assume that + <literal>rattan</literal> is on the first parallel port, and + <literal>bamboo</literal> is on a sixth serial port; here are + the additions to <filename>/etc/printcap</filename>:</para> + + <programlisting># +# /etc/printcap for host rose - identified what devices to use +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\ + :lp=<filename class="devicefile">/dev/ttyu5</filename>:</programlisting> + + <para>If you do not specify the <literal>lp</literal> capability + for a printer in your <filename>/etc/printcap</filename> file, + <application>LPD</application> uses + <filename class="devicefile">/dev/lp</filename> as a default. + <filename class="devicefile">/dev/lp</filename> currently does + not exist in &os;.</para> + + <para>If the printer you are installing is connected to a + parallel port, skip to the section entitled, <link + linkend="printing-textfilter">Installing the Text + Filter</link>. Otherwise, be sure to follow the instructions + in the next section.</para> + </sect4> + + <sect4 id="printing-commparam"> + <title>Configuring Spooler Communication Parameters</title> + <indexterm> + <primary>printers</primary> + <secondary>serial</secondary> + </indexterm> + + <para>For printers on serial ports, <application>LPD</application> + can set up the bps rate, parity, and other serial communication + parameters on behalf of the filter program that sends data to the + printer. This is advantageous since:</para> + + <itemizedlist> + <listitem> + <para>It lets you try different communication parameters by + simply editing the <filename>/etc/printcap</filename> + file; you do not have to recompile the filter + program.</para> + </listitem> + + <listitem> + <para>It enables the spooling system to use the same filter + program for multiple printers which may have different + serial communication settings.</para> + </listitem> + </itemizedlist> + + <para>The following <filename>/etc/printcap</filename> + capabilities control serial communication parameters of the + device listed in the <literal>lp</literal> capability:</para> + + <variablelist> + <varlistentry> + <term><literal>br#<replaceable>bps-rate</replaceable></literal></term> + + <listitem> + <para>Sets the communications speed of the device to + <replaceable>bps-rate</replaceable>, where + <replaceable>bps-rate</replaceable> can be 50, 75, 110, + 134, 150, 200, 300, 600, 1200, 1800, 2400, 4800, 9600, + 19200, 38400, 57600, or 115200 bits-per-second.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>ms#<replaceable>stty-mode</replaceable></literal></term> + + <listitem> + <para>Sets the options for the terminal device after + opening the device. &man.stty.1; explains the + available options.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>When <application>LPD</application> opens the device + specified by the <literal>lp</literal> capability, it sets + the characteristics of the device to those specified with + the <literal>ms#</literal> capability. Of particular + interest will be the <literal>parenb</literal>, + <literal>parodd</literal>, <literal>cs5</literal>, + <literal>cs6</literal>, <literal>cs7</literal>, + <literal>cs8</literal>, <literal>cstopb</literal>, + <literal>crtscts</literal>, and <literal>ixon</literal> + modes, which are explained in the &man.stty.1; + manual page.</para> + + <para>Let us add to our example printer on the sixth serial + port. We will set the bps rate to 38400. For the mode, + we will set no parity with <literal>-parenb</literal>, + 8-bit characters with <literal>cs8</literal>, + no modem control with <literal>clocal</literal> and + hardware flow control with <literal>crtscts</literal>:</para> + + <programlisting>bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\ + :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:</programlisting> + </sect4> + + <sect4 id="printing-textfilter"> + <title>Installing the Text Filter</title> + <indexterm> + <primary>printing</primary> + <secondary>filters</secondary> + </indexterm> + + <para>We are now ready to tell <application>LPD</application> + what text filter to use to + send jobs to the printer. A <emphasis>text filter</emphasis>, + also known as an <emphasis>input filter</emphasis>, is a + program that <application>LPD</application> runs when it + has a job to print. When <application>LPD</application> + runs the text filter for a printer, it sets the filter's + standard input to the job to print, and its standard output to + the printer device specified with the <literal>lp</literal> + capability. The filter is expected to read the job from + standard input, perform any necessary translation for the + printer, and write the results to standard output, which will + get printed. For more information on the text filter, see + the <link linkend="printing-advanced-filters">Filters</link> + section.</para> + + <para>For our simple printer setup, the text filter can be a + small shell script that just executes + <command>/bin/cat</command> to send the job to the printer. + &os; comes with another filter called + <filename>lpf</filename> that handles backspacing and + underlining for printers that might not deal with such + character streams well. And, of course, you can use any other + filter program you want. The filter <command>lpf</command> is + described in detail in section entitled <link + linkend="printing-advanced-lpf">lpf: a Text Filter</link>.</para> + + <para>First, let us make the shell script + <filename>/usr/local/libexec/if-simple</filename> be a simple + text filter. Put the following text into that file with your + favorite text editor:</para> + + <programlisting>#!/bin/sh +# +# if-simple - Simple text input filter for lpd +# Installed in /usr/local/libexec/if-simple +# +# Simply copies stdin to stdout. Ignores all filter arguments. + +/bin/cat && exit 0 +exit 2</programlisting> + + <para>Make the file executable:</para> + + <screen>&prompt.root; <userinput><command>chmod 555 <filename>/usr/local/libexec/if-simple</filename></command></userinput></screen> + + <para>And then tell LPD to use it by specifying it with the + <literal>if</literal> capability in + <filename>/etc/printcap</filename>. We will add it to the two + printers we have so far in the example + <filename>/etc/printcap</filename>:</para> + + <programlisting># +# /etc/printcap for host rose - added text filter +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :if=<filename>/usr/local/libexec/if-simple</filename>: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\ + :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:\ + :if=<filename>/usr/local/libexec/if-simple</filename>:</programlisting> + + <note> + <para>A copy of the <filename>if-simple</filename> script + can be found in the <filename + class="directory">/usr/share/examples/printing</filename> + directory.</para> + </note> + </sect4> + + <sect4> + <title>Turn on <application>LPD</application></title> + + <para>&man.lpd.8; is run from <filename>/etc/rc</filename>, + controlled by the <literal>lpd_enable</literal> variable. This + variable defaults to <literal>NO</literal>. If you have not done + so already, add the line:</para> + + <programlisting>lpd_enable="YES"</programlisting> + + <para>to <filename>/etc/rc.conf</filename>, and then either restart + your machine, or just run &man.lpd.8;.</para> + + <screen>&prompt.root; <userinput><command>lpd</command></userinput></screen> + </sect4> + + <sect4 id="printing-trying"> + <title>Trying It Out</title> + + <para>You have reached the end of the simple + <application>LPD</application> setup. + Unfortunately, congratulations are not quite yet in order, + since we still have to test the setup and correct any + problems. To test the setup, try printing something. To + print with the <application>LPD</application> system, you + use the command &man.lpr.1;, + which submits a job for printing.</para> + + <para>You can combine &man.lpr.1; with the &man.lptest.1; + program, introduced in section <link + linkend="printing-testing">Checking Printer + Communications</link> to generate some test text.</para> + + <para><emphasis>To test the simple <application>LPD</application> + setup:</emphasis></para> + + <para>Type:</para> + + <screen>&prompt.root; <userinput><command>lptest 20 5 | lpr <option>-P</option><replaceable>printer-name</replaceable></command></userinput></screen> + + <para>Where <replaceable>printer-name</replaceable> is a the + name of a printer (or an alias) specified in + <filename>/etc/printcap</filename>. To test the default + printer, type &man.lpr.1; without any <option>-P</option> + argument. Again, if you are testing a printer that expects + &postscript;, send a &postscript; program in that language instead + of using &man.lptest.1;. You can do so by putting the program + in a file and typing <command>lpr + <replaceable>file</replaceable></command>.</para> + + <para>For a &postscript; printer, you should get the results of + the program. If you are using &man.lptest.1;, then your + results should look like the following:</para> + + <screen>!"#$%&'()*+,-./01234 +"#$%&'()*+,-./012345 +#$%&'()*+,-./0123456 +$%&'()*+,-./01234567 +%&'()*+,-./012345678</screen> + + <para>To further test the printer, try downloading larger + programs (for language-based printers) or running + &man.lptest.1; with different arguments. For example, + <command>lptest 80 60</command> will produce 60 lines of 80 + characters each.</para> + + <para>If the printer did not work, see the <link + linkend="printing-troubleshooting">Troubleshooting</link> + section.</para> + </sect4> + </sect3> + </sect2> + </sect1> + + <sect1 id="printing-advanced"> + <title>Advanced Printer Setup</title> + + <warning> + <para>As of &os; 8.0, device nodes for serial ports have been + renamed from + <filename>/dev/ttyd<replaceable>N</replaceable></filename> to + <filename>/dev/ttyu<replaceable>N</replaceable></filename>. + &os; 7.X users will have to adapt the following + documentation according to these changes.</para> + </warning> + + <para>This section describes filters for printing specially formatted + files, header pages, printing across networks, and restricting and + accounting for printer usage.</para> + + <sect2 id="printing-advanced-filter-intro"> + <title>Filters</title> + <indexterm> + <primary>printing</primary> + <secondary>filters</secondary> + </indexterm> + + <para>Although <application>LPD</application> handles network protocols, + queuing, access control, and other aspects of printing, most of the + <emphasis>real</emphasis> work happens in the + <emphasis>filters</emphasis>. Filters are programs that communicate + with the printer and handle its device dependencies and special + requirements. In the simple printer setup, we installed a plain text + filter—an extremely simple one that should work with most + printers (section <link linkend="printing-textfilter">Installing the + Text Filter</link>).</para> + + <para>However, in order to take advantage of format conversion, printer + accounting, specific printer quirks, and so on, you should understand + how filters work. It will ultimately be the filter's responsibility + to handle these aspects. And the bad news is that most of the time + <emphasis>you</emphasis> have to provide filters yourself. The good + news is that many are generally available; when they are not, they are + usually easy to write.</para> + + <para>Also, &os; comes with one, + <filename>/usr/libexec/lpr/lpf</filename>, that works with many + printers that can print plain text. (It handles backspacing and tabs + in the file, and does accounting, but that is about all it does.) + There are also several filters and filter components in the &os; + Ports Collection.</para> + + <para>Here is what you will find in this section:</para> + + <itemizedlist> + <listitem> + <para>Section <link linkend="printing-advanced-filters">How Filters + Work</link>, tries to give an overview of a filter's role in the + printing process. You should read this section to get an + understanding of what is happening <quote>under the hood</quote> + when <application>LPD</application> uses filters. This knowledge + could help you anticipate + and debug problems you might encounter as you install more and + more filters for each of your printers.</para> + </listitem> + + <listitem> + <para><application>LPD</application> expects every printer to be + able to print plain text by + default. This presents a problem for &postscript; printers + (or other language-based printers) which cannot directly print + plain text. Section <link + linkend="printing-advanced-if-conversion">Accommodating + Plain Text Jobs on &postscript; Printers</link> tells you what + you should do to overcome this problem. You should read this + section if you have a &postscript; printer.</para> + </listitem> + + <listitem> + <para>&postscript; is a popular output format for many programs. + Some people even write &postscript; code directly. Unfortunately, + &postscript; printers are expensive. Section <link + linkend="printing-advanced-ps">Simulating &postscript; on + Non &postscript; Printers</link> tells how you can further + modify a printer's text filter to accept and print &postscript; + data on a <emphasis>non &postscript;</emphasis> printer. You + should read this section if you do not have a &postscript; + printer.</para> + </listitem> + + <listitem> + <para>Section <link + linkend="printing-advanced-convfilters">Conversion + Filters</link> tells about a way you can automate the conversion + of specific file formats, such as graphic or typesetting data, + into formats your printer can understand. After reading this + section, you should be able to set up your printers such that + users can type <command>lpr <option>-t</option></command> to + print troff data, or <command>lpr <option>-d</option></command> + to print &tex; DVI data, or + <command>lpr <option>-v</option></command> to print raster image + data, and so forth. The reading of this section is + recommended.</para> + </listitem> + + <listitem> + <para>Section <link linkend="printing-advanced-of">Output + Filters</link> tells all about a not often used feature of + <application>LPD</application>: + output filters. Unless you are printing header pages (see <link + linkend="printing-advanced-header-pages">Header Pages</link>), + you can probably skip that section altogether.</para> + </listitem> + + <listitem> + <para>Section <link linkend="printing-advanced-lpf">lpf: a Text + Filter</link> describes <command>lpf</command>, a fairly + complete if simple text filter for line printers (and laser + printers that act like line printers) that comes with &os;. If + you need a quick way to get printer accounting working for plain + text, or if you have a printer which emits smoke when it sees + backspace characters, you should definitely consider + <command>lpf</command>.</para> + </listitem> + </itemizedlist> + + <note> + <para>A copy of the various scripts described below can be + found in the <filename + class="directory">/usr/share/examples/printing</filename> + directory.</para> + </note> + + <sect3 id="printing-advanced-filters"> + <title>How Filters Work</title> + + <para>As mentioned before, a filter is an executable program started + by <application>LPD</application> to handle the device-dependent + part of communicating with the printer.</para> + + <para>When <application>LPD</application> wants to print a file in a + job, it starts a filter program. It sets the filter's standard + input to the file to print, its standard output to the printer, and + its standard error to the error logging file (specified in the + <literal>lf</literal> capability in + <filename>/etc/printcap</filename>, or + <filename class="devicefile">/dev/console</filename> by default).</para> + + <indexterm> + <primary><command>troff</command></primary> + </indexterm> + <para>Which filter <application>LPD</application> starts and the + filter's arguments depend on what is listed in the + <filename>/etc/printcap</filename> file and what arguments the user + specified for the job on the &man.lpr.1; command line. For + example, if the user typed + <command>lpr <option>-t</option></command>, + <application>LPD</application> would start the troff filter, listed + in the <literal>tf</literal> capability for the destination printer. + If the user wanted to print plain text, it would start the + <literal>if</literal> filter (this is mostly true: see <link + linkend="printing-advanced-of">Output Filters</link> for + details).</para> + + <para>There are three kinds of filters you can specify in + <filename>/etc/printcap</filename>:</para> + + <itemizedlist> + <listitem> + <para>The <emphasis>text filter</emphasis>, confusingly called the + <emphasis>input filter</emphasis> in + <application>LPD</application> documentation, handles + regular text printing. Think of it as the default filter. + <application>LPD</application> + expects every printer to be able to print plain text by default, + and it is the text filter's job to make sure backspaces, tabs, + or other special characters do not confuse the printer. If you + are in an environment where you have to account for printer + usage, the text filter must also account for pages printed, + usually by counting the number of lines printed and comparing + that to the number of lines per page the printer supports. The + text filter is started with the following argument list:</para> + + <cmdsynopsis> + <command>filter-name</command> + <arg>-c</arg> + <arg choice="plain">-w <replaceable>width</replaceable></arg> + <arg choice="plain">-l <replaceable>length</replaceable></arg> + <arg choice="plain">-i <replaceable>indent</replaceable></arg> + <arg choice="plain">-n <replaceable>login</replaceable></arg> + <arg choice="plain">-h <replaceable>host</replaceable></arg> + <arg choice="plain"><replaceable>acct-file</replaceable></arg> + </cmdsynopsis> + + <para>where</para> + + <variablelist> + <varlistentry> + <term><option>-c</option></term> + + <listitem> + <para>appears if the job is submitted with <command>lpr + <option>-l</option></command></para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>width</replaceable></term> + + <listitem> + <para>is the value from the <literal>pw</literal> (page + width) capability specified in + <filename>/etc/printcap</filename>, default 132</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>length</replaceable></term> + + <listitem> + <para>is the value from the <literal>pl</literal> (page + length) capability, default 66</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>indent</replaceable></term> + + <listitem> + <para>is the amount of the indentation from <command>lpr + <option>-i</option></command>, default 0</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>login</replaceable></term> + + <listitem> + <para>is the account name of the user printing the + file</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>host</replaceable></term> + + <listitem> + <para>is the host name from which the job was + submitted</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>acct-file</replaceable></term> + + <listitem> + <para>is the name of the accounting file from the + <literal>af</literal> capability.</para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + + <indexterm> + <primary>printing</primary> + <secondary>filters</secondary> + </indexterm> + <listitem> + <para>A <emphasis>conversion filter</emphasis> converts a specific + file format into one the printer can render onto paper. For + example, ditroff typesetting data cannot be directly printed, + but you can install a conversion filter for ditroff files to + convert the ditroff data into a form the printer can digest and + print. Section <link + linkend="printing-advanced-convfilters">Conversion + Filters</link> tells all about them. Conversion filters also + need to do accounting, if you need printer accounting. + Conversion filters are started with the following + arguments:</para> + + <cmdsynopsis> + <command>filter-name</command> + <arg choice="plain">-x <replaceable>pixel-width</replaceable></arg> + <arg choice="plain">-y <replaceable>pixel-height</replaceable></arg> + <arg choice="plain">-n <replaceable>login</replaceable></arg> + <arg choice="plain">-h <replaceable>host</replaceable></arg> + <arg choice="plain"><replaceable>acct-file</replaceable></arg> + </cmdsynopsis> + + <para>where <replaceable>pixel-width</replaceable> is the value + from the <literal>px</literal> capability (default 0) and + <replaceable>pixel-height</replaceable> is the value from the + <literal>py</literal> capability (default 0).</para> + </listitem> + + <listitem> + <para>The <emphasis>output filter</emphasis> is used only if there + is no text filter, or if header pages are enabled. In our + experience, output filters are rarely used. Section <link + linkend="printing-advanced-of">Output Filters</link> describes + them. There are only two arguments to an output filter:</para> + + <cmdsynopsis> + <command>filter-name</command> + <arg choice="plain">-w <replaceable>width</replaceable></arg> + <arg choice="plain">-l <replaceable>length</replaceable></arg> + </cmdsynopsis> + + <para>which are identical to the text filters + <option>-w</option> and <option>-l</option> arguments.</para> + </listitem> + </itemizedlist> + + <para>Filters should also <emphasis>exit</emphasis> with the + following exit status:</para> + + <variablelist> + <varlistentry> + <term>exit 0</term> + + <listitem> + <para>If the filter printed the file successfully.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>exit 1</term> + + <listitem> + <para>If the filter failed to print the file but wants + <application>LPD</application> to + try to print the file again. <application>LPD</application> + will restart a filter if it exits with this status.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>exit 2</term> + + <listitem> + <para>If the filter failed to print the file and does not want + <application>LPD</application> to try again. + <application>LPD</application> will throw out the file.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>The text filter that comes with the &os; release, + <filename>/usr/libexec/lpr/lpf</filename>, takes advantage of the + page width and length arguments to determine when to send a form + feed and how to account for printer usage. It uses the login, host, + and accounting file arguments to make the accounting entries.</para> + + <para>If you are shopping for filters, see if they are LPD-compatible. + If they are, they must support the argument lists described above. + If you plan on writing filters for general use, then have them + support the same argument lists and exit codes.</para> + </sect3> + + <sect3 id="printing-advanced-if-conversion"> + <title>Accommodating Plain Text Jobs on &postscript; Printers</title> + <indexterm><primary>print jobs</primary></indexterm> + + <para>If you are the only user of your computer and &postscript; (or + other language-based) printer, and you promise to never send plain + text to your printer and to never use features of various programs + that will want to send plain text to your printer, then you do not + need to worry about this section at all.</para> + + <para>But, if you would like to send both &postscript; and plain text + jobs to the printer, then you are urged to augment your printer + setup. To do so, we have the text filter detect if the arriving job + is plain text or &postscript;. All &postscript; jobs must start + with <literal>%!</literal> (for other printer languages, see your + printer documentation). If those are the first two characters in + the job, we have &postscript;, and can pass the rest of the job + directly. If those are not the first two characters in the file, + then the filter will convert the text into &postscript; and print + the result.</para> + + <para>How do we do this?</para> + + <indexterm> + <primary>printers</primary> + <secondary>serial</secondary> + </indexterm> + <para>If you have got a serial printer, a great way to do it is to + install <command>lprps</command>. <command>lprps</command> is a + &postscript; printer filter which performs two-way communication + with the printer. It updates the printer's status file with verbose + information from the printer, so users and administrators can see + exactly what the state of the printer is (such as <errorname>toner + low</errorname> or <errorname>paper jam</errorname>). But more + importantly, it includes a program called <command>psif</command> + which detects whether the incoming job is plain text and calls + <command>textps</command> (another program that comes with + <command>lprps</command>) to convert it to &postscript;. It then + uses <command>lprps</command> to send the job to the printer.</para> + + <para><command>lprps</command> is part of the &os; Ports Collection + (see <link linkend="ports">The Ports Collection</link>). You can + install one of the both + <filename role="package">print/lprps-a4</filename> and + <filename role="package">print/lprps-letter</filename> ports + according to the paper size used. After installing + <command>lprps</command>, just specify the pathname to the + <command>psif</command> program that is part of + <command>lprps</command>. If you installed <command>lprps</command> + from the Ports Collection, use the following in the serial + &postscript; printer's entry in + <filename>/etc/printcap</filename>:</para> + + <programlisting>:if=<filename>/usr/local/libexec/psif</filename>:</programlisting> + + <para>The <literal>rw</literal> capability should be also included in + order to let <application>LPD</application> to open the printer in + the read-write mode.</para> + + <para>If you have a parallel &postscript; printer (and therefore + cannot use two-way communication with the printer, which + <command>lprps</command> needs), you can use the following shell + script as the text filter:</para> + + <programlisting>#!/bin/sh +# +# psif - Print PostScript or plain text on a PostScript printer +# Script version; NOT the version that comes with lprps +# Installed in /usr/local/libexec/psif +# + +IFS="" read -r first_line +first_two_chars=`expr "$first_line" : '\(..\)'` + +if [ "$first_two_chars" = "%!" ]; then + # + # PostScript job, print it. + # + echo "$first_line" && cat && printf "\004" && exit 0 + exit 2 +else + # + # Plain text, convert it, then print it. + # + ( echo "$first_line"; cat ) | /usr/local/bin/textps && printf "\004" && exit 0 + exit 2 +fi</programlisting> + + <para>In the above script, <command>textps</command> is a program we + installed separately to convert plain text to &postscript;. You can + use any text-to-&postscript; program you wish. The &os; Ports + Collection (see <link linkend="ports">The Ports Collection</link>) + includes a full featured text-to-&postscript; program called + <literal>a2ps</literal> that you might want to investigate.</para> + </sect3> + + <sect3 id="printing-advanced-ps"> + <title>Simulating &postscript; on Non &postscript; Printers</title> + <indexterm> + <primary>PostScript</primary> + <secondary>emulating</secondary> + </indexterm> + <indexterm> <primary>Ghostscript</primary></indexterm> + + <para>&postscript; is the <emphasis>de facto</emphasis> standard for + high quality typesetting and printing. &postscript; is, however, an + <emphasis>expensive</emphasis> standard. Thankfully, Aladdin + Enterprises has a free &postscript; work-alike called + <application>Ghostscript</application> that runs with &os;. + <application>Ghostscript</application> can read most &postscript; + files and can render their pages onto a variety of devices, + including many brands of non-&postscript; printers. By installing + <application>Ghostscript</application> and using a special text + filter for your printer, you can make your non &postscript; printer + act like a real &postscript; printer.</para> + + <para><application>Ghostscript</application> is in the &os; Ports + Collection, many versions are available, the most commonly used + version is <filename + role="package">print/ghostscript-gpl</filename>.</para> + + <para>To simulate &postscript;, we have the text filter detect if it + is printing a &postscript; file. If it is not, then the filter + will pass the file directly to the printer; otherwise, it will use + <application>Ghostscript</application> to first convert the file + into a format the printer will understand.</para> + + <para>Here is an example: the following script is a text filter + for Hewlett Packard DeskJet 500 printers. For other printers, + substitute the <option>-sDEVICE</option> argument to the + <command>gs</command> (<application>Ghostscript</application>) + command. (Type <command>gs <option>-h</option></command> to get a + list of devices the current installation of + <application>Ghostscript</application> supports.)</para> + + <programlisting>#!/bin/sh +# +# ifhp - Print Ghostscript-simulated PostScript on a DeskJet 500 +# Installed in /usr/local/libexec/ifhp + +# +# Treat LF as CR+LF (to avoid the "staircase effect" on HP/PCL +# printers): +# +printf "\033&k2G" || exit 2 + +# +# Read first two characters of the file +# +IFS="" read -r first_line +first_two_chars=`expr "$first_line" : '\(..\)'` + +if [ "$first_two_chars" = "%!" ]; then + # + # It is PostScript; use Ghostscript to scan-convert and print it. + # + /usr/local/bin/gs -dSAFER -dNOPAUSE -q -sDEVICE=djet500 \ + -sOutputFile=- - && exit 0 +else + # + # Plain text or HP/PCL, so just print it directly; print a form feed + # at the end to eject the last page. + # + echo "$first_line" && cat && printf "\033&l0H" && +exit 0 +fi + +exit 2</programlisting> + + <para>Finally, you need to notify <application>LPD</application> of + the filter via the <literal>if</literal> capability:</para> + + <programlisting>:if=<filename>/usr/local/libexec/ifhp</filename>:</programlisting> + + <para>That is it. You can type + <command>lpr <filename><replaceable>plain.text</replaceable></filename></command> and + <command>lpr <filename><replaceable>whatever.ps</replaceable></filename></command> and both should print successfully.</para> + </sect3> + + <sect3 id="printing-advanced-convfilters"> + <title>Conversion Filters</title> + + <para>After completing the simple setup described in <link + linkend="printing-simple">Simple Printer Setup</link>, the first + thing you will probably want to do is install conversion filters for + your favorite file formats (besides plain ASCII text).</para> + + <sect4> + <title>Why Install Conversion Filters?</title> + <indexterm> + <primary>&tex;</primary> + <secondary>printing DVI files</secondary> + </indexterm> + + <para>Conversion filters make printing various kinds of files easy. + As an example, suppose we do a lot of work with the &tex; + typesetting system, and we have a &postscript; printer. Every + time we generate a DVI file from &tex;, we cannot print it + directly until we convert the DVI file into &postscript;. The + command sequence goes like this:</para> + + <screen>&prompt.user; <userinput><command>dvips <filename><replaceable>seaweed-analysis.dvi</replaceable></filename></command></userinput> +&prompt.user; <userinput><command>lpr <filename><replaceable>seaweed-analysis.ps</replaceable></filename></command></userinput></screen> + + <para>By installing a conversion filter for DVI files, we can skip + the hand conversion step each time by having + <application>LPD</application> do it for us. Now, each time we + get a DVI file, we are just one step away from printing it:</para> + + <screen>&prompt.user; <userinput><command>lpr <option>-d</option> <filename><replaceable>seaweed-analysis.dvi</replaceable></filename></command></userinput></screen> + + <para>We got <application>LPD</application> to do the DVI file + conversion for us by specifying + the <option>-d</option> option. Section <link + linkend="printing-lpr-options-format">Formatting and Conversion + Options</link> lists the conversion options.</para> + + <para>For each of the conversion options you want a printer to + support, install a <emphasis>conversion filter</emphasis> and + specify its pathname in <filename>/etc/printcap</filename>. A + conversion filter is like the text filter for the simple printer + setup (see section <link linkend="printing-textfilter">Installing + the Text Filter</link>) except that instead of printing plain + text, the filter converts the file into a format the printer can + understand.</para> + </sect4> + + <sect4> + <title>Which Conversion Filters Should I Install?</title> + + <para>You should install the conversion filters you expect to use. + If you print a lot of DVI data, then a DVI conversion filter is in + order. If you have got plenty of troff to print out, then you + probably want a troff filter.</para> + + <para>The following table summarizes the filters that + <application>LPD</application> works + with, their capability entries for the + <filename>/etc/printcap</filename> file, and how to invoke them + with the <command>lpr</command> command:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <thead> + <row> + <entry>File type</entry> + <entry><filename>/etc/printcap</filename> capability</entry> + <entry><command>lpr</command> option</entry> + </row> + </thead> + + <tbody> + <row> + <entry>cifplot</entry> + <entry><literal>cf</literal></entry> + <entry><option>-c</option></entry> + </row> + + <row> + <entry>DVI</entry> + <entry><literal>df</literal></entry> + <entry><option>-d</option></entry> + </row> + + <row> + <entry>plot</entry> + <entry><literal>gf</literal></entry> + <entry><option>-g</option></entry> + </row> + + <row> + <entry>ditroff</entry> + <entry><literal>nf</literal></entry> + <entry><option>-n</option></entry> + </row> + + <row> + <entry>FORTRAN text</entry> + <entry><literal>rf</literal></entry> + <entry><option>-f</option></entry> + </row> + + <row> + <entry>troff</entry> + <entry><literal>tf</literal></entry> + <entry><option>-f</option></entry> + </row> + + <row> + <entry>raster</entry> + <entry><literal>vf</literal></entry> + <entry><option>-v</option></entry> + </row> + + <row> + <entry>plain text</entry> + <entry><literal>if</literal></entry> + <entry>none, <option>-p</option>, or + <option>-l</option></entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>In our example, using + <command>lpr <option>-d</option></command> means the printer + needs a <literal>df</literal> capability in its entry in + <filename>/etc/printcap</filename>.</para> + + <indexterm><primary>FORTRAN</primary></indexterm> + <para>Despite what others might contend, formats like FORTRAN text + and plot are probably obsolete. At your site, you can give new + meanings to these or any of the formatting options just by + installing custom filters. For example, suppose you would like to + directly print Printerleaf files (files from the Interleaf desktop + publishing program), but will never print plot files. You could + install a Printerleaf conversion filter under the + <literal>gf</literal> capability and then educate your users that + <command>lpr <option>-g</option></command> mean <quote>print + Printerleaf files.</quote></para> + </sect4> + + <sect4> + <title>Installing Conversion Filters</title> + + <para>Since conversion filters are programs you install outside of + the base &os; installation, they should probably go under + <filename class="directory">/usr/local</filename>. The directory + <filename class="directory">/usr/local/libexec</filename> is a + popular location, since they are specialized programs that only + <application>LPD</application> will run; regular users should + not ever need to run them.</para> + + <para>To enable a conversion filter, specify its pathname under the + appropriate capability for the destination printer in + <filename>/etc/printcap</filename>.</para> + + <para>In our example, we will add the DVI conversion filter to the + entry for the printer named <literal>bamboo</literal>. Here is + the example <filename>/etc/printcap</filename> file again, with + the new <literal>df</literal> capability for the printer + <literal>bamboo</literal>:</para> + + <programlisting># +# /etc/printcap for host rose - added df filter for bamboo +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :if=<filename>/usr/local/libexec/if-simple</filename>: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\ + :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ + :if=<filename>/usr/local/libexec/psif</filename>:\ + :df=<filename>/usr/local/libexec/psdf</filename>:</programlisting> + + <para>The DVI filter is a shell script named + <filename>/usr/local/libexec/psdf</filename>. Here is that + script:</para> + + <programlisting>#!/bin/sh +# +# psdf - DVI to PostScript printer filter +# Installed in /usr/local/libexec/psdf +# +# Invoked by lpd when user runs lpr -d +# +exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@"</programlisting> + + <para>This script runs <command>dvips</command> in filter mode (the + <option>-f</option> argument) on standard input, which is the job + to print. It then starts the &postscript; printer filter + <command>lprps</command> (see section <link + linkend="printing-advanced-if-conversion">Accommodating Plain + Text Jobs on &postscript; Printers</link>) with the arguments + <application>LPD</application> + passed to this script. The <command>lprps</command> utility will + use those arguments to account for the pages printed.</para> + </sect4> + + <sect4> + <title>More Conversion Filter Examples</title> + + <para>There is no fixed set of steps to install conversion + filters, some working examples are described in this section. + Use these as guidance to making your own filters. Use them + directly, if appropriate.</para> + + <para>This example script is a raster (well, GIF file, actually) + conversion filter for a Hewlett Packard LaserJet III-Si + printer:</para> + + <programlisting>#!/bin/sh +# +# hpvf - Convert GIF files into HP/PCL, then print +# Installed in /usr/local/libexec/hpvf + +PATH=/usr/X11R6/bin:$PATH; export PATH +giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \ + && exit 0 \ + || exit 2</programlisting> + + <para>It works by converting the GIF file into a portable anymap, + converting that into a portable graymap, converting that into a + portable bitmap, and converting that into LaserJet/PCL-compatible + data.</para> + + <para>Here is the <filename>/etc/printcap</filename> file with an + entry for a printer using the above filter:</para> + + <programlisting># +# /etc/printcap for host orchid +# +teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:sh:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\ + :if=<filename>/usr/local/libexec/hpif</filename>:\ + :vf=<filename>/usr/local/libexec/hpvf</filename>:</programlisting> + + <para>The following script is a conversion filter for troff data + from the groff typesetting system for the &postscript; printer + named <literal>bamboo</literal>:</para> + + <programlisting>#!/bin/sh +# +# pstf - Convert groff's troff data into PS, then print. +# Installed in /usr/local/libexec/pstf +# +exec grops | /usr/local/libexec/lprps "$@"</programlisting> + + <para>The above script makes use of <command>lprps</command> again + to handle the communication with the printer. If the printer were + on a parallel port, we would use this script instead:</para> + + <programlisting>#!/bin/sh +# +# pstf - Convert groff's troff data into PS, then print. +# Installed in /usr/local/libexec/pstf +# +exec grops</programlisting> + + <para>That is it. Here is the entry we need to add to + <filename>/etc/printcap</filename> to enable the filter:</para> + + <programlisting>:tf=<filename>/usr/local/libexec/pstf</filename>:</programlisting> + + <para>Here is an example that might make old hands at FORTRAN blush. + It is a FORTRAN-text filter for any printer that can directly + print plain text. We will install it for the printer + <literal>teak</literal>:</para> + + <programlisting>#!/bin/sh +# +# hprf - FORTRAN text filter for LaserJet 3si: +# Installed in /usr/local/libexec/hprf +# + +printf "\033&k2G" && fpr && printf "\033&l0H" && + exit 0 +exit 2</programlisting> + + <para>And we will add this line to the + <filename>/etc/printcap</filename> for the printer + <literal>teak</literal> to enable this filter:</para> + + <programlisting>:rf=<filename>/usr/local/libexec/hprf</filename>:</programlisting> + + <para>Here is one final, somewhat complex example. We will add a + DVI filter to the LaserJet printer <literal>teak</literal> + introduced earlier. First, the easy part: updating + <filename>/etc/printcap</filename> with the location of the DVI + filter:</para> + + <programlisting>:df=<filename>/usr/local/libexec/hpdf</filename>:</programlisting> + + <para>Now, for the hard part: making the filter. For that, we need + a DVI-to-LaserJet/PCL conversion program. The &os; Ports + Collection (see <link linkend="ports">The Ports Collection</link>) + has one: <filename role="package">print/dvi2xx</filename>. + Installing this port gives us the program we need, + <command>dvilj2p</command>, which converts DVI into LaserJet IIp, + LaserJet III, and LaserJet 2000 compatible codes.</para> + + <para>The <command>dvilj2p</command> utility makes the filter + <command>hpdf</command> quite complex since + <command>dvilj2p</command> cannot read from standard input. It + wants to work with a filename. What is worse, the filename has to + end in <filename>.dvi</filename> so using + <filename class="devicefile">/dev/fd/0</filename> for standard + input is problematic. We can get around that problem by linking + (symbolically) a temporary file name (one that ends in + <filename>.dvi</filename>) to + <filename class="devicefile">/dev/fd/0</filename>, thereby forcing + <command>dvilj2p</command> to read from standard input.</para> + + <para>The only other fly in the ointment is the fact that we cannot + use <filename class="directory">/tmp</filename> for the temporary + link. Symbolic links are owned by user and group + <username>bin</username>. The filter runs as user + <username>daemon</username>. And the + <filename class="directory">/tmp</filename> directory has the + sticky bit set. The filter can create the link, but it will not + be able clean up when done and remove it since the link will + belong to a different user.</para> + + <para>Instead, the filter will make the symbolic link in the current + working directory, which is the spooling directory (specified by + the <literal>sd</literal> capability in + <filename>/etc/printcap</filename>). This is a perfect place for + filters to do their work, especially since there is (sometimes) + more free disk space in the spooling directory than under + <filename class="directory">/tmp</filename>.</para> + + <para>Here, finally, is the filter:</para> + + <programlisting>#!/bin/sh +# +# hpdf - Print DVI data on HP/PCL printer +# Installed in /usr/local/libexec/hpdf + +PATH=/usr/local/bin:$PATH; export PATH + +# +# Define a function to clean up our temporary files. These exist +# in the current directory, which will be the spooling directory +# for the printer. +# +cleanup() { + rm -f hpdf$$.dvi +} + +# +# Define a function to handle fatal errors: print the given message +# and exit 2. Exiting with 2 tells LPD to do not try to reprint the +# job. +# +fatal() { + echo "$@" 1>&2 + cleanup + exit 2 +} + +# +# If user removes the job, LPD will send SIGINT, so trap SIGINT +# (and a few other signals) to clean up after ourselves. +# +trap cleanup 1 2 15 + +# +# Make sure we are not colliding with any existing files. +# +cleanup + +# +# Link the DVI input file to standard input (the file to print). +# +ln -s /dev/fd/0 hpdf$$.dvi || fatal "Cannot symlink /dev/fd/0" + +# +# Make LF = CR+LF +# +printf "\033&k2G" || fatal "Cannot initialize printer" + +# +# Convert and print. Return value from dvilj2p does not seem to be +# reliable, so we ignore it. +# +dvilj2p -M1 -q -e- dfhp$$.dvi + +# +# Clean up and exit +# +cleanup +exit 0</programlisting> + </sect4> + + <sect4 id="printing-advanced-autoconv"> + <title>Automated Conversion: an Alternative to Conversion + Filters</title> + + <para>All these conversion filters accomplish a lot for your + printing environment, but at the cost forcing the user to specify + (on the &man.lpr.1; command line) which one to use. + If your users are not particularly computer literate, having to + specify a filter option will become annoying. What is worse, + though, is that an incorrectly specified filter option may run a + filter on the wrong type of file and cause your printer to spew + out hundreds of sheets of paper.</para> + + <para>Rather than install conversion filters at all, you might want + to try having the text filter (since it is the default filter) + detect the type of file it has been asked to print and then + automatically run the right conversion filter. Tools such as + <command>file</command> can be of help here. Of course, it will + be hard to determine the differences between + <emphasis>some</emphasis> file types—and, of course, you can + still provide conversion filters just for them.</para> + + <indexterm><primary>apsfilter</primary></indexterm> + <indexterm> + <primary>printing</primary> + <secondary>filters</secondary> + <tertiary>apsfilter</tertiary> + </indexterm> + <para>The &os; Ports Collection has a text filter that performs + automatic conversion called <command>apsfilter</command> + (<filename role="package">print/apsfilter</filename>). It can + detect plain text, &postscript;, DVI and almost any kind of + files, run the proper conversions, and print.</para> + </sect4> + </sect3> + + <sect3 id="printing-advanced-of"> + <title>Output Filters</title> + + <para>The <application>LPD</application> spooling system supports one + other type of filter that we have not yet explored: an output + filter. An output filter is intended for printing plain text only, + like the text filter, but with many simplifications. If you are + using an output filter but no text filter, then:</para> + + <itemizedlist> + <listitem> + <para><application>LPD</application> starts an output filter once + for the entire job instead of once for each file in the + job.</para> + </listitem> + + <listitem> + <para><application>LPD</application> does not make any provision + to identify the start or the end of files within the job for + the output filter.</para> + </listitem> + + <listitem> + <para><application>LPD</application> does not pass the user's + login or host to the filter, so it is not intended to do + accounting. In fact, it gets only two arguments:</para> + + <cmdsynopsis> + <command>filter-name</command> + <arg choice="plain">-w<replaceable>width</replaceable></arg> + <arg choice="plain">-l<replaceable>length</replaceable></arg> + </cmdsynopsis> + + <para>Where <replaceable>width</replaceable> is from the + <literal>pw</literal> capability and + <replaceable>length</replaceable> is from the + <literal>pl</literal> capability for the printer in + question.</para> + </listitem> + </itemizedlist> + + <para>Do not be seduced by an output filter's simplicity. If you + would like each file in a job to start on a different page an output + filter <emphasis>will not work</emphasis>. Use a text filter (also + known as an input filter); see section <link + linkend="printing-textfilter">Installing the Text Filter</link>. + Furthermore, an output filter is actually <emphasis>more + complex</emphasis> in that it has to examine the byte stream being + sent to it for special flag characters and must send signals to + itself on behalf of <application>LPD</application>.</para> + + <para>However, an output filter is <emphasis>necessary</emphasis> if + you want header pages and need to send escape sequences or other + initialization strings to be able to print the header page. (But it + is also <emphasis>futile</emphasis> if you want to charge header + pages to the requesting user's account, since + <application>LPD</application> does not give any user or host + information to the output filter.)</para> + + <para>On a single printer, <application>LPD</application> + allows both an output filter and text or other filters. In + such cases, <application>LPD</application> will start the + output filter to print the header page (see section <link + linkend="printing-advanced-header-pages">Header Pages</link>) + only. <application>LPD</application> then expects the + output filter to <emphasis>stop itself</emphasis> by sending two + bytes to the filter: ASCII 031 followed by ASCII 001. When an + output filter sees these two bytes (031, 001), it should stop by + sending <literal>SIGSTOP</literal> to itself. When + <application>LPD</application>'s done running other filters, it will + restart the output filter by sending <literal>SIGCONT</literal> to + it.</para> + + <para>If there is an output filter but <emphasis>no</emphasis> text + filter and <application>LPD</application> is working on a plain + text job, <application>LPD</application> uses the output + filter to do the job. As stated before, the output filter will + print each file of the job in sequence with no intervening form + feeds or other paper advancement, and this is probably + <emphasis>not</emphasis> what you want. In almost all cases, you + need a text filter.</para> + + <para>The program <command>lpf</command>, which we introduced earlier + as a text filter, can also run as an output filter. If you need a + quick-and-dirty output filter but do not want to write the byte + detection and signal sending code, try <command>lpf</command>. You + can also wrap <command>lpf</command> in a shell script to handle any + initialization codes the printer might require.</para> + </sect3> + + <sect3 id="printing-advanced-lpf"> + <title><command>lpf</command>: a Text Filter</title> + + <para>The program <filename>/usr/libexec/lpr/lpf</filename> that comes + with &os; binary distribution is a text filter (input filter) + that can indent output (job submitted with + <command>lpr <option>-i</option></command>), allow literal + characters to pass (job submitted with + <command>lpr <option>-l</option></command>), adjust the printing + position for backspaces and tabs in the job, and account for pages + printed. It can also act like an output filter.</para> + + <para>The <command>lpf</command> filter is suitable for many printing + environments. And although it has no capability to send + initialization sequences to a printer, it is easy to write a shell + script to do the needed initialization and then execute + <command>lpf</command>.</para> + + <indexterm><primary>page accounting</primary></indexterm> + <indexterm> + <primary>accounting</primary> + <secondary>printer</secondary> + </indexterm> + <para>In order for <command>lpf</command> to do page accounting + correctly, it needs correct values filled in for the + <literal>pw</literal> and <literal>pl</literal> capabilities in the + <filename>/etc/printcap</filename> file. It uses these values to + determine how much text can fit on a page and how many pages were in + a user's job. For more information on printer accounting, see <link + linkend="printing-advanced-acct">Accounting for Printer + Usage</link>.</para> + </sect3> + </sect2> + + <sect2 id="printing-advanced-header-pages"> + <title>Header Pages</title> + + <para>If you have <emphasis>lots</emphasis> of users, all of them using + various printers, then you probably want to consider <emphasis>header + pages</emphasis> as a necessary evil.</para> + + <indexterm> + <primary>banner pages</primary> + <see>header pages</see> + </indexterm> + <indexterm><primary>header pages</primary></indexterm> + <para>Header pages, also known as <emphasis>banner</emphasis> or + <emphasis>burst pages</emphasis> identify to whom jobs belong after + they are printed. They are usually printed in large, bold letters, + perhaps with decorative borders, so that in a stack of printouts they + stand out from the real documents that comprise users' jobs. They + enable users to locate their jobs quickly. The obvious drawback to a + header page is that it is yet one more sheet that has to be printed + for every job, their ephemeral usefulness lasting not more than a few + minutes, ultimately finding themselves in a recycling bin or rubbish + heap. (Note that header pages go with each job, not each file in a + job, so the paper waste might not be that bad.)</para> + + <para>The <application>LPD</application> system can provide header + pages automatically for your + printouts <emphasis>if</emphasis> your printer can directly print + plain text. If you have a &postscript; printer, you will need an + external program to generate the header page; see <link + linkend="printing-advanced-header-pages-ps">Header Pages on + &postscript; Printers</link>.</para> + + <sect3 id="printing-advanced-header-pages-enabling"> + <title>Enabling Header Pages</title> + + <para>In the <link linkend="printing-simple">Simple Printer + Setup</link> section, we turned off header pages by specifying + <literal>sh</literal> (meaning <quote>suppress header</quote>) in + the <filename>/etc/printcap</filename> file. To enable header + pages for a printer, just remove the <literal>sh</literal> + capability.</para> + + <para>Sounds too easy, right?</para> + + <para>You are right. You <emphasis>might</emphasis> have to provide + an output filter to send initialization strings to the printer. + Here is an example output filter for Hewlett Packard PCL-compatible + printers:</para> + + <programlisting>#!/bin/sh +# +# hpof - Output filter for Hewlett Packard PCL-compatible printers +# Installed in /usr/local/libexec/hpof + +printf "\033&k2G" || exit 2 +exec /usr/libexec/lpr/lpf</programlisting> + + <para>Specify the path to the output filter in the + <literal>of</literal> capability. See the <link + linkend="printing-advanced-of">Output Filters</link> section for + more information.</para> + + <para>Here is an example <filename>/etc/printcap</filename> file for + the printer <literal>teak</literal> that we introduced earlier; we + enabled header pages and added the above output filter:</para> + + <programlisting># +# /etc/printcap for host orchid +# +teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\ + :if=<filename>/usr/local/libexec/hpif</filename>:\ + :vf=<filename>/usr/local/libexec/hpvf</filename>:\ + :of=<filename>/usr/local/libexec/hpof</filename>:</programlisting> + + <para>Now, when users print jobs to <literal>teak</literal>, they get + a header page with each job. If users want to spend time searching + for their printouts, they can suppress header pages by submitting + the job with <command>lpr <option>-h</option></command>; see the + <link linkend="printing-lpr-options-misc">Header Page Options</link> + section for more &man.lpr.1; options.</para> + + <note> + <para><application>LPD</application> prints a form feed character + after the header page. If your printer uses a different character + or sequence of characters to eject a page, specify them with the + <literal>ff</literal> capability in + <filename>/etc/printcap</filename>.</para> + </note> + </sect3> + + <sect3 id="printing-advanced-header-pages-controlling"> + <title>Controlling Header Pages</title> + + <para>By enabling header pages, <application>LPD</application> will + produce a <emphasis>long header</emphasis>, a full page of large + letters identifying the user, host, and job. Here is an example + (<username>kelly</username> printed the job named + <quote>outline</quote> from host <hostid>rose</hostid>):</para> + + <screen> k ll ll + k l l + k l l + k k eeee l l y y + k k e e l l y y + k k eeeeee l l y y + kk k e l l y y + k k e e l l y yy + k k eeee lll lll yyy y + y + y y + yyyy + + + ll + t l i + t l + oooo u u ttttt l ii n nnn eeee + o o u u t l i nn n e e + o o u u t l i n n eeeeee + o o u u t l i n n e + o o u uu t t l i n n e e + oooo uuu u tt lll iii n n eeee + + + + + + + + + + r rrr oooo ssss eeee + rr r o o s s e e + r o o ss eeeeee + r o o ss e + r o o s s e e + r oooo ssss eeee + + + + + + + + Job: outline + Date: Sun Sep 17 11:04:58 1995</screen> + + <para><application>LPD</application> appends a form feed after this + text so the job starts on a new page (unless you have + <literal>sf</literal> (suppress form feeds) in the destination + printer's entry in <filename>/etc/printcap</filename>).</para> + + <para>If you prefer, <application>LPD</application> can make a + <emphasis>short header</emphasis>; specify <literal>sb</literal> + (short banner) in the <filename>/etc/printcap</filename> file. The + header page will look like this:</para> + + <screen>rose:kelly Job: outline Date: Sun Sep 17 11:07:51 1995</screen> + + <para>Also by default, <application>LPD</application> prints the + header page first, then the job. To reverse that, specify + <literal>hl</literal> (header last) in + <filename>/etc/printcap</filename>.</para> + </sect3> + + <sect3 id="printing-advanced-header-pages-accounting"> + <title>Accounting for Header Pages</title> + + <para>Using <application>LPD</application>'s built-in header pages + enforces a particular paradigm when it comes to printer accounting: + header pages must be <emphasis>free of charge</emphasis>.</para> + + <para>Why?</para> + + <para>Because the output filter is the only external program that will + have control when the header page is printed that could do + accounting, and it is not provided with any <emphasis>user or + host</emphasis> information or an accounting file, so it has no + idea whom to charge for printer use. It is also not enough to just + <quote>increase the page count by one</quote> by modifying the text + filter or any of the conversion filters (which do have user and host + information) since users can suppress header pages with + <command>lpr <option>-h</option></command>. They could still be + charged for header pages they did not print. Basically, + <command>lpr <option>-h</option></command> will be the preferred + option of environmentally-minded users, but you cannot offer any + incentive to use it.</para> + + <para>It is <emphasis>still not enough</emphasis> to have each of the + filters generate their own header pages (thereby being able to + charge for them). If users wanted the option of suppressing the + header pages with <command>lpr <option>-h</option></command>, they + will still get them and be charged for them since + <application>LPD</application> does not pass any knowledge + of the <option>-h</option> option to any of the filters.</para> + + <para>So, what are your options?</para> + + <para>You can:</para> + + <itemizedlist> + <listitem> + <para>Accept <application>LPD</application>'s paradigm and make + header pages free.</para> + </listitem> + + <listitem> + <para>Install an alternative to <application>LPD</application>, + such as <application>LPRng</application>. Section + <link linkend="printing-lpd-alternatives">Alternatives to the + Standard Spooler</link> tells more about other spooling + software you can substitute for <application>LPD</application>. + </para> + </listitem> + + <listitem> + <para>Write a <emphasis>smart</emphasis> output filter. Normally, + an output filter is not meant to do anything more than + initialize a printer or do some simple character conversion. It + is suited for header pages and plain text jobs (when there is no + text (input) filter). But, if there is a text filter for the + plain text jobs, then <application>LPD</application> will start + the output filter only for the header pages. And the output + filter can parse the header page text that + <application>LPD</application> generates to determine what user + and host to charge for the header page. The only other problem + with this method is that the output filter still does not know + what accounting file to use (it is not passed the name of the + file from the <literal>af</literal> capability), but if you have + a well-known accounting file, you can hard-code that into the + output filter. To facilitate the parsing step, use the + <literal>sh</literal> (short header) capability in + <filename>/etc/printcap</filename>. Then again, all that might + be too much trouble, and users will certainly appreciate the + more generous system administrator who makes header pages + free.</para> + </listitem> + </itemizedlist> + </sect3> + + <sect3 id="printing-advanced-header-pages-ps"> + <title>Header Pages on &postscript; Printers</title> + + <para>As described above, <application>LPD</application> can generate + a plain text header page suitable for many printers. Of course, + &postscript; cannot directly print plain text, so the header page + feature of <application>LPD</application> is useless—or mostly + so.</para> + + <para>One obvious way to get header pages is to have every conversion + filter and the text filter generate the header page. The filters + should use the user and host arguments to generate a suitable + header page. The drawback of this method is that users will always + get a header page, even if they submit jobs with <command>lpr + <option>-h</option></command>.</para> + + <para>Let us explore this method. The following script takes three + arguments (user login name, host name, and job name) and makes a + simple &postscript; header page:</para> + + <programlisting>#!/bin/sh +# +# make-ps-header - make a PostScript header page on stdout +# Installed in /usr/local/libexec/make-ps-header +# + +# +# These are PostScript units (72 to the inch). Modify for A4 or +# whatever size paper you are using: +# +page_width=612 +page_height=792 +border=72 + +# +# Check arguments +# +if [ $# -ne 3 ]; then + echo "Usage: `basename $0` <user> <host> <job>" 1>&2 + exit 1 +fi + +# +# Save these, mostly for readability in the PostScript, below. +# +user=$1 +host=$2 +job=$3 +date=`date` + +# +# Send the PostScript code to stdout. +# +exec cat <<EOF +%!PS + +% +% Make sure we do not interfere with user's job that will follow +% +save + +% +% Make a thick, unpleasant border around the edge of the paper. +% +$border $border moveto +$page_width $border 2 mul sub 0 rlineto +0 $page_height $border 2 mul sub rlineto +currentscreen 3 -1 roll pop 100 3 1 roll setscreen +$border 2 mul $page_width sub 0 rlineto closepath +0.8 setgray 10 setlinewidth stroke 0 setgray + +% +% Display user's login name, nice and large and prominent +% +/Helvetica-Bold findfont 64 scalefont setfont +$page_width ($user) stringwidth pop sub 2 div $page_height 200 sub moveto +($user) show + +% +% Now show the boring particulars +% +/Helvetica findfont 14 scalefont setfont +/y 200 def +[ (Job:) (Host:) (Date:) ] { +200 y moveto show /y y 18 sub def } +forall + +/Helvetica-Bold findfont 14 scalefont setfont +/y 200 def +[ ($job) ($host) ($date) ] { + 270 y moveto show /y y 18 sub def +} forall + +% +% That is it +% +restore +showpage +EOF</programlisting> + + <para>Now, each of the conversion filters and the text filter can call + this script to first generate the header page, and then print the + user's job. Here is the DVI conversion filter from earlier in this + document, modified to make a header page:</para> + + <programlisting>#!/bin/sh +# +# psdf - DVI to PostScript printer filter +# Installed in /usr/local/libexec/psdf +# +# Invoked by lpd when user runs lpr -d +# + +orig_args="$@" + +fail() { + echo "$@" 1>&2 + exit 2 +} + +while getopts "x:y:n:h:" option; do + case $option in + x|y) ;; # Ignore + n) login=$OPTARG ;; + h) host=$OPTARG ;; + *) echo "LPD started `basename $0` wrong." 1>&2 + exit 2 + ;; + esac +done + +[ "$login" ] || fail "No login name" +[ "$host" ] || fail "No host name" + +( /usr/local/libexec/make-ps-header $login $host "DVI File" + /usr/local/bin/dvips -f ) | eval /usr/local/libexec/lprps $orig_args</programlisting> + + <para>Notice how the filter has to parse the argument list in order to + determine the user and host name. The parsing for the other + conversion filters is identical. The text filter takes a slightly + different set of arguments, though (see section <link + linkend="printing-advanced-filters">How Filters Work</link>).</para> + + <para>As we have mentioned before, the above scheme, though fairly + simple, disables the <quote>suppress header page</quote> option (the + <option>-h</option> option) to <command>lpr</command>. If users + wanted to save a tree (or a few pennies, if you charge for header + pages), they would not be able to do so, since every filter's going + to print a header page with every job.</para> + + <para>To allow users to shut off header pages on a per-job basis, you + will need to use the trick introduced in section <link + linkend="printing-advanced-header-pages-accounting">Accounting for + Header Pages</link>: write an output filter that parses the + LPD-generated header page and produces a &postscript; version. If + the user submits the job with + <command>lpr <option>-h</option></command>, + then <application>LPD</application> will not generate a header page, + and neither will your output filter. Otherwise, your output filter + will read the text from <application>LPD</application> and send + the appropriate header page &postscript; code to the printer.</para> + + <para>If you have a &postscript; printer on a serial line, you can + make use of <command>lprps</command>, which comes with an output + filter, <command>psof</command>, which does the above. Note that + <command>psof</command> does not charge for header pages.</para> + </sect3> + </sect2> + + <sect2 id="printing-advanced-network-printers"> + <title>Networked Printing</title> + + <indexterm> + <primary>printers</primary> + <secondary>network</secondary> + </indexterm> + <indexterm><primary>network printing</primary></indexterm> + <para>&os; supports networked printing: sending jobs to remote + printers. Networked printing generally refers to two different + things:</para> + + <itemizedlist> + <listitem> + <para>Accessing a printer attached to a remote host. You install a + printer that has a conventional serial or parallel interface on + one host. Then, you set up <application>LPD</application> to + enable access to the printer from other hosts on the network. + Section <link linkend="printing-advanced-network-rm">Printers + Installed on Remote Hosts</link> tells how to do this.</para> + </listitem> + + <listitem> + <para>Accessing a printer attached directly to a network. The + printer has a network interface in addition to (or in place of) a + more conventional serial or parallel interface. Such a printer + might work as follows:</para> + + <itemizedlist> + <listitem> + <para>It might understand the <application>LPD</application> + protocol and can even queue + jobs from remote hosts. In this case, it acts just like a + regular host running <application>LPD</application>. Follow + the same procedure in section <link + linkend="printing-advanced-network-rm">Printers Installed on + Remote Hosts</link> to set up such a printer.</para> + </listitem> + + <listitem> + <para>It might support a data stream network connection. In + this case, you <quote>attach</quote> the printer to one host + on the network by making that host responsible for spooling + jobs and sending them to the printer. Section <link + linkend="printing-advanced-network-net-if">Printers with + Networked Data Stream Interfaces</link> gives some + suggestions on installing such printers.</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + + <sect3 id="printing-advanced-network-rm"> + <title>Printers Installed on Remote Hosts</title> + + <para>The <application>LPD</application> spooling system has built-in + support for sending jobs to other hosts also running + <application>LPD</application> (or are compatible with + <application>LPD</application>). This feature enables you to + install a printer on one host and make it accessible from other + hosts. It also works with printers that have network interfaces + that understand the <application>LPD</application> protocol.</para> + + <para>To enable this kind of remote printing, first install a printer + on one host, the <emphasis>printer host</emphasis>, using the simple + printer setup described in the <link + linkend="printing-simple">Simple Printer Setup</link> section. + Do any advanced setup in <link + linkend="printing-advanced">Advanced Printer Setup</link> that you + need. Make sure to test the printer and see if it works with the + features of <application>LPD</application> you have enabled. + Also ensure that the <emphasis>local host</emphasis> has + authorization to use the <application>LPD</application> service in + the <emphasis>remote host</emphasis> (see <link + linkend="printing-advanced-restricting-remote">Restricting Jobs + from Remote Hosts</link>).</para> + + <indexterm> + <primary>printers</primary> + <secondary>network</secondary> + </indexterm> + <indexterm><primary>network printing</primary></indexterm> + <para>If you are using a printer with a network interface that is + compatible with <application>LPD</application>, then the + <emphasis>printer host</emphasis> in + the discussion below is the printer itself, and the + <emphasis>printer name</emphasis> is the name you configured for the + printer. See the documentation that accompanied your printer and/or + printer-network interface.</para> + + <tip> + <para>If you are using a Hewlett Packard Laserjet then the printer + name <literal>text</literal> will automatically perform the LF to + CRLF conversion for you, so you will not require the + <filename>hpif</filename> script.</para> + </tip> + + <para>Then, on the other hosts you want to have access to the printer, + make an entry in their <filename>/etc/printcap</filename> files with + the following:</para> + + <orderedlist> + <listitem> + <para>Name the entry anything you want. For simplicity, though, + you probably want to use the same name and aliases as on the + printer host.</para> + </listitem> + + <listitem> + <para>Leave the <literal>lp</literal> capability blank, explicitly + (<literal>:lp=:</literal>).</para> + </listitem> + + <listitem> + <para>Make a spooling directory and specify its location in the + <literal>sd</literal> capability. + <application>LPD</application> will store jobs here before they + get sent to the printer host.</para> + </listitem> + + <listitem> + <para>Place the name of the printer host in the + <literal>rm</literal> capability.</para> + </listitem> + + <listitem> + <para>Place the printer name on the <emphasis>printer + host</emphasis> in the <literal>rp</literal> + capability.</para> + </listitem> + </orderedlist> + + <para>That is it. You do not need to list conversion filters, page + dimensions, or anything else in the + <filename>/etc/printcap</filename> file.</para> + + <para>Here is an example. The host <hostid>rose</hostid> has two + printers, <literal>bamboo</literal> and <literal>rattan</literal>. + We will enable users on the host <hostid>orchid</hostid> to print + to those printers. Here is the <filename>/etc/printcap</filename> + file for <hostid>orchid</hostid> (back from section <link + linkend="printing-advanced-header-pages-enabling">Enabling Header + Pages</link>). It already had the entry for the printer + <literal>teak</literal>; we have added entries for the two printers + on the host <hostid>rose</hostid>:</para> + + <programlisting># +# /etc/printcap for host orchid - added (remote) printers on rose +# + +# +# teak is local; it is connected directly to orchid: +# +teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\ + :if=<filename>/usr/local/libexec/ifhp</filename>:\ + :vf=<filename>/usr/local/libexec/vfhp</filename>:\ + :of=<filename>/usr/local/libexec/ofhp</filename>: + +# +# rattan is connected to rose; send jobs for rattan to rose: +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :lp=:rm=rose:rp=rattan:sd=<filename class="directory">/var/spool/lpd/rattan</filename>: + +# +# bamboo is connected to rose as well: +# +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :lp=:rm=rose:rp=bamboo:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:</programlisting> + + <para>Then, we just need to make spooling directories on + <hostid>orchid</hostid>:</para> + + <screen>&prompt.root; <userinput><command>mkdir <option>-p</option> <filename class="directory">/var/spool/lpd/rattan</filename> <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput> +&prompt.root; <userinput><command>chmod 770 <filename class="directory">/var/spool/lpd/rattan</filename> <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput> +&prompt.root; <userinput><command>chown daemon:daemon <filename class="directory">/var/spool/lpd/rattan</filename> <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput></screen> + + <para>Now, users on <hostid>orchid</hostid> can print to + <literal>rattan</literal> and <literal>bamboo</literal>. If, for + example, a user on <hostid>orchid</hostid> typed:</para> + + <screen>&prompt.user; <userinput><command>lpr <option>-P</option> bamboo <option>-d</option> <filename><replaceable>sushi-review.dvi</replaceable></filename></command></userinput></screen> + + <para>the <application>LPD</application> system on + <hostid>orchid</hostid> would copy the job to the spooling directory + <filename class="directory">/var/spool/lpd/bamboo</filename> and + note that it was a DVI job. As soon as the host + <hostid>rose</hostid> has room in its <literal>bamboo</literal> + spooling directory, the two <application>LPD</application>s would + transfer the file to <hostid>rose</hostid>. The file would wait in + <hostid>rose</hostid>'s queue until it was finally printed. It + would be converted from DVI to &postscript; + (since <literal>bamboo</literal> is a &postscript; printer) on + <hostid>rose</hostid>.</para> + </sect3> + + <sect3 id="printing-advanced-network-net-if"> + <title>Printers with Networked Data Stream Interfaces</title> + + <para>Often, when you buy a network interface card for a printer, you + can get two versions: one which emulates a spooler (the more + expensive version), or one which just lets you send data to it as if + you were using a serial or parallel port (the cheaper version). + This section tells how to use the cheaper version. For the more + expensive one, see the previous section <link + linkend="printing-advanced-network-rm">Printers Installed on + Remote Hosts</link>.</para> + + <para>The format of the <filename>/etc/printcap</filename> file lets + you specify what serial or parallel interface to use, and (if you + are using a serial interface), what baud rate, whether to use flow + control, delays for tabs, conversion of newlines, and more. But + there is no way to specify a connection to a printer that is + listening on a TCP/IP or other network port.</para> + + <para>To send data to a networked printer, you need to develop a + communications program that can be called by the text and conversion + filters. Here is one such example: the script + <command>netprint</command> takes all data on standard input and + sends it to a network-attached printer. We specify the hostname of + the printer as the first argument and the port number to which to + connect as the second argument to <command>netprint</command>. Note + that this supports one-way communication only (&os; to printer); + many network printers support two-way communication, and you might + want to take advantage of that (to get printer status, perform + accounting, etc.).</para> + + <programlisting>#!/usr/bin/perl +# +# netprint - Text filter for printer attached to network +# Installed in /usr/local/libexec/netprint +# +$#ARGV eq 1 || die "Usage: $0 <printer-hostname> <port-number>"; + +$printer_host = $ARGV[0]; +$printer_port = $ARGV[1]; + +require 'sys/socket.ph'; + +($ignore, $ignore, $protocol) = getprotobyname('tcp'); +($ignore, $ignore, $ignore, $ignore, $address) + = gethostbyname($printer_host); + +$sockaddr = pack('S n a4 x8', &AF_INET, $printer_port, $address); + +socket(PRINTER, &PF_INET, &SOCK_STREAM, $protocol) + || die "Can't create TCP/IP stream socket: $!"; +connect(PRINTER, $sockaddr) || die "Can't contact $printer_host: $!"; +while (<STDIN>) { print PRINTER; } +exit 0;</programlisting> + + <para>We can then use this script in various filters. Suppose we had + a Diablo 750-N line printer connected to the network. The printer + accepts data to print on port number 5100. The host name of the + printer is <hostid>scrivener</hostid>. Here is the text filter for + the printer:</para> + + <programlisting>#!/bin/sh +# +# diablo-if-net - Text filter for Diablo printer `scrivener' listening +# on port 5100. Installed in /usr/local/libexec/diablo-if-net +# +exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100</programlisting> + </sect3> + </sect2> + + <sect2 id="printing-advanced-restricting"> + <title>Restricting Printer Usage</title> + + <indexterm> + <primary>printers</primary> + <secondary>restricting access to</secondary> + </indexterm> + <para>This section gives information on restricting printer usage. The + <application>LPD</application> system lets you control who can access + a printer, both locally or remotely, whether they can print multiple + copies, how large their jobs can be, and how large the printer queues + can get.</para> + + <sect3 id="printing-advanced-restricting-copies"> + <title>Restricting Multiple Copies</title> + + <para>The <application>LPD</application> system makes it easy for + users to print multiple copies + of a file. Users can print jobs with + <command>lpr <option>-#5</option></command> (for example) and get + five copies of each file in the job. Whether this is a good thing + is up to you.</para> + + <para>If you feel multiple copies cause unnecessary wear and tear on + your printers, you can disable the <option>-#</option> option to + &man.lpr.1; by adding the <literal>sc</literal> capability to the + <filename>/etc/printcap</filename> file. When users submit jobs + with the <option>-#</option> option, they will see:</para> + + <screen>lpr: multiple copies are not allowed</screen> + + <para>Note that if you have set up access to a printer remotely (see + section <link linkend="printing-advanced-network-rm">Printers + Installed on Remote Hosts</link>), you need the + <literal>sc</literal> capability on the remote + <filename>/etc/printcap</filename> files as well, or else users will + still be able to submit multiple-copy jobs by using another + host.</para> + + <para>Here is an example. This is the + <filename>/etc/printcap</filename> file for the host + <hostid>rose</hostid>. The printer <literal>rattan</literal> is + quite hearty, so we will allow multiple copies, but the laser + printer <literal>bamboo</literal> is a bit more delicate, so we will + disable multiple copies by adding the <literal>sc</literal> + capability:</para> + + <programlisting># +# /etc/printcap for host rose - restrict multiple copies on bamboo +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :if=<filename>/usr/local/libexec/if-simple</filename>: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:\ + :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ + :if=<filename>/usr/local/libexec/psif</filename>:\ + :df=<filename>/usr/local/libexec/psdf</filename>:</programlisting> + + <para>Now, we also need to add the <literal>sc</literal> capability on + the host <hostid>orchid</hostid>'s + <filename>/etc/printcap</filename> (and while we are at it, let us + disable multiple copies for the printer + <literal>teak</literal>):</para> + + <programlisting># +# /etc/printcap for host orchid - no multiple copies for local +# printer teak or remote printer bamboo +teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:sc:\ + :if=<filename>/usr/local/libexec/ifhp</filename>:\ + :vf=<filename>/usr/local/libexec/vfhp</filename>:\ + :of=<filename>/usr/local/libexec/ofhp</filename>: + +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :lp=:rm=rose:rp=rattan:sd=<filename class="directory">/var/spool/lpd/rattan</filename>: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :lp=:rm=rose:rp=bamboo:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:</programlisting> + + <para>By using the <literal>sc</literal> capability, we prevent the + use of <command>lpr <option>-#</option></command>, but that still + does not prevent users from running &man.lpr.1; multiple times, or + from submitting the same file multiple times in one job like + this:</para> + + <screen>&prompt.user; <userinput>lpr <filename><replaceable>forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign</replaceable></filename></userinput></screen> + + <para>There are many ways to prevent this abuse (including ignoring + it) which you are free to explore.</para> + </sect3> + + <sect3 id="printing-advanced-restricting-access"> + <title>Restricting Access to Printers</title> + + <para>You can control who can print to what printers by using the + &unix; group mechanism and the <literal>rg</literal> capability in + <filename>/etc/printcap</filename>. Just place the users you want + to have access to a printer in a certain group, and then name that + group in the <literal>rg</literal> capability.</para> + + <para>If users outside the group (including <username>root</username>) + try to print to the controlled printer then they will be greeted + with the following message:</para> + + <screen>lpr: Not a member of the restricted group</screen> + + <para>As with the <literal>sc</literal> (suppress multiple copies) + capability, you need to specify <literal>rg</literal> on remote + hosts that also have access to your printers, if you feel it is + appropriate (see section <link + linkend="printing-advanced-network-rm">Printers Installed on + Remote Hosts</link>).</para> + + <para>For example, we will let anyone access the printer + <literal>rattan</literal>, but only those in group + <groupname>artists</groupname> can use <literal>bamboo</literal>. + Here is the familiar <filename>/etc/printcap</filename> for host + <hostid>rose</hostid>:</para> + + <programlisting># +# /etc/printcap for host rose - restricted group for bamboo +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :if=<filename>/usr/local/libexec/if-simple</filename>: + +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:rg=artists:\ + :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ + :if=<filename>/usr/local/libexec/psif</filename>:\ + :df=<filename>/usr/local/libexec/psdf</filename>:</programlisting> + + <para>Let us leave the other example + <filename>/etc/printcap</filename> file (for the host + <hostid>orchid</hostid>) alone. Of course, anyone on + <hostid>orchid</hostid> can print to <literal>bamboo</literal>. It + might be the case that we only allow certain logins on + <hostid>orchid</hostid> anyway, and want them to have access to the + printer. Or not.</para> + + <note> + <para>There can be only one restricted group per printer.</para> + </note> + </sect3> + + <sect3 id="printing-advanced-restricting-sizes"> + <title>Controlling Sizes of Jobs Submitted</title> + + <indexterm><primary>print jobs</primary></indexterm> + <para>If you have many users accessing the printers, you probably need + to put an upper limit on the sizes of the files users can submit to + print. After all, there is only so much free space on the + filesystem that houses the spooling directories, and you also need + to make sure there is room for the jobs of other users.</para> + + <indexterm> + <primary>print jobs</primary> + <secondary>controlling</secondary> + </indexterm> + <para><application>LPD</application> enables you to limit the maximum + byte size a file in a job can be with the <literal>mx</literal> + capability. The units are in <literal>BUFSIZ</literal> blocks, + which are 1024 bytes. If you put a zero for this capability, there + will be no limit on file size; however, if no <literal>mx</literal> + capability is specified, then a default limit of 1000 blocks will + be used.</para> + + <note> + <para>The limit applies to <emphasis>files</emphasis> in a job, and + <emphasis>not</emphasis> the total job size.</para> + </note> + + <para><application>LPD</application> will not refuse a file that is + larger than the limit you place on a printer. Instead, it will + queue as much of the file up to the limit, which will then get + printed. The rest will be discarded. Whether this is correct + behavior is up for debate.</para> + + <para>Let us add limits to our example printers + <literal>rattan</literal> and <literal>bamboo</literal>. Since + those <groupname>artists</groupname>' &postscript; files tend to be + large, we will limit them to five megabytes. We will put no limit + on the plain text line printer:</para> + + <programlisting># +# /etc/printcap for host rose +# + +# +# No limit on job size: +# +rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:mx#0:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :if=<filename>/usr/local/libexec/if-simple</filename>: + +# +# Limit of five megabytes: +# +bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:rg=artists:mx#5000:\ + :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ + :if=<filename>/usr/local/libexec/psif</filename>:\ + :df=<filename>/usr/local/libexec/psdf</filename>:</programlisting> + + <para>Again, the limits apply to the local users only. If you have + set up access to your printers remotely, remote users will not get + those limits. You will need to specify the <literal>mx</literal> + capability in the remote <filename>/etc/printcap</filename> files as + well. See section <link + linkend="printing-advanced-network-rm">Printers Installed on + Remote Hosts</link> for more information on remote + printing.</para> + + <para>There is another specialized way to limit job sizes from remote + printers; see section <link + linkend="printing-advanced-restricting-remote">Restricting Jobs + from Remote Hosts</link>.</para> + </sect3> + + <sect3 id="printing-advanced-restricting-remote"> + <title>Restricting Jobs from Remote Hosts</title> + + <para>The <application>LPD</application> spooling system provides + several ways to restrict print jobs submitted from remote + hosts:</para> + + <variablelist> + <varlistentry> + <term>Host restrictions</term> + + <listitem> + <para>You can control from which remote hosts a local + <application>LPD</application> accepts requests with the files + <filename>/etc/hosts.equiv</filename> and + <filename>/etc/hosts.lpd</filename>. + <application>LPD</application> checks to see if an + incoming request is from a host listed in either one of these + files. If not, <application>LPD</application> refuses the + request.</para> + + <para>The format of these files is simple: one host name per + line. Note that the file + <filename>/etc/hosts.equiv</filename> is also used by the + &man.ruserok.3; protocol, and affects programs like + &man.rsh.1; and &man.rcp.1;, so be careful.</para> + + <para>For example, here is the + <filename>/etc/hosts.lpd</filename> file on the host + <hostid>rose</hostid>:</para> + + <programlisting>orchid +violet +madrigal.fishbaum.de</programlisting> + + <para>This means <hostid>rose</hostid> will accept requests from + the hosts <hostid>orchid</hostid>, <hostid>violet</hostid>, + and <hostid role="fqdn">madrigal.fishbaum.de</hostid>. If any + other host tries to access <hostid>rose</hostid>'s + <application>LPD</application>, the job will be + refused.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Size restrictions</term> + + <listitem> + <para>You can control how much free space there needs to remain + on the filesystem where a spooling directory resides. Make a + file called <filename>minfree</filename> in the spooling + directory for the local printer. Insert in that file a number + representing how many disk blocks (512 bytes) of free space + there has to be for a remote job to be accepted.</para> + + <para>This lets you insure that remote users will not fill your + filesystem. You can also use it to give a certain priority to + local users: they will be able to queue jobs long after the + free disk space has fallen below the amount specified in the + <filename>minfree</filename> file.</para> + + <para>For example, let us add a <filename>minfree</filename> + file for the printer <literal>bamboo</literal>. We examine + <filename>/etc/printcap</filename> to find the spooling + directory for this printer; here is + <literal>bamboo</literal>'s entry:</para> + + <programlisting>bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ + :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:rg=artists:mx#5000:\ + :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:mx#5000:\ + :if=<filename>/usr/local/libexec/psif</filename>:\ + :df=<filename>/usr/local/libexec/psdf</filename>:</programlisting> + + <para>The spooling directory is given in the + <literal>sd</literal> capability. We will make three + megabytes (which is 6144 disk blocks) the amount of free disk + space that must exist on the filesystem for + <application>LPD</application> to accept remote jobs:</para> + + <screen>&prompt.root; <userinput><command>echo 6144 > <filename>/var/spool/lpd/bamboo/minfree</filename></command></userinput></screen> + </listitem> + </varlistentry> + + <varlistentry> + <term>User restrictions</term> + + <listitem> + <para>You can control which remote users can print to local + printers by specifying the <literal>rs</literal> capability in + <filename>/etc/printcap</filename>. When + <literal>rs</literal> appears in the entry for a + locally-attached printer, <application>LPD</application> will + accept jobs from remote hosts <emphasis>if</emphasis> the user + submitting the job also has an account of the same login name + on the local host. Otherwise, <application>LPD</application> + refuses the job.</para> + + <para>This capability is particularly useful in an environment + where there are (for example) different departments sharing a + network, and some users transcend departmental boundaries. By + giving them accounts on your systems, they can use your + printers from their own departmental systems. If you would + rather allow them to use <emphasis>only</emphasis> your + printers and not your computer resources, you can give them + <quote>token</quote> accounts, with no home directory and a + useless shell like <filename>/usr/bin/false</filename>.</para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + </sect2> + + <sect2 id="printing-advanced-acct"> + <title>Accounting for Printer Usage</title> + + <indexterm> + <primary>accounting</primary> + <secondary>printer</secondary> + </indexterm> + <para>So, you need to charge for printouts. And why not? Paper and ink + cost money. And then there are maintenance costs—printers are + loaded with moving parts and tend to break down. You have examined + your printers, usage patterns, and maintenance fees and have come up + with a per-page (or per-foot, per-meter, or per-whatever) cost. Now, + how do you actually start accounting for printouts?</para> + + <para>Well, the bad news is the <application>LPD</application> spooling + system does not provide much help in this department. Accounting is + highly dependent on the kind of printer in use, the formats being + printed, and <emphasis>your</emphasis> requirements in charging for + printer usage.</para> + + <para>To implement accounting, you have to modify a printer's text + filter (to charge for plain text jobs) and the conversion filters (to + charge for other file formats), to count pages or query the printer + for pages printed. You cannot get away with using the simple output + filter, since it cannot do accounting. See section <link + linkend="printing-advanced-filter-intro">Filters</link>.</para> + + <para>Generally, there are two ways to do accounting:</para> + + <itemizedlist> + <listitem> + <para><emphasis>Periodic accounting</emphasis> is the more common + way, possibly because it is easier. Whenever someone prints a + job, the filter logs the user, host, and number of pages to an + accounting file. Every month, semester, year, or whatever time + period you prefer, you collect the accounting files for the + various printers, tally up the pages printed by users, and charge + for usage. Then you truncate all the logging files, starting with + a clean slate for the next period.</para> + </listitem> + + <listitem> + <para><emphasis>Timely accounting</emphasis> is less common, + probably because it is more difficult. This method has the + filters charge users for printouts as soon as they use the + printers. Like disk quotas, the accounting is immediate. You can + prevent users from printing when their account goes in the red, + and might provide a way for users to check and adjust their + <quote>print quotas</quote>. But this method requires some + database code to track users and their quotas.</para> + </listitem> + </itemizedlist> + + <para>The <application>LPD</application> spooling system supports both + methods easily: since you have to provide the filters (well, most of + the time), you also have to provide the accounting code. But there + is a bright side: you have enormous flexibility in your accounting + methods. For example, you choose whether to use periodic or timely + accounting. You choose what information to log: user names, host + names, job types, pages printed, square footage of paper used, how + long the job took to print, and so forth. And you do so by modifying + the filters to save this information.</para> + + <sect3> + <title>Quick and Dirty Printer Accounting</title> + + <para>&os; comes with two programs that can get you set up with + simple periodic accounting right away. They are the text filter + <command>lpf</command>, described in section <link + linkend="printing-advanced-lpf">lpf: a Text Filter</link>, and + &man.pac.8;, a program to gather and total entries from printer + accounting files.</para> + + <para>As mentioned in the section on filters (<link + linkend="printing-advanced-filters">Filters</link>), + <application>LPD</application> starts the text and the conversion + filters with the name of the accounting file to use on the filter + command line. The filters can use this argument to know where to + write an accounting file entry. The name of this file comes from + the <literal>af</literal> capability in + <filename>/etc/printcap</filename>, and if not specified as an + absolute path, is relative to the spooling directory.</para> + + <para><application>LPD</application> starts <command>lpf</command> + with page width and length + arguments (from the <literal>pw</literal> and <literal>pl</literal> + capabilities). The <command>lpf</command> filter uses these + arguments to determine how much paper will be used. After sending + the file to the printer, it then writes an accounting entry in the + accounting file. The entries look like this:</para> + + <programlisting>2.00 rose:andy +3.00 rose:kelly +3.00 orchid:mary +5.00 orchid:mary +2.00 orchid:zhang</programlisting> + + <para>You should use a separate accounting file for each printer, as + <command>lpf</command> has no file locking logic built into it, and + two <command>lpf</command>s might corrupt each other's entries if + they were to write to the same file at the same time. An easy way + to insure a separate accounting file for each printer is to use + <literal>af=acct</literal> in <filename>/etc/printcap</filename>. + Then, each accounting file will be in the spooling directory for a + printer, in a file named <filename>acct</filename>.</para> + + <para>When you are ready to charge users for printouts, run the + &man.pac.8; program. Just change to the spooling directory for + the printer you want to collect on and type <command>pac</command>. + You will get a dollar-centric summary like the following:</para> + + <screen> Login pages/feet runs price +orchid:kelly 5.00 1 $ 0.10 +orchid:mary 31.00 3 $ 0.62 +orchid:zhang 9.00 1 $ 0.18 +rose:andy 2.00 1 $ 0.04 +rose:kelly 177.00 104 $ 3.54 +rose:mary 87.00 32 $ 1.74 +rose:root 26.00 12 $ 0.52 + +total 337.00 154 $ 6.74</screen> + + <para>These are the arguments &man.pac.8; expects:</para> + + <variablelist> + <varlistentry> + <term><option>-P<replaceable>printer</replaceable></option></term> + + <listitem> + <para>Which <replaceable>printer</replaceable> to summarize. + This option works only if there is an absolute path in the + <literal>af</literal> capability in + <filename>/etc/printcap</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-c</option></term> + + <listitem> + <para>Sort the output by cost instead of alphabetically by user + name.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-m</option></term> + + <listitem> + <para>Ignore host name in the accounting files. With this + option, user <username>smith</username> on host + <hostid>alpha</hostid> is the same user + <username>smith</username> on host <hostid>gamma</hostid>. + Without, they are different users.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-p<replaceable>price</replaceable></option></term> + + <listitem> + <para>Compute charges with <replaceable>price</replaceable> + dollars per page or per foot instead of the price from the + <literal>pc</literal> capability in + <filename>/etc/printcap</filename>, or two cents (the + default). You can specify <replaceable>price</replaceable> as + a floating point number.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-r</option></term> + + <listitem> + <para>Reverse the sort order.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-s</option></term> + + <listitem> + <para>Make an accounting summary file and truncate the + accounting file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>name</replaceable> + <replaceable>…</replaceable></term> + + <listitem> + <para>Print accounting information for the given user + <replaceable>names</replaceable> only.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>In the default summary that &man.pac.8; produces, you see the + number of pages printed by each user from various hosts. If, at + your site, host does not matter (because users can use any host), + run <command>pac <option>-m</option></command>, to produce the + following summary:</para> + + <screen> Login pages/feet runs price +andy 2.00 1 $ 0.04 +kelly 182.00 105 $ 3.64 +mary 118.00 35 $ 2.36 +root 26.00 12 $ 0.52 +zhang 9.00 1 $ 0.18 + +total 337.00 154 $ 6.74</screen> + + + <para>To compute the dollar amount due, + &man.pac.8; uses the <literal>pc</literal> capability in the + <filename>/etc/printcap</filename> file (default of 200, or 2 cents + per page). Specify, in hundredths of cents, the price per page or + per foot you want to charge for printouts in this capability. You + can override this value when you run &man.pac.8; with the + <option>-p</option> option. The units for the <option>-p</option> + option are in dollars, though, not hundredths of cents. For + example,</para> + + <screen>&prompt.root; <userinput><command>pac <option>-p1.50</option></command></userinput></screen> + + <para>makes each page cost one dollar and fifty cents. You can really + rake in the profits by using this option.</para> + + <para>Finally, running <command>pac <option>-s</option></command> will + save the summary information in a summary accounting file, which is + named the same as the printer's accounting file, but with + <literal>_sum</literal> appended to the name. It then truncates the + accounting file. When you run &man.pac.8; again, it rereads the + summary file to get starting totals, then adds information from the + regular accounting file.</para> + </sect3> + + <sect3> + <title>How Can You Count Pages Printed?</title> + + <para>In order to perform even remotely accurate accounting, you need + to be able to determine how much paper a job uses. This is the + essential problem of printer accounting.</para> + + <para>For plain text jobs, the problem is not that hard to solve: you + count how many lines are in a job and compare it to how many lines + per page your printer supports. Do not forget to take into account + backspaces in the file which overprint lines, or long logical lines + that wrap onto one or more additional physical lines.</para> + + <para>The text filter <command>lpf</command> (introduced in <link + linkend="printing-advanced-lpf">lpf: a Text Filter</link>) takes + into account these things when it does accounting. If you are + writing a text filter which needs to do accounting, you might want + to examine <command>lpf</command>'s source code.</para> + + <para>How do you handle other file formats, though?</para> + + <para>Well, for DVI-to-LaserJet or DVI-to-&postscript; conversion, you + can have your filter parse the diagnostic output of + <command>dvilj</command> or <command>dvips</command> and look to see + how many pages were converted. You might be able to do similar + things with other file formats and conversion programs.</para> + + <para>But these methods suffer from the fact that the printer may not + actually print all those pages. For example, it could jam, run out + of toner, or explode—and the user would still get + charged.</para> + + <para>So, what can you do?</para> + + <para>There is only one <emphasis>sure</emphasis> way to do + <emphasis>accurate</emphasis> accounting. Get a printer that can + tell you how much paper it uses, and attach it via a serial line or + a network connection. Nearly all &postscript; printers support this + notion. Other makes and models do as well (networked Imagen laser + printers, for example). Modify the filters for these printers to + get the page usage after they print each job and have them log + accounting information based on that value + <emphasis>only</emphasis>. There is no line counting nor + error-prone file examination required.</para> + + <para>Of course, you can always be generous and make all printouts + free.</para> + </sect3> + </sect2> + </sect1> + + <sect1 id="printing-using"> + <title>Using Printers</title> + + <indexterm> + <primary>printers</primary> + <secondary>usage</secondary> + </indexterm> + <para>This section tells you how to use printers you have set up with + &os;. Here is an overview of the user-level commands:</para> + + <variablelist> + <varlistentry> + <term>&man.lpr.1;</term> + + <listitem> + <para>Print jobs</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&man.lpq.1;</term> + + <listitem> + <para>Check printer queues</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>&man.lprm.1;</term> + + <listitem> + <para>Remove jobs from a printer's queue</para> + </listitem> + </varlistentry> + </variablelist> + + <para>There is also an administrative command, &man.lpc.8;, + described in the section <link + linkend="printing-lpc">Administering Printers</link>, used to + control printers and their queues.</para> + + <para>All three of the commands &man.lpr.1;, &man.lprm.1;, and &man.lpq.1; + accept an option + <option>-P <replaceable>printer-name</replaceable></option> to specify + on which printer/queue to operate, as listed in the + <filename>/etc/printcap</filename> file. This enables you to submit, + remove, and check on jobs for various printers. If you do not use the + <option>-P</option> option, then these commands use the printer + specified in the <envar>PRINTER</envar> environment variable. Finally, + if you do not have a <envar>PRINTER</envar> environment variable, these + commands default to the printer named <literal>lp</literal>.</para> + + <para>Hereafter, the terminology <emphasis>default printer</emphasis> + means the printer named in the <envar>PRINTER</envar> environment + variable, or the printer named <literal>lp</literal> when there is no + <envar>PRINTER</envar> environment variable.</para> + + <sect2 id="printing-lpr"> + <title>Printing Jobs</title> + + <para>To print files, type:</para> + + <screen>&prompt.user; <userinput><command>lpr <filename><replaceable>filename</replaceable></filename> <replaceable>...</replaceable></command></userinput></screen> + + <indexterm><primary>printing</primary></indexterm> + <para>This prints each of the listed files to the default printer. If + you list no files, &man.lpr.1; reads data to print from standard + input. For example, this command prints some important system + files:</para> + + <screen>&prompt.user; <userinput><command>lpr <filename>/etc/host.conf</filename> <filename>/etc/hosts.equiv</filename></command></userinput></screen> + + <para>To select a specific printer, type:</para> + + <screen>&prompt.user; <userinput><command>lpr <option>-P</option> <replaceable>printer-name</replaceable> <filename><replaceable>filename</replaceable></filename> <replaceable>...</replaceable></command></userinput></screen> + + <para>This example prints a long listing of the current directory to the + printer named <literal>rattan</literal>:</para> + + <screen>&prompt.user; <userinput><command>ls <option>-l</option> | lpr <option>-P</option> rattan</command></userinput></screen> + + <para>Because no files were listed for the &man.lpr.1; command, + <command>lpr</command> read the data to print from standard input, + which was the output of the <command>ls <option>-l</option></command> + command.</para> + + <para>The &man.lpr.1; command can also accept a wide variety of options + to control formatting, apply file conversions, generate multiple + copies, and so forth. For more information, see the section <link + linkend="printing-lpr-options">Printing Options</link>.</para> + </sect2> + + <sect2 id="printing-lpq"> + <title>Checking Jobs</title> + + <indexterm><primary>print jobs</primary></indexterm> + <para>When you print with &man.lpr.1;, the data you wish to print is put + together in a package called a <quote>print job</quote>, which is sent + to the <application>LPD</application> spooling system. Each printer + has a queue of jobs, and your job waits in that queue along with other + jobs from yourself and from other users. The printer prints those + jobs in a first-come, first-served order.</para> + + <para>To display the queue for the default printer, type &man.lpq.1;. + For a specific printer, use the <option>-P</option> option. For + example, the command + + <screen>&prompt.user; <userinput><command>lpq <option>-P</option> bamboo</command></userinput></screen> + + shows the queue for the printer named <literal>bamboo</literal>. Here + is an example of the output of the <command>lpq</command> + command:</para> + + <screen>bamboo is ready and printing +Rank Owner Job Files Total Size +active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes +2nd kelly 10 (standard input) 1635 bytes +3rd mary 11 ... 78519 bytes</screen> + + <para>This shows three jobs in the queue for <literal>bamboo</literal>. + The first job, submitted by user kelly, got assigned <quote>job + number</quote> 9. Every job for a printer gets a unique job number. + Most of the time you can ignore the job number, but you will need it + if you want to cancel the job; see section <link + linkend="printing-lprm">Removing Jobs</link> for details.</para> + + <para>Job number nine consists of two files; multiple files given on the + &man.lpr.1; command line are treated as part of a single job. It + is the currently active job (note the word <literal>active</literal> + under the <quote>Rank</quote> column), which means the printer should + be currently printing that job. The second job consists of data + passed as the standard input to the &man.lpr.1; command. The third + job came from user <username>mary</username>; it is a much larger + job. The pathname of the file she is trying to print is too long to + fit, so the &man.lpq.1; command just shows three dots.</para> + + <para>The very first line of the output from &man.lpq.1; is also useful: + it tells what the printer is currently doing (or at least what + <application>LPD</application> thinks the printer is doing).</para> + + <para>The &man.lpq.1; command also support a <option>-l</option> option + to generate a detailed long listing. Here is an example of + <command>lpq <option>-l</option></command>:</para> + + <screen>waiting for bamboo to become ready (offline ?) +kelly: 1st [job 009rose] + /etc/host.conf 73 bytes + /etc/hosts.equiv 15 bytes + +kelly: 2nd [job 010rose] + (standard input) 1635 bytes + +mary: 3rd [job 011rose] + /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes</screen> + </sect2> + + <sect2 id="printing-lprm"> + <title>Removing Jobs</title> + + <para>If you change your mind about printing a job, you can remove the + job from the queue with the &man.lprm.1; command. Often, you can + even use &man.lprm.1; to remove an active job, but some or all of the + job might still get printed.</para> + + <para>To remove a job from the default printer, first use + &man.lpq.1; to find the job number. Then type:</para> + + <screen>&prompt.user; <userinput><command>lprm <replaceable>job-number</replaceable></command></userinput></screen> + + <para>To remove the job from a specific printer, add the + <option>-P</option> option. The following command removes job number + 10 from the queue for the printer <literal>bamboo</literal>:</para> + + <screen>&prompt.user; <userinput><command>lprm <option>-P</option> bamboo 10</command></userinput></screen> + + <para>The &man.lprm.1; command has a few shortcuts:</para> + + <variablelist> + <varlistentry> + <term>lprm -</term> + + <listitem> + <para>Removes all jobs (for the default printer) belonging to + you.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>lprm <replaceable>user</replaceable></term> + + <listitem> + <para>Removes all jobs (for the default printer) belonging to + <replaceable>user</replaceable>. The superuser can remove other + users' jobs; you can remove only your own jobs.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>lprm</term> + + <listitem> + <para>With no job number, user name, or <option>-</option> + appearing on the command line, &man.lprm.1; removes the + currently active job on the default printer, if it belongs to + you. The superuser can remove any active job.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Just use the <option>-P</option> option with the above shortcuts + to operate on a specific printer instead of the default. For example, + the following command removes all jobs for the current user in the + queue for the printer named <literal>rattan</literal>:</para> + + <screen>&prompt.user; <userinput><command>lprm <option>-P</option> rattan -</command></userinput></screen> + + <note> + <para>If you are working in a networked environment, &man.lprm.1; will + let you remove jobs only from the host from which the jobs were + submitted, even if the same printer is available from other hosts. + The following command sequence demonstrates this:</para> + + <screen>&prompt.user; <userinput><command>lpr <option>-P</option> rattan <filename><replaceable>myfile</replaceable></filename></command></userinput> +&prompt.user; <userinput><command>rlogin orchid</command></userinput> +&prompt.user; <userinput><command>lpq <option>-P</option> rattan</command></userinput> +Rank Owner Job Files Total Size +active seeyan 12 ... 49123 bytes +2nd kelly 13 myfile 12 bytes +&prompt.user; <userinput><command>lprm <option>-P</option> rattan 13</command></userinput> +rose: Permission denied +&prompt.user; <userinput><command>logout</command></userinput> +&prompt.user; <userinput><command>lprm <option>-P</option> rattan 13</command></userinput> +dfA013rose dequeued +cfA013rose dequeued + </screen> + </note> + </sect2> + + <sect2 id="printing-lpr-options"> + <title>Beyond Plain Text: Printing Options</title> + + <para>The &man.lpr.1; command supports a number of options that control + formatting text, converting graphic and other file formats, producing + multiple copies, handling of the job, and more. This section + describes the options.</para> + + <sect3 id="printing-lpr-options-format"> + <title>Formatting and Conversion Options</title> + + <para>The following &man.lpr.1; options control formatting of the + files in the job. Use these options if the job does not contain + plain text or if you want plain text formatted through the + &man.pr.1; utility.</para> + + <indexterm><primary>&tex;</primary></indexterm> + <para>For example, the following command prints a DVI file (from the + &tex; typesetting system) named + <filename><replaceable>fish-report.dvi</replaceable></filename> + to the printer named <literal>bamboo</literal>:</para> + + <screen>&prompt.user; <userinput><command>lpr <option>-P</option> bamboo -d <filename><replaceable>fish-report.dvi</replaceable></filename></command></userinput></screen> + + <para>These options apply to every file in the job, so you cannot mix + (say) DVI and ditroff files together in a job. Instead, submit the + files as separate jobs, using a different conversion option for each + job.</para> + + <note> + <para>All of these options except <option>-p</option> and + <option>-T</option> require conversion filters installed for the + destination printer. For example, the <option>-d</option> option + requires the DVI conversion filter. Section <link + linkend="printing-advanced-convfilters">Conversion + Filters</link> gives details.</para> + </note> + + <variablelist> + <varlistentry> + <term><option>-c</option></term> + + <listitem> + <para>Print cifplot files.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-d</option></term> + + <listitem> + <para>Print DVI files.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-f</option></term> + + <listitem> + <para>Print FORTRAN text files.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-g</option></term> + + <listitem> + <para>Print plot data.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-i <replaceable>number</replaceable></option></term> + + <listitem> + <para>Indent the output by <replaceable>number</replaceable> + columns; if you omit <replaceable>number</replaceable>, indent + by 8 columns. This option works only with certain conversion + filters.</para> + + <note> + <para>Do not put any space between the <option>-i</option> and + the number.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-l</option></term> + + <listitem> + <para>Print literal text data, including control + characters.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-n</option></term> + + <listitem> + <para>Print ditroff (device independent troff) data.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-p</term> + + <listitem> + <para>Format plain text with &man.pr.1; before printing. See + &man.pr.1; for more information.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-T <replaceable>title</replaceable></option></term> + + <listitem> + <para>Use <replaceable>title</replaceable> on the + &man.pr.1; header instead of the file name. This option has + effect only when used with the <option>-p</option> + option.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-t</option></term> + + <listitem> + <para>Print troff data.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-v</option></term> + + <listitem> + <para>Print raster data.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Here is an example: this command prints a nicely formatted + version of the &man.ls.1; manual page on the default printer:</para> + + <screen>&prompt.user; <userinput><command>zcat <filename>/usr/share/man/man1/ls.1.gz</filename> | troff <option>-t</option> -man | lpr <option>-t</option></command></userinput></screen> + + <para>The &man.zcat.1; command uncompresses the source of the + &man.ls.1; manual page and passes it to the &man.troff.1; + command, which formats that source and makes GNU troff + output and passes it to &man.lpr.1;, which submits the job + to the <application>LPD</application> spooler. Because we + used the <option>-t</option> option to &man.lpr.1;, the spooler will + convert the GNU troff output into a format the default printer can + understand when it prints the job.</para> + </sect3> + + <sect3 id="printing-lpr-options-job-handling"> + <title>Job Handling Options</title> + + <para>The following options to &man.lpr.1; tell + <application>LPD</application> to handle the job + specially:</para> + + <variablelist> + <varlistentry> + <term>-# <replaceable>copies</replaceable></term> + + <listitem> + <para>Produce a number of <replaceable>copies</replaceable> of + each file in the job instead of just one copy. An + administrator may disable this option to reduce printer + wear-and-tear and encourage photocopier usage. See section + <link + linkend="printing-advanced-restricting-copies">Restricting + Multiple Copies</link>.</para> + + <para>This example prints three copies of + <filename><replaceable>parser.c</replaceable></filename> + followed by three copies of + <filename><replaceable>parser.h</replaceable></filename> + to the default printer:</para> + + <screen>&prompt.user; <userinput><command>lpr <option>-#3</option> <filename><replaceable>parser.c parser.h</replaceable></filename></command></userinput></screen> + </listitem> + </varlistentry> + + <varlistentry> + <term>-m</term> + + <listitem> + <para>Send mail after completing the print job. With this + option, the <application>LPD</application> system will send + mail to your account when it finishes handling your job. In + its message, it will tell you if the job completed + successfully or if there was an error, and (often) what the + error was.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-s</term> + + <listitem> + <para>Do not copy the files to the spooling directory, but make + symbolic links to them instead.</para> + + <para>If you are printing a large job, you probably want to use + this option. It saves space in the spooling directory (your + job might overflow the free space on the filesystem where the + spooling directory resides). It saves time as well since + <application>LPD</application> will not have to copy each and + every byte of your job to the spooling directory.</para> + + <para>There is a drawback, though: since + <application>LPD</application> will refer to the + original files directly, you cannot modify or remove them + until they have been printed.</para> + + <note> + <para>If you are printing to a remote printer, + <application>LPD</application> will eventually have to copy + files from the local host to the remote host, so the + <option>-s</option> option will save space only on the local + spooling directory, not the remote. It is still useful, + though.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>-r</term> + + <listitem> + <para>Remove the files in the job after copying them to the + spooling directory, or after printing them with the + <option>-s</option> option. Be careful with this + option!</para> + </listitem> + </varlistentry> + </variablelist> + </sect3> + + <sect3 id="printing-lpr-options-misc"> + <title>Header Page Options</title> + + <para>These options to &man.lpr.1; adjust the text that normally + appears on a job's header page. If header pages are suppressed for + the destination printer, these options have no effect. See section + <link linkend="printing-advanced-header-pages">Header Pages</link> + for information about setting up header pages.</para> + + <variablelist> + <varlistentry> + <term>-C <replaceable>text</replaceable></term> + + <listitem> + <para>Replace the hostname on the header page with + <replaceable>text</replaceable>. The hostname is normally the + name of the host from which the job was submitted.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-J <replaceable>text</replaceable></term> + + <listitem> + <para>Replace the job name on the header page with + <replaceable>text</replaceable>. The job name is normally the + name of the first file of the job, or + <filename>stdin</filename> if you are printing standard + input.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>-h</term> + + <listitem> + <para>Do not print any header page.</para> + + <note> + <para>At some sites, this option may have no effect due to the + way header pages are generated. See <link + linkend="printing-advanced-header-pages">Header + Pages</link> for details.</para> + </note> + </listitem> + </varlistentry> + </variablelist> + </sect3> + </sect2> + + <sect2 id="printing-lpc"> + <title>Administering Printers</title> + + <para>As an administrator for your printers, you have had to install, + set up, and test them. Using the &man.lpc.8; command, you + can interact with your printers in yet more ways. With &man.lpc.8;, + you can</para> + + <itemizedlist> + <listitem> + <para>Start and stop the printers</para> + </listitem> + + <listitem> + <para>Enable and disable their queues</para> + </listitem> + + <listitem> + <para>Rearrange the order of the jobs in each queue.</para> + </listitem> + </itemizedlist> + + <para>First, a note about terminology: if a printer is + <emphasis>stopped</emphasis>, it will not print anything in its queue. + Users can still submit jobs, which will wait in the queue until the + printer is <emphasis>started</emphasis> or the queue is + cleared.</para> + + <para>If a queue is <emphasis>disabled</emphasis>, no user (except + <username>root</username>) can submit jobs for the printer. An + <emphasis>enabled</emphasis> queue allows jobs to be submitted. A + printer can be <emphasis>started</emphasis> for a disabled queue, in + which case it will continue to print jobs in the queue until the queue + is empty.</para> + + <para>In general, you have to have <username>root</username> privileges + to use the &man.lpc.8; command. Ordinary users can use the + &man.lpc.8; command to get printer status and to restart a hung + printer only.</para> + + <para>Here is a summary of the &man.lpc.8; commands. Most of the + commands take a <replaceable>printer-name</replaceable> argument to + tell on which printer to operate. You can use <literal>all</literal> + for the <replaceable>printer-name</replaceable> to mean all printers + listed in <filename>/etc/printcap</filename>.</para> + + <variablelist> + <varlistentry> + <term><command>abort + <replaceable>printer-name</replaceable></command></term> + + <listitem> + <para>Cancel the current job and stop the printer. Users can + still submit jobs if the queue is enabled.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>clean + <replaceable>printer-name</replaceable></command></term> + + <listitem> + <para>Remove old files from the printer's spooling directory. + Occasionally, the files that make up a job are not properly + removed by <application>LPD</application>, particularly if + there have been errors during printing or a lot of + administrative activity. This command finds files that do not + belong in the spooling directory and removes them.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>disable + <replaceable>printer-name</replaceable></command></term> + + <listitem> + <para>Disable queuing of new jobs. If the printer is running, it + will continue to print any jobs remaining in the queue. The + superuser (<username>root</username>) can always submit jobs, + even to a disabled queue.</para> + + <para>This command is useful while you are testing a new printer + or filter installation: disable the queue and submit jobs as + <username>root</username>. Other users will not be able to + submit jobs until you complete your testing and re-enable the + queue with the <command>enable</command> command.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>down <replaceable>printer-name</replaceable> + <replaceable>message</replaceable></command></term> + + <listitem> + <para>Take a printer down. Equivalent to + <command>disable</command> followed by <command>stop</command>. + The <replaceable>message</replaceable> appears as the printer's + status whenever a user checks the printer's queue with + &man.lpq.1; or status with <command>lpc status</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>enable + <replaceable>printer-name</replaceable></command></term> + + <listitem> + <para>Enable the queue for a printer. Users can submit jobs but + the printer will not print anything until it is started.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>help + <replaceable>command-name</replaceable></command></term> + + <listitem> + <para>Print help on the command + <replaceable>command-name</replaceable>. With no + <replaceable>command-name</replaceable>, print a summary of the + commands available.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>restart + <replaceable>printer-name</replaceable></command></term> + + <listitem> + <para>Start the printer. Ordinary users can use this command if + some extraordinary circumstance hangs + <application>LPD</application>, but they cannot start + a printer stopped with either the <command>stop</command> or + <command>down</command> commands. The + <command>restart</command> command is equivalent to + <command>abort</command> followed by + <command>start</command>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>start + <replaceable>printer-name</replaceable></command></term> + + <listitem> + <para>Start the printer. The printer will print jobs in its + queue.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>stop + <replaceable>printer-name</replaceable></command></term> + + <listitem> + <para>Stop the printer. The printer will finish the current job + and will not print anything else in its queue. Even though the + printer is stopped, users can still submit jobs to an enabled + queue.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>topq <replaceable>printer-name</replaceable> + <replaceable>job-or-username</replaceable></command></term> + + <listitem> + <para>Rearrange the queue for + <replaceable>printer-name</replaceable> by placing the jobs with + the listed <replaceable>job</replaceable> numbers or the jobs + belonging to <replaceable>username</replaceable> at the top of + the queue. For this command, you cannot use + <literal>all</literal> as the + <replaceable>printer-name</replaceable>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>up + <replaceable>printer-name</replaceable></command></term> + + <listitem> + <para>Bring a printer up; the opposite of the + <command>down</command> command. Equivalent to + <command>start</command> followed by + <command>enable</command>.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>&man.lpc.8; accepts the above commands on the command line. If + you do not enter any commands, &man.lpc.8; enters an interactive mode, + where you can enter commands until you type <command>exit</command>, + <command>quit</command>, or end-of-file.</para> + </sect2> + </sect1> + + <sect1 id="printing-lpd-alternatives"> + <title>Alternatives to the Standard Spooler</title> + + <para>If you have been reading straight through this manual, by now you + have learned just about everything there is to know about the + <application>LPD</application> spooling system that comes with &os;. + You can probably appreciate many of its shortcomings, which naturally + leads to the question: <quote>What other spooling systems are out there + (and work with &os;)?</quote></para> + + <variablelist> + <varlistentry> + <term>LPRng</term> + + <indexterm><primary>LPRng</primary></indexterm> + <listitem> + <para><application>LPRng</application>, which purportedly means + <quote>LPR: the Next Generation</quote> is a complete rewrite of + PLP. Patrick Powell and Justin Mason (the principal maintainer + of PLP) collaborated to make <application>LPRng</application>. + The main site for <application>LPRng</application> is <ulink + url="http://www.lprng.org/"></ulink>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>CUPS</term> + + <indexterm><primary>CUPS</primary></indexterm> + <listitem> + <para><application>CUPS</application>, the Common UNIX Printing + System, provides a portable printing layer for &unix;-based + operating systems. It has been developed by Easy Software + Products to promote a standard printing solution for all &unix; + vendors and users.</para> + + <para><application>CUPS</application> uses the Internet Printing + Protocol (<acronym>IPP</acronym>) as the basis for managing + print jobs and queues. The Line Printer Daemon + (<acronym>LPD</acronym>), Server Message Block + (<acronym>SMB</acronym>), and AppSocket (aka JetDirect) + protocols are also supported with reduced functionality. CUPS + adds network printer browsing and PostScript Printer Description + (<acronym>PPD</acronym>) based printing options to support + real-world printing under &unix;.</para> + + <para>The main site for <application>CUPS</application> is <ulink + url="http://www.cups.org/"></ulink>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>HPLIP</term> + + <indexterm><primary>HPLIP</primary></indexterm> + <listitem> + <para><application>HPLIP</application>, the HP &linux; Imaging and + Printing system, is an HP-developed suite of programs that + supports printing, scanning and fax facilities for HP appliances. + This suite of programs utilizes + the <application>CUPS</application> printing system as a backend + for some of its printing features.</para> + + <para>The main site for <application>HPLIP</application> + is <ulink url="http://hplipopensource.com/hplip-web/index.html"></ulink>.</para> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1 id="printing-troubleshooting"> + <title>Troubleshooting</title> + + <para>After performing the simple test with &man.lptest.1;, you might + have gotten one of the following results instead of the correct + printout:</para> + + <variablelist> + <varlistentry> + <term>It worked, after awhile; or, it did not eject a full + sheet.</term> + + <listitem> + <para>The printer printed the above, but it sat for awhile and + did nothing. In fact, you might have needed to press a + PRINT REMAINING or FORM FEED button on the printer to get any + results to appear.</para> + + <para>If this is the case, the printer was probably waiting to + see if there was any more data for your job before it printed + anything. To fix this problem, you can have the text filter + send a FORM FEED character (or whatever is necessary) to the + printer. This is usually sufficient to have the printer + immediately print any text remaining in its internal buffer. + It is also useful to make sure each print job ends on a full + sheet, so the next job does not start somewhere on the middle + of the last page of the previous job.</para> + + <para>The following replacement for the shell script + <filename>/usr/local/libexec/if-simple</filename> prints a + form feed after it sends the job to the printer:</para> + + <programlisting>#!/bin/sh +# +# if-simple - Simple text input filter for lpd +# Installed in /usr/local/libexec/if-simple +# +# Simply copies stdin to stdout. Ignores all filter arguments. +# Writes a form feed character (\f) after printing job. + +/bin/cat && printf "\f" && exit 0 +exit 2</programlisting> + </listitem> + </varlistentry> + + <varlistentry> + <term>It produced the <quote>staircase effect.</quote></term> + + <listitem> + <para>You got the following on paper:</para> + + <screen>!"#$%&'()*+,-./01234 + "#$%&'()*+,-./012345 + #$%&'()*+,-./0123456</screen> + + <indexterm><primary>MS-DOS</primary></indexterm> + <indexterm><primary>OS/2</primary></indexterm> + <indexterm><primary>ASCII</primary></indexterm> + <para>You have become another victim of the <emphasis>staircase + effect</emphasis>, caused by conflicting interpretations of + what characters should indicate a new line. &unix; style + operating systems use a single character: ASCII code 10, the + line feed (LF). &ms-dos;, &os2;, and others uses a pair of + characters, ASCII code 10 <emphasis>and</emphasis> ASCII code + 13 (the carriage return or CR). Many printers use the &ms-dos; + convention for representing new-lines.</para> + + <para>When you print with &os;, your text used just the line + feed character. The printer, upon seeing a line feed + character, advanced the paper one line, but maintained the + same horizontal position on the page for the next character + to print. That is what the carriage return is for: to move + the location of the next character to print to the left edge + of the paper.</para> + + <para>Here is what &os; wants your printer to do:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <tbody> + <row> + <entry>Printer received CR</entry> + <entry>Printer prints CR</entry> + </row> + + <row> + <entry>Printer received LF</entry> + <entry>Printer prints CR + LF</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Here are some ways to achieve this:</para> + + <itemizedlist> + <listitem> + <para>Use the printer's configuration switches or control + panel to alter its interpretation of these characters. + Check your printer's manual to find out how to do + this.</para> + + <note> + <para>If you boot your system into other operating systems + besides &os;, you may have to + <emphasis>reconfigure</emphasis> the printer to use a an + interpretation for CR and LF characters that those other + operating systems use. You might prefer one of the other + solutions, below.</para> + </note> + </listitem> + + <listitem> + <para>Have &os;'s serial line driver automatically + convert LF to CR+LF. Of course, this works with printers + on serial ports <emphasis>only</emphasis>. To enable this + feature, use the <literal>ms#</literal> capability and + set the <literal>onlcr</literal> mode + in the <filename>/etc/printcap</filename> file + for the printer.</para> + </listitem> + + <listitem> + <para>Send an <emphasis>escape code</emphasis> to the + printer to have it temporarily treat LF characters + differently. Consult your printer's manual for escape + codes that your printer might support. When you find the + proper escape code, modify the text filter to send the + code first, then send the print job.</para> + + <indexterm><primary>PCL</primary></indexterm> + <para>Here is an example text filter for printers that + understand the Hewlett-Packard PCL escape codes. This + filter makes the printer treat LF characters as a LF and + CR; then it sends the job; then it sends a form feed to + eject the last page of the job. It should work with + nearly all Hewlett Packard printers.</para> + + <programlisting>#!/bin/sh +# +# hpif - Simple text input filter for lpd for HP-PCL based printers +# Installed in /usr/local/libexec/hpif +# +# Simply copies stdin to stdout. Ignores all filter arguments. +# Tells printer to treat LF as CR+LF. Ejects the page when done. + +printf "\033&k2G" && cat && printf "\033&l0H" && exit 0 +exit 2</programlisting> + + <para>Here is an example <filename>/etc/printcap</filename> + from a host called <hostid>orchid</hostid>. It has a single + printer attached to its first parallel port, a Hewlett Packard + LaserJet 3Si named <literal>teak</literal>. It is using the + above script as its text filter:</para> + + <programlisting># +# /etc/printcap for host orchid +# +teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:sh:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\ + :if=<filename>/usr/local/libexec/hpif</filename>:</programlisting> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>It overprinted each line.</term> + + <listitem> + <para>The printer never advanced a line. All of the lines of + text were printed on top of each other on one line.</para> + + <para>This problem is the <quote>opposite</quote> of the + staircase effect, described above, and is much rarer. + Somewhere, the LF characters that &os; uses to end a line + are being treated as CR characters to return the print + location to the left edge of the paper, but not also down a + line.</para> + + <para>Use the printer's configuration switches or control panel + to enforce the following interpretation of LF and CR + characters:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>Printer receives</entry> + <entry>Printer prints</entry> + </row> + </thead> + + <tbody> + <row> + <entry>CR</entry> + <entry>CR</entry> + </row> + + <row> + <entry>LF</entry> + <entry>CR + LF</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </listitem> + </varlistentry> + + <varlistentry> + <term>The printer lost characters.</term> + + <listitem> + <para>While printing, the printer did not print a few characters + in each line. The problem might have gotten worse as the + printer ran, losing more and more characters.</para> + + <para>The problem is that the printer cannot keep up with the + speed at which the computer sends data over a serial line + (this problem should not occur with printers on parallel + ports). There are two ways to overcome the problem:</para> + + <itemizedlist> + <listitem> + <para>If the printer supports XON/XOFF flow control, have + &os; use it by specifying the <literal>ixon</literal> mode + in the <literal>ms#</literal> capability.</para> + </listitem> + + <listitem> + <para>If the printer supports the Request to Send / Clear to + Send hardware handshake (commonly known as + <literal>RTS/CTS</literal>), specify the + <literal>crtscts</literal> mode in the <literal>ms#</literal> + capability. Make sure the cable connecting the printer to the + computer is correctly wired for hardware flow control.</para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + + <varlistentry> + <term>It printed garbage.</term> + + <listitem> + <para>The printer printed what appeared to be random garbage, + but not the desired text.</para> + + <para>This is usually another symptom of incorrect + communications parameters with a serial printer. Double-check + the bps rate in the <literal>br</literal> capability, and the + parity setting in the <literal>ms#</literal> capability; make sure + the printer is using the same settings as specified in the + <filename>/etc/printcap</filename> file.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Nothing happened.</term> + + <listitem> + <para>If nothing happened, the problem is probably within + &os; and not the hardware. Add the log file + (<literal>lf</literal>) capability to the entry for the + printer you are debugging in the + <filename>/etc/printcap</filename> file. For example, here is + the entry for <literal>rattan</literal>, with the + <literal>lf</literal> capability:</para> + + <programlisting>rattan|line|diablo|lp|Diablo 630 Line Printer:\ + :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ + :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :if=<filename>/usr/local/libexec/if-simple</filename>:\ + :lf=<filename>/var/log/rattan.log</filename></programlisting> + + <para>Then, try printing again. Check the log file (in our + example, <filename>/var/log/rattan.log</filename>) to see any + error messages that might appear. Based on the messages you + see, try to correct the problem.</para> + + <para>If you do not specify a <literal>lf</literal> capability, + <application>LPD</application> uses + <filename class="devicefile">/dev/console</filename> as a + default.</para> + </listitem> + </varlistentry> + </variablelist> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/security/Makefile b/en_US.ISO8859-1/books/handbook/security/Makefile new file mode 100644 index 0000000000..bbf01aa7ab --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/security/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= security/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.sgml b/en_US.ISO8859-1/books/handbook/security/chapter.sgml new file mode 100644 index 0000000000..469afb0264 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/security/chapter.sgml @@ -0,0 +1,4154 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="security"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Matthew</firstname> + <surname>Dillon</surname> + <contrib>Much of this chapter has been taken from the + security(7) manual page by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>Security</title> + + <indexterm><primary>security</primary></indexterm> + + <sect1 id="security-synopsis"> + <title>Synopsis</title> + + <para>This chapter will provide a basic introduction to system + security concepts, some general good rules of thumb, and some + advanced topics under &os;. A lot of the topics covered here + can be applied to system and Internet security in general as + well. The Internet is no longer a <quote>friendly</quote> place + in which everyone wants to be your kind neighbor. Securing your + system is imperative to protect your data, intellectual + property, time, and much more from the hands of hackers and the + like.</para> + + <para>&os; provides an array of utilities and mechanisms to ensure + the integrity and security of your system and network.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>Basic system security concepts, in respect to + &os;.</para> + </listitem> + + <listitem> + <para>About the various crypt mechanisms available in &os;, + such as <acronym>DES</acronym> and + <acronym>MD5</acronym>.</para> + </listitem> + + <listitem> + <para>How to set up one-time password authentication.</para> + </listitem> + + <listitem> + <para>How to configure <acronym>TCP</acronym> Wrappers for use + with <application>inetd</application>.</para> + </listitem> + + <listitem> + <para>How to set up <application>Kerberos5</application> on + &os;.</para> + </listitem> + + <listitem> + <para>How to configure IPsec and create a + <acronym>VPN</acronym> between &os;/&windows; + machines.</para> + </listitem> + + <listitem> + <para>How to configure and use + <application>OpenSSH</application>, &os;'s + <acronym>SSH</acronym> implementation.</para> + </listitem> + + <listitem> + <para>What file system <acronym>ACL</acronym>s are and how to + use them.</para> + </listitem> + + <listitem> + <para>How to use the <application>Portaudit</application> + utility to audit third party software packages installed + from the Ports Collection.</para> + </listitem> + + <listitem> + <para>How to utilize the &os; security advisories + publications.</para> + </listitem> + + <listitem> + <para>Have an idea of what Process Accounting is and how to + enable it on &os;.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand basic &os; and Internet concepts.</para> + </listitem> + </itemizedlist> + + <para>Additional security topics are covered throughout this book. + For example, Mandatory Access Control is discussed in <xref + linkend="mac"> and Internet Firewalls are discussed in <xref + linkend="firewalls">.</para> + </sect1> + + <sect1 id="security-intro"> + <title>Introduction</title> + + <para>Security is a function that begins and ends with the system + administrator. While all BSD &unix; multi-user systems have + some inherent security, the job of building and maintaining + additional security mechanisms to keep those users + <quote>honest</quote> is probably one of the single largest + undertakings of the sysadmin. Machines are only as secure as + you make them, and security concerns are ever competing with the + human necessity for convenience. &unix; systems, in general, + are capable of running a huge number of simultaneous processes + and many of these processes operate as servers — meaning + that external entities can connect and talk to them. As + yesterday's mini-computers and mainframes become today's + desktops, and as computers become networked and inter-networked, + security becomes an even bigger issue.</para> + + <para>System security also pertains to dealing with various forms + of attack, including attacks that attempt to crash, or otherwise + make a system unusable, but do not attempt to compromise the + <username>root</username> account (<quote>break root</quote>). + Security concerns can be split up into several + categories:</para> + + <orderedlist> + <listitem> + <para>Denial of service attacks.</para> + </listitem> + + <listitem> + <para>User account compromises.</para> + </listitem> + + <listitem> + <para>Root compromise through accessible servers.</para> + </listitem> + + <listitem> + <para>Root compromise via user accounts.</para> + </listitem> + + <listitem> + <para>Backdoor creation.</para> + </listitem> + </orderedlist> + + <indexterm> + <primary>DoS attacks</primary> + <see>Denial of Service (DoS)</see> + </indexterm> + <indexterm> + <primary>security</primary> + <secondary>DoS attacks</secondary> + <see>Denial of Service (DoS)</see> + </indexterm> + <indexterm><primary>Denial of Service (DoS)</primary></indexterm> + + <para>A denial of service attack is an action that deprives the + machine of needed resources. Typically, DoS attacks are + brute-force mechanisms that attempt to crash or otherwise make a + machine unusable by overwhelming its servers or network stack. + Some DoS attacks try to take advantage of bugs in the networking + stack to crash a machine with a single packet. The latter can + only be fixed by applying a bug fix to the kernel. Attacks on + servers can often be fixed by properly specifying options to + limit the load the servers incur on the system under adverse + conditions. Brute-force network attacks are harder to deal + with. A spoofed-packet attack, for example, is nearly + impossible to stop, short of cutting your system off from the + Internet. It may not be able to take your machine down, but it + can saturate your Internet connection.</para> + + <indexterm> + <primary>security</primary> + <secondary>account compromises</secondary> + </indexterm> + + <para>A user account compromise is even more common than a DoS + attack. Many sysadmins still run standard + <application>telnetd</application>, + <application>rlogind</application>, + <application>rshd</application>, and + <application>ftpd</application> servers on their machines. + These servers, by default, do not operate over encrypted + connections. The result is that if you have any moderate-sized + user base, one or more of your users logging into your system + from a remote location (which is the most common and convenient + way to login to a system) will have his or her password sniffed. + The attentive system admin will analyze his remote access logs + looking for suspicious source addresses even for successful + logins.</para> + + <para>One must always assume that once an attacker has access to a + user account, the attacker can break <username>root</username>. + However, the reality is that in a well secured and maintained + system, access to a user account does not necessarily give the + attacker access to <username>root</username>. The distinction + is important because without access to <username>root</username> + the attacker cannot generally hide his tracks and may, at best, + be able to do nothing more than mess with the user's files, or + crash the machine. User account compromises are very common + because users tend not to take the precautions that sysadmins + take.</para> + + <indexterm> + <primary>security</primary> + <secondary>backdoors</secondary> + </indexterm> + + <para>System administrators must keep in mind that there are + potentially many ways to break <username>root</username> on a + machine. The attacker may know the <username>root</username> + password, the attacker may find a bug in a root-run server and + be able to break <username>root</username> over a network + connection to that server, or the attacker may know of a bug in + a suid-root program that allows the attacker to break + <username>root</username> once he has broken into a user's + account. If an attacker has found a way to break + <username>root</username> on a machine, the attacker may not + have a need to install a backdoor. Many of the + <username>root</username> holes found and closed to date involve + a considerable amount of work by the attacker to cleanup after + himself, so most attackers install backdoors. A backdoor + provides the attacker with a way to easily regain + <username>root</username> access to the system, but it also + gives the smart system administrator a convenient way to detect + the intrusion. Making it impossible for an attacker to install + a backdoor may actually be detrimental to your security, because + it will not close off the hole the attacker found to break in + the first place.</para> + + <para>Security remedies should always be implemented with a + multi-layered <quote>onion peel</quote> approach and can be + categorized as follows:</para> + + <orderedlist> + <listitem> + <para>Securing <username>root</username> and staff + accounts.</para> + </listitem> + + <listitem> + <para>Securing <username>root</username>–run servers + and suid/sgid binaries.</para> + </listitem> + + <listitem> + <para>Securing user accounts.</para> + </listitem> + + <listitem> + <para>Securing the password file.</para> + </listitem> + + <listitem> + <para>Securing the kernel core, raw devices, and + file systems.</para> + </listitem> + + <listitem> + <para>Quick detection of inappropriate changes made to the + system.</para> + </listitem> + + <listitem> + <para>Paranoia.</para> + </listitem> + </orderedlist> + + <para>The next section of this chapter will cover the above bullet + items in greater depth.</para> + </sect1> + + <sect1 id="securing-freebsd"> + <title>Securing &os;</title> + + <indexterm> + <primary>security</primary> + <secondary>securing &os;</secondary> + </indexterm> + + <note> + <title>Command Versus Protocol</title> + + <para>Throughout this document, we will use + <application>bold</application> text to refer to an + application, and a <command>monospaced</command> font to refer + to specific commands. Protocols will use a normal font. This + typographical distinction is useful for instances such as ssh, + since it is a protocol as well as command.</para> + </note> + + <para>The sections that follow will cover the methods of securing + your &os; system that were mentioned in the <link + linkend="security-intro">last section</link> of this + chapter.</para> + + <sect2 id="securing-root-and-staff"> + <title>Securing the <username>root</username> Account and + Staff Accounts</title> + + <indexterm> + <primary><command>su</command></primary> + </indexterm> + + <para>First off, do not bother securing staff accounts if you + have not secured the <username>root</username> account. Most + systems have a password assigned to the + <username>root</username> account. The first thing you do is + assume that the password is <emphasis>always</emphasis> + compromised. This does not mean that you should remove the + password. The password is almost always necessary for console + access to the machine. What it does mean is that you should + not make it possible to use the password outside of the + console or possibly even with the &man.su.1; command. For + example, make sure that your ptys are specified as being + insecure in the <filename>/etc/ttys</filename> file so that + direct <username>root</username> logins via + <command>telnet</command> or <command>rlogin</command> are + disallowed. If using other login services such as + <application>sshd</application>, make sure that direct + <username>root</username> logins are disabled there as well. + You can do this by editing your + <filename>/etc/ssh/sshd_config</filename> file, and making + sure that <literal>PermitRootLogin</literal> is set to + <literal>no</literal>. Consider every access method — + services such as FTP often fall through the cracks. Direct + <username>root</username> logins should only be allowed via + the system console.</para> + + <indexterm> + <primary><groupname>wheel</groupname></primary> + </indexterm> + + <para>Of course, as a sysadmin you have to be able to get to + <username>root</username>, so we open up a few holes. But we + make sure these holes require additional password verification + to operate. One way to make <username>root</username> + accessible is to add appropriate staff accounts to the + <groupname>wheel</groupname> group (in + <filename>/etc/group</filename>). The staff members placed in + the <groupname>wheel</groupname> group are allowed to + <command>su</command> to <username>root</username>. You + should never give staff members native + <groupname>wheel</groupname> access by putting them in the + <groupname>wheel</groupname> group in their password entry. + Staff accounts should be placed in a + <groupname>staff</groupname> group, and then added to the + <groupname>wheel</groupname> group via the + <filename>/etc/group</filename> file. Only those staff + members who actually need to have <username>root</username> + access should be placed in the <groupname>wheel</groupname> + group. It is also possible, when using an authentication + method such as Kerberos, to use Kerberos' + <filename>.k5login</filename> file in the + <username>root</username> account to allow a &man.ksu.1; to + <username>root</username> without having to place anyone at + all in the <groupname>wheel</groupname> group. This may be + the better solution since the <groupname>wheel</groupname> + mechanism still allows an intruder to break + <username>root</username> if the intruder has gotten hold of + your password file and can break into a staff account. While + having the <groupname>wheel</groupname> mechanism is better + than having nothing at all, it is not necessarily the safest + option.</para> + + <para>To lock an account completely, the &man.pw.8; command + should be used:</para> + + <screen>&prompt.root; <userinput>pw lock <replaceable>staff</replaceable></userinput></screen> + + <para>This will prevent the user from logging in using any + mechanism, including &man.ssh.1;.</para> + + <para>Another method of blocking access to accounts would be to + replace the encrypted password with a single + <quote><literal>*</literal></quote> character. This character + would never match the encrypted password and thus block user + access. For example, the following staff account:</para> + + <programlisting>foobar:R9DT/Fa1/LV9U:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting> + + <para>Should be changed to this:</para> + + <programlisting>foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting> + + <para>This will prevent the <username>foobar</username> user + from logging in using conventional methods. This method for + access restriction is flawed on sites using + <application>Kerberos</application> or in situations where the + user has set up keys with &man.ssh.1;.</para> + + <para>These security mechanisms also assume that you are logging + in from a more restrictive server to a less restrictive + server. For example, if your main box is running all sorts of + servers, your workstation should not be running any. In order + for your workstation to be reasonably secure you should run as + few servers as possible, up to and including no servers at + all, and you should run a password-protected screen blanker. + Of course, given physical access to a workstation an attacker + can break any sort of security you put on it. This is + definitely a problem that you should consider, but you should + also consider the fact that the vast majority of break-ins + occur remotely, over a network, from people who do not have + physical access to your workstation or servers.</para> + + <para>Using something like Kerberos also gives you the ability + to disable or change the password for a staff account in one + place, and have it immediately affect all the machines on + which the staff member may have an account. If a staff + member's account gets compromised, the ability to instantly + change his password on all machines should not be underrated. + With discrete passwords, changing a password on N machines can + be a mess. You can also impose re-passwording restrictions + with Kerberos: not only can a Kerberos ticket be made to + timeout after a while, but the Kerberos system can require + that the user choose a new password after a certain period of + time (say, once a month).</para> + </sect2> + + <sect2> + <title>Securing Root-run Servers and SUID/SGID Binaries</title> + + <indexterm> + <primary><command>ntalk</command></primary> + </indexterm> + <indexterm> + <primary><command>comsat</command></primary> + </indexterm> + <indexterm> + <primary><command>finger</command></primary> + </indexterm> + <indexterm> + <primary>sandboxes</primary> + </indexterm> + <indexterm> + <primary><application>sshd</application></primary> + </indexterm> + <indexterm> + <primary><application>telnetd</application></primary> + </indexterm> + <indexterm> + <primary><application>rshd</application></primary> + </indexterm> + <indexterm> + <primary><application>rlogind</application></primary> + </indexterm> + + <para>The prudent sysadmin only runs the servers he needs to, no + more, no less. Be aware that third party servers are often + the most bug-prone. For example, running an old version of + <application>imapd</application> or + <application>popper</application> is like giving a universal + <username>root</username> ticket out to the entire world. + Never run a server that you have not checked out carefully. + Many servers do not need to be run as + <username>root</username>. For example, the + <application>ntalk</application>, + <application>comsat</application>, and + <application>finger</application> daemons can be run in + special user <firstterm>sandboxes</firstterm>. A sandbox is + not perfect, unless you go through a large amount of trouble, + but the onion approach to security still stands: If someone is + able to break in through a server running in a sandbox, they + still have to break out of the sandbox. The more layers the + attacker must break through, the lower the likelihood of his + success. Root holes have historically been found in virtually + every server ever run as <username>root</username>, including + basic system servers. If you are running a machine through + which people only login via <application>sshd</application> + and never login via <application>telnetd</application> or + <application>rshd</application> or + <application>rlogind</application>, then turn off those + services!</para> + + <para>&os; now defaults to running + <application>ntalkd</application>, + <application>comsat</application>, and + <application>finger</application> in a sandbox. Another + program which may be a candidate for running in a sandbox is + &man.named.8;. <filename>/etc/defaults/rc.conf</filename> + includes the arguments necessary to run + <application>named</application> in a sandbox in a + commented-out form. Depending on whether you are installing a + new system or upgrading an existing system, the special user + accounts used by these sandboxes may not be installed. The + prudent sysadmin would research and implement sandboxes for + servers whenever possible.</para> + + <indexterm> + <primary><application>sendmail</application></primary> + </indexterm> + + <para>There are a number of other servers that typically do not + run in sandboxes: <application>sendmail</application>, + <application>popper</application>, + <application>imapd</application>, + <application>ftpd</application>, and others. There are + alternatives to some of these, but installing them may require + more work than you are willing to perform (the convenience + factor strikes again). You may have to run these servers as + <username>root</username> and rely on other mechanisms to + detect break-ins that might occur through them.</para> + + <para>The other big potential <username>root</username> holes in + a system are the suid-root and sgid binaries installed on the + system. Most of these binaries, such as + <application>rlogin</application>, reside in <filename + class="directory">/bin</filename>, <filename + class="directory">/sbin</filename>, <filename + class="directory">/usr/bin</filename>, or <filename + class="directory">/usr/sbin</filename>. While nothing is + 100% safe, the system-default suid and sgid binaries can be + considered reasonably safe. Still, <username>root</username> + holes are occasionally found in these binaries. A + <username>root</username> hole was found in + <literal>Xlib</literal> in 1998 that made + <application>xterm</application> (which is typically suid) + vulnerable. It is better to be safe than sorry and the + prudent sysadmin will restrict suid binaries, that only staff + should run, to a special group that only staff can access, and + get rid of (<command>chmod 000</command>) any suid binaries + that nobody uses. A server with no display generally does not + need an <application>xterm</application> binary. Sgid + binaries can be almost as dangerous. If an intruder can break + an sgid-kmem binary, the intruder might be able to read + <filename>/dev/kmem</filename> and thus read the encrypted + password file, potentially compromising any passworded + account. Alternatively an intruder who breaks group + <literal>kmem</literal> can monitor keystrokes sent through + ptys, including ptys used by users who login through secure + methods. An intruder that breaks the + <groupname>tty</groupname> group can write to almost any + user's tty. If a user is running a terminal program or + emulator with a keyboard-simulation feature, the intruder can + potentially generate a data stream that causes the user's + terminal to echo a command, which is then run as that + user.</para> + </sect2> + + <sect2 id="secure-users"> + <title>Securing User Accounts</title> + + <para>User accounts are usually the most difficult to secure. + While you can impose draconian access restrictions on your + staff and <quote>star</quote> out their passwords, you may not + be able to do so with any general user accounts you might + have. If you do have sufficient control, then you may win out + and be able to secure the user accounts properly. If not, you + simply have to be more vigilant in your monitoring of those + accounts. Use of ssh and Kerberos for user accounts is more + problematic, due to the extra administration and technical + support required, but still a very good solution compared to a + encrypted password file.</para> + </sect2> + + <sect2> + <title>Securing the Password File</title> + + <para>The only sure fire way is to star out as many passwords as + you can and use ssh or Kerberos for access to those accounts. + Even though the encrypted password file + (<filename>/etc/spwd.db</filename>) can only be read by + <username>root</username>, it may be possible for an intruder + to obtain read access to that file even if the attacker cannot + obtain root-write access.</para> + + <para>Your security scripts should always check for and report + changes to the password file (see the <link + linkend="security-integrity">Checking file integrity</link> + section below).</para> + </sect2> + + <sect2> + <title>Securing the Kernel Core, Raw Devices, and + File Systems</title> + + <para>If an attacker breaks <username>root</username> he can do + just about anything, but there are certain conveniences. For + example, most modern kernels have a packet sniffing device + driver built in. Under &os; it is called the + <devicename>bpf</devicename> device. An intruder will + commonly attempt to run a packet sniffer on a compromised + machine. You do not need to give the intruder the capability + and most systems do not have the need for the + <devicename>bpf</devicename> device compiled in.</para> + + <indexterm> + <primary><command>sysctl</command></primary> + </indexterm> + + <para>But even if you turn off the <devicename>bpf</devicename> + device, you still have <filename>/dev/mem</filename> and + <filename>/dev/kmem</filename> to worry about. For that + matter, the intruder can still write to raw disk devices. + Also, there is another kernel feature called the module + loader, &man.kldload.8;. An enterprising intruder can use a + KLD module to install his own <devicename>bpf</devicename> + device, or other sniffing device, on a running kernel. To + avoid these problems you have to run the kernel at a higher + secure level, at least securelevel 1.</para> + + <para>The secure level of the kernel can be set in a variety of + ways. The simplest way of raising the secure level of a + running kernel is through a <command>sysctl</command> on the + <varname>kern.securelevel</varname> kernel variable:</para> + + <screen>&prompt.root; <userinput>sysctl kern.securelevel=<replaceable>1</replaceable></userinput></screen> + + <para>By default, the &os; kernel boots with a secure level of + -1. The secure level will remain at -1 unless it is altered, + either by the administrator or by &man.init.8; because of a + setting in the start up scripts. The secure level may be + raised during system startup by setting the + <varname>kern_securelevel_enable</varname> variable to + <literal>YES</literal> in the + <filename>/etc/rc.conf</filename> file, and the value of the + <varname>kern_securelevel</varname> variable to the desired + secure level.</para> + + <para>The default secure level of a &os; system right after the + startup scripts are done is -1. This is called + <quote>insecure mode</quote> because immutable file flags may + be turned off, all devices may be read from or written to, and + so on.</para> + + <para>Once the secure level is set to 1 or a higher value, the + append-only and immutable files are honored, they cannot be + turned off, and access to raw devices will be denied. Higher + levels restrict even more operations. For a full description + of the effect of various secure levels, please read the + &man.security.7; manual page (or the manual page of + &man.init.8; in releases older than &os; 7.0).</para> + + <note> + <para>Bumping the secure level to 1 or higher may cause a few + problems to X11 (access to <filename>/dev/io</filename> will + be blocked), or to the installation of &os; built from + source (the <maketarget>installworld</maketarget> part of + the process needs to temporarily reset the append-only and + immutable flags of some files), and in a few other cases. + Sometimes, as in the case of X11, it may be possible to work + around this by starting &man.xdm.1; pretty early in the boot + process, when the securelevel is still low enough. + Workarounds like this may not be possible for all secure + levels or for all the potential restrictions they enforce. + A bit of forward planning is a good idea. Understanding the + restrictions imposed by each secure level is important as + they severely diminish the ease of system use. It will also + make choosing a default setting much simpler and prevent any + surprises.</para> + </note> + + <para>If the kernel's secure level is raised to 1 or a higher + value, it may be useful to set the <literal>schg</literal> + flag on critical startup binaries, directories, and script + files (i.e., everything that gets run up to the point where + the securelevel is set). This might be overdoing it, and + upgrading the system is much more difficult when it operates + at a high secure level. A less strict compromise is to run + the system at a higher secure level but skip setting the + <literal>schg</literal> flag for every system file and + directory under the sun. Another possibility is to simply + mount <filename class="directory">/</filename> and <filename + class="directory">/usr</filename> read-only. It should be + noted that being too draconian about what is permitted may + prevent the all-important detection of an intrusion.</para> + </sect2> + + <sect2 id="security-integrity"> + <title>Checking File Integrity: Binaries, Configuration Files, + Etc.</title> + + <para>When it comes right down to it, you can only protect your + core system configuration and control files so much before the + convenience factor rears its ugly head. For example, using + <command>chflags</command> to set the <literal>schg</literal> + bit on most of the files in <filename + class="directory">/</filename> and <filename + class="directory">/usr</filename> is probably + counterproductive, because while it may protect the files, it + also closes a detection window. The last layer of your + security onion is perhaps the most important — + detection. The rest of your security is pretty much useless + (or, worse, presents you with a false sense of security) if + you cannot detect potential intrusions. Half the job of the + onion is to slow down the attacker, rather than stop him, in + order to be able to catch him in the act.</para> + + <para>The best way to detect an intrusion is to look for + modified, missing, or unexpected files. The best way to look + for modified files is from another (often centralized) + limited-access system. Writing your security scripts on the + extra-secure limited-access system makes them mostly invisible + to potential attackers, and this is important. In order to + take maximum advantage you generally have to give the + limited-access box significant access to the other machines in + the business, usually either by doing a read-only NFS export + of the other machines to the limited-access box, or by setting + up ssh key-pairs to allow the limited-access box to ssh to the + other machines. Except for its network traffic, NFS is the + least visible method — allowing you to monitor the file + systems on each client box virtually undetected. If your + limited-access server is connected to the client boxes through + a switch, the NFS method is often the better choice. If your + limited-access server is connected to the client boxes through + a hub, or through several layers of routing, the NFS method + may be too insecure (network-wise) and using ssh may be the + better choice even with the audit-trail tracks that ssh + lays.</para> + + <para>Once you have given a limited-access box at least read + access to the client systems it is supposed to monitor, you + must write scripts to do the actual monitoring. Given an NFS + mount, you can write scripts out of simple system utilities + such as &man.find.1; and &man.md5.1;. It is best to + physically md5 the client-box files at least once a day, and + to test control files such as those found in <filename + class="directory">/etc</filename> and <filename + class="directory">/usr/local/etc</filename> even more often. + When mismatches are found, relative to the base md5 + information the limited-access machine knows is valid, it + should scream at a sysadmin to go check it out. A good + security script will also check for inappropriate suid + binaries and for new or deleted files on system partitions + such as <filename class="directory">/</filename> and <filename + class="directory">/usr</filename>.</para> + + <para>When using ssh rather than NFS, writing the security + script is much more difficult. You essentially have to + <command>scp</command> the scripts to the client box in order + to run them, making them visible, and for safety you also need + to <command>scp</command> the binaries (such as find) that + those scripts use. The <application>ssh</application> client + on the client box may already be compromised. All in all, + using ssh may be necessary when running over insecure links, + but it is also a lot harder to deal with.</para> + + <para>A good security script will also check for changes to user + and staff members access configuration files: + <filename>.rhosts</filename>, <filename>.shosts</filename>, + <filename>.ssh/authorized_keys</filename> and so forth, files + that might fall outside the purview of the + <literal>MD5</literal> check.</para> + + <para>If you have a huge amount of user disk space, it may take + too long to run through every file on those partitions. In + this case, setting mount flags to disallow suid binaries is a + good idea. The <literal>nosuid</literal> option (see + &man.mount.8;) is what you want to look into. You should + probably scan them anyway, at least once a week, since the + object of this layer is to detect a break-in attempt, whether + or not the attempt succeeds.</para> + + <para>Process accounting (see &man.accton.8;) is a relatively + low-overhead feature of the operating system which might help + as a post-break-in evaluation mechanism. It is especially + useful in tracking down how an intruder has actually broken + into a system, assuming the file is still intact after the + break-in has occurred.</para> + + <para>Finally, security scripts should process the log files, + and the logs themselves should be generated in as secure a + manner as possible — remote syslog can be very useful. + An intruder will try to cover his tracks, and log files are + critical to the sysadmin trying to track down the time and + method of the initial break-in. One way to keep a permanent + record of the log files is to run the system console to a + serial port and collect the information to a secure machine + monitoring the consoles.</para> + </sect2> + + <sect2> + <title>Paranoia</title> + + <para>A little paranoia never hurts. As a rule, a sysadmin can + add any number of security features, as long as they do not + affect convenience, and can add security features that + <emphasis>do</emphasis> affect convenience with some added + thought. Even more importantly, a security administrator + should mix it up a bit — if you use recommendations such + as those given by this document verbatim, you give away your + methodologies to the prospective attacker who also has access + to this document.</para> + </sect2> + + <sect2> + <title>Denial of Service Attacks</title> + + <indexterm> + <primary>Denial of Service (DoS)</primary> + </indexterm> + + <para>This section covers Denial of Service attacks. A DoS + attack is typically a packet attack. While there is not much + you can do about modern spoofed packet attacks that saturate + your network, you can generally limit the damage by ensuring + that the attacks cannot take down your servers by:</para> + + <orderedlist> + <listitem> + <para>Limiting server forks.</para> + </listitem> + + <listitem> + <para>Limiting springboard attacks (ICMP response attacks, + ping broadcast, etc.).</para> + </listitem> + + <listitem> + <para>Overloading the Kernel Route Cache.</para> + </listitem> + </orderedlist> + + <para>A common DoS attack scenario is attacking a forking server + and making it spawn so many child processes that the host + system eventually runs out of memory, file descriptors, etc. + and then grinds to a halt. <application>inetd</application> + (see &man.inetd.8;) has several options to limit this sort of + attack. It should be noted that while it is possible to + prevent a machine from going down, it is not generally + possible to prevent a service from being disrupted by the + attack. Read the <application>inetd</application> manual page + carefully and pay specific attention to the + <option>-c</option>, <option>-C</option>, and + <option>-R</option> options. Note that spoofed-IP attacks + will circumvent the <option>-C</option> option to + <application>inetd</application>, so typically a combination + of options must be used. Some standalone servers have + self-fork-limitation parameters.</para> + + <para><application>Sendmail</application> has its + <option>-OMaxDaemonChildren</option> option, which tends to + work much better than trying to use + <application>Sendmail</application>'s load limiting options + due to the load lag. You should specify a + <literal>MaxDaemonChildren</literal> parameter, when you start + <application>sendmail</application>; high enough to handle + your expected load, but not so high that the computer cannot + handle that number of <application>Sendmail</application> + instances without falling on its face. It is also prudent to + run <application>Sendmail</application> in queued mode + (<option>-ODeliveryMode=queued</option>) and to run the daemon + (<command>sendmail -bd</command>) separate from the queue-runs + (<command>sendmail -q15m</command>). If you still want + real-time delivery you can run the queue at a much lower + interval, such as <option>-q1m</option>, but be sure to + specify a reasonable <literal>MaxDaemonChildren</literal> + option for <emphasis>that</emphasis> + <application>Sendmail</application> to prevent cascade + failures.</para> + + <para><application>Syslogd</application> can be attacked + directly and it is strongly recommended that you use the + <option>-s</option> option whenever possible, and the + <option>-a</option> option otherwise.</para> + + <para>You should also be fairly careful with connect-back + services such as <application>TCP Wrapper</application>'s + reverse-identd, which can be attacked directly. You generally + do not want to use the reverse-ident feature of + <application>TCP Wrapper</application> for this reason.</para> + + <para>It is a very good idea to protect internal services from + external access by firewalling them off at your border + routers. The idea here is to prevent saturation attacks from + outside your LAN, not so much to protect internal services + from network-based <username>root</username> compromise. + Always configure an exclusive firewall, i.e., <quote>firewall + everything <emphasis>except</emphasis> ports A, B, C, D, and + M-Z</quote>. This way you can firewall off all of your low + ports except for certain specific services such as + <application>named</application> (if you are primary for a + zone), <application>ntalkd</application>, + <application>sendmail</application>, and other + Internet-accessible services. If you try to configure the + firewall the other way — as an inclusive or permissive + firewall, there is a good chance that you will forget to + <quote>close</quote> a couple of services, or that you will + add a new internal service and forget to update the firewall. + You can still open up the high-numbered port range on the + firewall, to allow permissive-like operation, without + compromising your low ports. Also take note that &os; allows + you to control the range of port numbers used for dynamic + binding, via the various + <varname>net.inet.ip.portrange</varname> + <command>sysctl</command>'s (<command>sysctl -a | fgrep + portrange</command>), which can also ease the complexity of + your firewall's configuration. For example, you might use a + normal first/last range of 4000 to 5000, and a hiport range of + 49152 to 65535, then block off everything under 4000 in your + firewall (except for certain specific Internet-accessible + ports, of course).</para> + + <para>Another common DoS attack is called a springboard attack + — to attack a server in a manner that causes the server + to generate responses which overloads the server, the local + network, or some other machine. The most common attack of + this nature is the <emphasis>ICMP ping broadcast + attack</emphasis>. The attacker spoofs ping packets sent to + your LAN's broadcast address with the source IP address set to + the actual machine they wish to attack. If your border + routers are not configured to stomp on ping packets to + broadcast addresses, your LAN winds up generating sufficient + responses to the spoofed source address to saturate the + victim, especially when the attacker uses the same trick on + several dozen broadcast addresses over several dozen different + networks at once. Broadcast attacks of over a hundred and + twenty megabits have been measured. A second common + springboard attack is against the ICMP error reporting system. + By constructing packets that generate ICMP error responses, an + attacker can saturate a server's incoming network and cause + the server to saturate its outgoing network with ICMP + responses. This type of attack can also crash the server by + running it out of memory, especially if the server cannot + drain the ICMP responses it generates fast enough. Use the + <application>sysctl</application> variable + <literal>net.inet.icmp.icmplim</literal> to limit these + attacks. The last major class of springboard attacks is + related to certain internal <application>inetd</application> + services such as the udp echo service. An attacker simply + spoofs a UDP packet with the source address being server A's + echo port, and the destination address being server B's echo + port, where server A and B are both on your LAN. The two + servers then bounce this one packet back and forth between + each other. The attacker can overload both servers and their + LANs simply by injecting a few packets in this manner. + Similar problems exist with the internal + <application>chargen</application> port. A competent sysadmin + will turn off all of these inetd-internal test + services.</para> + + <para>Spoofed packet attacks may also be used to overload the + kernel route cache. Refer to the + <varname>net.inet.ip.rtexpire</varname>, + <varname>rtminexpire</varname>, and + <varname>rtmaxcache</varname> <command>sysctl</command> + parameters. A spoofed packet attack that uses a random source + IP will cause the kernel to generate a temporary cached route + in the route table, viewable with <command>netstat -rna | + fgrep W3</command>. These routes typically timeout in 1600 + seconds or so. If the kernel detects that the cached route + table has gotten too big it will dynamically reduce the + <varname>rtexpire</varname> but will never decrease it to less + than <varname>rtminexpire</varname>. There are two + problems:</para> + + <orderedlist> + <listitem> + + <para>The kernel does not react quickly enough when a + lightly loaded server is suddenly attacked.</para> + </listitem> + + <listitem> + <para>The <varname>rtminexpire</varname> is not low enough + for the kernel to survive a sustained attack.</para> + </listitem> + </orderedlist> + + <para>If your servers are connected to the Internet via a T3 or + better, it may be prudent to manually override both + <varname>rtexpire</varname> and <varname>rtminexpire</varname> + via &man.sysctl.8;. Never set either parameter to zero + (unless you want to crash the machine). Setting both + parameters to 2 seconds should be sufficient to protect the + route table from attack.</para> + </sect2> + + <sect2> + <title>Access Issues with Kerberos and SSH</title> + + <indexterm><primary><command>ssh</command></primary></indexterm> + + <para>There are a few issues with both Kerberos and + ssh that need to be addressed if + you intend to use them. Kerberos 5 is an excellent + authentication protocol, but there are bugs in the kerberized + <application>telnet</application> and + <application>rlogin</application> applications that make them + unsuitable for dealing with binary streams. Also, by default + Kerberos does not encrypt a session unless you use the + <option>-x</option> option. <application>ssh</application> + encrypts everything by default.</para> + + <para>Ssh works quite well in every respect except that it + forwards encryption keys by default. What this means is that + if you have a secure workstation holding keys that give you + access to the rest of the system, and you ssh to an insecure + machine, your keys are usable. The actual keys themselves are + not exposed, but ssh installs a forwarding port for the + duration of your login, and if an attacker has broken + <username>root</username> on the insecure machine he can + utilize that port to use your keys to gain access to any other + machine that your keys unlock.</para> + + <para>We recommend that you use ssh in combination with Kerberos + whenever possible for staff logins. + <application>Ssh</application> can be compiled with Kerberos + support. This reduces your reliance on potentially exposed + ssh keys while at the same time protecting passwords via + Kerberos. Ssh keys should only be used for automated tasks + from secure machines (something that Kerberos is unsuited to + do). We also recommend that you either turn off + key-forwarding in the ssh configuration, or that you make use + of the <literal>from=IP/DOMAIN</literal> option that ssh + allows in its <filename>authorized_keys</filename> file to + make the key only usable to entities logging in from specific + machines.</para> + </sect2> + </sect1> + + <sect1 id="crypt"> + <sect1info> + <authorgroup> + <author> + <firstname>Bill</firstname> + <surname>Swingle</surname> + <contrib>Parts rewritten and updated by </contrib> + </author> + </authorgroup> + <!-- 21 Mar 2000 --> + </sect1info> + + <title>DES, Blowfish, MD5, and Crypt</title> + + <indexterm> + <primary>security</primary> + <secondary>crypt</secondary> + </indexterm> + + <indexterm><primary>crypt</primary></indexterm> + <indexterm><primary>Blowfish</primary></indexterm> + <indexterm><primary>DES</primary></indexterm> + <indexterm><primary>MD5</primary></indexterm> + + <para>Every user on a &unix; system has a password associated with + their account. It seems obvious that these passwords need to be + known only to the user and the actual operating system. In + order to keep these passwords secret, they are encrypted with + what is known as a <quote>one-way hash</quote>, that is, they + can only be easily encrypted but not decrypted. In other words, + what we told you a moment ago was obvious is not even true: the + operating system itself does not <emphasis>really</emphasis> + know the password. It only knows the + <emphasis>encrypted</emphasis> form of the password. The only + way to get the <quote>plain-text</quote> password is by a brute + force search of the space of possible passwords.</para> + + <para>Unfortunately the only secure way to encrypt passwords when + &unix; came into being was based on DES, the Data Encryption + Standard. This was not such a problem for users resident in the + US, but since the source code for DES could not be exported + outside the US, &os; had to find a way to both comply with US + law and retain compatibility with all the other &unix; variants + that still used DES.</para> + + <para>The solution was to divide up the encryption libraries so + that US users could install the DES libraries and use DES but + international users still had an encryption method that could be + exported abroad. This is how &os; came to use MD5 as its + default encryption method. MD5 is believed to be more secure + than DES, so installing DES is offered primarily for + compatibility reasons.</para> + + <sect2> + <title>Recognizing Your Crypt Mechanism</title> + + <para>Currently the library supports DES, MD5 and Blowfish hash + functions. By default &os; uses MD5 to encrypt + passwords.</para> + + <para>It is pretty easy to identify which encryption method &os; + is set up to use. Examining the encrypted passwords in the + <filename>/etc/master.passwd</filename> file is one way. + Passwords encrypted with the MD5 hash are longer than those + encrypted with the DES hash and also begin with the characters + <literal>$1$</literal>. Passwords starting with + <literal>$2a$</literal> are encrypted with the + Blowfish hash function. DES password strings do not have any + particular identifying characteristics, but they are shorter + than MD5 passwords, and are coded in a 64-character alphabet + which does not include the <literal>$</literal> + character, so a relatively short string which does not begin + with a dollar sign is very likely a DES password.</para> + + <para>The password format used for new passwords is controlled + by the <literal>passwd_format</literal> login capability in + <filename>/etc/login.conf</filename>, which takes values of + <literal>des</literal>, <literal>md5</literal> or + <literal>blf</literal>. See the &man.login.conf.5; manual + page for more information about login capabilities.</para> + </sect2> + </sect1> + + <sect1 id="one-time-passwords"> + <title>One-time Passwords</title> + + <indexterm><primary>one-time passwords</primary></indexterm> + <indexterm> + <primary>security</primary> + <secondary>one-time passwords</secondary> + </indexterm> + + <para>By default, &os; includes support for OPIE (One-time + Passwords In Everything), which uses the MD5 hash by + default.</para> + + <para>There are three different sorts of passwords which we will + discuss below. The first is your usual &unix; style or Kerberos + password; we will call this a <quote>&unix; password</quote>. + The second sort is the one-time password which is generated by + the OPIE &man.opiekey.1; program and accepted by the + &man.opiepasswd.1; program and the login prompt; we will call + this a <quote>one-time password</quote>. The final sort of + password is the secret password which you give to the + <command>opiekey</command> program (and sometimes the + <command>opiepasswd</command> programs) which it uses to + generate one-time passwords; we will call it a <quote>secret + password</quote> or just unqualified + <quote>password</quote>.</para> + + <para>The secret password does not have anything to do with your + &unix; password; they can be the same but this is not + recommended. OPIE secret passwords are not limited to 8 + characters like old &unix; passwords<footnote><para>Under &os; + the standard login password may be up to 128 characters in + length.</para></footnote>, they can be as long as you like. + Passwords of six or seven word long phrases are fairly common. + For the most part, the OPIE system operates completely + independently of the &unix; password system.</para> + + <para>Besides the password, there are two other pieces of data + that are important to OPIE. One is what is known as the + <quote>seed</quote> or <quote>key</quote>, consisting of two + letters and five digits. The other is what is called the + <quote>iteration count</quote>, a number between 1 and 100. + OPIE creates the one-time password by concatenating the seed and + the secret password, then applying the MD5 hash as many times as + specified by the iteration count and turning the result into six + short English words. These six English words are your one-time + password. The authentication system (primarily PAM) keeps track + of the last one-time password used, and the user is + authenticated if the hash of the user-provided password is equal + to the previous password. Because a one-way hash is used it is + impossible to generate future one-time passwords if a + successfully used password is captured; the iteration count is + decremented after each successful login to keep the user and the + login program in sync. When the iteration count gets down to 1, + OPIE must be reinitialized.</para> + + <para>There are a few programs involved in each system which we + will discuss below. The <command>opiekey</command> program + accepts an iteration count, a seed, and a secret password, and + generates a one-time password or a consecutive list of one-time + passwords. The <command>opiepasswd</command> program is used to + initialize OPIE, and to change passwords, iteration counts, or + seeds; it takes either a secret passphrase, or an iteration + count, seed, and a one-time password. The + <command>opieinfo</command> program will examine the relevant + credentials files (<filename>/etc/opiekeys</filename>) and print + out the invoking user's current iteration count and seed.</para> + + <para>There are four different sorts of operations we will cover. + The first is using <command>opiepasswd</command> over a secure + connection to set up one-time-passwords for the first time, or + to change your password or seed. The second operation is using + <command>opiepasswd</command> over an insecure connection, in + conjunction with <command>opiekey</command> over a secure + connection, to do the same. The third is using + <command>opiekey</command> to log in over an insecure + connection. The fourth is using <command>opiekey</command> to + generate a number of keys which can be written down or printed + out to carry with you when going to some location without secure + connections to anywhere.</para> + + <sect2> + <title>Secure Connection Initialization</title> + + <para>To initialize OPIE for the first time, execute the + <command>opiepasswd</command> command:</para> + + <screen>&prompt.user; <userinput>opiepasswd -c</userinput> +[grimreaper] ~ $ opiepasswd -f -c +Adding unfurl: +Only use this method from the console; NEVER from remote. If you are using +telnet, xterm, or a dial-in, type ^C now or exit with no password. +Then run opiepasswd without the -c parameter. +Using MD5 to compute responses. +Enter new secret pass phrase: +Again new secret pass phrase: + +ID unfurl OTP key is 499 to4268 +MOS MALL GOAT ARM AVID COED</screen> + + <para>At the <prompt>Enter new secret pass phrase:</prompt> or + <prompt>Enter secret password:</prompt> prompts, you should + enter a password or phrase. Remember, this is not the + password that you will use to login with, this is used to + generate your one-time login keys. The <quote>ID</quote> line + gives the parameters of your particular instance: your login + name, the iteration count, and seed. When logging in the + system will remember these parameters and present them back to + you so you do not have to remember them. The last line gives + the particular one-time password which corresponds to those + parameters and your secret password; if you were to re-login + immediately, this one-time password is the one you would + use.</para> + </sect2> + + <sect2> + <title>Insecure Connection Initialization</title> + + <para>To initialize or change your secret password over an + insecure connection, you will need to already have a secure + connection to some place where you can run + <command>opiekey</command>; this might be in the form of a + shell prompt on a machine you trust. You will also need to + make up an iteration count (100 is probably a good value), and + you may make up your own seed or use a randomly-generated one. + Over on the insecure connection (to the machine you are + initializing), use <command>opiepasswd</command>:</para> + + <screen>&prompt.user; <userinput>opiepasswd</userinput> + +Updating unfurl: +You need the response from an OTP generator. +Old secret pass phrase: + otp-md5 498 to4268 ext + Response: GAME GAG WELT OUT DOWN CHAT +New secret pass phrase: + otp-md5 499 to4269 + Response: LINE PAP MILK NELL BUOY TROY + +ID mark OTP key is 499 gr4269 +LINE PAP MILK NELL BUOY TROY</screen> + + <para>To accept the default seed press <keycap>Return</keycap>. + Then before entering an access password, move over to your + secure connection and give it the same parameters:</para> + + <screen>&prompt.user; <userinput>opiekey 498 to4268</userinput> +Using the MD5 algorithm to compute response. +Reminder: Don't use opiekey from telnet or dial-in sessions. +Enter secret pass phrase: +GAME GAG WELT OUT DOWN CHAT</screen> + + <para>Now switch back over to the insecure connection, and copy + the one-time password generated over to the relevant + program.</para> + </sect2> + + <sect2> + <title>Generating a Single One-time Password</title> + + <para>Once you have initialized OPIE and login, you will be + presented with a prompt like this:</para> + +<screen>&prompt.user; <userinput>telnet example.com</userinput> +Trying 10.0.0.1... +Connected to example.com +Escape character is '^]'. + +FreeBSD/i386 (example.com) (ttypa) + +login: <userinput><username></userinput> +otp-md5 498 gr4269 ext +Password: </screen> + + <para>As a side note, the OPIE prompts have a useful feature + (not shown here): if you press <keycap>Return</keycap> at the + password prompt, the prompter will turn echo on, so you can + see what you are typing. This can be extremely useful if you + are attempting to type in a password by hand, such as from a + printout.</para> + + <indexterm><primary>MS-DOS</primary></indexterm> + <indexterm><primary>Windows</primary></indexterm> + <indexterm><primary>MacOS</primary></indexterm> + + <para>At this point you need to generate your one-time password + to answer this login prompt. This must be done on a trusted + system that you can run <command>opiekey</command> on. (There + are versions of these for DOS, &windows; and &macos; as well.) + They need the iteration count and the seed as command line + options. You can cut-and-paste these right from the login + prompt on the machine that you are logging in to.</para> + + <para>On the trusted system:</para> + + <screen>&prompt.user; <userinput>opiekey 498 to4268</userinput> +Using the MD5 algorithm to compute response. +Reminder: Don't use opiekey from telnet or dial-in sessions. +Enter secret pass phrase: +GAME GAG WELT OUT DOWN CHAT</screen> + + <para>Now that you have your one-time password you can continue + logging in.</para> + </sect2> + + <sect2> + <title>Generating Multiple One-time Passwords</title> + + <para>Sometimes you have to go places where you do not have + access to a trusted machine or secure connection. In this + case, it is possible to use the <command>opiekey</command> + command to generate a number of one-time passwords beforehand + to be printed out and taken with you. For example:</para> + + <screen>&prompt.user; <userinput>opiekey -n 5 30 zz99999</userinput> +Using the MD5 algorithm to compute response. +Reminder: Don't use opiekey from telnet or dial-in sessions. +Enter secret pass phrase: <userinput><secret password></userinput> +26: JOAN BORE FOSS DES NAY QUIT +27: LATE BIAS SLAY FOLK MUCH TRIG +28: SALT TIN ANTI LOON NEAL USE +29: RIO ODIN GO BYE FURY TIC +30: GREW JIVE SAN GIRD BOIL PHI</screen> + + <para>The <option>-n 5</option> requests five keys in sequence, + the <option>30</option> specifies what the last iteration + number should be. Note that these are printed out in + <emphasis>reverse</emphasis> order of eventual use. If you + are really paranoid, you might want to write the results down + by hand; otherwise you can cut-and-paste into + <command>lpr</command>. Note that each line shows both the + iteration count and the one-time password; you may still find + it handy to scratch off passwords as you use them.</para> + </sect2> + + <sect2> + <title>Restricting Use of &unix; Passwords</title> + + <para>OPIE can restrict the use of &unix; passwords based on the + IP address of a login session. The relevant file is + <filename>/etc/opieaccess</filename>, which is present by + default. Please check &man.opieaccess.5; for more information + on this file and which security considerations you should be + aware of when using it.</para> + + <para>Here is a sample <filename>opieaccess</filename> + file:</para> + + <programlisting>permit 192.168.0.0 255.255.0.0</programlisting> + + <para>This line allows users whose IP source address (which is + vulnerable to spoofing) matches the specified value and mask, + to use &unix; passwords at any time.</para> + + <para>If no rules in <filename>opieaccess</filename> are + matched, the default is to deny non-OPIE logins.</para> + </sect2> + </sect1> + + <sect1 id="tcpwrappers"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + + <indexterm><primary>TCP Wrappers</primary></indexterm> + + <title>TCP Wrappers</title> + + <para>Anyone familiar with &man.inetd.8; has probably heard of + <acronym>TCP</acronym> Wrappers at some point. But few + individuals seem to fully comprehend its usefulness in a network + environment. It seems that everyone wants to install a firewall + to handle network connections. While a firewall has a wide + variety of uses, there are some things that a firewall will not + handle, such as sending text back to the connection originator. + The <acronym>TCP</acronym> Wrappers software does this and much + more. In the next few sections many of the + <acronym>TCP</acronym> Wrappers features will be discussed, and, + when applicable, example configuration lines will be + provided.</para> + + <para>The <acronym>TCP</acronym> Wrappers software extends the + abilities of <application>inetd</application> to provide support + for every server daemon under its control. Using this method it + is possible to provide logging support, return messages to + connections, permit a daemon to only accept internal + connections, etc. While some of these features can be provided + by implementing a firewall, this will add not only an extra + layer of protection but go beyond the amount of control a + firewall can provide.</para> + + <para>The added functionality of <acronym>TCP</acronym> Wrappers + should not be considered a replacement for a good firewall. + <acronym>TCP</acronym> Wrappers can be used in conjunction + with a firewall or other security enhancements though and + it can serve nicely as an extra layer of protection + for the system.</para> + + <para>Since this is an extension to the configuration of + <application>inetd</application>, the reader is expected have + read the <link linkend="network-inetd">inetd + configuration</link> section.</para> + + <note> + <para>While programs run by &man.inetd.8; are not exactly + <quote>daemons</quote>, they have traditionally been called + daemons. This is the term we will use in this section + too.</para> + </note> + + <sect2> + <title>Initial Configuration</title> + + <para>The only requirement of using <acronym>TCP</acronym> + Wrappers in &os; is to ensure the + <application>inetd</application> server is started from + <filename>rc.conf</filename> with the <option>-Ww</option> + option; this is the default setting. Of course, proper + configuration of <filename>/etc/hosts.allow</filename> is also + expected, but &man.syslogd.8; will throw messages in the + system logs in these cases.</para> + + <note> + <para>Unlike other implementations of <acronym>TCP</acronym> + Wrappers, the use of <filename>hosts.deny</filename> has + been deprecated. All configuration options should be placed + in <filename>/etc/hosts.allow</filename>.</para> + </note> + + <para>In the simplest configuration, daemon connection policies + are set to either be permitted or blocked depending on the + options in <filename>/etc/hosts.allow</filename>. The default + configuration in &os; is to allow a connection to every daemon + started with <application>inetd</application>. Changing this + will be discussed only after the basic configuration is + covered.</para> + + <para>Basic configuration usually takes the form of + <literal>daemon : address : action</literal>. Where + <literal>daemon</literal> is the daemon name which + <command>inetd</command> started. The + <literal>address</literal> can be a valid hostname, an + <acronym>IP</acronym> address or an IPv6 address enclosed in + brackets ([ ]). The <literal>action</literal> field can + be either <literal>allow</literal> or <literal>deny</literal> + to grant or deny access appropriately. Keep in mind that + configuration works off a first rule match semantic, meaning + that the configuration file is scanned in ascending order for + a matching rule. When a match is found the rule is applied + and the search process will halt.</para> + + <para>Several other options exist but they will be explained + in a later section. A simple configuration line may easily be + constructed from that information alone. For example, to + allow <acronym>POP</acronym>3 connections via the + <filename role="package">mail/qpopper</filename> daemon, + the following lines should be appended to + <filename>hosts.allow</filename>:</para> + + <programlisting># This line is required for POP3 connections: +qpopper : ALL : allow</programlisting> + + <para>After adding this line, <application>inetd</application> + will need to be restarted. This can be accomplished by use of + the &man.kill.1; command, or with the + <parameter>restart</parameter> parameter with + <filename>/etc/rc.d/inetd</filename>.</para> + </sect2> + + <sect2> + <title>Advanced Configuration</title> + + <para><acronym>TCP</acronym> Wrappers has advanced options too; + they will allow for more control over the way connections are + handled. In some cases it may be a good idea to return a + comment to certain hosts or daemon connections. In other + cases, perhaps a log file should be recorded or an email sent + to the administrator. Other situations may require the use of + a service for local connections only. This is all possible + through the use of configuration options known as + <literal>wildcards</literal>, expansion characters and + external command execution. The next two sections are written + to cover these situations.</para> + + <sect3> + <title>External Commands</title> + + <para>Suppose that a situation occurs where a connection + should be denied yet a reason should be sent to the + individual who attempted to establish that connection. How + could it be done? That action can be made possible by using + the <option>twist</option> option. When a connection + attempt is made, <option>twist</option> will be called to + execute a shell command or script. An example already + exists in the <filename>hosts.allow</filename> file:</para> + + <programlisting># The rest of the daemons are protected. +ALL : ALL \ + : severity auth.info \ + : twist /bin/echo "You are not welcome to use %d from %h."</programlisting> + + <para>This example shows that the message, + <quote>You are not allowed to use <literal>daemon</literal> + from <literal>hostname</literal>.</quote> will be returned + for any daemon not previously configured in the access file. + This is extremely useful for sending a reply back to the + connection initiator right after the established connection + is dropped. Note that any message returned + <emphasis>must</emphasis> be wrapped in quote + <literal>"</literal> characters; there are no exceptions to + this rule.</para> + + <warning> + <para>It may be possible to launch a denial of service + attack on the server if an attacker, or group of attackers, + could flood these daemons with connection requests.</para> + </warning> + + <para>Another possibility is to use the <option>spawn</option> + option in these cases. Like <option>twist</option>, the + <option>spawn</option> option implicitly denies the + connection and may be used to run external shell commands or + scripts. Unlike <option>twist</option>, + <option>spawn</option> will not send a reply back to the + individual who established the connection. For an example, + consider the following configuration line:</para> + + <programlisting># We do not allow connections from example.com: +ALL : .example.com \ + : spawn (/bin/echo %a from %h attempted to access %d >> \ + /var/log/connections.log) \ + : deny</programlisting> + + <para>This will deny all connection attempts from the <hostid + role="fqdn">*.example.com</hostid> domain; simultaneously + logging the hostname, <acronym>IP</acronym> address and the + daemon which they attempted to access in the + <filename>/var/log/connections.log</filename> file.</para> + + <para>Aside from the already explained substitution characters + above, e.g., <literal>%a</literal>, a few others exist. See + the &man.hosts.access.5; manual page for the complete + list.</para> + </sect3> + + <sect3> + <title>Wildcard Options</title> + + <para>Thus far the <literal>ALL</literal> option has been used + continuously throughout the examples. Other options exist + which could extend the functionality a bit further. For + instance, <literal>ALL</literal> may be used to match every + instance of either a daemon, domain or an + <acronym>IP</acronym> address. Another wildcard available + is <literal>PARANOID</literal> which may be used to match + any host which provides an <acronym>IP</acronym> address + that may be forged. In other words, + <literal>PARANOID</literal> may be used to define an action + to be taken whenever a connection is made from an + <acronym>IP</acronym> address that differs from its + hostname. The following example may shed some more light on + this discussion:</para> + + <programlisting># Block possibly spoofed requests to sendmail: +sendmail : PARANOID : deny</programlisting> + + <para>In that example all connection requests to + <command>sendmail</command> which have an + <acronym>IP</acronym> address that varies from its hostname + will be denied.</para> + + <caution> + <para>Using the <literal>PARANOID</literal> wildcard may + severely cripple servers if the client or server has a + broken <acronym>DNS</acronym> setup. Administrator + discretion is advised.</para> + </caution> + + <para>To learn more about wildcards and their associated + functionality, see the &man.hosts.access.5; manual + page.</para> + + <para>Before any of the specific configuration lines above + will work, the first configuration line should be commented + out in <filename>hosts.allow</filename>. This was noted at + the beginning of this section.</para> + </sect3> + </sect2> + </sect1> + + <sect1 id="kerberos5"> + <sect1info> + <authorgroup> + <author> + <firstname>Tillman</firstname> + <surname>Hodgson</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Mark</firstname> + <surname>Murray</surname> + <contrib>Based on a contribution by </contrib> + </author> + </authorgroup> + </sect1info> + + <title><application>Kerberos5</application></title> + + <para><application>Kerberos</application> is a network add-on + system/protocol that allows users to authenticate themselves + through the services of a secure server. Services such as + remote login, remote copy, secure inter-system file copying and + other high-risk tasks are made considerably safer and more + controllable.</para> + + <para><application>Kerberos</application> can be described as an + identity-verifying proxy system. It can also be described as a + trusted third-party authentication system. + <application>Kerberos</application> provides only one function + — the secure authentication of users on the network. It + does not provide authorization functions (what users are allowed + to do) or auditing functions (what those users did). After a + client and server have used <application>Kerberos</application> + to prove their identity, they can also encrypt all of their + communications to assure privacy and data integrity as they go + about their business.</para> + + <para>Therefore it is highly recommended that + <application>Kerberos</application> be used with other security + methods which provide authorization and audit services.</para> + + <para>The following instructions can be used as a guide on how to + set up <application>Kerberos</application> as distributed for + &os;. However, you should refer to the relevant manual pages + for a complete description.</para> + + <para>For purposes of demonstrating a + <application>Kerberos</application> installation, the various + name spaces will be handled as follows:</para> + + <itemizedlist> + <listitem> + <para>The <acronym>DNS</acronym> domain (<quote>zone</quote>) + will be example.org.</para> + </listitem> + + <listitem> + <para>The <application>Kerberos</application> realm will be + EXAMPLE.ORG.</para> + </listitem> + </itemizedlist> + + <note> + <para>Please use real domain names when setting up + <application>Kerberos</application> even if you intend to run + it internally. This avoids <acronym>DNS</acronym> problems + and assures inter-operation with other + <application>Kerberos</application> realms.</para> + </note> + + <sect2> + <title>History</title> + + <indexterm> + <primary>Kerberos5</primary> + <secondary>history</secondary> + </indexterm> + + <para><application>Kerberos</application> was created by + <acronym>MIT</acronym> as a solution to network security + problems. The <application>Kerberos</application> protocol + uses strong cryptography so that a client can prove its + identity to a server (and vice versa) across an insecure + network connection.</para> + + <para><application>Kerberos</application> is both the name of a + network authentication protocol and an adjective to describe + programs that implement the program + (<application>Kerberos</application> telnet, for example). + The current version of the protocol is version 5, described in + <acronym>RFC</acronym> 1510.</para> + + <para>Several free implementations of this protocol are + available, covering a wide range of operating systems. The + Massachusetts Institute of Technology + (<acronym>MIT</acronym>), where + <application>Kerberos</application> was originally developed, + continues to develop their <application>Kerberos</application> + package. It is commonly used in the <acronym>US</acronym> as + a cryptography product, as such it has historically been + affected by <acronym>US</acronym> export regulations. The + <acronym>MIT</acronym> <application>Kerberos</application> is + available as a port (<filename + role="package">security/krb5</filename>). Heimdal + <application>Kerberos</application> is another version 5 + implementation, and was explicitly developed outside of the + <acronym>US</acronym> to avoid export regulations (and is thus + often included in non-commercial &unix; variants). The + Heimdal <application>Kerberos</application> distribution is + available as a port (<filename + role="package">security/heimdal</filename>), and a minimal + installation of it is included in the base &os; + install.</para> + + <para>In order to reach the widest audience, these instructions + assume the use of the Heimdal distribution included in + &os;.</para> + </sect2> + + <sect2> + <title>Setting up a Heimdal <acronym>KDC</acronym></title> + + <indexterm> + <primary>Kerberos5</primary> + <secondary>Key Distribution Center</secondary> + </indexterm> + + <para>The Key Distribution Center (<acronym>KDC</acronym>) is + the centralized authentication service that + <application>Kerberos</application> provides — it is the + computer that issues <application>Kerberos</application> + tickets. The <acronym>KDC</acronym> is considered + <quote>trusted</quote> by all other computers in the + <application>Kerberos</application> realm, and thus has + heightened security concerns.</para> + + <para>Note that while running the + <application>Kerberos</application> server requires very few + computing resources, a dedicated machine acting only as a + <acronym>KDC</acronym> is recommended for security + reasons.</para> + + <para>To begin setting up a <acronym>KDC</acronym>, ensure that + your <filename>/etc/rc.conf</filename> file contains the + correct settings to act as a <acronym>KDC</acronym> (you may + need to adjust paths to reflect your own system):</para> + + <programlisting>kerberos5_server_enable="YES" +kadmind5_server_enable="YES"</programlisting> + + <para>Next we will set up your + <application>Kerberos</application> config file, + <filename>/etc/krb5.conf</filename>:</para> + + <programlisting>[libdefaults] + default_realm = EXAMPLE.ORG +[realms] + EXAMPLE.ORG = { + kdc = kerberos.example.org + admin_server = kerberos.example.org + } +[domain_realm] + .example.org = EXAMPLE.ORG</programlisting> + + <para>Note that this <filename>/etc/krb5.conf</filename> file + implies that your <acronym>KDC</acronym> will have the + fully-qualified hostname of <hostid + role="fqdn">kerberos.example.org</hostid>. You will need to + add a CNAME (alias) entry to your zone file to accomplish this + if your <acronym>KDC</acronym> has a different + hostname.</para> + + <note> + <para>For large networks with a properly configured + <acronym>BIND</acronym> <acronym>DNS</acronym> server, the + above example could be trimmed to:</para> + + <programlisting>[libdefaults] + default_realm = EXAMPLE.ORG</programlisting> + + <para>With the following lines being appended to the + <hostid role="fqdn">example.org</hostid> zonefile:</para> + + <programlisting>_kerberos._udp IN SRV 01 00 88 kerberos.example.org. +_kerberos._tcp IN SRV 01 00 88 kerberos.example.org. +_kpasswd._udp IN SRV 01 00 464 kerberos.example.org. +_kerberos-adm._tcp IN SRV 01 00 749 kerberos.example.org. +_kerberos IN TXT EXAMPLE.ORG</programlisting> + </note> + + <note> + <para>For clients to be able to find the + <application>Kerberos</application> services, you + <emphasis>must</emphasis> have either a fully configured + <filename>/etc/krb5.conf</filename> or a minimally + configured <filename>/etc/krb5.conf</filename> + <emphasis>and</emphasis> a properly configured DNS + server.</para> + </note> + + <para>Next we will create the + <application>Kerberos</application> database. This database + contains the keys of all principals encrypted with a master + password. You are not required to remember this password, it + will be stored in a file + (<filename>/var/heimdal/m-key</filename>). To create the + master key, run <command>kstash</command> and enter a + password.</para> + + <para>Once the master key has been created, you can initialize + the database using the <command>kadmin</command> program with + the <literal>-l</literal> option (standing for + <quote>local</quote>). This option instructs + <command>kadmin</command> to modify the database files + directly rather than going through the + <command>kadmind</command> network service. This handles the + chicken-and-egg problem of trying to connect to the database + before it is created. Once you have the + <command>kadmin</command> prompt, use the + <command>init</command> command to create your realms initial + database.</para> + + <para>Lastly, while still in <command>kadmin</command>, create + your first principal using the <command>add</command> command. + Stick to the defaults options for the principal for now, you + can always change them later with the + <command>modify</command> command. Note that you can use the + <literal>?</literal> command at any prompt to see the + available options.</para> + + <para>A sample database creation session is shown below:</para> + + <screen>&prompt.root; <userinput>kstash</userinput> +Master key: <userinput>xxxxxxxx</userinput> +Verifying password - Master key: <userinput>xxxxxxxx</userinput> + +&prompt.root; <userinput>kadmin -l</userinput> +kadmin> <userinput>init EXAMPLE.ORG</userinput> +Realm max ticket life [unlimited]: +kadmin> <userinput>add tillman</userinput> +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +Password: <userinput>xxxxxxxx</userinput> +Verifying password - Password: <userinput>xxxxxxxx</userinput></screen> + + <para>Now it is time to start up the <acronym>KDC</acronym> + services. Run <command>/etc/rc.d/kerberos start</command> and + <command>/etc/rc.d/kadmind start</command> to bring up the + services. Note that you will not have any kerberized daemons + running at this point but you should be able to confirm that + the <acronym>KDC</acronym> is functioning by obtaining and + listing a ticket for the principal (user) that you just + created from the command-line of the <acronym>KDC</acronym> + itself:</para> + + <screen>&prompt.user; <userinput>kinit <replaceable>tillman</replaceable></userinput> +tillman@EXAMPLE.ORG's Password: + +&prompt.user; <userinput>klist</userinput> +Credentials cache: FILE:<filename>/tmp/krb5cc_500</filename> + Principal: tillman@EXAMPLE.ORG + + Issued Expires Principal +Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG</screen> + + <para>The ticket can then be revoked when you have + finished:</para> + + <screen>&prompt.user; <userinput>kdestroy</userinput></screen> + </sect2> + + <sect2> + <title><application>Kerberos</application> Enabling a Server + with Heimdal Services</title> + + <indexterm> + <primary>Kerberos5</primary> + <secondary>enabling services</secondary> + </indexterm> + + <para>First, we need a copy of the + <application>Kerberos</application> configuration file, + <filename>/etc/krb5.conf</filename>. To do so, simply copy + it over to the client computer from the + <acronym>KDC</acronym> in a secure fashion (using network + utilities, such as &man.scp.1;, or physically via a floppy + disk).</para> + + <para>Next you need a <filename>/etc/krb5.keytab</filename> + file. This is the major difference between a server + providing <application>Kerberos</application> enabled + daemons and a workstation — the server must have a + <filename>keytab</filename> file. This file contains the + server's host key, which allows it and the + <acronym>KDC</acronym> to verify each others identity. It + must be transmitted to the server in a secure fashion, as + the security of the server can be broken if the key is made + public. This explicitly means that transferring it via a + clear text channel, such as <acronym>FTP</acronym>, is a + very bad idea.</para> + + <para>Typically, you transfer the <filename>keytab</filename> + to the server using the <command>kadmin</command> program. + This is handy because you also need to create the host + principal (the <acronym>KDC</acronym> end of the + <filename>krb5.keytab</filename>) using + <command>kadmin</command>.</para> + + <para>Note that you must have already obtained a ticket and + that this ticket must be allowed to use the + <command>kadmin</command> interface in the + <filename>kadmind.acl</filename>. See the section titled + <quote>Remote administration</quote> in the Heimdal info + pages (<command>info heimdal</command>) for details on + designing access control lists. If you do not want to + enable remote <command>kadmin</command> access, you can + simply securely connect to the <acronym>KDC</acronym> (via + local console, &man.ssh.1; or + <application>Kerberos</application> &man.telnet.1;) and + perform administration locally using + <command>kadmin -l</command>.</para> + + <para>After installing the <filename>/etc/krb5.conf</filename> + file, you can use <command>kadmin</command> from the + <application>Kerberos</application> server. The + <command>add --random-key</command> command will let you add + the server's host principal, and the <command>ext</command> + command will allow you to extract the server's host + principal to its own keytab. For example:</para> + + <screen>&prompt.root; <userinput>kadmin</userinput> +kadmin><userinput> add --random-key host/myserver.example.org</userinput> +Max ticket life [unlimited]: +Max renewable life [unlimited]: +Attributes []: +kadmin><userinput> ext host/myserver.example.org</userinput> +kadmin><userinput> exit</userinput></screen> + + <para>Note that the <command>ext</command> command (short for + <quote>extract</quote>) stores the extracted key in + <filename>/etc/krb5.keytab</filename> by default.</para> + + <para>If you do not have <command>kadmind</command> running on + the <acronym>KDC</acronym> (possibly for security reasons) + and thus do not have access to <command>kadmin</command> + remotely, you can add the host principal + (<username>host/myserver.EXAMPLE.ORG</username>) directly on + the <acronym>KDC</acronym> and then extract it to a + temporary file (to avoid over-writing the + <filename>/etc/krb5.keytab</filename> on the + <acronym>KDC</acronym>) using something like this:</para> + + <screen>&prompt.root; <userinput>kadmin</userinput> +kadmin><userinput> ext --keytab=/tmp/example.keytab host/myserver.example.org</userinput> +kadmin><userinput> exit</userinput></screen> + + <para>You can then securely copy the keytab to the server + computer (using <command>scp</command> or a floppy, for + example). Be sure to specify a non-default keytab name to + avoid over-writing the keytab on the + <acronym>KDC</acronym>.</para> + + <para>At this point your server can communicate with the + <acronym>KDC</acronym> (due to its + <filename>krb5.conf</filename> file) and it can prove its + own identity (due to the <filename>krb5.keytab</filename> + file). It is now ready for you to enable some + <application>Kerberos</application> services. For this + example we will enable the <command>telnet</command> service + by putting a line like this into your + <filename>/etc/inetd.conf</filename> and then restarting the + &man.inetd.8; service with <command>/etc/rc.d/inetd + restart</command>:</para> + + <programlisting>telnet stream tcp nowait root /usr/libexec/telnetd telnetd -a user</programlisting> + + <para>The critical bit is that the <command>-a</command> (for + authentication) type is set to user. Consult the + &man.telnetd.8; manual page for more details.</para> + </sect2> + + <sect2> + <title><application>Kerberos</application> Enabling a Client + with Heimdal</title> + + <indexterm> + <primary>Kerberos5</primary> + <secondary>configure clients</secondary> + </indexterm> + + <para>Setting up a client computer is almost trivially easy. + As far as <application>Kerberos</application> configuration + goes, you only need the <application>Kerberos</application> + configuration file, located at + <filename>/etc/krb5.conf</filename>. Simply securely copy + it over to the client computer from the + <acronym>KDC</acronym>.</para> + + <para>Test your client computer by attempting to use + <command>kinit</command>, <command>klist</command>, and + <command>kdestroy</command> from the client to obtain, show, + and then delete a ticket for the principal you created + above. You should also be able to use + <application>Kerberos</application> applications to connect + to <application>Kerberos</application> enabled servers, + though if that does not work and obtaining a ticket does the + problem is likely with the server and not with the client or + the <acronym>KDC</acronym>.</para> + + <para>When testing an application like + <command>telnet</command>, try using a packet sniffer (such + as &man.tcpdump.1;) to confirm that your password is not + sent in the clear. Try using <command>telnet</command> with + the <literal>-x</literal> option, which encrypts the entire + data stream (similar to <command>ssh</command>).</para> + + <para>Various non-core <application>Kerberos</application> + client applications are also installed by default. This is + where the <quote>minimal</quote> nature of the base Heimdal + installation is felt: <command>telnet</command> is the only + <application>Kerberos</application> enabled service.</para> + + <para>The Heimdal port adds some of the missing client + applications: <application>Kerberos</application> enabled + versions of <command>ftp</command>, <command>rsh</command>, + <command>rcp</command>, <command>rlogin</command>, and a few + other less common programs. The <acronym>MIT</acronym> port + also contains a full suite of + <application>Kerberos</application> client + applications.</para> + </sect2> + + <sect2> + <title>User Configuration Files: <filename>.k5login</filename> + and <filename>.k5users</filename></title> + + <indexterm> + <primary><filename>.k5login</filename></primary> + </indexterm> + + <indexterm> + <primary><filename>.k5users</filename></primary> + </indexterm> + + <para>Users within a realm typically have their + <application>Kerberos</application> principal (such as + <username>tillman@EXAMPLE.ORG</username>) mapped to a local + user account (such as a local account named + <username>tillman</username>). Client applications such as + <command>telnet</command> usually do not require a user name + or a principal.</para> + + <para>Occasionally, however, you want to grant access to a + local user account to someone who does not have a matching + <application>Kerberos</application> principal. For example, + <username>tillman@EXAMPLE.ORG</username> may need access to + the local user account <username>webdevelopers</username>. + Other principals may also need access to that local + account.</para> + + <para>The <filename>.k5login</filename> and + <filename>.k5users</filename> files, placed in a users home + directory, can be used similar to a powerful combination of + <filename>.hosts</filename> and + <filename>.rhosts</filename>, solving this problem. For + example, if a <filename>.k5login</filename> with the + following contents:</para> + + <screen>tillman@example.org +jdoe@example.org</screen> + + <para>Were to be placed into the home directory of the local + user <username>webdevelopers</username> then both principals + listed would have access to that account without requiring a + shared password.</para> + + <para>Reading the manual pages for these commands is + recommended. Note that the <command>ksu</command> manual + page covers <filename>.k5users</filename>.</para> + </sect2> + + <sect2> + <title><application>Kerberos</application> Tips, Tricks, and + Troubleshooting</title> + + <indexterm> + <primary>Kerberos5</primary> + <secondary>troubleshooting</secondary> + </indexterm> + + <itemizedlist> + <listitem> + <para>When using either the Heimdal or + <acronym>MIT</acronym> + <application>Kerberos</application> ports ensure that + your <envar>PATH</envar> environment variable lists the + <application>Kerberos</application> versions of the + client applications before the system versions.</para> + </listitem> + + <listitem> + <para>Do all the computers in your realm have synchronized + time settings? If not, authentication may fail. + <xref linkend="network-ntp"> describes how to synchronize + clocks using <acronym>NTP</acronym>.</para> + </listitem> + + <listitem> + <para><acronym>MIT</acronym> and Heimdal inter-operate + nicely. Except for <command>kadmin</command>, the + protocol for which is not standardized.</para> + </listitem> + + <listitem> + <para>If you change your hostname, you also need to change + your <username>host/</username> principal and update + your keytab. This also applies to special keytab + entries like the <username>www/</username> principal + used for Apache's + <filename + role="package">www/mod_auth_kerb</filename>.</para> + </listitem> + + <listitem> + <para>All hosts in your realm must be resolvable (both + forwards and reverse) in <acronym>DNS</acronym> (or + <filename>/etc/hosts</filename> as a minimum). CNAMEs + will work, but the A and PTR records must be correct and + in place. The error message is not very intuitive: + <errorname>Kerberos5 refuses authentication because Read + req failed: Key table entry not + found</errorname>.</para> + </listitem> + + <listitem> + <para>Some operating systems that may being acting as + clients to your <acronym>KDC</acronym> do not set the + permissions for <command>ksu</command> to be setuid + <username>root</username>. This means that + <command>ksu</command> does not work, which is a good + security idea but annoying. This is not a + <acronym>KDC</acronym> error.</para> + </listitem> + + <listitem> + <para>With <acronym>MIT</acronym> + <application>Kerberos</application>, if you want to + allow a principal to have a ticket life longer than the + default ten hours, you must use + <command>modify_principal</command> in + <command>kadmin</command> to change the maxlife of both + the principal in question and the + <username>krbtgt</username> principal. Then the + principal can use the <literal>-l</literal> option with + <command>kinit</command> to request a ticket with a + longer lifetime.</para> + </listitem> + + <listitem> + <note> + <para>If you run a packet sniffer on your + <acronym>KDC</acronym> to add in troubleshooting and + then run <command>kinit</command> from a workstation, + you will notice that your <acronym>TGT</acronym> is + sent immediately upon running <command>kinit</command> + — even before you type your password! The + explanation is that the + <application>Kerberos</application> server freely + transmits a <acronym>TGT</acronym> (Ticket Granting + Ticket) to any unauthorized request; however, every + <acronym>TGT</acronym> is encrypted in a key derived + from the user's password. Therefore, when a user + types their password it is not being sent to the + <acronym>KDC</acronym>, it is being used to decrypt + the <acronym>TGT</acronym> that + <command>kinit</command> already obtained. If the + decryption process results in a valid ticket with a + valid time stamp, the user has valid + <application>Kerberos</application> credentials. + These credentials include a session key for + establishing secure communications with the + <application>Kerberos</application> server in the + future, as well as the actual ticket-granting ticket, + which is actually encrypted with the + <application>Kerberos</application> server's own key. + This second layer of encryption is unknown to the + user, but it is what allows the + <application>Kerberos</application> server to verify + the authenticity of each + <acronym>TGT</acronym>.</para> + </note> + </listitem> + + <listitem> + <para>If you want to use long ticket lifetimes (a week, + for example) and you are using + <application>OpenSSH</application> to connect to the + machine where your ticket is stored, make sure that + <application>Kerberos</application> + <option>TicketCleanup</option> is set to + <literal>no</literal> in your + <filename>sshd_config</filename> or else your tickets + will be deleted when you log out.</para> + </listitem> + + <listitem> + <para>Remember that host principals can have a longer + ticket lifetime as well. If your user principal has a + lifetime of a week but the host you are connecting to + has a lifetime of nine hours, you will have an expired + host principal in your cache and the ticket cache will + not work as expected.</para> + </listitem> + + <listitem> + <para>When setting up a <filename>krb5.dict</filename> + file to prevent specific bad passwords from being used + (the manual page for <command>kadmind</command> covers + this briefly), remember that it only applies to + principals that have a password policy assigned to them. + The <filename>krb5.dict</filename> files format is + simple: one string per line. Creating a symbolic link + to <filename>/usr/share/dict/words</filename> might be + useful.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Differences with the <acronym>MIT</acronym> + Port</title> + + <para>The major difference between the <acronym>MIT</acronym> + and Heimdal installs relates to the + <command>kadmin</command> program which has a different (but + equivalent) set of commands and uses a different protocol. + This has a large implications if your <acronym>KDC</acronym> + is <acronym>MIT</acronym> as you will not be able to use the + Heimdal <command>kadmin</command> program to administer your + <acronym>KDC</acronym> remotely (or vice versa, for that + matter).</para> + + <para>The client applications may also take slightly different + command line options to accomplish the same tasks. + Following the instructions on the <acronym>MIT</acronym> + <application>Kerberos</application> web site + (<ulink url="http://web.mit.edu/Kerberos/www/"></ulink>) is + recommended. Be careful of path issues: the + <acronym>MIT</acronym> port installs into + <filename class="directory">/usr/local/</filename> by default, + and the <quote>normal</quote> system applications may be run + instead of <acronym>MIT</acronym> if your + <envar>PATH</envar> environment variable lists the system + directories first.</para> + + <note> + <para>With the <acronym>MIT</acronym> + <filename role="package">security/krb5</filename> port that + is provided by &os;, be sure to read the + <filename>/usr/local/share/doc/krb5/README.FreeBSD</filename> + file installed by the port if you want to understand why + logins via <command>telnetd</command> and + <command>klogind</command> behave somewhat oddly. Most + importantly, correcting the <quote>incorrect permissions on + cache file</quote> behavior requires that the + <command>login.krb5</command> binary be used for + authentication so that it can properly change ownership for + the forwarded credentials.</para> + </note> + + <para>The <filename>rc.conf</filename> must also be modified + to contain the following configuration:</para> + + <programlisting>kerberos5_server="/usr/local/sbin/krb5kdc" +kadmind5_server="/usr/local/sbin/kadmind" +kerberos5_server_enable="YES" +kadmind5_server_enable="YES"</programlisting> + + <para>This is done because the applications for + <acronym>MIT</acronym> kerberos installs binaries in the + <filename class="directory">/usr/local</filename> + hierarchy.</para> + </sect2> + + <sect2> + <title>Mitigating Limitations Found in + <application>Kerberos</application></title> + + <indexterm> + <primary>Kerberos5</primary> + <secondary>limitations and shortcomings</secondary> + </indexterm> + + <sect3> + <title><application>Kerberos</application> is an + all-or-nothing approach</title> + + <para>Every service enabled on the network must be modified + to work with <application>Kerberos</application> (or be + otherwise secured against network attacks) or else the + users credentials could be stolen and re-used. An example + of this would be <application>Kerberos</application> + enabling all remote shells (via <command>rsh</command> and + <command>telnet</command>, for example) but not converting + the <acronym>POP3</acronym> mail server which sends + passwords in plain text.</para> + </sect3> + + <sect3> + <title><application>Kerberos</application> is Intended for + Single-User Workstations</title> + + <para>In a multi-user environment, + <application>Kerberos</application> is less secure. + This is because it stores the tickets in the + <filename class="directory">/tmp</filename> directory, which + is readable by all users. If a user is sharing a computer + with several other people simultaneously (i.e. + multi-user), it is possible that the user's tickets can be + stolen (copied) by another user.</para> + + <para>This can be overcome with the <literal>-c</literal> + filename command-line option or (preferably) the + <envar>KRB5CCNAME</envar> environment variable, but this + is rarely done. In principal, storing the ticket in the + users home directory and using simple file permissions can + mitigate this problem.</para> + </sect3> + + <sect3> + <title>The KDC is a Single Point of Failure</title> + + <para>By design, the <acronym>KDC</acronym> must be as + secure as the master password database is contained on it. + The <acronym>KDC</acronym> should have absolutely no other + services running on it and should be physically secured. + The danger is high because + <application>Kerberos</application> stores all passwords + encrypted with the same key (the <quote>master</quote> + key), which in turn is stored as a file on the + <acronym>KDC</acronym>.</para> + + <para>As a side note, a compromised master key is not quite + as bad as one might normally fear. The master key is only + used to encrypt the <application>Kerberos</application> + database and as a seed for the random number generator. + As long as access to your <acronym>KDC</acronym> is + secure, an attacker cannot do much with the master + key.</para> + + <para>Additionally, if the <acronym>KDC</acronym> is + unavailable (perhaps due to a denial of service attack or + network problems) the network services are unusable as + authentication can not be performed, a recipe for a + denial-of-service attack. This can alleviated with + multiple <acronym>KDC</acronym>s (a single master and one + or more slaves) and with careful implementation of + secondary or fall-back authentication + (<acronym>PAM</acronym> is excellent for this).</para> + </sect3> + + <sect3> + <title><application>Kerberos</application> + Shortcomings</title> + + <para><application>Kerberos</application> allows users, + hosts and services to authenticate between themselves. It + does not have a mechanism to authenticate the + <acronym>KDC</acronym> to the users, hosts or services. + This means that a trojanned <command>kinit</command> (for + example) could record all user names and passwords. + Something like + <filename role="package">security/tripwire</filename> or + other file system integrity checking tools can alleviate + this.</para> + </sect3> + </sect2> + + <sect2> + <title>Resources and further information</title> + + <indexterm> + <primary>Kerberos5</primary> + <secondary>external resources</secondary> + </indexterm> + + <itemizedlist> + <listitem> + <para><ulink + url="http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html"> + The <application>Kerberos</application> + FAQ</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://web.mit.edu/Kerberos/www/dialogue.html">Designing + an Authentication System: a Dialog in Four + Scenes</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://www.ietf.org/rfc/rfc1510.txt?number=1510">RFC + 1510, The <application>Kerberos</application> Network + Authentication Service (V5)</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://web.mit.edu/Kerberos/www/"><acronym>MIT</acronym> + <application>Kerberos</application> home + page</ulink></para> + </listitem> + + <listitem> + <para><ulink url="http://www.pdc.kth.se/heimdal/">Heimdal + <application>Kerberos</application> home + page</ulink></para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1 id="openssl"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + + <title>OpenSSL</title> + + <indexterm> + <primary>security</primary> + <secondary>OpenSSL</secondary> + </indexterm> + + <para>One feature that many users overlook is the + <application>OpenSSL</application> toolkit included in &os;. + <application>OpenSSL</application> provides an encryption + transport layer on top of the normal communications layer; + thus allowing it to be intertwined with many network + applications and services.</para> + + <para>Some uses of <application>OpenSSL</application> may + include encrypted authentication of mail clients, web based + transactions such as credit card payments and more. Many + ports such as + <filename role="package">www/apache22</filename>, and + <filename role="package">mail/claws-mail</filename> will offer + compilation support for building with + <application>OpenSSL</application>.</para> + + <note> + <para>In most cases the Ports Collection will attempt to build + the <filename role="package">security/openssl</filename> + port unless the <makevar>WITH_OPENSSL_BASE</makevar> make + variable is explicitly set to <quote>yes</quote>.</para> + </note> + + <para>The version of <application>OpenSSL</application> included + in &os; supports Secure Sockets Layer v2/v3 (SSLv2/SSLv3), + Transport Layer Security v1 (TLSv1) network security protocols + and can be used as a general cryptographic library.</para> + + <note> + <para>While <application>OpenSSL</application> supports the + <acronym>IDEA</acronym> algorithm, it is disabled by default + due to United States patents. To use it, the license should + be reviewed and, if the restrictions are acceptable, the + <makevar>MAKE_IDEA</makevar> variable must be set in + <filename>make.conf</filename>.</para> + </note> + + <para>One of the most common uses of + <application>OpenSSL</application> is to provide certificates + for use with software applications. These certificates ensure + that the credentials of the company or individual are valid + and not fraudulent. If the certificate in question has not + been verified by one of the several <quote>Certificate + Authorities</quote>, or <acronym>CA</acronym>s, a warning is + usually produced. A Certificate Authority is a company, such + as <ulink url="http://www.verisign.com">VeriSign</ulink>, + which will sign certificates in order to validate credentials + of individuals or companies. This process has a cost + associated with it and is definitely not a requirement for + using certificates; however, it can put some of the more + paranoid users at ease.</para> + + <sect2> + <title>Generating Certificates</title> + + <indexterm> + <primary>OpenSSL</primary> + <secondary>certificate generation</secondary> + </indexterm> + + <para>To generate a certificate, the following command is + available:</para> + + <screen>&prompt.root; <userinput>openssl req -new -nodes -out req.pem -keyout cert.pem</userinput> +Generating a 1024 bit RSA private key +................++++++ +.......................................++++++ +writing new private key to 'cert.pem' +----- +You are about to be asked to enter information that will be incorporated +into your certificate request. +What you are about to enter is what is called a Distinguished Name or a DN. +There are quite a few fields but you can leave some blank +For some fields there will be a default value, +If you enter '.', the field will be left blank. +----- +Country Name (2 letter code) [AU]:<userinput><replaceable>US</replaceable></userinput> +State or Province Name (full name) [Some-State]:<userinput><replaceable>PA</replaceable></userinput> +Locality Name (eg, city) []:<userinput><replaceable>Pittsburgh</replaceable></userinput> +Organization Name (eg, company) [Internet Widgits Pty Ltd]:<userinput><replaceable>My Company</replaceable></userinput> +Organizational Unit Name (eg, section) []:<userinput><replaceable>Systems Administrator</replaceable></userinput> +Common Name (eg, YOUR name) []:<userinput><replaceable>localhost.example.org</replaceable></userinput> +Email Address []:<userinput><replaceable>trhodes@FreeBSD.org</replaceable></userinput> + +Please enter the following 'extra' attributes +to be sent with your certificate request +A challenge password []:<userinput><replaceable>SOME PASSWORD</replaceable></userinput> +An optional company name []:<userinput><replaceable>Another Name</replaceable></userinput></screen> + + <para>Notice the response directly after the + <quote>Common Name</quote> prompt shows a domain name. This + prompt requires a server name to be entered for verification + purposes; placing anything but a domain name would yield a + useless certificate. Other options, for instance expire + time, alternate encryption algorithms, etc. are available. + A complete list may be obtained by viewing the + &man.openssl.1; manual page.</para> + + <para>Two files should now exist in the directory in which the + aforementioned command was issued. The certificate request, + <filename>req.pem</filename>, may be sent to a certificate + authority who will validate the credentials that you + entered, sign the request and return the certificate to you. + The second file created will be named + <filename>cert.pem</filename> and is the private key for the + certificate and should be protected at all costs; if this + falls in the hands of others it can be used to impersonate + you (or your server).</para> + + <para>In cases where a signature from a <acronym>CA</acronym> + is not required, a self signed certificate can be created. + First, generate the <acronym>RSA</acronym> key:</para> + + <screen>&prompt.root; <userinput>openssl dsaparam -rand -genkey -out <filename>myRSA.key</filename> 1024</userinput></screen> + + <para>Next, generate the <acronym>CA</acronym> key:</para> + + <screen>&prompt.root; <userinput>openssl gendsa -des3 -out <filename>myca.key</filename> <filename>myRSA.key</filename></userinput></screen> + + <para>Use this key to create the certificate:</para> + + <screen>&prompt.root; <userinput>openssl req -new -x509 -days 365 -key <filename>myca.key</filename> -out <filename>new.crt</filename></userinput></screen> + + <para>Two new files should appear in the directory: a + certificate authority signature file, + <filename>myca.key</filename> and the certificate itself, + <filename>new.crt</filename>. These should be placed in a + directory, preferably under + <filename class="directory">/etc</filename>, which is readable + only by <username>root</username>. Permissions of 0700 should + be fine for this and they can be set with the + <command>chmod</command> utility.</para> + </sect2> + + <sect2> + <title>Using Certificates, an Example</title> + + <para>So what can these files do? A good use would be to + encrypt connections to the + <application>Sendmail</application> <acronym>MTA</acronym>. + This would dissolve the use of clear text authentication for + users who send mail via the local + <acronym>MTA</acronym>.</para> + + <note> + <para>This is not the best use in the world as some + <acronym>MUA</acronym>s will present the user with an + error if they have not installed the certificate locally. + Refer to the documentation included with the software for + more information on certificate installation.</para> + </note> + + <para>The following lines should be placed inside the local + <filename>.mc</filename> file:</para> + + <programlisting>dnl SSL Options +define(`confCACERT_PATH',`/etc/certs')dnl +define(`confCACERT',`/etc/certs/new.crt')dnl +define(`confSERVER_CERT',`/etc/certs/new.crt')dnl +define(`confSERVER_KEY',`/etc/certs/myca.key')dnl +define(`confTLS_SRV_OPTIONS', `V')dnl</programlisting> + + <para>Where <filename class="directory">/etc/certs/</filename> + is the directory to be used for storing the certificate and + key files locally. The last few requirements are a rebuild + of the local <filename>.cf</filename> file. This is easily + achieved by typing <command>make + <maketarget>install</maketarget></command> within the + <filename class="directory">/etc/mail</filename> directory. + Follow that up with <command>make + <maketarget>restart</maketarget></command> which should + start the <application>Sendmail</application> daemon.</para> + + <para>If all went well there will be no error messages in the + <filename>/var/log/maillog</filename> file and + <application>Sendmail</application> will show up in the + process list.</para> + + <para>For a simple test, simply connect to the mail server + using the &man.telnet.1; utility:</para> + + <screen>&prompt.root; <userinput>telnet <replaceable>example.com</replaceable> 25</userinput> +Trying 192.0.34.166... +Connected to <hostid role="fqdn">example.com</hostid>. +Escape character is '^]'. +220 <hostid role="fqdn">example.com</hostid> ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT) +<userinput>ehlo <replaceable>example.com</replaceable></userinput> +250-example.com Hello example.com [192.0.34.166], pleased to meet you +250-ENHANCEDSTATUSCODES +250-PIPELINING +250-8BITMIME +250-SIZE +250-DSN +250-ETRN +250-AUTH LOGIN PLAIN +250-STARTTLS +250-DELIVERBY +250 HELP +<userinput>quit</userinput> +221 2.0.0 <hostid role="fqdn">example.com</hostid> closing connection +Connection closed by foreign host.</screen> + + <para>If the <quote>STARTTLS</quote> line appears in the + output then everything is working correctly.</para> + </sect2> + </sect1> + + <sect1 id="ipsec"> + <sect1info> + <authorgroup> + <author> + <firstname>Nik</firstname> + <surname>Clayton</surname> + <affiliation> + <address><email>nik@FreeBSD.org</email></address> + </affiliation> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect1info> + + <indexterm> + <primary>IPsec</primary> + </indexterm> + + <title>VPN over IPsec</title> + + <para>Creating a VPN between two networks, separated by the + Internet, using FreeBSD gateways.</para> + + <sect2> + <sect2info> + <authorgroup> + <author> + <firstname>Hiten M.</firstname> + <surname>Pandya</surname> + <affiliation> + <address><email>hmp@FreeBSD.org</email></address> + </affiliation> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>Understanding IPsec</title> + + <para>This section will guide you through the process of + setting up IPsec. In order to set up IPsec, it is necessary + that you are familiar with the concepts of building a custom + kernel (see <xref linkend="kernelconfig">).</para> + + <para><emphasis>IPsec</emphasis> is a protocol which sits on + top of the Internet Protocol (IP) layer. It allows two or + more hosts to communicate in a secure manner (hence the + name). The FreeBSD IPsec <quote>network stack</quote> is + based on the <ulink url="http://www.kame.net/">KAME</ulink> + implementation, which has support for both protocol + families, IPv4 and IPv6.</para> + + <indexterm> + <primary>IPsec</primary> + <secondary>ESP</secondary> + </indexterm> + + <indexterm> + <primary>IPsec</primary> + <secondary>AH</secondary> + </indexterm> + + <para>IPsec consists of two sub-protocols:</para> + + <itemizedlist> + <listitem> + <para><emphasis>Encapsulated Security Payload + ESP)</emphasis>, protects the IP packet data from + third party interference, by encrypting the contents + using symmetric cryptography algorithms (like Blowfish, + 3DES).</para> + </listitem> + + <listitem> + <para><emphasis>Authentication Header (AH)</emphasis>, + protects the IP packet header from third party + interference and spoofing, by computing a cryptographic + checksum and hashing the IP packet header fields with a + secure hashing function. This is then followed by an + additional header that contains the hash, to allow the + information in the packet to be authenticated.</para> + </listitem> + </itemizedlist> + + <para><acronym>ESP</acronym> and <acronym>AH</acronym> can + either be used together or separately, depending on the + environment.</para> + + <indexterm> + <primary>VPN</primary> + </indexterm> + + <indexterm> + <primary>virtual private network</primary> + <see>VPN</see> + </indexterm> + + <para>IPsec can either be used to directly encrypt the traffic + between two hosts (known as <emphasis>Transport + Mode</emphasis>); or to build <quote>virtual + tunnels</quote> between two subnets, which could be used for + secure communication between two corporate networks (known + as <emphasis>Tunnel Mode</emphasis>). The latter is more + commonly known as a <emphasis>Virtual Private Network + (VPN)</emphasis>. The &man.ipsec.4; manual page should be + consulted for detailed information on the IPsec subsystem in + FreeBSD.</para> + + <para>To add IPsec support to your kernel, add the following + options to your kernel configuration file:</para> + + <indexterm> + <primary>kernel options</primary> + <secondary>IPSEC</secondary> + </indexterm> + + <screen> +options IPSEC #IP security +device crypto</screen> + + <indexterm> + <primary>kernel options</primary> + <secondary>IPSEC_DEBUG</secondary> + </indexterm> + + <para>If IPsec debugging support is desired, the following + kernel option should also be added:</para> + + <screen> +options IPSEC_DEBUG #debug for IP security</screen> + </sect2> + + <sect2> + <title>The Problem</title> + + <para>There is no standard for what constitutes a VPN. VPNs + can be implemented using a number of different technologies, + each of which have their own strengths and weaknesses. This + section presents a scenario, and the strategies used for + implementing a VPN for this scenario.</para> + </sect2> + + <sect2> + <title>The Scenario: Two networks, one home based and one + corporate based. Both are connected to the Internet, and + expected, via this <acronym>VPN</acronym> to behave as + one.</title> + + <indexterm> + <primary>VPN</primary> + <secondary>creating</secondary> + </indexterm> + + <para>The premise is as follows:</para> + + <itemizedlist> + <listitem> + <para>You have at least two sites</para> + </listitem> + + <listitem> + <para>Both sites are using IP internally</para> + </listitem> + + <listitem> + <para>Both sites are connected to the Internet, through a + gateway that is running FreeBSD.</para> + </listitem> + + <listitem> + <para>The gateway on each network has at least one public + IP address.</para> + </listitem> + + <listitem> + <para>The internal addresses of the two networks can be + public or private IP addresses, it does not matter. + They just may not collide; e.g.: may not both use + <hostid role="ipaddr">192.168.1.x</hostid>.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <sect2info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <affiliation> + <address><email>trhodes@FreeBSD.org</email></address> + </affiliation> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>Configuring IPsec on &os;</title> + + <para>To begin, the + <filename role="package">security/ipsec-tools</filename> + must be installed from the Ports Collection. This third + party software package provides a number of applications + which will help support the configuration.</para> + + <para>The next requirement is to create two &man.gif.4; + pseudo-devices which will be used to tunnel packets and + allow both networks to communicate properly. As + <username>root</username>, run the following commands, + replacing the <replaceable>internal</replaceable> and + <replaceable>external</replaceable> items with the real + internal and external gateways:</para> + + <screen>&prompt.root; <userinput>ifconfig gif0 create</userinput></screen> + + <screen>&prompt.root; <userinput>ifconfig gif0 <replaceable>internal1 internal2</replaceable></userinput></screen> + + <screen>&prompt.root; <userinput>ifconfig gif0 tunnel <replaceable>external1 external2</replaceable></userinput></screen> + + <para>For example, the corporate <acronym>LAN</acronym>'s + public <acronym>IP</acronym> is + <hostid role="ipaddr">172.16.5.4</hostid> having a private + <acronym>IP</acronym> of + <hostid role="ipaddr">10.246.38.1</hostid>. The home + <acronym>LAN</acronym>'s public <acronym>IP</acronym> is + <hostid role="ipaddr">192.168.1.12</hostid> with an internal + private <acronym>IP</acronym> of + <hostid role="ipaddr">10.0.0.5</hostid>.</para> + + <para>This may seem confusing, so review the following example + output from the &man.ifconfig.8; command:</para> + + <programlisting>Gateway 1: + +gif0: flags=8051 mtu 1280 +tunnel inet 172.16.5.4 --> 192.168.1.12 +inet6 fe80::2e0:81ff:fe02:5881%gif0 prefixlen 64 scopeid 0x6 +inet 10.246.38.1 --> 10.0.0.5 netmask 0xffffff00 + +Gateway 2: + +gif0: flags=8051 mtu 1280 +tunnel inet 192.168.1.12 --> 172.16.5.4 +inet 10.0.0.5 --> 10.246.38.1 netmask 0xffffff00 +inet6 fe80::250:bfff:fe3a:c1f%gif0 prefixlen 64 scopeid 0x4</programlisting> + + <para>Once complete, both private <acronym>IP</acronym>s + should be reachable using the &man.ping.8; command like + the following output suggests:</para> + + <programlisting>priv-net# ping 10.0.0.5 +PING 10.0.0.5 (10.0.0.5): 56 data bytes +64 bytes from 10.0.0.5: icmp_seq=0 ttl=64 time=42.786 ms +64 bytes from 10.0.0.5: icmp_seq=1 ttl=64 time=19.255 ms +64 bytes from 10.0.0.5: icmp_seq=2 ttl=64 time=20.440 ms +64 bytes from 10.0.0.5: icmp_seq=3 ttl=64 time=21.036 ms +--- 10.0.0.5 ping statistics --- +4 packets transmitted, 4 packets received, 0% packet loss +round-trip min/avg/max/stddev = 19.255/25.879/42.786/9.782 ms + +corp-net# ping 10.246.38.1 +PING 10.246.38.1 (10.246.38.1): 56 data bytes +64 bytes from 10.246.38.1: icmp_seq=0 ttl=64 time=28.106 ms +64 bytes from 10.246.38.1: icmp_seq=1 ttl=64 time=42.917 ms +64 bytes from 10.246.38.1: icmp_seq=2 ttl=64 time=127.525 ms +64 bytes from 10.246.38.1: icmp_seq=3 ttl=64 time=119.896 ms +64 bytes from 10.246.38.1: icmp_seq=4 ttl=64 time=154.524 ms +--- 10.246.38.1 ping statistics --- +5 packets transmitted, 5 packets received, 0% packet loss +round-trip min/avg/max/stddev = 28.106/94.594/154.524/49.814 ms</programlisting> + + <para>As expected, both sides have the ability to send and + receive <acronym>ICMP</acronym> packets from the privately + configured addresses. Next, both gateways must be told how + to route packets in order to correctly send traffic from + either network. The following command will achieve this + goal:</para> + + <screen>&prompt.root; <userinput>corp-net# route add <replaceable>10.0.0.0 10.0.0.5 255.255.255.0</replaceable></userinput></screen> + + <screen>&prompt.root; <userinput>corp-net# route add net <replaceable>10.0.0.0: gateway 10.0.0.5</replaceable></userinput></screen> + + <screen>&prompt.root; <userinput>priv-net# route add <replaceable>10.246.38.0 10.246.38.1 255.255.255.0</replaceable></userinput></screen> + + <screen>&prompt.root; <userinput>priv-net# route add host <replaceable>10.246.38.0: gateway 10.246.38.1</replaceable></userinput></screen> + + <para>At this point, internal machines should be reachable + from each gateway as well as from machines behind the + gateways. This is easily determined from the following + example:</para> + + <programlisting>corp-net# ping 10.0.0.8 +PING 10.0.0.8 (10.0.0.8): 56 data bytes +64 bytes from 10.0.0.8: icmp_seq=0 ttl=63 time=92.391 ms +64 bytes from 10.0.0.8: icmp_seq=1 ttl=63 time=21.870 ms +64 bytes from 10.0.0.8: icmp_seq=2 ttl=63 time=198.022 ms +64 bytes from 10.0.0.8: icmp_seq=3 ttl=63 time=22.241 ms +64 bytes from 10.0.0.8: icmp_seq=4 ttl=63 time=174.705 ms +--- 10.0.0.8 ping statistics --- +5 packets transmitted, 5 packets received, 0% packet loss +round-trip min/avg/max/stddev = 21.870/101.846/198.022/74.001 ms + +priv-net# ping 10.246.38.107 +PING 10.246.38.1 (10.246.38.107): 56 data bytes +64 bytes from 10.246.38.107: icmp_seq=0 ttl=64 time=53.491 ms +64 bytes from 10.246.38.107: icmp_seq=1 ttl=64 time=23.395 ms +64 bytes from 10.246.38.107: icmp_seq=2 ttl=64 time=23.865 ms +64 bytes from 10.246.38.107: icmp_seq=3 ttl=64 time=21.145 ms +64 bytes from 10.246.38.107: icmp_seq=4 ttl=64 time=36.708 ms +--- 10.246.38.107 ping statistics --- +5 packets transmitted, 5 packets received, 0% packet loss +round-trip min/avg/max/stddev = 21.145/31.721/53.491/12.179 ms</programlisting> + + <para>Setting up the tunnels is the easy part. Configuring + a secure link is a much more in depth process. The + following configuration uses pre-shared + (<acronym>PSK</acronym>) <acronym>RSA</acronym> keys. Aside + from the <acronym>IP</acronym> addresses, both + <filename>/usr/local/etc/racoon/racoon.conf</filename> files + will be identical and look similar to</para> + + <programlisting>path pre_shared_key "/usr/local/etc/racoon/psk.txt"; #location of pre-shared key file +log debug; #log verbosity setting: set to 'notify' when testing and debugging is complete + +padding # options are not to be changed +{ + maximum_length 20; + randomize off; + strict_check off; + exclusive_tail off; +} + +timer # timing options. change as needed +{ + counter 5; + interval 20 sec; + persend 1; +# natt_keepalive 15 sec; + phase1 30 sec; + phase2 15 sec; +} + +listen # address [port] that racoon will listening on +{ + isakmp 172.16.5.4 [500]; + isakmp_natt 172.16.5.4 [4500]; +} + +remote 192.168.1.12 [500] +{ + exchange_mode main,aggressive; + doi ipsec_doi; + situation identity_only; + my_identifier address 172.16.5.4; + peers_identifier address 192.168.1.12; + lifetime time 8 hour; + passive off; + proposal_check obey; +# nat_traversal off; + generate_policy off; + + proposal { + encryption_algorithm blowfish; + hash_algorithm md5; + authentication_method pre_shared_key; + lifetime time 30 sec; + dh_group 1; + } +} + +sainfo (address 10.246.38.0/24 any address 10.0.0.0/24 any) # address $network/$netmask $type address $network/$netmask $type ( $type being any or esp) +{ # $network must be the two internal networks you are joining. + pfs_group 1; + lifetime time 36000 sec; + encryption_algorithm blowfish,3des,des; + authentication_algorithm hmac_md5,hmac_sha1; + compression_algorithm deflate; +}</programlisting> + + <para>Explaining every available option, along with those + listed in these examples is beyond the scope of this + document. There is plenty of relevant information in the + <application>racoon</application> configuration manual + page.</para> + + <para>The <acronym>SPD</acronym> policies need to be + configured so &os; and <application>racoon</application> is + able to encrypt and decrypt network traffic between + hosts.</para> + + <para>This task may be undertaken with a simple shell script + similar to the following which is on the corporate gateway. + This file will be used during system initialization and + should be saved as + <filename>/usr/local/etc/racoon/setkey.conf</filename>.</para> + + <programlisting>flush; +spdflush; +# To the home network +spdadd 10.246.38.0/24 10.0.0.0/24 any -P out ipsec esp/tunnel/172.16.5.4-192.168.1.12/use; +spdadd 10.0.0.0/24 10.246.38.0/24 any -P in ipsec esp/tunnel/192.168.1.12-172.16.5.4/use;</programlisting> + + <para>Once in place, <application>racoon</application> may be + started on both gateways using the following command:</para> + + <screen>&prompt.root; <userinput>/usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf -l /var/log/racoon.log</userinput></screen> + + <para>The output should be similar to the following:</para> + + <programlisting>corp-net# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf +Foreground mode. +2006-01-30 01:35:47: INFO: begin Identity Protection mode. +2006-01-30 01:35:48: INFO: received Vendor ID: KAME/racoon +2006-01-30 01:35:55: INFO: received Vendor ID: KAME/racoon +2006-01-30 01:36:04: INFO: ISAKMP-SA established 172.16.5.4[500]-192.168.1.12[500] spi:623b9b3bd2492452:7deab82d54ff704a +2006-01-30 01:36:05: INFO: initiate new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0] +2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=28496098(0x1b2d0e2) +2006-01-30 01:36:09: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=47784998(0x2d92426) +2006-01-30 01:36:13: INFO: respond new phase 2 negotiation: 172.16.5.4[0]192.168.1.12[0] +2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=124397467(0x76a279b) +2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=175852902(0xa7b4d66)</programlisting> + + <para>To ensure the tunnel is working properly, switch to + another console and use &man.tcpdump.1; to view network + traffic using the following command. Replace + <literal>em0</literal> with the network interface card as + required.</para> + + <screen>&prompt.root; <userinput>tcpdump -i em0 host <replaceable>172.16.5.4 and dst 192.168.1.12</replaceable></userinput></screen> + + <para>Data similar to the following should appear on the + console. If not, there is an issue, and debugging the + returned data will be required.</para> + + <programlisting>01:47:32.021683 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xa) +01:47:33.022442 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xb) +01:47:34.024218 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xc)</programlisting> + + <para>At this point, both networks should be available and + seem to be part of the same network. Most likely both + networks are protected by a firewall, as they should be. To + allow traffic to flow between them, rules need to be added + to pass packets back and forth. For the &man.ipfw.8; + firewall, add the following lines to the firewall + configuration file:</para> + + <programlisting>ipfw add 00201 allow log esp from any to any +ipfw add 00202 allow log ah from any to any +ipfw add 00203 allow log ipencap from any to any +ipfw add 00204 allow log udp from any 500 to any</programlisting> + + <note> + <para>The rule numbers may need to be altered depending on + the current host configuration.</para> + </note> + + <para>For users of &man.pf.4; or &man.ipf.8;, the following + rules should do the trick:</para> + + <programlisting>pass in quick proto esp from any to any +pass in quick proto ah from any to any +pass in quick proto ipencap from any to any +pass in quick proto udp from any port = 500 to any port = 500 +pass in quick on gif0 from any to any +pass out quick proto esp from any to any +pass out quick proto ah from any to any +pass out quick proto ipencap from any to any +pass out quick proto udp from any port = 500 to any port = 500 +pass out quick on gif0 from any to any</programlisting> + + <para>Finally, to allow the machine to start support for the + <acronym>VPN</acronym> during system initialization, add the + following lines to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>ipsec_enable="YES" +ipsec_program="/usr/local/sbin/setkey" +ipsec_file="/usr/local/etc/racoon/setkey.conf" # allows setting up spd policies on boot +racoon_enable="yes"</programlisting> + </sect2> + </sect1> + + <sect1 id="openssh"> + <sect1info> + <authorgroup> + <author> + <firstname>Chern</firstname> + <surname>Lee</surname> + <contrib>Contributed by </contrib> + </author> + <!-- 21 April 2001 --> + </authorgroup> + </sect1info> + + <title>OpenSSH</title> + + <indexterm><primary>OpenSSH</primary></indexterm> + <indexterm> + <primary>security</primary> + <secondary>OpenSSH</secondary> + </indexterm> + + <para><application>OpenSSH</application> is a set of network + connectivity tools used to access remote machines securely. + It can be used as a direct replacement for + <command>rlogin</command>, <command>rsh</command>, + <command>rcp</command>, and <command>telnet</command>. + Additionally, TCP/IP connections can be tunneled/forwarded + securely through SSH. <application>OpenSSH</application> + encrypts all traffic to effectively eliminate eavesdropping, + connection hijacking, and other network-level attacks.</para> + + <para><application>OpenSSH</application> is maintained by the + OpenBSD project, and is based upon SSH v1.2.12 with all the + recent bug fixes and updates. It is compatible with both SSH + protocols 1 and 2.</para> + + <sect2> + <title>Advantages of Using OpenSSH</title> + + <para>Normally, when using &man.telnet.1; or &man.rlogin.1;, + data is sent over the network in a clear, un-encrypted form. + Network sniffers anywhere in between the client and server + can steal your user/password information or data transferred + in your session. <application>OpenSSH</application> offers + a variety of authentication and encryption methods to + prevent this from happening.</para> + </sect2> + + <sect2> + <title>Enabling <application>sshd</application></title> + + <indexterm> + <primary>OpenSSH</primary> + <secondary>enabling</secondary> + </indexterm> + + <para>The <application>sshd</application> is an option + presented during a <literal>Standard</literal> install of + &os;. To see if <application>sshd</application> is enabled, + check the <filename>rc.conf</filename> file for:</para> + + <programlisting>sshd_enable="YES"</programlisting> + + <para>This will load &man.sshd.8;, the daemon program for + <application>OpenSSH</application>, the next time your + system initializes. Alternatively, it is possible to use + <filename>/etc/rc.d/sshd</filename> &man.rc.8; script to + start <application>OpenSSH</application>:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/sshd start</userinput></screen> + </sect2> + + <sect2> + <title>SSH Client</title> + + <indexterm> + <primary>OpenSSH</primary> + <secondary>client</secondary> + </indexterm> + + <para>The &man.ssh.1; utility works similarly to + &man.rlogin.1;.</para> + + <screen>&prompt.root; <userinput>ssh <replaceable>user@example.com</replaceable></userinput> +Host key not found from the list of known hosts. +Are you sure you want to continue connecting (yes/no)? <userinput>yes</userinput> +Host 'example.com' added to the list of known hosts. +user@example.com's password: <userinput>*******</userinput></screen> + + <para>The login will continue just as it would have if a + session was created using <command>rlogin</command> or + <command>telnet</command>. SSH utilizes a key fingerprint + system for verifying the authenticity of the server when the + client connects. The user is prompted to enter + <literal>yes</literal> only when connecting for the first + time. Future attempts to login are all verified against the + saved fingerprint key. The SSH client will alert you if the + saved fingerprint differs from the received fingerprint on + future login attempts. The fingerprints are saved in + <filename>~/.ssh/known_hosts</filename>, or + <filename>~/.ssh/known_hosts2</filename> for SSH v2 + fingerprints.</para> + + <para>By default, recent versions of the + <application>OpenSSH</application> servers only accept SSH + v2 connections. The client will use version 2 if possible + and will fall back to version 1. The client can also be + forced to use one or the other by passing it the + <option>-1</option> or <option>-2</option> for version 1 or + version 2, respectively. The version 1 compatibility is + maintained in the client for backwards compatibility with + older versions.</para> + </sect2> + + <sect2> + <title>Secure Copy</title> + + <indexterm> + <primary>OpenSSH</primary> + <secondary>secure copy</secondary> + </indexterm> + <indexterm> + <primary><command>scp</command></primary> + </indexterm> + + <para>The &man.scp.1; command works similarly to &man.rcp.1;; + it copies a file to or from a remote machine, except in a + secure fashion.</para> + + <screen>&prompt.root; <userinput> scp <replaceable>user@example.com:/COPYRIGHT COPYRIGHT</replaceable></userinput> +user@example.com's password: <userinput>*******</userinput> +COPYRIGHT 100% |*****************************| 4735 +00:00 +&prompt.root;</screen> + + <para>Since the fingerprint was already saved for this host in + the previous example, it is verified when using &man.scp.1; + here.</para> + + <para>The arguments passed to &man.scp.1; are similar to + &man.cp.1;, with the file or files in the first argument, + and the destination in the second. Since the file is + fetched over the network, through SSH, one or more of the + file arguments takes on the form + <option>user@host:<path_to_remote_file></option>.</para> + </sect2> + + <sect2> + <title>Configuration</title> + + <indexterm> + <primary>OpenSSH</primary> + <secondary>configuration</secondary> + </indexterm> + + <para>The system-wide configuration files for both the + <application>OpenSSH</application> daemon and client reside + within the <filename class="directory">/etc/ssh</filename> + directory.</para> + + <para><filename>ssh_config</filename> configures the client + settings, while <filename>sshd_config</filename> configures + the daemon.</para> + + <para>Additionally, the <option>sshd_program</option> + (<filename>/usr/sbin/sshd</filename> by default), and + <option>sshd_flags</option> <filename>rc.conf</filename> + options can provide more levels of configuration.</para> + </sect2> + + <sect2 id="security-ssh-keygen"> + <title><application>ssh-keygen</application></title> + + <para>Instead of using passwords, &man.ssh-keygen.1; can + be used to generate DSA or RSA keys to authenticate a + user:</para> + + <screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>dsa</replaceable></userinput> +Generating public/private dsa key pair. +Enter file in which to save the key (/home/user/.ssh/id_dsa): +Created directory '/home/user/.ssh'. +Enter passphrase (empty for no passphrase): +Enter same passphrase again: +Your identification has been saved in /home/user/.ssh/id_dsa. +Your public key has been saved in /home/user/.ssh/id_dsa.pub. +The key fingerprint is: +bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com</screen> + + <para>&man.ssh-keygen.1; will create a public and private key + pair for use in authentication. The private key is stored + in <filename>~/.ssh/id_dsa</filename> or + <filename>~/.ssh/id_rsa</filename>, whereas the public key + is stored in <filename>~/.ssh/id_dsa.pub</filename> or + <filename>~/.ssh/id_rsa.pub</filename>, respectively for + <acronym>DSA</acronym> and <acronym>RSA</acronym> key types. + The public key must be placed in the + <filename>~/.ssh/authorized_keys</filename> file of the + remote machine for both <acronym>RSA</acronym> or + <acronym>DSA</acronym> keys in order for the setup to + work.</para> + + <para>This will allow connection to the remote machine based + upon SSH keys instead of passwords.</para> + + <para>If a passphrase is used in &man.ssh-keygen.1;, the user + will be prompted for a password each time in order to use + the private key. &man.ssh-agent.1; can alleviate the strain + of repeatedly entering long passphrases, and is explored in + the <xref linkend="security-ssh-agent"> section + below.</para> + + <warning> + <para>The various options and files can be different + according to the <application>OpenSSH</application> + version you have on your system; to avoid problems you + should consult the &man.ssh-keygen.1; manual page.</para> + </warning> + </sect2> + + <sect2 id="security-ssh-agent"> + <title><application>ssh-agent</application> and <application>ssh-add</application></title> + + <para>The &man.ssh-agent.1; and &man.ssh-add.1; utilities + provide methods for <application>SSH</application> keys to + be loaded into memory for use, without needing to type the + passphrase each time.</para> + + <para>The &man.ssh-agent.1; utility will handle the + authentication using the private key(s) that are loaded into + it. &man.ssh-agent.1; should be used to launch another + application. At the most basic level, it could spawn a + shell or at a more advanced level, a window manager.</para> + + <para>To use &man.ssh-agent.1; in a shell, first it will need + to be spawned with a shell as an argument. Secondly, the + identity needs to be added by running &man.ssh-add.1; and + providing it the passphrase for the private key. Once these + steps have been completed the user will be able to + &man.ssh.1; to any host that has the corresponding public + key installed. For example:</para> + + <screen>&prompt.user; ssh-agent <replaceable>csh</replaceable> +&prompt.user; ssh-add +Enter passphrase for /home/user/.ssh/id_dsa: +Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa) +&prompt.user;</screen> + + <para>To use &man.ssh-agent.1; in X11, a call to + &man.ssh-agent.1; will need to be placed in + <filename>~/.xinitrc</filename>. This will provide the + &man.ssh-agent.1; services to all programs launched in X11. + An example <filename>~/.xinitrc</filename> file might look + like this:</para> + + <programlisting>exec ssh-agent <replaceable>startxfce4</replaceable></programlisting> + + <para>This would launch &man.ssh-agent.1;, which would in turn + launch <application>XFCE</application>, every time X11 + starts. Then once that is done and X11 has been restarted so + that the changes can take effect, simply run &man.ssh-add.1; + to load all of your SSH keys.</para> + </sect2> + + <sect2 id="security-ssh-tunneling"> + <title>SSH Tunneling</title> + + <indexterm> + <primary>OpenSSH</primary> + <secondary>tunneling</secondary> + </indexterm> + + <para><application>OpenSSH</application> has the ability to + create a tunnel to encapsulate another protocol in an + encrypted session.</para> + + <para>The following command tells &man.ssh.1; to create a + tunnel for <application>telnet</application>:</para> + + <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5023:localhost:23 user@foo.example.com</replaceable></userinput> +&prompt.user;</screen> + + <para>The <command>ssh</command> command is used with the + following options:</para> + + <variablelist> + <varlistentry> + <term><option>-2</option></term> + + <listitem> + <para>Forces <command>ssh</command> to use version 2 of + the protocol. (Do not use if you are working with + older SSH servers)</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-N</option></term> + + <listitem> + <para>Indicates no command, or tunnel only. If omitted, + <command>ssh</command> would initiate a normal + session.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-f</option></term> + + <listitem> + <para>Forces <command>ssh</command> to run in the + background.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-L</option></term> + + <listitem> + <para>Indicates a local tunnel in + <replaceable>localport:remotehost:remoteport</replaceable> + fashion.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>user@foo.example.com</option></term> + + <listitem> + <para>The remote SSH server.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>An SSH tunnel works by creating a listen socket on + <hostid>localhost</hostid> on the specified port. It then + forwards any connection received on the local host/port via + the SSH connection to the specified remote host and + port.</para> + + <para>In the example, port <replaceable>5023</replaceable> on + <hostid>localhost</hostid> is being forwarded to port + <replaceable>23</replaceable> on <hostid>localhost</hostid> + of the remote machine. Since <replaceable>23</replaceable> + is <application>telnet</application>, this would create a + secure <application>telnet</application> session through an + SSH tunnel.</para> + + <para>This can be used to wrap any number of insecure TCP + protocols such as SMTP, POP3, FTP, etc.</para> + + <example> + <title>Using SSH to Create a Secure Tunnel for SMTP</title> + + <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5025:localhost:25 user@mailserver.example.com</replaceable></userinput> +user@mailserver.example.com's password: <userinput>*****</userinput> +&prompt.user; <userinput>telnet localhost 5025</userinput> +Trying 127.0.0.1... +Connected to localhost. +Escape character is '^]'. +220 mailserver.example.com ESMTP</screen> + + <para>This can be used in conjunction with an + &man.ssh-keygen.1; and additional user accounts to create + a more seamless/hassle-free SSH tunneling environment. + Keys can be used in place of typing a password, and the + tunnels can be run as a separate user.</para> + </example> + + <sect3> + <title>Practical SSH Tunneling Examples</title> + + <sect4> + <title>Secure Access of a POP3 Server</title> + + <para>At work, there is an SSH server that accepts + connections from the outside. On the same office + network resides a mail server running a POP3 server. + The network, or network path between your home and + office may or may not be completely trustable. Because + of this, you need to check your e-mail in a secure + manner. The solution is to create an SSH connection to + your office's SSH server, and tunnel through to the mail + server.</para> + + <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>2110:mail.example.com:110 user@ssh-server.example.com</replaceable></userinput> +user@ssh-server.example.com's password: <userinput>******</userinput></screen> + + <para>When the tunnel is up and running, you can point + your mail client to send POP3 requests to + + <hostid>localhost</hostid> port 2110. A connection here + will be forwarded securely across the tunnel to + <hostid>mail.example.com</hostid>.</para> + </sect4> + + <sect4> + <title>Bypassing a Draconian Firewall</title> + + <para>Some network administrators impose extremely + draconian firewall rules, filtering not only incoming + connections, but outgoing connections. You may be only + given access to contact remote machines on ports 22 and + 80 for SSH and web surfing.</para> + + <para>You may wish to access another (perhaps non-work + related) service, such as an Ogg Vorbis server to stream + music. If this Ogg Vorbis server is streaming on some + other port than 22 or 80, you will not be able to access + it.</para> + + <para>The solution is to create an SSH connection to a + machine outside of your network's firewall, and use it + to tunnel to the Ogg Vorbis server.</para> + + <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>8888:music.example.com:8000 user@unfirewalled-system.example.org</replaceable></userinput> +user@unfirewalled-system.example.org's password: <userinput>*******</userinput></screen> + + <para>Your streaming client can now be pointed to + <hostid>localhost</hostid> port 8888, which will be + forwarded over to <hostid>music.example.com</hostid> + port 8000, successfully evading the firewall.</para> + </sect4> + </sect3> + </sect2> + + <sect2> + <title>The <varname>AllowUsers</varname> Users Option</title> + + <para>It is often a good idea to limit which users can log in + and from where. The <literal>AllowUsers</literal> option is + a good way to accomplish this. For example, to only allow + the <username>root</username> user to log in from + <hostid role="ipaddr">192.168.1.32</hostid>, something like + this would be appropriate in the + <filename>/etc/ssh/sshd_config</filename> file:</para> + + <programlisting>AllowUsers root@192.168.1.32</programlisting> + + <para>To allow the user <username>admin</username> to log in + from anywhere, just list the username by itself:</para> + + <programlisting>AllowUsers admin</programlisting> + + <para>Multiple users should be listed on the same line, like + so:</para> + + <programlisting>AllowUsers root@192.168.1.32 admin</programlisting> + + <note> + <para>It is important that you list each user that needs to + log in to this machine; otherwise they will be locked + out.</para> + </note> + + <para>After making changes to + <filename>/etc/ssh/sshd_config</filename> you must tell + &man.sshd.8; to reload its config files, by running:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/sshd reload</userinput></screen> + </sect2> + + <sect2> + <title>Further Reading</title> + + <para><ulink + url="http://www.openssh.com/">OpenSSH</ulink></para> + + <para>&man.ssh.1; &man.scp.1; &man.ssh-keygen.1; + &man.ssh-agent.1; &man.ssh-add.1; &man.ssh.config.5;</para> + + <para>&man.sshd.8; &man.sftp-server.8; + &man.sshd.config.5;</para> + </sect2> + </sect1> + + <sect1 id="fs-acl"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <indexterm> + <primary>ACL</primary> + </indexterm> + + <title>File System Access Control Lists</title> + + <para>In conjunction with file system enhancements like + snapshots, FreeBSD offers the security of File System Access + Control Lists (<acronym>ACL</acronym>s).</para> + + <para>Access Control Lists extend the standard &unix; permission + model in a highly compatible (&posix;.1e) way. This feature + permits an administrator to make use of and take advantage of + a more sophisticated security model.</para> + + <para>To enable <acronym>ACL</acronym> support for + <acronym>UFS</acronym> file systems, the following:</para> + + <programlisting>options UFS_ACL</programlisting> + + <para>must be compiled into the kernel. If this option has not + been compiled in, a warning message will be displayed when + attempting to mount a file system supporting + <acronym>ACL</acronym>s. This option is included in the + <filename>GENERIC</filename> kernel. <acronym>ACL</acronym>s + rely on extended attributes being enabled on the file system. + Extended attributes are natively supported in the next + generation &unix; file system, <acronym>UFS2</acronym>.</para> + + <note> + <para>A higher level of administrative overhead is required to + configure extended attributes on <acronym>UFS1</acronym> + than on <acronym>UFS2</acronym>. The performance of + extended attributes on <acronym>UFS2</acronym> is also + substantially higher. As a result, <acronym>UFS2</acronym> + is generally recommended in preference to + <acronym>UFS1</acronym> for use with access control + lists.</para> + </note> + + <para><acronym>ACL</acronym>s are enabled by the mount-time + administrative flag, <option>acls</option>, which may be added + to <filename>/etc/fstab</filename>. The mount-time flag can + also be automatically set in a persistent manner using + &man.tunefs.8; to modify a superblock <acronym>ACL</acronym>s + flag in the file system header. In general, it is preferred + to use the superblock flag for several reasons:</para> + + <itemizedlist> + <listitem> + <para>The mount-time <acronym>ACL</acronym>s flag cannot be + changed by a remount (&man.mount.8; <option>-u</option>), + only by means of a complete &man.umount.8; and fresh + &man.mount.8;. This means that <acronym>ACL</acronym>s + cannot be enabled on the root file system after boot. It + also means that you cannot change the disposition of a + file system once it is in use.</para> + </listitem> + + <listitem> + <para>Setting the superblock flag will cause the file system + to always be mounted with <acronym>ACL</acronym>s enabled + even if there is not an <filename>fstab</filename> entry + or if the devices re-order. This prevents accidental + mounting of the file system without + <acronym>ACL</acronym>s enabled, which can result in + <acronym>ACL</acronym>s being improperly enforced, and + hence security problems.</para> + </listitem> + </itemizedlist> + + <note> + <para>We may change the <acronym>ACL</acronym>s behavior to + allow the flag to be enabled without a complete fresh + &man.mount.8;, but we consider it desirable to discourage + accidental mounting without <acronym>ACL</acronym>s enabled, + because you can shoot your feet quite nastily if you enable + <acronym>ACL</acronym>s, then disable them, then re-enable + them without flushing the extended attributes. In general, + once you have enabled <acronym>ACL</acronym>s on a file + system, they should not be disabled, as the resulting file + protections may not be compatible with those intended by the + users of the system, and re-enabling <acronym>ACL</acronym>s + may re-attach the previous <acronym>ACL</acronym>s to files + that have since had their permissions changed, resulting in + other unpredictable behavior.</para> + </note> + + <para>File systems with <acronym>ACL</acronym>s enabled will + show a <literal>+</literal> (plus) sign in their permission + settings when viewed. For example:</para> + + <programlisting>drwx------ 2 robert robert 512 Dec 27 11:54 private +drwxrwx---+ 2 robert robert 512 Dec 23 10:57 directory1 +drwxrwx---+ 2 robert robert 512 Dec 22 10:20 directory2 +drwxrwx---+ 2 robert robert 512 Dec 27 11:57 directory3 +drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html</programlisting> + + <para>Here we see that the + <filename class="directory">directory1</filename>, + <filename class="directory">directory2</filename>, and + <filename class="directory">directory3</filename> directories + are all taking advantage of <acronym>ACL</acronym>s. The + <filename class="directory">public_html</filename> directory + is not.</para> + + <sect2> + <title>Making Use of <acronym>ACL</acronym>s</title> + + <para>The file system <acronym>ACL</acronym>s can be viewed by + the &man.getfacl.1; utility. For instance, to view the + <acronym>ACL</acronym> settings on the + <filename>test</filename> file, one would use the + command:</para> + + <screen>&prompt.user; <userinput>getfacl <filename>test</filename></userinput> + #file:test + #owner:1001 + #group:1001 + user::rw- + group::r-- + other::r--</screen> + + <para>To change the <acronym>ACL</acronym> settings on this + file, invoke the &man.setfacl.1; utility. Observe:</para> + + <screen>&prompt.user; <userinput>setfacl -k <filename>test</filename></userinput></screen> + + <para>The <option>-k</option> flag will remove all of the + currently defined <acronym>ACL</acronym>s from a file or + file system. The more preferable method would be to use + <option>-b</option> as it leaves the basic fields required + for <acronym>ACL</acronym>s to work.</para> + + <screen>&prompt.user; <userinput>setfacl -m u:trhodes:rwx,group:web:r--,o::--- <filename>test</filename></userinput></screen> + + <para>In the aforementioned command, the <option>-m</option> + option was used to modify the default <acronym>ACL</acronym> + entries. Since there were no pre-defined entries, as they + were removed by the previous command, this will restore the + default options and assign the options listed. Take care to + notice that if you add a user or group which does not exist + on the system, an <errorname>Invalid argument</errorname> + error will be printed to + <devicename>stdout</devicename>.</para> + </sect2> + </sect1> + + <sect1 id="security-portaudit"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + + <indexterm> + <primary>Portaudit</primary> + </indexterm> + + <title>Monitoring Third Party Security Issues</title> + + <para>In recent years, the security world has made many + improvements to how vulnerability assessment is handled. The + threat of system intrusion increases as third party utilities + are installed and configured for virtually any operating + system available today.</para> + + <para>Vulnerability assessment is a key factor in security, and + while &os; releases advisories for the base system, doing so + for every third party utility is beyond the &os; Project's + capability. There is a way to mitigate third party + vulnerabilities and warn administrators of known security + issues. A &os; add on utility known as + <application>Portaudit</application> exists solely for this + purpose.</para> + + <para>The + <filename role="package">ports-mgmt/portaudit</filename> + port polls a database, updated and maintained by the &os; + Security Team and ports developers, for known security + issues.</para> + + <para>To begin using <application>Portaudit</application>, one + must install it from the Ports Collection:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/portaudit && make install clean</userinput></screen> + + <para>During the install process, the configuration files for + &man.periodic.8; will be updated, permitting + <application>Portaudit</application> output in the daily + security runs. Ensure the daily security run emails, which + are sent to <username>root</username>'s email account, are + being read. No more configuration will be required + here.</para> + + <para>After installation, an administrator can update the + database and view known vulnerabilities in installed packages + by invoking the following command:</para> + + <screen>&prompt.root; <userinput>portaudit -Fda</userinput></screen> + + <note> + <para>The database will automatically be updated during the + &man.periodic.8; run; thus, the previous command is + completely optional. It is only required for the following + examples.</para> + </note> + + <para>To audit the third party utilities installed as part of + the Ports Collection at anytime, an administrator need only + run the following command:</para> + + <screen>&prompt.root; <userinput>portaudit -a</userinput></screen> + + <para><application>Portaudit</application> will produce + something like this for vulnerable packages:</para> + + <programlisting>Affected package: cups-base-1.1.22.0_1 +Type of problem: cups-base -- HPGL buffer overflow vulnerability. +Reference: <http://www.FreeBSD.org/ports/portaudit/40a3bca2-6809-11d9-a9e7-0001020eed82.html> + +1 problem(s) in your installed packages found. + +You are advised to update or deinstall the affected package(s) immediately.</programlisting> + + <para>By pointing a web browser to the <acronym>URL</acronym> + shown, an administrator may obtain more information about the + vulnerability in question. This will include versions + affected, by &os; Port version, along with other web sites + which may contain security advisories.</para> + + <para>In short, <application>Portaudit</application> is a + powerful utility and extremely useful when coupled with the + <application>Portupgrade</application> port.</para> + </sect1> + + <sect1 id="security-advisories"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <indexterm> + <primary>FreeBSD Security Advisories</primary> + </indexterm> + + <title>&os; Security Advisories</title> + + <para>Like many production quality operating systems, &os; + publishes <quote>Security Advisories</quote>. These + advisories are usually mailed to the security lists and noted + in the Errata only after the appropriate releases have been + patched. This section will work to explain what an advisory + is, how to understand it, and what measures to take in order + to patch a system.</para> + + <sect2> + <title>What Does an Advisory Look Like?</title> + + <para>The &os; security advisories look similar to the one + below, taken from the &a.security-notifications.name; + mailing list.</para> + + <programlisting>============================================================================= +FreeBSD-SA-XX:XX.UTIL Security Advisory + The FreeBSD Project + +Topic: denial of service due to some problem <co id="co-topic"> + +Category: core <co id="co-category"> +Module: sys <co id="co-module"> +Announced: 2003-09-23 <co id="co-announce"> +Credits: Person <co id="co-credit"> +Affects: All releases of &os; <co id="co-affects"> + &os; 4-STABLE prior to the correction date +Corrected: 2003-09-23 16:42:59 UTC (RELENG_4, 4.9-PRERELEASE) + 2003-09-23 20:08:42 UTC (RELENG_5_1, 5.1-RELEASE-p6) + 2003-09-23 20:07:06 UTC (RELENG_5_0, 5.0-RELEASE-p15) + 2003-09-23 16:44:58 UTC (RELENG_4_8, 4.8-RELEASE-p8) + 2003-09-23 16:47:34 UTC (RELENG_4_7, 4.7-RELEASE-p18) + 2003-09-23 16:49:46 UTC (RELENG_4_6, 4.6-RELEASE-p21) + 2003-09-23 16:51:24 UTC (RELENG_4_5, 4.5-RELEASE-p33) + 2003-09-23 16:52:45 UTC (RELENG_4_4, 4.4-RELEASE-p43) + 2003-09-23 16:54:39 UTC (RELENG_4_3, 4.3-RELEASE-p39) <co id="co-corrected"> +<acronym>CVE</acronym> Name: CVE-XXXX-XXXX <co id="co-cve"> + +For general information regarding FreeBSD Security Advisories, +including descriptions of the fields above, security branches, and the +following sections, please visit +http://www.FreeBSD.org/security/. + +I. Background <co id="co-backround"> + + +II. Problem Description <co id="co-descript"> + + +III. Impact <co id="co-impact"> + + +IV. Workaround <co id="co-workaround"> + + +V. Solution <co id="co-solution"> + + +VI. Correction details <co id="co-details"> + + +VII. References <co id="co-ref"></programlisting> + + <calloutlist> + <callout arearefs="co-topic"> + <para>The <literal>Topic</literal> field indicates exactly + what the problem is. It is basically an introduction to + the current security advisory and notes the utility with + the vulnerability.</para> + </callout> + + <callout arearefs="co-category"> + <para>The <literal>Category</literal> refers to the + affected part of the system which may be one of + <literal>core</literal>, <literal>contrib</literal>, or + <literal>ports</literal>. The <literal>core</literal> + category means that the vulnerability affects a core + component of the &os; operating system. The + <literal>contrib</literal> category means that the + vulnerability affects software contributed to the &os; + Project, such as <application>sendmail</application>. + Finally the <literal>ports</literal> category indicates + that the vulnerability affects add on software available + as part of the Ports Collection.</para> + </callout> + + <callout arearefs="co-module"> + <para>The <literal>Module</literal> field refers to the + component location, for instance <literal>sys</literal>. + In this example, we see that the module, + <literal>sys</literal>, is affected; therefore, this + vulnerability affects a component used within the + kernel.</para> + </callout> + + <callout arearefs="co-announce"> + <para>The <literal>Announced</literal> field reflects the + date said security advisory was published, or announced + to the world. This means that the security team has + verified that the problem does exist and that a patch + has been committed to the &os; source code + repository.</para> + </callout> + + <callout arearefs="co-credit"> + <para>The <literal>Credits</literal> field gives credit to + the individual or organization who noticed the + vulnerability and reported it.</para> + </callout> + + <callout arearefs="co-affects"> + <para>The <literal>Affects</literal> field explains which + releases of &os; are affected by this vulnerability. + For the kernel, a quick look over the output from + <command>ident</command> on the affected files will help + in determining the revision. For ports, the version + number is listed after the port name in + <filename class="directory">/var/db/pkg</filename>. If + the system does not sync with the &os; + <acronym>CVS</acronym> repository and rebuild daily, + chances are that it is affected.</para> + </callout> + + <callout arearefs="co-corrected"> + <para>The <literal>Corrected</literal> field indicates the + date, time, time offset, and release that was + corrected.</para> + </callout> + + <callout arearefs="co-cve"> + <para>Reserved for the identification information used to + look up vulnerabilities in the Common Vulnerabilities + Database system.</para> + </callout> + + <callout arearefs="co-backround"> + <para>The <literal>Background</literal> field gives + information on exactly what the affected utility is. + Most of the time this is why the utility exists in &os;, + what it is used for, and a bit of information on how the + utility came to be.</para> + </callout> + + <callout arearefs="co-descript"> + <para>The <literal>Problem Description</literal> field + explains the security hole in depth. This can include + information on flawed code, or even how the utility + could be maliciously used to open a security + hole.</para> + </callout> + + <callout arearefs="co-impact"> + <para>The <literal>Impact</literal> field describes what + type of impact the problem could have on a system. For + example, this could be anything from a denial of service + attack, to extra privileges available to users, or even + giving the attacker superuser access.</para> + </callout> + + <callout arearefs="co-workaround"> + <para>The <literal>Workaround</literal> field offers a + feasible workaround to system administrators who may be + incapable of upgrading the system. This may be due to + time constraints, network availability, or a slew of + other reasons. Regardless, security should not be taken + lightly, and an affected system should either be patched + or the security hole workaround should be + implemented.</para> + </callout> + + <callout arearefs="co-solution"> + <para>The <literal>Solution</literal> field offers + instructions on patching the affected system. This is a + step by step tested and verified method for getting a + system patched and working securely.</para> + </callout> + + <callout arearefs="co-details"> + <para>The <literal>Correction Details</literal> field + displays the <acronym>CVS</acronym> branch or release + name with the periods changed to underscore characters. + It also shows the revision number of the affected files + within each branch.</para> + </callout> + + <callout arearefs="co-ref"> + <para>The <literal>References</literal> field usually + offers sources of other information. This can include + web <acronym>URL</acronym>s, books, mailing lists, and + newsgroups.</para> + </callout> + </calloutlist> + </sect2> + </sect1> + + <sect1 id="security-accounting"> + <sect1info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <indexterm> + <primary>Process Accounting</primary> + </indexterm> + + <title>Process Accounting</title> + + <para>Process accounting is a security method in which an + administrator may keep track of system resources used, + their allocation among users, provide for system monitoring, + and minimally track a user's commands.</para> + + <para>This indeed has its own positive and negative points. One + of the positives is that an intrusion may be narrowed down to + the point of entry. A negative is the amount of logs + generated by process accounting, and the disk space they may + require. This section will walk an administrator through the + basics of process accounting.</para> + + <sect2> + <title>Enable and Utilizing Process Accounting</title> + + <para>Before making use of process accounting, it must be + enabled. To do this, execute the following commands:</para> + + <screen>&prompt.root; <userinput>touch <filename>/var/account/acct</filename></userinput> + +&prompt.root; <userinput>accton <filename>/var/account/acct</filename></userinput> + +&prompt.root; <userinput>echo 'accounting_enable="YES"' >> <filename>/etc/rc.conf</filename></userinput></screen> + + <para>Once enabled, accounting will begin to track + <acronym>CPU</acronym> stats, commands, etc. All accounting + logs are in a non-human readable format and may be viewed + using the &man.sa.8; utility. If issued without any + options, <command>sa</command> will print information + relating to the number of per user calls, the total elapsed + time in minutes, total <acronym>CPU</acronym> and user time + in minutes, average number of I/O operations, etc.</para> + + <para>To view information about commands being issued, one + would use the &man.lastcomm.1; utility. The + <command>lastcomm</command> command may be used to print out + commands issued by users on specific &man.ttys.5;, for + example:</para> + + <screen>&prompt.root; <userinput>lastcomm ls + <username>trhodes</username> ttyp1</userinput></screen> + + <para>Would print out all known usage of the + <command>ls</command> by <username>trhodes</username> on the + <literal>ttyp1</literal> terminal.</para> + + <para>Many other useful options exist and are explained in the + &man.lastcomm.1;, &man.acct.5; and &man.sa.8; manual + pages.</para> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/Makefile b/en_US.ISO8859-1/books/handbook/serialcomms/Makefile new file mode 100644 index 0000000000..b83d9a27bb --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/serialcomms/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= serialcomms/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml new file mode 100644 index 0000000000..3ee1afa1d3 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.sgml @@ -0,0 +1,2934 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="serialcomms"> + <title>Serial Communications</title> + + <sect1 id="serial-synopsis"> + <title>Synopsis</title> + + <indexterm><primary>serial communications</primary></indexterm> + + <para>&unix; has always had support for serial communications. In fact, + the very first &unix; machines relied on serial lines for user input + and output. Things have changed a lot from the days when the average + <quote>terminal</quote> consisted of a 10-character-per-second serial + printer and a keyboard. This chapter will cover some of the ways in + which FreeBSD uses serial communications.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>How to connect terminals to your FreeBSD + system.</para> + </listitem> + <listitem> + <para>How to use a modem to dial out to remote + hosts.</para> + </listitem> + <listitem> + <para>How to allow remote users to login to your + system with a modem.</para> + </listitem> + <listitem> + <para>How to boot your system from a serial console.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Know how to configure and install a new kernel (<xref + linkend="kernelconfig">).</para> + </listitem> + <listitem> + <para>Understand &unix; permissions and processes (<xref + linkend="basics">).</para> + </listitem> + <listitem> + <para>Have access to the technical manual for the serial hardware + (modem or multi-port card) that you would like to use with + FreeBSD.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="serial"> + <title>Introduction</title> + + <warning> + <para>As of &os; 8.0, device nodes for serial ports have been + renamed from + <filename>/dev/cuad<replaceable>N</replaceable></filename> to + <filename>/dev/cuau<replaceable>N</replaceable></filename> and + from + <filename>/dev/ttyd<replaceable>N</replaceable></filename> to + <filename>/dev/ttyu<replaceable>N</replaceable></filename>. + &os; 7.X users will have to adapt the following + documentation according to these changes.</para> + </warning> + <!-- XXX Write me! --> + + <sect2 id="serial-terminology"> + <title>Terminology</title> + + <variablelist> + <indexterm><primary>bits-per-second</primary></indexterm> + <varlistentry> + <term>bps</term> + <listitem> + <para>Bits per Second — the rate at which data is + transmitted</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DTE</term> + <indexterm><primary>DTE</primary></indexterm> + <listitem> + <para>Data Terminal Equipment — for example, your + computer</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>DCE</term> + <indexterm><primary>DCE</primary></indexterm> + <listitem> + <para>Data Communications Equipment — your modem</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>RS-232</term> + <indexterm><primary>RS-232C cables</primary></indexterm> + <listitem> + <para>EIA standard for hardware serial communications</para> + </listitem> + </varlistentry> + </variablelist> + + <para>When talking about communications data rates, this section + does not use the term <quote>baud</quote>. Baud refers to the + number of electrical state transitions that may be made in a + period of time, while <quote>bps</quote> (bits per second) is + the <emphasis>correct</emphasis> term to use (at least it does not + seem to bother the curmudgeons quite as much).</para> + </sect2> + + <sect2 id="serial-cables-ports"> + <title>Cables and Ports</title> + + <para>To connect a modem or terminal to your FreeBSD system, you + will need a serial port on your computer and the proper cable to + connect to your serial device. If you are already familiar with your + hardware and the cable it requires, you can safely skip this + section.</para> + + <sect3 id="term-cables"> + <title>Cables</title> + + <para>There are several different kinds of serial cables. The + two most common types for our purposes are null-modem cables + and standard (<quote>straight</quote>) RS-232 cables. The + documentation for your hardware should describe the type of cable + required.</para> + + <sect4 id="term-cables-null"> + <title>Null-modem Cables</title> + + <indexterm> + <primary>null-modem cable</primary> + </indexterm> + + <para>A null-modem cable passes some signals, such as + <quote>Signal Ground</quote>, straight through, but switches other + signals. For example, the <quote>Transmitted Data</quote> pin on + one end goes to the <quote>Received Data</quote> pin on the other + end.</para> + + <para>You can also construct your own null-modem cable for use with + terminals (e.g., for quality purposes). This table shows the + RS-232C <link linkend="serialcomms-signal-names">signals</link> + and the pin numbers on a DB-25 connector. Note that the standard + also calls for a straight-through pin 1 to pin 1 + <emphasis>Protective Ground</emphasis> line, but it is often + omitted. Some terminals work OK using only pins 2, 3 and 7, + while others require different configurations than the examples + shown below.</para> + + <table frame="none" pgwide="1"> + <title>DB-25 to DB-25 Null-Modem Cable</title> + + <tgroup cols="5"> + <thead> + <row> + <entry align="left">Signal</entry> + <entry align="left">Pin #</entry> + <entry></entry> + <entry align="left">Pin #</entry> + <entry align="left">Signal</entry> + </row> + </thead> + + <tbody> + <row> + <entry>SG</entry> + <entry>7</entry> + <entry>connects to</entry> + <entry>7</entry> + <entry>SG</entry> + </row> + + <row> + <entry>TD</entry> + <entry>2</entry> + <entry>connects to</entry> + <entry>3</entry> + <entry>RD</entry> + </row> + + <row> + <entry>RD</entry> + <entry>3</entry> + <entry>connects to</entry> + <entry>2</entry> + <entry>TD</entry> + </row> + + <row> + <entry>RTS</entry> + <entry>4</entry> + <entry>connects to</entry> + <entry>5</entry> + <entry>CTS</entry> + </row> + + <row> + <entry>CTS</entry> + <entry>5</entry> + <entry>connects to</entry> + <entry>4</entry> + <entry>RTS</entry> + </row> + + <row> + <entry>DTR</entry> + <entry>20</entry> + <entry>connects to</entry> + <entry>6</entry> + <entry>DSR</entry> + </row> + + <row> + <entry>DTR</entry> + <entry>20</entry> + <entry>connects to</entry> + <entry>8</entry> + <entry>DCD</entry> + </row> + + <row> + <entry>DSR</entry> + <entry>6</entry> + <entry>connects to</entry> + <entry>20</entry> + <entry>DTR</entry> + </row> + + <row> + <entry>DCD</entry> + <entry>8</entry> + <entry>connects to</entry> + <entry>20</entry> + <entry>DTR</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Here are two other schemes more common nowadays.</para> + + <table frame="none" pgwide="1"> + <title>DB-9 to DB-9 Null-Modem Cable</title> + + <tgroup cols="5"> + <thead> + <row> + <entry align="left">Signal</entry> + <entry align="left">Pin #</entry> + <entry></entry> + <entry align="left">Pin #</entry> + <entry align="left">Signal</entry> + </row> + </thead> + + <tbody> + <row> + <entry>RD</entry> + <entry>2</entry> + <entry>connects to</entry> + <entry>3</entry> + <entry>TD</entry> + </row> + + <row> + <entry>TD</entry> + <entry>3</entry> + <entry>connects to</entry> + <entry>2</entry> + <entry>RD</entry> + </row> + + <row> + <entry>DTR</entry> + <entry>4</entry> + <entry>connects to</entry> + <entry>6</entry> + <entry>DSR</entry> + </row> + + <row> + <entry>DTR</entry> + <entry>4</entry> + <entry>connects to</entry> + <entry>1</entry> + <entry>DCD</entry> + </row> + + <row> + <entry>SG</entry> + <entry>5</entry> + <entry>connects to</entry> + <entry>5</entry> + <entry>SG</entry> + </row> + + <row> + <entry>DSR</entry> + <entry>6</entry> + <entry>connects to</entry> + <entry>4</entry> + <entry>DTR</entry> + </row> + + <row> + <entry>DCD</entry> + <entry>1</entry> + <entry>connects to</entry> + <entry>4</entry> + <entry>DTR</entry> + </row> + + <row> + <entry>RTS</entry> + <entry>7</entry> + <entry>connects to</entry> + <entry>8</entry> + <entry>CTS</entry> + </row> + + <row> + <entry>CTS</entry> + <entry>8</entry> + <entry>connects to</entry> + <entry>7</entry> + <entry>RTS</entry> + </row> + </tbody> + </tgroup> + </table> + + <table frame="none" pgwide="1"> + <title>DB-9 to DB-25 Null-Modem Cable</title> + + <tgroup cols="5"> + <thead> + <row> + <entry align="left">Signal</entry> + <entry align="left">Pin #</entry> + <entry></entry> + <entry align="left">Pin #</entry> + <entry align="left">Signal</entry> + </row> + </thead> + + <tbody> + <row> + <entry>RD</entry> + <entry>2</entry> + <entry>connects to</entry> + <entry>2</entry> + <entry>TD</entry> + </row> + + <row> + <entry>TD</entry> + <entry>3</entry> + <entry>connects to</entry> + <entry>3</entry> + <entry>RD</entry> + </row> + + <row> + <entry>DTR</entry> + <entry>4</entry> + <entry>connects to</entry> + <entry>6</entry> + <entry>DSR</entry> + </row> + + <row> + <entry>DTR</entry> + <entry>4</entry> + <entry>connects to</entry> + <entry>8</entry> + <entry>DCD</entry> + </row> + + <row> + <entry>SG</entry> + <entry>5</entry> + <entry>connects to</entry> + <entry>7</entry> + <entry>SG</entry> + </row> + + <row> + <entry>DSR</entry> + <entry>6</entry> + <entry>connects to</entry> + <entry>20</entry> + <entry>DTR</entry> + </row> + + <row> + <entry>DCD</entry> + <entry>1</entry> + <entry>connects to</entry> + <entry>20</entry> + <entry>DTR</entry> + </row> + + <row> + <entry>RTS</entry> + <entry>7</entry> + <entry>connects to</entry> + <entry>5</entry> + <entry>CTS</entry> + </row> + + <row> + <entry>CTS</entry> + <entry>8</entry> + <entry>connects to</entry> + <entry>4</entry> + <entry>RTS</entry> + </row> + </tbody> + </tgroup> + </table> + + <note> + <para>When one pin at one end connects to a pair of pins + at the other end, it is usually implemented with one short + wire between the pair of pins in their connector and a + long wire to the other single pin.</para> + </note> + + <para>The above designs seems to be the most popular. In another + variation (explained in the book <emphasis>RS-232 Made + Easy</emphasis>) SG connects to SG, TD connects to RD, RTS and + CTS connect to DCD, DTR connects to DSR, and vice-versa.</para> + </sect4> + + <sect4 id="term-cables-std"> + <title>Standard RS-232C Cables</title> + <indexterm><primary>RS-232C cables</primary></indexterm> + + <para>A standard serial cable passes all of the RS-232C signals + straight through. That is, the <quote>Transmitted Data</quote> + pin on one end of the cable goes to the + <quote>Transmitted Data</quote> pin on the other end. This is + the type of cable to use to connect a modem to your FreeBSD + system, and is also appropriate for some terminals.</para> + </sect4> + </sect3> + + <sect3 id="term-ports"> + <title>Ports</title> + + <para>Serial ports are the devices through which data is transferred + between the FreeBSD host computer and the terminal. This section + describes the kinds of ports that exist and how they are addressed + in FreeBSD.</para> + + <sect4 id="term-portkinds"> + <title>Kinds of Ports</title> + + <para>Several kinds of serial ports exist. Before you purchase or + construct a cable, you need to make sure it will fit the ports on + your terminal and on the FreeBSD system.</para> + + <para>Most terminals will have DB-25 ports. Personal computers, + including PCs running FreeBSD, will have DB-25 or DB-9 ports. If + you have a multiport serial card for your PC, you may have RJ-12 or + RJ-45 ports.</para> + + <para>See the documentation that accompanied the hardware for + specifications on the kind of port in use. A visual inspection of + the port often works too.</para> + </sect4> + + <sect4 id="term-portnames"> + <title>Port Names</title> + + <para>In FreeBSD, you access each serial port through an entry in + the <filename>/dev</filename> directory. There are two different + kinds of entries:</para> + + <itemizedlist> + <listitem> + <para>Call-in ports are named + <filename>/dev/ttyu<replaceable>N</replaceable></filename> + where <replaceable>N</replaceable> is the port number, + starting from zero. Generally, you use the call-in port for + terminals. Call-in ports require that the serial line assert + the data carrier detect (DCD) signal to work correctly.</para> + </listitem> + + <listitem> + <para>Call-out ports are named + <filename>/dev/cuau<replaceable>N</replaceable></filename>. + You usually do not use the call-out port for terminals, just + for modems. You may use the call-out port if the serial cable + or the terminal does not support the carrier detect + signal.</para> + </listitem> + </itemizedlist> + + <para>If you have connected a terminal to the first serial port + (<devicename>COM1</devicename> in &ms-dos;), then you will + use <filename>/dev/ttyu0</filename> to refer to the terminal. If + the terminal is on the second serial port (also known as + <devicename>COM2</devicename>), use + <filename>/dev/ttyu1</filename>, and so forth.</para> + + </sect4> + </sect3> + </sect2> + + <sect2> + <title>Kernel Configuration</title> + + <para>FreeBSD supports four serial ports by default. In the + &ms-dos; world, these are known as + <devicename>COM1</devicename>, + <devicename>COM2</devicename>, + <devicename>COM3</devicename>, and + <devicename>COM4</devicename>. FreeBSD currently supports + <quote>dumb</quote> multiport serial interface cards, such as + the BocaBoard 1008 and 2016, as well as more + intelligent multi-port cards such as those made by Digiboard + and Stallion Technologies. However, the default kernel only looks + for the standard COM ports.</para> + + <para>To see if your kernel recognizes any of your serial ports, watch + for messages while the kernel is booting, or use the + <command>/sbin/dmesg</command> command to replay the kernel's boot + messages. In particular, look for messages that start with the + characters <literal>sio</literal>.</para> + + <tip><para>To view just the messages that have the word + <literal>sio</literal>, use the command:</para> + + <screen>&prompt.root; <userinput>/sbin/dmesg | grep 'sio'</userinput></screen> + </tip> + + <para>For example, on a system with four serial ports, these are the + serial-port specific kernel boot messages:</para> + + <screen>sio0 at 0x3f8-0x3ff irq 4 on isa +sio0: type 16550A +sio1 at 0x2f8-0x2ff irq 3 on isa +sio1: type 16550A +sio2 at 0x3e8-0x3ef irq 5 on isa +sio2: type 16550A +sio3 at 0x2e8-0x2ef irq 9 on isa +sio3: type 16550A</screen> + + <para>If your kernel does not recognize all of your serial + ports, you will probably need to configure your kernel + in the <filename>/boot/device.hints</filename> file. You can + also comment-out or completely remove lines for devices you do not + have.</para> + + <para>Please refer to the &man.sio.4; manual page for + more information on serial ports and multiport boards configuration. + Be careful if you are using a configuration + file that was previously used for a different version of + FreeBSD because the device flags and the syntax have changed between + versions.</para> + + <note> + <para><literal>port IO_COM1</literal> is a substitution for + <literal>port 0x3f8</literal>, <literal>IO_COM2</literal> is + <literal>0x2f8</literal>, <literal>IO_COM3</literal> is + <literal>0x3e8</literal>, and <literal>IO_COM4</literal> is + <literal>0x2e8</literal>, which are fairly common port addresses for + their respective serial ports; interrupts 4, 3, 5, and 9 are fairly + common interrupt request lines. Also note that regular serial ports + <emphasis>cannot</emphasis> share interrupts on ISA-bus PCs + (multiport boards have on-board electronics that allow all the + 16550A's on the board to share one or two interrupt request + lines).</para> + </note> + + </sect2> + + <sect2> + <title>Device Special Files</title> + + <para>Most devices in the kernel are accessed through <quote>device + special files</quote>, which are located in the + <filename>/dev</filename> directory. The <devicename>sio</devicename> + devices are accessed through the + <filename>/dev/ttyu<replaceable>N</replaceable></filename> (dial-in) + and <filename>/dev/cuau<replaceable>N</replaceable></filename> + (call-out) devices. FreeBSD also provides initialization devices + (<filename>/dev/ttyu<replaceable>N</replaceable>.init</filename> and + <filename>/dev/cuau<replaceable>N</replaceable>.init</filename>) + and + locking devices + (<filename>/dev/ttyu<replaceable>N</replaceable>.lock</filename> and + <filename>/dev/cuau<replaceable>N</replaceable>.lock</filename>). + The + initialization devices are used to initialize communications port + parameters each time a port is opened, such as + <literal>crtscts</literal> for modems which use + <literal>RTS/CTS</literal> signaling for flow control. The locking + devices are used to lock flags on ports to prevent users or programs + changing certain parameters; see the manual pages &man.termios.4;, + &man.sio.4;, and &man.stty.1; for + information on the terminal settings, locking and initializing + devices, and setting terminal options, respectively.</para> + </sect2> + + + <sect2 id="serial-hw-config"> + <title>Serial Port Configuration</title> + + <indexterm><primary><devicename>ttyu</devicename></primary></indexterm> + <indexterm><primary><devicename>cuau</devicename></primary></indexterm> + + <para>The <devicename>ttyu<replaceable>N</replaceable></devicename> (or + <devicename>cuau<replaceable>N</replaceable></devicename>) device is the + regular device you will want to open for your applications. When a + process opens the device, it will have a default set of terminal I/O + settings. You can see these settings with the command</para> + + <screen>&prompt.root; <userinput>stty -a -f /dev/ttyu1</userinput></screen> + + <para>When you change the settings to this device, the settings are in + effect until the device is closed. When it is reopened, it goes back to + the default set. To make changes to the default set, you can open and + adjust the settings of the <quote>initial state</quote> device. For + example, to turn on <option>CLOCAL</option> mode, 8 bit communication, + and <option>XON/XOFF</option> flow control by default for + <devicename>ttyu5</devicename>, type:</para> + + <screen>&prompt.root; <userinput>stty -f /dev/ttyu5.init clocal cs8 ixon ixoff</userinput></screen> + + <indexterm> + <primary>rc files</primary> + <secondary><filename>rc.serial</filename></secondary> + </indexterm> + + <para>System-wide initialization of the serial devices is + controlled in <filename>/etc/rc.d/serial</filename>. This file + affects the default settings of serial devices.</para> + + <para>To prevent certain settings from being changed by an + application, make adjustments to the <quote>lock state</quote> + device. For example, to lock the speed of + <devicename>ttyu5</devicename> to 57600 bps, type:</para> + + <screen>&prompt.root; <userinput>stty -f /dev/ttyu5.lock 57600</userinput></screen> + + <para>Now, an application that opens + <devicename>ttyu5</devicename> and tries to change the speed of + the port will be stuck with 57600 bps.</para> + + <para>Naturally, you should make the initial state and lock state devices + writable only by the <username>root</username> account.</para> + </sect2> + </sect1> + + <sect1 id="term"> + <sect1info> + <authorgroup> + <author> + <firstname>Sean</firstname> + <surname>Kelly</surname> + <contrib>Contributed by </contrib> + </author> + <!-- 28 July 1996 --> + </authorgroup> + </sect1info> + <title>Terminals</title> + + <warning> + <para>As of &os; 8.0, device nodes for serial ports have been + renamed from + <filename>/dev/cuad<replaceable>N</replaceable></filename> to + <filename>/dev/cuau<replaceable>N</replaceable></filename> and + from + <filename>/dev/ttyd<replaceable>N</replaceable></filename> to + <filename>/dev/ttyu<replaceable>N</replaceable></filename>. + &os; 7.X users will have to adapt the following + documentation according to these changes.</para> + </warning> + + <indexterm><primary>terminals</primary></indexterm> + + <para>Terminals provide a convenient and low-cost way to access + your FreeBSD system when you are not at the computer's console or on + a connected network. This section describes how to use terminals with + FreeBSD.</para> + + <sect2 id="term-uses"> + <title>Uses and Types of Terminals</title> + + <para>The original &unix; systems did not have consoles. Instead, people + logged in and ran programs through terminals that were connected to + the computer's serial ports. It is quite similar to using a modem and + terminal software to dial into a remote system to do text-only + work.</para> + + <para>Today's PCs have consoles capable of high quality graphics, but + the ability to establish a login session on a serial port still exists + in nearly every &unix; style operating system today; FreeBSD is no + exception. By using a terminal attached to an unused serial port, you + can log in and run any text program that you would normally run on the + console or in an <command>xterm</command> window in the X Window + System.</para> + + <para>For the business user, you can attach many terminals to a FreeBSD + system and place them on your employees' desktops. For a home user, a + spare computer such as an older IBM PC or a &macintosh; can be a + terminal wired into a more powerful computer running FreeBSD. You can + turn what might otherwise be a single-user computer into a powerful + multiple user system.</para> + + <para>For FreeBSD, there are three kinds of terminals:</para> + + <itemizedlist> + <listitem> + <para><link linkend="term-dumb">Dumb terminals</link></para> + </listitem> + + <listitem> + <para><link linkend="term-pcs">PCs acting as terminals</link></para> + </listitem> + + <listitem> + <para><link linkend="term-x">X terminals</link></para> + </listitem> + </itemizedlist> + + <para>The remaining subsections describe each kind.</para> + + <sect3 id="term-dumb"> + <title>Dumb Terminals</title> + + <para>Dumb terminals are specialized pieces of hardware that let you + connect to computers over serial lines. They are called + <quote>dumb</quote> because they have only enough computational power + to display, send, and receive text. You cannot run any programs on + them. It is the computer to which you connect them that has all the + power to run text editors, compilers, email, games, and so + forth.</para> + + <para>There are hundreds of kinds of dumb terminals made by many + manufacturers, including Digital Equipment Corporation's VT-100 and + Wyse's WY-75. Just about any kind will work with FreeBSD. Some + high-end terminals can even display graphics, but only certain + software packages can take advantage of these advanced + features.</para> + + <para>Dumb terminals are popular in work environments where workers do + not need access to graphical applications such as those provided by + the X Window System.</para> + </sect3> + + <sect3 id="term-pcs"> + <title>PCs Acting as Terminals</title> + + <para>If a <link linkend="term-dumb">dumb terminal</link> has just + enough ability to display, send, and receive text, then certainly + any spare personal computer can be a dumb terminal. All you need is + the proper cable and some <emphasis>terminal emulation</emphasis> + software to run on the computer.</para> + + <para>Such a configuration is popular in homes. For example, if your + spouse is busy working on your FreeBSD system's console, you can do + some text-only work at the same time from a less powerful personal + computer hooked up as a terminal to the FreeBSD system.</para> + + <para>There are at least two utilities in the base-system of + &os; that can be used to work through a serial connection: + &man.cu.1; and &man.tip.1;.</para> + + <para>To connect from a client system that runs &os; to the + serial connection of another system, you can use:</para> + + <screen>&prompt.root; <userinput>cu -l <replaceable>serial-port-device</replaceable></userinput></screen> + + <para>Where <quote>serial-port-device</quote> is the name of a + special device file denoting a serial port of your system. + These device files are called + <devicename>/dev/cuau<replaceable>N</replaceable></devicename>.</para> + + <para>The <quote>N</quote>-part of a device name is the serial + port number.</para> + + <note> + <para>Note that device numbers in &os; start from zero and not + one (like they do, for instance in &ms-dos;-derived systems). + This means that what &ms-dos;-based systems call + <devicename>COM1</devicename> is usually + <filename>/dev/cuau0</filename> in &os;.</para> + </note> + + <note> + <para>Some people prefer to use other programs, available + through the Ports Collection. The Ports include quite a few + utilities which can work in ways similar to &man.cu.1; and + &man.tip.1;, + i.e., <filename role="package">comms/minicom</filename>.</para> + </note> + </sect3> + + <sect3 id="term-x"> + <title>X Terminals</title> + + <para>X terminals are the most sophisticated kind of terminal + available. Instead of connecting to a serial port, they usually + connect to a network like Ethernet. Instead of being relegated to + text-only applications, they can display any X application.</para> + + <para>We introduce X terminals just for the sake of completeness. + However, this chapter does <emphasis>not</emphasis> cover setup, + configuration, or use of X terminals.</para> + </sect3> + </sect2> + + <sect2 id="term-config"> + <title>Configuration</title> + + <para>This section describes what you need to configure on your FreeBSD + system to enable a login session on a terminal. It assumes you have + already configured your kernel to support the serial port to which the + terminal is connected—and that you have connected it.</para> + + <para>Recall from <xref linkend="boot"> that the + <command>init</command> process is responsible for all process + control and initialization at system startup. One of the + tasks performed by <command>init</command> is to read the + <filename>/etc/ttys</filename> file and start a + <command>getty</command> process on the available terminals. + The <command>getty</command> process is responsible for + reading a login name and starting the <command>login</command> + program.</para> + + <para>Thus, to configure terminals for your FreeBSD system the + following steps should be taken as <username>root</username>:</para> + + <procedure> + <step> + <para>Add a line to <filename>/etc/ttys</filename> for the entry in + the <filename>/dev</filename> directory for the serial port if it + is not already there.</para> + </step> + + <step> + <para>Specify that <command>/usr/libexec/getty</command> be run on + the port, and specify the appropriate + <replaceable>getty</replaceable> type from the + <filename>/etc/gettytab</filename> file.</para> + </step> + + <step> + <para>Specify the default terminal type.</para> + </step> + + <step> + <para>Set the port to <quote>on.</quote></para> + </step> + + <step> + <para>Specify whether the port should be + <quote>secure.</quote></para> + </step> + + <step> + <para>Force <command>init</command> to reread the + <filename>/etc/ttys</filename> file.</para> + </step> + </procedure> + + <para>As an optional step, you may wish to create a custom + <replaceable>getty</replaceable> type for use in step 2 by making an + entry in <filename>/etc/gettytab</filename>. This chapter does + not explain how to do so; you are encouraged to see the + &man.gettytab.5; and the &man.getty.8; manual pages for more + information.</para> + + <sect3 id="term-etcttys"> + <title>Adding an Entry to <filename>/etc/ttys</filename></title> + + <para>The <filename>/etc/ttys</filename> file lists all of the ports + on your FreeBSD system where you want to allow logins. For example, + the first virtual console <devicename>ttyv0</devicename> has an entry + in this file. You can log in on the console using this entry. This + file also contains entries for the other virtual consoles, serial + ports, and pseudo-ttys. For a hardwired terminal, just list the + serial port's <filename>/dev</filename> entry without the + <filename>/dev</filename> part (for example, + <filename>/dev/ttyv0</filename> would be listed as + <devicename>ttyv0</devicename>).</para> + + <para>A default FreeBSD install includes an + <filename>/etc/ttys</filename> file with support for the first + four serial ports: <devicename>ttyu0</devicename> through + <devicename>ttyu3</devicename>. If you are attaching a terminal + to one of those ports, you do not need to add another entry.</para> + + <example id="ex-etc-ttys"> + <title>Adding Terminal Entries to + <filename>/etc/ttys</filename></title> + + <para>Suppose we would like to connect two terminals to the + system: a Wyse-50 and an old 286 IBM PC running + <application>Procomm</application> terminal software + emulating a VT-100 terminal. We connect the Wyse to the + second serial port and the 286 to the sixth serial port (a + port on a multiport serial card). The corresponding + entries in the <filename>/etc/ttys</filename> file would + look like this:</para> + + <programlisting>ttyu1<co + id="co-ttys-line1col1"> "/usr/libexec/getty std.38400"<co + id="co-ttys-line1col2"> wy50<co + id="co-ttys-line1col3"> on<co + id="co-ttys-line1col4"> insecure<co + id="co-ttys-line1col5"> +ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure + </programlisting> + + <calloutlist> + <callout arearefs="co-ttys-line1col1"> + <para>The first field normally specifies the name of + the terminal special file as it is found in + <filename>/dev</filename>.</para> + </callout> + + <callout arearefs="co-ttys-line1col2"> + <para>The second field is the command to execute for + this line, which is usually &man.getty.8;. + <command>getty</command> initializes and opens the + line, sets the speed, prompts for a user name and then + executes the &man.login.1; program.</para> + + <para>The <command>getty</command> program accepts one + (optional) parameter on its command line, the + <replaceable>getty</replaceable> type. A + <replaceable>getty</replaceable> type configures + characteristics on the terminal line, like bps rate + and parity. The <command>getty</command> program reads + these characteristics from the file + <filename>/etc/gettytab</filename>.</para> + + <para>The file <filename>/etc/gettytab</filename> + contains lots of entries for terminal lines both old + and new. In almost all cases, the entries that start + with the text <literal>std</literal> will work for + hardwired terminals. These entries ignore parity. + There is a <literal>std</literal> entry for each bps + rate from 110 to 115200. Of course, you can add your + own entries to this file. The &man.gettytab.5; manual + page provides more information.</para> + + <para>When setting the <replaceable>getty</replaceable> + type in the <filename>/etc/ttys</filename> file, make + sure that the communications settings on the terminal + match.</para> + + <para>For our example, the Wyse-50 uses no parity and + connects at 38400 bps. The 286 PC uses no parity + and connects at 19200 bps.</para> + </callout> + + <callout arearefs="co-ttys-line1col3"> + <para>The third field is the type of terminal usually + connected to that tty line. For dial-up ports, + <literal>unknown</literal> or + <literal>dialup</literal> is typically used in this + field since users may dial up with practically any + type of terminal or software. For hardwired + terminals, the terminal type does not change, so you + can put a real terminal type from the &man.termcap.5; + database file in this field.</para> + + <para>For our example, the Wyse-50 uses the real + terminal type while the 286 PC running + <application>Procomm</application> will be set to + emulate at VT-100. </para> + </callout> + + <callout arearefs="co-ttys-line1col4"> + <para>The fourth field specifies if the port should be + enabled. Putting <literal>on</literal> here will have + the <command>init</command> process start the program + in the second field, <command>getty</command>. If you + put <literal>off</literal> in this field, there will + be no <command>getty</command>, and hence no logins on + the port.</para> + </callout> + + <callout arearefs="co-ttys-line1col5"> + <para>The final field is used to specify whether the + port is secure. Marking a port as secure means that + you trust it enough to allow the + <username>root</username> account (or any account with + a user ID of 0) to login from that port. Insecure + ports do not allow <username>root</username> logins. + On an insecure port, users must login from + unprivileged accounts and then use &man.su.1; or a + similar mechanism to gain superuser privileges.</para> + + <para>It is highly recommended that you use + <quote>insecure</quote> + even for terminals that are behind locked doors. It + is quite easy to login and use <command>su</command> + if you need superuser privileges.</para> + </callout> + </calloutlist> + </example> + </sect3> + + <sect3 id="term-hup"> + <title>Force <command>init</command> to Reread + <filename>/etc/ttys</filename></title> + + <para>After making the necessary changes to the + <filename>/etc/ttys</filename> file you should send a SIGHUP + (hangup) signal to the <command>init</command> process to + force it to re-read its configuration file. For example:</para> + + <screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen> + + <note> + <para><command>init</command> is always the first process run + on a system, therefore it will always have PID 1.</para> + </note> + + <para>If everything is set up correctly, all cables are in + place, and the terminals are powered up, then a + <command>getty</command> process should be running on each + terminal and you should see login prompts on your terminals + at this point.</para> + </sect3> + </sect2> + + <sect2 id="term-debug"> + <title>Troubleshooting Your Connection</title> + + <para>Even with the most meticulous attention to detail, something could + still go wrong while setting up a terminal. Here is a list of + symptoms and some suggested fixes.</para> + + <sect3> + <title>No Login Prompt Appears</title> + + <para>Make sure the terminal is plugged in and powered up. If it + is a personal computer acting as a terminal, make sure it is + running terminal emulation software on the correct serial + port.</para> + + <para>Make sure the cable is connected firmly to both the terminal + and the FreeBSD computer. Make sure it is the right kind of + cable.</para> + + <para>Make sure the terminal and FreeBSD agree on the bps rate and + parity settings. If you have a video display terminal, make + sure the contrast and brightness controls are turned up. If it + is a printing terminal, make sure paper and ink are in good + supply.</para> + + <para>Make sure that a <command>getty</command> process is running + and serving the terminal. For example, to get a list of + running <command>getty</command> processes with + <command>ps</command>, type:</para> + + <screen>&prompt.root; <userinput>ps -axww|grep getty</userinput></screen> + + <para>You should see an entry for the terminal. For + example, the following display shows that a + <command>getty</command> is running on the second serial + port <devicename>ttyu1</devicename> and is using the + <literal>std.38400</literal> entry in + <filename>/etc/gettytab</filename>:</para> + + <screen>22189 d1 Is+ 0:00.03 /usr/libexec/getty std.38400 ttyu1</screen> + + <para>If no <command>getty</command> process is running, make sure + you have enabled the port in <filename>/etc/ttys</filename>. + Also remember to run <command>kill -HUP 1</command> + after modifying the <filename>ttys</filename> file.</para> + + <para>If the <command>getty</command> process is running + but the terminal still does not display a login prompt, + or if it displays a prompt but will not allow you to + type, your terminal or cable may not support hardware + handshaking. Try changing the entry in + <filename>/etc/ttys</filename> from + <literal>std.38400</literal> to + <literal>3wire.38400</literal> (remember to run + <command>kill -HUP 1</command> after modifying + <filename>/etc/ttys</filename>). The + <literal>3wire</literal> entry is similar to + <literal>std</literal>, but ignores hardware + handshaking. You may need to reduce the baud rate or + enable software flow control when using + <literal>3wire</literal> to prevent buffer + overflows.</para> + + </sect3> + + <sect3> + <title>If Garbage Appears Instead of a Login Prompt</title> + + <para>Make sure the terminal and FreeBSD agree on the bps rate and + parity settings. Check the <command>getty</command> processes + to make sure the + correct <replaceable>getty</replaceable> type is in use. If + not, edit <filename>/etc/ttys</filename> and run <command>kill + -HUP 1</command>.</para> + + </sect3> + + <sect3> + <title>Characters Appear Doubled; the Password Appears When + Typed</title> + + <para>Switch the terminal (or the terminal emulation software) + from <quote>half duplex</quote> or <quote>local echo</quote> to + <quote>full duplex.</quote></para> + + </sect3> + </sect2> + </sect1> + + <sect1 id="dialup"> + <sect1info> + <authorgroup> + <author> + <firstname>Guy</firstname> + <surname>Helmer</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Sean</firstname> + <surname>Kelly</surname> + <contrib>Additions by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Dial-in Service</title> + + <warning> + <para>As of &os; 8.0, device nodes for serial ports have been + renamed from + <filename>/dev/cuad<replaceable>N</replaceable></filename> to + <filename>/dev/cuau<replaceable>N</replaceable></filename> and + from + <filename>/dev/ttyd<replaceable>N</replaceable></filename> to + <filename>/dev/ttyu<replaceable>N</replaceable></filename>. + &os; 7.X users will have to adapt the following + documentation according to these changes.</para> + </warning> + + <indexterm><primary>dial-in service</primary></indexterm> + + <para>Configuring your FreeBSD system for dial-in service is very + similar to connecting terminals except that you are dealing with + modems instead of terminals.</para> + + <sect2> + <title>External Versus Internal Modems</title> + + <para>External modems seem to be more convenient for dial-up, because + external modems often can be semi-permanently configured via + parameters stored in non-volatile RAM and they usually provide + lighted indicators that display the state of important RS-232 + signals. Blinking lights impress visitors, but lights are also very + useful to see whether a modem is operating properly.</para> + + <para>Internal modems usually lack non-volatile RAM, so their + configuration may be limited only to setting DIP switches. If your + internal modem has any signal indicator lights, it is probably + difficult to view the lights when the system's cover is in + place.</para> + + <sect3> + <title>Modems and Cables</title> + <indexterm><primary>modem</primary></indexterm> + + <para>If you are using an external modem, then you will of + course need the proper cable. A standard RS-232C serial + cable should suffice as long as all of the normal signals + are wired:</para> + + <table frame="none" pgwide="1" id="serialcomms-signal-names"> + <title>Signal Names</title> + + <tgroup cols="2"> + <thead> + <row> + <entry align="left">Acronyms</entry> + <entry align="left">Names</entry> + </row> + </thead> + + <tbody> + <row> + <entry><acronym>RD</acronym></entry> + <entry>Received Data</entry> + </row> + + <row> + <entry><acronym>TD</acronym></entry> + <entry>Transmitted Data</entry> + </row> + + <row> + <entry><acronym>DTR</acronym></entry> + <entry>Data Terminal Ready</entry> + </row> + + <row> + <entry><acronym>DSR</acronym></entry> + <entry>Data Set Ready</entry> + </row> + + <row> + <entry><acronym>DCD</acronym></entry> + <entry>Data Carrier Detect (RS-232's Received Line + Signal Detector)</entry> + </row> + + <row> + <entry><acronym>SG</acronym></entry> + <entry>Signal Ground</entry> + </row> + + <row> + <entry><acronym>RTS</acronym></entry> + <entry>Request to Send</entry> + </row> + + <row> + <entry><acronym>CTS</acronym></entry> + <entry>Clear to Send</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>FreeBSD needs the <acronym>RTS</acronym> and + <acronym>CTS</acronym> signals for flow control at speeds above + 2400 bps, the <acronym>CD</acronym> signal to detect when a + call has been answered or the line has been hung up, and the + <acronym>DTR</acronym> signal to reset the modem after a session is + complete. Some cables are wired without all of the needed signals, + so if you have problems, such as a login session not going away when + the line hangs up, you may have a problem with your cable.</para> + + <para>Like other &unix; like operating systems, FreeBSD uses the + hardware signals to find out when a call has been answered + or a line has been hung up and to hangup and reset the modem + after a call. FreeBSD avoids sending commands to the modem + or watching for status reports from the modem. If you are + familiar with connecting modems to PC-based bulletin board + systems, this may seem awkward.</para> + </sect3> + </sect2> + + <sect2> + <title>Serial Interface Considerations</title> + + <para>FreeBSD supports NS8250-, NS16450-, NS16550-, and NS16550A-based + EIA RS-232C (CCITT V.24) communications interfaces. The 8250 and + 16450 devices have single-character buffers. The 16550 device + provides a 16-character buffer, which allows for better system + performance. (Bugs in plain 16550's prevent the use of the + 16-character buffer, so use 16550A's if possible). Because + single-character-buffer devices require more work by the operating + system than the 16-character-buffer devices, 16550A-based serial + interface cards are much preferred. If the system has many active + serial ports or will have a heavy load, 16550A-based cards are + better for low-error-rate communications.</para> + </sect2> + + <sect2> + <title>Quick Overview</title> + + <indexterm><primary>getty</primary></indexterm> + <para>As with terminals, <command>init</command> spawns a + <command>getty</command> process for each configured serial + port for dial-in connections. For example, if a modem is + attached to <filename>/dev/ttyu0</filename>, the command + <command>ps ax</command> might show this:</para> + + <screen> 4850 ?? I 0:00.09 /usr/libexec/getty V19200 ttyu0</screen> + + <para>When a user dials the modem's line and the modems connect, the + <acronym>CD</acronym> (Carrier Detect) line is reported by the modem. + The kernel + notices that carrier has been detected and completes + <command>getty</command>'s open of the port. <command>getty</command> + sends a <prompt>login:</prompt> prompt at the specified initial line + speed. <command>getty</command> watches to see if legitimate + characters are received, and, in a typical configuration, if it finds + junk (probably due to the modem's connection speed being different + than <command>getty</command>'s speed), <command>getty</command> tries + adjusting the line speeds until it receives reasonable + characters.</para> + + <indexterm> + <primary><command>/usr/bin/login</command></primary> + </indexterm> + <para>After the user enters his/her login name, + <command>getty</command> executes + <filename>/usr/bin/login</filename>, which completes the login + by asking for the user's password and then starting the user's + shell.</para> + </sect2> + + + <sect2> + <title>Configuration Files</title> + + <para>There are three system configuration files in the + <filename>/etc</filename> directory that you will probably need to + edit to allow dial-up access to your FreeBSD system. The first, + <filename>/etc/gettytab</filename>, contains configuration information + for the <filename>/usr/libexec/getty</filename> daemon. Second, + <filename>/etc/ttys</filename> holds information that tells + <filename>/sbin/init</filename> what <filename>tty</filename> devices + should have <command>getty</command> processes running on them. + Lastly, you can place port initialization commands in the + <filename>/etc/rc.d/serial</filename> script.</para> + + <para>There are two schools of thought regarding dial-up modems on + &unix;. One group likes to configure their modems and systems so that + no matter at what speed a remote user dials in, the local + computer-to-modem RS-232 interface runs at a locked speed. The benefit + of this configuration is that the remote user always sees a system + login prompt immediately. The downside is that the system does not + know what a user's true data rate is, so full-screen programs like + <application>Emacs</application> will not adjust their screen-painting + methods to make their response better for slower connections.</para> + + <para>The other school configures their modems' RS-232 interface to vary + its speed based on the remote user's connection speed. For example, + V.32bis (14.4 Kbps) connections to the modem might make the modem + run its RS-232 interface at 19.2 Kbps, while 2400 bps + connections make the modem's RS-232 interface run at 2400 bps. + Because <command>getty</command> does not understand any particular + modem's connection speed reporting, <command>getty</command> gives a + <prompt>login:</prompt> message at an initial speed and watches the + characters that come back in response. If the user sees junk, it is + assumed that they know they should press the + <keycap>Enter</keycap> key until they see a recognizable + prompt. If the data rates do not match, <command>getty</command> sees + anything the user types as <quote>junk</quote>, tries going to the next + speed and gives the <prompt>login:</prompt> prompt again. This + procedure can continue ad nauseam, but normally only takes a keystroke + or two before the user sees a good prompt. Obviously, this login + sequence does not look as clean as the former + <quote>locked-speed</quote> method, but a user on a low-speed + connection should receive better interactive response from full-screen + programs.</para> + + <para>This section will try to give balanced configuration information, + but is biased towards having the modem's data rate follow the + connection rate.</para> + + <sect3> + <title><filename>/etc/gettytab</filename></title> + + <indexterm> + <primary><filename>/etc/gettytab</filename></primary> + </indexterm> + <para><filename>/etc/gettytab</filename> is a &man.termcap.5;-style + file of configuration information for &man.getty.8;. Please see the + &man.gettytab.5; manual page for complete information on the + format of the file and the list of capabilities.</para> + + <sect4> + <title>Locked-speed Config</title> + + <para>If you are locking your modem's data communications rate at a + particular speed, you probably will not need to make any changes + to <filename>/etc/gettytab</filename>.</para> + </sect4> + + <sect4> + <title>Matching-speed Config</title> + + <para>You will need to set up an entry in + <filename>/etc/gettytab</filename> to give + <command>getty</command> information about the speeds you wish to + use for your modem. If you have a 2400 bps modem, you can + probably use the existing <literal>D2400</literal> entry.</para> + + <programlisting># +# Fast dialup terminals, 2400/1200/300 rotary (can start either way) +# +D2400|d2400|Fast-Dial-2400:\ + :nx=D1200:tc=2400-baud: +3|D1200|Fast-Dial-1200:\ + :nx=D300:tc=1200-baud: +5|D300|Fast-Dial-300:\ + :nx=D2400:tc=300-baud:</programlisting> + + <para>If you have a higher speed modem, you will probably need to + add an entry in <filename>/etc/gettytab</filename>; here is an + entry you could use for a 14.4 Kbps modem with a top interface + speed of 19.2 Kbps:</para> + + <programlisting># +# Additions for a V.32bis Modem +# +um|V300|High Speed Modem at 300,8-bit:\ + :nx=V19200:tc=std.300: +un|V1200|High Speed Modem at 1200,8-bit:\ + :nx=V300:tc=std.1200: +uo|V2400|High Speed Modem at 2400,8-bit:\ + :nx=V1200:tc=std.2400: +up|V9600|High Speed Modem at 9600,8-bit:\ + :nx=V2400:tc=std.9600: +uq|V19200|High Speed Modem at 19200,8-bit:\ + :nx=V9600:tc=std.19200:</programlisting> + + <para>This will result in 8-bit, no parity connections.</para> + + <para>The example above starts the communications rate at + 19.2 Kbps (for a V.32bis connection), then cycles through + 9600 bps (for V.32), 2400 bps, 1200 bps, + 300 bps, and back to 19.2 Kbps. Communications rate + cycling is implemented with the <literal>nx=</literal> + (<quote>next table</quote>) capability. Each of the lines uses + a <literal>tc=</literal> (<quote>table continuation</quote>) + entry to pick up the rest of the <quote>standard</quote> + settings for a particular data rate.</para> + + <para>If you have a 28.8 Kbps modem and/or you want to take + advantage of compression on a 14.4 Kbps modem, you need to + use a higher communications rate than 19.2 Kbps. Here is an + example of a <filename>gettytab</filename> entry starting a + 57.6 Kbps:</para> + + <programlisting># +# Additions for a V.32bis or V.34 Modem +# Starting at 57.6 Kbps +# +vm|VH300|Very High Speed Modem at 300,8-bit:\ + :nx=VH57600:tc=std.300: +vn|VH1200|Very High Speed Modem at 1200,8-bit:\ + :nx=VH300:tc=std.1200: +vo|VH2400|Very High Speed Modem at 2400,8-bit:\ + :nx=VH1200:tc=std.2400: +vp|VH9600|Very High Speed Modem at 9600,8-bit:\ + :nx=VH2400:tc=std.9600: +vq|VH57600|Very High Speed Modem at 57600,8-bit:\ + :nx=VH9600:tc=std.57600:</programlisting> + + <para>If you have a slow CPU or a heavily loaded system and do + not have 16550A-based serial ports, you may receive + <errorname>sio</errorname> + <quote>silo</quote> errors at 57.6 Kbps.</para> + </sect4> + </sect3> + + <sect3 id="dialup-ttys"> + <title><filename>/etc/ttys</filename></title> + <indexterm> + <primary><filename>/etc/ttys</filename></primary> + </indexterm> + + <para>Configuration of the <filename>/etc/ttys</filename> file + was covered in <xref linkend="ex-etc-ttys">. + Configuration for modems is similar but we must pass a + different argument to <command>getty</command> and specify a + different terminal type. The general format for both + locked-speed and matching-speed configurations is:</para> + + <programlisting>ttyu0 "/usr/libexec/getty <replaceable>xxx</replaceable>" dialup on</programlisting> + + <para>The first item in the above line is the device special file for + this entry — <devicename>ttyu0</devicename> means + <filename>/dev/ttyu0</filename> is the file that this + <command>getty</command> will be watching. The second item, + <literal>"/usr/libexec/getty + <replaceable>xxx</replaceable>"</literal> + (<replaceable>xxx</replaceable> will be replaced by the initial + <filename>gettytab</filename> capability) is the process + <command>init</command> will run on the device. The third item, + <literal>dialup</literal>, is the default terminal type. The fourth + parameter, <literal>on</literal>, indicates to + <command>init</command> that the line is operational. There can be + a fifth parameter, <literal>secure</literal>, but it should only be + used for terminals which are physically secure (such as the system + console).</para> + + <para>The default terminal type (<literal>dialup</literal> in the + example above) may depend on local preferences. + <literal>dialup</literal> is the traditional default terminal type + on dial-up lines so that users may customize their login scripts to + notice when the terminal is <literal>dialup</literal> and + automatically adjust their terminal type. However, the author finds + it easier at his site to specify <literal>vt102</literal> as the + default terminal type, since the users just use VT102 emulation on + their remote systems.</para> + + <para>After you have made changes to <filename>/etc/ttys</filename>, + you may send the <command>init</command> process a + <acronym>HUP</acronym> signal to re-read the file. You can use the + command + + <screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen> + + to send the signal. If this is your first time setting up the + system, you may want to wait until your modem(s) are properly + configured and connected before signaling <command>init</command>. + </para> + + <sect4> + <title>Locked-speed Config</title> + + <para>For a locked-speed configuration, your + <filename>ttys</filename> entry needs to have a fixed-speed entry + provided to <command>getty</command>. For a modem whose port + speed is locked at 19.2 Kbps, the <filename>ttys</filename> + entry might look like this:</para> + + <programlisting>ttyu0 "/usr/libexec/getty std.19200" dialup on</programlisting> + + <para>If your modem is locked at a different data rate, + substitute the appropriate value for + <literal>std.<replaceable>speed</replaceable></literal> + instead of <literal>std.19200</literal>. Make sure that + you use a valid type listed in + <filename>/etc/gettytab</filename>.</para> + </sect4> + + <sect4> + <title>Matching-speed Config</title> + + <para>In a matching-speed configuration, your + <filename>ttys</filename> entry needs to reference the appropriate + beginning <quote>auto-baud</quote> (sic) entry in + <filename>/etc/gettytab</filename>. For example, if you added the + above suggested entry for a matching-speed modem that starts at + 19.2 Kbps (the <filename>gettytab</filename> entry containing + the <literal>V19200</literal> starting point), your + <filename>ttys</filename> entry might look like this:</para> + + <programlisting>ttyu0 "/usr/libexec/getty V19200" dialup on</programlisting> + </sect4> + </sect3> + + <sect3> + <title><filename>/etc/rc.d/serial</filename></title> + <indexterm> + <primary>rc files</primary> + <secondary><filename>rc.serial</filename></secondary> + </indexterm> + + <para>High-speed modems, like V.32, V.32bis, and V.34 modems, + need to use hardware (<literal>RTS/CTS</literal>) flow + control. You can add <command>stty</command> commands to + <filename>/etc/rc.d/serial</filename> to set the hardware flow + control flag in the FreeBSD kernel for the modem + ports.</para> + + <para>For example to set the <literal>termios</literal> flag + <varname>crtscts</varname> on serial port #1's + (<devicename>COM2</devicename>) dial-in and dial-out initialization + devices, the following lines could be added to + <filename>/etc/rc.d/serial</filename>:</para> + <programlisting># Serial port initial configuration +stty -f /dev/ttyu1.init crtscts +stty -f /dev/cuau1.init crtscts</programlisting> + + </sect3> + </sect2> + + <sect2> + <title>Modem Settings</title> + + <para>If you have a modem whose parameters may be permanently set in + non-volatile RAM, you will need to use a terminal program (such as + <application>Telix</application> under &ms-dos; or + <command>tip</command> under FreeBSD) to set the parameters. Connect + to the modem using the same communications speed as the initial speed + <command>getty</command> will use and configure the modem's + non-volatile RAM to match these requirements:</para> + + <itemizedlist> + <listitem> + <para><acronym>CD</acronym> asserted when connected</para> + </listitem> + + <listitem> + <para><acronym>DTR</acronym> asserted for operation; dropping DTR + hangs up line and resets modem</para> + </listitem> + + <listitem> + <para><acronym>CTS</acronym> transmitted data flow control</para> + </listitem> + + <listitem> + <para>Disable <acronym>XON/XOFF</acronym> flow control</para> + </listitem> + + <listitem> + <para><acronym>RTS</acronym> received data flow control</para> + </listitem> + + <listitem> + <para>Quiet mode (no result codes)</para> + </listitem> + + <listitem> + <para>No command echo</para> + </listitem> + </itemizedlist> + + <para>Please read the documentation for your modem to find out what + commands and/or DIP switch settings you need to give it.</para> + + <para>For example, to set the above parameters on a &usrobotics; + &sportster; 14,400 external modem, one could give these commands to + the modem:</para> + + <programlisting>ATZ +AT&C1&D2&H1&I0&R2&W</programlisting> + + <para>You might also want to take this opportunity to adjust other + settings in the modem, such as whether it will use V.42bis and/or MNP5 + compression.</para> + + <para>The &usrobotics; &sportster; 14,400 external modem also has some + DIP switches that need to be set; for other modems, perhaps you can + use these settings as an example:</para> + + <itemizedlist> + <listitem> + <para>Switch 1: UP — DTR Normal</para> + </listitem> + + <listitem> + <para>Switch 2: N/A (Verbal Result Codes/Numeric Result + Codes)</para> + </listitem> + + <listitem> + <para>Switch 3: UP — Suppress Result Codes</para> + </listitem> + + <listitem> + <para>Switch 4: DOWN — No echo, offline commands</para> + </listitem> + + <listitem> + <para>Switch 5: UP — Auto Answer</para> + </listitem> + + <listitem> + <para>Switch 6: UP — Carrier Detect Normal</para> + </listitem> + + <listitem> + <para>Switch 7: UP — Load NVRAM Defaults</para> + </listitem> + + <listitem> + <para>Switch 8: N/A (Smart Mode/Dumb Mode)</para> + </listitem> + </itemizedlist> + + <para>Result codes should be disabled/suppressed for dial-up modems to + avoid problems that can occur if <command>getty</command> mistakenly + gives a <prompt>login:</prompt> prompt to a modem that is in command + mode and the modem echoes the command or returns a result + code. This sequence can result in a extended, silly conversation + between <command>getty</command> and the modem.</para> + + <sect3> + <title>Locked-speed Config</title> + + <para>For a locked-speed configuration, you will need to configure the + modem to maintain a constant modem-to-computer data rate independent + of the communications rate. On a &usrobotics; &sportster; 14,400 + external modem, these commands will lock the modem-to-computer data + rate at the speed used to issue the commands:</para> + + <programlisting>ATZ +AT&B1&W</programlisting> + </sect3> + + <sect3> + <title>Matching-speed Config</title> + + <para>For a variable-speed configuration, you will need to configure + your modem to adjust its serial port data rate to match the incoming + call rate. On a &usrobotics; &sportster; 14,400 external modem, + these commands will lock the modem's error-corrected data rate to the + speed used to issue the commands, but allow the serial port rate to + vary for non-error-corrected connections:</para> + + <programlisting>ATZ +AT&B2&W</programlisting> + </sect3> + + <sect3> + <title>Checking the Modem's Configuration</title> + + <para>Most high-speed modems provide commands to view the modem's + current operating parameters in a somewhat human-readable fashion. + On the &usrobotics; &sportster; 14,400 external modems, the command + <command>ATI5</command> displays the settings that are stored in the + non-volatile RAM. To see the true operating parameters of the modem + (as influenced by the modem's DIP switch settings), use the commands + <command>ATZ</command> and then <command>ATI4</command>.</para> + + <para>If you have a different brand of modem, check your modem's + manual to see how to double-check your modem's configuration + parameters.</para> + </sect3> + </sect2> + + <sect2> + <title>Troubleshooting</title> + + <para>Here are a few steps you can follow to check out the dial-up modem + on your system.</para> + + <sect3> + <title>Checking Out the FreeBSD System</title> + + <para>Hook up your modem to your FreeBSD system, boot the system, and, + if your modem has status indication lights, watch to see whether the + modem's <acronym>DTR</acronym> indicator lights when the + <prompt>login:</prompt> prompt appears on the system's console + — if it lights up, that should mean that FreeBSD has started a + <command>getty</command> process on the appropriate communications + port and is waiting for the modem to accept a call.</para> + + <para>If the <acronym>DTR</acronym> indicator does not light, login to + the FreeBSD system through the console and issue a <command>ps + ax</command> to see if FreeBSD is trying to run a + <command>getty</command> process on the correct port. You should see + lines like these among the processes displayed:</para> + + <screen> 114 ?? I 0:00.10 /usr/libexec/getty V19200 ttyu0 + 115 ?? I 0:00.10 /usr/libexec/getty V19200 ttyu1</screen> + + <para>If you see something different, like this:</para> + + <screen> 114 d0 I 0:00.10 /usr/libexec/getty V19200 ttyu0</screen> + + <para>and the modem has not accepted a call yet, this means that + <command>getty</command> has completed its open on the + communications port. This could indicate a problem with the cabling + or a mis-configured modem, because <command>getty</command> should + not be able to open the communications port until + <acronym>CD</acronym> (carrier detect) has been asserted by the + modem.</para> + + <para>If you do not see any <command>getty</command> processes waiting + to open the desired + <devicename>ttyu<replaceable>N</replaceable></devicename> port, + double-check your entries in <filename>/etc/ttys</filename> to see + if there are any mistakes there. Also, check the log file + <filename>/var/log/messages</filename> to see if there are any log + messages from <command>init</command> or <command>getty</command> + regarding any problems. If there are any messages, triple-check the + configuration files <filename>/etc/ttys</filename> and + <filename>/etc/gettytab</filename>, as well as the appropriate + device special files <filename>/dev/ttyuN</filename>, for any + mistakes, missing entries, or missing device special files.</para> + </sect3> + + <sect3> + <title>Try Dialing In</title> + + <para>Try dialing into the system; be sure to use 8 bits, no parity, + and 1 + stop bit on the remote system. If you do not get a prompt right + away, or get garbage, try pressing <keycap>Enter</keycap> + about once per second. If you still do not see a + <prompt>login:</prompt> prompt after a while, try sending a + <command>BREAK</command>. If you are using a high-speed modem to do + the dialing, try dialing again after locking the dialing modem's + interface speed (via <command>AT&B1</command> on a &usrobotics; + &sportster; modem, for example).</para> + + <para>If you still cannot get a <prompt>login:</prompt> prompt, check + <filename>/etc/gettytab</filename> again and double-check + that</para> + + <itemizedlist> + <listitem> + <para>The initial capability name specified in + <filename>/etc/ttys</filename> for the line matches a name of a + capability in <filename>/etc/gettytab</filename></para> + </listitem> + + <listitem> + <para>Each <literal>nx=</literal> entry matches another + <filename>gettytab</filename> capability name</para> + </listitem> + + <listitem> + <para>Each <literal>tc=</literal> entry matches another + <filename>gettytab</filename> capability name</para> + </listitem> + </itemizedlist> + + <para>If you dial but the modem on the FreeBSD system will not answer, + make sure that the modem is configured to answer the phone when + <acronym>DTR</acronym> is asserted. If the modem seems to be + configured correctly, verify that the <acronym>DTR</acronym> line is + asserted by checking the modem's indicator lights (if it has + any).</para> + + <para>If you have gone over everything several times and it still does + not work, take a break and come back to it later. If it still does + not work, perhaps you can send an electronic mail message to the + &a.questions; describing your modem and your problem, and the good + folks on the list will try to help.</para> + </sect3> + </sect2> + + </sect1> + + <sect1 id="dialout"> + <title>Dial-out Service</title> + + <warning> + <para>As of &os; 8.0, device nodes for serial ports have been + renamed from + <filename>/dev/cuad<replaceable>N</replaceable></filename> to + <filename>/dev/cuau<replaceable>N</replaceable></filename>. + &os; 7.X users will have to adapt the following + documentation according to these changes.</para> + </warning> + + <indexterm><primary>dial-out service</primary></indexterm> + + <para>The following are tips for getting your host to be able to connect + over the modem to another computer. This is appropriate for + establishing a terminal session with a remote host.</para> + + <para>This is useful to log onto a BBS.</para> + + <para>This kind of connection can be extremely helpful to get a file on + the Internet if you have problems with PPP. If you need to FTP + something and PPP is broken, use the terminal session to FTP it. Then + use zmodem to transfer it to your machine.</para> + + <sect2 id="hayes-unsupported"> + <title>My Stock Hayes Modem Is Not Supported, What Can I Do?</title> + + <para>Actually, the manual page for <command>tip</command> is out of + date. There is a generic Hayes dialer already built in. Just use + <literal>at=hayes</literal> in your <filename>/etc/remote</filename> + file.</para> + + <para>The Hayes driver is not smart enough to recognize some of the + advanced features of newer modems—messages like + <literal>BUSY</literal>, <literal>NO DIALTONE</literal>, or + <literal>CONNECT 115200</literal> will just confuse it. You should + turn those messages off when you use <command>tip</command> (using + <command>ATX0&W</command>).</para> + + <para>Also, the dial timeout for <command>tip</command> is 60 seconds. + Your modem should use something less, or else tip will think there is + a communication problem. Try <command>ATS7=45&W</command>.</para> + </sect2> + + <sect2 id="direct-at"> + <title>How Am I Expected to Enter These <literal>AT</literal> Commands?</title> + + <indexterm> + <primary><filename>/etc/remote</filename></primary> + </indexterm> + <para>Make what is called a <quote>direct</quote> entry in your + <filename>/etc/remote</filename> file. For example, if your modem is + hooked up to the first serial port, <filename>/dev/cuau0</filename>, + then put in the following line:</para> + + <programlisting>cuau0:dv=/dev/cuau0:br#19200:pa=none</programlisting> + + <para>Use the highest bps rate your modem supports in the br capability. + Then, type <command>tip cuau0</command> and you will be connected to + your modem.</para> + + <para>Or use <command>cu</command> as <username>root</username> with the + following command:</para> + + <screen>&prompt.root; <userinput>cu -l<replaceable>line</replaceable> -s<replaceable>speed</replaceable></userinput></screen> + + <para><replaceable>line</replaceable> is the serial port + (e.g., <filename>/dev/cuau0</filename>) and + <replaceable>speed</replaceable> is the speed + (e.g., <literal>57600</literal>). When you are done entering the AT + commands type <command>~.</command> to exit.</para> + </sect2> + + <sect2 id="gt-failure"> + <title>The <literal>@</literal> Sign for the pn Capability Does Not + Work!</title> + + <para>The <literal>@</literal> sign in the phone number capability tells + tip to look in <filename>/etc/phones</filename> for a phone number. + But the <literal>@</literal> sign is also a special character in + capability files like <filename>/etc/remote</filename>. Escape it + with a backslash:</para> + + <programlisting>pn=\@</programlisting> + </sect2> + + <sect2 id="dial-command-line"> + <title>How Can I Dial a Phone Number on the Command Line?</title> + + <para>Put what is called a <quote>generic</quote> entry in your + <filename>/etc/remote</filename> file. For example:</para> + + <programlisting>tip115200|Dial any phone number at 115200 bps:\ + :dv=/dev/cuau0:br#115200:at=hayes:pa=none:du: +tip57600|Dial any phone number at 57600 bps:\ + :dv=/dev/cuau0:br#57600:at=hayes:pa=none:du:</programlisting> + + <para>Then you can do things like:</para> + + <screen>&prompt.root; <userinput>tip -115200 5551234</userinput></screen> + + <para>If you prefer <command>cu</command> over <command>tip</command>, + use a generic <literal>cu</literal> entry:</para> + + <programlisting>cu115200|Use cu to dial any number at 115200bps:\ + :dv=/dev/cuau1:br#57600:at=hayes:pa=none:du:</programlisting> + + <para>and type:</para> + + <screen>&prompt.root; <userinput>cu 5551234 -s 115200</userinput></screen> + </sect2> + + <sect2 id="set-bps"> + <title>Do I Have to Type in the bps Rate Every Time I Do That?</title> + + <para>Put in an entry for <literal>tip1200</literal> or + <literal>cu1200</literal>, but go ahead and use whatever bps rate is + appropriate with the br capability. <command>tip</command> thinks a + good default is 1200 bps which is why it looks for a + <literal>tip1200</literal> entry. You do not have to use + 1200 bps, though.</para> + </sect2> + + <sect2 id="terminal-server"> + <title>I Access a Number of Hosts Through a Terminal Server</title> + + <para>Rather than waiting until you are connected and typing + <command>CONNECT <replaceable>host</replaceable></command> each time, + use tip's <literal>cm</literal> capability. For example, these entries + in <filename>/etc/remote</filename>:</para> + + <programlisting>pain|pain.deep13.com|Forrester's machine:\ + :cm=CONNECT pain\n:tc=deep13: +muffin|muffin.deep13.com|Frank's machine:\ + :cm=CONNECT muffin\n:tc=deep13: +deep13:Gizmonics Institute terminal server:\ + :dv=/dev/cuau2:br#38400:at=hayes:du:pa=none:pn=5551234:</programlisting> + + <para>will let you type <command>tip pain</command> or <command>tip + muffin</command> to connect to the hosts <hostid>pain</hostid> or + <hostid>muffin</hostid>, and <command>tip deep13</command> to get to + the terminal server.</para> + </sect2> + + <sect2 id="tip-multiline"> + <title>Can Tip Try More Than One Line for Each Site?</title> + + <para>This is often a problem where a university has several modem lines + and several thousand students trying to use them.</para> + + <para>Make an entry for your university in + <filename>/etc/remote</filename> and use <literal>@</literal> for the + <literal>pn</literal> capability:</para> + + <programlisting>big-university:\ + :pn=\@:tc=dialout +dialout:\ + :dv=/dev/cuau3:br#9600:at=courier:du:pa=none:</programlisting> + + <para>Then, list the phone numbers for the university in + <filename>/etc/phones</filename>:</para> + + <programlisting>big-university 5551111 +big-university 5551112 +big-university 5551113 +big-university 5551114</programlisting> + + <para><command>tip</command> will try each one in the listed order, then + give up. If you want to keep retrying, run <command>tip</command> in + a while loop.</para> + </sect2> + + <sect2 id="multi-controlp"> + <title>Why Do I Have to Hit + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>P</keycap> + </keycombo> + Twice to Send + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>P</keycap> + </keycombo> + Once?</title> + + <para><keycombo action="simul"><keycap>Ctrl</keycap><keycap>P</keycap></keycombo> + is the default <quote>force</quote> character, used to tell + <command>tip</command> that the next character is literal data. You + can set the force character to any other character with the + <command>~s</command> escape, which means <quote>set a + variable.</quote></para> + + <para>Type + <command>~sforce=<replaceable>single-char</replaceable></command> + followed by a newline. <replaceable>single-char</replaceable> is any + single character. If you leave out + <replaceable>single-char</replaceable>, then the force character is + the nul character, which you can get by typing + <keycombo action="simul"> + <keycap>Ctrl</keycap><keycap>2</keycap> + </keycombo> + or + <keycombo action="simul"> + <keycap>Ctrl</keycap><keycap>Space</keycap> + </keycombo>. + A pretty good value for <replaceable>single-char</replaceable> is + <keycombo action="simul"> + <keycap>Shift</keycap> + <keycap>Ctrl</keycap> + <keycap>6</keycap> + </keycombo>, which is only used on some terminal + servers.</para> + + <para>You can have the force character be whatever you want by + specifying the following in your + <filename>$HOME/.tiprc</filename> file:</para> + + <programlisting>force=<replaceable>single-char</replaceable></programlisting> + </sect2> + + <sect2 id="uppercase"> + <title>Suddenly Everything I Type Is in Upper Case??</title> + + <para>You must have pressed + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>A</keycap> + </keycombo>, <command>tip</command>'s + <quote>raise character,</quote> specially designed for people with + broken caps-lock keys. Use <command>~s</command> as above and set the + variable <literal>raisechar</literal> to something reasonable. In + fact, you can set it to the same as the force character, if you never + expect to use either of these features.</para> + + <para>Here is a sample <filename>.tiprc</filename> file perfect for + <application>Emacs</application> users who need to type + <keycombo action="simul"> + <keycap>Ctrl</keycap><keycap>2</keycap> + </keycombo> + and + <keycombo action="simul"> + <keycap>Ctrl</keycap><keycap>A</keycap> + </keycombo> + a lot:</para> + + <programlisting>force=^^ +raisechar=^^</programlisting> + + <para>The <literal>^^</literal> is + <keycombo action="simul"> + <keycap>Shift</keycap><keycap>Ctrl</keycap><keycap>6</keycap> + </keycombo>.</para> + + </sect2> + + <sect2 id="tip-filetransfer"> + <title>How Can I Do File Transfers with <command>tip</command>?</title> + + <para>If you are talking to another &unix; system, you can send and + receive files with <command>~p</command> (put) and + <command>~t</command> (take). These commands run + <command>cat</command> and <command>echo</command> on the remote + system to accept and send files. The syntax is:</para> + + <cmdsynopsis> + <command>~p</command> + <arg choice="plain">local-file</arg> + <arg choice="opt">remote-file</arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>~t</command> + <arg choice="plain">remote-file</arg> + <arg choice="opt">local-file</arg> + </cmdsynopsis> + + <para>There is no error checking, so you probably should use another + protocol, like zmodem.</para> + </sect2> + + <sect2 id="zmodem-tip"> + <title>How Can I Run <application>zmodem</application> with <command>tip</command>?</title> + + <para>To receive files, start the sending program on the remote end. + Then, type <command>~C rz</command> to begin receiving them + locally.</para> + + <para>To send files, start the receiving program on the remote end. + Then, type <command>~C sz <replaceable>files</replaceable></command> + to send them to the remote system.</para> + </sect2> + </sect1> + + <sect1 id="serialconsole-setup"> + <sect1info> + <authorgroup> + <author> + <firstname>Kazutaka</firstname> + <surname>YOKOTA</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <authorgroup> + <author> + <firstname>Bill</firstname> + <surname>Paul</surname> + <contrib>Based on a document by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Setting Up the Serial Console</title> + + <warning> + <para>As of &os; 8.0, device nodes for serial ports have been + renamed from + <filename>/dev/ttyd<replaceable>N</replaceable></filename> to + <filename>/dev/ttyu<replaceable>N</replaceable></filename>. + &os; 7.X users will have to adapt the following + documentation according to these changes.</para> + </warning> + + <indexterm><primary>serial console</primary></indexterm> + + <sect2 id="serialconsole-intro"> + <title>Introduction</title> + + <para>FreeBSD has the ability to boot on a system with only + a dumb terminal on a serial port as a console. Such a configuration + should be useful for two classes of people: system administrators who + wish to install FreeBSD on machines that have no keyboard or monitor + attached, and developers who want to debug the kernel or device + drivers.</para> + + <para>As described in <xref linkend="boot">, FreeBSD employs a three + stage bootstrap. The first two stages are in the boot block code which + is stored at the beginning of the FreeBSD slice on the boot disk. The + boot block will then load and run the boot loader + (<filename>/boot/loader</filename>) as the third stage code.</para> + + <para>In order to set up the serial console you must configure the boot + block code, the boot loader code and the kernel.</para> + + </sect2> + + <sect2 id="serialconsole-howto-fast"> + <title>Serial Console Configuration, Terse Version</title> + + <para>This section assumes that you are using the default setup + and just want a fast overview of setting up the serial + console.</para> + + <procedure> + + <step> + <para>Connect the serial cable to <devicename>COM1</devicename> and + the controlling terminal.</para> + </step> + + <step> + <para>To see all boot messages on the serial console, issue + the following command while logged in as the superuser:</para> + <screen>&prompt.root; echo 'console="comconsole"' >> /boot/loader.conf</screen> + </step> + + <step> + <para>Edit <filename>/etc/ttys</filename> and change + <literal>off</literal> to <literal>on</literal> and + <literal>dialup</literal> to <literal>vt100</literal> for the + <devicename>ttyu0</devicename> entry. Otherwise a password will + not be required to connect via the serial console, resulting in a + potential security hole.</para> + </step> + + <step> + <para>Reboot the system to see if the changes took effect.</para> + </step> + + </procedure> + + <para>If a different configuration is required, a more in depth + configuration explanation exists in + <xref linkend="serialconsole-howto">.</para> + </sect2> + + <sect2 id="serialconsole-howto"> + <title>Serial Console Configuration</title> + + <procedure> + <step> + <para>Prepare a serial cable.</para> + + <indexterm><primary>null-modem cable</primary></indexterm> + <para>You will need either a null-modem cable or a standard serial + cable and a null-modem adapter. See <xref linkend="serial-cables-ports"> for + a discussion on serial cables.</para> + </step> + + <step> + <para>Unplug your keyboard.</para> + + <para>Most PC systems probe for the keyboard during the Power-On + Self-Test (POST) and will generate an error if the keyboard is not + detected. Some machines complain loudly about the lack of a + keyboard and will not continue to boot until it is plugged + in.</para> + + <para>If your computer complains about the error, but boots anyway, + then you do not have to do anything special. (Some machines with + Phoenix BIOS installed merely say <errorname>Keyboard + failed</errorname> and continue to boot normally.)</para> + + <para>If your computer refuses to boot without a keyboard attached + then you will have to configure the BIOS so that it ignores this + error (if it can). Consult your motherboard's manual for details + on how to do this.</para> + + <tip> + <para>Set the keyboard to <quote>Not installed</quote> in the + BIOS setup. You will still + be able to use your keyboard. All this does is tell the BIOS + not to probe for a keyboard at power-on. Your BIOS should not + complain if the keyboard is absent. You can leave the + keyboard plugged in even with this flag set to <quote>Not + installed</quote> and the keyboard will still work. If the + above option is not present in the BIOS, look for an + <quote>Halt on Error</quote> option instead. Setting this to + <quote>All but Keyboard</quote> or even to + <quote>No Errors</quote>, will have the same effect.</para> + </tip> + + <note> + <para>If your system has a &ps2; mouse, chances are very good that + you may have to unplug your mouse as well as your keyboard. + This is because &ps2; mice share some hardware with the keyboard + and leaving the mouse plugged in can fool the keyboard probe + into thinking the keyboard is still there. It is said that a + Gateway 2000 Pentium 90 MHz system with an AMI BIOS that + behaves this way. In general, this is not a problem since the + mouse is not much good without the keyboard anyway.</para> + </note> + </step> + + <step> + <para>Plug a dumb terminal into <devicename>COM1</devicename> + (<devicename>sio0</devicename>).</para> + + <para>If you do not have a dumb terminal, you can use an old PC/XT + with a modem program, or the serial port on another &unix; box. If + you do not have a <devicename>COM1</devicename> + (<devicename>sio0</devicename>), get one. At this time, there is + no way to select a port other than <devicename>COM1</devicename> + for the boot blocks without recompiling the boot blocks. If you + are already using <devicename>COM1</devicename> for another + device, you will have to temporarily remove that device and + install a new boot block and kernel once you get FreeBSD up and + running. (It is assumed that <devicename>COM1</devicename> will + be available on a file/compute/terminal server anyway; if you + really need <devicename>COM1</devicename> for something else + (and you cannot switch that something else to + <devicename>COM2</devicename> (<devicename>sio1</devicename>)), + then you probably should not even be bothering with all this in + the first place.)</para> + </step> + + <step> + <para>Make sure the configuration file of your kernel has + appropriate flags set for <devicename>COM1</devicename> + (<devicename>sio0</devicename>).</para> + + <para>Relevant flags are:</para> + + <variablelist> + <varlistentry> + <term><literal>0x10</literal></term> + + <listitem> + <para>Enables console support for this unit. The other + console flags are ignored unless this is set. Currently, at + most one unit can have console support; the first one (in + config file order) with this flag set is preferred. This + option alone will not make the serial port the console. Set + the following flag or use the <option>-h</option> option + described below, together with this flag.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>0x20</literal></term> + + <listitem> + <para>Forces this unit to be the console (unless there is + another higher priority console), regardless of the + <option>-h</option> option discussed below. + The flag <literal>0x20</literal> must be used + together with the <option>0x10</option> flag.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>0x40</literal></term> + + <listitem> + <para>Reserves this unit (in conjunction with + <literal>0x10</literal>) and makes the unit + unavailable for normal access. You should not set + this flag to the serial port unit which you want to + use as the serial console. The only use of this + flag is to designate the unit for kernel remote + debugging. See <ulink + url="&url.books.developers-handbook;/index.html">The + Developer's Handbook</ulink> for more information on + remote debugging.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Example:</para> + + <programlisting>device sio0 flags 0x10</programlisting> + + <para>See the &man.sio.4; manual page for more details.</para> + + <para>If the flags were not set, you need to run UserConfig (on a + different console) or recompile the kernel.</para> + </step> + + <step> + <para>Create <filename>boot.config</filename> in the root directory + of the <literal>a</literal> partition on the boot drive.</para> + + <para>This file will instruct the boot block code how you would like + to boot the system. In order to activate the serial console, you + need one or more of the following options—if you want + multiple options, include them all on the same line:</para> + + <variablelist> + <varlistentry> + <term><option>-h</option></term> + + <listitem> + <para>Toggles internal and serial consoles. You can use this + to switch console devices. For instance, if you boot from + the internal (video) console, you can use + <option>-h</option> to direct the boot loader and the kernel + to use the serial port as its console device. Alternatively, + if you boot from the serial port, you can use the + <option>-h</option> to tell the boot loader and the kernel + to use the video display as the console instead.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-D</option></term> + + <listitem> + <para>Toggles single and dual console configurations. In the + single configuration the console will be either the internal + console (video display) or the serial port, depending on the + state of the <option>-h</option> option above. In the dual + console configuration, both the video display and the + serial port will become the console at the same time, + regardless of the state of the <option>-h</option> option. + However, note that the dual console configuration takes + effect only during the boot block is running. Once the boot + loader gets control, the console specified by the + <option>-h</option> option becomes the only console.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><option>-P</option></term> + + <listitem> + <para>Makes the boot block probe the keyboard. If no keyboard + is found, the <option>-D</option> and <option>-h</option> + options are automatically set.</para> + + <note> + <para>Due to space constraints in the current version of the + boot blocks, the <option>-P</option> option is capable of + detecting extended keyboards only. Keyboards with less + than 101 keys (and without F11 and F12 keys) may not be + detected. Keyboards on some laptop computers may not be + properly found because of this limitation. If this is + the case with your system, you have to abandon using + the <option>-P</option> option. Unfortunately there is no + workaround for this problem.</para> + </note> + </listitem> + </varlistentry> + </variablelist> + + <para>Use either the <option>-P</option> option to select the + console automatically, or the <option>-h</option> option to + activate the serial console.</para> + + <para>You may include other options described in &man.boot.8; as + well.</para> + + <para>The options, except for <option>-P</option>, will be passed to + the boot loader (<filename>/boot/loader</filename>). The boot + loader will determine which of the internal video or the serial + port should become the console by examining the state of the + <option>-h</option> option alone. This means that if you specify + the <option>-D</option> option but not the <option>-h</option> + option in <filename>/boot.config</filename>, you can use the + serial port as the console only during the boot block; the boot + loader will use the internal video display as the console.</para> + </step> + + <step> + <para>Boot the machine.</para> + + <para>When you start your FreeBSD box, the boot blocks will echo the + contents of <filename>/boot.config</filename> to the console. For + example:</para> + + <screen>/boot.config: -P +Keyboard: no</screen> + + <para>The second line appears only if you put <option>-P</option> in + <filename>/boot.config</filename> and indicates presence/absence + of the keyboard. These messages go to either serial or internal + console, or both, depending on the option in + <filename>/boot.config</filename>.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry align="left">Options</entry> + <entry align="left">Message goes to</entry> + </row> + </thead> + + <tbody> + <row> + <entry>none</entry> + <entry>internal console</entry> + </row> + + <row> + <entry><option>-h</option></entry> + <entry>serial console</entry> + </row> + + <row> + <entry><option>-D</option></entry> + <entry>serial and internal consoles</entry> + </row> + + <row> + <entry><option>-Dh</option></entry> + <entry>serial and internal consoles</entry> + </row> + + <row> + <entry><option>-P</option>, keyboard present</entry> + <entry>internal console</entry> + </row> + + <row> + <entry><option>-P</option>, keyboard absent</entry> + <entry>serial console</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>After the above messages, there will be a small pause before + the boot blocks continue loading the boot loader and before any + further messages printed to the console. Under normal + circumstances, you do not need to interrupt the boot blocks, but + you may want to do so in order to make sure things are set up + correctly.</para> + + <para>Hit any key, other than <keycap>Enter</keycap>, at the console + to interrupt the boot process. The boot blocks will then prompt + you for further action. You should now see something like:</para> + + <screen>>> FreeBSD/i386 BOOT +Default: 0:ad(0,a)/boot/loader +boot:</screen> + + <para>Verify the above message appears on either the serial or + internal console or both, according to the options you put in + <filename>/boot.config</filename>. If the message appears in the + correct console, hit <keycap>Enter</keycap> to continue the boot + process.</para> + + <para>If you want the serial console but you do not see the prompt + on the serial terminal, something is wrong with your settings. In + the meantime, you enter <option>-h</option> and hit + <keycap>Enter</keycap> or <keycap>Return</keycap> (if possible) + to tell the boot block (and then the boot loader and the kernel) + to choose the serial port for the console. Once the system is + up, go back and check what went wrong.</para> + </step> + </procedure> + + <para>After the boot loader is loaded and you are in the third stage of + the boot process you can still switch between the internal console and + the serial console by setting appropriate environment variables in the + boot loader. See <xref linkend="serialconsole-loader">.</para> + </sect2> + + <sect2 id="serialconsole-summary"> + <title>Summary</title> + + <para>Here is the summary of various settings discussed in this section + and the console eventually selected.</para> + + <sect3> + <title>Case 1: You Set the Flags to 0x10 for + <devicename>sio0</devicename></title> + + <programlisting>device sio0 flags 0x10</programlisting> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="4"> + <thead> + <row> + <entry align="left">Options in /boot.config</entry> + <entry align="left">Console during boot blocks</entry> + <entry align="left">Console during boot loader</entry> + <entry align="left">Console in kernel</entry> + </row> + </thead> + + <tbody> + <row> + <entry>nothing</entry> + <entry>internal</entry> + <entry>internal</entry> + <entry>internal</entry> + </row> + + <row> + <entry><option>-h</option></entry> + <entry>serial</entry> + <entry>serial</entry> + <entry>serial</entry> + </row> + + <row> + <entry><option>-D</option></entry> + <entry>serial and internal</entry> + <entry>internal</entry> + <entry>internal</entry> + </row> + + <row> + <entry><option>-Dh</option></entry> + <entry>serial and internal</entry> + <entry>serial</entry> + <entry>serial</entry> + </row> + + <row> + <entry><option>-P</option>, keyboard present</entry> + <entry>internal</entry> + <entry>internal</entry> + <entry>internal</entry> + </row> + + <row> + <entry><option>-P</option>, keyboard absent</entry> + <entry>serial and internal</entry> + <entry>serial</entry> + <entry>serial</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect3> + + <sect3> + <title>Case 2: You Set the Flags to 0x30 for <devicename>sio0</devicename></title> + + <programlisting>device sio0 flags 0x30</programlisting> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="4"> + <thead> + <row> + <entry align="left">Options in /boot.config</entry> + <entry align="left">Console during boot blocks</entry> + <entry align="left">Console during boot loader</entry> + <entry align="left">Console in kernel</entry> + </row> + </thead> + + <tbody> + <row> + <entry>nothing</entry> + <entry>internal</entry> + <entry>internal</entry> + <entry>serial</entry> + </row> + + <row> + <entry><option>-h</option></entry> + <entry>serial</entry> + <entry>serial</entry> + <entry>serial</entry> + </row> + + <row> + <entry><option>-D</option></entry> + <entry>serial and internal</entry> + <entry>internal</entry> + <entry>serial</entry> + </row> + + <row> + <entry><option>-Dh</option></entry> + <entry>serial and internal</entry> + <entry>serial</entry> + <entry>serial</entry> + </row> + + <row> + <entry><option>-P</option>, keyboard present</entry> + <entry>internal</entry> + <entry>internal</entry> + <entry>serial</entry> + </row> + + <row> + <entry><option>-P</option>, keyboard absent</entry> + <entry>serial and internal</entry> + <entry>serial</entry> + <entry>serial</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect3> + </sect2> + + <sect2 id="serialconsole-tips"> + <title>Tips for the Serial Console</title> + + <sect3> + <title>Setting a Faster Serial Port Speed</title> + + <para>By default, the serial port settings are: 9600 baud, 8 + bits, no parity, and 1 stop bit. If you wish to change the default + console speed, you have the following options:</para> + + <itemizedlist> + <listitem> + <para>Recompile the boot blocks + with <makevar>BOOT_COMCONSOLE_SPEED</makevar> set to the new + console speed. See <xref linkend="serialconsole-com2"> for + detailed instructions about building and installing new boot + blocks.</para> + + <para>If the serial console is configured in some other way than + by booting with <option>-h</option>, or if the serial console + used by the kernel is different from the one used by the boot + blocks, then you must also add the following option to the + kernel configuration file and compile a new kernel:</para> + + <programlisting>options CONSPEED=19200</programlisting> + </listitem> + + <listitem> + <para>Use the <option>-S</option> boot option of the kernel. + The <option>-S</option> command line option can be added + to <filename>/boot.config</filename>. See the &man.boot.8; + manual page for a description of how to add options + to <filename>/boot.config</filename> and a list of the supported + options.</para> + </listitem> + + <listitem> + <para>Enable the <varname>comconsole_speed</varname> + option in your <filename>/boot/loader.conf</filename> + file.</para> + + <para>This option depends on <varname>console</varname>, + <varname>boot_serial</varname>, and + <varname>boot_multicons</varname> being set in + <filename>/boot/loader.conf</filename> too. An example of using + <varname>comconsole_speed</varname> to change the serial console + speed is:</para> + + <programlisting>boot_multicons="YES" +boot_serial="YES" +comconsole_speed="115200" +console="comconsole,vidconsole"</programlisting> + </listitem> + </itemizedlist> + </sect3> + + <sect3 id="serialconsole-com2"> + <title>Using Serial Port Other Than <devicename>sio0</devicename> for + the Console</title> + + <para>Using a port other than <devicename>sio0</devicename> as the + console requires some recompiling. If you want to use another + serial port for whatever reasons, recompile the boot blocks, the + boot loader and the kernel as follows.</para> + + <procedure> + <step> + <para>Get the kernel source. (See <xref + linkend="updating-upgrading">)</para> + </step> + + <step> + <para>Edit <filename>/etc/make.conf</filename> and set + <literal>BOOT_COMCONSOLE_PORT</literal> to the address of the + port you want to use (0x3F8, 0x2F8, 0x3E8 or 0x2E8). Only + <devicename>sio0</devicename> through + <devicename>sio3</devicename> (<devicename>COM1</devicename> + through <devicename>COM4</devicename>) can be used; multiport + serial cards will not work. No interrupt setting is + needed.</para> + </step> + + <step> + <para>Create a custom kernel configuration file and add + appropriate flags for the serial port you want to use. For + example, if you want to make <devicename>sio1</devicename> + (<devicename>COM2</devicename>) the console:</para> + + <programlisting>device sio1 flags 0x10</programlisting> + + <para>or</para> + + <programlisting>device sio1 flags 0x30</programlisting> + + <para>The console flags for the other serial ports should not be + set.</para> + </step> + + <step> + <para>Recompile and install the boot blocks and the boot + loader:</para> + + <screen>&prompt.root; <userinput>cd /sys/boot</userinput> +&prompt.root; <userinput>make clean</userinput> +&prompt.root; <userinput>make</userinput> +&prompt.root; <userinput>make install</userinput></screen> + </step> + + <step> + <para>Rebuild and install the kernel.</para> + </step> + + <step> + <para>Write the boot blocks to the boot disk with + &man.bsdlabel.8; and boot from the new kernel.</para> + </step> + </procedure> + </sect3> + + <sect3 id="serialconsole-ddb"> + <title>Entering the DDB Debugger from the Serial Line</title> + + <para>If you wish to drop into the kernel debugger from the serial + console (useful for remote diagnostics, but also dangerous if you + generate a spurious BREAK on the serial port!) then you should + compile your kernel with the following options:</para> + + <programlisting>options BREAK_TO_DEBUGGER +options DDB</programlisting> + </sect3> + + <sect3> + <title>Getting a Login Prompt on the Serial Console</title> + + <para>While this is not required, you may wish to get a + <emphasis>login</emphasis> prompt over the serial line, now that you + can see boot messages and can enter the kernel debugging session + through the serial console. Here is how to do it.</para> + + <para>Open the file <filename>/etc/ttys</filename> with an editor + and locate the lines:</para> + + <programlisting>ttyu0 "/usr/libexec/getty std.9600" unknown off secure +ttyu1 "/usr/libexec/getty std.9600" unknown off secure +ttyu2 "/usr/libexec/getty std.9600" unknown off secure +ttyu3 "/usr/libexec/getty std.9600" unknown off secure</programlisting> + + <para><devicename>ttyu0</devicename> through + <devicename>ttyu3</devicename> corresponds to + <devicename>COM1</devicename> through <devicename>COM4</devicename>. + Change <literal>off</literal> to <literal>on</literal> for the + desired port. If you have changed the speed of the serial port, + you need to change <literal>std.9600</literal> to match the current + setting, e.g., <literal>std.19200</literal>.</para> + + <para>You may also want to change the terminal type from + <literal>unknown</literal> to the actual type of your serial + terminal.</para> + + <para>After editing the file, you must <command>kill -HUP 1</command> + to make this change take effect.</para> + </sect3> + </sect2> + + <sect2 id="serialconsole-loader"> + <title>Changing Console from the Boot Loader</title> + + <para>Previous sections described how to set up the serial console by + tweaking the boot block. This section shows that you can specify the + console by entering some commands and environment variables in the + boot loader. As the boot loader is invoked at the third stage of the + boot process, after the boot block, the settings in the boot loader + will override the settings in the boot block.</para> + + <sect3> + <title>Setting Up the Serial Console</title> + + <para>You can easily specify the boot loader and the kernel to use the + serial console by writing just one line in + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>console="comconsole"</programlisting> + + <para>This will take effect regardless of the settings in the boot + block discussed in the previous section.</para> + + <para>You had better put the above line as the first line of + <filename>/boot/loader.conf</filename> so as to see boot messages on + the serial console as early as possible.</para> + + <para>Likewise, you can specify the internal console as:</para> + + <programlisting>console="vidconsole"</programlisting> + + <para>If you do not set the boot loader environment variable + <envar>console</envar>, the boot loader, and subsequently the + kernel, will use whichever console indicated by the + <option>-h</option> option in the boot block.</para> + + <para>The console can be specified in + <filename>/boot/loader.conf.local</filename> or in + <filename>/boot/loader.conf</filename>.</para> + + <para>See &man.loader.conf.5; for more information.</para> + + <note> + <para>At the moment, the boot loader has no option equivalent to the + <option>-P</option> option in the boot block, and there is no + provision to automatically select the internal console and the + serial console based on the presence of the keyboard.</para> + </note> + </sect3> + + <sect3> + <title>Using a Serial Port Other Than <devicename>sio0</devicename> for + the Console</title> + + <para>You need to recompile the boot loader to use a serial port other + than <devicename>sio0</devicename> for the serial console. Follow the + procedure described in <xref linkend="serialconsole-com2">.</para> + </sect3> + </sect2> + + <sect2 id="serialconsole-caveats"> + <title>Caveats</title> + + <para>The idea here is to allow people to set up dedicated servers that + require no graphics hardware or attached keyboards. Unfortunately, + while most systems will let you boot without a keyboard, there + are quite a few that will not let you boot without a graphics adapter. + Machines with AMI BIOSes can be configured to boot with no graphics + adapter installed by changing the + <quote>graphics adapter</quote> setting in the CMOS configuration to + <quote>Not installed.</quote></para> + + <para>However, many machines do not support this option and will refuse + to boot if you have no display hardware in the system. With these + machines, you will have to leave some kind of graphics card plugged in, + (even if it is just a junky mono board) although you will not have to + attach a monitor. You might also try installing an AMI + BIOS.</para> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO8859-1/books/handbook/txtfiles.ent b/en_US.ISO8859-1/books/handbook/txtfiles.ent new file mode 100644 index 0000000000..26a1f8ec72 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/txtfiles.ent @@ -0,0 +1,70 @@ +<!-- + Creates entities for each .txt screenshot that is included in the + Handbook. + + Each entity is named txt.dir.foo, where dir is the directory in + which it is stored, and foo is its filename, without the '.txt' + extension. + + Entities should be listed in alphabetical order. + + $FreeBSD$ +--> + +<!ENTITY txt.install.adduser1 SYSTEM "install/adduser1.txt"> +<!ENTITY txt.install.adduser2 SYSTEM "install/adduser2.txt"> +<!ENTITY txt.install.adduser3 SYSTEM "install/adduser3.txt"> +<!ENTITY txt.install.boot-mgr SYSTEM "install/boot-mgr.txt"> +<!ENTITY txt.install.config-country SYSTEM "install/config-country.txt"> +<!ENTITY txt.install.console-saver1 SYSTEM "install/console-saver1.txt"> +<!ENTITY txt.install.console-saver2 SYSTEM "install/console-saver2.txt"> +<!ENTITY txt.install.console-saver3 SYSTEM "install/console-saver3.txt"> +<!ENTITY txt.install.console-saver4 SYSTEM "install/console-saver4.txt"> +<!ENTITY txt.install.disklabel-auto SYSTEM "install/disklabel-auto.txt"> +<!ENTITY txt.install.disklabel-ed1 SYSTEM "install/disklabel-ed1.txt"> +<!ENTITY txt.install.disklabel-ed2 SYSTEM "install/disklabel-ed2.txt"> +<!ENTITY txt.install.disklabel-fs SYSTEM "install/disklabel-fs.txt"> +<!ENTITY txt.install.disklabel-root1 SYSTEM "install/disklabel-root1.txt"> +<!ENTITY txt.install.disklabel-root2 SYSTEM "install/disklabel-root2.txt"> +<!ENTITY txt.install.disklabel-root3 SYSTEM "install/disklabel-root3.txt"> +<!ENTITY txt.install.dist-set SYSTEM "install/dist-set.txt"> +<!ENTITY txt.install.dist-set2 SYSTEM "install/dist-set2.txt"> +<!ENTITY txt.install.docmenu1 SYSTEM "install/docmenu1.txt"> +<!ENTITY txt.install.ed0-conf SYSTEM "install/ed0-conf.txt"> +<!ENTITY txt.install.ed0-conf2 SYSTEM "install/ed0-conf2.txt"> +<!ENTITY txt.install.edit-inetd-conf SYSTEM "install/edit-inetd-conf.txt"> +<!ENTITY txt.install.fdisk-drive1 SYSTEM "install/fdisk-drive1.txt"> +<!ENTITY txt.install.fdisk-drive2 SYSTEM "install/fdisk-drive2.txt"> +<!ENTITY txt.install.fdisk-edit1 SYSTEM "install/fdisk-edit1.txt"> +<!ENTITY txt.install.fdisk-edit2 SYSTEM "install/fdisk-edit2.txt"> +<!ENTITY txt.install.ftp-anon1 SYSTEM "install/ftp-anon1.txt"> +<!ENTITY txt.install.ftp-anon2 SYSTEM "install/ftp-anon2.txt"> +<!ENTITY txt.install.hdwrconf SYSTEM "install/hdwrconf.txt"> +<!ENTITY txt.install.keymap SYSTEM "install/keymap.txt"> +<!ENTITY txt.install.main-doc SYSTEM "install/main-doc.txt"> +<!ENTITY txt.install.main-keymap SYSTEM "install/main-keymap.txt"> +<!ENTITY txt.install.main-options SYSTEM "install/main-options.txt"> +<!ENTITY txt.install.main-std SYSTEM "install/main-std.txt"> +<!ENTITY txt.install.main1 SYSTEM "install/main1.txt"> +<!ENTITY txt.install.mainexit SYSTEM "install/mainexit.txt"> +<!ENTITY txt.install.media SYSTEM "install/media.txt"> +<!ENTITY txt.install.mouse1 SYSTEM "install/mouse1.txt"> +<!ENTITY txt.install.mouse2 SYSTEM "install/mouse2.txt"> +<!ENTITY txt.install.mouse3 SYSTEM "install/mouse3.txt"> +<!ENTITY txt.install.mouse4 SYSTEM "install/mouse4.txt"> +<!ENTITY txt.install.mouse5 SYSTEM "install/mouse5.txt"> +<!ENTITY txt.install.mouse6 SYSTEM "install/mouse6.txt"> +<!ENTITY txt.install.nfs-server-edit SYSTEM "install/nfs-server-edit.txt"> +<!ENTITY txt.install.options SYSTEM "install/options.txt"> +<!ENTITY txt.install.pkg-cat SYSTEM "install/pkg-cat.txt"> +<!ENTITY txt.install.pkg-confirm SYSTEM "install/pkg-confirm.txt"> +<!ENTITY txt.install.pkg-install SYSTEM "install/pkg-install.txt"> +<!ENTITY txt.install.pkg-sel SYSTEM "install/pkg-sel.txt"> +<!ENTITY txt.install.probstart SYSTEM "install/probstart.txt"> +<!ENTITY txt.install.security SYSTEM "install/security.txt"> +<!ENTITY txt.install.sysinstall-exit SYSTEM "install/sysinstall-exit.txt"> +<!ENTITY txt.install.timezone1 SYSTEM "install/timezone1.txt"> +<!ENTITY txt.install.timezone2 SYSTEM "install/timezone2.txt"> +<!ENTITY txt.install.timezone3 SYSTEM "install/timezone3.txt"> +<!ENTITY txt.install.userconfig SYSTEM "../../../share/images/books/handbook/install/userconfig.txt"> +<!ENTITY txt.install.userconfig2 SYSTEM "../../../share/images/books/handbook/install/userconfig2.txt"> diff --git a/en_US.ISO8859-1/books/handbook/users/Makefile b/en_US.ISO8859-1/books/handbook/users/Makefile new file mode 100644 index 0000000000..dfa2918b7b --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/users/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= users/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/users/chapter.sgml b/en_US.ISO8859-1/books/handbook/users/chapter.sgml new file mode 100644 index 0000000000..72a780dcdb --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/users/chapter.sgml @@ -0,0 +1,1044 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="users"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Neil</firstname> + <surname>Blakey-Milner</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <!-- Feb 2000 --> + </chapterinfo> + + <title>Users and Basic Account Management</title> + + <sect1 id="users-synopsis"> + <title>Synopsis</title> + + <para>FreeBSD allows multiple users to use the computer at the same time. + Obviously, only one of those users can be sitting in front of the screen and + keyboard at any one time + <footnote> + <para>Well, unless you hook up multiple terminals, but we will + save that for <xref linkend="serialcomms">.</para> + </footnote>, but any number of users can log in through the + network to get their work done. To use the system every user must have + an account.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>The differences between the various user accounts on a FreeBSD + system.</para> + </listitem> + + <listitem> + <para>How to add user accounts.</para> + </listitem> + + <listitem> + <para>How to remove user accounts.</para> + </listitem> + + <listitem> + <para>How to change account details, such as the user's full name, or + preferred shell.</para> + </listitem> + + <listitem> + <para>How to set limits on a per-account basis, to control the + resources such as memory and CPU time that accounts and groups of + accounts are allowed to access.</para> + </listitem> + + <listitem> + <para>How to use groups to make account management easier.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand the basics of &unix; and FreeBSD (<xref + linkend="basics">).</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="users-introduction"> + <title>Introduction</title> + + <para>All access to the system is achieved via accounts, and all + processes are run by users, so user and account management are + of integral importance on FreeBSD systems.</para> + + <para>Every account on a FreeBSD system has certain information associated + with it to identify the account.</para> + + <variablelist> + <varlistentry> + <term>User name</term> + + <listitem> + <para>The user name as it would be typed at the + <prompt>login:</prompt> prompt. User names must be unique across + the computer; you may not have two users with the same + user name. There are a number of rules for creating valid user + names, documented in &man.passwd.5;; you would typically use user + names that consist of eight or fewer all lower case + characters.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Password</term> + + <listitem> + <para>Each account has a password associated with it. The password + may be blank, in which case no password will be required to access + the system. This is normally a very bad idea; every account + should have a password.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User ID (UID)</term> + + <listitem> + <para>The UID is a number, traditionally from 0 to 65535<footnote id="users-largeuidgid"> + <para>It is possible to use UID/GIDs as large as + 4294967295, but such IDs can cause serious problems + with software that makes assumptions about the values + of IDs.</para> + </footnote>, used to uniquely identify + the user to the system. Internally, FreeBSD uses the UID to + identify users—any FreeBSD commands that allow you to + specify a user name will convert it to the UID before working with + it. This means that you can have several accounts with different + user names but the same UID. As far as FreeBSD is concerned these + accounts are one user. It is unlikely you will ever need to do + this.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Group ID (GID)</term> + + <listitem> + <para>The GID is a number, traditionally from 0 to 65535<footnoteref linkend="users-largeuidgid">, used to uniquely identify + the primary group that the user belongs to. Groups are a + mechanism for controlling access to resources based on a user's + GID rather than their UID. This can significantly reduce the size + of some configuration files. A user may also be in more than one + group.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Login class</term> + + <listitem> + <para>Login classes are an extension to the group mechanism that + provide additional flexibility when tailoring the system to + different users.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Password change time</term> + + <listitem> + <para>By default FreeBSD does not force users to change their + passwords periodically. You can enforce this on a per-user basis, + forcing some or all of your users to change their passwords after + a certain amount of time has elapsed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Account expiry time</term> + + <listitem> + <para>By default FreeBSD does not expire accounts. If you are + creating accounts that you know have a limited lifespan, for + example, in a school where you have accounts for the students, + then you can specify when the account expires. After the expiry + time has elapsed the account cannot be used to log in to the + system, although the account's directories and files will + remain.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User's full name</term> + + <listitem> + <para>The user name uniquely identifies the account to FreeBSD, but + does not necessarily reflect the user's real name. This + information can be associated with the account.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Home directory</term> + + <listitem> + <para>The home directory is the full path to a directory on the + system in which the user will start when logging on to the + system. A common convention is to put all user home directories + under + <filename>/home/<replaceable>username</replaceable></filename> + or <filename>/usr/home/<replaceable>username</replaceable></filename>. + The user would store their personal files in their home directory, + and any directories they may create in there.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User shell</term> + + <listitem> + <para>The shell provides the default environment users use to + interact with the system. There are many different kinds of + shells, and experienced users will have their own preferences, + which can be reflected in their account settings.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>There are three main types of accounts: the <link + linkend="users-superuser">Superuser</link>, <link + linkend="users-system">system users</link>, and <link + linkend="users-user">user accounts</link>. The Superuser + account, usually called <username>root</username>, is used to + manage the system with no limitations on privileges. System + users run services. Finally, user accounts are used by real + people, who log on, read mail, and so forth.</para> + </sect1> + + <sect1 id="users-superuser"> + <title>The Superuser Account</title> + + <indexterm> + <primary>accounts</primary> + <secondary>superuser (root)</secondary> + </indexterm> + <para>The superuser account, usually called + <username>root</username>, comes preconfigured to facilitate + system administration, and should not be used for day-to-day + tasks like sending and receiving mail, general exploration of + the system, or programming.</para> + + <para>This is because the superuser, unlike normal user accounts, + can operate without limits, and misuse of the superuser account + may result in spectacular disasters. User accounts are unable + to destroy the system by mistake, so it is generally best to use + normal user accounts whenever possible, unless you especially + need the extra privilege.</para> + + <para>You should always double and triple-check commands you issue + as the superuser, since an extra space or missing character can + mean irreparable data loss.</para> + + <para>So, the first thing you should do after reading this + chapter is to create an unprivileged user account for yourself + for general usage if you have not already. This applies equally + whether you are running a multi-user or single-user machine. + Later in this chapter, we discuss how to create additional + accounts, and how to change between the normal user and + superuser.</para> + </sect1> + + <sect1 id="users-system"> + <title>System Accounts</title> + + <indexterm> + <primary>accounts</primary> + <secondary>system</secondary> + </indexterm> + <para>System users are those used to run services such as DNS, + mail, web servers, and so forth. The reason for this is + security; if all services ran as the superuser, they could + act without restriction.</para> + + <indexterm> + <primary>accounts</primary> + <secondary><username>daemon</username></secondary> + </indexterm> + <indexterm> + <primary>accounts</primary> + <secondary><username>operator</username></secondary> + </indexterm> + <para>Examples of system users are <username>daemon</username>, + <username>operator</username>, <username>bind</username> (for + the Domain Name Service), <username>news</username>, and + <username>www</username>.</para> + + <indexterm> + <primary>accounts</primary> + <secondary><username>nobody</username></secondary> + </indexterm> + <para><username>nobody</username> is the generic unprivileged + system user. However, it is important to keep in mind that the + more services that use <username>nobody</username>, the more + files and processes that user will become associated with, and + hence the more privileged that user becomes.</para> + </sect1> + + <sect1 id="users-user"> + <title>User Accounts</title> + + <indexterm> + <primary>accounts</primary> + <secondary>user</secondary> + </indexterm> + <para>User accounts are the primary means of access for real + people to the system, and these accounts insulate the user and + the environment, preventing the users from damaging the system + or other users, and allowing users to customize their + environment without affecting others.</para> + + <para>Every person accessing your system should have a unique user + account. This allows you to find out who is doing what, prevent + people from clobbering each others' settings or reading each + others' mail, and so forth.</para> + + <para>Each user can set up their own environment to accommodate + their use of the system, by using alternate shells, editors, key + bindings, and language.</para> + </sect1> + + <sect1 id="users-modifying"> + <title>Modifying Accounts</title> + + <indexterm> + <primary>accounts</primary> + <secondary>modifying</secondary> + </indexterm> + + <para>There are a variety of different commands available in the + &unix; environment to manipulate user accounts. The most common + commands are summarized below, followed by more detailed + examples of their usage.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"> + <colspec colwidth="2*"> + + <thead> + <row> + <entry>Command</entry> + <entry>Summary</entry> + </row> + </thead> + <tbody> + <row> + <entry>&man.adduser.8;</entry> + <entry>The recommended command-line application for adding + new users.</entry> + </row> + <row> + <entry>&man.rmuser.8;</entry> + <entry>The recommended command-line application for + removing users.</entry> + </row> + <row> + <entry>&man.chpass.1;</entry> + <entry>A flexible tool to change user database information.</entry> + </row> + <row> + <entry>&man.passwd.1;</entry> + <entry>The simple command-line tool to change user + passwords.</entry> + </row> + <row> + <entry>&man.pw.8;</entry> + <entry>A powerful and flexible tool to modify all aspects + of user accounts.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <sect2 id="users-adduser"> + <title><command>adduser</command></title> + + <indexterm> + <primary>accounts</primary> + <secondary>adding</secondary> + </indexterm> + <indexterm> + <primary><command>adduser</command></primary> + </indexterm> + <indexterm> + <primary><filename class="directory">/usr/share/skel</filename></primary> + </indexterm> + <indexterm><primary>skeleton directory</primary></indexterm> + <para>&man.adduser.8; is a simple program for + adding new users. It creates entries in the system + <filename>passwd</filename> and <filename>group</filename> + files. It will also create a home directory for the new user, + copy in the default configuration files (<quote>dotfiles</quote>) from + <filename>/usr/share/skel</filename>, and can optionally mail + the new user a welcome message.</para> + + <example> + <title>Adding a User on &os;</title> + + <screen>&prompt.root; <userinput>adduser</userinput> +Username: <userinput>jru</userinput> +Full name: <userinput>J. Random User</userinput> +Uid (Leave empty for default): +Login group [jru]: +Login group is jru. Invite jru into other groups? []: <userinput>wheel</userinput> +Login class [default]: +Shell (sh csh tcsh zsh nologin) [sh]: <userinput>zsh</userinput> +Home directory [/home/jru]: +Home directory permissions (Leave empty for default): +Use password-based authentication? [yes]: +Use an empty password? (yes/no) [no]: +Use a random password? (yes/no) [no]: +Enter password: +Enter password again: +Lock out the account after creation? [no]: +Username : jru +Password : **** +Full Name : J. Random User +Uid : 1001 +Class : +Groups : jru wheel +Home : /home/jru +Shell : /usr/local/bin/zsh +Locked : no +OK? (yes/no): <userinput>yes</userinput> +adduser: INFO: Successfully added (jru) to the user database. +Add another user? (yes/no): <userinput>no</userinput> +Goodbye! +&prompt.root;</screen> + </example> + + <note> + <para>The password you type in is not echoed, nor are asterisks + displayed. Make sure that you do not mistype the password. + </para> + </note> + </sect2> + + <sect2 id="users-rmuser"> + <title><command>rmuser</command></title> + + <indexterm><primary><command>rmuser</command></primary></indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>removing</secondary> + </indexterm> + + <para>You can use &man.rmuser.8; to + completely remove a user from the system. + &man.rmuser.8; performs the following + steps:</para> + + <procedure> + <step> + <para>Removes the user's &man.crontab.1; entry (if + any).</para> + </step> + <step> + <para>Removes any &man.at.1; jobs belonging to the + user.</para> + </step> + <step> + <para>Kills all processes owned by the user.</para> + </step> + <step> + <para>Removes the user from the system's local password + file.</para> + </step> + <step> + <para>Removes the user's home directory (if it is owned by + the user).</para> + </step> + <step> + <para>Removes the incoming mail files belonging to the user + from <filename>/var/mail</filename>.</para> + </step> + <step> + <para>Removes all files owned by the user from temporary + file storage areas such as <filename>/tmp</filename>.</para> + </step> + <step> + <para>Finally, removes the username from all groups to which + it belongs in <filename>/etc/group</filename>.</para> + + <note> + <para>If a group becomes empty and the group name is the + same as the username, the group is removed; this + complements the per-user unique groups created by + &man.adduser.8;.</para> + </note> + </step> + </procedure> + + <para>&man.rmuser.8; cannot be used to remove + superuser accounts, since that is almost always an indication + of massive destruction.</para> + + <para>By default, an interactive mode is used, which attempts to + make sure you know what you are doing.</para> + + <example> + <title><command>rmuser</command> Interactive Account Removal</title> + + <screen>&prompt.root; <userinput>rmuser jru</userinput> +Matching password entry: +jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh +Is this the entry you wish to remove? <userinput>y</userinput> +Remove user's home directory (/home/jru)? <userinput>y</userinput> +Updating password file, updating databases, done. +Updating group file: trusted (removing group jru -- personal group is empty) done. +Removing user's incoming mail file /var/mail/jru: done. +Removing files belonging to jru from /tmp: done. +Removing files belonging to jru from /var/tmp: done. +Removing files belonging to jru from /var/tmp/vi.recover: done. +&prompt.root;</screen> + </example> + </sect2> + + <sect2 id="users-chpass"> + <title><command>chpass</command></title> + + <indexterm><primary><command>chpass</command></primary></indexterm> + <para>&man.chpass.1; changes user database + information such as passwords, shells, and personal + information.</para> + + <para>Only system administrators, as the superuser, may change + other users' information and passwords with + &man.chpass.1;.</para> + + <para>When passed no options, aside from an optional username, + &man.chpass.1; displays an editor + containing user information. When the user exists from the + editor, the user database is updated with the new + information.</para> + + <note> + <para>You will be asked for your password + after exiting the editor if you are not the superuser.</para> + </note> + + <example> + <title>Interactive <command>chpass</command> by Superuser</title> + + <screen>#Changing user database information for jru. +Login: jru +Password: * +Uid [#]: 1001 +Gid [# or name]: 1001 +Change [month day year]: +Expire [month day year]: +Class: +Home directory: /home/jru +Shell: /usr/local/bin/zsh +Full Name: J. Random User +Office Location: +Office Phone: +Home Phone: +Other information:</screen> + </example> + + <para>The normal user can change only a small subset of this + information, and only for themselves.</para> + + <example> + <title>Interactive <command>chpass</command> by Normal User</title> + + <screen>#Changing user database information for jru. +Shell: /usr/local/bin/zsh +Full Name: J. Random User +Office Location: +Office Phone: +Home Phone: +Other information:</screen> + </example> + + <note> + <para>&man.chfn.1; and &man.chsh.1; are + just links to &man.chpass.1;, as + are &man.ypchpass.1;, + &man.ypchfn.1;, and + &man.ypchsh.1;. NIS support is automatic, so + specifying the <literal>yp</literal> before the command is + not necessary. If this is confusing to you, do not worry, NIS will + be covered in <xref linkend="network-servers">.</para> + </note> + </sect2> + <sect2 id="users-passwd"> + <title><command>passwd</command></title> + + <indexterm><primary><command>passwd</command></primary></indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>changing password</secondary> + </indexterm> + <para>&man.passwd.1; is the usual way to + change your own password as a user, or another user's password + as the superuser.</para> + + <note> + <para>To prevent accidental or unauthorized changes, the original + password must be entered before a new password can be set.</para> + </note> + + <example> + <title>Changing Your Password</title> + + <screen>&prompt.user; <userinput>passwd</userinput> +Changing local password for jru. +Old password: +New password: +Retype new password: +passwd: updating the database... +passwd: done</screen> + </example> + + <example> + <title>Changing Another User's Password as the Superuser</title> + + <screen>&prompt.root; <userinput>passwd jru</userinput> +Changing local password for jru. +New password: +Retype new password: +passwd: updating the database... +passwd: done</screen> + </example> + + <note> + <para>As with &man.chpass.1;, + &man.yppasswd.1; is just a link to + &man.passwd.1;, so NIS works with either + command.</para> + </note> + </sect2> + + + <sect2 id="users-pw"> + <title><command>pw</command></title> + <indexterm><primary><command>pw</command></primary></indexterm> + + <para>&man.pw.8; is a command line utility to create, remove, + modify, and display users and groups. It functions as a front + end to the system user and group files. &man.pw.8; + has a very powerful set of command line options that make it + suitable for use in shell scripts, but new users may find it + more complicated than the other commands presented + here.</para> + </sect2> + + + </sect1> + + <sect1 id="users-limiting"> + <title>Limiting Users</title> + + <indexterm><primary>limiting users</primary></indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>limiting</secondary> + </indexterm> + <para>If you have users, the ability to limit their system use may + have come to mind. FreeBSD provides + several ways an administrator can limit the amount of system + resources an individual may use. These limits are + divided into two sections: disk quotas, and other resource + limits.</para> + + <indexterm><primary>quotas</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>quotas</secondary> + </indexterm> + <indexterm><primary>disk quotas</primary></indexterm> + <para>Disk quotas limit disk usage to users, and + they + provide a way to quickly check that usage without + calculating it every time. Quotas are discussed in <xref + linkend="quotas">.</para> + + <para>The other resource limits include ways to limit the amount of + CPU, memory, and other resources a user may consume. These are + defined using login classes and are discussed here.</para> + + <indexterm> + <primary><filename>/etc/login.conf</filename></primary> + </indexterm> + <para>Login classes are defined in + <filename>/etc/login.conf</filename>. The precise semantics are + beyond the scope of this section, but are described in detail in the + &man.login.conf.5; manual page. It is sufficient to say that each + user is assigned to a login class (<literal>default</literal> by + default), and that each login class has a set of login capabilities + associated with it. A login capability is a + <literal><replaceable>name</replaceable>=<replaceable>value</replaceable></literal> + pair, where <replaceable>name</replaceable> is a well-known + identifier and <replaceable>value</replaceable> is an arbitrary + string processed accordingly depending on the name. Setting up login + classes and capabilities is rather straight-forward and is also + described in &man.login.conf.5;.</para> + + <note> + <para>The system does not normally read the configuration in + <filename>/etc/login.conf</filename> directly, but reads the database + file <filename>/etc/login.conf.db</filename> which provides + faster lookups. + To generate <filename>/etc/login.conf.db</filename> from + <filename>/etc/login.conf</filename>, execute the following + command:</para> + + <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen> + </note> + + <para>Resource limits are different from plain vanilla login + capabilities in two ways. First, for every limit, there is a soft + (current) and hard limit. A soft limit may be adjusted by the user + or application, but may be no higher than the hard limit. The latter + may be lowered by the user, but never raised. Second, most resource + limits apply per process to a specific user, not the user as a whole. + Note, however, that these differences are mandated by the specific + handling of the limits, not by the implementation of the login + capability framework (i.e., they are not <emphasis>really</emphasis> + a special case of login capabilities).</para> + + <para>And so, without further ado, below are the most commonly used + resource limits (the rest, along with all the other login + capabilities, may be found in &man.login.conf.5;).</para> + + <variablelist> + <varlistentry> + <term><literal>coredumpsize</literal></term> + + <listitem> + <indexterm><primary>coredumpsize</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>coredumpsize</secondary> + </indexterm> + <para>The limit on the size of a core file generated by a program + is, for obvious reasons, subordinate to other limits on disk + usage (e.g., <literal>filesize</literal>, or disk quotas). + Nevertheless, it is often used as a less-severe method of + controlling disk space consumption: since users do not generate + core files themselves, and often do not delete them, setting this + may save them from running out of disk space should a large + program (e.g., <application>emacs</application>) crash.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>cputime</literal></term> + + <listitem> + <indexterm><primary>cputime</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>cputime</secondary> + </indexterm> + <para>This is the maximum amount of CPU time a user's process may + consume. Offending processes will be killed by the kernel.</para> + + <note> + <para>This is a limit on CPU <emphasis>time</emphasis> + consumed, not percentage of the CPU as displayed in some + fields by &man.top.1; and &man.ps.1;. A limit on the + latter is, at the time of this writing, not possible, and + would be rather useless: a compiler—probably a + legitimate task—can easily use almost 100% of a CPU + for some time.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>filesize</literal></term> + + <listitem> + <indexterm><primary>filesize</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>filesize</secondary> + </indexterm> + <para>This is the maximum size of a file the user may possess. + Unlike <link linkend="quotas">disk quotas</link>, this limit is + enforced on individual files, not the set of all files a user + owns.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>maxproc</literal></term> + + <listitem> + <indexterm><primary>maxproc</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>maxproc</secondary> + </indexterm> + <para>This is the maximum number of processes a user may be + running. This includes foreground and background processes + alike. For obvious reasons, this may not be larger than the + system limit specified by the <varname>kern.maxproc</varname> + &man.sysctl.8;. Also note that setting this + too small may hinder a + user's productivity: it is often useful to be logged in + multiple times or execute pipelines. Some tasks, such as + compiling a large program, also spawn multiple processes (e.g., + &man.make.1;, &man.cc.1;, and other intermediate + preprocessors).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>memorylocked</literal></term> + + <listitem> + <indexterm><primary>memorylocked</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>memorylocked</secondary> + </indexterm> + <para>This is the maximum amount a memory a process may have + requested to be locked into main memory (e.g., see + &man.mlock.2;). Some system-critical programs, such as + &man.amd.8;, lock into main memory such that in the event + of being swapped out, they do not contribute to + a system's trashing in time of trouble.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>memoryuse</literal></term> + + <listitem> + <indexterm><primary>memoryuse</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>memoryuse</secondary> + </indexterm> + <para>This is the maximum amount of memory a process may consume + at any given time. It includes both core memory and swap + usage. This is not a catch-all limit for restricting memory + consumption, but it is a good start.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>openfiles</literal></term> + + <listitem> + <indexterm><primary>openfiles</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>openfiles</secondary> + </indexterm> + <para>This is the maximum amount of files a process may have + open. In FreeBSD, files are also used to represent sockets and + IPC channels; thus, be careful not to set this too low. The + system-wide limit for this is defined by the + <varname>kern.maxfiles</varname> &man.sysctl.8;.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>sbsize</literal></term> + + <listitem> + <indexterm><primary>sbsize</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>sbsize</secondary> + </indexterm> + <para>This is the limit on the amount of network memory, and thus + mbufs, a user may consume. This originated as a response to an + old DoS attack by creating a lot of sockets, but can be + generally used to limit network communications.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>stacksize</literal></term> + + <listitem> + <indexterm><primary>stacksize</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>stacksize</secondary> + </indexterm> + <para>This is the maximum size a process' stack may grow to. + This alone is not sufficient to limit the amount of memory a + program may use; consequently, it should be used in conjunction + with other limits.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>There are a few other things to remember when setting resource + limits. Following are some general tips, suggestions, and + miscellaneous comments.</para> + + <itemizedlist> + <listitem> + <para>Processes started at system startup by + <filename>/etc/rc</filename> are assigned to the + <literal>daemon</literal> login class.</para> + </listitem> + + <listitem> + <para>Although the <filename>/etc/login.conf</filename> that comes + with the system is a good source of reasonable values for most + limits, only you, the administrator, can know what is appropriate + for your system. Setting a limit too high may open your system + up to abuse, while setting it too low may put a strain on + productivity.</para> + </listitem> + + <listitem> + <para>Users of the X Window System (X11) should probably be granted + more resources than other users. X11 by itself takes a lot of + resources, but it also encourages users to run more programs + simultaneously.</para> + </listitem> + + <listitem> + <para>Remember that many limits apply to individual processes, not + the user as a whole. For example, setting + <varname>openfiles</varname> to 50 means + that each process the user runs may open up to 50 files. Thus, + the gross amount of files a user may open is the value of + <literal>openfiles</literal> multiplied by the value of + <literal>maxproc</literal>. This also applies to memory + consumption.</para> + </listitem> + </itemizedlist> + + <para>For further information on resource limits and login classes and + capabilities in general, please consult the relevant manual pages: + &man.cap.mkdb.1;, &man.getrlimit.2;, &man.login.conf.5;.</para> + </sect1> + + <sect1 id="users-groups"> + <title>Groups</title> + + <indexterm><primary>groups</primary></indexterm> + <indexterm> + <primary><filename>/etc/groups</filename></primary> + </indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>groups</secondary> + </indexterm> + <para>A group is simply a list of users. Groups are identified by + their group name and GID (Group ID). In FreeBSD (and most other &unix; like + systems), the two factors the kernel uses to decide whether a process + is allowed to do something is its user ID and list of groups it + belongs to. Unlike a user ID, a process has a list of groups + associated with it. You may hear some things refer to the <quote>group ID</quote> + of a user or process; most of the time, this just means the first + group in the list.</para> + + <para>The group name to group ID map is in + <filename>/etc/group</filename>. This is a plain text file with four + colon-delimited fields. The first field is the group name, the + second is the encrypted password, the third the group ID, and the + fourth the comma-delimited list of members. It can safely be edited + by hand (assuming, of course, that you do not make any syntax + errors!). For a more complete description of the syntax, see the + &man.group.5; manual page.</para> + + <para>If you do not want to edit <filename>/etc/group</filename> + manually, you can use the &man.pw.8; command to add and edit groups. + For example, to add a group called <groupname>teamtwo</groupname> and + then confirm that it exists you can use:</para> + + <example> + <title>Adding a Group Using &man.pw.8;</title> + + <screen>&prompt.root; <userinput>pw groupadd teamtwo</userinput> +&prompt.root; <userinput>pw groupshow teamtwo</userinput> +teamtwo:*:1100:</screen> + </example> + + <para>The number <literal>1100</literal> above is the group ID of the + group <groupname>teamtwo</groupname>. Right now, + <groupname>teamtwo</groupname> has no members, and is thus rather + useless. Let's change that by inviting <username>jru</username> to + the <groupname>teamtwo</groupname> group.</para> + + <example> + <title>Setting the List of Members of a Group Using &man.pw.8;</title> + + <screen>&prompt.root; <userinput>pw groupmod teamtwo -M jru</userinput> +&prompt.root; <userinput>pw groupshow teamtwo</userinput> +teamtwo:*:1100:jru</screen> + </example> + + <para>The argument to the <option>-M</option> option is a + comma-delimited list of users who are to be in the group. From the + preceding sections, we know that the password file also contains a + group for each user. The latter (the user) is automatically added to + the group list by the system; the user will not show up as a member + when using the <option>groupshow</option> command to &man.pw.8;, + but will show up when the information is queried via &man.id.1; or + similar tool. In other words, &man.pw.8; only manipulates the + <filename>/etc/group</filename> file; it will never attempt to read + additionally data from <filename>/etc/passwd</filename>.</para> + + <example> + <title>Adding a New Member to a Group Using &man.pw.8;</title> + + <screen>&prompt.root; <userinput>pw groupmod teamtwo -m db</userinput> +&prompt.root; <userinput>pw groupshow teamtwo</userinput> +teamtwo:*:1100:jru,db</screen> + </example> + + <para>The argument to the <option>-m</option> option is a + comma-delimited list of users who are to be added to the group. Unlike + the previous example, these users are added to the group and do not + replace the list of users in the group.</para> + + <example> + <title>Using &man.id.1; to Determine Group Membership</title> + + <screen>&prompt.user; <userinput>id jru</userinput> +uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)</screen> + </example> + + <para>As you can see, <username>jru</username> is a member of the + groups <groupname>jru</groupname> and + <groupname>teamtwo</groupname>.</para> + + <para>For more information about &man.pw.8;, see its manual page, and + for more information on the format of + <filename>/etc/group</filename>, consult the &man.group.5; manual + page.</para> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/vinum/Makefile b/en_US.ISO8859-1/books/handbook/vinum/Makefile new file mode 100644 index 0000000000..eca585a9aa --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/vinum/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= vinum/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml b/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml new file mode 100644 index 0000000000..510f32359d --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/vinum/chapter.sgml @@ -0,0 +1,1306 @@ +<!-- + The Vinum Volume Manager + By Greg Lehey (grog at lemis dot com) + + Added to the Handbook by Hiten Pandya <hmp@FreeBSD.org> + and Tom Rhodes <trhodes@FreeBSD.org> + + For the FreeBSD Documentation Project + $FreeBSD$ +--> + +<chapter id="vinum-vinum"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Greg</firstname> + <surname>Lehey</surname> + <contrib>Originally written by </contrib> + </author> + </authorgroup> + </chapterinfo> + + <title>The Vinum Volume Manager</title> + + <sect1 id="vinum-synopsis"> + <title>Synopsis</title> + + <para>No matter what disks you have, there are always potential + problems:</para> + + <itemizedlist> + <listitem> + <para>They can be too small.</para> + </listitem> + + <listitem> + <para>They can be too slow.</para> + </listitem> + + <listitem> + <para>They can be too unreliable.</para> + </listitem> + </itemizedlist> + + <para>Various solutions to these problems have been proposed and + implemented. One way some users safeguard themselves against such + issues is through the use of multiple, and sometimes redundant, + disks. In addition to supporting various cards and controllers + for hardware RAID systems, the base &os; system includes the + Vinum Volume Manager, a block device driver that implements + virtual disk drives. <emphasis>Vinum</emphasis> is a + so-called <emphasis>Volume Manager</emphasis>, a virtual disk + driver that addresses these three problems. Vinum provides more + flexibility, performance, and reliability than traditional disk + storage, and implements RAID-0, RAID-1, and RAID-5 models both + individually and in combination.</para> + + <para>This chapter provides an overview of potential problems with + traditional disk storage, and an introduction to the Vinum Volume + Manager.</para> + + <note> + <para>Starting with &os; 5, Vinum has been rewritten in order + to fit into the GEOM architecture (<xref linkend="GEOM">), + retaining the original ideas, terminology, and on-disk + metadata. This rewrite is called <emphasis>gvinum</emphasis> + (for <emphasis> GEOM vinum</emphasis>). The following text + usually refers to <emphasis>Vinum</emphasis> as an abstract + name, regardless of the implementation variant. Any command + invocations should now be done using + the <command>gvinum</command> command, and the name of the + kernel module has been changed + from <filename>vinum.ko</filename> + to <filename>geom_vinum.ko</filename>, and all device nodes + reside under <filename class="directory">/dev/gvinum</filename> instead + of <filename class="directory">/dev/vinum</filename>. As of &os; 6, the old + Vinum implementation is no longer available in the code + base.</para> + </note> + + </sect1> + + <sect1 id="vinum-intro"> + <title>Disks Are Too Small</title> + + <indexterm><primary>Vinum</primary></indexterm> + <indexterm><primary>RAID</primary> + <secondary>software</secondary></indexterm> + + <para>Disks are getting bigger, but so are data storage + requirements. Often you will find you want a file system that + is bigger than the disks you have available. Admittedly, this + problem is not as acute as it was ten years ago, but it still + exists. Some systems have solved this by creating an abstract + device which stores its data on a number of disks.</para> + </sect1> + + <sect1 id="vinum-access-bottlenecks"> + <title>Access Bottlenecks</title> + + <para>Modern systems frequently need to access data in a highly + concurrent manner. For example, large FTP or HTTP servers can + maintain thousands of concurrent sessions and have multiple + 100 Mbit/s connections to the outside world, well beyond + the sustained transfer rate of most disks.</para> + + <para>Current disk drives can transfer data sequentially at up to + 70 MB/s, but this value is of little importance in an + environment where many independent processes access a drive, + where they may achieve only a fraction of these values. In such + cases it is more interesting to view the problem from the + viewpoint of the disk subsystem: the important parameter is the + load that a transfer places on the subsystem, in other words the + time for which a transfer occupies the drives involved in the + transfer.</para> + + <para>In any disk transfer, the drive must first position the + heads, wait for the first sector to pass under the read head, + and then perform the transfer. These actions can be considered + to be atomic: it does not make any sense to interrupt + them.</para> + + <para><anchor id="vinum-latency"> Consider a typical transfer of + about 10 kB: the current generation of high-performance + disks can position the heads in an average of 3.5 ms. The + fastest drives spin at 15,000 rpm, so the average + rotational latency (half a revolution) is 2 ms. At + 70 MB/s, the transfer itself takes about 150 μs, + almost nothing compared to the positioning time. In such a + case, the effective transfer rate drops to a little over + 1 MB/s and is clearly highly dependent on the transfer + size.</para> + + <para>The traditional and obvious solution to this bottleneck is + <quote>more spindles</quote>: rather than using one large disk, + it uses several smaller disks with the same aggregate storage + space. Each disk is capable of positioning and transferring + independently, so the effective throughput increases by a factor + close to the number of disks used. + </para> + + <para>The exact throughput improvement is, of course, smaller than + the number of disks involved: although each drive is capable of + transferring in parallel, there is no way to ensure that the + requests are evenly distributed across the drives. Inevitably + the load on one drive will be higher than on another.</para> + + <indexterm> + <primary>disk concatenation</primary> + </indexterm> + <indexterm> + <primary>Vinum</primary> + <secondary>concatenation</secondary> + </indexterm> + + <para>The evenness of the load on the disks is strongly dependent + on the way the data is shared across the drives. In the + following discussion, it is convenient to think of the disk + storage as a large number of data sectors which are addressable + by number, rather like the pages in a book. The most obvious + method is to divide the virtual disk into groups of consecutive + sectors the size of the individual physical disks and store them + in this manner, rather like taking a large book and tearing it + into smaller sections. This method is called + <emphasis>concatenation</emphasis> and has the advantage that + the disks are not required to have any specific size + relationships. It works well when the access to the virtual + disk is spread evenly about its address space. When access is + concentrated on a smaller area, the improvement is less marked. + <xref linkend="vinum-concat"> illustrates the sequence in which + storage units are allocated in a concatenated + organization.</para> + + <para> + <figure id="vinum-concat"> + <title>Concatenated Organization</title> + <graphic fileref="vinum/vinum-concat"> + </figure> + </para> + + <indexterm> + <primary>disk striping</primary> + </indexterm> + <indexterm> + <primary>Vinum</primary> + <secondary>striping</secondary> + </indexterm> + <indexterm> + <primary>RAID</primary> + </indexterm> + + <para>An alternative mapping is to divide the address space into + smaller, equal-sized components and store them sequentially on + different devices. For example, the first 256 sectors may be + stored on the first disk, the next 256 sectors on the next disk + and so on. After filling the last disk, the process repeats + until the disks are full. This mapping is called + <emphasis>striping</emphasis> or <acronym>RAID-0</acronym> + + <footnote> + <para><acronym>RAID</acronym> stands for <emphasis>Redundant + Array of Inexpensive Disks</emphasis> and offers various forms + of fault tolerance, though the latter term is somewhat + misleading: it provides no redundancy.</para> </footnote>. + + Striping requires somewhat more effort to locate the data, and it + can cause additional I/O load where a transfer is spread over + multiple disks, but it can also provide a more constant load + across the disks. <xref linkend="vinum-striped"> illustrates the + sequence in which storage units are allocated in a striped + organization.</para> + + <para> + <figure id="vinum-striped"> + <title>Striped Organization</title> + <graphic fileref="vinum/vinum-striped"> + </figure> + </para> + </sect1> + + <sect1 id="vinum-data-integrity"> + <title>Data Integrity</title> + + <para>The final problem with current disks is that they are + unreliable. Although disk drive reliability has increased + tremendously over the last few years, they are still the most + likely core component of a server to fail. When they do, the + results can be catastrophic: replacing a failed disk drive and + restoring data to it can take days.</para> + + <indexterm> + <primary>disk mirroring</primary> + </indexterm> + <indexterm> + <primary>Vinum</primary> + <secondary>mirroring</secondary> + </indexterm> + <indexterm> + <primary>RAID-1</primary> + </indexterm> + + <para>The traditional way to approach this problem has been + <emphasis>mirroring</emphasis>, keeping two copies of the data + on different physical hardware. Since the advent of the + <acronym>RAID</acronym> levels, this technique has also been + called <acronym>RAID level 1</acronym> or + <acronym>RAID-1</acronym>. Any write to the volume writes to + both locations; a read can be satisfied from either, so if one + drive fails, the data is still available on the other + drive.</para> + + <para>Mirroring has two problems:</para> + + <itemizedlist> + <listitem> + <para>The price. It requires twice as much disk storage as + a non-redundant solution.</para> + </listitem> + + <listitem> + <para>The performance impact. Writes must be performed to + both drives, so they take up twice the bandwidth of a + non-mirrored volume. Reads do not suffer from a + performance penalty: it even looks as if they are + faster.</para> + </listitem> + </itemizedlist> + + <para><indexterm><primary>RAID-5</primary></indexterm>An + alternative solution is <emphasis>parity</emphasis>, + implemented in the <acronym>RAID</acronym> levels 2, 3, 4 and + 5. Of these, <acronym>RAID-5</acronym> is the most + interesting. As implemented in Vinum, it is a variant on a + striped organization which dedicates one block of each stripe + to parity one of the other blocks. As implemented by Vinum, a + <acronym>RAID-5</acronym> plex is similar to a striped plex, + except that it implements <acronym>RAID-5</acronym> by + including a parity block in each stripe. As required by + <acronym>RAID-5</acronym>, the location of this parity block + changes from one stripe to the next. The numbers in the data + blocks indicate the relative block numbers.</para> + + <para> + <figure id="vinum-raid5-org"> + <title>RAID-5 Organization</title> + <graphic fileref="vinum/vinum-raid5-org"> + </figure> + </para> + + <para>Compared to mirroring, <acronym>RAID-5</acronym> has the + advantage of requiring significantly less storage space. Read + access is similar to that of striped organizations, but write + access is significantly slower, approximately 25% of the read + performance. If one drive fails, the array can continue to + operate in degraded mode: a read from one of the remaining + accessible drives continues normally, but a read from the + failed drive is recalculated from the corresponding block from + all the remaining drives. + </para> + </sect1> + + <sect1 id="vinum-objects"> + <title>Vinum Objects</title> + <para>In order to address these problems, Vinum implements a four-level + hierarchy of objects:</para> + + <itemizedlist> + <listitem> + <para>The most visible object is the virtual disk, called a + <emphasis>volume</emphasis>. Volumes have essentially the same + properties as a &unix; disk drive, though there are some minor + differences. They have no size limitations.</para> + </listitem> + + <listitem> + <para>Volumes are composed of <emphasis>plexes</emphasis>, + each of which represent the total address space of a + volume. This level in the hierarchy thus provides + redundancy. Think of plexes as individual disks in a + mirrored array, each containing the same data.</para> + </listitem> + + <listitem> + <para>Since Vinum exists within the &unix; disk storage + framework, it would be possible to use &unix; + partitions as the building block for multi-disk plexes, + but in fact this turns out to be too inflexible: + &unix; disks can have only a limited number of + partitions. Instead, Vinum subdivides a single + &unix; partition (the <emphasis>drive</emphasis>) + into contiguous areas called + <emphasis>subdisks</emphasis>, which it uses as building + blocks for plexes.</para> + </listitem> + + <listitem> + <para>Subdisks reside on Vinum <emphasis>drives</emphasis>, + currently &unix; partitions. Vinum drives can + contain any number of subdisks. With the exception of a + small area at the beginning of the drive, which is used + for storing configuration and state information, the + entire drive is available for data storage.</para> + </listitem> + </itemizedlist> + + <para>The following sections describe the way these objects provide the + functionality required of Vinum.</para> + + <sect2> + <title>Volume Size Considerations</title> + + <para>Plexes can include multiple subdisks spread over all + drives in the Vinum configuration. As a result, the size of + an individual drive does not limit the size of a plex, and + thus of a volume.</para> + </sect2> + + <sect2> + <title>Redundant Data Storage</title> + <para>Vinum implements mirroring by attaching multiple plexes to + a volume. Each plex is a representation of the data in a + volume. A volume may contain between one and eight + plexes.</para> + + <para>Although a plex represents the complete data of a volume, + it is possible for parts of the representation to be + physically missing, either by design (by not defining a + subdisk for parts of the plex) or by accident (as a result of + the failure of a drive). As long as at least one plex can + provide the data for the complete address range of the volume, + the volume is fully functional.</para> + </sect2> + + <sect2> + <title>Performance Issues</title> + + <para>Vinum implements both concatenation and striping at the + plex level:</para> + + <itemizedlist> + <listitem> + <para>A <emphasis>concatenated plex</emphasis> uses the + address space of each subdisk in turn.</para> + </listitem> + + <listitem> + <para>A <emphasis>striped plex</emphasis> stripes the data + across each subdisk. The subdisks must all have the same + size, and there must be at least two subdisks in order to + distinguish it from a concatenated plex.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Which Plex Organization?</title> + <para>The version of Vinum supplied with &os; &rel.current; implements + two kinds of plex:</para> + + <itemizedlist> + <listitem> + <para>Concatenated plexes are the most flexible: they can + contain any number of subdisks, and the subdisks may be of + different length. The plex may be extended by adding + additional subdisks. They require less + <acronym>CPU</acronym> time than striped plexes, though + the difference in <acronym>CPU</acronym> overhead is not + measurable. On the other hand, they are most susceptible + to hot spots, where one disk is very active and others are + idle.</para> + </listitem> + + <listitem> + <para>The greatest advantage of striped + (<acronym>RAID-0</acronym>) plexes is that they reduce hot + spots: by choosing an optimum sized stripe (about + 256 kB), you can even out the load on the component + drives. The disadvantages of this approach are + (fractionally) more complex code and restrictions on + subdisks: they must be all the same size, and extending a + plex by adding new subdisks is so complicated that Vinum + currently does not implement it. Vinum imposes an + additional, trivial restriction: a striped plex must have + at least two subdisks, since otherwise it is + indistinguishable from a concatenated plex.</para> + </listitem> + </itemizedlist> + + <para><xref linkend="vinum-comparison"> summarizes the advantages + and disadvantages of each plex organization.</para> + + <table id="vinum-comparison" frame="none"> + <title>Vinum Plex Organizations</title> + <tgroup cols="5"> + <thead> + <row> + <entry>Plex type</entry> + <entry>Minimum subdisks</entry> + <entry>Can add subdisks</entry> + <entry>Must be equal size</entry> + <entry>Application</entry> + </row> + </thead> + + <tbody> + <row> + <entry>concatenated</entry> + <entry>1</entry> + <entry>yes</entry> + <entry>no</entry> + <entry>Large data storage with maximum placement flexibility + and moderate performance</entry> + </row> + + <row> + <entry>striped</entry> + <entry>2</entry> + <entry>no</entry> + <entry>yes</entry> + <entry>High performance in combination with highly concurrent + access</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + </sect1> + + <sect1 id="vinum-examples"> + <title>Some Examples</title> + + <para>Vinum maintains a <emphasis>configuration + database</emphasis> which describes the objects known to an + individual system. Initially, the user creates the + configuration database from one or more configuration files with + the aid of the &man.gvinum.8; utility program. Vinum stores a + copy of its configuration database on each disk slice (which + Vinum calls a <emphasis>device</emphasis>) under its control. + This database is updated on each state change, so that a restart + accurately restores the state of each Vinum object.</para> + + <sect2> + <title>The Configuration File</title> + <para>The configuration file describes individual Vinum objects. The + definition of a simple volume might be:</para> + + <programlisting> + drive a device /dev/da3h + volume myvol + plex org concat + sd length 512m drive a</programlisting> + + <para>This file describes four Vinum objects:</para> + + <itemizedlist> + <listitem> + <para>The <emphasis>drive</emphasis> line describes a disk + partition (<emphasis>drive</emphasis>) and its location + relative to the underlying hardware. It is given the + symbolic name <emphasis>a</emphasis>. This separation of + the symbolic names from the device names allows disks to + be moved from one location to another without + confusion.</para> + </listitem> + + <listitem> + <para>The <emphasis>volume</emphasis> line describes a volume. + The only required attribute is the name, in this case + <emphasis>myvol</emphasis>.</para> + </listitem> + + <listitem> + <para>The <emphasis>plex</emphasis> line defines a plex. + The only required parameter is the organization, in this + case <emphasis>concat</emphasis>. No name is necessary: + the system automatically generates a name from the volume + name by adding the suffix + <emphasis>.p</emphasis><emphasis>x</emphasis>, where + <emphasis>x</emphasis> is the number of the plex in the + volume. Thus this plex will be called + <emphasis>myvol.p0</emphasis>.</para> + </listitem> + + <listitem> + <para>The <emphasis>sd</emphasis> line describes a subdisk. + The minimum specifications are the name of a drive on + which to store it, and the length of the subdisk. As with + plexes, no name is necessary: the system automatically + assigns names derived from the plex name by adding the + suffix <emphasis>.s</emphasis><emphasis>x</emphasis>, + where <emphasis>x</emphasis> is the number of the subdisk + in the plex. Thus Vinum gives this subdisk the name + <emphasis>myvol.p0.s0</emphasis>.</para> + </listitem> + </itemizedlist> + + <para>After processing this file, &man.gvinum.8; produces the following + output:</para> + + <programlisting width="97"> + &prompt.root; gvinum -> <userinput>create config1</userinput> + Configuration summary + Drives: 1 (4 configured) + Volumes: 1 (4 configured) + Plexes: 1 (8 configured) + Subdisks: 1 (16 configured) + + D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%) + + V myvol State: up Plexes: 1 Size: 512 MB + + P myvol.p0 C State: up Subdisks: 1 Size: 512 MB + + S myvol.p0.s0 State: up PO: 0 B Size: 512 MB</programlisting> + + <para>This output shows the brief listing format of &man.gvinum.8;. It + is represented graphically in <xref linkend="vinum-simple-vol">.</para> + + <para> + <figure id="vinum-simple-vol"> + <title>A Simple Vinum Volume</title> + <graphic fileref="vinum/vinum-simple-vol"> + </figure> + </para> + + <para>This figure, and the ones which follow, represent a + volume, which contains the plexes, which in turn contain the + subdisks. In this trivial example, the volume contains one + plex, and the plex contains one subdisk.</para> + + <para>This particular volume has no specific advantage over a + conventional disk partition. It contains a single plex, so it + is not redundant. The plex contains a single subdisk, so + there is no difference in storage allocation from a + conventional disk partition. The following sections + illustrate various more interesting configuration + methods.</para> + </sect2> + + <sect2> + <title>Increased Resilience: Mirroring</title> + + <para>The resilience of a volume can be increased by mirroring. + When laying out a mirrored volume, it is important to ensure + that the subdisks of each plex are on different drives, so + that a drive failure will not take down both plexes. The + following configuration mirrors a volume:</para> + + <programlisting> + drive b device /dev/da4h + volume mirror + plex org concat + sd length 512m drive a + plex org concat + sd length 512m drive b</programlisting> + + <para>In this example, it was not necessary to specify a + definition of drive <emphasis>a</emphasis> again, since Vinum + keeps track of all objects in its configuration database. + After processing this definition, the configuration looks + like:</para> + + + <programlisting width="97"> + Drives: 2 (4 configured) + Volumes: 2 (4 configured) + Plexes: 3 (8 configured) + Subdisks: 3 (16 configured) + + D a State: up Device /dev/da3h Avail: 1549/2573 MB (60%) + D b State: up Device /dev/da4h Avail: 2061/2573 MB (80%) + + V myvol State: up Plexes: 1 Size: 512 MB + V mirror State: up Plexes: 2 Size: 512 MB + + P myvol.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB + + S myvol.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB</programlisting> + + <para><xref linkend="vinum-mirrored-vol"> shows the structure + graphically.</para> + + <para> + <figure id="vinum-mirrored-vol"> + <title>A Mirrored Vinum Volume</title> + <graphic fileref="vinum/vinum-mirrored-vol"> + </figure> + </para> + + <para>In this example, each plex contains the full 512 MB + of address space. As in the previous example, each plex + contains only a single subdisk.</para> + </sect2> + + <sect2> + <title>Optimizing Performance</title> + + <para>The mirrored volume in the previous example is more + resistant to failure than an unmirrored volume, but its + performance is less: each write to the volume requires a write + to both drives, using up a greater proportion of the total + disk bandwidth. Performance considerations demand a different + approach: instead of mirroring, the data is striped across as + many disk drives as possible. The following configuration + shows a volume with a plex striped across four disk + drives:</para> + + <programlisting> + drive c device /dev/da5h + drive d device /dev/da6h + volume stripe + plex org striped 512k + sd length 128m drive a + sd length 128m drive b + sd length 128m drive c + sd length 128m drive d</programlisting> + + <para>As before, it is not necessary to define the drives which are + already known to Vinum. After processing this definition, the + configuration looks like:</para> + + <programlisting width="92"> + Drives: 4 (4 configured) + Volumes: 3 (4 configured) + Plexes: 4 (8 configured) + Subdisks: 7 (16 configured) + + D a State: up Device /dev/da3h Avail: 1421/2573 MB (55%) + D b State: up Device /dev/da4h Avail: 1933/2573 MB (75%) + D c State: up Device /dev/da5h Avail: 2445/2573 MB (95%) + D d State: up Device /dev/da6h Avail: 2445/2573 MB (95%) + + V myvol State: up Plexes: 1 Size: 512 MB + V mirror State: up Plexes: 2 Size: 512 MB + V striped State: up Plexes: 1 Size: 512 MB + + P myvol.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB + P striped.p1 State: up Subdisks: 1 Size: 512 MB + + S myvol.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB + S striped.p0.s0 State: up PO: 0 B Size: 128 MB + S striped.p0.s1 State: up PO: 512 kB Size: 128 MB + S striped.p0.s2 State: up PO: 1024 kB Size: 128 MB + S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB</programlisting> + + <para> + <figure id="vinum-striped-vol"> + <title>A Striped Vinum Volume</title> + <graphic fileref="vinum/vinum-striped-vol"> + </figure> + </para> + + <para>This volume is represented in + <xref linkend="vinum-striped-vol">. The darkness of the stripes + indicates the position within the plex address space: the lightest stripes + come first, the darkest last.</para> + </sect2> + + <sect2> + <title>Resilience and Performance</title> + + <para><anchor id="vinum-resilience">With sufficient hardware, it + is possible to build volumes which show both increased + resilience and increased performance compared to standard + &unix; partitions. A typical configuration file might + be:</para> + + <programlisting> + volume raid10 + plex org striped 512k + sd length 102480k drive a + sd length 102480k drive b + sd length 102480k drive c + sd length 102480k drive d + sd length 102480k drive e + plex org striped 512k + sd length 102480k drive c + sd length 102480k drive d + sd length 102480k drive e + sd length 102480k drive a + sd length 102480k drive b</programlisting> + + <para>The subdisks of the second plex are offset by two drives from those + of the first plex: this helps ensure that writes do not go to the same + subdisks even if a transfer goes over two drives.</para> + + <para><xref linkend="vinum-raid10-vol"> represents the structure + of this volume.</para> + + <para> + <figure id="vinum-raid10-vol"> + <title>A Mirrored, Striped Vinum Volume</title> + <graphic fileref="vinum/vinum-raid10-vol"> + </figure> + </para> + </sect2> + </sect1> + + <sect1 id="vinum-object-naming"> + <title>Object Naming</title> + + <para>As described above, Vinum assigns default names to plexes + and subdisks, although they may be overridden. Overriding the + default names is not recommended: experience with the VERITAS + volume manager, which allows arbitrary naming of objects, has + shown that this flexibility does not bring a significant + advantage, and it can cause confusion.</para> + + <para>Names may contain any non-blank character, but it is + recommended to restrict them to letters, digits and the + underscore characters. The names of volumes, plexes and + subdisks may be up to 64 characters long, and the names of + drives may be up to 32 characters long.</para> + + <para>Vinum objects are assigned device nodes in the hierarchy + <filename class="directory">/dev/gvinum</filename>. The configuration shown above + would cause Vinum to create the following device nodes:</para> + + <itemizedlist> + <listitem> + <para>Device entries for each volume. + These are the main devices used by Vinum. Thus the configuration + above would include the devices + <filename class="devicefile">/dev/gvinum/myvol</filename>, + <filename class="devicefile">/dev/gvinum/mirror</filename>, + <filename class="devicefile">/dev/gvinum/striped</filename>, + <filename class="devicefile">/dev/gvinum/raid5</filename> and + <filename class="devicefile">/dev/gvinum/raid10</filename>.</para> + </listitem> + + <listitem> + <para>All volumes get direct entries under + <filename class="directory">/dev/gvinum/</filename>.</para> + </listitem> + + <listitem> + <para>The directories + <filename class="directory">/dev/gvinum/plex</filename>, and + <filename class="directory">/dev/gvinum/sd</filename>, which contain + device nodes for each plex and for each subdisk, + respectively.</para> + </listitem> + </itemizedlist> + + <para>For example, consider the following configuration file:</para> + <programlisting> + drive drive1 device /dev/sd1h + drive drive2 device /dev/sd2h + drive drive3 device /dev/sd3h + drive drive4 device /dev/sd4h + volume s64 setupstate + plex org striped 64k + sd length 100m drive drive1 + sd length 100m drive drive2 + sd length 100m drive drive3 + sd length 100m drive drive4</programlisting> + + <para>After processing this file, &man.gvinum.8; creates the following + structure in <filename class="directory">/dev/gvinum</filename>:</para> + + <programlisting> + drwxr-xr-x 2 root wheel 512 Apr 13 16:46 plex + crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64 + drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd + + /dev/vinum/plex: + total 0 + crwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0 + + /dev/vinum/sd: + total 0 + crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0 + crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1 + crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2 + crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3</programlisting> + + <para>Although it is recommended that plexes and subdisks should + not be allocated specific names, Vinum drives must be named. + This makes it possible to move a drive to a different location + and still recognize it automatically. Drive names may be up to + 32 characters long.</para> + + <sect2> + <title>Creating File Systems</title> + + <para>Volumes appear to the system to be identical to disks, + with one exception. Unlike &unix; drives, Vinum does + not partition volumes, which thus do not contain a partition + table. This has required modification to some disk + utilities, notably &man.newfs.8;, which previously tried to + interpret the last letter of a Vinum volume name as a + partition identifier. For example, a disk drive may have a + name like <filename class="devicefile">/dev/ad0a</filename> or + <filename class="devicefile">/dev/da2h</filename>. These names represent + the first partition (<devicename>a</devicename>) on the + first (0) IDE disk (<devicename>ad</devicename>) and the + eighth partition (<devicename>h</devicename>) on the third + (2) SCSI disk (<devicename>da</devicename>) respectively. + By contrast, a Vinum volume might be called + <filename class="devicefile">/dev/gvinum/concat</filename>, a name which has + no relationship with a partition name.</para> + + <para>In order to create a file system on this volume, use + &man.newfs.8;:</para> + + <screen>&prompt.root; <userinput>newfs /dev/gvinum/concat</userinput></screen> + </sect2> + </sect1> + + <sect1 id="vinum-config"> + <title>Configuring Vinum</title> + + <para>The <filename>GENERIC</filename> kernel does not contain + Vinum. It is possible to build a special kernel which includes + Vinum, but this is not recommended. The standard way to start + Vinum is as a kernel module (<acronym>kld</acronym>). You do + not even need to use &man.kldload.8; for Vinum: when you start + &man.gvinum.8;, it checks whether the module has been loaded, and + if it is not, it loads it automatically.</para> + + + <sect2> + <title>Startup</title> + + <para>Vinum stores configuration information on the disk slices + in essentially the same form as in the configuration files. + When reading from the configuration database, Vinum recognizes + a number of keywords which are not allowed in the + configuration files. For example, a disk configuration might + contain the following text:</para> + + <programlisting width="119">volume myvol state up +volume bigraid state down +plex name myvol.p0 state up org concat vol myvol +plex name myvol.p1 state up org concat vol myvol +plex name myvol.p2 state init org striped 512b vol myvol +plex name bigraid.p0 state initializing org raid5 512b vol bigraid +sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b +sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b +sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b +sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b +sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b +sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b +sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b +sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b +sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b +sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b +sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b +sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b +sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b</programlisting> + + <para>The obvious differences here are the presence of + explicit location information and naming (both of which are + also allowed, but discouraged, for use by the user) and the + information on the states (which are not available to the + user). Vinum does not store information about drives in the + configuration information: it finds the drives by scanning + the configured disk drives for partitions with a Vinum + label. This enables Vinum to identify drives correctly even + if they have been assigned different &unix; drive + IDs.</para> + + <sect3 id="vinum-rc-startup"> + <title>Automatic Startup</title> + + <para> + <emphasis>Gvinum</emphasis> always + features an automatic startup once the kernel module is + loaded, via &man.loader.conf.5;. To load the + <emphasis>Gvinum</emphasis> module at boot time, add + <literal>geom_vinum_load="YES"</literal> to + <filename>/boot/loader.conf</filename>.</para> + + <para>When you start Vinum with the <command>gvinum + start</command> command, Vinum reads the configuration + database from one of the Vinum drives. Under normal + circumstances, each drive contains an identical copy of the + configuration database, so it does not matter which drive is + read. After a crash, however, Vinum must determine which + drive was updated most recently and read the configuration + from this drive. It then updates the configuration if + necessary from progressively older drives.</para> + + </sect3> + </sect2> + </sect1> + + <sect1 id="vinum-root"> + <title>Using Vinum for the Root Filesystem</title> + + <para>For a machine that has fully-mirrored filesystems using + Vinum, it is desirable to also mirror the root filesystem. + Setting up such a configuration is less trivial than mirroring + an arbitrary filesystem because:</para> + + <itemizedlist> + <listitem> + <para>The root filesystem must be available very early during + the boot process, so the Vinum infrastructure must already be + available at this time.</para> + </listitem> + <listitem> + <para>The volume containing the root filesystem also contains + the system bootstrap and the kernel, which must be read + using the host system's native utilities (e. g. the BIOS on + PC-class machines) which often cannot be taught about the + details of Vinum.</para> + </listitem> + </itemizedlist> + + <para>In the following sections, the term <quote>root + volume</quote> is generally used to describe the Vinum volume + that contains the root filesystem. It is probably a good idea + to use the name <literal>"root"</literal> for this volume, but + this is not technically required in any way. All command + examples in the following sections assume this name though.</para> + + <sect2> + <title>Starting up Vinum Early Enough for the Root + Filesystem</title> + + <para>There are several measures to take for this to + happen:</para> + + <itemizedlist> + <listitem> + <para>Vinum must be available in the kernel at boot-time. + Thus, the method to start Vinum automatically described in + <xref linkend="vinum-rc-startup"> is not applicable to + accomplish this task, and the + <literal>start_vinum</literal> parameter must actually + <emphasis>not</emphasis> be set when the following setup + is being arranged. The first option would be to compile + Vinum statically into the kernel, so it is available all + the time, but this is usually not desirable. There is + another option as well, to have + <filename>/boot/loader</filename> (<xref + linkend="boot-loader">) load the vinum kernel module + early, before starting the kernel. This can be + accomplished by putting the line:</para> + + <programlisting>geom_vinum_load="YES"</programlisting> + + <para>into the file + <filename>/boot/loader.conf</filename>.</para> + </listitem> + + <listitem> + <para>For <emphasis>Gvinum</emphasis>, all startup + is done automatically once the kernel module has been + loaded, so the procedure described above is all that is + needed.</para> + </listitem> + </itemizedlist> + </sect2> + + <sect2> + <title>Making a Vinum-based Root Volume Accessible to the + Bootstrap</title> + + <para>Since the current &os; bootstrap is only 7.5 KB of + code, and already has the burden of reading files (like + <filename>/boot/loader</filename>) from the UFS filesystem, it + is sheer impossible to also teach it about internal Vinum + structures so it could parse the Vinum configuration data, and + figure out about the elements of a boot volume itself. Thus, + some tricks are necessary to provide the bootstrap code with + the illusion of a standard <literal>"a"</literal> partition + that contains the root filesystem.</para> + + <para>For this to be possible at all, the following requirements + must be met for the root volume:</para> + + <itemizedlist> + <listitem> + <para>The root volume must not be striped or RAID-5.</para> + </listitem> + + <listitem> + <para>The root volume must not contain more than one + concatenated subdisk per plex.</para> + </listitem> + </itemizedlist> + + <para>Note that it is desirable and possible that there are + multiple plexes, each containing one replica of the root + filesystem. The bootstrap process will, however, only use one + of these replica for finding the bootstrap and all the files, + until the kernel will eventually mount the root filesystem + itself. Each single subdisk within these plexes will then + need its own <literal>"a"</literal> partition illusion, for + the respective device to become bootable. It is not strictly + needed that each of these faked <literal>"a"</literal> + partitions is located at the same offset within its device, + compared with other devices containing plexes of the root + volume. However, it is probably a good idea to create the + Vinum volumes that way so the resulting mirrored devices are + symmetric, to avoid confusion.</para> + + <para>In order to set up these <literal>"a"</literal> partitions, + for each device containing part of the root volume, the + following needs to be done:</para> + + <procedure> + <step> + <para>The location (offset from the beginning of the device) + and size of this device's subdisk that is part of the root + volume need to be examined, using the command:</para> + + <screen>&prompt.root; <userinput>gvinum l -rv root</userinput></screen> + + <para>Note that Vinum offsets and sizes are measured in + bytes. They must be divided by 512 in order to obtain the + block numbers that are to be used in the + <command>bsdlabel</command> command.</para> + </step> + + <step> + <para>Run the command:</para> + + <screen>&prompt.root; <userinput>bsdlabel -e <replaceable>devname</replaceable></userinput></screen> + + <para>for each device that participates in the root volume. + <replaceable>devname</replaceable> must be either the name + of the disk (like <devicename>da0</devicename>) for disks + without a slice (aka. fdisk) table, or the name of the + slice (like <devicename>ad0s1</devicename>).</para> + + <para>If there is already an <literal>"a"</literal> + partition on the device (presumably, containing a + pre-Vinum root filesystem), it should be renamed to + something else, so it remains accessible (just in case), + but will no longer be used by default to bootstrap the + system. Note that active partitions (like a root + filesystem currently mounted) cannot be renamed, so this + must be executed either when being booted from a + <quote>Fixit</quote> medium, or in a two-step process, + where (in a mirrored situation) the disk that has not been + currently booted is being manipulated first.</para> + + <para>Then, the offset of the Vinum partition on this + device (if any) must be added to the offset of the + respective root volume subdisk on this device. The + resulting value will become the + <literal>"offset"</literal> value for the new + <literal>"a"</literal> partition. The + <literal>"size"</literal> value for this partition can be + taken verbatim from the calculation above. The + <literal>"fstype"</literal> should be + <literal>4.2BSD</literal>. The + <literal>"fsize"</literal>, <literal>"bsize"</literal>, + and <literal>"cpg"</literal> values should best be chosen + to match the actual filesystem, though they are fairly + unimportant within this context.</para> + + <para>That way, a new <literal>"a"</literal> partition will + be established that overlaps the Vinum partition on this + device. Note that the <command>bsdlabel</command> will + only allow for this overlap if the Vinum partition has + properly been marked using the <literal>"vinum"</literal> + fstype.</para> + </step> + + <step> + <para>That's all! A faked <literal>"a"</literal> partition + does exist now on each device that has one replica of the + root volume. It is highly recommendable to verify the + result again, using a command like:</para> + + <screen>&prompt.root; <userinput>fsck -n /dev/<replaceable>devname</replaceable>a</userinput></screen> + </step> + </procedure> + + <para>It should be remembered that all files containing control + information must be relative to the root filesystem in the + Vinum volume which, when setting up a new Vinum root volume, + might not match the root filesystem that is currently active. + So in particular, the files <filename>/etc/fstab</filename> + and <filename>/boot/loader.conf</filename> need to be taken + care of.</para> + + <para>At next reboot, the bootstrap should figure out the + appropriate control information from the new Vinum-based root + filesystem, and act accordingly. At the end of the kernel + initialization process, after all devices have been announced, + the prominent notice that shows the success of this setup is a + message like:</para> + + <screen>Mounting root from ufs:/dev/gvinum/root</screen> + </sect2> + + <sect2> + <title>Example of a Vinum-based Root Setup</title> + + <para>After the Vinum root volume has been set up, the output of + <command>gvinum l -rv root</command> could look like:</para> + + <screen> +... +Subdisk root.p0.s0: + Size: 125829120 bytes (120 MB) + State: up + Plex root.p0 at offset 0 (0 B) + Drive disk0 (/dev/da0h) at offset 135680 (132 kB) + +Subdisk root.p1.s0: + Size: 125829120 bytes (120 MB) + State: up + Plex root.p1 at offset 0 (0 B) + Drive disk1 (/dev/da1h) at offset 135680 (132 kB) + </screen> + + <para>The values to note are <literal>135680</literal> for the + offset (relative to partition + <filename class="devicefile">/dev/da0h</filename>). This translates to 265 + 512-byte disk blocks in <command>bsdlabel</command>'s terms. + Likewise, the size of this root volume is 245760 512-byte + blocks. <filename class="devicefile">/dev/da1h</filename>, containing the + second replica of this root volume, has a symmetric + setup.</para> + + <para>The bsdlabel for these devices might look like:</para> + + <screen> +... +8 partitions: +# size offset fstype [fsize bsize bps/cpg] + a: 245760 281 4.2BSD 2048 16384 0 # (Cyl. 0*- 15*) + c: 71771688 0 unused 0 0 # (Cyl. 0 - 4467*) + h: 71771672 16 vinum # (Cyl. 0*- 4467*) + </screen> + + <para>It can be observed that the <literal>"size"</literal> + parameter for the faked <literal>"a"</literal> partition + matches the value outlined above, while the + <literal>"offset"</literal> parameter is the sum of the offset + within the Vinum partition <literal>"h"</literal>, and the + offset of this partition within the device (or slice). This + is a typical setup that is necessary to avoid the problem + described in <xref linkend="vinum-root-panic">. It can also + be seen that the entire <literal>"a"</literal> partition is + completely within the <literal>"h"</literal> partition + containing all the Vinum data for this device.</para> + + <para>Note that in the above example, the entire device is + dedicated to Vinum, and there is no leftover pre-Vinum root + partition, since this has been a newly set-up disk that was + only meant to be part of a Vinum configuration, ever.</para> + </sect2> + + <sect2> + <title>Troubleshooting</title> + + <para>If something goes wrong, a way is needed to recover from + the situation. The following list contains few known pitfalls + and solutions.</para> + + <sect3> + <title>System Bootstrap Loads, but System Does Not Boot</title> + + <para>If for any reason the system does not continue to boot, + the bootstrap can be interrupted with by pressing the + <keycap>space</keycap> key at the 10-seconds warning. The + loader variables (like <literal>vinum.autostart</literal>) + can be examined using the <command>show</command>, and + manipulated using <command>set</command> or + <command>unset</command> commands.</para> + + <para>If the only problem was that the Vinum kernel module was + not yet in the list of modules to load automatically, a + simple <command>load geom_vinum</command> will help.</para> + + <para>When ready, the boot process can be continued with a + <command>boot -as</command>. The options + <option>-as</option> will request the kernel to ask for the + root filesystem to mount (<option>-a</option>), and make the + boot process stop in single-user mode (<option>-s</option>), + where the root filesystem is mounted read-only. That way, + even if only one plex of a multi-plex volume has been + mounted, no data inconsistency between plexes is being + risked.</para> + + <para>At the prompt asking for a root filesystem to mount, any + device that contains a valid root filesystem can be entered. + If <filename>/etc/fstab</filename> had been set up + correctly, the default should be something like + <literal>ufs:/dev/gvinum/root</literal>. A typical alternate + choice would be something like + <literal>ufs:da0d</literal> which could be a + hypothetical partition that contains the pre-Vinum root + filesystem. Care should be taken if one of the alias + <literal>"a"</literal> partitions are entered here that are + actually reference to the subdisks of the Vinum root device, + because in a mirrored setup, this would only mount one piece + of a mirrored root device. If this filesystem is to be + mounted read-write later on, it is necessary to remove the + other plex(es) of the Vinum root volume since these plexes + would otherwise carry inconsistent data.</para> + </sect3> + + <sect3> + <title>Only Primary Bootstrap Loads</title> + + <para>If <filename>/boot/loader</filename> fails to load, but + the primary bootstrap still loads (visible by a single dash + in the left column of the screen right after the boot + process starts), an attempt can be made to interrupt the + primary bootstrap at this point, using the + <keycap>space</keycap> key. This will make the bootstrap + stop in stage two, see <xref linkend="boot-boot1">. An + attempt can be made here to boot off an alternate partition, + like the partition containing the previous root filesystem + that has been moved away from <literal>"a"</literal> + above.</para> + </sect3> + + <sect3 id="vinum-root-panic"> + <title>Nothing Boots, the Bootstrap + Panics</title> + + <para>This situation will happen if the bootstrap had been + destroyed by the Vinum installation. Unfortunately, Vinum + accidentally currently leaves only 4 KB at the beginning of + its partition free before starting to write its Vinum header + information. However, the stage one and two bootstraps plus + the bsdlabel embedded between them currently require 8 KB. + So if a Vinum partition was started at offset 0 within a + slice or disk that was meant to be bootable, the Vinum setup + will trash the bootstrap.</para> + + <para>Similarly, if the above situation has been recovered, + for example by booting from a <quote>Fixit</quote> medium, + and the bootstrap has been re-installed using + <command>bsdlabel -B</command> as described in <xref + linkend="boot-boot1">, the bootstrap will trash the Vinum + header, and Vinum will no longer find its disk(s). Though + no actual Vinum configuration data or data in Vinum volumes + will be trashed by this, and it would be possible to recover + all the data by entering exact the same Vinum configuration + data again, the situation is hard to fix at all. It would + be necessary to move the entire Vinum partition by at least + 4 KB off, in order to have the Vinum header and the system + bootstrap no longer collide.</para> + </sect3> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/virtualization/Makefile b/en_US.ISO8859-1/books/handbook/virtualization/Makefile new file mode 100644 index 0000000000..4c89488e9c --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/virtualization/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= virtualization/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/virtualization/chapter.sgml b/en_US.ISO8859-1/books/handbook/virtualization/chapter.sgml new file mode 100644 index 0000000000..aa53c0534a --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/virtualization/chapter.sgml @@ -0,0 +1,1312 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="virtualization"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + <!-- Mar 2007 --> + </chapterinfo> + + <title>Virtualization</title> + + <sect1 id="virtualization-synopsis"> + <title>Synopsis</title> + + <para>Virtualization software allows multiple operating systems + to run simultaneously on the same computer. Such software + systems for PCs often involve a host operating system which runs + the virtualization software and supports any number of guest + operating systems.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>The difference between a host operating system and a + guest operating system.</para> + </listitem> + + <listitem> + <para>How to install &os; on an &intel;-based &apple; + &macintosh; computer.</para> + </listitem> + +<!-- + Note: There is no working/end-user ready Xen support for FreeBSD as of 07-2010. + Hide all information regarding Xen under FreeBSD. + + <listitem> + <para>How to install &os; on Linux with + <application>&xen;</application>.</para> + </listitem> +--> + <listitem> + <para>How to install &os; on µsoft.windows; with + <application>Virtual PC</application>.</para> + </listitem> + + <listitem> + <para>How to tune a &os; system for best performance under + virtualization.</para> + </listitem> + + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand the basics of &unix; and &os; (<xref + linkend="basics">).</para> + </listitem> + + <listitem> + <para>Know how to install &os; (<xref + linkend="install">).</para> + </listitem> + + <listitem> + <para>Know how to set up your network connection (<xref + linkend="advanced-networking">).</para> + </listitem> + + <listitem> + <para>Know how to install additional third-party + software (<xref linkend="ports">).</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="virtualization-guest"> + <title>&os; as a Guest OS</title> + + <sect2 id="virtualization-guest-parallels"> + <title>Parallels on MacOS</title> + + <para><application>Parallels Desktop</application> for &mac; is + a commercial software product available for &intel; based + &apple; &mac; computers running &macos; 10.4.6 or higher. + &os; is a fully supported guest operating system. Once + <application>Parallels</application> has been installed on + &macos; X, the user must configure a virtual machine and then + install the desired guest operating system.</para> + + <sect3 id="virtualization-guest-parallels-install"> + <title>Installing &os; on Parallels/&macos; X</title> + + <para>The first step in installing &os; on &macos; + X/<application>Parallels</application> is to create a new + virtual machine for installing &os;. Select + <guimenuitem>&os;</guimenuitem> as the <guimenu>Guest OS + Type</guimenu> when prompted:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd1"> + </imageobject> + </mediaobject> + + <para>And choose a reasonable amount of disk and memory + depending on your plans for this virtual &os; instance. + 4GB of disk space and 512MB of RAM work well for most uses + of &os; under <application>Parallels</application>:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd2"> + </imageobject> + </mediaobject> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd3"> + </imageobject> + </mediaobject> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd4"> + </imageobject> + </mediaobject> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd5"> + </imageobject> + </mediaobject> + + <para>Select the type of networking and a network + interface:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd6"> + </imageobject> + </mediaobject> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd7"> + </imageobject> + </mediaobject> + + <para>Save and finish the configuration:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd8"> + </imageobject> + </mediaobject> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd9"> + </imageobject> + </mediaobject> + + <para>After your &os; virtual machine has been created, you + will need to install &os; on it. This is best done with an + official &os; CDROM or with an ISO image downloaded from an + official FTP site. When you have the appropriate ISO image + on your local &mac; filesystem or a CDROM in your &mac;'s CD + drive, click on the disc icon in the bottom right corner of + your &os; <application>Parallels</application> window. This + will bring up a window that allows you to associate the + CDROM drive in your virtual machine with an ISO file on disk + or with your real CDROM drive.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd11"> + </imageobject> + </mediaobject> + + <para>Once you have made this association with your CDROM + source, reboot your &os; virtual machine as normal by + clicking the reboot icon. + <application>Parallels</application> will reboot with a + special BIOS that first checks if you have a CDROM just as a + normal BIOS would do.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd10"> + </imageobject> + </mediaobject> + + <para>In this case it will find the &os; installation media + and begin a normal <application>sysinstall</application> + based installation as described in <xref + linkend="install">. You may install, but do not attempt + to configure X11 at this time.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd12"> + </imageobject> + </mediaobject> + + <para>When you have finished the installation, reboot into + your newly installed &os; virtual machine.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/parallels-freebsd13"> + </imageobject> + </mediaobject> + </sect3> + + <sect3 id="virtualization-guest-parallels-configure"> + <title>Configuring &os; on &macos; X/Parallels</title> + + <para>After &os; has been successfully installed on &macos; + X with <application>Parallels</application>, there are a + number of configuration steps that can be taken to + optimize the system for virtualized operation.</para> + + <procedure> + <step> + <title>Set Boot Loader Variables</title> + + <para>The most important step is to reduce the + <option>kern.hz</option> tunable to reduce the CPU + utilization of &os; under the <application>Parallels + </application> environment. This is accomplished by + adding the following line to <filename> + /boot/loader.conf</filename>:</para> + + <programlisting>kern.hz=100</programlisting> + + <para>Without this setting, an idle &os; + <application>Parallels</application> guest + OS will use roughly 15% of the CPU of a single + processor &imac;. After this change the usage will be + closer to a mere 5%.</para> + </step> + + <step> + <title>Create a New Kernel Configuration File</title> + + <para>You can remove all of the SCSI, FireWire, and USB + device drivers. <application>Parallels</application> + provides a virtual network + adapter used by the &man.ed.4; driver, so + all other network devices except for + &man.ed.4; and &man.miibus.4; can be + removed from the kernel.</para> + </step> + + <step> + <title>Configure Networking</title> + + <para>The most basic networking setup involves simply + using DHCP to connect your virtual machine to the same + local area network as your host &mac;. This can be + accomplished by adding + <literal>ifconfig_ed0="DHCP"</literal> to + <filename>/etc/rc.conf</filename>. More advanced + networking setups are described in + <xref linkend="advanced-networking">.</para> + </step> + </procedure> + </sect3> + </sect2> +<!-- +Deactive/hide this section as the instructions in there do NOT work anymore: +- FreeBSD 7.0 has reached its EOL a long time ago. +- The needed files from www.fsmware.com are not available anymore, as the + server is dead. So it is impossible to follow the instructions in here. + +jkois@FreeBSD.org, 2010-06-18 + + <sect2 id="virtualization-guest-xen"> + <sect2info> + <authorgroup> + <author> + <firstname>Fukang</firstname> + <surname>Chen (Loader)</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect2info> + + <title>&os; with &xen; on Linux</title> + + <para>The <application>&xen;</application> hypervisor is an + open source paravirtualization product which is now + supported by the commercial XenSource company. Guest + operating systems are known as domU domains, and the host + operating system is known as dom0. The first step in + running a virtual &os; instance under Linux is to install + <application>&xen;</application> for Linux dom0. The host + operating system will be a Slackware Linux + distribution.</para> + + <sect3 id="xen-slackware-dom0"> + <title>Setup &xen; 3 on Linux dom0</title> + + <procedure> + <step> + <title>Download &xen; 3.0 from XenSource</title> + + <para>Download <ulink + url="http://bits.xensource.com/oss-xen/release/3.0.4-1/src.tgz/xen-3.0.4_1-src.tgz">xen-3.0.4_1-src.tgz</ulink> + from <ulink + url="http://www.xensource.com/"></ulink>.</para> + </step> + + <step> + <title>Unpack the tarball</title> + + <screen>&prompt.root; <userinput>cd xen-3.0.4_1-src</userinput> +&prompt.root; <userinput>KERNELS="linux-2.6-xen0 linux-2.6-xenU" make world</userinput> +&prompt.root; <userinput>make install</userinput></screen> + + <note> + <para>To re-compile the kernel for dom0:</para> + + <screen>&prompt.root; <userinput>cd xen-3.0.4_1-src/linux-2.6.16.33-xen0</userinput> +&prompt.root; <userinput>make menuconfig</userinput> +&prompt.root; <userinput>make</userinput> +&prompt.root; <userinput>make install</userinput></screen> + + <para>Older version of + <application>&xen;</application> may need to specify + <command>make ARCH=xen menuconfig</command></para> + </note> + </step> + + <step> + <title>Add a menu entry into Grub menu.lst</title> + + <para>Edit <filename>/boot/grub/menu.lst</filename> and + add the following lines:</para> + + <programlisting>title Xen-3.0.4 +root (hd0,0) +kernel /boot/xen-3.0.4-1.gz dom0_mem=262144 +module /boot/vmlinuz-2.6.16.33-xen0 root=/dev/hda1 ro</programlisting> + </step> + + <step> + <title>Reboot your computer into &xen;</title> + + <para>First, edit + <filename>/etc/xen/xend-config.sxp</filename>, and add + the following line:</para> + + <programlisting>(network-script 'network-bridge netdev=eth0')</programlisting> + + <para>Then, we can launch + <application>&xen;</application>:</para> + + <screen>&prompt.root; <userinput>/etc/init.d/xend start</userinput> +&prompt.root; <userinput>/etc/init.d/xendomains start</userinput></screen> + + <para>Our dom0 is running:</para> + + <screen>&prompt.root; <userinput>xm list</userinput> +Name ID Mem VCPUs State Time(s) +Domain-0 0 256 1 r––––– 54452.9</screen> + </step> + </procedure> + </sect3> + + <sect3> + <title>&os; 7-CURRENT domU</title> + + <para>Download the &os; domU kernel for + <application>&xen; 3.0</application> and disk image from + <ulink + url="http://www.fsmware.com/">http://www.fsmware.com/</ulink></para> + + <itemizedlist> + <listitem> + <para><ulink + url="http://www.fsmware.com/xenofreebsd/7.0/download/kernel-current">kernel-current</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://www.fsmware.com/xenofreebsd/7.0/download/mdroot-7.0.bz2">mdroot-7.0.bz2</ulink></para> + </listitem> + + <listitem> + <para><ulink + url="http://www.fsmware.com/xenofreebsd/7.0/download/config/xmexample1.bsd">xmexample1.bsd</ulink></para> + </listitem> + </itemizedlist> + + <para>Put the configuration file + <filename>xmexample1.bsd</filename> into + <filename>/etc/xen/</filename> and modify the related + entries about where the kernel and the disk image are + stored. It should look like the following:</para> + + <programlisting>kernel = "/opt/kernel-current" +memory = 256 +name = "freebsd" +vif = [ '' ] +disk = [ 'file:/opt/mdroot-7.0,hda1,w' ] +#on_crash = 'preserve' +extra = "boot_verbose" +extra += ",boot_single" +extra += ",kern.hz=100" +extra += ",vfs.root.mountfrom=ufs:/dev/xbd769a"</programlisting> + + <para>The <filename>mdroot-7.0.bz2</filename> file should + be uncompressed.</para> + + <para>Next, the __xen_guest section in + <filename>kernel-current</filename> needs to be altered to + add the VIRT_BASE that + <application>&xen; 3.0.3</application> requires:</para> + + <screen>&prompt.root; <userinput>objcopy kernel-current -R __xen_guest</userinput> +&prompt.root; <userinput>perl -e 'print "LOADER=generic,GUEST_OS=freebsd,GUEST_VER=7.0,XEN_VER=xen-3.0,BSD_SYMTAB,VIRT_BASE=0xC0000000\x00"' > tmp</userinput> +&prompt.root; <userinput>objcopy kernel-current ––add-section __xen_guest=tmp</userinput></screen> + + <screen>&prompt.root; <userinput>objdump -j __xen_guest -s kernel-current</userinput> + +kernel-current: file format elf32-i386 + +Contents of section __xen_guest: + 0000 4c4f4144 45523d67 656e6572 69632c47 LOADER=generic,G + 0010 55455354 5f4f533d 66726565 6273642c UEST_OS=freebsd, + 0020 47554553 545f5645 523d372e 302c5845 GUEST_VER=7.0,XE + 0030 4e5f5645 523d7865 6e2d332e 302c4253 N_VER=xen-3.0,BS + 0040 445f5359 4d544142 2c564952 545f4241 D_SYMTAB,VIRT_BA + 0050 53453d30 78433030 30303030 3000 SE=0xC0000000. </screen> + + <para>We are, now, ready to create and launch our + domU:</para> + + <screen>&prompt.root; <userinput>xm create /etc/xen/xmexample1.bsd -c</userinput> +Using config file "/etc/xen/xmexample1.bsd". +Started domain freebsd +WARNING: loader(8) metadata is missing! +Copyright (c) 1992-2006 The FreeBSD Project. +Copyright (c) 1979, 1980, 1983, 1986, 1988, 1989, 1991, 1992, 1993, 1994 +The Regents of the University of California. All rights reserved. +FreeBSD 7.0-CURRENT #113: Wed Jan 4 06:25:43 UTC 2006 + kmacy@freebsd7.gateway.2wire.net:/usr/home/kmacy/p4/freebsd7_xen3/src/sys/i386-xen/compile/XENCONF +WARNING: DIAGNOSTIC option enabled, expect reduced performance. +Xen reported: 1796.927 MHz processor. +Timecounter "ixen" frequency 1796927000 Hz quality 0 +CPU: Intel(R) Pentium(R) 4 CPU 1.80GHz (1796.93-MHz 686-class CPU) + Origin = "GenuineIntel" Id = 0xf29 Stepping = 9 + Features=0xbfebfbff<FPU,VME,DE,PSE,TSC,MSR,PAE,MCE,CX8,APIC,SEP,MTRR,PGE,MCA,CMOV,PAT,PSE36,CLFLUSH, + DTS,ACPI,MMX,FXSR,SSE,SSE2,SS,HTT,TM,PBE> + Features2=0x4400<CNTX-ID,<b14>> +real memory = 265244672 (252 MB) +avail memory = 255963136 (244 MB) +xc0: <Xen Console> on motherboard +cpu0 on motherboard +Timecounters tick every 10.000 msec +[XEN] Initialising virtual ethernet driver. +xn0: Ethernet address: 00:16:3e:6b:de:3a +[XEN] +Trying to mount root from ufs:/dev/xbd769a +WARNING: / was not properly dismounted +Loading configuration files. +No suitable dump device was found. +Entropy harvesting: interrupts ethernet point_to_point kickstart. +Starting file system checks: +/dev/xbd769a: 18859 files, 140370 used, 113473 free (10769 frags, 12838 blocks, 4.2% fragmentation) +Setting hostname: demo.freebsd.org. +lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 + inet6 ::1 prefixlen 128 + inet6 fe80::1%lo0 prefixlen 64 scopeid 0x2 + inet 127.0.0.1 netmask 0xff000000 +Additional routing options:. +Mounting NFS file systems:. +Starting syslogd. +/etc/rc: WARNING: Dump device does not exist. Savecore not run. +ELF ldconfig path: /lib /usr/lib /usr/lib/compat /usr/X11R6/lib /usr/local/lib +a.out ldconfig path: /usr/lib/aout /usr/lib/compat/aout /usr/X11R6/lib/aout +Starting usbd. +usb: Kernel module not available: No such file or directory +Starting local daemons:. +Updating motd. +Starting sshd. +Initial i386 initialization:. +Additional ABI support: linux. +Starting cron. +Local package initialization:. +Additional TCP options:. +Starting background file system checks in 60 seconds. + +Sun Apr 1 02:11:43 UTC 2007 + +FreeBSD/i386 (demo.freebsd.org) (xc0) + +login: </screen> + + <para>The domU should run the &os; 7.0-CURRENT + kernel:</para> + + <screen>&prompt.root; <userinput>uname -a</userinput> +FreeBSD demo.freebsd.org 7.0-CURRENT FreeBSD 7.0-CURRENT #113: Wed Jan 4 06:25:43 UTC 2006 +kmacy@freebsd7.gateway.2wire.net:/usr/home/kmacy/p4/freebsd7_xen3/src/sys/i386-xen/compile/XENCONF i386</screen> + + <para>The network can now be configured on the domU. The + &os; domU will use a specific interface called + <devicename>xn0</devicename>:</para> + + <screen>&prompt.root; <userinput>ifconfig xn0 10.10.10.200 netmask 255.0.0.0</userinput> +&prompt.root; <userinput>ifconfig</userinput> +xn0: flags=843<UP,BROADCAST,RUNNING,SIMPLEX> mtu 1500 + inet 10.10.10.200 netmask 0xff000000 broadcast 10.255.255.255 + ether 00:16:3e:6b:de:3a +lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 + inet6 ::1 prefixlen 128 + inet6 fe80::1%lo0 prefixlen 64 scopeid 0x2 + inet 127.0.0.1 netmask 0xff000000 </screen> + + <para>On dom0 Slackware, some + <application>&xen;</application> dependant network + interfaces should show up:</para> + + <screen>&prompt.root; <userinput>ifconfig</userinput> +eth0 Link encap:Ethernet HWaddr 00:07:E9:A0:02:C2 + inet addr:10.10.10.130 Bcast:0.0.0.0 Mask:255.0.0.0 + UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 + RX packets:815 errors:0 dropped:0 overruns:0 frame:0 + TX packets:1400 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:204857 (200.0 KiB) TX bytes:129915 (126.8 KiB) + +lo Link encap:Local Loopback + inet addr:127.0.0.1 Mask:255.0.0.0 + UP LOOPBACK RUNNING MTU:16436 Metric:1 + RX packets:99 errors:0 dropped:0 overruns:0 frame:0 + TX packets:99 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:9744 (9.5 KiB) TX bytes:9744 (9.5 KiB) + +peth0 Link encap:Ethernet HWaddr FE:FF:FF:FF:FF:FF + UP BROADCAST RUNNING NOARP MTU:1500 Metric:1 + RX packets:1853349 errors:0 dropped:0 overruns:0 frame:0 + TX packets:952923 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:1000 + RX bytes:2432115831 (2.2 GiB) TX bytes:86528526 (82.5 MiB) + Base address:0xc000 Memory:ef020000-ef040000 + +vif0.1 Link encap:Ethernet HWaddr FE:FF:FF:FF:FF:FF + UP BROADCAST RUNNING NOARP MTU:1500 Metric:1 + RX packets:1400 errors:0 dropped:0 overruns:0 frame:0 + TX packets:815 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:129915 (126.8 KiB) TX bytes:204857 (200.0 KiB) + +vif1.0 Link encap:Ethernet HWaddr FE:FF:FF:FF:FF:FF + UP BROADCAST RUNNING NOARP MTU:1500 Metric:1 + RX packets:3 errors:0 dropped:0 overruns:0 frame:0 + TX packets:2 errors:0 dropped:157 overruns:0 carrier:0 + collisions:0 txqueuelen:1 + RX bytes:140 (140.0 b) TX bytes:158 (158.0 b) + +xenbr1 Link encap:Ethernet HWaddr FE:FF:FF:FF:FF:FF + UP BROADCAST RUNNING NOARP MTU:1500 Metric:1 + RX packets:4 errors:0 dropped:0 overruns:0 frame:0 + TX packets:0 errors:0 dropped:0 overruns:0 carrier:0 + collisions:0 txqueuelen:0 + RX bytes:112 (112.0 b) TX bytes:0 (0.0 b)</screen> + + <screen>&prompt.root; <userinput>brctl show</userinput> +bridge name bridge id STP enabled interfaces +xenbr1 8000.feffffffffff no vif0.1 + peth0 + vif1.0</screen> + </sect3> + </sect2> +--> + <sect2 id="virtualization-guest-virtualpc"> + <title>Virtual PC on &windows;</title> + + <para><application>Virtual PC</application> for &windows; is a + µsoft; software product available for free download. + See <ulink + url="http://www.microsoft.com/windows/downloads/virtualpc/sysreq.mspx"> + system requirements</ulink>. Once <application> Virtual PC + </application> has been installed on µsoft.windows;, + the user must configure a virtual machine and then install + the desired guest operating system.</para> + + <sect3 id="virtualization-guest-virtualpc-install"> + <title>Installing &os; on Virtual + PC/µsoft.windows;</title> + + <para>The first step in installing &os; on + µsoft.windows; /<application>Virtual PC + </application> is to create a new virtual machine for + installing &os;. Select <guimenuitem>Create a virtual + machine</guimenuitem> when prompted:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd1"> + </imageobject> + </mediaobject> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd2"> + </imageobject> + </mediaobject> + + <para>And select <guimenuitem>Other</guimenuitem> as the + <guimenuitem>Operating system</guimenuitem> when + prompted:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd3"> + </imageobject> + </mediaobject> + + <para>Then, choose a reasonable amount of disk and memory + depending on your plans for this virtual &os; + instance. 4GB of disk space and 512MB of RAM work well + for most uses of &os; under + <application>Virtual PC</application>:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd4"> + </imageobject> + </mediaobject> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd5"> + </imageobject> + </mediaobject> + + <para>Save and finish the configuration:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd6"> + </imageobject> + </mediaobject> + + <para>Select your &os; virtual machine and click + <guimenu>Settings</guimenu>, then set the type of networking + and a network interface:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd7"> + </imageobject> + </mediaobject> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd8"> + </imageobject> + </mediaobject> + + <para>After your &os; virtual machine has been created, you + will need to install &os; on it. This is best done with an + official &os; CDROM or with an ISO image downloaded from an + official FTP site. When you have the appropriate ISO image + on your local &windows; filesystem or a CDROM in your CD + drive, double click on your &os; virtual machine to boot. + Then, click <guimenu>CD</guimenu> and choose + <guimenu>Capture ISO Image...</guimenu> on + <application>Virtual PC</application> window. This will + bring up a window that allows you to associate the CDROM + drive in your virtual machine with an ISO file on disk or + with your real CDROM drive.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd9"> + </imageobject> + </mediaobject> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd10"> + </imageobject> + </mediaobject> + + <para>Once you have made this association with your CDROM + source, reboot your &os; virtual machine as normal by + clicking the <guimenu>Action</guimenu> and + <guimenu>Reset</guimenu>. + <application>Virtual PC</application> will reboot with a + special BIOS that first checks if you have a CDROM just as a + normal BIOS would do.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd11"> + </imageobject> + </mediaobject> + + <para>In this case it will find the &os; installation media + and begin a normal <application>sysinstall</application> + based installation as described in <xref linkend="install">. + You may install, but do not attempt to configure X11 at this + time.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd12"> + </imageobject> + </mediaobject> + + <para>When you have finished the installation, remember to + eject CDROM or release ISO image. Finally, reboot into your + newly installed &os; virtual machine.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/virtualpc-freebsd13"> + </imageobject> + </mediaobject> + </sect3> + + <sect3 id="virtualization-guest-virtualpc-configure"> + <title>Configuring &os; on µsoft.windows;/Virtual + PC</title> + + <para>After &os; has been successfully installed on + µsoft.windows; with <application>Virtual PC + </application>, there are a number of configuration + steps that can be taken to optimize the system for + virtualized operation.</para> + + <procedure> + <step> + <title>Set Boot Loader Variables</title> + + <para>The most important step is to reduce the + <option>kern.hz</option> tunable to reduce the CPU + utilization of &os; under the + <application>Virtual PC</application> environment. + This is accomplished by adding the following line to + <filename> /boot/loader.conf</filename>:</para> + + <programlisting>kern.hz=100</programlisting> + + <para>Without this setting, an idle &os; + <application>Virtual PC</application> guest OS will + use roughly 40% of the CPU of a single processor + computer. After this change the usage will be + closer to a mere 3%.</para> + </step> + + <step> + <title>Create a New Kernel Configuration File</title> + + <para>You can remove all of the SCSI, FireWire, and USB + device drivers. <application>Virtual PC</application> + provides a virtual network adapter used by the + &man.de.4; driver, so all other network devices except + for &man.de.4; and &man.miibus.4; can be removed from + the kernel.</para> + </step> + + <step> + <title>Configure Networking</title> + + <para>The most basic networking setup involves simply + using DHCP to connect your virtual machine to the same + local area network as your host µsoft.windows;. + This can be accomplished by adding + <literal>ifconfig_de0="DHCP"</literal> to + <filename>/etc/rc.conf</filename>. More advanced + networking setups are described in + <xref linkend="advanced-networking">.</para> + </step> + </procedure> + </sect3> + </sect2> + + <sect2 id="virtualization-guest-vmware"> + <title>VMware on MacOS</title> + + <para><application>VMware Fusion</application> for &mac; is a + commercial software product available for &intel; based + &apple; &mac; computers running &macos; 10.4.9 or higher. + &os; is a fully supported guest operating system. Once + <application>VMware Fusion</application> has been + installed on &macos; X, the user must configure a virtual + machine and then install the desired guest operating + system.</para> + + <sect3 id="virtualization-guest-vmware-install"> + <title>Installing &os; on VMware/&macos; X</title> + + <para>The first step is to start VMware Fusion, the Virtual + Machine Library will load. Click "New" to create the + VM:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd01"> + </imageobject> + </mediaobject> + + <para>This will load the New Virtual Machine Assistant to help + you create the VM, click Continue to proceed:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd02"> + </imageobject> + </mediaobject> + + <para>Select <guimenuitem>Other</guimenuitem> as the + <guimenuitem>Operating System</guimenuitem> and + <guimenuitem>&os;</guimenuitem> or + <guimenuitem>&os; 64-bit</guimenuitem>, depending on if + you want 64-bit support, as the <guimenu>Version</guimenu> + when prompted:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd03"> + </imageobject> + </mediaobject> + + <para>Choose the Name of the VM Image and the Directory where + you would like it saved:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd04"> + </imageobject> + </mediaobject> + + <para>Choose the size of the Virtual Hard Disk for the + VM:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd05"> + </imageobject> + </mediaobject> + + <para>Choose the method you would like to install the VM, + either from an ISO image or from a CD:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd06"> + </imageobject> + </mediaobject> + + <para>Once you click Finish, the VM will boot:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd07"> + </imageobject> + </mediaobject> + + <para>Install &os; like you normally would, or by following + the directions in <xref linkend="install">:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd08"> + </imageobject> + </mediaobject> + + <para>Once the install is complete you can modify the settings + of the VM, such as Memory Usage:</para> + + <note> + <para>The System Hardware settings of the VM cannot be + modified while the VM is running.</para> + </note> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd09"> + </imageobject> + </mediaobject> + + <para>The number of CPUs the VM will have access to:</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd10"> + </imageobject> + </mediaobject> + + <para>The status of the CD-Rom Device. Normally you can + disconnect the CD-Rom/ISO from the VM if you will not be + needing it anymore.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd11"> + </imageobject> + </mediaobject> + + <para>The last thing to change is how the VM will connect to + the Network. If you want to allow connections to the VM + from other machines besides the Host, make sure you choose + the <guimenuitem>Connect directly to the physical network + (Bridged)</guimenuitem>. Otherwise <guimenuitem>Share the + host's internet connection (NAT)</guimenuitem> is + preferred so that the VM can have access to the Internet, + but the network cannot access the VM.</para> + + <mediaobject> + <imageobject> + <imagedata fileref="virtualization/vmware-freebsd12"> + </imageobject> + </mediaobject> + + <para>After you have finished modifying the settings, boot the + newly installed &os; virtual machine.</para> + </sect3> + + <sect3 id="virtualization-guest-vmware-configure"> + <title>Configuring &os; on &macos; X/VMware</title> + + <para>After &os; has been successfully installed on &macos; X + with <application>VMware</application>, there are a number + of configuration steps that can be taken to optimize the + system for virtualized operation.</para> + + <procedure> + <step> + <title>Set Boot Loader Variables</title> + + <para>The most important step is to reduce the + <option>kern.hz</option> tunable to reduce the CPU + utilization of &os; under the + <application>VMware</application> environment. This is + accomplished by adding the following line to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>kern.hz=100</programlisting> + + <para>Without this setting, an idle &os; + <application>VMware</application> guest + OS will use roughly 15% of the CPU of a single + processor &imac;. After this change the usage will be + closer to a mere 5%.</para> + </step> + + <step> + <title>Create a New Kernel Configuration File</title> + + <para>You can remove all of the FireWire, and USB device + drivers. <application>VMware</application> provides a + virtual network adapter used by the &man.em.4; driver, + so all other network devices except for &man.em.4; can + be removed from the kernel.</para> + </step> + + <step> + <title>Configure Networking</title> + + <para>The most basic networking setup involves simply + using DHCP to connect your virtual machine to the + same local area network as your host &mac;. This + can be accomplished by adding + <literal>ifconfig_em0="DHCP"</literal> to + <filename>/etc/rc.conf</filename>. More advanced + networking setups are described in + <xref linkend="advanced-networking">.</para> + </step> + </procedure> + </sect3> + </sect2> + + <sect2 id="virtualization-guest-virtualbox-guest-additions"> + <title>&virtualbox; Guest Additions on a &os; Guest</title> + + <para>The <application>&virtualbox;</application> guest + additions provide support for:</para> + + <itemizedlist> + <listitem> + <para>Clipboard sharing</para> + </listitem> + + <listitem> + <para>Mouse pointer integration</para> + </listitem> + + <listitem> + <para>Host time synchronization</para> + </listitem> + + <listitem> + <para>Window scaling</para> + </listitem> + + <listitem> + <para>Seamless mode</para> + </listitem> + </itemizedlist> + + <note> + <para>The following commands are run in the &os; guest.</para> + </note> + + <para>First, install the <filename + role="package">emulators/virtualbox-ose-additions</filename> + package in the &os; guest.</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/emulators/virtualbox-ose-additions && make install clean</userinput></screen> + + <para>Add these lines to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>vboxguest_enable="YES" +vboxservice_enable="YES"</programlisting> + + <para>If &man.ntpd.8; or &man.ntpdate.8; will be used, host time + synchronization should be disabled:</para> + + <programlisting>vboxservice_flags="--disable-timesync"</programlisting> + + <para>The <literal>vboxvideo_drv</literal> should be recognized + by <command>Xorg -configure</command>. If not, modify + <filename>xorg.conf</filename> for the + <application>&virtualbox;</application> video card:</para> + + <programlisting>Section "Device" + ### Available Driver options are:- + ### Values: <i>: integer, <f>: float, <bool>: "True"/"False", + ### <string>: "String", <freq>: "<f> Hz/kHz/MHz" + ### [arg]: arg optional + Identifier "Card0" + Driver "vboxvideo" + VendorName "InnoTek Systemberatung GmbH" + BoardName "VirtualBox Graphics Adapter" + BusID "PCI:0:2:0" +EndSection</programlisting> + + <para>To use <literal>vboxmouse_drv</literal>, adjust the mouse + section in your <filename>xorg.conf</filename>:</para> + + <programlisting>Section "InputDevice" + Identifier "Mouse0" + Driver "vboxmouse" +EndSection</programlisting> + + <para><acronym>HAL</acronym> users should create this file at + <filename>/usr/local/etc/hal/fdi/policy/90-vboxguest.fdi</filename> + or copy it from + <filename>/usr/local/share/hal/fdi/policy/10osvendor/90-vboxguest.fdi</filename>:</para> + + <programlisting><?xml version="1.0" encoding="UTF-8"?> +<!-- +# Sun VirtualBox +# Hal driver description for the vboxmouse driver +# $Id: chapter.sgml,v 1.33 2012-03-17 04:53:52 eadler Exp $ + + Copyright (C) 2008-2009 Sun Microsystems, Inc. + + This file is part of VirtualBox Open Source Edition (OSE, as + available from http://www.virtualbox.org. This file is free software; + you can redistribute it and/or modify it under the terms of the GNU + General Public License (GPL) as published by the Free Software + Foundation, in version 2 as it comes in the "COPYING" file of the + VirtualBox OSE distribution. VirtualBox OSE is distributed in the + hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. + + Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa + Clara, CA 95054 USA or visit http://www.sun.com if you need + additional information or have any questions. +--> +<deviceinfo version="0.2"> + <device> + <match key="info.subsystem" string="pci"> + <match key="info.product" string="VirtualBox guest Service"> + <append key="info.capabilities" type="strlist">input</append> + <append key="info.capabilities" type="strlist">input.mouse</append> + <merge key="input.x11_driver" type="string">vboxmouse</merge> + <merge key="input.device" type="string">/dev/vboxguest</merge> + </match> + </match> + </device> +</deviceinfo></programlisting> + </sect2> + </sect1> + + <sect1 id="virtualization-host"> + <title>&os; as a Host OS</title> + + <para>For a number of years, &os; was not officially supported as + a host OS by any of the available virtualization solutions. + Some people were using older and mostly obsolete versions of + <application>VMware</application> (like + <filename role="package">emulators/vmware3</filename>), which + utilized the &linux; binary compatibility layer. Shortly after + the release of &os; 7.2, the Open Source Edition + (<acronym>OSE</acronym>) of Sun's + <application>&virtualbox;</application> appeared in the + Ports Collection as a native &os; program.</para> + + <para><application>&virtualbox;</application> is an actively + developed, complete virtualization package, that is available + for most operating systems including &windows;, &macos;, &linux; + and &os;. It is equally capable at running &windows; or &unix; + like guests. It comes in two flavors, an open source and a + proprietary edition. From the user's point of view, perhaps the + most important limitation of the <acronym>OSE</acronym> is the + lack of USB support. Other differences may be found in the + <quote>Editions</quote> page of the + <application>&virtualbox;</application> wiki, at + <ulink url="http://www.virtualbox.org/wiki/Editions"></ulink>. + Currently, only the OSE is available for &os;.</para> + + <sect2 id="virtualization-virtualbox-install"> + <title>Installing &virtualbox;</title> + + <para><application>&virtualbox;</application> is available as a + &os; port in + <filename role="package">emulators/virtualbox-ose</filename>. + As &virtualbox; is very actively developed, make sure your + ports tree is up to date before installing. Install using + these commands:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/emulators/virtualbox-ose</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>One useful option in the configuration dialog is the + <literal>GuestAdditions</literal> suite of programs. These + provide a number of useful features in guest operating + systems, like mouse pointer integration (allowing the mouse to + be shared between host and guest without the need to press a + special keyboard shortcut to switch) and faster video + rendering, especially in &windows; guests. The guest + additions are available in the <guimenu>Devices</guimenu> + menu, after the installation of the guest OS is + finished.</para> + + <para>A few configuration changes are needed before + <application>&virtualbox;</application> is started for the + first time. The port installs a kernel module in + <filename class="directory">/boot/modules</filename> which + must be loaded into the running kernel:</para> + + <screen>&prompt.root; <userinput>kldload vboxdrv</userinput></screen> + + <para>To ensure the module always gets loaded after a reboot, + add the following line to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>vboxdrv_load="YES"</programlisting> + + <para>To use the kernel modules that allow bridged or host-only + networking, add the following to + <filename>/etc/rc.conf</filename> and reboot the + computer:</para> + + <programlisting>vboxnet_enable="YES"</programlisting> + + <para>The <groupname>vboxusers</groupname> group is created + during installation of + <application>&virtualbox;</application>. All users that need + access to <application>&virtualbox;</application> will have to + be added as members of this group. The <command>pw</command> + command may be used to add new members:</para> + + <screen>&prompt.root; <userinput>pw groupmod vboxusers -m <replaceable>yourusername</replaceable></userinput></screen> + + <para>The default permissions for + <filename class="devicefile">/dev/vboxnetctl</filename> are + restrictive and need to be changed for bridged + networking.</para> + + <para>To test it temporarily:</para> + + <screen>&prompt.root; <userinput>chown root:vboxusers /dev/vboxnetctl</userinput> +&prompt.root; <userinput>chmod 0660 /dev/vboxnetctl</userinput></screen> + + <para>To make the permissions change permanent, add these + lines to <filename>/etc/devfs.conf</filename>:</para> + + <programlisting>own vboxnetctl root:vboxusers +perm vboxnetctl 0660</programlisting> + + <para>To launch <application>&virtualbox;</application>, either + select the <guimenuitem>Sun VirtualBox</guimenuitem> item from + the graphic environment's menu, or type the following in a + terminal:</para> + + <screen>&prompt.user; <userinput>VirtualBox</userinput></screen> + + <para>For more information on configuring and using + <application>&virtualbox;</application>, please visit the + official website at + <ulink url="http://www.virtualbox.org"></ulink>. As the &os; + port is very recent, it is under heavy development. For the + latest information and troubleshooting instructions, please + visit the relevant page in the &os; wiki, at <ulink + url="http://wiki.FreeBSD.org/VirtualBox"></ulink>.</para> + </sect2> + + <sect2 id="virtualization-virtualbox-usb-support"> + <title>&virtualbox; USB Support</title> + + <note> + <para>These steps require VirtualBox 4.0.0 or later.</para> + </note> + + <para>In order to be able to read and write to USB devices, + users need to be members of the operator group:</para> + + <screen>&prompt.root; <userinput>pw groupmod operator -m <replaceable>jerry</replaceable></userinput></screen> + + <para>Then, add the following to + <filename>/etc/devfs.rules</filename> (create it if it does + not exist yet):</para> + + <programlisting>[system=10] +add path 'usb/*' mode 0660 group operator</programlisting> + + <para>To load these new rules, add the following to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>devfs_system_ruleset="system"</programlisting> + + <para>Then, restart devfs:</para> + + <screen>&prompt.root; <userinput>/etc/rc.d/devfs restart</userinput></screen> + + <para>USB can now be enabled in the guest operating system. USB + devices should be visible in the &virtualbox; + preferences.</para> + </sect2> + + <sect2 id="virtualization-virtualbox-host-dvd-cd-access"> + <title>&virtualbox; Host DVD/CD Access</title> + + <para>The <command>atapicam</command> kernel module needs to be + loaded by adding the following line to + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>atapicam_load="YES"</programlisting> + + <para><acronym>HAL</acronym> needs to run for + <application>&virtualbox;</application> DVD/CD functions to + work, so enable it in <filename>/etc/rc.conf</filename> and + start it (if it is not already running):</para> + + <programlisting>hald_enable="YES"</programlisting> + + <screen>&prompt.root; <userinput>/usr/local/etc/rc.d/hald start</userinput></screen> + + <para>In order for users to be able to use + <application>&virtualbox;</application> DVD/CD functions, they + need access to + <filename class="devicefile">/dev/xpt0</filename>, <filename + class="devicefile">/dev/cd<replaceable>N</replaceable></filename>, + and <filename + class="devicefile">/dev/pass<replaceable>N</replaceable></filename>. + Add the following lines to + <filename>/etc/devfs.conf</filename>:</para> + + <programlisting>perm cd0 0600 +perm xpt0 0660 +perm pass0 0660</programlisting> + </sect2> + +<!-- + Note: There is no working/end-user ready Xen support for FreeBSD as of 07-2010. + Hide all information regarding Xen under FreeBSD. + + <sect2 id="virtualization-other"> + <title>Other Virtualization Options</title> + + <para>There is ongoing work in getting + <application>&xen;</application> + to work as a host environment on &os;.</para> + </sect2> +--> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/handbook/x11/Makefile b/en_US.ISO8859-1/books/handbook/x11/Makefile new file mode 100644 index 0000000000..06b452cd33 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/x11/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= x11/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml new file mode 100644 index 0000000000..4dfee9efa6 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml @@ -0,0 +1,1745 @@ +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> + +<chapter id="x11"> + <chapterinfo> + <authorgroup> + <author> + <firstname>Ken</firstname> + <surname>Tom</surname> + <contrib>Updated for X.Org's X11 server by </contrib> + </author> + <author> + <firstname>Marc</firstname> + <surname>Fonvieille</surname> + </author> + </authorgroup> + </chapterinfo> + + <title>The X Window System</title> + + <sect1 id="x11-synopsis"> + <title>Synopsis</title> + + <para>FreeBSD uses X11 to provide users with + a powerful graphical user interface. X11 + is a freely available version of the X Window System that + is implemented in <application>&xorg;</application> + (and other software + packages not discussed here). + The + default and official flavor of X11 in &os; is + <application>&xorg;</application>, the X11 server developed by + the X.Org Foundation under a license very similar to the one used + by &os;. Commercial X servers for &os; are also available.</para> + + <para>For more information on the video hardware that X11 + supports, check the <ulink + url="http://www.x.org/">&xorg;</ulink> web site.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>The various components of the X Window System, and how they + interoperate.</para> + </listitem> + + <listitem> + <para>How to install and configure X11.</para> + </listitem> + + <listitem> + <para>How to install and use different window managers.</para> + </listitem> + + <listitem> + <para>How to use &truetype; fonts in X11.</para> + </listitem> + + <listitem> + <para>How to set up your system for graphical logins + (<application>XDM</application>).</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Know how to install additional third-party + software (<xref linkend="ports">).</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 id="x-understanding"> + <title>Understanding X</title> + + <para>Using X for the first time can be somewhat of a shock to someone + familiar with other graphical environments, such as µsoft.windows; or + &macos;.</para> + + <para>While it is not necessary to understand all of the details of various + X components and how they interact, some basic knowledge makes + it possible to take advantage of X's strengths.</para> + + <sect2> + <title>Why X?</title> + + <para>X is not the first window system written for &unix;, but it is the + most popular of them. X's original development team had worked on another + window system prior to writing X. That system's name was + <quote>W</quote> (for <quote>Window</quote>). X was just the next + letter in the Roman alphabet.</para> + + <para>X can be called <quote>X</quote>, <quote>X Window System</quote>, + <quote>X11</quote>, and a number of other terms. You may find + that using the term <quote>X Windows</quote> to describe X11 + can be offensive to some people; for a bit more insight on + this, see &man.X.7;.</para> + </sect2> + + <sect2> + <title>The X Client/Server Model</title> + + <para>X was designed from the beginning to be network-centric, and + adopts a <quote>client-server</quote> model.</para> + + <para>In the X model, the + <quote>X server</quote> runs on the computer that has the keyboard, + monitor, and mouse attached. The server's responsibility includes tasks such as managing + the display, handling input from the keyboard and mouse, and other + input or output devices (i.e., a <quote>tablet</quote> can be used as + an input device, and a video projector may be an alternative output + device). + Each X application (such as <application>XTerm</application>, or + <application>&netscape;</application>) is a <quote>client</quote>. A + client sends messages to the server such as <quote>Please draw a + window at these coordinates</quote>, and the server sends back + messages such as <quote>The user just clicked on the OK + button</quote>.</para> + + <para>In a home or small + office environment, the X server and the X clients commonly run on + the same computer. However, it is perfectly possible to run the X + server on a less powerful desktop computer, and run X applications + (the clients) on, say, the powerful and expensive machine that serves + the office. In this scenario the communication between the X client + and server takes place over the network.</para> + + <para>This confuses some people, because the X terminology is + exactly backward to what they expect. They expect the <quote>X + server</quote> to be the big powerful machine down the hall, and + the <quote>X client</quote> to be the machine on their desk.</para> + + <para>It is important to remember that the X server is the machine with the monitor and + keyboard, and the X clients are the programs that display the + windows.</para> + + <para>There is nothing in the protocol that forces the client and + server machines to be running the same operating system, or even to + be running on the same type of computer. It is certainly possible to + run an X server on µsoft.windows; or Apple's &macos;, and there are + various free and commercial applications available that do exactly + that.</para> + </sect2> + + <sect2> + <title>The Window Manager</title> + + <para>The X design philosophy is much like the &unix; design philosophy, + <quote>tools, not policy</quote>. This means that X does not try to + dictate how a task is to be accomplished. Instead, tools are provided + to the user, and it is the user's responsibility to decide how to use + those tools.</para> + + <para>This philosophy extends to X not dictating what windows should + look like on screen, how to move them around with the mouse, what + keystrokes should be used to move between windows (i.e., + <keycombo action="simul"> + <keycap>Alt</keycap> + <keycap>Tab</keycap> + </keycombo>, in the case of µsoft.windows;), what the title bars + on each window should look like, whether or not they have close + buttons on them, and so on.</para> + + <para>Instead, X delegates this responsibility to an application called + a <quote>Window Manager</quote>. There are dozens of window + managers available for X: <application>AfterStep</application>, + <application>Blackbox</application>, <application>ctwm</application>, + <application>Enlightenment</application>, + <application>fvwm</application>, <application>Sawfish</application>, + <application>twm</application>, + <application>Window Maker</application>, and more. Each of these + window managers provides a different look and feel; some of them + support <quote>virtual desktops</quote>; some of them allow customized + keystrokes to manage the desktop; some have a <quote>Start</quote> + button or similar device; some are <quote>themeable</quote>, allowing + a complete change of look-and-feel by applying a new theme. These + window managers, and many more, are available in the + <filename>x11-wm</filename> category of the Ports Collection.</para> + + <para>In addition, the <application>KDE</application> and + <application>GNOME</application> desktop environments both have their + own window managers which integrate with the desktop.</para> + + <para>Each window manager also has a different configuration mechanism; + some expect configuration file written by hand, others feature + GUI tools for most of the configuration tasks; at least one + (<application>Sawfish</application>) has a configuration file written + in a dialect of the Lisp language.</para> + + <note> + <title>Focus Policy</title> + + <para>Another feature the window manager is responsible for is the + mouse <quote>focus policy</quote>. Every windowing system + needs some means of choosing a window to be actively receiving + keystrokes, and should visibly indicate which window is active as + well.</para> + + <para>A familiar focus policy is called <quote>click-to-focus</quote>. + This is the model utilized by µsoft.windows;, in which a window + becomes active upon receiving a mouse click.</para> + + <para>X does not support any particular focus policy. Instead, the + window manager controls which window has the focus at any one time. + Different window managers will support different focus methods. All + of them support click to focus, and the majority of them support + several others.</para> + + <para>The most popular focus policies are:</para> + + <variablelist> + <varlistentry> + <term>focus-follows-mouse</term> + + <listitem> + <para>The window that is under the mouse pointer is the + window that has the focus. This may not necessarily be + the window that is on top of all the other windows. + The focus is changed by pointing at another window, there + is no need to click in it as well.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>sloppy-focus</term> + + <listitem> + <para>This policy is a small extension to focus-follows-mouse. + With focus-follows-mouse, if the mouse is moved over the + root window (or background) then no window has the focus, + and keystrokes are simply lost. With sloppy-focus, focus is + only changed when the cursor enters a new window, and not + when exiting the current window.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>click-to-focus</term> + + <listitem> + <para>The active window is selected by mouse click. The + window may then be <quote>raised</quote>, and appear in + front of all other windows. All keystrokes will now be + directed to this window, even if the cursor is moved to + another window.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Many window managers support other policies, as well as + variations on these. Be sure to consult the documentation for + the window manager itself.</para> + </note> + </sect2> + + <sect2> + <title>Widgets</title> + + <para>The X approach of providing tools and not policy extends to the + widgets seen on screen in each application.</para> + + <para><quote>Widget</quote> is a term for all the items in the user + interface that can be clicked or manipulated in some way; buttons, + check boxes, radio buttons, icons, lists, and so on. µsoft.windows; + calls these <quote>controls</quote>.</para> + + <para>µsoft.windows; and Apple's &macos; both have a very rigid widget + policy. Application developers are supposed to ensure that their + applications share a common look and feel. With X, it was not + considered sensible to mandate a particular graphical style, or set + of widgets to adhere to.</para> + + <para>As a result, do not expect X applications to have a common + look and feel. There are several popular widget sets and + variations, including the original Athena widget set from MIT, + <application>&motif;</application> (on which the widget set in + µsoft.windows; was modeled, all bevelled edges and three shades of + grey), <application>OpenLook</application>, and others.</para> + + <para>Most newer X applications today will use a modern-looking widget + set, either Qt, used by <application>KDE</application>, or + GTK+, used by the + <application>GNOME</application> + project. In this respect, there is some convergence in + look-and-feel of the &unix; desktop, which certainly makes things + easier for the novice user.</para> + </sect2> + </sect1> + + <sect1 id="x-install"> + <title>Installing X11</title> + + <para><application>&xorg;</application> is the default X11 + implementation for &os;. <application>&xorg;</application> is + the X server of the open source X Window System implementation released by the X.Org + Foundation. <application>&xorg;</application> is based on the code of + <application>&xfree86 4.4RC2</application> and X11R6.6. + The version of <application>&xorg;</application> currently + available in the &os; Ports Collection is &xorg.version;.</para> + + <para>To build and install <application>&xorg;</application> from the + Ports Collection:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/x11/xorg</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <note> + <para>To build <application>&xorg;</application> in its + entirety, be sure to have at least 4 GB of free space + available.</para> + </note> + + <para>Alternatively, X11 + can be installed directly from packages. + Binary packages to use with &man.pkg.add.1; tool are also available for + X11. When the remote fetching + feature of &man.pkg.add.1; is used, the version number of the + package must be removed. &man.pkg.add.1; will automatically fetch + the latest version of the application.</para> + + <para>So to fetch and install the package of + <application>&xorg;</application>, simply type:</para> + + <screen>&prompt.root; <userinput>pkg_add -r xorg</userinput></screen> + + <note><para>The examples above will install the complete + X11 distribution including the + servers, clients, fonts etc. Separate packages and ports of X11 + are also + available.</para> + + <para>To install a minimal X11 distribution you can alternatively install + <filename role="package">x11/xorg-minimal</filename>.</para> + </note> + + <para>The rest of this chapter will explain how to configure + X11, and how to set up a productive desktop + environment.</para> + </sect1> + + <sect1 id="x-config"> + <sect1info> + <authorgroup> + <author> + <firstname>Christopher</firstname> + <surname>Shumway</surname> + <contrib>Contributed by </contrib> + <!-- July 2001 --> + </author> + </authorgroup> + </sect1info> + <title>X11 Configuration</title> + + + <indexterm><primary>&xorg;</primary></indexterm> + <indexterm><primary>X11</primary></indexterm> + + <sect2> + <title>Before Starting</title> + + <para>Before configuration of X11 + the following information about the target system is needed:</para> + + <itemizedlist> + <listitem><para>Monitor specifications</para></listitem> + <listitem><para>Video Adapter chipset</para></listitem> + <listitem><para>Video Adapter memory</para></listitem> + </itemizedlist> + + <indexterm><primary>horizontal scan rate</primary></indexterm> + <indexterm><primary>vertical scan rate</primary></indexterm> + + <para>The specifications for the monitor are used by + X11 to determine the resolution and + refresh rate to run at. These specifications can usually be + obtained from the documentation that came with the monitor or from + the manufacturer's website. There are two ranges of numbers that + are needed, the horizontal scan rate and the vertical synchronization + rate.</para> + + <para>The video adapter's chipset defines what driver module + X11 uses to talk to the graphics + hardware. With most chipsets, this can be automatically + determined, but it is still useful to know in case the automatic + detection does not work correctly.</para> + + <para>Video memory on the graphic adapter determines the + resolution and color depth which the system can run at. This is + important to know so the user knows the limitations of the + system.</para> + </sect2> + + <sect2> + <title>Configuring X11</title> + + <para><application>&xorg;</application> + uses <acronym>HAL</acronym> to autodetect keyboards and mice. + The <filename role="package">sysutils/hal</filename> and + <filename role="package">devel/dbus</filename> ports are installed + as dependencies of <filename role="package">x11/xorg</filename>, but + must be enabled by the following entries in the + <filename>/etc/rc.conf</filename> file:</para> + + <programlisting>hald_enable="YES" +dbus_enable="YES"</programlisting> + + <para>These services should be started (either manually or by + rebooting) before further <application>&xorg;</application> + configuration or use is attempted.</para> + + <para><application>&xorg;</application> can + often work without any further configuration steps by simply typing at + prompt:</para> + + <screen>&prompt.user; <userinput>startx</userinput></screen> + + <para>The automatic configuration may fail to work with some hardware, + or may not set things up quite as desired. In these cases, manual + configuration will be necessary.</para> + + <note> + <para>Desktop environments like + <application>GNOME</application>, + <application>KDE</application> or + <application>Xfce</application> have tools allowing the user + to easily set the screen parameters such as the resolution. + So if the default configuration is not acceptable and you + planned to install a desktop environment then just continue + with the installation of the desktop environment and use the + appropriate screen settings tool.</para> + </note> + + <para>Configuration of X11 is + a multi-step process. The first step is to build an initial + configuration file. + As the super user, simply + run:</para> + + <screen>&prompt.root; <userinput>Xorg -configure</userinput></screen> + + <para>This will generate an + X11 configuration skeleton file in the + <filename>/root</filename> directory called + <filename>xorg.conf.new</filename> (whether you &man.su.1; or + do a direct login affects the inherited supervisor + <envar>$HOME</envar> directory variable). The + X11 program will attempt to probe + the graphics hardware on the system and write a + configuration file to load the proper drivers for the detected + hardware on the target system.</para> + + <para>The next step is to test the existing + configuration to verify that <application>&xorg;</application> + can work with the graphics + hardware on the target system. Type:</para> + + <screen>&prompt.root; <userinput>Xorg -config xorg.conf.new -retro</userinput></screen> + + <para>If a black and grey grid and an X mouse cursor appear, + the configuration was successful. To exit the test, switch to the + virtual console used to start it by pressing + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>Alt</keycap> + <keycap>F<replaceable>n</replaceable></keycap> + </keycombo> (<keycap>F1</keycap> for the first virtual console) + and press + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>C</keycap> + </keycombo>.</para> + + <note> + <para>The + <keycombo action="simul"> + <keycap>Ctrl</keycap> + <keycap>Alt</keycap> + <keycap>Backspace</keycap> + </keycombo> key combination may also be used to break out of + <application>&xorg;</application>. To enable it, + you can either type the following + command from any X terminal emulator:</para> + + <screen>&prompt.user; <userinput>setxkbmap -option terminate:ctrl_alt_bksp</userinput></screen> + + <para>or create a keyboard configuration file for + <application>hald</application> called + <filename>x11-input.fdi</filename> and saved in the + <filename + class="directory">/usr/local/etc/hal/fdi/policy</filename> + directory. This file should contain the following + lines:</para> + + <programlisting><?xml version="1.0" encoding="ISO-8859-1"?> +<deviceinfo version="0.2"> + <device> + <match key="info.capabilities" contains="input.keyboard"> + <merge key="input.x11_options.XkbOptions" type="string">terminate:ctrl_alt_bksp</merge> + </match> + </device> +</deviceinfo></programlisting> + + <para>You will have to reboot your machine to force + <application>hald</application> to read this file.</para> + + <para>The following line will also have to be added to + <filename>xorg.conf.new</filename>, in the + <literal>ServerLayout</literal> or <literal>ServerFlags</literal> + section:</para> + + <programlisting>Option "DontZap" "off"</programlisting> + </note> + + <para>If the mouse does not work, you will need to first + configure it before proceeding. See <xref linkend="mouse"> + in the &os; install chapter. In recent + <application>Xorg</application> versions, + the <literal>InputDevice</literal> sections in + <filename>xorg.conf</filename> are ignored in favor of the + autodetected devices. To restore the old behavior, add the + following line to the <literal>ServerLayout</literal> or + <literal>ServerFlags</literal> section of this file:</para> + + <programlisting>Option "AutoAddDevices" "false"</programlisting> + + <para>Input devices may then be configured as in previous versions, + along with any other options needed (e.g., keyboard layout + switching).</para> + + <note> + <para>As previously explained + the <application>hald</application> daemon will, by default, + automatically detect your keyboard. There are chances that + your keyboard layout or model will not be correct, desktop + environments like <application>GNOME</application>, + <application>KDE</application> or + <application>Xfce</application> provide tools to configure + the keyboard. However, it is possible to set the keyboard + properties directly either with the help of the + &man.setxkbmap.1; utility or with a + <application>hald</application>'s configuration rule.</para> + + <para>For example if one wants to use a PC 102 keys keyboard + coming with a french layout, we have to create a keyboard + configuration file for <application>hald</application> + called <filename>x11-input.fdi</filename> and saved in the + <filename + class="directory">/usr/local/etc/hal/fdi/policy</filename> + directory. This file should contain the following + lines:</para> + + <programlisting><?xml version="1.0" encoding="ISO-8859-1"?> +<deviceinfo version="0.2"> + <device> + <match key="info.capabilities" contains="input.keyboard"> + <merge key="input.x11_options.XkbModel" type="string">pc102</merge> + <merge key="input.x11_options.XkbLayout" type="string">fr</merge> + </match> + </device> +</deviceinfo></programlisting> + + <para>If this file already exists, just copy and add to your + file the lines regarding the keyboard configuration.</para> + + <para>You will have to reboot your machine to force + <application>hald</application> to read this file.</para> + + <para>It is possible to do the same configuration from an X + terminal or a script with this command line:</para> + + <screen>&prompt.user; <userinput>setxkbmap -model pc102 -layout fr</userinput></screen> + + <para>The + <filename>/usr/local/share/X11/xkb/rules/base.lst</filename> + file lists the various keyboard, layouts and options + available.</para> + </note> + + <indexterm><primary>X11 tuning</primary></indexterm> + + <para>Next, tune the <filename>xorg.conf.new</filename> + configuration file to taste. Open the file in a text editor such + as &man.emacs.1; or &man.ee.1;. First, add the + frequencies for the target system's monitor. These are usually + expressed as a horizontal and vertical synchronization rate. These + values are added to the <filename>xorg.conf.new</filename> file + under the <literal>"Monitor"</literal> section:</para> + + <programlisting>Section "Monitor" + Identifier "Monitor0" + VendorName "Monitor Vendor" + ModelName "Monitor Model" + HorizSync 30-107 + VertRefresh 48-120 +EndSection</programlisting> + + <para>The <literal>HorizSync</literal> and + <literal>VertRefresh</literal> keywords may be missing in the + configuration file. If they are, they need to be added, with + the correct horizontal synchronization rate placed after the + <literal>HorizSync</literal> keyword and the vertical + synchronization rate after the <literal>VertRefresh</literal> + keyword. In the example above the target monitor's rates were + entered.</para> + + <para>X allows DPMS (Energy Star) features to be used with capable + monitors. The &man.xset.1; program controls the time-outs and can force + standby, suspend, or off modes. If you wish to enable DPMS features + for your monitor, you must add the following line to the monitor + section:</para> + + <programlisting> + Option "DPMS"</programlisting> + + <indexterm> + <primary><filename>xorg.conf</filename></primary> + </indexterm> + + <para>While the <filename>xorg.conf.new</filename> + configuration file is still open in an editor, select + the default resolution and color depth desired. This is + defined in the <literal>"Screen"</literal> section:</para> + + <programlisting>Section "Screen" + Identifier "Screen0" + Device "Card0" + Monitor "Monitor0" + DefaultDepth 24 + SubSection "Display" + Viewport 0 0 + Depth 24 + Modes "1024x768" + EndSubSection +EndSection</programlisting> + + <para>The <literal>DefaultDepth</literal> keyword describes + the color depth to run at by default. This can be overridden + with the <option>-depth</option> command line switch to + &man.Xorg.1;. + The <literal>Modes</literal> keyword + describes the resolution to run at for the given color depth. + Note that only VESA standard modes are supported as defined by + the target system's graphics hardware. + In the example above, the default color depth is twenty-four + bits per pixel. At this color depth, the accepted resolution is + 1024 by 768 + pixels.</para> + + <para>Finally, write the configuration file and test it using + the test mode given above.</para> + + <note> + <para>One of the tools available to assist you during + troubleshooting process are the X11 log files, which contain + information on each device that the X11 server attaches to. + <application>&xorg;</application> log file names are in the format + of <filename>/var/log/Xorg.0.log</filename>. The exact name + of the log can vary from <filename>Xorg.0.log</filename> to + <filename>Xorg.8.log</filename> and so forth.</para> + </note> + + <para>If all is well, the configuration + file needs to be installed in a common location where + &man.Xorg.1; can find it. + This is typically <filename>/etc/X11/xorg.conf</filename> or + <filename>/usr/local/etc/X11/xorg.conf</filename>.</para> + + <screen>&prompt.root; <userinput>cp xorg.conf.new /etc/X11/xorg.conf</userinput></screen> + + <para>The X11 configuration process is now + complete. <application>&xorg;</application> may be now + started with the &man.startx.1; utility. + The X11 server may also be started with the use of + &man.xdm.1;.</para> + </sect2> + + <sect2> + <title>Advanced Configuration Topics</title> + + <sect3> + <title>Configuration with &intel; i810 Graphics Chipsets</title> + + <indexterm><primary>Intel i810 graphic chipset</primary></indexterm> + + <para>Configuration with &intel; i810 integrated chipsets + requires the <devicename>agpgart</devicename> + AGP programming interface for X11 + to drive the card. See the &man.agp.4; driver manual page + for more information.</para> + + <para>This will allow configuration of the hardware as any other + graphics board. Note on systems without the &man.agp.4; + driver compiled in the kernel, trying to load the module + with &man.kldload.8; will not work. This driver has to be + in the kernel at boot time through being compiled in or + using <filename>/boot/loader.conf</filename>.</para> + </sect3> + + <sect3> + <title>Adding a Widescreen Flatpanel to the Mix</title> + + <indexterm><primary>widescreen flatpanel configuration</primary></indexterm> + + <para>This section assumes a bit of advanced configuration knowledge. + If attempts to use the standard configuration tools above have not + resulted in a working configuration, there is information enough + in the log files to be of use in getting the setup working. + Use of a text editor will be necessary.</para> + + <para>Current widescreen (WSXGA, WSXGA+, WUXGA, WXGA, WXGA+, et.al.) + formats support 16:10 and 10:9 formats or aspect ratios that can + be problematic. Examples of some common screen resolutions for + 16:10 aspect ratios are:</para> + + <itemizedlist> + <listitem><para>2560x1600</para></listitem> + <listitem><para>1920x1200</para></listitem> + <listitem><para>1680x1050</para></listitem> + <listitem><para>1440x900</para></listitem> + <listitem><para>1280x800</para></listitem> + </itemizedlist> + + <para>At some point, it will be as easy as adding one of these + resolutions as a possible <literal>Mode</literal> in the <literal>Section + "Screen"</literal> as such:</para> + + <programlisting>Section "Screen" +Identifier "Screen0" +Device "Card0" +Monitor "Monitor0" +DefaultDepth 24 +SubSection "Display" + Viewport 0 0 + Depth 24 + Modes "1680x1050" +EndSubSection +EndSection</programlisting> + + <para><application>&xorg;</application> is smart enough to pull the + resolution information from the widescreen via I2C/DDC information + so it knows what the monitor can handle as far as frequencies + and resolutions.</para> + + <para>If those <literal>ModeLines</literal> do not exist in the drivers, + one might need to give <application>&xorg;</application> a little hint. + Using <filename>/var/log/Xorg.0.log</filename> one can extract + enough information to manually create a <literal>ModeLine</literal> that + will work. Simply look for information resembling this:</para> + + <programlisting>(II) MGA(0): Supported additional Video Mode: +(II) MGA(0): clock: 146.2 MHz Image Size: 433 x 271 mm +(II) MGA(0): h_active: 1680 h_sync: 1784 h_sync_end 1960 h_blank_end 2240 h_border: 0 +(II) MGA(0): v_active: 1050 v_sync: 1053 v_sync_end 1059 v_blanking: 1089 v_border: 0 +(II) MGA(0): Ranges: V min: 48 V max: 85 Hz, H min: 30 H max: 94 kHz, PixClock max 170 MHz</programlisting> + + <para>This information is called EDID information. Creating a + <literal>ModeLine</literal> from this is just a matter of putting the + numbers in the correct order:</para> + + <programlisting>ModeLine <name> <clock> <4 horiz. timings> <4 vert. timings></programlisting> + + <para>So that the <literal>ModeLine</literal> in <literal>Section "Monitor"</literal> + for this example would look like this:</para> + + <programlisting>Section "Monitor" +Identifier "Monitor1" +VendorName "Bigname" +ModelName "BestModel" +ModeLine "1680x1050" 146.2 1680 1784 1960 2240 1050 1053 1059 1089 +Option "DPMS" +EndSection</programlisting> + + <para>Now having completed these simple editing steps, X should start + on your new widescreen monitor.</para> + </sect3> + </sect2> + </sect1> + + <sect1 id="x-fonts"> + <sect1info> + <authorgroup> + <author> + <firstname>Murray</firstname> + <surname>Stokely</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>Using Fonts in X11</title> + + <sect2 id="type1"> + <title>Type1 Fonts</title> + <para>The default fonts that ship with + X11 are less than ideal for typical + desktop publishing applications. Large presentation fonts show up + jagged and unprofessional looking, and small fonts in + <application>&netscape;</application> are almost completely unintelligible. + However, there are several free, high quality Type1 (&postscript;) fonts + available which can be readily used + with X11. For instance, the URW font collection + (<filename role="package">x11-fonts/urwfonts</filename>) includes + high quality versions of standard type1 fonts (<trademark class="registered">Times Roman</trademark>, + <trademark class="registered">Helvetica</trademark>, <trademark class="registered">Palatino</trademark> and others). The Freefonts collection + (<filename role="package">x11-fonts/freefonts</filename>) includes + many more fonts, but most of them are intended for use in + graphics software such as the <application>Gimp</application>, and are not + complete enough to serve as screen fonts. In addition, + X11 can be configured to use + &truetype; fonts with a minimum of effort. For more details on + this, see the &man.X.7; manual page or the + <link linkend="truetype">section on &truetype; fonts</link>.</para> + + <para>To install the above Type1 font collections from the + Ports Collection, run the following commands:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/x11-fonts/urwfonts</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>And likewise with the freefont or other collections. To have the X + server detect these fonts, add an appropriate line to the + X server configuration file (<filename>/etc/X11/xorg.conf</filename>), + which reads:</para> + + <programlisting>FontPath "/usr/local/lib/X11/fonts/URW/"</programlisting> + + <para>Alternatively, at the command line in the X session + run:</para> + + <screen>&prompt.user; <userinput>xset fp+ /usr/local/lib/X11/fonts/URW</userinput> +&prompt.user; <userinput>xset fp rehash</userinput></screen> + + <para>This will work but will be lost when the X session is closed, + unless it is added to the startup file (<filename>~/.xinitrc</filename> + for a normal <command>startx</command> session, + or <filename>~/.xsession</filename> when logging in through a + graphical login manager like <application>XDM</application>). + A third way is to use the new + <filename>/usr/local/etc/fonts/local.conf</filename> file: see the + section on <link linkend="antialias">anti-aliasing</link>.</para> + </sect2> + + <sect2 id="truetype"> + <title>&truetype; Fonts</title> + + <indexterm><primary>TrueType Fonts</primary></indexterm> + <indexterm><primary>fonts</primary> + <secondary>TrueType</secondary> + </indexterm> + + <para><application>&xorg;</application> has built in support + for rendering &truetype; fonts. There are two different modules + that can enable this functionality. The freetype module is used + in this example because it is more consistent with the other font + rendering back-ends. To enable the freetype module just add the + following line to the <literal>"Module"</literal> section of the + <filename>/etc/X11/xorg.conf</filename> file.</para> + + <programlisting>Load "freetype"</programlisting> + + <para>Now make a directory for the &truetype; fonts (for example, + <filename>/usr/local/lib/X11/fonts/TrueType</filename>) + and copy all of the &truetype; fonts into this directory. Keep in + mind that &truetype; fonts cannot be directly taken from a + &macintosh;; they must be in &unix;/&ms-dos;/&windows; format for use by + X11. Once the files have been + copied into this directory, use + <application>ttmkfdir</application> to create a + <filename>fonts.dir</filename> file, so that the X font renderer + knows that these new files have been installed. + <command>ttmkfdir</command> is available from the FreeBSD + Ports Collection as + <filename role="package">x11-fonts/ttmkfdir</filename>.</para> + + <screen>&prompt.root; <userinput>cd /usr/local/lib/X11/fonts/TrueType</userinput> +&prompt.root; <userinput>ttmkfdir -o fonts.dir</userinput></screen> + + <para>Now add the &truetype; directory to the font + path. This is just the same as described above for <link + linkend="type1">Type1</link> fonts, that is, use</para> + + <screen>&prompt.user; <userinput>xset fp+ /usr/local/lib/X11/fonts/TrueType</userinput> +&prompt.user; <userinput>xset fp rehash</userinput></screen> + + <para>or add a <literal>FontPath</literal> line to the + <filename>xorg.conf</filename> file.</para> + + <para>That's it. Now <application>&netscape;</application>, + <application>Gimp</application>, + <application>&staroffice;</application>, and all of the other X + applications should now recognize the installed &truetype; + fonts. Extremely small fonts (as with text in a high resolution + display on a web page) and extremely large fonts (within + <application>&staroffice;</application>) will look much better + now.</para> + </sect2> + + <sect2 id="antialias"> + <sect2info> + <authorgroup> + <author> + <firstname>Joe Marcus</firstname> + <surname>Clarke</surname> + <contrib>Updated by </contrib> + <!-- May 2003 --> + </author> + </authorgroup> + </sect2info> + <title>Anti-Aliased Fonts</title> + + <indexterm><primary>anti-aliased fonts</primary></indexterm> + <indexterm><primary>fonts</primary> + <secondary>anti-aliased</secondary></indexterm> + + <para>All fonts in X11 that are found + in <filename>/usr/local/lib/X11/fonts/</filename> and + <filename>~/.fonts/</filename> are automatically + made available for anti-aliasing to Xft-aware applications. + Most recent applications are Xft-aware, including + <application>KDE</application>, <application>GNOME</application>, and + <application>Firefox</application>.</para> + + <para>In order to control which fonts are anti-aliased, or to + configure anti-aliasing properties, create (or edit, if it + already exists) the file + <filename>/usr/local/etc/fonts/local.conf</filename>. Several + advanced features of the Xft font system can be tuned using + this file; this section describes only some simple + possibilities. For more details, please see + &man.fonts-conf.5;.</para> + + <indexterm><primary>XML</primary></indexterm> + + <para>This file must be in XML format. Pay careful attention to + case, and make sure all tags are properly closed. The file + begins with the usual XML header followed by a DOCTYPE + definition, and then the <literal><fontconfig></literal> tag:</para> + + <programlisting> + <?xml version="1.0"?> + <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> + <fontconfig> + </programlisting> + + <para>As previously stated, all fonts in + <filename>/usr/local/lib/X11/fonts/</filename> as well as + <filename>~/.fonts/</filename> are already made available to + Xft-aware applications. If you wish to add another directory + outside of these two directory trees, add a line similar to the + following to + <filename>/usr/local/etc/fonts/local.conf</filename>:</para> + + <programlisting><dir>/path/to/my/fonts</dir></programlisting> + + <para>After adding new fonts, and especially new font directories, + you should run the following command to rebuild the font + caches:</para> + + <screen>&prompt.root; <userinput>fc-cache -f</userinput></screen> + + <para>Anti-aliasing makes borders slightly fuzzy, which makes very + small text more readable and removes <quote>staircases</quote> from + large text, but can cause eyestrain if applied to normal text. To + exclude font sizes smaller than 14 point from anti-aliasing, include + these lines:</para> + + <programlisting> <match target="font"> + <test name="size" compare="less"> + <double>14</double> + </test> + <edit name="antialias" mode="assign"> + <bool>false</bool> + </edit> + </match> + <match target="font"> + <test name="pixelsize" compare="less" qual="any"> + <double>14</double> + </test> + <edit mode="assign" name="antialias"> + <bool>false</bool> + </edit> + </match></programlisting> + + <indexterm><primary>fonts</primary> + <secondary>spacing</secondary></indexterm> + + <para>Spacing for some monospaced fonts may also be inappropriate + with anti-aliasing. This seems to be an issue with + <application>KDE</application>, in particular. One possible fix for + this is to force the spacing for such fonts to be 100. Add the + following lines:</para> + + <programlisting> <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>fixed</string> + </test> + <edit name="family" mode="assign"> + <string>mono</string> + </edit> + </match> + <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>console</string> + </test> + <edit name="family" mode="assign"> + <string>mono</string> + </edit> + </match></programlisting> + + <para>(this aliases the other common names for fixed fonts as + <literal>"mono"</literal>), and then add:</para> + + <programlisting> <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>mono</string> + </test> + <edit name="spacing" mode="assign"> + <int>100</int> + </edit> + </match> </programlisting> + + <para>Certain fonts, such as Helvetica, may have a problem when + anti-aliased. Usually this manifests itself as a font that + seems cut in half vertically. At worst, it may cause + applications to + crash. To avoid this, consider adding the following to + <filename>local.conf</filename>:</para> + + <programlisting> <match target="pattern" name="family"> + <test qual="any" name="family"> + <string>Helvetica</string> + </test> + <edit name="family" mode="assign"> + <string>sans-serif</string> + </edit> + </match> </programlisting> + + <para>Once you have finished editing + <filename>local.conf</filename> make sure you end the file + with the <literal></fontconfig></literal> tag. Not doing this will cause + your changes to be ignored.</para> + + <para>Finally, users can add their own settings via their personal + <filename>.fonts.conf</filename> files. To do this, each user should + simply create a <filename>~/.fonts.conf</filename>. This file must + also be in XML format.</para> + + <indexterm><primary>LCD screen</primary></indexterm> + <indexterm><primary>Fonts</primary> + <secondary>LCD screen</secondary></indexterm> + + <para>One last point: with an LCD screen, sub-pixel sampling may be + desired. This basically treats the (horizontally separated) + red, green and blue components separately to improve the horizontal + resolution; the results can be dramatic. To enable this, add the + line somewhere in the <filename>local.conf</filename> file:</para> + + <programlisting> + <match target="font"> + <test qual="all" name="rgba"> + <const>unknown</const> + </test> + <edit name="rgba" mode="assign"> + <const>rgb</const> + </edit> + </match> + </programlisting> + + <note> + <para>Depending on the sort of display, + <literal>rgb</literal> may need to be changed to <literal>bgr</literal>, + <literal>vrgb</literal> or <literal>vbgr</literal>: experiment and + see which works best.</para> + </note> + </sect2> + </sect1> + + <sect1 id="x-xdm"> + <sect1info> + <authorgroup> + <author> + <firstname>Seth</firstname> + <surname>Kingsley</surname> + <contrib>Contributed by </contrib> + </author> + </authorgroup> + </sect1info> + <title>The X Display Manager</title> + <sect2> + <title>Overview</title> + + <indexterm><primary>X Display Manager</primary></indexterm> + <para>The X Display Manager (<application>XDM</application>) is + an optional part of the X Window System that is used for login + session management. This is useful for several types of + situations, including minimal <quote>X Terminals</quote>, + desktops, and large network display + servers. Since the X Window System is network and protocol + independent, there are a wide variety of possible configurations + for running X clients and servers on different machines + connected by a network. <application>XDM</application> provides + a graphical interface for choosing which display server to + connect to, and entering authorization information such as a + login and password combination.</para> + + <para>Think of <application>XDM</application> as + providing the same functionality to the user as the + &man.getty.8; utility (see <xref linkend="term-config"> for + details). That is, it performs system logins to the display + being connected to and then runs a session manager on behalf of + the user (usually an X window + manager). <application>XDM</application> then waits for this + program to exit, signaling that the user is done and should be + logged out of the display. At this point, + <application>XDM</application> can display the login and display + chooser screens for the next user to login.</para> + </sect2> + + <sect2> + <title>Using XDM</title> + + <para>To start using <application>XDM</application>, install the + <filename role="package">x11/xdm</filename> port (it is not + installed by default in recent versions of + <application>&xorg;</application>). + The <application>XDM</application> daemon program may then be + found in <filename>/usr/local/bin/xdm</filename>. This program + can be run at any time as <username>root</username> and it will + start managing the X display on the local machine. If + <application>XDM</application> is to be run every + time the machine boots up, a convenient way to do this is by + adding an entry to <filename>/etc/ttys</filename>. For more + information about the format and usage of this file, see <xref + linkend="term-etcttys">. There is a line in the default + <filename>/etc/ttys</filename> file for running the + <application>XDM</application> daemon on a virtual terminal:</para> + + <screen>ttyv8 "/usr/local/bin/xdm -nodaemon" xterm off secure</screen> + + <para>By default this entry is disabled; in order to enable it + change field 5 from <literal>off</literal> to + <literal>on</literal> and restart &man.init.8; using the + directions in <xref linkend="term-hup">. The first field, the + name of the terminal this program will manage, is + <literal>ttyv8</literal>. This means that + <application>XDM</application> will start running on the 9th + virtual terminal.</para> + </sect2> + + <sect2> + <title>Configuring XDM</title> + + <para>The <application>XDM</application> configuration directory + is located in <filename>/usr/local/lib/X11/xdm</filename>. In + this directory there are several files used to change the + behavior and appearance of + <application>XDM</application>. Typically these files will + be found:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>File</entry> + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry><filename>Xaccess</filename></entry> + <entry>Client authorization ruleset.</entry> + </row> + + <row> + <entry><filename>Xresources</filename></entry> + <entry>Default X resource values.</entry> + </row> + + <row> + <entry><filename>Xservers</filename></entry> + <entry>List of remote and local displays to manage.</entry> + </row> + + <row> + <entry><filename>Xsession</filename></entry> + <entry>Default session script for logins.</entry> + </row> + + <row> + <entry><filename>Xsetup_</filename>*</entry> + <entry>Script to launch applications before the login + interface.</entry> + </row> + + <row> + <entry><filename>xdm-config</filename></entry> + <entry>Global configuration for all displays running on + this machine.</entry> + </row> + + <row> + <entry><filename>xdm-errors</filename></entry> + <entry>Errors generated by the server program.</entry> + </row> + + <row> + <entry><filename>xdm-pid</filename></entry> + <entry>The process ID of the currently running XDM.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Also in this directory are a few scripts and programs used + to set up the desktop when <application>XDM</application> is + running. The purpose of each of these files will be briefly + described. The exact syntax and usage of all of these files is + described in &man.xdm.1;.</para> + + <para>The default configuration is a simple rectangular login + window with the hostname of the machine displayed at the top in + a large font and <quote>Login:</quote> and + <quote>Password:</quote> prompts below. This is a good starting + point for changing the look and feel of + <application>XDM</application> screens.</para> + + <sect3> + <title>Xaccess</title> + + <para>The protocol for connecting to + <application>XDM</application>-controlled displays is called + the X Display Manager Connection Protocol (XDMCP). This file + is a ruleset for controlling XDMCP connections from remote + machines. It is ignored unless the <filename>xdm-config</filename> + is changed to listen for remote connections. By default, it does + not allow any clients to connect.</para> + </sect3> + + <sect3> + <title>Xresources</title> + <para>This is an application-defaults file for the display + chooser and login screens. In it, the appearance + of the login program can be modified. The format is identical + to the app-defaults file described in the + X11 documentation.</para> + </sect3> + + <sect3> + <title>Xservers</title> + <para>This is a list of the remote displays the chooser should + provide as choices.</para> + </sect3> + + <sect3> + <title>Xsession</title> + <para>This is the default session script for + <application>XDM</application> to run after a user has logged + in. Normally each user will have a customized session script + in <filename>~/.xsession</filename> that overrides this + script.</para> + </sect3> + + <sect3> + <title>Xsetup_*</title> + <para>These will be run automatically before displaying the + chooser or login interfaces. There is a script for each + display being used, named <filename>Xsetup_</filename> followed + by the local display number (for instance + <filename>Xsetup_0</filename>). Typically these scripts will + run one or two programs in the background such as + <command>xconsole</command>.</para> + </sect3> + + <sect3> + <title>xdm-config</title> + <para>This contains settings in the form of app-defaults + that are applicable to every display that this installation + manages.</para> + </sect3> + + <sect3> + <title>xdm-errors</title> + <para>This contains the output of the X servers that + <application>XDM</application> is trying to run. If a display + that <application>XDM</application> is trying to start hangs + for some reason, this is a good place to look for error + messages. These messages are also written to the user's + <filename>~/.xsession-errors</filename> file on a per-session + basis.</para> + </sect3> + </sect2> + + <sect2> + <title>Running a Network Display Server</title> + + <para>In order for other clients to connect to the display + server, you must edit the access control rules and enable the connection + listener. By default these are set to conservative values. + To make <application>XDM</application> listen for connections, + first comment out a line in the <filename>xdm-config</filename> + file:</para> + + <screen>! SECURITY: do not listen for XDMCP or Chooser requests +! Comment out this line if you want to manage X terminals with xdm +DisplayManager.requestPort: 0</screen> + + <para>and then restart <application>XDM</application>. Remember that + comments in app-defaults files begin with a <quote>!</quote> + character, not the usual <quote>#</quote>. More strict + access controls may be desired — look at the example + entries in <filename>Xaccess</filename>, and refer to the + &man.xdm.1; manual page for further information.</para> + </sect2> + + <sect2> + <title>Replacements for XDM</title> + + <para>Several replacements for the default + <application>XDM</application> program exist. One of them, + <application>KDM</application> (bundled with + <application>KDE</application>) is described later in this + chapter. The <application>KDM</application> display manager offers many visual + improvements and cosmetic frills, as well as the + functionality to allow users to choose their window manager + of choice at login time.</para> + </sect2> + </sect1> + + <sect1 id="x11-wm"> + <sect1info> + <authorgroup> + <author> + <firstname>Valentino</firstname> + <surname>Vaschetto</surname> + <contrib>Contributed by </contrib> + </author> + <!-- June 2001 --> + </authorgroup> + </sect1info> + + <title>Desktop Environments</title> + + <para>This section describes the different desktop environments + available for X on FreeBSD. A <quote>desktop environment</quote> + can mean anything ranging from a simple window manager to a + complete suite of desktop applications, such as + <application>KDE</application> or <application>GNOME</application>.</para> + + <sect2 id="x11-wm-gnome"> + <title>GNOME</title> + + <sect3 id="x11-wm-gnome-about"> + <title>About GNOME</title> + + <indexterm><primary>GNOME</primary></indexterm> + <para><application>GNOME</application> is a user-friendly + desktop environment that enables users to easily use and + configure their computers. <application>GNOME</application> + includes a panel (for starting applications and displaying + status), a desktop (where data and applications can be + placed), a set of standard desktop tools and applications, and + a set of conventions that make it easy for applications to + cooperate and be consistent with each other. Users of other + operating systems or environments should feel right at home + using the powerful graphics-driven environment that + <application>GNOME</application> provides. More + information regarding <application>GNOME</application> on + FreeBSD can be found on the <ulink + url="http://www.FreeBSD.org/gnome">FreeBSD GNOME + Project</ulink>'s web site. The web site also contains fairly + comprehensive FAQs about installing, configuring, and managing + <application>GNOME</application>.</para> + </sect3> + + <sect3 id="x11-wm-gnome-install"> + <title>Installing GNOME</title> + + <para>The software can be easily installed from a package or the + Ports Collection:</para> + + <para>To install the <application>GNOME</application> package + from the network, simply type:</para> + + <screen>&prompt.root; <userinput>pkg_add -r gnome2</userinput></screen> + + <para>To build <application>GNOME</application> from source, use + the ports tree:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/x11/gnome2</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>For proper operation, <application>GNOME</application> requires + the <filename>/proc</filename> filesystem to be mounted. Add</para> + + <programlisting>proc /proc procfs rw 0 0</programlisting> + + <para>to <filename>/etc/fstab</filename> to mount + &man.procfs.5; automatically during + startup.</para> + + <para>Once <application>GNOME</application> is installed, + the X server must be told to start + <application>GNOME</application> instead of a default window + manager.</para> + + <para>The easiest way to start + <application>GNOME</application> is with + <application>GDM</application>, the GNOME Display Manager. + <application>GDM</application> is installed as part + of the <application>GNOME</application> desktop, although + it is disabled by default. It can be enabled by adding this + line to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>gdm_enable="YES"</programlisting> + + <para>Once you have rebooted, + <application>GDM</application> will start automatically.</para> + + <para>It is often desirable to start all + <application>GNOME</application> services together with + <application>GDM</application>. To achieve this, add the + following line to <filename>/etc/rc.conf</filename>:</para> + + <programlisting>gnome_enable="YES"</programlisting> + + <para><application>GNOME</application> may also be started + from the command-line by properly configuring a file named + <filename>.xinitrc</filename>. + If a custom <filename>.xinitrc</filename> is already in + place, simply replace the line that starts the current window + manager with one that starts + <application>/usr/local/bin/gnome-session</application> instead. + If nothing special has been done to the configuration file, + then it is enough simply to type:</para> + + <screen>&prompt.user; <userinput>echo "/usr/local/bin/gnome-session" > ~/.xinitrc</userinput></screen> + + <para>Next, type <command>startx</command>, and the + <application>GNOME</application> desktop environment will be + started.</para> + + <note><para>If an older display manager, like + <application>XDM</application>, is being used, this will not work. + Instead, create an executable <filename>.xsession</filename> + file with the same command in it. To do this, edit the file + and replace the existing window manager command with + <application>/usr/local/bin/gnome-session</application>: + </para></note> + + <screen>&prompt.user; <userinput>echo "#!/bin/sh" > ~/.xsession</userinput> +&prompt.user; <userinput>echo "/usr/local/bin/gnome-session" >> ~/.xsession</userinput> +&prompt.user; <userinput>chmod +x ~/.xsession</userinput></screen> + + <para>Yet another option is to configure the display manager to + allow choosing the window manager at login time; the section on + <link linkend="x11-wm-kde-details">KDE details</link> + explains how to do this for <application>KDM</application>, the + display manager of <application>KDE</application>.</para> + </sect3> + </sect2> + + <sect2 id="x11-wm-kde"> + <title>KDE</title> + + <indexterm><primary>KDE</primary></indexterm> + <sect3 id="x11-wm-kde-about"> + <title>About KDE</title> + + <para><application>KDE</application> is an easy to use + contemporary desktop environment. Some of the things that + <application>KDE</application> brings to the user are:</para> + + <itemizedlist> + <listitem> + <para>A beautiful contemporary desktop</para> + </listitem> + + <listitem> + <para>A desktop exhibiting complete network transparency</para> + </listitem> + + <listitem> + <para>An integrated help system allowing for convenient, + consistent access to help on the use of the + <application>KDE</application> desktop and its + applications</para> + </listitem> + + <listitem> + <para>Consistent look and feel of all + <application>KDE</application> applications</para> + </listitem> + + <listitem> + <para>Standardized menu and toolbars, keybindings, color-schemes, + etc.</para> + </listitem> + + <listitem> + <para>Internationalization: <application>KDE</application> + is available in more than 55 languages</para> + </listitem> + + <listitem> + <para>Centralized, consistent, dialog-driven desktop + configuration</para> + </listitem> + + <listitem> + <para>A great number of useful + <application>KDE</application> applications</para> + </listitem> + </itemizedlist> + + <para><application>KDE</application> comes with a web browser called + <application>Konqueror</application>, which is + a solid competitor to other existing web browsers on &unix; + systems. More information on <application>KDE</application> + can be found on the <ulink url="http://www.kde.org/">KDE + website</ulink>. For FreeBSD specific information and + resources on <application>KDE</application>, consult + the <ulink url="http://freebsd.kde.org/">KDE/FreeBSD + initiative</ulink>'s website.</para> + + <para>There are two versions of <application>KDE</application> + available on FreeBSD. Version 3 has been around for a long + time, and is still available in the Ports Collection though + it's now unmaintained and partially broken. Version 4 is + punctually updated and is the default choice for + <application>KDE</application> users. They can even be + installed side by side.</para> + </sect3> + + <sect3 id="x11-wm-kde-install"> + <title>Installing KDE</title> + + <para>Just as with <application>GNOME</application> or any + other desktop environment, the software can be easily installed + from a package or the Ports Collection:</para> + + <para>To install the <application>KDE 3</application> package + from the network, type:</para> + + <screen>&prompt.root; <userinput>pkg_add -r kde</userinput></screen> + + <para>To install the <application>KDE 4</application> package + from the network, type:</para> + + <screen>&prompt.root; <userinput>pkg_add -r kde4</userinput></screen> + + <para>&man.pkg.add.1; will automatically fetch the latest version + of the application.</para> + + <para>To build <application>KDE 3</application> from source, + use the ports tree:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde3</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>To build <application>KDE 4</application> from source, + use the ports tree:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/x11/kde4</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>After <application>KDE</application> has been installed, + the X server must be told to launch this application + instead of the default window manager. This is accomplished + by editing the <filename>.xinitrc</filename> file:</para> + + <para>For <application>KDE 3</application>:</para> + + <screen>&prompt.user; <userinput>echo "exec startkde" > ~/.xinitrc</userinput></screen> + + <para>For <application>KDE 4</application>:</para> + + <screen>&prompt.user; <userinput>echo "exec /usr/local/kde4/bin/startkde" > ~/.xinitrc</userinput></screen> + + <para>Now, whenever the X Window System is invoked with + <command>startx</command>, + <application>KDE</application> will be the desktop.</para> + + <para>If a display manager such as + <application>XDM</application> is being used, the + configuration is slightly different. Edit the + <filename>.xsession</filename> file instead. Instructions + for <application>KDM</application> are described later in + this chapter.</para> + </sect3> + </sect2> + + <sect2 id="x11-wm-kde-details"> + <title>More Details on KDE</title> + + <para>Now that <application>KDE</application> is installed on + the system, most things can be discovered through the + help pages, or just by pointing and clicking at various menus. + &windows; or &mac; users will feel quite at home.</para> + + <para>The best reference for <application>KDE</application> is + the on-line documentation. <application>KDE</application> + comes with its own web browser, + <application>Konqueror</application>, dozens of useful + applications, and extensive documentation. The remainder of + this section discusses the technical items that are + difficult to learn by random exploration.</para> + + <sect3 id="x11-wm-kde-kdm"> + <title>The KDE Display Manager</title> + + <indexterm><primary>KDE</primary> + <secondary>display manager</secondary></indexterm> + <para>An administrator of a multi-user system may wish to have + a graphical login screen to welcome users. + <link linkend="x-xdm">XDM</link> can be + used, as described earlier. However, + <application>KDE</application> includes an + alternative, <application>KDM</application>, which is designed + to look more attractive and include more login-time options. + In particular, users can easily choose (via a menu) which + desktop environment (<application>KDE</application>, + <application>GNOME</application>, or something else) to run + after logging on.</para> + + <para>To enable <application>KDM</application>, different files + need to be edited depending on the version of + <application>KDE</application>.</para> + + <para>For <application>KDE 3</application>, the <literal>ttyv8</literal> + entry in <filename>/etc/ttys</filename> has to be adapted as + follows:</para> + + <programlisting>ttyv8 "/usr/local/bin/kdm -nodaemon" xterm on secure</programlisting> + + <para>For <application>KDE 4</application>, you have to mount + &man.procfs.5; and add the following line to + <filename>/etc/rc.conf</filename>:</para> + + <programlisting>kdm4_enable="YES"</programlisting> + </sect3> + + </sect2> + + <sect2 id="x11-wm-xfce"> + <title>Xfce</title> + <sect3 id="x11-wm-xfce-about"> + <title>About Xfce</title> + + <para><application>Xfce</application> is a desktop environment + based on the GTK+ + toolkit used by <application>GNOME</application>, but is much + more lightweight and meant for those who want a simple, + efficient desktop which is nevertheless easy to use and + configure. Visually, it looks very much like + <application>CDE</application>, found on commercial &unix; + systems. Some of <application>Xfce</application>'s features + are:</para> + + <itemizedlist> + <listitem> + <para>A simple, easy-to-handle desktop</para> + </listitem> + + <listitem> + <para>Fully configurable via mouse, with drag and + drop, etc.</para> + </listitem> + + <listitem> + <para>Main panel similar to <application>CDE</application>, with + menus, applets and applications launchers</para> + </listitem> + + <listitem> + <para>Integrated window manager, file manager, sound manager, + <application>GNOME</application> compliance module, and more</para> + </listitem> + + <listitem> + <para>Themeable (since it uses GTK+)</para> + </listitem> + + <listitem> + <para>Fast, light and efficient: ideal for older/slower machines + or machines with memory limitations</para> + </listitem> + </itemizedlist> + + <para>More information on <application>Xfce</application> + can be found on the <ulink url="http://www.xfce.org/">Xfce + website</ulink>.</para> + </sect3> + + <sect3 id="x11-wm-xfce-install"> + <title>Installing Xfce</title> + + <para>A binary package for <application>Xfce</application> + exists (at the time of writing). To install, simply type:</para> + + <screen>&prompt.root; <userinput>pkg_add -r xfce4</userinput></screen> + + <para>Alternatively, to build from source, use the + Ports Collection:</para> + + <screen>&prompt.root; <userinput>cd /usr/ports/x11-wm/xfce4</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> + + <para>Now, tell the X server to launch + <application>Xfce</application> the next time X is started. + Simply type this:</para> + + <screen>&prompt.user; <userinput>echo "/usr/local/bin/startxfce4" > ~/.xinitrc</userinput></screen> + + <para>The next time X is started, + <application>Xfce</application> will be the desktop. + As before, if a display manager like + <application>XDM</application> is being used, create an + <filename>.xsession</filename>, as described in the + section on <link linkend="x11-wm-gnome">GNOME</link>, but + with the <filename>/usr/local/bin/startxfce4</filename> + command; or, configure the display manager to allow + choosing a desktop at login time, as explained in + the section on <link linkend="x11-wm-kde-kdm">kdm</link>.</para> + </sect3> + </sect2> + </sect1> + +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> |