diff --git a/en_US.ISO8859-1/books/handbook/desktop/chapter.xml b/en_US.ISO8859-1/books/handbook/desktop/chapter.xml index 9f1a2f8857..ac7256323f 100644 --- a/en_US.ISO8859-1/books/handbook/desktop/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/desktop/chapter.xml @@ -1,1269 +1,1271 @@ + + + --> Desktop Applications Synopsis While &os; is popular as a server for its performance and stability, it is also suited for day-to-day use as a desktop. With over &os.numports; applications available as &os; packages or ports, it is easy to build a customized desktop that runs a wide variety of desktop applications. This chapter demonstrates how to install some popular desktop applications using packages or the &os; Ports Collection. Users who prefer to install a pre-built desktop version of FreeBSD rather than configuring one from scratch should refer to the pcbsd.org website. As &os; features &linux; binary compatibility, many applications developed for &linux; can be installed on a &os; desktop. Many of the ports using &linux; binary compatibility start with linux-. This chapter assumes that &linux; binary compatibility has been enabled before any &linux; applications are installed. This chapter demonstrates how to install the following desktop applications: Type of Application Application Name Package Name Ports Name Browser Firefox firefox www/firefox Browser Opera opera www/opera Browser Konqueror kde4-baseapps x11/kde4-baseapps Browser Chromium chromium www/chromium Productivity Calligra calligra editors/calligra Productivity AbiWord abiword editors/abiword Productivity The GIMP gimp graphics/gimp Productivity Apache OpenOffice openoffice editors/openoffice-4 Productivity LibreOffice libreoffice editors/libreoffice Document Viewer &acrobat.reader; no package due to license restriction print/acroread9 Document Viewer gv gv print/gv Document Viewer Xpdf xpdf graphics/xpdf Document Viewer GQview gqview graphics/gqview Finance GnuCash gnucash finance/gnucash Finance Gnumeric gnumeric math/gnumeric Finance KMyMoney kmymoney-kde4 finance/kmymoney-kde4 Before reading this chapter, you should know how to: Install additional software using packages or ports as described in . Install X and a window manager as described in . Enable &linux; binary compatibility as described in . For information on how to configure a multimedia environment, refer to . Browsers browsers web &os; does not come with a pre-installed web browser. Instead, the www category of the Ports Collection contains many browsers which can be installed as a package or compiled from the Ports Collection. The KDE and GNOME desktop environments include their own HTML browser. Refer to for more information on how to set up these complete desktops. Some light-weight browsers include www/dillo2, www/links, and www/w3m. This section demonstrates how to install the following popular web browsers and indicates if the application is resource-heavy, takes time to compile from ports, or has any major dependencies. Application Name Resources Needed Installation from Ports Notes Firefox medium heavy &os;, &linux;, and localized versions are available Opera light light &os; and &linux; versions are available Konqueror medium heavy Requires KDE libraries Chromium medium heavy Requires Gtk+ Firefox Firefox Firefox is an open source browser that is fully ported to &os;. It features a standards-compliant HTML display engine, tabbed browsing, popup blocking, extensions, improved security, and more. Firefox is based on the Mozilla codebase. To install the package of the latest release version of Firefox, type: &prompt.root; pkg_add -r firefox To instead install Firefox Extended Support Release (ESR) version, use: &prompt.root; pkg_add -r firefox-esr Localized versions are available in www/firefox-i18n and www/firefox-esr-i18n. The Ports Collection can instead be used to compile the desired version of Firefox from source code. This example builds www/firefox, where firefox can be replaced with the ESR or localized version to install. &prompt.root; cd /usr/ports/www/firefox &prompt.root; make install clean Firefox and &java; Plugin The installation of Firefox does not include &java; support. However, java/icedtea-web provides a free software web browser plugin for running Java applets. It can be installed as a package. To alternately compile the port: &prompt.root; cd /usr/ports/java/icedtea-web &prompt.root; make install clean Keep the default configuration options when compiling the port. Once installed, start firefox, enter about:plugins in the location bar and press Enter. A page listing the installed plugins will be displayed. The &java; plugin should be listed. If the browser is unable to find the plugin, each user will have to run the following command and relaunch the browser: &prompt.user; ln -s /usr/local/lib/IcedTeaPlugin.so \ $HOME/.mozilla/plugins/ Firefox and &adobe; &flash; Plugin Flash A native &adobe; &flash; plugin is not available for &os;. However, a software wrapper for running the &linux; version of the plugin is available. This wrapper also provides support for other browser plugins such as &realplayer;. To install and enable this plugin, perform these steps: Install the www/nspluginwrapper port. Due to licensing restrictions, a package is not available. This port requires emulators/linux_base-f10 which is a large port. Install the www/linux-f10-flashplugin11 port. Due to licensing restrictions, a package is not available. &prompt.root; ln -s /usr/local/lib/npapi/linux-f10-flashplugin/libflashplayer.so \ /usr/local/lib/browser_plugins/ Create the /usr/local/lib/browser_plugins directory if it is not already present. Before the plugin is first used, each user must run: &prompt.user; nspluginwrapper -v -a -i When the plugin port has been updated and reinstalled, each user must run: &prompt.user; nspluginwrapper -v -a -u Start the browser, enter about:plugins in the location bar and press Enter. A list of all the currently available plugins will be shown. Firefox and Swfdec &flash; Plugin Swfdec is a decoder and renderer for &flash; animations. Swfdec-Mozilla is a plugin for Firefox browsers that uses the Swfdec library for playing SWF files. To install the package: &prompt.root; pkg_add -r swfdec-plugin If the package is not available, compile and install it from the Ports Collection: &prompt.root; cd /usr/ports/www/swfdec-plugin &prompt.root; make install clean Restart the browser to activate this plugin. Opera Opera Opera is a full-featured and standards-compliant browser which is still lightweight and fast. It comes with a built-in mail and news reader, an IRC client, an RSS/Atom feeds reader, and more. It is available as a native &os; version and as a version that runs under &linux; emulation. This command installs the package of the &os; version of Opera. Replace opera with linux-opera to instead install the &linux; version. &prompt.root; pkg_add -r opera Alternately, install either version through the Ports Collection. This example compiles the native version: &prompt.root; cd /usr/ports/www/opera &prompt.root; make install clean To install the &linux; version, substitute linux-opera in place of opera. To install &adobe; &flash; plugin support, first compile the www/linux-f10-flashplugin11 port, as a package is not available due to licensing restrictions. Then install either the www/opera-linuxplugins port or package. This example compiles both applications from ports: &prompt.root; cd /usr/ports/www/linux-f10-flashplugin11 &prompt.root; make install clean &prompt.root; cd /usr/ports/www/opera-linuxplugins &prompt.root; make install clean Once installed, check the presence of the plugin by starting the browser, entering opera:plugins in the location bar and pressing Enter. A list should appear with all the currently available plugins. To add the &java; plugin, follow the instructions in . Konqueror Konqueror Konqueror is more than a web browser as it is also a file manager and a multimedia viewer. It is included in the x11/kde4-baseapps package or port. Konqueror supports WebKit as well as its own KHTML. WebKit is a rendering engine used by many modern browsers including Chromium. To use WebKit with Konqueror on &os;, install the www/kwebkitpart package or port. This example compiles the port: &prompt.root; cd /usr/ports/www/kwebkitpart &prompt.root; make install clean To enable WebKit within Konqueror, click Settings, Configure Konqueror. In the General settings page, click the drop-down menu next to Default web browser engine and change KHTML to WebKit. Konqueror also supports &flash;. A How To guide for getting &flash; support on Konqueror is available at . Chromium Chromium Chromium is an open source browser project that aims to build a safer, faster, and more stable web browsing experience. Chromium features tabbed browsing, popup blocking, extensions, and much more. Chromium is the open source project upon which the Google Chrome web browser is based. Chromium can be installed as a package by typing: &prompt.root; pkg_add -r chromium Alternatively, Chromium can be compiled from source using the Ports Collection: &prompt.root; cd /usr/ports/www/chromium &prompt.root; make install clean The executable for Chromium is /usr/local/bin/chrome, not /usr/local/bin/chromium. Chromium and &java; Plugin The installation of Chromium does not include &java; support. To install &java; plugin support, follow the instructions in . Once &java; support is installed, start Chromium and enter about:plugins in the address bar. IcedTea-Web should be listed as one of the installed plugins. If Chromium does not display the IcedTea-Web plugin, run the following commands and restart the web browser: &prompt.root; mkdir -p /usr/local/share/chromium/plugins &prompt.root; ln -s /usr/local/lib/IcedTeaPlugin.so \ /usr/local/share/chromium/plugins/ Chromium and &adobe; &flash; Plugin Configuring Chromium and &adobe; &flash; is similar to the the instructions in . No additional configuration should be necessary, since Chromium is able to use some plugins from other browsers. Productivity When it comes to productivity, new users often look for an office suite or an easy-to-use word processor. While some desktop environments like KDE provide an office suite, there is no default productivity package. Several office suites and graphical word processors are available for &os;, regardless of the installed window manager. This section demonstrates how to install the following popular productivity software and indicates if the application is resource-heavy, takes time to compile from ports, or has any major dependencies. Application Name Resources Needed Installation from Ports Major Dependencies Calligra light heavy KDE AbiWord light light Gtk+ or GNOME The Gimp light heavy Gtk+ Apache OpenOffice heavy huge &jdk; and Mozilla LibreOffice somewhat heavy huge Gtk+, or KDE/ GNOME, or &jdk; Calligra Calligra office suite Calligra The KDE desktop environment includes an office suite which can be installed separately from KDE. Calligra includes standard components that can be found in other office suites. Words is the word processor, Sheets is the spreadsheet program, Stage manages slide presentations, and Karbon is used to draw graphical documents. In &os;, editors/calligra can be installed as a package or a port. To install the package: &prompt.root; pkg_add -r calligra If the package is not available, use the Ports Collection instead: &prompt.root; cd /usr/ports/editors/calligra &prompt.root; make install clean AbiWord AbiWord AbiWord is a free word processing program similar in look and feel to µsoft; Word. It is fast, contains many features, and is user-friendly. AbiWord can import or export many file formats, including some proprietary ones like µsoft; .rtf. To install the AbiWord package: &prompt.root; pkg_add -r abiword If the package is not available, it can be compiled from the Ports Collection: &prompt.root; cd /usr/ports/editors/abiword &prompt.root; make install clean The GIMP The GIMP For image authoring or picture retouching, The GIMP provides a 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 plugins and features a scripting interface. The GIMP can read and write a wide range of file formats and supports interfaces with scanners and tablets. To install the package: &prompt.root; pkg_add -r gimp Alternately, use the Ports Collection: &prompt.root; cd /usr/ports/graphics/gimp &prompt.root; make install clean The graphics category (freebsd.org/ports/graphics.html) of the Ports Collection contains several GIMP-related plugins, help files, and user manuals. Apache OpenOffice Apache OpenOffice office suite Apache OpenOffice Apache OpenOffice is an open source office suite which is developed under the wing of the Apache Software Foundation's Incubator. It includes all of the applications found in a complete office productivity suite: a word processor, spreadsheet, presentation manager, and drawing program. Its user interface is 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 and internationalization has been extended to interfaces, spell checkers, and dictionaries. The word processor of Apache OpenOffice uses a native XML file format for increased portability and flexibility. The spreadsheet program features a macro language which can be interfaced with external databases. Apache OpenOffice is stable and runs natively on &windows;, &solaris;, &linux;, &os;, and &macos; X. More information about Apache OpenOffice can be found at openoffice.org. For &os; specific information refer to porting.openoffice.org/freebsd/. To install the Apache OpenOffice package: &prompt.root; pkg_add -r apache-openoffice Once the package is installed, type the following command to launch Apache OpenOffice: &prompt.user; openoffice-X.Y.Z where X.Y.Z is the version number of the installed version of Apache OpenOffice. The first time Apache OpenOffice launches, some questions will be asked and a .openoffice.org folder will be created in the user's home directory. If the desired Apache OpenOffice package is not available, compiling the port is still an option. However, this requires a lot of disk space and a fairly long time to compile: &prompt.root; cd /usr/ports/editors/openoffice-4 &prompt.root; make install clean To build a localized version, replace the previous command with: &prompt.root; make LOCALIZED_LANG=your_language install clean Replace your_language with the correct language ISO-code. A list of supported language codes is available in files/Makefile.localized, located in the port's directory. LibreOffice LibreOffice office suite LibreOffice LibreOffice is a free software office suite developed by documentfoundation.org. It is compatible with other major office suites and available on a variety of platforms. It is a rebranded fork of OpenOffice.org and includes applications found in a complete office productivity suite: a word processor, spreadsheet, presentation manager, drawing program, database management program, and a tool for creating and editing mathematical formulæ. It is available in a number of different languages and internationalization has been extended to interfaces, spell checkers, and dictionaries. The word processor of LibreOffice uses a native XML file format for increased portability and flexibility. The spreadsheet program features a macro language which can be interfaced with external databases. LibreOffice is stable and runs natively on &windows;, &linux;, &os;, and &macos; X. More information about LibreOffice can be found at libreoffice.org. To install the English version of the LibreOffice package: &prompt.root; pkg_add -r libreoffice The editors category (freebsd.org/ports/editors.html) of the Ports Collection contains several localizations for LibreOffice. When installing a localized package, replace libreoffice with the name of the localized package. Once the package is installed, type the following command to run LibreOffice: &prompt.user; libreoffice During the first launch, some questions will be asked and a .libreoffice folder will be created in the user's home directory. If the desired LibreOffice package is not available, compiling the port is still an option. However, this requires a lot of disk space and a fairly long time to compile. This example compiles the English version: &prompt.root; cd /usr/ports/editors/libreoffice &prompt.root; make install clean To build a localized version, cd into the port directory of the desired language. Supported languages can be found in the editors category (freebsd.org/ports/editors.html) of the Ports Collection. Document Viewers Some new document formats have gained popularity since the advent of &unix; and the viewers they require may not be available in the base system. This section demonstrates how to install the following document viewers: Application Name Resources Needed Installation from Ports Major Dependencies &acrobat.reader; light light &linux; binary compatibility gv light light Xaw3d Xpdf light light FreeType GQview light light Gtk+ or GNOME &acrobat.reader; Acrobat Reader PDF viewing Many documents are now distributed as Portable Document Format (PDF) files. One popular PDF viewer is &acrobat.reader;, released by &adobe; for &linux;. As &os; can run &linux; binaries, it is also available for &os;. Due to licensing restrictions, a package is not available, meaning that this application must be compiled from ports. Several localizations are available from the print category (freebsd.org/ports/print.html) of the Ports Collection. This command installs the English version of &acrobat.reader; 9 from the Ports Collection. To instead install a localized version, cd into the desired port's directory. &prompt.root; cd /usr/ports/print/acroread9 &prompt.root; make install clean <application>gv</application> gv PDF viewing PostScript viewing gv is a &postscript; and PDF viewer. It is based on ghostview, but has a nicer look as it is based on the Xaw3d widget toolkit. gv has many configurable features, such as orientation, paper size, scale, and anti-aliasing. Almost any operation can be performed with either the keyboard or the mouse. To install gv as a package: &prompt.root; pkg_add -r gv If a package is unavailable, use the Ports Collection: &prompt.root; cd /usr/ports/print/gv &prompt.root; make install clean Xpdf Xpdf PDF viewing For users that prefer a small &os; PDF viewer, Xpdf provides a light-weight and efficient viewer which requires few resources. It uses the standard X fonts and does not require any additional toolkits. To install the Xpdf package: &prompt.root; pkg_add -r xpdf If the package is not available, use the Ports Collection: &prompt.root; cd /usr/ports/graphics/xpdf &prompt.root; make install clean Once the installation is complete, launch xpdf and use the right mouse button to activate the menu. GQview GQview GQview is an image manager which supports viewing a file with a single click, launching an external editor, and thumbnail previews. It also features a slideshow mode and some basic file operations, making it easy to manage image collections and to find duplicate files. GQview supports full screen viewing and internationalization. To install the GQview package: &prompt.root; pkg_add -r gqview If the package is not available, use the Ports Collection: &prompt.root; cd /usr/ports/graphics/gqview &prompt.root; make install clean Finance For managing personal finances on a &os; desktop, some powerful and easy-to-use applications can be installed. Some are compatible with widespread file formats, such as the formats used by Quicken and Excel. This section covers these programs: Application Name Resources Needed Installation from Ports Major Dependencies GnuCash light heavy GNOME Gnumeric light heavy GNOME KMyMoney light heavy KDE GnuCash GnuCash GnuCash is part of the GNOME effort to provide user-friendly, yet powerful, applications to end-users. GnuCash can be used to keep track of income and expenses, bank accounts, and stocks. It features an intuitive interface while remaining professional. GnuCash 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. GnuCash can import and merge Quicken QIF files. It also handles most international date and currency formats. To install the GnuCash package: &prompt.root; pkg_add -r gnucash If the package is not available, use the Ports Collection: &prompt.root; cd /usr/ports/finance/gnucash &prompt.root; make install clean Gnumeric Gnumeric spreadsheet Gnumeric Gnumeric is a spreadsheet program developed by the GNOME community. It features convenient automatic guessing 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, including Excel, Lotus 1-2-3, and Quattro Pro. 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. To install Gnumeric as a package: &prompt.root; pkg_add -r gnumeric If the package is not available, use the Ports Collection: &prompt.root; cd /usr/ports/math/gnumeric &prompt.root; make install clean KMyMoney KMyMoney spreadsheet KMyMoney KMyMoney is a personal finance application created by the KDE community. KMyMoney aims to provide the important features found in commercial personal finance manager applications. It also highlights ease-of-use and proper double-entry accounting among its features. KMyMoney imports from standard Quicken QIF files, tracks investments, handles multiple currencies, and provides a wealth of reports. To install KMyMoney as a package: &prompt.root; pkg_add -r kmymoney-kde4 If the package is not available, use the Ports Collection: &prompt.root; cd /usr/ports/finance/kmymoney-kde4 &prompt.root; make install clean diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml index 9f3073b867..911c0e0a7e 100644 --- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml @@ -1,1380 +1,1385 @@ - - + + --> Configuring the FreeBSD Kernel Synopsis kernel building a custom kernel 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 much of &os; is dynamically configurable, it is still occasionally necessary to configure and compile a custom kernel. After reading this chapter, you will know: When to build a custom kernel. How to take a hardware inventory. How to customize a kernel configuration file. How to use the kernel configuration file to create and build a new kernel. How to install the new kernel. How to troubleshoot if things go wrong. All of the commands listed in the examples in this chapter should be executed as root. Why Build a Custom Kernel? Traditionally, &os; used a monolithic kernel. The kernel was one large program, supported a fixed list of devices, and in order to change the kernel's behavior, one had to compile and then reboot into a new kernel. Today, most of the functionality in the &os; kernel is contained in modules which can be dynamically loaded and unloaded from the kernel as necessary. This allows the running kernel to adapt immediately to new hardware or for new functionality to be brought into the kernel. This is known as a modular kernel. Occasionally, it is still necessary to perform static kernel configuration. Sometimes the needed functionality is so tied to the kernel that it can not be made dynamically loadable. Some security environments prevent the loading and unloading of kernel modules and require that only needed functionality is statically compiled into the kernel. Building a custom kernel is often a rite of passage for advanced BSD users. This process, while time consuming, can provide benefits to the &os; system. Unlike the GENERIC kernel, which must support a wide range of hardware, a custom kernel can be stripped down to only provide support for that computer's hardware. This has a number of benefits, such as: Faster boot time. Since the kernel will only probe the hardware on the system, the time it takes the system to boot can decrease. Lower memory usage. A custom kernel often uses less memory than the GENERIC 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 useful on a system with a small amount of RAM. Additional hardware support. A custom kernel can add support for devices which are not present in the GENERIC kernel. Before building a custom kernel, consider the reason for doing so. If there is a need for specific hardware support, it may already exist as a module. Kernel modules exist in /boot/kernel and may be dynamically loaded into the running kernel using &man.kldload.8;. Most kernel drivers have a loadable module and manual page. For example, the &man.ath.4; wireless Ethernet driver has the following information in its manual page: Alternatively, to load the driver as a module at boot time, place the following line in &man.loader.conf.5;: if_ath_load="YES" Adding if_ath_load="YES" to /boot/loader.conf will load this module dynamically at boot time. In some cases, there is no associated module in /boot/kernel. This is mostly true for certain subsystems. + + + --> Finding the System Hardware Before editing the kernel configuration file, it is recommended to perform an inventory of the machine's hardware. On a dual-boot system, the inventory can be created from the other operating system. For example, µsoft;'s Device Manager contains information about installed devices. Some versions of µsoft.windows; have a System icon which can be used to access Device Manager. If &os; is the only installed operating system, use &man.dmesg.8; to determine the hardware that was found and listed during the boot probe. Most device drivers on &os; have a manual page which lists the hardware supported by that driver. For example, the following lines indicate that the &man.psm.4; driver found a mouse: psm0: <PS/2 Mouse> irq 12 on atkbdc0 psm0: [GIANT-LOCKED] psm0: [ITHREAD] psm0: model Generic PS/2 mouse, device ID 0 Since this hardware exists, this driver should not be removed from a custom kernel configuration file. If the output of dmesg does not display the results of the boot probe output, instead read the contents of /var/run/dmesg.boot. Another tool for finding hardware is &man.pciconf.8;, which provides more verbose output. For example: pciconf 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 This output shows that the ath driver located a wireless Ethernet device. The flag of &man.man.1; can be used to provide useful information. For example, to display a list of manual pages which contain the specified word: &prompt.root; man -k Atheros ath(4) - Atheros IEEE 802.11 wireless network driver ath_hal(4) - Atheros Hardware Access Layer (HAL) Once the hardware inventory list is created, refer to it to ensure that installed hardware is not removed as you edit the custom kernel configuration file. + + + --> The Configuration File In order to create a custom kernel configuration file and build a custom kernel, the full &os; source tree must first be installed. If /usr/src/ does not exist or it is empty, source has not been installed. Source can be installed using svn, which is described in , or by installing the src distribution using &man.sysinstall.8;. This distribution can be selected by navigating to the Configuration and then to the Distributions menu within &man.sysinstall.8;. Once source is installed, review the contents of /usr/src/sys. This directory contains a number of subdirectories, including those which represent the following supported architectures: amd64, i386, ia64, pc98, powerpc, and sparc64. Everything inside a particular architecture's directory deals with that architecture only and the rest of the code is machine independent code common to all platforms. Each supported architecture has a conf subdirectory which contains the GENERIC kernel configuration file for that architecture. Do not make edits to GENERIC. Instead, copy the file to a different name and make edits to the copy. The convention is to use a name with all capital letters. When maintaining multiple &os; machines with different hardware, it is a good idea to name it after the machine's hostname. This example creates a custom configuration file for the amd64 architecture: &prompt.root; cd /usr/src/sys/amd64/conf &prompt.root; cp GENERIC MYKERNEL When finished customizing the kernel configuration file, save a backup copy to a location outside of /usr/src. Alternately, keep the kernel configuration file elsewhere and create a symbolic link to the file: &prompt.root; cd /usr/src/sys/amd64/conf &prompt.root; mkdir /root/kernels &prompt.root; cp GENERIC /root/kernels/MYKERNEL &prompt.root; ln -s /root/kernels/MYKERNEL The configuration file MYKERNEL can now be customized with any ASCII text editor. The default editor is vi, though an easier editor for beginners, called ee, is also installed with &os;. kernel NOTES NOTES kernel configuration file The format of the kernel configuration file is simple. Each line contains a keyword that represents a device or subsystem, an argument, and a brief description. Any text after a # is considered a comment and ignored. To remove kernel support for a device or subsystem, put a # at the beginning of the line representing that device or subsystem. Do not add or remove a # for any line that you do not understand. In addition to the brief descriptions provided in this file, additional descriptions are contained in NOTES, which can be found in the same directory as GENERIC for that architecture. For architecture independent options, refer to /usr/src/sys/conf/NOTES. An include directive is available for use in configuration files. This allows another configuration file to be included in the current one, making it easy to maintain small changes relative to an existing file. For example, if only a small number of additional options or drivers are required, this allows a delta to be maintained with respect to GENERIC: include GENERIC ident MYKERNEL options IPFIREWALL options DUMMYNET options IPFIREWALL_DEFAULT_TO_ACCEPT options IPDIVERT Using this method, the local configuration file expresses local differences from a GENERIC kernel. As upgrades are performed, new features added to GENERIC will also be added to the local kernel unless they are specifically prevented using nooptions or nodevice. A comprehensive list of configuration directives and their descriptions may be found in &man.config.5;. To build a file which contains all available options, run the following command as root: &prompt.root; cd /usr/src/sys/i386/conf && make LINT kernel options ident ident GENERIC This is the identification of the kernel. Change this to the new kernel name, such as MYKERNEL. The value in the ident string will print when the kernel boots. makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols This option enables debugging information when passed to &man.gcc.1;. options SCHED_ULE # ULE scheduler The default system scheduler for &os;. Keep this. options INET # InterNETworking Networking support. This is mandatory as most programs require at least loopback networking. options INET6 # IPv6 communications protocols This enables the IPv6 communication protocols. options FFS # Berkeley Fast Filesystem This is the basic hard drive file system. Leave it in if the system boots from the hard disk. options SOFTUPDATES # Enable FFS Soft Updates support This option enables Soft Updates in the kernel which helps to 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 of &man.mount.8; to determine if Soft Updates is enabled. If the soft-updates option is not in the output, it can be activated using &man.tunefs.8; for existing file systems or &man.newfs.8; for new file systems. options UFS_ACL # Support for access control lists This option enables kernel support for access control lists (ACLs). This relies on the use of extended attributes and UFS2, and the feature is described in detail in . ACLs 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 ACLs, changing the way files are protected in unpredictable ways. options UFS_DIRHASH # Improve performance on big directories This option includes functionality to speed up disk operations on large directories, at the expense of using additional memory. Keep this for a large server or interactive workstation, and remove it from smaller systems where memory is at a premium and disk access speed is less important, such as a firewall. options MD_ROOT # MD is a potential root device This option enables support for a memory backed virtual disk used as a root device. kernel options NFS kernel options NFS_ROOT options NFSCLIENT # Network Filesystem Client options NFSSERVER # Network Filesystem Server options NFS_ROOT # NFS usable as /, requires NFSCLIENT The network file system (NFS). These lines can be commented unless the system needs to mount partitions from a NFS file server over TCP/IP. kernel options MSDOSFS options MSDOSFS # MSDOS Filesystem The &ms-dos; file system. Unless the system needs to mount a DOS formatted hard drive partition at boot time, comment this out. It will be automatically loaded the first time a DOS partition is mounted. The emulators/mtools package allows access to DOS floppies without having to mount and unmount them and does not require MSDOSFS. options CD9660 # ISO 9660 Filesystem The ISO 9660 file system for CDROMs. Comment it out if the system does not have a CDROM drive or only mounts data CDs occasionally since it will be dynamically loaded the first time a data CD is mounted. Audio CDs do not need this file system. options PROCFS # Process filesystem (requires PSEUDOFS) The process file system. This is a pretend file system mounted on /proc which allows some programs to provide more information on what processes are running. Use of PROCFS is not required under most circumstances, as most debugging and monitoring tools have been adapted to run without PROCFS. The default installation will not mount this file system by default. options PSEUDOFS # Pseudo-filesystem framework Kernels making use of PROCFS must also include support for PSEUDOFS. options GEOM_PART_GPT # GUID Partition Tables. Adds support for GUID Partition Tables (GPT). GPT provides the ability to have a large number of partitions per disk, 128 in the standard configuration. options COMPAT_43 # Compatible with BSD 4.3 [KEEP THIS!] Compatibility with 4.3BSD. Leave this in as some programs will act strangely if this is commented out. options COMPAT_FREEBSD4 # Compatible with &os;4 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 after &os; 4.X, such as ia64 and &sparc64;, do not require this option. options COMPAT_FREEBSD5 # Compatible with &os;5 This option is required to support applications compiled on &os; 5.X versions that use &os; 5.X system call interfaces. options COMPAT_FREEBSD6 # Compatible with &os;6 This option is required to support applications compiled on &os; 6.X versions that use &os; 6.X system call interfaces. options COMPAT_FREEBSD7 # Compatible with &os;7 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. options SCSI_DELAY=5000 # Delay (in ms) before probing SCSI This causes the kernel to pause for 5 seconds before probing each SCSI device in the system. If the system only has IDE hard drives, ignore this or lower the number to speed up booting. However, if &os; has trouble recognizing the SCSI devices, the number will have to be raised again. options KTRACE # ktrace(1) support This enables kernel process tracing, which is useful in debugging. options SYSVSHM # SYSV-style shared memory 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 Xorg is installed, include this. options SYSVMSG # SYSV-style message queues Support for System V messages. This option only adds a few hundred bytes to the kernel. options SYSVSEM # SYSV-style semaphores Support for System V semaphores. Less commonly used, but only adds a few hundred bytes to the kernel. Using with &man.ipcs.1; will list any processes using each of these System V facilities. options _KPOSIX_PRIORITY_SCHEDULING # POSIX P1003_1B real-time extensions Real-time extensions added in the 1993 &posix;. Certain applications in the Ports Collection use these. options KBD_INSTALL_CDEV # install a CDEV entry in /dev This option is required to allow the creation of keyboard device nodes in /dev. kernel options SMP device apic # I/O APIC This device enables the use of the I/O APIC for interrupt delivery. It can be used in both uni-processor and SMP kernels, but is required for SMP kernels. Add options SMP to include support for multiple processors. This device exists only on the i386 architecture and this configuration line should not be used on other architectures. device eisa Include this for systems with an EISA motherboard. This enables auto-detection and configuration support for all devices on the EISA bus. device pci Include this for systems with a PCI motherboard. This enables auto-detection of PCI cards and gatewaying from the PCI to ISA bus. # Floppy drives device fdc This is the floppy drive controller. # ATA and ATAPI devices device ata This driver supports all ATA and ATAPI devices. Only one device ata line is needed for the kernel to detect all PCI ATA/ATAPI devices on modern machines. device atadisk # ATA disk drives This is needed along with device ata for ATA disk drives. device ataraid # ATA RAID drives This is needed along with device ata for ATA RAID drives. device atapicd # ATAPI CDROM drives This is needed along with device ata for ATAPI CDROM drives. device atapifd # ATAPI floppy drives This is needed along with device ata for ATAPI floppy drives. device atapist # ATAPI tape drives This is needed along with device ata for ATAPI tape drives. options ATA_STATIC_ID # Static device numbering This makes the controller number static. Without this, the device numbers are dynamically allocated. # 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 In this section, comment out any SCSI controllers not on the system. For an IDE only system, these lines can be removed. The *_REG_PRETTY_PRINT lines are debugging options for their respective drivers. # 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) Comment out any SCSI peripherals not on the system. If the system only has IDE hardware, these lines can be removed completely. The USB &man.umass.4; driver and a few other drivers use the SCSI subsystem even though they are not real SCSI devices. Do not remove SCSI support if any such drivers are included in the kernel configuration. # 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 Supported RAID controllers. If the system does not have any of these, comment them out or remove them. # atkbdc0 controls both the keyboard and the PS/2 mouse device atkbdc # AT keyboard controller The atkbdc keyboard controller provides I/O services for the AT keyboard and PS/2 style pointing devices. This controller is required by &man.atkbd.4; and &man.psm.4;. device atkbd # AT keyboard The &man.atkbd.4; driver, together with the &man.atkbdc.4; controller, provides access to the AT 84 keyboard or the AT enhanced keyboard which is connected to the AT keyboard controller. device psm # PS/2 mouse Use this device if the mouse plugs into the PS/2 mouse port. device kbdmux # keyboard multiplexer Basic support for keyboard multiplexing. If the system does not use more than one keyboard, this line can be safely removed. device vga # VGA video card driver The &man.vga.4; video card driver. device splash # Splash screen and screen saver support Required by the boot splash screen and screen savers. # syscons is the default console driver, resembling a SCO console device sc &man.sc.4; is the default console driver and resembles a SCO console. Since most full-screen programs access the console through a terminal database library like termcap, it should not matter whether this or vt, the VT220 compatible console driver, is used. When a user logs in, the TERM variable can be set to scoansi if full-screen programs have trouble running under this console. # 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 This is a VT220-compatible console driver, backward compatible to VT100/102. It works well on some laptops which have hardware incompatibilities with sc. Users may need to set TERM to vt100 or vt220 after login. This driver is useful when connecting to a large number of different machines over the network, where termcap or terminfo entries for the sc device are not available as vt100 should be available on virtually any platform. device agp Include this if the system has an AGP card. This will enable support for AGP and AGP GART for boards which have these features. # Add suspend/resume support for the i8254. device pmtimer Timer device driver for power management events, such as APM and ACPI. # 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 PCMCIA support. Keep this on laptop systems. # Serial (COM) ports device sio # 8250, 16[45]50 based serial ports These are the serial ports referred to as COM ports in &windows;. If the system has an internal modem on COM4 and a serial port at COM2, change the IRQ of the modem to 2. For a multiport serial card, refer to &man.sio.4; for more information on the proper values to add to /boot/device.hints. Some video cards, notably those based on S3 chips, use I/O addresses in the form of 0x*2e8. Since many cheap serial cards do not fully decode the 16-bit I/O address space, they clash with these cards, making the COM4 port practically unavailable. Each serial port is required to have a unique IRQ and the default IRQs for COM3 and COM4 cannot be used. The exception is multiport cards where shared interrupts are supported. # Parallel port device ppc This is the ISA bus parallel port interface. device ppbus # Parallel port bus (required) Provides support for the parallel port bus. device lpt # Printer Adds support for parallel port printers. All three of the above are required to enable parallel printer support. device ppi # Parallel port interface device The general-purpose I/O (geek port) + IEEE1284 I/O. #device vpo # Requires scbus and da zip drive This is for an Iomega Zip drive. It requires scbus and da support. Best performance is achieved with ports in EPP 1.9 mode. #device puc Uncomment this device if the system has a dumb serial or parallel PCI card that is supported by the &man.puc.4; glue driver. # PCI Ethernet NICs. device de # DEC/Intel DC21x4x (Tulip) device em # Intel PRO/1000 adapter Gigabit Ethernet Card device ixgb # Intel PRO/10GbE Ethernet Card device txp # 3Com 3cR990 (Typhoon) device vx # 3Com 3c590, 3c595 (Vortex) Various PCI network card drivers. Comment out or remove any of these which are not present in the system. # 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 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 device miibus 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. 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 (Starfire) 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 EPIC) device vge # VIA VT612x gigabit ethernet device vr # VIA Rhine, Rhine II device wb # Winbond W89C840F device xl # 3Com 3c90x (Boomerang, Cyclone) Drivers that use the MII bus controller code. # 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 ISA Ethernet drivers. See /usr/src/sys/i386/conf/NOTES for details of which cards are supported by which driver. # Wireless NIC cards device wlan # 802.11 support Generic 802.11 support. This line is required for wireless networking. device wlan_wep # 802.11 WEP support device wlan_ccmp # 802.11 CCMP support device wlan_tkip # 802.11 TKIP support Crypto support for 802.11 devices. These lines are needed on systems which use encryption and 802.11i security protocols. 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. Support for various wireless cards. # Pseudo devices device loop # Network loopback This is the generic loopback device for TCP/IP. This is mandatory. device random # Entropy device Cryptographically secure random number generator. device ether # Ethernet support ether is only needed if the system has an Ethernet card. It includes generic Ethernet protocol code. device sl # Kernel SLIP sl provides 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. device ppp # Kernel PPP This is for kernel PPP support for dial-up connections. There is also a version of PPP implemented as a userland application that uses tun and offers more flexibility and features such as demand dialing. device tun # Packet tunnel. This is used by the userland PPP software. See the PPP section of the Handbook for more information. device pty # Pseudo-ttys (telnet etc) This is a pseudo-terminal or simulated login port. It is used by incoming telnet and rlogin sessions, xterm, and some other applications such as Emacs. device md # Memory disks Memory disk pseudo-devices. device gif # IPv6 and IPv4 tunneling This implements IPv6 over IPv4 tunneling, IPv4 over IPv6 tunneling, IPv4 over IPv4 tunneling, and IPv6 over IPv6 tunneling. The gif device is auto-cloning, and will create device nodes as needed. device faith # IPv6-to-IPv4 relaying (translation) This pseudo-device captures packets that are sent to it and diverts them to the IPv4/IPv6 translation daemon. # 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 The Berkeley Packet Filter pseudo-device allows network interfaces to be placed in promiscuous mode, capturing every packet on a broadcast network such as an Ethernet network. These packets can be captured to disk and or examined using &man.tcpdump.1;. The &man.bpf.4; device is also used by &man.dhclient.8;. If DHCP is used, leave this uncommented. # 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 # Human Interface Devices 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 Support for various USB devices. # FireWire support device firewire # FireWire bus code device sbp # SCSI over FireWire (Requires scbus and da) device fwe # Ethernet over FireWire (non-standard!) Support for various Firewire devices. For more information and additional devices supported by &os;, see /usr/src/sys/i386/conf/NOTES. Large Memory Configurations (<acronym>PAE</acronym>) Physical Address Extensions (PAE) large memory Large memory configuration machines require access to more than the 4 gigabyte limit on User+Kernel Virtual Address (KVA) space. Due to this limitation, Intel added support for 36-bit physical address space access in the &pentium; Pro and later line of CPUs. The Physical Address Extension (PAE) 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 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. To enable PAE support in the kernel, add the following line to the kernel configuration file: options PAE The PAE support in &os; is only available for &intel; IA-32 processors. It should also be noted that the PAE support in &os; has not received wide testing, and should be considered beta quality compared to other stable features of &os;. PAE support in &os; has a few limitations: A process is not able to access more than 4 gigabytes of virtual memory space. Device drivers that do not use the &man.bus.dma.9; interface will cause data corruption in a PAE enabled kernel and are not recommended for use. For this reason, a PAE kernel configuration file is provided in &os; which excludes all drivers not known to work in a PAE enabled kernel. 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 PAE system. One such example is the kern.maxvnodes 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. It might be necessary to increase the kernel virtual address (KVA) space or to reduce the amount of specific kernel resource that is heavily used in order to avoid KVA exhaustion. The kernel option can be used for increasing the KVA space. For performance and stability concerns, it is advised to consult &man.tuning.7;. &man.pae.4; contains up-to-date information on &os;'s PAE support. Building and Installing a Custom Kernel After saving the edits, compile the source code for the kernel. After syncing the source tree with the latest sources, always read /usr/src/UPDATING before performing any update steps. This file describes any important issues or areas requiring special attention within the updated source code. /usr/src/UPDATING always matches the version of the &os; source and contains more up-to-date information than this Handbook. 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 ATA disk drivers may not boot. When in doubt, just leave support in the kernel. Building a Kernel kernel building / installing It is required to have the full &os; source tree installed to build the kernel. cd to /usr/src: &prompt.root; cd /usr/src Compile the new kernel by specifying the name of the custom kernel configuration file: &prompt.root; make buildkernel KERNCONF=MYKERNEL Install the new kernel: &prompt.root; make installkernel KERNCONF=MYKERNEL By default, when a custom kernel is compiled, all kernel modules are rebuilt as well. To update a kernel faster or to build only custom modules, edit /etc/make.conf before starting to build the kernel: MODULES_OVERRIDE = linux acpi sound/sound sound/driver/ds1 ntfs This variable specifies the list of modules to build instead the default of building of all of them. WITHOUT_MODULES = linux acpi sound ntfs This variable sets up a list of top level modules to exclude from the build process. For other available variables, refer to &man.make.conf.5;. /boot/kernel.old The new kernel will be copied to /boot/kernel as /boot/kernel/kernel and the old kernel will be moved to /boot/kernel.old/kernel. Now, shutdown the system and reboot into the new kernel. If something goes wrong, refer to the troubleshooting instructions and the section which explains how to recover when the new kernel does not boot. Other files relating to the boot process, such as the boot &man.loader.8; and configuration, are stored in /boot. Third party or custom modules can be placed in /boot/kernel, 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. If Something Goes Wrong There are four categories of trouble that can occur when building a custom kernel. They are: config fails: If &man.config.8; fails, it is probably a simple error. Fortunately, &man.config.8; will print the line number that it had trouble with. For example, for this message: config: line 17: syntax error Make sure the keyword on line 17 is typed correctly by comparing it to the GENERIC kernel or another reference. make fails: If make fails, it usually signals an error in the kernel description which is not severe enough for &man.config.8; to catch. Review the configuration, and if you still cannot resolve the problem, send an email to the &a.questions; with the kernel configuration. The kernel does not boot: If the new kernel does not boot, or fails to recognize devices, do not panic! Fortunately, &os; has an excellent mechanism for recovering from incompatible kernels. Simply choose the kernel to boot from at the &os; boot loader. This can be accessed when the system boot menu appears by selecting the Escape to a loader prompt option. At the prompt, type boot kernel.old, 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. After booting with a good kernel, check over the configuration file and try to build it again. One helpful resource is /var/log/messages which records the kernel messages from every successful boot. Also, &man.dmesg.8; will print the kernel messages from the current boot. When troubleshooting a kernel, make sure to keep GENERIC, or some other kernel that is known to work, on hand as a different name that will not get erased on the next build. Do not rely on kernel.old because when installing a new kernel, kernel.old is overwritten with the last installed kernel which may be non-functional. As soon as possible, move the working kernel to the proper /boot/kernel location or commands such as &man.ps.1; may not work properly. To do this, simply rename the directory containing the good kernel: &prompt.root; mv /boot/kernel /boot/kernel.bad &prompt.root; mv /boot/kernel.good /boot/kernel The kernel works, but &man.ps.1; does not work any more: If the kernel version differs 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. To fix this, recompile and install a world built with the same version of the source tree as the kernel. This is one reason why it is not a good idea to use a different version of the kernel than the rest of the operating system. diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.xml b/en_US.ISO8859-1/books/handbook/ports/chapter.xml index eb8db4a3a2..77621e5ff0 100644 --- a/en_US.ISO8859-1/books/handbook/ports/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/ports/chapter.xml @@ -1,1688 +1,1690 @@ Installing Applications: Packages and Ports Synopsis ports packages &os; is bundled with a rich collection of system tools as part of the base system. In addition, &os; provides two complementary technologies for installing third-party software: the &os; Ports Collection, for installing from source, and packages, for installing from pre-built binaries. Either method may be used to install software from local media or from the network. After reading this chapter, you will know: The difference between binary packages and ports. How to find third-party software that has been ported to &os;. How to manage binary packages using the traditional package system. How to manage binary packages using pkgng. How to build third-party software from source using the Ports Collection. How to find the files installed with the application for post-installation configuration. What to do if a software installation fails. Overview of Software Installation The typical steps for installing third-party software on a &unix; system include: Find and download the software, which might be distributed in source code format or as a binary. Unpack the software from its distribution format. This is typically a tarball compressed with &man.compress.1;, &man.gzip.1;, or &man.bzip2.1;. Locate the documentation in INSTALL, README or some file in a doc/ subdirectory and read up on how to install the software. If the software was distributed in source format, compile it. This may involve editing a Makefile or running a configure script. Test and install the software. If the software package was not deliberately ported, or tested to work, on &os;, the source code may need editing in order for it to install and run properly. At the time of this writing, over &os.numports; third-party applications have been ported to &os;. &os; provides two technologies which automate these steps. A &os; package contains pre-compiled copies of all the commands for an application, as well as any configuration files and documentation. A package can be manipulated with the traditional &os; package management commands, such as &man.pkg.add.1;, or using the newer pkgng commands, such as pkg install. A &os; port is a collection of files designed to automate the process of compiling an application from source code. The files that comprise a port contain all the necessary information to automatically download, extract, patch, compile, and install the application. The ports system can also be used to generate packages which can be manipulated with the &os; package management commands. Both packages and ports understand dependencies. If a package or port is used to install an application and a dependent library is not already installed, the library will automatically be installed first. While the two technologies are similar, packages and ports each have their own strengths. Select the technology that meets your requirements for installing a particular application. Package Benefits A compressed package tarball is typically smaller than the compressed tarball containing the source code for the application. Packages do not require compilation time. For large applications, such as Mozilla, KDE, or GNOME, this can be important on a slow system. Packages do not require any understanding of the process involved in compiling software on &os;. Port Benefits Packages are normally compiled with conservative options because they have to run on the maximum number of systems. By compiling from the port, one can change the compilation options. Some applications have compile-time options relating to which features are installed. For example, Apache can be configured with a wide variety of different built-in options. In some cases, multiple packages will exist for the same application to specify certain settings. For example, Ghostscript is available as a ghostscript package and a ghostscript-nox11 package, depending on whether or not Xorg is installed. Creating multiple packages rapidly becomes impossible if an application has more than one or two different compile-time options. The licensing conditions of some software forbid binary distribution. Such software must be distributed as source code which must be compiled by the end-user. Some people do not trust binary distributions or prefer to read through source code in order to look for potential problems. Source code is needed in order to apply custom patches. To keep track of updated ports, subscribe to the &a.ports; and the &a.ports-bugs;. Before installing any application, check for security issues related to the application or install ports-mgmt/portaudit. Once installed, type portaudit -F -a to check all installed applications for known vulnerabilities. The remainder of this chapter explains how to use packages and ports to install and manage third-party software on &os;. Finding Software &os;'s list of available applications is growing all the time. There are a number of ways to find software to install: The &os; web site maintains an up-to-date searchable list of all the available applications, at http://www.FreeBSD.org/ports/. The ports can be searched by application name or by software category. FreshPorts Dan Langille maintains FreshPorts.org which provides a comprehensive search utility and also tracks changes to the applications in the Ports Collection. Registered users can create a customized watch list in order to receive an automated email when their watched ports are updated. Freecode If you do not know the name of an application, try using a site like Freecode.com to find an application, then check back at the &os; site to see if the application has been ported yet. If the Ports Collection is already installed, there are several methods to query the local version of the ports tree. To find out which category a port is in, type whereis file, where file is the program to be installed: &prompt.root; whereis lsof lsof: /usr/ports/sysutils/lsof Alternately, an &man.echo.1; statement can be used: &prompt.root; echo /usr/ports/*/*lsof* /usr/ports/sysutils/lsof Note that this will also return any matched files downloaded into the /usr/ports/distfiles directory. Another way to find software is by using the Ports Collection's built-in search mechanism. To use the search feature, cd to /usr/ports then run make search name=program-name where program-name is the name of the software. For example, to search for lsof: &prompt.root; cd /usr/ports &prompt.root; make search name=lsof Port: lsof-4.88.d,8 Path: /usr/ports/sysutils/lsof Info: Lists information about open files (similar to fstat(1)) Maint: ler@lerctr.org Index: sysutils B-deps: R-deps: The built-in search mechanism uses a file of index information. If a message indicates that the INDEX is required, run make fetchindex to download the current index file. With the INDEX present, make search will be able to perform the requested search. The Path: line indicates where to find the port. To receive less information, use the quicksearch feature: &prompt.root; cd /usr/ports &prompt.root; make quicksearch name=lsof Port: lsof-4.88.d,8 Path: /usr/ports/sysutils/lsof Info: Lists information about open files (similar to fstat(1)) For more in-depth searching, use make search key=string or make quicksearch key=string, where string is some text to search for. The text can be in comments, descriptions, or dependencies in order to find ports which relate to a particular subject when the name of the program is unknown. When using search or quicksearch, the search string is case-insensitive. Searching for LSOF will yield the same results as searching for lsof. + + + --> Using Binary Packages At the present time, &os; is transitioning toward a new method of package management. Users may wish to investigate the benefits of using PKGng to manage third-party software on &os;. This section describes the traditional method for managing binary packages and only applies to those users who have not yet migrated to the pkgng format. This method of package management uses a package database directory, /var/db/pkg, to track installed software versions and the files installed with each application. Several utilities interact with the database directory and are used to manage binary packages. These commands begin with pkg_. This section provides an overview of the commands which are used to install, delete, and gather information about binary packages. Each command provides many switches to customize its operation. Refer to the listed man pages for more details and further usage examples. Installing a Package packages installing pkg_add To install a binary package from a local &os; media or a remote &os; package server, use &man.pkg.add.1;. While a &os; media can provide a source of local packages without requiring a network connection, it may not contain the latest versions of binary packages as new versions are always being rebuilt for the &os; package servers. To install from a package server, always include (for remote) with &man.pkg.add.1;. This automatically determines the correct object format and release, and then fetches and installs the package from a package server without any further user intervention. pkg_add &prompt.root; pkg_add -r lsof In this example, lsof is used without specifying a version number as the version is not included when the remote fetching feature is used. To specify an alternative &os; FTP mirror, specify the mirror in the PACKAGESITE environment variable. &man.pkg.add.1; uses &man.fetch.3; to download files, which uses various environment variables, including FTP_PASSIVE_MODE, FTP_PROXY, and FTP_PASSWORD. 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 of FTP-related variables. &man.pkg.add.1; will automatically download the latest version of the application if you are using &os.current; or &os.stable;. If you run a -RELEASE version, it instead installs the version of the package that was built with that release. It is possible to change this behavior by overriding PACKAGESITE. For example, on a &os; 9.1-RELEASE system, by default &man.pkg.add.1; will try to fetch packages from ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-9.1-release/Latest/. To force &man.pkg.add.1; to download &os; 9-STABLE packages, set PACKAGESITE to ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-9-stable/Latest/. Package files are distributed in the .tbz format. Packages are available from or the /packages directory of the &os; DVD distribution. The layout of the packages directory is similar to that of the /usr/ports tree. Each category has its own directory, and every package can be found within the All directory. Managing Packages packages managing To list and describe installed packages, use &man.pkg.info.1;: pkg_info &prompt.root; pkg_info colordiff-1.0.13 Tool to colorize diff output docbook-1.4 Meta-port for the different versions of the DocBook DTD ... To receive a summary of the versions of all installed packages and a comparison of the installed package versions to the current versions found in the locally installed ports tree, use &man.pkg.version.1;: pkg_version &prompt.root; pkg_version colordiff = docbook = ... The symbols in the second column indicate the relative age of the installed version and the version available in the local ports tree. Symbol Meaning = The version of the installed package matches the one in the local ports tree. < The version of the installed package is older than the one in the local ports tree. > The version of the installed package is newer than the one in the local ports tree, meaning that the local ports tree is probably out of date. ? The installed package cannot be found in the ports index. This can happen when an installed port is removed from the Ports Collection or is renamed. * There are multiple versions of the package. ! The installed package exists in the index but for some reason pkg_version was unable to compare the version number of the installed package with the corresponding entry in the index. Deleting a Package pkg_delete packages deleting To remove a previously installed software package, use &man.pkg.delete.1;: &prompt.root; pkg_delete xchat-2.8.8_1 Note that &man.pkg.delete.1; requires the full package name and number and that the above command would not work if xchat was given instead of xchat-2.8.8_1. Use &man.pkg.version.1; to find the version of the installed package, or use a wildcard: &prompt.root; pkg_delete xchat\* in this case, all packages whose names start with xchat will be deleted. Using <application>pkgng</application> for Binary Package Management pkgng is the next generation replacement for the traditional &os; package management tools, offering many features that make dealing with binary packages faster and easier. pkgng is not a replacement for port management tools like ports-mgmt/portmaster or ports-mgmt/portupgrade. These tools can be used to install third-party software from both binary packages and the Ports Collection, while pkgng installs only binary packages. Getting Started with <application>pkgng</application> &os; 9.1 and later includes a bootstrap utility which can be used to download and install pkgng, along with its manual pages. To bootstrap the system, run: &prompt.root; /usr/sbin/pkg For earlier &os; versions, pkgng must instead be installed from the Ports Collection or as a binary package. To install the port, run: &prompt.root; cd /usr/ports/ports-mgmt/pkg &prompt.root; make &prompt.root; make install clean To install the binary package, run: &prompt.root; pkg_add -r pkg Once pkgng is installed, the package database must be converted from the traditional format to the new format by running this command: &prompt.root; pkg2ng This step is not required for new installations that do not yet have any third-party software installed. This step is not reversible. Once the package database has been converted to the pkgng format, the traditional pkg_* tools should not be used. The package database conversion may emit errors as the contents are converted to the new version. Generally, these errors can be safely ignored. However, a list of third-party software that was not successfully converted will be listed after pkg2ng has finished and these applications must be manually reinstalled. To ensure that the &os; Ports Collection registers new software with pkgng, and not the traditional packages format, &os; versions earlier than 10.X require this line in /etc/make.conf: WITH_PKGNG= yes The pkgng package management system uses a package repository for most operations. The default package repository location is defined in /usr/local/etc/pkg.conf or by the PACKAGESITE environment variable, which overrides the configuration file. Additional pkgng configuration options are described in pkg.conf(5). Usage information for pkgng is available in pkg(8) or by running pkg without additional arguments. Each pkgng command argument is documented in a command-specific manual page. To read the manual page for pkg install, for example, run either of these commands: &prompt.root; pkg help install &prompt.root; man pkg-install The rest of this section demonstrates common binary package management tasks which can be performed using pkgng. Each demonstrated command provides many switches to customize its use. Refer to a command's help or man page for details and more examples. Obtaining Information About Installed Packages Information about the packages installed on a system can be viewed by running pkg info which, when run without any switches, will list the package version for either all installed packages or the specified package. For example, to see which version of pkgng is installed, run: &prompt.root; pkg info pkg pkg-1.1.4_1 Installing and Removing Packages To install a binary package use the following command, where packagename is the name of the package to install: &prompt.root; pkg install packagename This command uses repository data to determine which version of the software to install and if it has any uninstalled dependencies. For example, to install curl: &prompt.root; pkg install curl Updating repository catalogue /usr/local/tmp/All/curl-7.31.0_1.txz 100% of 1181 kB 1380 kBps 00m01s /usr/local/tmp/All/ca_root_nss-3.15.1_1.txz 100% of 288 kB 1700 kBps 00m00s Updating repository catalogue The following 2 packages will be installed: Installing ca_root_nss: 3.15.1_1 Installing curl: 7.31.0_1 The installation will require 3 MB more space 0 B to be downloaded Proceed with installing packages [y/N]: y Checking integrity... done [1/2] Installing ca_root_nss-3.15.5_1... done [2/2] Installing curl-7.31.0_1... done Cleaning up cache files...Done The new package and any additional packages that were installed as dependencies can be seen in the installed packages list: &prompt.root; pkg info ca_root_nss-3.15.5_1 The root certificate bundle from the Mozilla Project curl-7.31.0_1 Non-interactive tool to get files from FTP, GOPHER, HTTP(S) servers pkg-1.1.4_6 New generation package manager Packages that are no longer needed can be removed with pkg delete. For example: &prompt.root; pkg delete curl The following packages will be deleted: curl-7.31.0_1 The deletion will free 3 MB Proceed with deleting packages [y/N]: y [1/1] Deleting curl-7.31.0_1... done Upgrading Installed Packages Packages that are outdated can be found with pkg version. If a local ports tree does not exist, pkg-version(8) will use the remote repository catalogue. Otherwise, the local ports tree will be used to identify package versions. Installed packages can be upgraded to their latest versions by typing pkg upgrade. This command will compare the installed versions with those available in the repository catalogue. When finished, it will list the applications that have newer versions. Type y to proceed with the upgrade or n to cancel the upgrade. Auditing Installed Packages Occasionally, software vulnerabilities may be discovered in third-party applications. To address this, pkgng includes a built-in auditing mechanism. To determine if there are any known vulnerabilities for the software installed on the system, run: &prompt.root; pkg audit -F Automatically Removing Leaf Dependencies Removing a package may leave behind dependencies which are no longer required. Unneeded packages that were installed as dependencies can be automatically detected and removed using: &prompt.root; pkg autoremove Packages to be autoremoved: ca_root_nss-3.13.5 The autoremoval will free 723 kB Proceed with autoremoval of packages [y/N]: y Deinstalling ca_root_nss-3.15.1_1... done Backing Up the Package Database Unlike the traditional package management system, pkgng includes its own package database backup mechanism. To manually back up the contents of the package database, run the following command, replacing pkgng.db with a suitable file name: &prompt.root; pkg backup -d pkgng.db Additionally, pkgng includes a &man.periodic.8; script to automatically perform a daily back up of the package database. This functionality is enabled if daily_backup_pkgng_enable is set to YES in &man.periodic.conf.5;. To disable the periodic script from backing up the package database, set daily_backup_pkgdb_ enable to NO in &man.periodic.conf.5;. To restore the contents of a previous package database backup, run: &prompt.root; pkg backup -r /path/to/pkgng.db Removing Stale Packages By default, pkgng stores binary packages in a cache directory defined by PKG_CACHEDIR in pkg.conf(5). When upgrading packages with pkg upgrade, old versions of the upgraded packages are not automatically removed. To remove these outdated binary packages, run: &prompt.root; pkg clean Modifying Package Metadata Software within the &os; Ports Collection can undergo major version number changes. To address this, pkgng has a built-in command to update package origins. This can be useful, for example, if lang/php5 is renamed to lang/php53 so that lang/php5 can now represent version 5.4. To change the package origin for the above example, run: &prompt.root; pkg set -o lang/php5:lang/php53 As another example, to update lang/ruby18 to lang/ruby19, run: &prompt.root; pkg set -o lang/ruby18:lang/ruby19 As a final example, to change the origin of the libglut shared libraries from graphics/libglut to graphics/freeglut, run: &prompt.root; pkg set -o graphics/libglut:graphics/freeglut When changing package origins, it is important to reinstall packages that are dependent on the package with the modified origin. To force a reinstallation of dependent packages, run: &prompt.root; pkg install -Rf graphics/freeglut Using the Ports Collection The Ports Collection is a set of Makefiles, patches, and description files stored in /usr/ports. This set of files is used to compile and install applications on &os;. Before an application can be compiled using a port, the Ports Collection must first be installed. If it was not installed during the installatio of &os;, use one of the following methods to install it: Portsnap Method Portsnap is a fast and user-friendly tool for retrieving the Ports Collection and is the recommended choice for most users. See for a detailed description of Portsnap. Download a compressed snapshot of the Ports Collection into /var/db/portsnap. &prompt.root; portsnap fetch When running Portsnap for the first time, extract the snapshot into /usr/ports: &prompt.root; portsnap extract After the first use of Portsnap has been completed as shown above, /usr/ports can be updated as needed by running: &prompt.root; portsnap fetch &prompt.root; portsnap update Subversion Method If more control over the ports tree is needed or if local changes need to be maintained, Subversion can be used to obtain the Ports Collection. Refer to the Subversion Primer for a detailed description of Subversion. Subversion must be installed before it can be used to check out the ports tree. If a copy of the ports tree is already present, install Subversion like this: &prompt.root; cd /usr/ports/devel/subversion &prompt.root; make install clean If the ports tree is not available, Subversion can be installed as a package: &prompt.root; pkg_add -r subversion If pkgng is being used to manage packages, Subversion can be installed with it instead: &prompt.root; pkg install subversion Check out a copy of the ports tree. For better performance, replace svn0.us-east.FreeBSD.org with a Subversion mirror close to your geographic location: &prompt.root; svn checkout https://svn0.us-east.FreeBSD.org/ports/head /usr/ports As needed, update /usr/ports after the initial Subversion checkout: &prompt.root; svn update /usr/ports The Ports Collection installs a series of directories representing software categories with each category having a subdirectory for each application. Each subdirectory, also referred to as a ports skeleton, contains a set of files that tell &os; how to compile and install that program. Each port skeleton includes these files and directories: Makefile: contains statements that specify how the application should be compiled and where its components should be installed. distinfo: contains the names and checksums of the files that must be downloaded to build the port. files/: this directory contains any patches needed for the program to compile and install on &os;. This directory may also contain other files used to build the port. pkg-descr: provides a more detailed description of the program. pkg-plist: a list of all the files that will be installed by the port. It also tells the ports system which files to remove upon deinstallation. Some ports include pkg-message or other files to handle special situations. For more details on these files, and on ports in general, refer to the &os; Porter's Handbook. The port does not include the actual source code, also known as a distfile. The extract portion of building a port will automatically save the downloaded source to /usr/ports/distfiles. Installing Ports ports installing This section provides basic instructions on using the Ports Collection to install or remove software. The detailed description of available make targets and environment variables is available in &man.ports.7;. Before compiling any port, be sure to update the Ports Collection as described in the previous section. Since the installation of any third-party software can introduce security vulnerabilities, it is recommended to first check for known security issues related to the port. Alternately, if ports-mgmt/portaudit is installed, run portaudit -F before installing a new port. This command can be configured to automatically perform a security audit and an update of the vulnerability database during the daily security system check. For more information, refer to the manual page for portaudit and &man.periodic.8;. Using the Ports Collection assumes a working Internet connection. It also requires superuser privilege. Some third-party DVD products such as the &os; Toolkit from freebsdmall.com contain distfiles which can be used to install ports without an Internet connection. Mount the DVD on /cdrom. If you use a different mount point, set the CD_MOUNTPTS make variable. The needed distfiles will be automatically used if they are present on the disk. However, the licenses of a few ports do not allow their inclusion on the DVD. This could be because a registration form needs to be filled out before downloading or redistribution is not allowed. In order to install a port not included on the DVD, a connection to the Internet will still be required. To compile and install the port, change to the directory of the port to be installed, then type make install at the prompt. Messages will indicate the progress: &prompt.root; cd /usr/ports/sysutils/lsof &prompt.root; make install >> lsof_4.88D.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.88 ... [extraction output snipped] ... >> Checksum OK for lsof_4.88D.freebsd.tar.gz. ===> Patching for lsof-4.88.d,8 ===> Applying FreeBSD patches for lsof-4.88.d,8 ===> Configuring for lsof-4.88.d,8 ... [configure output snipped] ... ===> Building for lsof-4.88.d,8 ... [compilation output snipped] ... ===> Installing for lsof-4.88.d,8 ... [installation output snipped] ... ===> Generating temporary packing list ===> Compressing manual pages for lsof-4.88.d,8 ===> Registering installation for lsof-4.88.d,8 ===> SECURITY NOTE: This port has installed the following binaries which execute with increased privileges. /usr/local/sbin/lsof &prompt.root; Since lsof is a program that runs with increased privileges, a security warning is displayed as it is installed. Once the installation is complete, the prompt will be returned. Some shells keep a cache of the commands that are available in the directories listed in the PATH environment variable, to speed up lookup operations for the executable file of these commands. Users of the tcsh shell should type rehash so that a newly installed command can be used without specifying its full path. Use hash -r instead for the sh shell. Refer to the documentation for the shell for more information. During installation, a working subdirectory is created which contains all the temporary files used during compilation. Removing this directory saves disk space and minimizes the chance of problems later when upgrading to the newer version of the port: &prompt.root; make clean ===> Cleaning for lsof-88.d,8 &prompt.root; To save this extra step, instead use make install clean when compiling the port. Customizing Ports Installation Some ports provide build options which can be used to enable or disable application components, provide security options, or allow for other customizations. Examples include www/firefox, security/gpgme, and mail/sylpheed-claws. If the port depends upon other ports which have configurable options, it may pause several times for user interaction as the default behavior is to prompt the user to select options from a menu. To avoid this, run make config-recursive within the port skeleton to do this configuration in one batch. Then, run make install [clean] to compile and install the port. When using config-recursive, the list of ports to configure are gathered by the all-depends-list target. It is recommended to run make config-recursive until all dependent ports options have been defined, and ports options screens no longer appear, to be certain that all dependency options have been configured. There are several ways to revisit a port's build options menu in order to add, remove, or change these options after a port has been built. One method is to cd into the directory containing the port and type make config. Another option is to use make showconfig. Another option is to execute make rmconfig which will remove all selected options and allow you to start over. All of these options, and others, are explained in great detail in &man.ports.7;. The ports system uses &man.fetch.1; to download the source files, which supports various environment variables. The FTP_PASSIVE_MODE, FTP_PROXY, and FTP_PASSWORD variables may need to be set if the &os; system is behind a firewall or FTP/HTTP proxy. See &man.fetch.3; for the complete list of supported variables. For users who cannot be connected to the Internet all the time, make fetch can be run within /usr/ports, to fetch all distfiles, or within a category, such as /usr/ports/net, or within the specific port skeleton. Note that if a port has any dependencies, running this command in a category or ports skeleton will not fetch the distfiles of ports from another category. Instead, use make fetch-recursive to also fetch the distfiles for all the dependencies of a port. In rare cases, such as when an organization has a local distfiles repository, the MASTER_SITES variable can be used to override the download locations specified in the Makefile. When using, specify the alternate location: &prompt.root; cd /usr/ports/directory &prompt.root; make MASTER_SITE_OVERRIDE= \ ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/ fetch The WRKDIRPREFIX and PREFIX variables can override the default working and target directories. For example: &prompt.root; make WRKDIRPREFIX=/usr/home/example/ports install will compile the port in /usr/home/example/ports and install everything under /usr/local. &prompt.root; make PREFIX=/usr/home/example/local install will compile the port in /usr/ports and install it in /usr/home/example/local. And: &prompt.root; make WRKDIRPREFIX=../ports PREFIX=../local install will combine the two. These can also be set as environmental variables. Refer to the manual page for your shell for instructions on how to set an environmental variable. Removing Installed Ports ports removing Installed ports can be uninstalled using &man.pkg.delete.1;. Alternately, if the &os; system has been configured to use pkg, a port can be uninstalled using pkg delete. Examples for using these commands can be found in and Alternately, make deinstall can be run in the port's directory: &prompt.root; cd /usr/ports/sysutils/lsof make deinstall ===> Deinstalling for sysutils/lsof ===> Deinstalling Deinstallation has been requested for the following 1 packages: lsof-4.88.d,8 The deinstallation will free 229 kB [1/1] Deleting lsof-4.88.d,8... done It is recommended to read the messages as the port is uninstalled. If the port has any applications that depend upon it, this information will be displayed but the uninstallation will proceed. In such cases, it may be better to reinstall the application in order to prevent broken dependencies. Upgrading Ports ports upgrading Over time, newer versions of software become available in the Ports Collection. This section describes how to determine which software can be upgraded and how to perform the upgrade. To determine if newer versions of installed ports are available, ensure that the latest version of the ports tree is installed, using the updating command described in either Procedure 5.1 or Procedure 5.2. Then, run this command to get a listing of the ports which are older than the currently available version: &prompt.root; pkg_version -l "<" Before attempting an upgrade, read /usr/ports/UPDATING from the top of the file to the date closest to the last time ports were upgraded or the system was installed. 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 any incompatibilities with previous versions. Make note of any instructions which match any of the ports that need upgrading and follow these instructions when performing the upgrade. To perform the actual upgrade, use either Portmaster or Portupgrade. Upgrading Ports Using <application>Portmaster</application> portmaster The ports-mgmt/portmaster package or port is the recommended tool for upgrading installed ports as it is designed to use the tools installed with &os; without depending upon other ports. It uses the information in /var/db/pkg/ to determine which ports to upgrade. To install this utility as a port: &prompt.root; cd /usr/ports/ports-mgmt/portmaster &prompt.root; make install clean Portmaster defines four categories of ports: Root port: has no dependencies and is not a dependency of any other ports. Trunk port: has no dependencies, but other ports depend upon it. Branch port: has dependencies and other ports depend upon it. Leaf port: has dependencies but no other ports depend upon it. To list these categories and search for updates: &prompt.root; portmaster -L ===>>> 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) ===>>> apache22-2.2.3 ===>>> New version available: apache22-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 This command is used to upgrade all outdated ports: &prompt.root; portmaster -a By default, Portmaster will make a backup package before deleting the existing port. If the installation of the new version is successful, Portmaster will delete the backup. Using will instruct Portmaster not to automatically delete the backup. Adding will start Portmaster in interactive mode, prompting for confirmation before upgrading each port. Many other options are available. Read through the manual page for portmaster(8) for details regarding their usage. If errors are encountered during the upgrade process, add to upgrade and rebuild all ports: &prompt.root; portmaster -af Portmaster can also be used to install new ports on the system, upgrading all dependencies before building and installing the new port. To use this function, specify the location of the port in the Ports Collection: &prompt.root; portmaster shells/bash Upgrading Ports Using Portupgrade portupgrade Another utility that can be used to upgrade ports is Portupgrade, which is available as the ports-mgmt/portupgrade package or port. This utility installs a suite of applications which can be used to manage ports. However, it is dependent upon Ruby. To install the port: &prompt.root; cd /usr/ports/ports-mgmt/portupgrade &prompt.root; make install clean Before performing an upgrade using this utility, it is recommended to scan the list of installed ports using pkgdb -F and to fix all the inconsistencies it reports. To upgrade all the outdated ports installed on the system, use portupgrade -a. Alternately, include to be asked for confirmation of every individual upgrade: &prompt.root; portupgrade -ai To upgrade only a specified application instead of all available ports, use portupgrade pkgname. It is very important to include to first upgrade all the ports required by the given application: &prompt.root; portupgrade -R firefox If is included, Portupgrade searches for available packages in the local directories listed in PKG_PATH. If none are available locally, it then fetches packages from a remote site. If packages can not be found locally or fetched remotely, Portupgrade will use ports. To avoid using ports entirely, specify . This last set of options tells Portupgrade to abort if no packages are available: &prompt.root; portupgrade -PP gnome2 To just fetch the port distfiles, or packages, if is specified, without building or installing anything, use . For further information on all of the available switches, refer to the manual page for portupgrade. Ports and Disk Space ports disk-space Using the Ports Collection will use up disk space over time. After building and installing a port, running make clean within the ports skeleton will clean up the temporary work directory. If Portmaster is used to install a port, it will automatically remove this directory unless is specified. If Portupgrade is installed, this command will remove all work directories found within the local copy of the Ports Collection: &prompt.root; portsclean -C In addition, a lot of out-dated source distribution files will collect in /usr/ports/distfiles over time. If Portupgrade is installed, this command will delete all the distfiles that are no longer referenced by any ports: &prompt.root; portsclean -D To use Portupgrade to remove all distfiles not referenced by any port currently installed on the system: &prompt.root; portsclean -DD If Portmaster is installed, use: &prompt.root; portmaster --clean-distfiles By default, this command is interactive and will prompt the user to confirm if a distfile should be deleted. In addition to these commands, the ports-mgmt/pkg_cutleaves package or port automates the task of removing installed ports that are no longer needed. Post-Installation Considerations Regardless of whether the software was installed from a binary package or port, most third-party applications require some level of configuration after installation. The following commands and locations can be used to help determine what was installed with the application. Most applications install at least one default configuration file in /usr/local/etc. The configuration files should be reviewed and possibly edited to meet the system's needs. Applications which provide documentation will install it into /usr/local/share/doc and many applications also install manual pages. This documentation should be consulted before continuing. Some applications run services which must be added to /etc/rc.conf before starting the application. These applications usually install a startup script in /usr/local/etc/rc.d. See Starting Services for more information. Users of &man.csh.1; should run rehash to rebuild the known binary list in the shells PATH. If the system is running the traditional package system, use &man.pkg.info.1; to determine which files, man pages, and binaries were installed with the application. If the system is running pkgng, instead use pkg info. Dealing with Broken Ports When a port does not build or install, try the following: Search to see if there is a fix pending for the port in the Problem Report database. If so, implementing the proposed fix may fix the issue. Ask the maintainer of the port for help. Type make maintainer in the ports skeleton or read the port's Makefile to find the maintainer's email address. Remember to include the $FreeBSD: line from the port's Makefile and the output leading up to the error in the email to the maintainer. Some ports are not maintained by an individual but instead by a mailing list. Many, but not all, of these addresses look like freebsd-listname@FreeBSD.org. Take this into account when sending an email. In particular, ports shown as maintained by ports@FreeBSD.org are not maintained by a specific individual. Instead, any fixes and support come from the general community who subscribe to that mailing list. More volunteers are always needed! If there is no response to the email, use &man.send-pr.1; to submit a bug report using the instructions in Writing &os; Problem Reports. Fix it! The Porter's Handbook includes detailed information on the ports infrastructure so that you can fix the occasional broken port or even submit your own! Install the package instead of the port using the instructions in or . diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.xml b/en_US.ISO8859-1/books/handbook/x11/chapter.xml index 1e998e6f1a..5c6147b893 100644 --- a/en_US.ISO8859-1/books/handbook/x11/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/x11/chapter.xml @@ -1,1755 +1,1767 @@ + + + --> The X Window System Synopsis An installation of &os; using bsdinstall does not automatically install a graphical user interface. This chapter describes how to install and configure &xorg;, which provides the open source X Window System used to provide a graphical environment. It then describes how to find and install a desktop environment or window manager. Users who prefer an installation method that automatically configures the &xorg; and offers a choice of window managers during installation should refer to the pcbsd.org website. For more information on the video hardware that &xorg; supports, refer to the x.org website. After reading this chapter, you will know: The various components of the X Window System, and how they interoperate. How to install and configure &xorg;. How to install and configure several window managers and desktop environments. How to use &truetype; fonts in &xorg;. How to set up your system for graphical logins (XDM). Before reading this chapter, you should: Know how to install additional third-party software as described in . Terminology While it is not necessary to understand all of the details of the various components in the X Window System and how they interact, some basic knowledge of these components can be useful: X server X was designed from the beginning to be network-centric, and adopts a client-server model. In this model, the X server 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 handling input or output from other devices such as a tablet or a video projector. This confuses some people, because the X terminology is exactly backward to what they expect. They expect the X server to be the big powerful machine down the hall, and the X client to be the machine on their desk. X client Each X application, such as XTerm or Firefox, is a client. A client sends messages to the server such as Please draw a window at these coordinates, and the server sends back messages such as The user just clicked on the OK button. In a home or small office environment, the X server and the X clients commonly run on the same computer. It is also possible to run the X server on a less powerful computer and to run the X applications on a more powerful system. In this scenario, the communication between the X client and server takes place over the network. window manager X does not dictate what windows should look like on screen, how to move them around with the mouse, which keystrokes should be used to move between windows, what the title bars on each window should look like, whether or not they have close buttons on them, and so on. Instead, X delegates this responsibility to a separate window manager application. There are dozens of window managers available. Each window manager provides a different look and feel: some support virtual desktops, some allow customized keystrokes to manage the desktop, some have a Start button, and some are themeable, allowing a complete change of the desktop's look-and-feel. Window managers are available in the x11-wm category of the Ports Collection. Each window manager uses a different configuration mechanism. Some expect configuration file written by hand while others provide graphical tools for most configuration tasks. desktop environment KDE and GNOME are considered to be desktop environments as they include an entire suite of applications for performing common desktop tasks. These may include office suites, web browsers, and games. focus policy The window manager is responsible for the mouse focus policy. This policy provides some means for choosing which window is actively receiving keystrokes and it should also visibly indicate which window is currently active. One focus policy is called click-to-focus. In this model, a window becomes active upon receiving a mouse click. In the focus-follows-mouse policy, the window that is under the mouse pointer has focus and the focus is changed by pointing at another window. If the mouse is over the root window, then this window is focused. In the sloppy-focus model, if the mouse is moved over the root window, the most recently used window still has the focus. With sloppy-focus, focus is only changed when the cursor enters a new window, and not when exiting the current window. In the click-to-focus policy, the active window is selected by mouse click. The window may then be raised 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. Different window managers support different focus models. All of them support click-to-focus, and the majority of them also support other policies. Consult the documentation for the window manager to determine which focus models are available. widgets Widget is a term for all of the items in the user interface that can be clicked or manipulated in some way. This includes buttons, check boxes, radio buttons, icons, and lists. A widget toolkit is a set of widgets used to create graphical applications. There are several popular widget toolkits, including Qt, used by KDE, and GTK+, used by GNOME. As a result, applications will have a different look and feel, depending upon which widget toolkit was used to create the application. Installing <application>&xorg;</application> &xorg; is the implementation of the open source X Window System released by the X.Org Foundation. In &os;, it can be installed as a package or port. The meta-port for the complete distribution which includes X servers, clients, libraries, and fonts is located in x11/xorg. A minimal distribution is located in x11/xorg-minimal, with separate ports available for docs, libraries, and apps. The examples in this section install the complete &xorg; distribution. To build and install &xorg; from the Ports Collection: &prompt.root; cd /usr/ports/x11/xorg &prompt.root; make install clean To build &xorg; in its entirety, be sure to have at least 4 GB of free disk space available. Alternatively, &xorg; can be installed directly from packages. To install the package using pkg_add, type: &prompt.root; pkg_add -r xorg To instead install the package using pkg, type: &prompt.root; pkg install xorg + + + --> <application>&xorg;</application> Configuration &xorg; &xorg; In most cases, &xorg; is self-configuring. Those with older or unusual equipment may find it helpful to gather some hardware information before beginning configuration. Monitor sync frequencies Video card chipset Video card memory horizontal sync frequency horizontal scan rate horizontal sync frequency refresh rate vertical sync frequency refresh rate vertical scan rate refresh rate Screen resolution and refresh rate are determined by the monitor's horizontal and vertical sync frequencies. Almost all monitors support electronic autodetection of these values. A few monitors do not provide these values, and the specifications must be determined from the printed manual or manufacturer web site. The video card chipset is also autodetected, and used to select the proper video driver. It is beneficial for the user to be aware of which chipset is installed for when autodetection does not provide the desired result. Video card memory determines the maximum resolution and color depth which can be displayed. Caveats The ability to configure optimal resolution is dependent upon the video hardware and the support provided by its driver. At this time, driver support is as follows: NVIDIA: several NVIDIA drivers are available in the x11 category of the FreeBSD Ports Collection. Install the driver that matches the model of the NVIDIA hardware. Intel: as of FreeBSD 9.1, 3D acceleration on most Intel graphics, including IronLake, SandyBridge, and IvyBridge, is supported. Due to the current KMS implementation, it is not possible to switch between the graphical console and a virtual console using Crtl+Alt+F#. ATI/Radeon: 3D acceleration will not work on ATI or Radeon cards until FreeBSD completes its TTM work. These cards will need to be configured with the 2D driver, and if that does not work, with the Vesa driver. Optimus: currently there is no switching support between the two graphics adapters provided by Optimus. Optimus implementations vary, so FreeBSD may or may not be able to successfully load a graphics driver on all hardware. If you get a blank screen, check if the BIOS has an option to disable one of the graphics adapters or to set discrete mode. Configuring <application>&xorg;</application> &xorg; uses HAL to autodetect keyboards and mice. The sysutils/hal and devel/dbus ports are automatically installed as dependencies of x11/xorg, but must be enabled by adding the following entries to /etc/rc.conf: hald_enable="YES" dbus_enable="YES" Start these services before configuring &xorg;: &prompt.root; service hald start &prompt.root; service dbus start Once these services are started, check if &xorg; auto-configures itself by typing: &prompt.root; Xorg -configure This will generate a file named /root/xorg.conf.new which attempts to load the proper drivers for the detected hardware. Next, test that the automatically generated configuration file works with the graphics hardware by typing: &prompt.root; Xorg -config xorg.conf.new -retro 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 Ctrl Alt Fn (F1 for the first virtual console) and press Ctrl C . The Ctrl Alt Backspace key combination may also be used to break out of &xorg;. To enable it, you can either type the following command from any X terminal emulator: &prompt.user; setxkbmap -option terminate:ctrl_alt_bksp or create a keyboard configuration file for hald called x11-input.fdi and saved in the /usr/local/etc/hal/fdi/policy directory. This file should contain the following lines: <?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> You will have to reboot your machine to force hald to read this file. The following line will also have to be added to xorg.conf.new, in the ServerLayout or ServerFlags section: Option "DontZap" "off" If the test is unsuccessful, skip ahead to . Once the test is successful, copy the configuration file to /etc/X11/xorg.conf: &prompt.root; cp xorg.conf.new /etc/X11/xorg.conf Desktop environments like GNOME, KDE or Xfce provide graphical tools to set parameters such as video resolution. If the default configuration works, skip to for examples on how to install a desktop environment. + + + --> Using Fonts in <application>&xorg;</application> Type1 Fonts The default fonts that ship with &xorg; are less than ideal for typical desktop publishing applications. Large presentation fonts show up jagged and unprofessional looking, and small fonts are almost completely unintelligible. However, there are several free, high quality Type1 (&postscript;) fonts available which can be readily used with &xorg;. For instance, the URW font collection (x11-fonts/urwfonts) includes high quality versions of standard type1 fonts (Times Roman, Helvetica, Palatino and others). The Freefonts collection (x11-fonts/freefonts) includes many more fonts, but most of them are intended for use in graphics software such as the Gimp, and are not complete enough to serve as screen fonts. In addition, &xorg; 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 section on &truetype; fonts. To install the above Type1 font collections from the Ports Collection, run the following commands: &prompt.root; cd /usr/ports/x11-fonts/urwfonts &prompt.root; make install clean 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 (/etc/X11/xorg.conf), which reads: FontPath "/usr/local/lib/X11/fonts/URW/" Alternatively, at the command line in the X session run: &prompt.user; xset fp+ /usr/local/lib/X11/fonts/URW &prompt.user; xset fp rehash This will work but will be lost when the X session is closed, unless it is added to the startup file (~/.xinitrc for a normal startx session, or ~/.xsession when logging in through a graphical login manager like XDM). A third way is to use the new /usr/local/etc/fonts/local.conf file: see the section on anti-aliasing. &truetype; Fonts TrueType Fonts fonts TrueType &xorg; 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 "Module" section of the /etc/X11/xorg.conf file. Load "freetype" Now make a directory for the &truetype; fonts (for example, /usr/local/lib/X11/fonts/TrueType) 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 &xorg;. Once the files have been copied into this directory, use ttmkfdir to create a fonts.dir file, so that the X font renderer knows that these new files have been installed. ttmkfdir is available from the FreeBSD Ports Collection as x11-fonts/ttmkfdir. &prompt.root; cd /usr/local/lib/X11/fonts/TrueType &prompt.root; ttmkfdir -o fonts.dir Now add the &truetype; directory to the font path. This is just the same as described above for Type1 fonts, that is, use &prompt.user; xset fp+ /usr/local/lib/X11/fonts/TrueType &prompt.user; xset fp rehash or add a FontPath line to the xorg.conf file. That's it. Now Gimp, Apache OpenOffice, 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 &staroffice;) will look much better now. + + + --> Anti-Aliased Fonts anti-aliased fonts fonts anti-aliased All fonts in &xorg; that are found in /usr/local/lib/X11/fonts/ and ~/.fonts/ are automatically made available for anti-aliasing to Xft-aware applications. Most recent applications are Xft-aware, including KDE, GNOME, and Firefox. In order to control which fonts are anti-aliased, or to configure anti-aliasing properties, create (or edit, if it already exists) the file /usr/local/etc/fonts/local.conf. 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;. XML 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 <fontconfig> tag: <?xml version="1.0"?> <!DOCTYPE fontconfig SYSTEM "fonts.dtd"> <fontconfig> As previously stated, all fonts in /usr/local/lib/X11/fonts/ as well as ~/.fonts/ 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 /usr/local/etc/fonts/local.conf: <dir>/path/to/my/fonts</dir> After adding new fonts, and especially new font directories, you should run the following command to rebuild the font caches: &prompt.root; fc-cache -f Anti-aliasing makes borders slightly fuzzy, which makes very small text more readable and removes staircases 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: <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> fonts spacing Spacing for some monospaced fonts may also be inappropriate with anti-aliasing. This seems to be an issue with KDE, in particular. One possible fix for this is to force the spacing for such fonts to be 100. Add the following lines: <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> (this aliases the other common names for fixed fonts as "mono"), and then add: <match target="pattern" name="family"> <test qual="any" name="family"> <string>mono</string> </test> <edit name="spacing" mode="assign"> <int>100</int> </edit> </match> 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 local.conf: <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> Once you have finished editing local.conf make sure you end the file with the </fontconfig> tag. Not doing this will cause your changes to be ignored. Finally, users can add their own settings via their personal .fonts.conf files. To do this, each user should simply create a ~/.fonts.conf. This file must also be in XML format. LCD screen Fonts LCD screen 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 local.conf file: <match target="font"> <test qual="all" name="rgba"> <const>unknown</const> </test> <edit name="rgba" mode="assign"> <const>rgb</const> </edit> </match> Depending on the sort of display, rgb may need to be changed to bgr, vrgb or vbgr: experiment and see which works best. + + + --> The X Display Manager Overview X Display Manager The X Display Manager (XDM) 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 X Terminals, 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. XDM provides a graphical interface for choosing which display server to connect to, and entering authorization information such as a login and password combination. Think of XDM as providing the same functionality to the user as the &man.getty.8; utility (see 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). XDM then waits for this program to exit, signaling that the user is done and should be logged out of the display. At this point, XDM can display the login and display chooser screens for the next user to login. Using XDM To start using XDM, install the x11/xdm port (it is not installed by default in recent versions of &xorg;). The XDM daemon program may then be found in /usr/local/bin/xdm. This program can be run at any time as root and it will start managing the X display on the local machine. If XDM is to be run every time the machine boots up, a convenient way to do this is by adding an entry to /etc/ttys. For more information about the format and usage of this file, see . There is a line in the default /etc/ttys file for running the XDM daemon on a virtual terminal: ttyv8 "/usr/local/bin/xdm -nodaemon" xterm off secure By default this entry is disabled; in order to enable it change field 5 from off to on and restart &man.init.8; using the directions in . The first field, the name of the terminal this program will manage, is ttyv8. This means that XDM will start running on the 9th virtual terminal. Configuring XDM The XDM configuration directory is located in /usr/local/lib/X11/xdm. In this directory there are several files used to change the behavior and appearance of XDM. Typically these files will be found: File Description Xaccess Client authorization ruleset. Xresources Default X resource values. Xservers List of remote and local displays to manage. Xsession Default session script for logins. Xsetup_* Script to launch applications before the login interface. xdm-config Global configuration for all displays running on this machine. xdm-errors Errors generated by the server program. xdm-pid The process ID of the currently running XDM. Also in this directory are a few scripts and programs used to set up the desktop when XDM 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;. The default configuration is a simple rectangular login window with the hostname of the machine displayed at the top in a large font and Login: and Password: prompts below. This is a good starting point for changing the look and feel of XDM screens. Xaccess The protocol for connecting to XDM-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 xdm-config is changed to listen for remote connections. By default, it does not allow any clients to connect. Xresources 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 &xorg; documentation. Xservers This is a list of the remote displays the chooser should provide as choices. Xsession This is the default session script for XDM to run after a user has logged in. Normally each user will have a customized session script in ~/.xsession that overrides this script. Xsetup_* These will be run automatically before displaying the chooser or login interfaces. There is a script for each display being used, named Xsetup_ followed by the local display number (for instance Xsetup_0). Typically these scripts will run one or two programs in the background such as xconsole. xdm-config This contains settings in the form of app-defaults that are applicable to every display that this installation manages. xdm-errors This contains the output of the X servers that XDM is trying to run. If a display that XDM 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 ~/.xsession-errors file on a per-session basis. Running a Network Display Server 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 XDM listen for connections, first comment out a line in the xdm-config file: ! 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 and then restart XDM. Remember that comments in app-defaults files begin with a ! character, not the usual #. More strict access controls may be desired — look at the example entries in Xaccess, and refer to the &man.xdm.1; manual page for further information. Replacements for XDM Several replacements for the default XDM program exist. One of them, KDM (bundled with KDE) is described later in this chapter. The KDM 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. + + + --> Desktop Environments This section describes the different desktop environments available for X on FreeBSD. A desktop environment can mean anything ranging from a simple window manager to a complete suite of desktop applications, such as KDE or GNOME. GNOME About GNOME GNOME GNOME is a user-friendly desktop environment that enables users to easily use and configure their computers. GNOME 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, anda 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 GNOME provides. More information regarding GNOME on FreeBSD can be found on the FreeBSD GNOME Project's web site. The web site also contains fairly comprehensive FAQs about installing, configuring, and managing GNOME. Installing GNOME The software can be easily installed from a package or the Ports Collection: To install the GNOME package from the network, simply type: &prompt.root; pkg_add -r gnome2 For pkgng users, the equivalent command is: &prompt.root; pkg install gnome2 To build GNOME from source, use the ports tree: &prompt.root; cd /usr/ports/x11/gnome2 &prompt.root; make install clean For proper operation, GNOME requires the /proc filesystem to be mounted. Add proc /proc procfs rw 0 0 to /etc/fstab to mount &man.procfs.5; automatically during startup. Once GNOME is installed, the X server must be told to start GNOME instead of a default window manager. The easiest way to start GNOME is with GDM, the GNOME Display Manager. GDM is installed as part of the GNOME desktop, although it is disabled by default. It can be enabled by adding this line to /etc/rc.conf: gdm_enable="YES" Once you have rebooted, GDM will start automatically. It is often desirable to start all GNOME services together with GDM. To achieve this, add the following line to /etc/rc.conf: gnome_enable="YES" GNOME may also be started from the command-line by properly configuring a file named .xinitrc. If a custom .xinitrc is already in place, simply replace the line that starts the current window manager with one that starts /usr/local/bin/gnome-session instead. If nothing special has been done to the configuration file, then it is enough simply to type: &prompt.user; echo "/usr/local/bin/gnome-session" > ~/.xinitrc Next, type startx, and the GNOME desktop environment will be started. If an older display manager, like XDM, is being used, this will not work. Instead, create an executable .xsession file with the same command in it. To do this, edit the file and replace the existing window manager command with /usr/local/bin/gnome-session: &prompt.user; echo "#!/bin/sh" > ~/.xsession &prompt.user; echo "/usr/local/bin/gnome-session" >> ~/.xsession &prompt.user; chmod +x ~/.xsession Yet another option is to configure the display manager to allow choosing the window manager at login time; the section on KDE details explains how to do this for KDM, the display manager of KDE. KDE KDE About KDE KDE is an easy to use contemporary desktop environment. Some of the things that KDE brings to the user are: A beautiful contemporary desktop A desktop exhibiting complete network transparency An integrated help system allowing for convenient, consistent access to help on the use of the KDE desktop and its applications Consistent look and feel of all KDE applications Standardized menu and toolbars, keybindings, color-schemes, etc. Internationalization: KDE is available in more than 55 languages Centralized, consistent, dialog-driven desktop configuration A great number of useful KDE applications KDE comes with a web browser called Konqueror, which is a solid competitor to other existing web browsers on &unix; systems. More information on KDE can be found on the KDE website. For FreeBSD specific information and resources on KDE, consult the KDE/FreeBSD initiative's website. Installing KDE Just as with GNOME or any other desktop environment, the software can be easily installed from a package or the Ports Collection: To install the KDE 4 package from the network, type: &prompt.root; pkg_add -r kde4 &man.pkg.add.1; will automatically fetch the latest version of the application. For pkgng users, the equivalent command is: &prompt.root; pkg install kde4 To build KDE from source, use the ports tree: &prompt.root; cd /usr/ports/x11/kde4 &prompt.root; make install clean The first time the port is installed, a menu will be shown for selecting options. Accepting the defaults is recommended. KDE 4 is a large application, and will take quite some time to compile even on a fast computer. After KDE 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 .xinitrc file: &prompt.user; echo "exec /usr/local/kde4/bin/startkde" > ~/.xinitrc Now, whenever the X Window System is invoked with startx, KDE will be the desktop. If a display manager such as XDM is being used, the configuration is slightly different. Edit the .xsession file instead. Instructions for KDM are described later in this chapter. More Details on KDE Now that KDE 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. The best reference for KDE is the on-line documentation. KDE comes with its own web browser, Konqueror, dozens of useful applications, and extensive documentation. The remainder of this section discusses the technical items that are difficult to learn by random exploration. The KDE Display Manager KDE display manager An administrator of a multi-user system may wish to have a graphical login screen to welcome users. XDM can be used, as described earlier. However, KDE includes an alternative, KDM, 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 (KDE, GNOME, or something else) to run after logging on. KDE 4 requires that &man.procfs.5; be mounted, and this line must be added to /etc/rc.conf: kdm4_enable="YES" Xfce About Xfce Xfce is a desktop environment based on the GTK+ toolkit used by GNOME, 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 CDE, found on commercial &unix; systems. Some of Xfce's features are: A simple, easy-to-handle desktop Fully configurable via mouse, with drag and drop, etc. Main panel similar to CDE, with menus, applets and applications launchers Integrated window manager, file manager, sound manager, GNOME compliance module, and more Themeable (since it uses GTK+) Fast, light and efficient: ideal for older/slower machines or machines with memory limitations More information on Xfce can be found on the Xfce website. Installing Xfce To install the Xfce from the network, simply type: &prompt.root; pkg_add -r xfce4 For pkgng users, the equivalent command is: &prompt.root; pkg install xfce4 Alternatively, to build from source, use the Ports Collection: &prompt.root; cd /usr/ports/x11-wm/xfce4 &prompt.root; make install clean Now, tell the X server to launch Xfce the next time X is started. Simply type this: &prompt.user; echo "/usr/local/bin/startxfce4" > ~/.xinitrc The next time X is started, Xfce will be the desktop. As before, if a display manager like XDM is being used, create an .xsession, as described in the section on GNOME, but with the /usr/local/bin/startxfce4 command; or, configure the display manager to allow choosing a desktop at login time, as explained in the section on kdm. Troubleshooting If the mouse does not work, you will need to first configure it before proceeding. See in the &os; install chapter. In recent Xorg versions, the InputDevice sections in xorg.conf are ignored in favor of the autodetected devices. To restore the old behavior, add the following line to the ServerLayout or ServerFlags section of this file: Option "AutoAddDevices" "false" Input devices may then be configured as in previous versions, along with any other options needed (e.g., keyboard layout switching). As previously explained the hald daemon will, by default, automatically detect your keyboard. There are chances that your keyboard layout or model will not be correct, desktop environments like GNOME, KDE or Xfce 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 hald's configuration rule. 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 hald called x11-input.fdi and saved in the /usr/local/etc/hal/fdi/policy directory. This file should contain the following lines: <?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> If this file already exists, just copy and add to your file the lines regarding the keyboard configuration. You will have to reboot your machine to force hald to read this file. It is possible to do the same configuration from an X terminal or a script with this command line: &prompt.user; setxkbmap -model pc102 -layout fr The /usr/local/share/X11/xkb/rules/base.lst file lists the various keyboard, layouts and options available. &xorg; tuning The xorg.conf.new configuration file may now be tuned to taste. Open the file in a text editor such as &man.emacs.1; or &man.ee.1;. If the monitor is an older or unusual model that does not support autodetection of sync frequencies, those settings can be added to xorg.conf.new under the "Monitor" section: Section "Monitor" Identifier "Monitor0" VendorName "Monitor Vendor" ModelName "Monitor Model" HorizSync 30-107 VertRefresh 48-120 EndSection Most monitors support sync frequency autodetection, making manual entry of these values unnecessary. For the few monitors that do not support autodetection, avoid potential damage by only entering values provided by the manufacturer. 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: Option "DPMS" xorg.conf While the xorg.conf.new configuration file is still open in an editor, select the default resolution and color depth desired. This is defined in the "Screen" section: Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" DefaultDepth 24 SubSection "Display" Viewport 0 0 Depth 24 Modes "1024x768" EndSubSection EndSection The DefaultDepth keyword describes the color depth to run at by default. This can be overridden with the command line switch to &man.Xorg.1;. The Modes 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. Finally, write the configuration file and test it using the test mode given above. One of the tools available to assist you during troubleshooting process are the &xorg; log files, which contain information on each device that the &xorg; server attaches to. &xorg; log file names are in the format of /var/log/Xorg.0.log. The exact name of the log can vary from Xorg.0.log to Xorg.8.log and so forth. 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 /etc/X11/xorg.conf or /usr/local/etc/X11/xorg.conf. &prompt.root; cp xorg.conf.new /etc/X11/xorg.conf The &xorg; configuration process is now complete. &xorg; may be now started with the &man.startx.1; utility. The &xorg; server may also be started with the use of &man.xdm.1;. Configuration with &intel; <literal>i810</literal> Graphics Chipsets Intel i810 graphic chipset Configuration with &intel; i810 integrated chipsets requires the agpgart AGP programming interface for &xorg; to drive the card. See the &man.agp.4; driver manual page for more information. 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 /boot/loader.conf. Adding a Widescreen Flatpanel to the Mix widescreen flatpanel configuration 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. 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: 2560x1600 1920x1200 1680x1050 1440x900 1280x800 At some point, it will be as easy as adding one of these resolutions as a possible Mode in the Section "Screen" as such: Section "Screen" Identifier "Screen0" Device "Card0" Monitor "Monitor0" DefaultDepth 24 SubSection "Display" Viewport 0 0 Depth 24 Modes "1680x1050" EndSubSection EndSection &xorg; 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. If those ModeLines do not exist in the drivers, one might need to give &xorg; a little hint. Using /var/log/Xorg.0.log one can extract enough information to manually create a ModeLine that will work. Simply look for information resembling this: (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 This information is called EDID information. Creating a ModeLine from this is just a matter of putting the numbers in the correct order: ModeLine <name> <clock> <4 horiz. timings> <4 vert. timings> So that the ModeLine in Section "Monitor" for this example would look like this: Section "Monitor" Identifier "Monitor1" VendorName "Bigname" ModelName "BestModel" ModeLine "1680x1050" 146.2 1680 1784 1960 2240 1050 1053 1059 1089 Option "DPMS" EndSection Now having completed these simple editing steps, X should start on your new widescreen monitor.