diff --git a/en_US.ISO8859-1/books/handbook/config/chapter.sgml b/en_US.ISO8859-1/books/handbook/config/chapter.sgml index 2c2481eec3..eb1bbfe2c2 100644 --- a/en_US.ISO8859-1/books/handbook/config/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/config/chapter.sgml @@ -1,2317 +1,2317 @@ Chern Lee Written by Mike Smith Based on a tutorial written by Matt Dillon Also based on tuning(7) written by Configuration and Tuning Synopsis system configuration system optimization One of the important aspects of FreeBSD is system configuration. Correct system configuration will help prevent headaches during future upgrades. This chapter will explain much of the FreeBSD configuration process, including some of the parameters which can be set to tune a FreeBSD system. After reading this chapter, you will know: How to efficiently work with file systems and swap partitions. The basics of rc.conf configuration and /usr/local/etc/rc.d startup systems. How to configure and test a network card. How to configure virtual hosts on your network devices. How to use the various configuration files in /etc. How to tune FreeBSD using sysctl variables. How to tune disk performance and modify kernel limitations. Before reading this chapter, you should: Understand Unix and FreeBSD basics (). Be familiar with keeping FreeBSD sources up to date (), and the basics of kernel configuration/compilation (). Initial Configuration Partition Layout Partition layout /etc /var /usr Base Partitions When laying out file systems with &man.disklabel.8; or &man.sysinstall.8;, remember that hard drives transfer data faster from the outer tracks to the inner. Thus smaller and heavier-accessed file systems should be closer to the outside of the drive While larger partitions like /usr should be placed toward the inner. It is a good idea to create partitions in a similar order to: root, swap, /var, /usr. The size of /var reflects the intended machine usage. /var is used to hold mailboxes, log files, and printer spools. Mailboxes and log files can grow to unexpected sizes depending on how many users exist and how long log files are kept. Most users would never require a gigabyte, but remember that /var/tmp must be large enough to contain packages. The /usr partition holds much of the files required to support the system, the &man.ports.7; collection (recommended) and the source code (optional). Both of which are optional at install time. At least 2 gigabytes would be recommended for this partition. When selecting partition sizes, keep the space requirements in mind. Running out of space in one partition while barely using another can be a hassle. Some users have found that &man.sysinstall.8;'s Auto-defaults partition sizer will sometimes select smaller than adequate /var and / partitions. Partition wisely and generously. Swap Partition swap sizing swap partition As a rule of thumb, the swap partition should be about double the size of system memory (RAM). For example, if the machine has 128 megabytes of memory, the swap file should be 256 megabytes. Systems with less memory may perform better with more swap. Less than 256 megabytes of swap is not recommended and memory expansion should be considered. The kernel's VM paging algorithms are tuned to perform best when the swap partition is at least two times the size of main memory. Configuring too little swap can lead to inefficiencies in the VM page scanning code and might create issues later if more memory is added. On larger systems with multiple SCSI disks (or multiple IDE disks operating on different controllers), it is recommend that a swap is configured on each drive (up to four drives). The swap partitions should be approximately the same size. The kernel can handle arbitrary sizes but internal data structures scale to 4 times the largest swap partition. Keeping the swap partitions near the same size will allow the kernel to optimally stripe swap space across disks. Large swap sizes are fine, even if swap is not used much. It might be easier to recover from a runaway program before being forced to reboot. Why Partition? Several users think a single large partition will be fine, but there are several reasons why this is a bad idea. First, each partition has different operational characteristics and separating them allows the file system to tune accordingly. For example, the root and /usr partitions are read-mostly, without much writing. While a lot of reading and writing could occur in /var and /var/tmp. By properly partitioning a system, fragmentation introduced in the smaller write heavy partitions will not bleed over into the mostly-read partitions. Keeping the write-loaded partitions closer to the disk's edge, will increase I/O performance in the partitions where it occurs the most. Now while I/O performance in the larger partitions may be needed, shifting them more toward the edge of the disk will not lead to a significant performance improvement over moving /var to the edge. Finally, there are safety concerns. A smaller, neater root partition which is mostly read-only has a greater chance of surviving a bad crash. Core Configuration rc files rc.conf The principal location for system configuration information is within /etc/rc.conf. This file contains a wide range of configuration information, principally used at system startup to configure the system. Its name directly implies this; it is configuration information for the rc* files. An administrator should make entries in the rc.conf file to override the default settings from /etc/defaults/rc.conf. The defaults file should not be copied verbatim to /etc - it contains default values, not examples. All system-specific changes should be made in the rc.conf file itself. A number of strategies may be applied in clustered applications to separate site-wide configuration from system-specific configuration in order to keep administration overhead down. The recommended approach is to place site-wide configuration into another file, such as /etc/rc.conf.site, and then include this file into /etc/rc.conf, which will contain only system-specific information. As rc.conf is read by &man.sh.1; it is trivial to achieve this. For example: rc.conf: . rc.conf.site hostname="node15.example.com" network_interfaces="fxp0 lo0" ifconfig_fxp0="inet 10.1.1.1" rc.conf.site: defaultrouter="10.1.1.254" saver="daemon" blanktime="100" The rc.conf.site file can then be distributed to every system using rsync or a similar program, while the rc.conf file remains unique. Upgrading the system using &man.sysinstall.8; or make world will not overwrite the rc.conf file, so system configuration information will not be lost. Application Configuration Typically, installed applications have their own configuration files, with their own syntax, etc. It is important that these files be kept separate from the base system, so that they may be easily located and managed by the package management tools. /usr/local/etc Typically, these files are installed in /usr/local/etc. In the case where an application has a large number of configuration files, a subdirectory will be created to hold them. Normally, when a port or package is installed, sample configuration files are also installed. These are usually identified with a .default suffix. If there are no existing configuration files for the application, they will be created by copying the .default files. For example, consider the contents of the directory /usr/local/etc/apache: -rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf -rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf.default -rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf -rw-r--r-- 1 root wheel 9555 May 20 1998 httpd.conf.default -rw-r--r-- 1 root wheel 12205 May 20 1998 magic -rw-r--r-- 1 root wheel 12205 May 20 1998 magic.default -rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types -rw-r--r-- 1 root wheel 2700 May 20 1998 mime.types.default -rw-r--r-- 1 root wheel 7980 May 20 1998 srm.conf -rw-r--r-- 1 root wheel 7933 May 20 1998 srm.conf.default The file sizes show that only the srm.conf file has been changed. A later update of the Apache port would not overwrite this changed file. Starting Services services It is common for a system to host a number of services. These may be started in several different fashions, each having different advantages. /usr/local/etc/rc.d Software installed from a port or the packages collection will often place a script in /usr/local/etc/rc.d which is invoked at system startup with a argument, and at system shutdown with a argument. This is the recommended way for starting system-wide services that are to be run as root, or that expect to be started as root. These scripts are registered as part of the installation of the package, and will be removed when the package is removed. A generic startup script in /usr/local/etc/rc.d looks like: #!/bin/sh echo -n ' FooBar' case "$1" in start) /usr/local/bin/foobar ;; stop) kill -9 `cat /var/run/foobar.pid` ;; *) echo "Usage: `basename $0` {start|stop}" >&2 exit 64 ;; esac exit 0 The startup scripts of FreeBSD will look in /usr/local/etc/rc.d for scripts that have an .sh extension and are executable by root. Those scripts that are found are called with an option at startup, and at shutdown to allow them to carry out their purpose. So if you wanted the above sample script to be picked up and run at the proper time during system startup, you should save it to a file called FooBar.sh in /usr/local/etc/rc.d and make sure it is executable. You can make a shell script executable with &man.chmod.1; as shown below: &prompt.root; chmod 755 FooBar.sh Some services expect to be invoked by &man.inetd.8; when a connection is received on a suitable port. This is common for mail reader servers (POP and IMAP, etc.). These services are enabled by editing the file /etc/inetd.conf. See &man.inetd.8; for details on editing this file. Some additional system services may not be covered by the toggles in /etc/rc.conf. These are traditionally enabled by placing the command(s) to invoke them in /etc/rc.local. As of FreeBSD 3.1 there is no default /etc/rc.local; if it is created by the administrator it will however be honored in the normal fashion. Note that rc.local is generally regarded as the location of last resort; if there is a better place to start a service, do it there. Do not place any commands in /etc/rc.conf. To start daemons, or run any commands at boot time, place a script in /usr/local/etc/rc.d instead. It is also possible to use the &man.cron.8; daemon to start system services. This approach has a number of advantages, not least being that because &man.cron.8; runs these processes as the owner of the crontab, services may be started and maintained by non-root users. This takes advantage of a feature of &man.cron.8;: the time specification may be replaced by @reboot, which will cause the job to be run when &man.cron.8; is started shortly after system boot. Tom Rhodes Contributed by Configuring the <command>cron</command> utility Configuring the cron utility One of the most useful utilities in FreeBSD is &man.cron.8;. The cron utility runs in the background and constantly checks the /etc/crontab file. The cron utility also checks the /var/cron/tabs directory, in search of new crontab files. These crontab files store information about specific functions which cron is supposed to perform at certain times. Let us take a look at the /etc/crontab file: # /etc/crontab - root's crontab for FreeBSD # # $FreeBSD: src/etc/crontab,v 1.32 2002/11/22 16:13:39 tom Exp $ # # SHELL=/bin/sh PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin HOME=/var/log # # #minute hour mday month wday who command # # */5 * * * * root /usr/libexec/atrun Like most &os; configuration files, the # character represents a comment. A comment can be placed in the file as a reminder of what and why a desired action is performed. Comments cannot be on the same line as a command or else they will be interpreted as part of the command; they must be on a new line. Blank lines are ignored. First, the environment must be defined. The equals (= character is used to define any environment settings, as with this example where it is used for the , , and options. If the shell line is omitted, cron will use the default, which is sh. If the variable is omitted, no default will be used and file locations will need to be absolute. If is omitted, cron will use the invoking users home directory. This line defines a total of seven fields. Listed here are the values minute, hour, mday, month, wday, who, and command. These are almost all self explanatory. Minute is the time in minutes the command will be run. Hour is similar to the minute option, just in hours. Mday stands for day of the month. Month is similar to hour and minute, as it designates the month. The wday options stands for day of the week. All these fields must be numeric values, and follow the twenty-four hour clock. The who field is special, and only exists in the /etc/crontab file. This field specifies which user the command should be run as. When a user installs his or her crontab file, they will not have this option. Finally, the command option is listed. This is the last field, so naturally it should designate the command to be executed. This last line will define the values discussed above. Notice here we have a */5 listing, followed by several more * characters. These * characters mean first-last, and can be interpreted as every time. So, judging by this line, its apparent that the atrun command is to be invoked by root every five minutes regardless of what day or month it is. For more information on the atrun, see the &man.atrun.8; manual page. Commands can have any number of flags passed to them; however, commands which extend to multiple lines need to be broken with the backslash \ continuation character. This is the basic set up for every crontab file, although there is one thing different about this one. Field number six, where we specified the username, only exists in the system /etc/crontab file. This field should be omitted for individual user crontab files. Installing a <filename>crontab</filename> To install your freshly written crontab, just use the crontab utility. The most common usage is: &prompt.root; crontab crontab There is also an option to list installed crontab files, just pass the to crontab and look over the output. Users who wish to begin their own crontab file from scratch, without the use of a template, the crontab -e option is available. This will invoke the selected editor with an empty file. When the file is saved, it will be automatically installed by the crontab command. Tom Rhodes Contributed by Using rc under FreeBSD 5.X rcNG FreeBSD has recently integrated the NetBSD rc.d system for system initialization. Users should notice the files listed in the /etc/rc.d directory. Many of these files are for basic services which can be controlled with the , , and options. For instance, &man.sshd.8; can be restarted with the following command: &prompt.root; /etc/rc.d/sshd restart This procedure is similar for other services. Of course, services are usually started automatically as specified in &man.rc.conf.5;. For example, enabling the Network Address Translation daemon at startup is as simple as adding the following line to /etc/rc.conf: natd_enable="YES" If a line is already present, then simply change the to . The rc scripts will automatically load any other dependent services during the next reboot, as described below. Since the rc.d system is primarily intended to start/stop services at system startup/shutdown time; the standard , and options will only perform their action if the appropriate /etc/rc.conf variables are set. For instance the above sshd restart command will only work if sshd_enable is set to in /etc/rc.conf. To , or a service regardless of the settings in /etc/rc.conf, the commands should be prefixed with force. For instance to restart sshd regardless of the current /etc/rc.conf setting, execute the following command: &prompt.root; /etc/rc.d/sshd forcerestart It's easy to check if a service is enabled in /etc/rc.conf by running the appropriate rc.d script with the option . Thus, an administrator can check that sshd is in fact enabled in /etc/rc.conf by running: &prompt.root; /etc/rc.d/sshd rcvar # sshd $sshd_enable=YES The second line (# sshd) is the output from the sshd command; not a root console. To determine if a service is running, a option is available. For instance to verify that sshd is actually started: &prompt.root; /etc/rc.d/sshd status sshd is running as pid 433. It is also possible to a service. This will attempt to send a signal to an individual service, forcing the service to reload its configuration files. In most cases this means sending the service a SIGHUP signal. The rcNG structure is not only used for network services, it also contributes to most of the system initialization. For instance, consider the bgfsck file. When this script is executed, it will print out the following message: Starting background file system checks in 60 seconds. Therefore this file is used for background file system checks, which are done only during system initialization. Many system services depend on other services to function properly. For example, NIS and other RPC-based services may fail to start until after the rpcbind (portmapper) service has started. To resolve this issue, information about dependencies and other meta-data is included in the comments at the top of each startup script. The &man.rcorder.8; script is then used to parse these comments during system initialization to determine the order in which system services should be invoked to satisfy the dependencies. The following words may be included at the top of each startup file : PROVIDE: Name of service REQUIRE: Name of services which may be required for this service to function BEFORE: What service should be run before this service KEYWORD: FreeBSD or NetBSD. This is used for *BSD dependent features. By using this method, an administrator can easily control system services without the hassle of runlevels like some other &unix; operating systems. Additional information about the &os; 5.X rc.d system can be found in the &man.rc.8; and &man.rc.subr.8; manual pages. Marc Fonvieille Contributed by Setting Up Network Interface Cards Network card configuration Nowadays we can not think about a computer without thinking about a network connection. Adding and configuring a network card is a common task for any FreeBSD administrator. Locating the Correct Driver Network card configuration Locating the driver Before you begin, you should know the model of the card you have, the chip it uses, and whether it is a PCI or ISA card. FreeBSD supports a wide variety of both PCI and ISA cards. Check the Hardware Compatibility List for your release to see if your card is supported. Once you are sure your card is supported, you need to determine the proper driver for the card. The file /usr/src/sys/i386/conf/LINT will give you the list of network interfaces drivers with some information about the supported chipsets/cards. If you have doubts about which driver is the correct one, read the manual page of the driver. The manual page will give you more information about the supported hardware and even the possible problems that could occur. If you own a common card, most of the time you will not have to look very hard for a driver. Drivers for common network cards are present in the GENERIC kernel, so your card should show up during boot, like so: dc0: <82c169 PNIC 10/100BaseTX> port 0xa000-0xa0ff mem 0xd3800000-0xd38 000ff irq 15 at device 11.0 on pci0 dc0: Ethernet address: 00:a0:cc:da:da:da miibus0: <MII bus> on dc0 ukphy0: <Generic IEEE 802.3u media interface> on miibus0 ukphy0: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto dc1: <82c169 PNIC 10/100BaseTX> port 0x9800-0x98ff mem 0xd3000000-0xd30 000ff irq 11 at device 12.0 on pci0 dc1: Ethernet address: 00:a0:cc:da:da:db miibus1: <MII bus> on dc1 ukphy1: <Generic IEEE 802.3u media interface> on miibus1 ukphy1: 10baseT, 10baseT-FDX, 100baseTX, 100baseTX-FDX, auto In this example, we see that two cards using the &man.dc.4; driver are present on the system. To use your network card, you will need to load the proper driver. This may be accomplished in one of two ways. The easiest way is to simply load a kernel module for your network card with &man.kldload.8;. A module is not available for all network card drivers (ISA cards and cards using the &man.ed.4; driver, for example). Alternatively, you may statically compile the support for your card into your kernel. Check /usr/src/sys/i386/conf/LINT and the manual page of the driver to know what to add in your kernel configuration file. For more information about recompiling your kernel, please see . If your card was detected at boot by your kernel (GENERIC) you do not have to build a new kernel. Configuring the Network Card Network card configuration configuration Once the right driver is loaded for the network card, the card needs to be configured. As with many other things, the network card may have been configured at installation time by sysinstall. To display the configuration for the network interfaces on your system, enter the following command: &prompt.user; ifconfig dc0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet 192.168.1.3 netmask 0xffffff00 broadcast 192.168.1.255 ether 00:a0:cc:da:da:da media: Ethernet autoselect (100baseTX <full-duplex>) status: active dc1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet 10.0.0.1 netmask 0xffffff00 broadcast 10.0.0.255 ether 00:a0:cc:da:da:db media: Ethernet 10baseT/UTP status: no carrier lp0: flags=8810<POINTOPOINT,SIMPLEX,MULTICAST> mtu 1500 lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 16384 inet 127.0.0.1 netmask 0xff000000 tun0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 Old versions of FreeBSD may require the option following &man.ifconfig.8;, for more details about the correct syntax of &man.ifconfig.8;, please refer to the manual page. Note also that entries concerning IPv6 (inet6 etc.) were omitted in this example. In this example, the following devices were displayed: dc0: The first Ethernet interface dc1: The second Ethernet interface lp0: The parallel port interface lo0: The loopback device tun0: The tunnel device used by ppp FreeBSD uses the driver name followed by the order in which one the card is detected at the kernel boot to name the network card. For example sis2 would be the third network card on the system using the &man.sis.4; driver. In this example, the dc0 device is up and running. The key indicators are: UP means that the card is configured and ready. The card has an Internet (inet) address (in this case 192.168.1.3). It has a valid subnet mask (netmask; 0xffffff00 is the same as 255.255.255.0). It has a valid broadcast address (in this case, 192.168.1.255). The MAC address of the card (ether) is 00:a0:cc:da:da:da The physical media selection is on autoselection mode (media: Ethernet autoselect (100baseTX <full-duplex>)). We see that dc1 was configured to run with 10baseT/UTP media. For more information on available media types for a driver, please refer to its manual page. The status of the link (status) is active, i.e. the carrier is detected. For dc1, we see status: no carrier. This is normal when an ethernet cable is not plugged into the card. If the &man.ifconfig.8; output had shown something similar to: dc0: flags=8843<BROADCAST,SIMPLEX,MULTICAST> mtu 1500 ether 00:a0:cc:da:da:da it would indicate the card has not been configured. To configure your card, you need root privileges. The network card configuration can be done from the command line with &man.ifconfig.8; but you would have to do it after each reboot of the system. The file /etc/rc.conf is where to add the network card's configuration. Open /etc/rc.conf in your favorite editor. You need to add a line for each network card present on the system, for example in our case, we added these lines: ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0" ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP" You have to replace dc0, dc1, and so on, with the correct device for your cards, and the addresses with the proper ones. You should read the card driver and &man.ifconfig.8; manual pages for more details about the allowed options and also &man.rc.conf.5; manual page for more information on the syntax of /etc/rc.conf. If you configured the network during installation, some lines about the network card(s) may be already present. Double check /etc/rc.conf before adding any lines. You will also have to edit the file /etc/hosts to add the names and the IP addresses of various machines of the LAN, if they are not already there. For more information please refer to &man.hosts.5; and to /usr/share/examples/etc/hosts. Testing and Troubleshooting Once you have made the necessary changes in /etc/rc.conf, you should reboot your system. This will allow the change(s) to the interface(s) to be applied, and verify that the system restarts without any configuration errors. Once the system has been rebooted, you should test the network interfaces. Testing the Ethernet Card Network card configuration Testing the card To verify that an Ethernet card is configured correctly, you have to try two things. First, ping the interface itself, and then ping another machine on the LAN. First test the local interface: &prompt.user; ping -c5 192.168.1.3 PING 192.168.1.3 (192.168.1.3): 56 data bytes 64 bytes from 192.168.1.3: icmp_seq=0 ttl=64 time=0.082 ms 64 bytes from 192.168.1.3: icmp_seq=1 ttl=64 time=0.074 ms 64 bytes from 192.168.1.3: icmp_seq=2 ttl=64 time=0.076 ms 64 bytes from 192.168.1.3: icmp_seq=3 ttl=64 time=0.108 ms 64 bytes from 192.168.1.3: icmp_seq=4 ttl=64 time=0.076 ms --- 192.168.1.3 ping statistics --- 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 0.074/0.083/0.108/0.013 ms Now we have to ping another machine on the LAN: &prompt.user; ping -c5 192.168.1.2 PING 192.168.1.2 (192.168.1.2): 56 data bytes 64 bytes from 192.168.1.2: icmp_seq=0 ttl=64 time=0.726 ms 64 bytes from 192.168.1.2: icmp_seq=1 ttl=64 time=0.766 ms 64 bytes from 192.168.1.2: icmp_seq=2 ttl=64 time=0.700 ms 64 bytes from 192.168.1.2: icmp_seq=3 ttl=64 time=0.747 ms 64 bytes from 192.168.1.2: icmp_seq=4 ttl=64 time=0.704 ms --- 192.168.1.2 ping statistics --- 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms You could also use the machine name instead of 192.168.1.2 if you have set up the /etc/hosts file. Troubleshooting Network card configuration Troubleshooting Troubleshooting hardware and software configurations is always a pain, and a pain which can be alleviated by checking the simple things first. Is your network cable plugged in? Have you properly configured the network services? Did you configure the firewall correctly? Is the card you are using supported by FreeBSD? Always check the hardware notes before sending off a bug report. Update your version of FreeBSD to the latest STABLE version. Check the mailing list archives, or perhaps search the Internet. If the card works, yet performance is poor, it would be worthwhile to read over the &man.tuning.7; manual page. You can also check the network configuration as incorrect network settings can cause slow connections. Some users experience one or two device timeouts, which is normal for some cards. If they continue, or are bothersome, you may wish to be sure the device is not conflicting with another device. Double check the cable connections. Perhaps you may just need to get another card. At times, users see a few watchdog timeout errors. The first thing to do here is to check your network cable. Many cards require a PCI slot which supports Bus Mastering. On some old motherboards, only one PCI slot allows it (usually slot 0). Check the network card and the motherboard documentation to determine if that may be the problem. No route to host messages occur if the system is unable to route a packet to the destination host. This can happen if no default route is specified, or if a cable is unplugged. Check the output of netstat -rn and make sure there is a valid route to the host you are trying to reach. If there is not, read on to . ping: sendto: Permission denied error messages are often caused by a misconfigured firewall. If ipfw is enabled in the kernel but no rules have been defined, then the default policy is to deny all traffic, even ping requests! Read on to for more information. Virtual Hosts virtual hosts IP aliases A very common use of FreeBSD is virtual site hosting, where one server appears to the network as many servers. This is achieved by assigning multiple network addresses to a single interface. A given network interface has one real address, and may have any number of alias addresses. These aliases are normally added by placing alias entries in /etc/rc.conf. An alias entry for the interface fxp0 looks like: ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx" Note that alias entries must start with alias0 and proceed upwards in order, (for example, _alias1, _alias2, and so on). The configuration process will stop at the first missing number. The calculation of alias netmasks is important, but fortunately quite simple. For a given interface, there must be one address which correctly represents the network's netmask. Any other addresses which fall within this network must have a netmask of all 1s. For example, consider the case where the fxp0 interface is connected to two networks, the 10.1.1.0 network with a netmask of 255.255.255.0 and the 202.0.75.16 network with a netmask of 255.255.255.240. We want the system to appear at 10.1.1.1 through 10.1.1.5 and at 202.0.75.17 through 202.0.75.20. The following entries configure the adapter correctly for this arrangement: ifconfig_fxp0="inet 10.1.1.1 netmask 255.255.255.0" ifconfig_fxp0_alias0="inet 10.1.1.2 netmask 255.255.255.255" ifconfig_fxp0_alias1="inet 10.1.1.3 netmask 255.255.255.255" ifconfig_fxp0_alias2="inet 10.1.1.4 netmask 255.255.255.255" ifconfig_fxp0_alias3="inet 10.1.1.5 netmask 255.255.255.255" ifconfig_fxp0_alias4="inet 202.0.75.17 netmask 255.255.255.240" ifconfig_fxp0_alias5="inet 202.0.75.18 netmask 255.255.255.255" ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255" ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255" Configuration Files <filename>/etc</filename> Layout There are a number of directories in which configuration information is kept. These include: /etc Generic system configuration information; data here is system-specific. /etc/defaults Default versions of system configuration files. /etc/mail Extra &man.sendmail.8; configuration, other MTA configuration files. /etc/ppp Configuration for both user- and kernel-ppp programs. /etc/namedb Default location for &man.named.8; data. Normally named.conf and zone files are stored here. /usr/local/etc Configuration files for installed applications. May contain per-application subdirectories. /usr/local/etc/rc.d Start/stop scripts for installed applications. /var/db Automatically generated system-specific database files, such as the package database, the locate database, and so on Hostnames hostname DNS <filename>/etc/resolv.conf</filename> resolv.conf /etc/resolv.conf dictates how FreeBSD's resolver accesses the Internet Domain Name System (DNS). The most common entries to resolv.conf are: nameserver The IP address of a name server the resolver should query. The servers are queried in the order listed with a maximum of three. search Search list for hostname lookup. This is normally determined by the domain of the local hostname. domain The local domain name. A typical resolv.conf: search example.com nameserver 147.11.1.11 nameserver 147.11.100.30 Only one of the search and domain options should be used. If you are using DHCP, &man.dhclient.8; usually rewrites resolv.conf with information received from the DHCP server. <filename>/etc/hosts</filename> hosts /etc/hosts is a simple text database reminiscent of the old Internet. It works in conjunction with DNS and NIS providing name to IP address mappings. Local computers connected via a LAN can be placed in here for simplistic naming purposes instead of setting up a &man.named.8; server. Additionally, /etc/hosts can be used to provide a local record of Internet names, reducing the need to query externally for commonly accessed names. # $FreeBSD$ # # Host Database # This file should contain the addresses and aliases # for local hosts that share this file. # In the presence of the domain name service or NIS, this file may # not be consulted at all; see /etc/nsswitch.conf for the resolution order. # # ::1 localhost localhost.my.domain myname.my.domain 127.0.0.1 localhost localhost.my.domain myname.my.domain # # Imaginary network. #10.0.0.2 myname.my.domain myname #10.0.0.3 myfriend.my.domain myfriend # # According to RFC 1918, you can use the following IP networks for # private nets which will never be connected to the Internet: # # 10.0.0.0 - 10.255.255.255 # 172.16.0.0 - 172.31.255.255 # 192.168.0.0 - 192.168.255.255 # # In case you want to be able to connect to the Internet, you need # real official assigned numbers. PLEASE PLEASE PLEASE do not try # to invent your own network numbers but instead get one from your # network provider (if any) or from the Internet Registry (ftp to # rs.internic.net, directory `/templates'). # /etc/hosts takes on the simple format of: [Internet address] [official hostname] [alias1] [alias2] ... For example: 10.0.0.1 myRealHostname.example.com myRealHostname foobar1 foobar2 Consult &man.hosts.5; for more information. Log File Configuration log files <filename>syslog.conf</filename> syslog.conf syslog.conf is the configuration file for the &man.syslogd.8; program. It indicates which types of syslog messages are logged to particular log files. # $FreeBSD$ # # Spaces ARE valid field separators in this file. However, # other *nix-like systems still insist on using tabs as field # separators. If you are sharing this file between systems, you # may want to use only tabs as field separators here. # Consult the syslog.conf(5) manual page. *.err;kern.debug;auth.notice;mail.crit /dev/console *.notice;kern.debug;lpr.info;mail.crit;news.err /var/log/messages security.* /var/log/security mail.info /var/log/maillog lpr.info /var/log/lpd-errs cron.* /var/log/cron *.err root *.notice;news.err root *.alert root *.emerg * # uncomment this to log all writes to /dev/console to /var/log/console.log #console.info /var/log/console.log # uncomment this to enable logging of all log messages to /var/log/all.log #*.* /var/log/all.log # uncomment this to enable logging to a remote log host named loghost #*.* @loghost # uncomment these if you're running inn # news.crit /var/log/news/news.crit # news.err /var/log/news/news.err # news.notice /var/log/news/news.notice !startslip *.* /var/log/slip.log !ppp *.* /var/log/ppp.log Consult the &man.syslog.conf.5; manual page for more information. <filename>newsyslog.conf</filename> newsyslog.conf newsyslog.conf is the configuration file for &man.newsyslog.8;, a program that is normally scheduled to run by &man.cron.8;. &man.newsyslog.8; determines when log files require archiving or rearranging. logfile is moved to logfile.0, logfile.0 is moved to logfile.1, and so on. Alternatively, the log files may be archived in &man.gzip.1; format causing them to be named: logfile.0.gz, logfile.1.gz, and so on. newsyslog.conf indicates which log files are to be managed, how many are to be kept, and when they are to be touched. Log files can be rearranged and/or archived when they have either reached a certain size, or at a certain periodic time/date. # configuration file for newsyslog # $FreeBSD$ # # filename [owner:group] mode count size when [ZB] [/pid_file] [sig_num] /var/log/cron 600 3 100 * Z /var/log/amd.log 644 7 100 * Z /var/log/kerberos.log 644 7 100 * Z /var/log/lpd-errs 644 7 100 * Z /var/log/maillog 644 7 * @T00 Z /var/log/sendmail.st 644 10 * 168 B /var/log/messages 644 5 100 * Z /var/log/all.log 600 7 * @T00 Z /var/log/slip.log 600 3 100 * Z /var/log/ppp.log 600 3 100 * Z /var/log/security 600 10 100 * Z /var/log/wtmp 644 3 * @01T05 B /var/log/daily.log 640 7 * @T00 Z /var/log/weekly.log 640 5 1 $W6D0 Z /var/log/monthly.log 640 12 * $M1D0 Z /var/log/console.log 640 5 100 * Z Consult the &man.newsyslog.8; manual page for more information. <filename>sysctl.conf</filename> sysctl.conf sysctl sysctl.conf looks much like rc.conf. Values are set in a variable=value form. The specified values are set after the system goes into multi-user mode. Not all variables are settable in this mode. A sample sysctl.conf turning off logging of fatal signal exits and letting Linux programs know they are really running under FreeBSD: kern.logsigexit=0 # Do not log fatal signal exits (e.g. sig 11) compat.linux.osname=FreeBSD compat.linux.osrelease=4.3-STABLE Tuning with sysctl sysctl tuning with sysctl &man.sysctl.8; is an interface that allows you to make changes to a running FreeBSD system. This includes many advanced options of the TCP/IP stack and virtual memory system that can dramatically improve performance for an experienced system administrator. Over five hundred system variables can be read and set using &man.sysctl.8;. At its core, &man.sysctl.8; serves two functions: to read and to modify system settings. To view all readable variables: &prompt.user; sysctl -a To read a particular variable, for example, kern.maxproc: &prompt.user; sysctl kern.maxproc kern.maxproc: 1044 To set a particular variable, use the intuitive variable=value syntax: &prompt.root; sysctl kern.maxfiles=5000 kern.maxfiles: 2088 -> 5000 Settings of sysctl variables are usually either strings, numbers, or booleans (a boolean being 1 for yes or a 0 for no). Tom Rhodes Contributed by &man.sysctl.8; read only In some cases it may be desirable to modify read-only &man.sysctl.8; values. While this is not recommended, it is also sometimes unavoidable. For instance on some laptop models the &man.cardbus.4; device will not probe memory ranges, and fail with errors which look similar to: cbb0: Could not map register memory device_probe_and_attach: cbb0 attach returned 12 Cases like the one above usually require the modification of some default &man.sysctl.8; settings which are set read only. To overcome these situations a user can put &man.sysctl.8; OIDs in their local /boot/loader.conf.local. Default settings are located in the /boot/defaults/loader.conf file. Fixing the problem mentioned above would require a user to set in the aforementioned file. Now &man.cardbus.4; will work properly. Tuning Disks Sysctl Variables <varname>vfs.vmiodirenable</varname> vfs.vmiodirenable The vfs.vmiodirenable sysctl variable may be set to either 0 (off) or 1 (on); it is 1 by default. This variable controls how directories are cached by the system. Most directories are small, using just a single fragment (typically 1 K) in the file system and less (typically 512 bytes) in the buffer cache. However, when operating in the default mode the buffer cache will only cache a fixed number of directories even if you have a huge amount of memory. Turning on this sysctl allows the buffer cache to use the VM Page Cache to cache the directories, making all the memory available for caching directories. However, the minimum in-core memory used to cache a directory is the physical page size (typically 4 K) rather than 512 bytes. We recommend turning this option on if you are running any services which manipulate large numbers of files. Such services can include web caches, large mail systems, and news systems. Turning on this option will generally not reduce performance even with the wasted memory but you should experiment to find out. <varname>vfs.write_behind</varname> vfs.write_behind The vfs.write_behind sysctl variable defaults to 1 (on). This tells the file system to issue media writes as full clusters are collected, which typically occurs when writing large sequential files. The idea is to avoid saturating the buffer cache with dirty buffers when it would not benefit I/O performance. However, this may stall processes and under certain circumstances you may wish to turn it off. <varname>vfs.hirunningspace</varname> vfs.hirunningspace The vfs.hirunningspace sysctl variable determines how much outstanding write I/O may be queued to disk controllers system-wide at any given instance. The default is usually sufficient but on machines with lots of disks you may want to bump it up to four or five megabytes. Note that setting too high a value (exceeding the buffer cache's write threshold) can lead to extremely bad clustering performance. Do not set this value arbitrarily high! Higher write values may add latency to reads occurring at the same time. There are various other buffer-cache and VM page cache related sysctls. We do not recommend modifying these values. As of FreeBSD 4.3, the VM system does an extremely good job of automatically tuning itself. <varname>vm.swap_idle_enabled</varname> vm.swap_idle_enabled The vm.swap_idle_enabled sysctl variable is useful in large multi-user systems where you have lots of users entering and leaving the system and lots of idle processes. Such systems tend to generate a great deal of continuous pressure on free memory reserves. Turning this feature on and tweaking the swapout hysteresis (in idle seconds) via vm.swap_idle_threshold1 and vm.swap_idle_threshold2 allows you to depress the priority of memory pages associated with idle processes more quickly then the normal pageout algorithm. This gives a helping hand to the pageout daemon. Do not turn this option on unless you need it, because the tradeoff you are making is essentially pre-page memory sooner rather than later; thus eating more swap and disk bandwidth. In a small system this option will have a determinable effect but in a large system that is already doing moderate paging this option allows the VM system to stage whole processes into and out of memory easily. <varname>hw.ata.wc</varname> hw.ata.wc FreeBSD 4.3 flirted with turning off IDE write caching. This reduced write bandwidth to IDE disks but was considered necessary due to serious data consistency issues introduced by hard drive vendors. The problem is that IDE drives lie about when a write completes. With IDE write caching turned on, IDE hard drives not only write data to disk out of order, but will sometimes delay writing some blocks indefinitely when under heavy disk loads. A crash or power failure may cause serious file system corruption. FreeBSD's default was changed to be safe. Unfortunately, the result was such a huge performance loss that we changed write caching back to on by default after the release. You should check the default on your system by observing the hw.ata.wc sysctl variable. If IDE write caching is turned off, you can turn it back on by setting the kernel variable back to 1. This must be done from the boot loader at boot time. Attempting to do it after the kernel boots will have no effect. For more information, please see &man.ata.4;. <option>SCSI_DELAY</option> (<varname>kern.cam.scsi_delay</varname>) kern.cam.scsi_delay The kernel config may be used to reduce system boot times. The defaults are fairly high and can be responsible for 15+ seconds of delay in the boot process. Reducing it to 5 seconds usually works (especially with modern drives). Newer versions of FreeBSD (5.0+) should use the kern.cam.scsi_delay boot time tunable. The tunable, and kernel config option accept values in terms of milliseconds and not seconds. Soft Updates Soft Updates tunefs The &man.tunefs.8; program can be used to fine-tune a file system. This program has many different options, but for now we are only concerned with toggling Soft Updates on and off, which is done by: &prompt.root; tunefs -n enable /filesystem &prompt.root; tunefs -n disable /filesystem A filesystem cannot be modified with &man.tunefs.8; while it is mounted. A good time to enable Soft Updates is before any partitions have been mounted, in single-user mode. As of FreeBSD 4.5, it is possible to enable Soft Updates at filesystem creation time, through use of the -U option to &man.newfs.8;. Soft Updates drastically improves meta-data performance, mainly file creation and deletion, through the use of a memory cache. We recommend to use Soft Updates on all of your file systems. There are two downsides to Soft Updates that you should be aware of: First, Soft Updates guarantees filesystem consistency in the case of a crash but could very easily be several seconds (even a minute!) behind updating the physical disk. If your system crashes you may lose more work than otherwise. Secondly, Soft Updates delays the freeing of filesystem blocks. If you have a filesystem (such as the root filesystem) which is almost full, performing a major update, such as make installworld, can cause the filesystem to run out of space and the update to fail. More details about Soft Updates Soft Updates Details There are two traditional approaches to writing a file systems meta-data back to disk. (Meta-data updates are updates to non-content data like inodes or directories.) Historically, the default behavior was to write out meta-data updates synchronously. If a directory had been changed, the system waited until the change was actually written to disk. The file data buffers (file contents) were passed through the buffer cache and backed up to disk later on asynchronously. The advantage of this implementation is that it operates safely. If there is a failure during an update, the meta-data are always in a consistent state. A file is either created completely or not at all. If the data blocks of a file did not find their way out of the buffer cache onto the disk by the time of the crash, &man.fsck.8; is able to recognize this and repair the filesystem by setting the file length to 0. Additionally, the implementation is clear and simple. The disadvantage is that meta-data changes are slow. An rm -r, for instance, touches all the files in a directory sequentially, but each directory change (deletion of a file) will be written synchronously to the disk. This includes updates to the directory itself, to the inode table, and possibly to indirect blocks allocated by the file. Similar considerations apply for unrolling large hierarchies (tar -x). The second case is asynchronous meta-data updates. This is the default for Linux/ext2fs and mount -o async for *BSD ufs. All meta-data updates are simply being passed through the buffer cache too, that is, they will be intermixed with the updates of the file content data. The advantage of this implementation is there is no need to wait until each meta-data update has been written to disk, so all operations which cause huge amounts of meta-data updates work much faster than in the synchronous case. Also, the implementation is still clear and simple, so there is a low risk for bugs creeping into the code. The disadvantage is that there is no guarantee at all for a consistent state of the filesystem. If there is a failure during an operation that updated large amounts of meta-data (like a power failure, or someone pressing the reset button), the filesystem will be left in an unpredictable state. There is no opportunity to examine the state of the filesystem when the system comes up again; the data blocks of a file could already have been written to the disk while the updates of the inode table or the associated directory were not. It is actually impossible to implement a fsck which is able to clean up the resulting chaos (because the necessary information is not available on the disk). If the filesystem has been damaged beyond repair, the only choice is to use &man.newfs.8; on it and restore it from backup. The usual solution for this problem was to implement dirty region logging, which is also referred to as journaling, although that term is not used consistently and is occasionally applied to other forms of transaction logging as well. Meta-data updates are still written synchronously, but only into a small region of the disk. Later on they will be moved to their proper location. Because the logging area is a small, contiguous region on the disk, there are no long distances for the disk heads to move, even during heavy operations, so these operations are quicker than synchronous updates. Additionally the complexity of the implementation is fairly limited, so the risk of bugs being present is low. A disadvantage is that all meta-data are written twice (once into the logging region and once to the proper location) so for normal work, a performance pessimization might result. On the other hand, in case of a crash, all pending meta-data operations can be quickly either rolled-back or completed from the logging area after the system comes up again, resulting in a fast filesystem startup. Kirk McKusick, the developer of Berkeley FFS, solved this problem with Soft Updates: all pending meta-data updates are kept in memory and written out to disk in a sorted sequence (ordered meta-data updates). This has the effect that, in case of heavy meta-data operations, later updates to an item catch the earlier ones if the earlier ones are still in memory and have not already been written to disk. So all operations on, say, a directory are generally performed in memory before the update is written to disk (the data blocks are sorted according to their position so that they will not be on the disk ahead of their meta-data). If the system crashes, this causes an implicit log rewind: all operations which did not find their way to the disk appear as if they had never happened. A consistent filesystem state is maintained that appears to be the one of 30 to 60 seconds earlier. The algorithm used guarantees that all resources in use are marked as such in their appropriate bitmaps: blocks and inodes. After a crash, the only resource allocation error that occurs is that resources are marked as used which are actually free. &man.fsck.8; recognizes this situation, and frees the resources that are no longer used. It is safe to ignore the dirty state of the filesystem after a crash by forcibly mounting it with mount -f. In order to free resources that may be unused, &man.fsck.8; needs to be run at a later time. This is the idea behind the background fsck: at system startup time, only a snapshot of the filesystem is recorded. The fsck can be run later on. All file systems can then be mounted dirty, so the system startup proceeds in multiuser mode. Then, background fscks will be scheduled for all file systems where this is required, to free resources that may be unused. (File systems that do not use Soft Updates still need the usual foreground fsck though.) The advantage is that meta-data operations are nearly as fast as asynchronous updates (i.e. faster than with logging, which has to write the meta-data twice). The disadvantages are the complexity of the code (implying a higher risk for bugs in an area that is highly sensitive regarding loss of user data), and a higher memory consumption. Additionally there are some idiosyncrasies one has to get used to. After a crash, the state of the filesystem appears to be somewhat older. In situations where the standard synchronous approach would have caused some zero-length files to remain after the fsck, these files do not exist at all with a Soft Updates filesystem because neither the meta-data nor the file contents have ever been written to disk. Disk space is not released until the updates have been written to disk, which may take place some time after running rm. This may cause problems when installing large amounts of data on a filesystem that does not have enough free space to hold all the files twice. Tuning Kernel Limits tuning kernel limits File/Process Limits <varname>kern.maxfiles</varname> kern.maxfiles kern.maxfiles can be raised or lowered based upon your system requirements. This variable indicates the maximum number of file descriptors on your system. When the file descriptor table is full, file: table is full will show up repeatedly in the system message buffer, which can be viewed with the dmesg command. Each open file, socket, or fifo uses one file descriptor. A large-scale production server may easily require many thousands of file descriptors, depending on the kind and number of services running concurrently. kern.maxfile's default value is dictated by the option in your kernel configuration file. kern.maxfiles grows proportionally to the value of . When compiling a custom kernel, it is a good idea to set this kernel configuration option according to the uses of your system. From this number, the kernel is given most of its pre-defined limits. Even though a production machine may not actually have 256 users connected as once, the resources needed may be similar to a high-scale web server. As of FreeBSD 4.5, setting to 0 in your kernel configuration file will choose a reasonable default value based on the amount of RAM present in your system. <varname>kern.ipc.somaxconn</varname> kern.ipc.somaxconn The kern.ipc.somaxconn sysctl variable limits the size of the listen queue for accepting new TCP connections. The default value of 128 is typically too low for robust handling of new connections in a heavily loaded web server environment. For such environments, it is recommended to increase this value to 1024 or higher. The service daemon may itself limit the listen queue size (e.g. &man.sendmail.8;, or Apache) but will often have a directive in it's configuration file to adjust the queue size. Large listen queues also do a better job of avoiding Denial of Service (DoS) attacks. Network Limits The kernel configuration option dictates the amount of network Mbufs available to the system. A heavily-trafficked server with a low number of Mbufs will hinder FreeBSD's ability. Each cluster represents approximately 2 K of memory, so a value of 1024 represents 2 megabytes of kernel memory reserved for network buffers. A simple calculation can be done to figure out how many are needed. If you have a web server which maxes out at 1000 simultaneous connections, and each connection eats a 16 K receive and 16 K send buffer, you need approximately 32 MB worth of network buffers to cover the web server. A good rule of thumb is to multiply by 2, so 2x32 MB / 2 KB = 64 MB / 2 kB = 32768. We recommend values between 4096 and 32768 for machines with greater amounts of memory. Under no circumstances should you specify an arbitrarily high value for this parameter as it could lead to a boot time crash. The option to &man.netstat.1; may be used to observe network cluster use. kern.ipc.nmbclusters loader tunable should be used to tune this at boot time. Only older versions of FreeBSD will require you to use the kernel &man.config.8; option. For busy servers that make extensive use of the &man.sendfile.2; system call, it may be necessary to increase the number of &man.sendfile.2; buffers via the kernel configuration option or by setting its value in /boot/loader.conf (see &man.loader.8; for details). A common indicator that this parameter needs to be adjusted is when processes are seen in the sfbufa state. The sysctl variable kern.ipc.nsfbufs is a read-only glimpse at the kernel configured variable. This parameter nominally scales with kern.maxusers, however it may be necessary to tune accordingly. Even though a socket has been marked as non-blocking, calling &man.sendfile.2; on the non-blocking socket may result in the &man.sendfile.2; call blocking until enough struct sf_buf's are made available. <varname>net.inet.ip.portrange.*</varname> net.inet.ip.portrange.* The net.inet.ip.portrange.* sysctl variables control the port number ranges automatically bound to TCP and UDP sockets. There are three ranges: a low range, a default range, and a high range. Most network programs use the default range which is controlled by the net.inet.ip.portrange.first and net.inet.ip.portrange.last, which default to 1024 and 5000, respectively. Bound port ranges are used for outgoing connections, and it is possible to run the system out of ports under certain circumstances. This most commonly occurs when you are running a heavily loaded web proxy. The port range is not an issue when running servers which handle mainly incoming connections, such as a normal web server, or has a limited number of outgoing connections, such as a mail relay. For situations where you may run yourself out of ports, it is recommended to increase net.inet.ip.portrange.last modestly. A value of 10000, 20000 or 30000 may be reasonable. You should also consider firewall effects when changing the port range. Some firewalls may block large ranges of ports (usually low-numbered ports) and expect systems to use higher ranges of ports for outgoing connections — for this reason it is recommended that net.inet.ip.portrange.first be lowered. TCP Bandwidth Delay Product TCP Bandwidth Delay Product Limiting net.inet.tcp.inflight_enable The TCP Bandwidth Delay Product Limiting is similar to TCP/Vegas in NetBSD. It can be enabled by setting net.inet.tcp.inflight_enable sysctl variable to 1. The system will attempt to calculate the bandwidth delay product for each connection and limit the amount of data queued to the network to just the amount required to maintain optimum throughput. This feature is useful if you are serving data over modems, Gigabit Ethernet, or even high speed WAN links (or any other link with a high bandwidth delay product), especially if you are also using window scaling or have configured a large send window. If you enable this option, you should also be sure to set net.inet.tcp.inflight_debug to 0 (disable debugging), and for production use setting net.inet.tcp.inflight_min to at least 6144 may be beneficial. However, note that setting high minimums may effectively disable bandwidth limiting depending on the link. The limiting feature reduces the amount of data built up in intermediate route and switch packet queues as well as reduces the amount of data built up in the local host's interface queue. With fewer packets queued up, interactive connections, especially over slow modems, will also be able to operate with lower Round Trip Times. However, note that this feature only effects data transmission (uploading / server side). It has no effect on data reception (downloading). Adjusting net.inet.tcp.inflight_stab is not recommended. This parameter defaults to 20, representing 2 maximal packets added to the bandwidth delay product window calculation. The additional window is required to stabilize the algorithm and improve responsiveness to changing conditions, but it can also result in higher ping times over slow links (though still much lower than you would get without the inflight algorithm). In such cases, you may wish to try reducing this parameter to 15, 10, or 5; and may also have to reduce net.inet.tcp.inflight_min (for example, to 3500) to get the desired effect. Reducing these parameters should be done as a last resort only. Adding Swap Space No matter how well you plan, sometimes a system does not run as you expect. If you find you need more swap space, it is simple enough to add. You have three ways to increase swap space: adding a new hard drive, enabling swap over NFS, and creating a swap file on an existing partition. Swap on a New Hard Drive The best way to add swap, of course, is to use this as an excuse to add another hard drive. You can always use another hard drive, after all. If you can do this, go reread the discussion of swap space from the Initial Configuration section of the Handbook for some suggestions on how to best arrange your swap. Swapping over NFS Swapping over NFS is only recommended if you do not have a local hard disk to swap to. Swapping over NFS is slow and inefficient in versions of FreeBSD prior to 4.X. It is reasonably fast and efficient in 4.0-RELEASE and newer. Even with newer versions of FreeBSD, NFS swapping will be limited by the available network bandwidth and puts an additional burden on the NFS server. Swapfiles You can create a file of a specified size to use as a swap file. In our example here we will use a 64MB file called /usr/swap0. You can use any name you want, of course. Creating a Swapfile on FreeBSD 4.X Be certain that your kernel configuration includes the vnode driver. It is not in recent versions of GENERIC. pseudo-device vn 1 #Vnode driver (turns a file into a device) create a vn-device: &prompt.root; cd /dev &prompt.root; sh MAKEDEV vn0 create a swapfile (/usr/swap0): &prompt.root; dd if=/dev/zero of=/usr/swap0 bs=1024k count=64 set proper permissions on (/usr/swap0): &prompt.root; chmod 0600 /usr/swap0 enable the swap file in /etc/rc.conf: swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired. Reboot the machine or to enable the swap file immediately, type: &prompt.root; vnconfig -e /dev/vn0b /usr/swap0 swap Creating a Swapfile on FreeBSD 5.X Be certain that your kernel configuration includes the memory disk driver (&man.md.4;). It is default in GENERIC kernel. device md # Memory "disks" create a swapfile (/usr/swap0): &prompt.root; dd if=/dev/zero of=/usr/swap0 bs=1024k count=64 set proper permissions on (/usr/swap0): &prompt.root; chmod 0600 /usr/swap0 enable the swap file in /etc/rc.conf: swapfile="/usr/swap0" # Set to name of swapfile if aux swapfile desired. Reboot the machine or to enable the swap file immediately, type: &prompt.root; mdconfig -a -t vnode -f /usr/swap0 -u 0 && swapon /dev/md0 Hiten Pandya Written by Tom Rhodes Power and Resource Management It is very important to utilize hardware resources in an efficient manner. Before ACPI was introduced, it was very difficult and inflexible for operating systems to manage the power usage and thermal properties of a system. The hardware was controlled by some sort of BIOS embedded interface, such as Plug and Play BIOS (PNPBIOS), or Advanced Power Management (APM) and so on. Power and Resource Management is one of the key components of a modern operating system. For example, you may want an operating system to monitor system limits (and possibly alert you) in case your system temperature increased unexpectedly. In this section of the FreeBSD Handbook, we will provide comprehensive information about ACPI. References will be provided for further reading at the end. Please be aware that ACPI is only available on FreeBSD 5.X and above. What is ACPI? Advanced Configuration and Power Interface (ACPI) is a standard written by an alliance of vendors to provide a standard interface for hardware resources and power management (hence the name). It is a key element in Operating System-directed configuration and Power Management, i.e.: it provides more control and flexibility to the operating system (OS). Modern systems stretched the limits of the current Plug and Play interfaces (such as APM, which is used in FreeBSD 4.X), prior to the introduction of ACPI. ACPI is the direct successor to APM (Advanced Power Management). Shortcomings of Advanced Power Management (APM) The Advanced Power Management (APM) facility control's the power usage of a system based on its activity. The APM BIOS is supplied by the (system) vendor and it is specific to the hardware platform. An APM driver in the OS mediates access to the APM Software Interface, which allows management of power levels. There are four major problems in APM. Firstly, power management is done by the (vendor-specific) BIOS, and the OS does not have any knowledge of it. One example of this, is when the user sets idle-time values for a hard drive in the APM BIOS, that when exceeded, it (BIOS) would spin down the hard drive, without the consent of the OS. Secondly, the APM logic is embedded in the BIOS, and it operates outside the scope of the OS. This means users can only fix problems in their APM BIOS by flashing a new one into the ROM; which, is a very dangerous procedure, and if it fails, it could leave the system in an unrecoverable state. Thirdly, APM is a vendor-specific technology, which, means that there is a lot or parity (duplication of efforts) and bugs found in one vendor's BIOS, may not be solved in others. Last but not the least, the APM BIOS did not have enough room to implement a sophisticated power policy, or one that can adapt very well to the purpose of the - machine. + machine. Plug and Play BIOS (PNPBIOS) was unreliable in many situations. PNPBIOS is 16-bit technology, so the OS has to use 16-bit emulation in order to interface with PNPBIOS methods. The FreeBSD APM driver is documented in the &man.apm.4; manual page. Configuring <acronym>ACPI</acronym> The acpi.ko driver is loaded by default at start up by the &man.loader.8; and should not be compiled into the kernel. The reasoning behind this is that modules are easier to work with, say if switching to another acpi.ko without doing a kernel rebuild. This has the advantage of making testing easier. Another reason is that starting ACPI after a system has been brought up is not too useful, and in some cases can be fatal. In doubt, just disable ACPI all together. This driver should not and can not be unloaded because the system bus uses it for various hardware interactions. ACPI can be disabled with the &man.acpiconf.8; utility. In fact most of the interaction with ACPI can be done via &man.acpiconf.8;. Basically this means, if anything about ACPI is in the &man.dmesg.8; output, then most likely it is already running. ACPI and APM cannot coexist and should be used separately. The last one to load will terminate if the driver notices the other running. In the simplest form, ACPI can be used to put the system into a sleep mode with &man.acpiconf.8;, the flag, and a 1-5 option. Most users will only need 1. Option 5 will do a soft-off which is the same action as: &prompt.root; halt -p The other options are available. Check out the &man.acpiconf.8; manual page for more information. Debugging and Disabling <acronym>ACPI</acronym> Almost everything in ACPI is transparent, until it does not work. That is usually when you as a user will know there is something not working properly. The &man.acpi.4; driver supports many debugging options, it is even possible to selectively disable some parts of the ACPI system. For more information about debugging facilities, read the &man.acpi.4; manual page. Sometimes for various reasons, the acpi.ko module must be unloaded. This can only be done at boot time by the &man.loader.8;. You can type at &man.loader.8; prompt the command unset acpi_load each time you boot the system, or to stop the autoloading of the &man.acpi.4; driver add the following line to the /boot/loader.conf file: exec="unset acpi_load" &os; 5.1-RELEASE and later come with a boot-time menu that controls how &os; is booted. One of the proposed options is to turn off ACPI. So to disable ACPI just select 2. Boot &os; with ACPI disabled in the menu. diff --git a/en_US.ISO8859-1/books/handbook/disks/chapter.sgml b/en_US.ISO8859-1/books/handbook/disks/chapter.sgml index 7b6c74e9fe..847ebc18e9 100644 --- a/en_US.ISO8859-1/books/handbook/disks/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/disks/chapter.sgml @@ -1,3195 +1,3195 @@ Storage Synopsis This chapter covers the use of disks in FreeBSD. This includes memory-backed disks, network-attached disks, and standard SCSI/IDE storage devices. After reading this chapter, you will know: The terminology FreeBSD uses to describe the organization of data on a physical disk (partitions and slices). How to mount and unmount file systems. How to add additional hard disks to your system. How to setup virtual file systems, such as memory disks. How to use quotas to limit disk space usage. How to encrypt disks to secure them against attackers. How to create and burn CDs and DVDs on FreeBSD. The various storage media options for backups. How to use backup programs available under FreeBSD. How to backup to floppy disks. What snapshots are and how to use them efficiently. Device Names The following is a list of physical storage devices supported in FreeBSD, and the device names associated with them. Physical Disk Naming Conventions Drive type Drive device name IDE hard drives ad IDE CDROM drives acd SCSI hard drives and USB Mass storage devices da SCSI CDROM drives cd Assorted non-standard CDROM drives mcd for Mitsumi CD-ROM, scd for Sony CD-ROM, matcd for Matsushita/Panasonic CD-ROM The &man.matcd.4; driver has been removed in FreeBSD 4.X branch since October 5th, 2002 and does not exist in FreeBSD 5.0 and later. Floppy drives fd SCSI tape drives sa IDE tape drives ast Flash drives fla for DiskOnChip Flash device RAID drives aacd for Adaptec AdvancedRAID, mlxd and mlyd for Mylex, amrd for AMI MegaRAID, idad for Compaq Smart RAID, twed for 3Ware RAID.
David O'Brien Originally contributed by Adding Disks disks adding Lets say we want to add a new SCSI disk to a machine that currently only has a single drive. First turn off the computer and install the drive in the computer following the instructions of the computer, controller, and drive manufacturer. Due to the wide variations of procedures to do this, the details are beyond the scope of this document. Login as user root. After you have installed the drive, inspect /var/run/dmesg.boot to ensure the new disk was found. Continuing with our example, the newly added drive will be da1 and we want to mount it on /1 (if you are adding an IDE drive, the device name will be wd1 in pre-4.0 systems, or ad1 in most 4.X systems). partitions slices fdisk Because FreeBSD runs on IBM-PC compatible computers, it must take into account the PC BIOS partitions. These are different from the traditional BSD partitions. A PC disk has up to four BIOS partition entries. If the disk is going to be truly dedicated to FreeBSD, you can use the dedicated mode. Otherwise, FreeBSD will have to live within one of the PC BIOS partitions. FreeBSD calls the PC BIOS partitions slices so as not to confuse them with traditional BSD partitions. You may also use slices on a disk that is dedicated to FreeBSD, but used in a computer that also has another operating system installed. This is to not confuse the fdisk utility of the other operating system. In the slice case the drive will be added as /dev/da1s1e. This is read as: SCSI disk, unit number 1 (second SCSI disk), slice 1 (PC BIOS partition 1), and e BSD partition. In the dedicated case, the drive will be added simply as /dev/da1e. Using &man.sysinstall.8; sysinstall adding disks su Navigating <application>Sysinstall</application> You may use /stand/sysinstall to partition and label a new disk using its easy to use menus. Either login as user root or use the su command. Run /stand/sysinstall and enter the Configure menu. Within the FreeBSD Configuration Menu, scroll down and select the Fdisk option. <application>fdisk</application> Partition Editor Once inside fdisk, we can type A to use the entire disk for FreeBSD. When asked if you want to remain cooperative with any future possible operating systems, answer YES. Write the changes to the disk using W. Now exit the FDISK editor by typing q. Next you will be asked about the Master Boot Record. Since you are adding a disk to an already running system, choose None. Disk Label Editor BSD partitions Next, you need to exit sysinstall and start it again. Follow the directions above, although this time choose the Label option. This will enter the Disk Label Editor. This is where you will create the traditional BSD partitions. A disk can have up to eight partitions, labeled a-h. A few of the partition labels have special uses. The a partition is used for the root partition (/). Thus only your system disk (e.g, the disk you boot from) should have an a partition. The b partition is used for swap partitions, and you may have many disks with swap partitions. The c partition addresses the entire disk in dedicated mode, or the entire FreeBSD slice in slice mode. The other partitions are for general use. sysinstall's Label editor favors the e partition for non-root, non-swap partitions. Within the Label editor, create a single file system by typing C. When prompted if this will be a FS (file system) or swap, choose FS and type in a mount point (e.g, /mnt). When adding a disk in post-install mode, sysinstall will not create entries in /etc/fstab for you, so the mount point you specify is not important. You are now ready to write the new label to the disk and create a file system on it. Do this by typing W. Ignore any errors from sysinstall that it could not mount the new partition. Exit the Label Editor and sysinstall completely. Finish The last step is to edit /etc/fstab to add an entry for your new disk. Using Command Line Utilities Using Slices This setup will allow your disk to work correctly with other operating systems that might be installed on your computer and will not confuse other operating systems' fdisk utilities. It is recommended to use this method for new disk installs. Only use dedicated mode if you have a good reason to do so! &prompt.root; dd if=/dev/zero of=/dev/da1 bs=1k count=1 &prompt.root; fdisk -BI da1 #Initialize your new disk &prompt.root; disklabel -B -w -r da1s1 auto #Label it. &prompt.root; disklabel -e da1s1 # Edit the disklabel just created and add any partitions. &prompt.root; mkdir -p /1 &prompt.root; newfs /dev/da1s1e # Repeat this for every partition you created. &prompt.root; mount /dev/da1s1e /1 # Mount the partition(s) &prompt.root; vi /etc/fstab # Add the appropriate entry/entries to your /etc/fstab. If you have an IDE disk, substitute ad for da. On pre-4.X systems use wd. Dedicated OS/2 If you will not be sharing the new drive with another operating system, you may use the dedicated mode. Remember this mode can confuse Microsoft operating systems; however, no damage will be done by them. IBM's OS/2 however, will appropriate any partition it finds which it does not understand. &prompt.root; dd if=/dev/zero of=/dev/da1 bs=1k count=1 &prompt.root; disklabel -Brw da1 auto &prompt.root; disklabel -e da1 # create the `e' partition &prompt.root; newfs -d0 /dev/da1e &prompt.root; mkdir -p /1 &prompt.root; vi /etc/fstab # add an entry for /dev/da1e &prompt.root; mount /1 An alternate method is: &prompt.root; dd if=/dev/zero of=/dev/da1 count=2 &prompt.root; disklabel /dev/da1 | disklabel -BrR da1 /dev/stdin &prompt.root; newfs /dev/da1e &prompt.root; mkdir -p /1 &prompt.root; vi /etc/fstab # add an entry for /dev/da1e &prompt.root; mount /1 RAID Software RAID Christopher Shumway Original work by Jim Brown Revised by RAIDSoftware RAIDCCD Concatenated Disk Driver (CCD) Configuration When choosing a mass storage solution the most important factors to consider are speed, reliability, and cost. It is rare to have all three in balance; normally a fast, reliable mass storage device is expensive, and to cut back on cost either speed or reliability must be sacrificed. In designing the system described below, cost was chosen as the most important factor, followed by speed, then reliability. Data transfer speed for this system is ultimately constrained by the network. And while reliability is very important, the CCD drive described below serves online data that is already fully backed up on CD-R's and can easily be replaced. Defining your own requirements is the first step in choosing a mass storage solution. If your requirements prefer speed or reliability over cost, your solution will differ from the system described in this section. Installing the Hardware In addition to the IDE system disk, three Western Digital 30GB, 5400 RPM IDE disks form the core of the CCD disk described below providing approximately 90GB of online storage. Ideally, each IDE disk would have its own IDE controller and cable, but to minimize cost, additional IDE controllers were not used. Instead the disks were configured with jumpers so that each IDE controller has one master, and one slave. Upon reboot, the system BIOS was configured to automatically detect the disks attached. More importantly, FreeBSD detected them on reboot: ad0: 19574MB <WDC WD205BA> [39770/16/63] at ata0-master UDMA33 ad1: 29333MB <WDC WD307AA> [59598/16/63] at ata0-slave UDMA33 ad2: 29333MB <WDC WD307AA> [59598/16/63] at ata1-master UDMA33 ad3: 29333MB <WDC WD307AA> [59598/16/63] at ata1-slave UDMA33 If FreeBSD does not detect all the disks, ensure that you have jumpered them correctly. Most IDE drives also have a Cable Select jumper. This is not the jumper for the master/slave relationship. Consult the drive documentation for help in identifying the correct jumper. Next, consider how to attach them as part of the file system. You should research both &man.vinum.8; () and &man.ccd.4;. In this particular configuration, &man.ccd.4; was chosen. Setting up the CCD The driver &man.ccd.4; allows you to take several identical disks and concatenate them into one logical file system. In order to use &man.ccd.4;, you need a kernel with &man.ccd.4; support built in. Add this line to your kernel configuration file, rebuild, and reinstall the kernel: pseudo-device ccd 4 On 5.X systems, you have to use instead the following line: device ccd In FreeBSD 5.X, it is not necessary to specify a number of &man.ccd.4; devices, as the &man.ccd.4; device driver is now self-cloning — new device instances will automatically be created on demand. The &man.ccd.4; support can also be loaded as a kernel loadable module in FreeBSD 3.0 or later. To set up &man.ccd.4;, you must first use &man.disklabel.8; to label the disks: disklabel -r -w ad1 auto disklabel -r -w ad2 auto disklabel -r -w ad3 auto This creates a disklabel for ad1c, ad2c and ad3c that spans the entire disk. The next step is to change the disk label type. You can use &man.disklabel.8; to edit the disks: disklabel -e ad1 disklabel -e ad2 disklabel -e ad3 This opens up the current disk label on each disk with the editor specified by the EDITOR environment variable, typically &man.vi.1;. An unmodified disk label will look something like this: 8 partitions: # size offset fstype [fsize bsize bps/cpg] c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) Add a new e partition for &man.ccd.4; to use. This can usually be copied from the c partition, but the must be 4.2BSD. The disk label should now look something like this: 8 partitions: # size offset fstype [fsize bsize bps/cpg] c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) e: 60074784 0 4.2BSD 0 0 0 # (Cyl. 0 - 59597) Building the File System The device node for ccd0c may not exist yet, so to create it, perform the following commands: cd /dev sh MAKEDEV ccd0 In FreeBSD 5.0, &man.devfs.5; will automatically manage device nodes in /dev, so use of MAKEDEV is not necessary. Now that you have all of the disks labeled, you must build the &man.ccd.4;. To do that, use &man.ccdconfig.8;, with options similar to the following: ccdconfig ccd0 32 0 /dev/ad1e /dev/ad2e /dev/ad3e The use and meaning of each option is shown below: The first argument is the device to configure, in this case, /dev/ccd0c. The /dev/ portion is optional. The interleave for the file system. The interleave defines the size of a stripe in disk blocks, each normally 512 bytes. So, an interleave of 32 would be 16,384 bytes. Flags for &man.ccdconfig.8;. If you want to enable drive mirroring, you can specify a flag here. This configuration does not provide mirroring for &man.ccd.4;, so it is set at 0 (zero). The final arguments to &man.ccdconfig.8; are the devices to place into the array. Use the complete pathname for each device. After running &man.ccdconfig.8; the &man.ccd.4; is configured. A file system can be installed. Refer to &man.newfs.8; for options, or simply run: newfs /dev/ccd0c Making it all Automatic Generally, you will want to mount the &man.ccd.4; upon each reboot. To do this, you must configure it first. Write out your current configuration to /etc/ccd.conf using the following command: ccdconfig -g > /etc/ccd.conf During reboot, the script /etc/rc runs ccdconfig -C if /etc/ccd.conf exists. This automatically configures the &man.ccd.4; so it can be mounted. If you are booting into single user mode, before you can &man.mount.8; the &man.ccd.4;, you need to issue the following command to configure the array: ccdconfig -C To automatically mount the &man.ccd.4;, place an entry for the &man.ccd.4; in /etc/fstab so it will be mounted at boot time: /dev/ccd0c /media ufs rw 2 2 The Vinum Volume Manager RAIDSoftware RAID Vinum The Vinum Volume Manager is a block device driver which implements virtual disk drives. It isolates disk hardware from the block device interface and maps data in ways which result in an increase in flexibility, performance and reliability compared to the traditional slice view of disk storage. &man.vinum.8; implements the RAID-0, RAID-1 and RAID-5 models, both individually and in combination. See for more information about &man.vinum.8;. Hardware RAID RAID Hardware FreeBSD also supports a variety of hardware RAID controllers. These devices control a RAID subsystem without the need for FreeBSD specific software to manage the array. Using an on-card BIOS, the card controls most of the disk operations itself. The following is a brief setup description using a Promise IDE RAID controller. When this card is installed and the system is started up, it displays a prompt requesting information. Follow the instructions to enter the card's setup screen. From here, you have the ability to combine all the attached drives. After doing so, the disk(s) will look like a single drive to FreeBSD. Other RAID levels can be set up accordingly. Rebuilding ATA RAID1 Arrays FreeBSD allows you to hot-replace a failed disk in an array. This requires that you catch it before you reboot. You will probably see something like the following in /var/log/messages or in the &man.dmesg.8; output: ad6 on monster1 suffered a hard error. ad6: READ command timeout tag=0 serv=0 - resetting ad6: trying fallback to PIO mode ata3: resetting devices .. done ad6: hard error reading fsbn 1116119 of 0-7 (ad6 bn 1116119; cn 1107 tn 4 sn 11) status=59 error=40 ar0: WARNING - mirror lost Using &man.atacontrol.8;, check for further information: &prompt.root; atacontrol list ATA channel 0: Master: no device present Slave: acd0 <HL-DT-ST CD-ROM GCR-8520B/1.00> ATA/ATAPI rev 0 ATA channel 1: Master: no device present Slave: no device present ATA channel 2: Master: ad4 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 Slave: no device present ATA channel 3: Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 Slave: no device present &prompt.root; atacontrol status ar0 ar0: ATA RAID1 subdisks: ad4 ad6 status: DEGRADED You will first need to detach the disk from the array so that you can safely remove it: &prompt.root; atacontrol detach 3 Replace the disk. Reattach the disk as a spare: &prompt.root; atacontrol attach 3 Master: ad6 <MAXTOR 6L080J4/A93.0500> ATA/ATAPI rev 5 Slave: no device present Rebuild the array: &prompt.root; atacontrol rebuild ar0 The rebuild command hangs until complete. However, it is possible to open another terminal (using Alt Fn) and check on the progress by issuing the following command: &prompt.root; dmesg | tail -10 [output removed] ad6: removed from configuration ad6: deleted from ar0 disk1 ad6: inserted into ar0 disk1 as spare &prompt.root; atacontrol status ar0 ar0: ATA RAID1 subdisks: ad4 ad6 status: REBUILDING 0% completed Wait until this operation completes. Mike Meyer Contributed by Creating and Using Optical Media (CDs & DVDs) CDROMs creating Introduction CDs have a number of features that differentiate them from conventional disks. Initially, they were not writable by the user. They are designed so that they can be read continuously without delays to move the head between tracks. They are also much easier to transport between systems than similarly sized media were at the time. CDs do have tracks, but this refers to a section of data to be read continuously and not a physical property of the disk. To produce a CD on FreeBSD, you prepare the data files that are going to make up the tracks on the CD, then write the tracks to the CD. ISO 9660 file systems ISO 9660 The ISO 9660 file system was designed to deal with these differences. It unfortunately codifies file system limits that were common then. Fortunately, it provides an extension mechanism that allows properly written CDs to exceed those limits while still working with systems that do not support those extensions. sysutils/mkisofs The sysutils/mkisofs program is used to produce a data file containing an ISO 9660 file system. It has options that support various extensions, and is described below. You can install it with the sysutils/mkisofs port. CD burner ATAPI Which tool to use to burn the CD depends on whether your CD burner is ATAPI or something else. ATAPI CD burners use the burncd program that is part of the base system. SCSI and USB CD burners should use cdrecord from the sysutils/cdrtools port. burncd has a limited number of supported drives. To find out if a drive is supported, see the CD-R/RW supported drives list. CD burner ATAPI/CAM driver If you run &os; 5.X, &os; 4.8-RELEASE version or higher, it will be possible to use cdrecord and other tools for SCSI drives on an ATAPI hardware with the ATAPI/CAM module. mkisofs sysutils/mkisofs produces an ISO 9660 file system that is an image of a directory tree in the Unix file system name space. The simplest usage is: &prompt.root; mkisofs -o imagefile.iso /path/to/tree file systems ISO 9660 This command will create an imagefile.iso containing an ISO 9660 file system that is a copy of the tree at /path/to/tree. In the process, it will map the file names to names that fit the limitations of the standard ISO 9660 file system, and will exclude files that have names uncharacteristic of ISO file systems. file systems HFS file systems Joliet A number of options are available to overcome those restrictions. In particular, enables the Rock Ridge extensions common to Unix systems, enables Joliet extensions used by Microsoft systems, and can be used to create HFS file systems used by MacOS. For CDs that are going to be used only on FreeBSD systems, can be used to disable all filename restrictions. When used with , it produces a file system image that is identical to the FreeBSD tree you started from, though it may violate the ISO 9660 standard in a number of ways. CDROMs creating bootable The last option of general use is . This is used to specify the location of the boot image for use in producing an El Torito bootable CD. This option takes an argument which is the path to a boot image from the top of the tree being written to the CD. So, given that /tmp/myboot holds a bootable FreeBSD system with the boot image in /tmp/myboot/boot/cdboot, you could produce the image of an ISO 9660 file system in /tmp/bootable.iso like so: &prompt.root; mkisofs -U -R -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot Having done that, if you have vn (FreeBSD 4.X), or md (FreeBSD 5.X) configured in your kernel, you can mount the file system with: &prompt.root; vnconfig -e vn0c /tmp/bootable.iso &prompt.root; mount -t cd9660 /dev/vn0c /mnt for FreeBSD 4.X, and for FreeBSD 5.X: &prompt.root; mdconfig -a -t vnode -f /tmp/bootable.iso -u 0 &prompt.root; mount -t cd9660 /dev/md0 /mnt At which point you can verify that /mnt and /tmp/myboot are identical. There are many other options you can use with sysutils/mkisofs to fine-tune its behavior. In particular: modifications to an ISO 9660 layout and the creation of Joliet and HFS discs. See the &man.mkisofs.8; manual page for details. burncd CDROMs burning If you have an ATAPI CD burner, you can use the burncd command to burn an ISO image onto a CD. burncd is part of the base system, installed as /usr/sbin/burncd. Usage is very simple, as it has few options: &prompt.root; burncd -f cddevice data imagefile.iso fixate Will burn a copy of imagefile.iso on cddevice. The default device is /dev/acd0c. See &man.burncd.8; for options to set the write speed, eject the CD after burning, and write audio data. cdrecord If you do not have an ATAPI CD burner, you will have to use cdrecord to burn your CDs. cdrecord is not part of the base system; you must install it from either the port at sysutils/cdrtools or the appropriate package. Changes to the base system can cause binary versions of this program to fail, possibly resulting in a coaster. You should therefore either upgrade the port when you upgrade your system, or if you are tracking -STABLE, upgrade the port when a new version becomes available. While cdrecord has many options, basic usage is even simpler than burncd. Burning an ISO 9660 image is done with: &prompt.root; cdrecord dev=device imagefile.iso The tricky part of using cdrecord is finding the to use. To find the proper setting, use the flag of cdrecord, which might produce results like this: CDROMs burning &prompt.root; cdrecord -scanbus Cdrecord 1.9 (i386-unknown-freebsd4.2) Copyright (C) 1995-2000 Jörg Schilling Using libscg version 'schily-0.1' scsibus0: 0,0,0 0) 'SEAGATE ' 'ST39236LW ' '0004' Disk 0,1,0 1) 'SEAGATE ' 'ST39173W ' '5958' Disk 0,2,0 2) * 0,3,0 3) 'iomega ' 'jaz 1GB ' 'J.86' Removable Disk 0,4,0 4) 'NEC ' 'CD-ROM DRIVE:466' '1.26' Removable CD-ROM 0,5,0 5) * 0,6,0 6) * 0,7,0 7) * scsibus1: 1,0,0 100) * 1,1,0 101) * 1,2,0 102) * 1,3,0 103) * 1,4,0 104) * 1,5,0 105) 'YAMAHA ' 'CRW4260 ' '1.0q' Removable CD-ROM 1,6,0 106) 'ARTEC ' 'AM12S ' '1.06' Scanner 1,7,0 107) * This lists the appropriate value for the devices on the list. Locate your CD burner, and use the three numbers separated by commas as the value for . In this case, the CRW device is 1,5,0, so the appropriate input would be . There are easier ways to specify this value; see &man.cdrecord.1; for details. That is also the place to look for information on writing audio tracks, controlling the speed, and other things. Duplicating Audio CDs You can duplicate an audio CD by extracting the audio data from the CD to a series of files, and then writing these files to a blank CD. The process is slightly different for ATAPI and SCSI drives. SCSI drives Use cdda2wav to extract the audio. &prompt.user; cdda2wav -v255 -D2,0 -B -Owav Use cdrecord to write the .wav files. &prompt.user; cdrecord -v dev=2,0 -dao -useinfo *.wav Make sure that 2.0 is set appropriately, as described in . ATAPI drives The ATAPI CD driver makes each track available as /dev/acddtnn, where d is the drive number, and nn is the track number written with two decimal digits, prefixed with zero as needed. So the first track on the first disk is /dev/acd0t01, the second is /dev/acd0t02, the third is /dev/acd0t03, and so on. Make sure the appropriate files exist in /dev. &prompt.root; cd /dev &prompt.root; sh MAKEDEV acd0t99 In FreeBSD 5.0, &man.devfs.5; will automatically create and manage entries in /dev for you, so it is not necessary to use MAKEDEV. Extract each track using &man.dd.1;. You must also use a specific block size when extracting the files. &prompt.root; dd if=/dev/acd0t01 of=track1.cdr bs=2352 &prompt.root; dd if=/dev/acd0t02 of=track2.cdr bs=2352 ... Burn the extracted files to disk using burncd. You must specify that these are audio files, and that burncd should fixate the disk when finished. &prompt.root; burncd -f /dev/acd0c audio track1.cdr track2.cdr ... fixate Duplicating Data CDs You can copy a data CD to a image file that is functionally equivalent to the image file created with sysutils/mkisofs, and you can use it to duplicate any data CD. The example given here assumes that your CDROM device is acd0. Substitute your correct CDROM device. A c must be appended to the end of the device name to indicate the entire partition or, in the case of CDROMs, the entire disc. &prompt.root; dd if=/dev/acd0c of=file.iso bs=2048 Now that you have an image, you can burn it to CD as described above. Using Data CDs Now that you have created a standard data CDROM, you probably want to mount it and read the data on it. By default, &man.mount.8; assumes that a file system is of type ufs. If you try something like: &prompt.root; mount /dev/cd0c /mnt you will get a complaint about Incorrect super block, and no mount. The CDROM is not a UFS file system, so attempts to mount it as such will fail. You just need to tell &man.mount.8; that the file system is of type ISO9660, and everything will work. You do this by specifying the option &man.mount.8;. For example, if you want to mount the CDROM device, /dev/cd0c, under /mnt, you would execute: &prompt.root; mount -t cd9660 /dev/cd0c /mnt Note that your device name (/dev/cd0c in this example) could be different, depending on the interface your CDROM uses. Also, the option just executes &man.mount.cd9660.8;. The above example could be shortened to: &prompt.root; mount_cd9660 /dev/cd0c /mnt You can generally use data CDROMs from any vendor in this way. Disks with certain ISO 9660 extensions might behave oddly, however. For example, Joliet disks store all filenames in two-byte Unicode characters. The FreeBSD kernel does not speak Unicode (yet!), so non-English characters show up as question marks. (If you are running FreeBSD 4.3 or later, the CD9660 driver includes hooks to load an appropriate Unicode conversion table on the fly. Modules for some of the common encodings are available via the sysutils/cd9660_unicode port.) Occasionally, you might get Device not configured when trying to mount a CDROM. This usually means that the CDROM drive thinks that there is no disk in the tray, or that the drive is not visible on the bus. It can take a couple of seconds for a CDROM drive to realize that it has been fed, so be patient. Sometimes, a SCSI CDROM may be missed because it didn't have enough time to answer the bus reset. If you have a SCSI CDROM please add the following option to your kernel configuration and rebuild your kernel. options SCSI_DELAY=15000 This tells your SCSI bus to pause 15 seconds during boot, to give your CDROM drive every possible chance to answer the bus reset. Burning Raw Data CDs You can choose to burn a file directly to CD, without creating an ISO 9660 file system. Some people do this for backup purposes. This runs more quickly than burning a standard CD: &prompt.root; burncd -f /dev/acd1c -s 12 data archive.tar.gz fixate In order to retrieve the data burned to such a CD, you must read data from the raw device node: &prompt.root; tar xzvf /dev/acd1c You cannot mount this disk as you would a normal CDROM. Such a CDROM cannot be read under any operating system except FreeBSD. If you want to be able to mount the CD, or share data with another operating system, you must use sysutils/mkisofs as described above. CD burner ATAPI/CAM driver Using the ATAPI/CAM Driver This driver allows ATAPI devices (CD-ROM, CD-RW, DVD drives etc...) to be accessed through the SCSI subsystem, and so allows the use of applications like sysutils/cdrdao or &man.cdrecord.1;. To use this driver, you will need to add the following lines to your kernel configuration file: device atapicam device scbus device cd device pass You also need the following lines in your kernel configuration file: device ata device atapicd Both of which should already be present. Then rebuild, install your new kernel, and reboot your machine. During the boot process, your burner should show up, like so: acd0: CD-RW <MATSHITA CD-RW/DVD-ROM UJDA740> at ata1-master PIO4 cd0 at ata1 bus 0 target 0 lun 0 cd0: <MATSHITA CDRW/DVD UJDA740 1.00> Removable CD-ROM SCSI-0 device cd0: 16.000MB/s transfers cd0: Attempt to query device size failed: NOT READY, Medium not present - tray closed The drive could now be accessed via the /dev/cd0 device name, for example to mount a CD-ROM on /mnt, just type the following: &prompt.root; mount -t cd9660 /dev/cd0c /mnt As root, you can run the following command to get the SCSI address of the burner: &prompt.root; camcontrol devlist <MATSHITA CDRW/DVD UJDA740 1.00> at scbus1 target 0 lun 0 (pass0,cd0) So 1,0,0 will be the SCSI address to use with &man.cdrecord.1; and other SCSI application. For more information about ATAPI/CAM and SCSI system, refer to the &man.atapicam.4; and &man.cam.4; manual pages. Julio Merino Original work by Martin Karlsson Rewritten by Creating and Using Floppy Disks Storing data on floppy disks is sometimes useful, for example when one does not have any other removable storage media or when one needs to transfer small amounts of data to another computer. This section will explain how to use floppy disks in FreeBSD. It will primarily cover formatting and usage of 3.5inch DOS floppies, but the concepts are similar for other floppy disk formats. Formatting floppies The device Floppy disks are accessed through entries in /dev, just like other devices. To access the raw floppy disk in 4.X and earlier releases, one uses /dev/fdN, where N stands for the drive number, usually 0, or /dev/fdNX, where X stands for a letter. In 5.0 or newer releases, simply use /dev/fdN. The disk size in 4.X and earlier releases There are also /dev/fdN.size devices, where size is a floppy disk size in kilobytes. These entries are used at low-level format time to determine the disk size. 1440kB is the size that will be used in the following examples. Sometimes the entries under /dev will have to be (re)created. To do that, issue: &prompt.root; cd /dev && ./MAKEDEV "fd*" The disk size in 5.0 and newer releases In 5.0, &man.devfs.5; will automatically manage device nodes in /dev, so use of MAKEDEV is not necessary. The desired disk size is passed to &man.fdformat.1; through the flag. Supported sizes are listed in &man.fdcontrol.8;, but be advised that 1440kB is what works best. Formatting A floppy disk needs to be low-level formated before it can be used. This is usually done by the vendor, but formatting is a good way to check media integrity. Although it is possible to force larger (or smaller) disk sizes, 1440kB is what most floppy disks are designed for. To low-level format the floppy disk you need to use &man.fdformat.1;. This utility expects the device name as an argument. Make note of any error messages, as these can help determine if the disk is good or bad. Formatting in 4.X and earlier releases Use the /dev/fdN.size devices to format the floppy. Insert a new 3.5inch floppy disk in your drive and issue: &prompt.root; /usr/sbin/fdformat /dev/fd0.1440 Formatting in 5.0 and newer releases Use the /dev/fdN devices to format the floppy. Insert a new 3.5inch floppy disk in your drive and issue: &prompt.root; /usr/sbin/fdformat -f 1440 /dev/fd0 The Disk Label After low-level formatting the disk, you will need to place a disk label on it. This disk label will be destroyed later, but it is needed by the system to determine the size of the disk and its geometry later. The new disk label will take over the whole disk, and will contain all the proper information about the geometry of the floppy. The geometry values for the disk label are listed in - /etc/disktab. + /etc/disktab. You can run now &man.disklabel.8; like so: &prompt.root; /sbin/disklabel -B -r -w /dev/fd0 fd1440 The file system Now the floppy is ready to be high-level formated. This will place a new file system on it, which will let FreeBSD read and write to the disk. After creating the new file system, the disk label is destroyed, so if you want to reformat the disk, you will have to recreate the disk label. The floppy's file system can be either UFS or FAT. FAT is generally a better choice for floppies. To put a new file system on the floppy, issue: &prompt.root; /sbin/newfs_msdos /dev/fd0 The disk is now ready for use. Using the floppy To use the floppy, mount it with &man.mount.msdos.8; (in 4.X and earlier releases) or &man.mount.msdosfs.8; (in 5.0 or newer releases). One can also use mtools from the ports collection. Creating and Using Data Tapes tape media The major tape media are the 4mm, 8mm, QIC, mini-cartridge and DLT. 4mm (DDS: Digital Data Storage) tape media DDS (4mm) tapes tape media QIC tapes 4mm tapes are replacing QIC as the workstation backup media of choice. This trend accelerated greatly when Conner purchased Archive, a leading manufacturer of QIC drives, and then stopped production of QIC drives. 4mm drives are small and quiet but do not have the reputation for reliability that is enjoyed by 8mm drives. The cartridges are less expensive and smaller (3 x 2 x 0.5 inches, 76 x 51 x 12 mm) than 8mm cartridges. 4mm, like 8mm, has comparatively short head life for the same reason, both use helical scan. Data throughput on these drives starts ~150 kB/s, peaking at ~500 kB/s. Data capacity starts at 1.3 GB and ends at 2.0 GB. Hardware compression, available with most of these drives, approximately doubles the capacity. Multi-drive tape library units can have 6 drives in a single cabinet with automatic tape changing. Library capacities reach 240 GB. The DDS-3 standard now supports tape capacities up to 12 GB (or 24 GB compressed). 4mm drives, like 8mm drives, use helical-scan. All the benefits and drawbacks of helical-scan apply to both 4mm and 8mm drives. Tapes should be retired from use after 2,000 passes or 100 full backups. 8mm (Exabyte) tape media Exabyte (8mm) tapes 8mm tapes are the most common SCSI tape drives; they are the best choice of exchanging tapes. Nearly every site has an Exabyte 2 GB 8mm tape drive. 8mm drives are reliable, convenient and quiet. Cartridges are inexpensive and small (4.8 x 3.3 x 0.6 inches; 122 x 84 x 15 mm). One downside of 8mm tape is relatively short head and tape life due to the high rate of relative motion of the tape across the heads. Data throughput ranges from ~250 kB/s to ~500 kB/s. Data sizes start at 300 MB and go up to 7 GB. Hardware compression, available with most of these drives, approximately doubles the capacity. These drives are available as single units or multi-drive tape libraries with 6 drives and 120 tapes in a single cabinet. Tapes are changed automatically by the unit. Library capacities reach 840+ GB. The Exabyte Mammoth model supports 12 GB on one tape (24 GB with compression) and costs approximately twice as much as conventional tape drives. Data is recorded onto the tape using helical-scan, the heads are positioned at an angle to the media (approximately 6 degrees). The tape wraps around 270 degrees of the spool that holds the heads. The spool spins while the tape slides over the spool. The result is a high density of data and closely packed tracks that angle across the tape from one edge to the other. QIC tape media QIC-150 QIC-150 tapes and drives are, perhaps, the most common tape drive and media around. QIC tape drives are the least expensive serious backup drives. The downside is the cost of media. QIC tapes are expensive compared to 8mm or 4mm tapes, up to 5 times the price per GB data storage. But, if your needs can be satisfied with a half-dozen tapes, QIC may be the correct choice. QIC is the most common tape drive. Every site has a QIC drive of some density or another. Therein lies the rub, QIC has a large number of densities on physically similar (sometimes identical) tapes. QIC drives are not quiet. These drives audibly seek before they begin to record data and are clearly audible whenever reading, writing or seeking. QIC tapes measure (6 x 4 x 0.7 inches; 15.2 x 10.2 x 1.7 mm). Mini-cartridges, which also use 1/4" wide tape are discussed separately. Tape libraries and changers are not available. Data throughput ranges from ~150 kB/s to ~500 kB/s. Data capacity ranges from 40 MB to 15 GB. Hardware compression is available on many of the newer QIC drives. QIC drives are less frequently installed; they are being supplanted by DAT drives. Data is recorded onto the tape in tracks. The tracks run along the long axis of the tape media from one end to the other. The number of tracks, and therefore the width of a track, varies with the tape's capacity. Most if not all newer drives provide backward-compatibility at least for reading (but often also for writing). QIC has a good reputation regarding the safety of the data (the mechanics are simpler and more robust than for helical scan drives). Tapes should be retired from use after 5,000 backups. XXX* Mini-Cartridge DLT tape media DLT DLT has the fastest data transfer rate of all the drive types listed here. The 1/2" (12.5mm) tape is contained in a single spool cartridge (4 x 4 x 1 inches; 100 x 100 x 25 mm). The cartridge has a swinging gate along one entire side of the cartridge. The drive mechanism opens this gate to extract the tape leader. The tape leader has an oval hole in it which the drive uses to hook the tape. The take-up spool is located inside the tape drive. All the other tape cartridges listed here (9 track tapes are the only exception) have both the supply and take-up spools located inside the tape cartridge itself. Data throughput is approximately 1.5 MB/s, three times the throughput of 4mm, 8mm, or QIC tape drives. Data capacities range from 10 GB to 20 GB for a single drive. Drives are available in both multi-tape changers and multi-tape, multi-drive tape libraries containing from 5 to 900 tapes over 1 to 20 drives, providing from 50 GB to 9 TB of storage. With compression, DLT Type IV format supports up to 70 GB capacity. Data is recorded onto the tape in tracks parallel to the direction of travel (just like QIC tapes). Two tracks are written at once. Read/write head lifetimes are relatively long; once the tape stops moving, there is no relative motion between the heads and the tape. AIT tape media AIT AIT is a new format from Sony, and can hold up to 50 GB (with compression) per tape. The tapes contain memory chips which retain an index of the tape's contents. This index can be rapidly read by the tape drive to determine the position of files on the tape, instead of the several minutes that would be required for other tapes. Software such as SAMS:Alexandria can operate forty or more AIT tape libraries, communicating directly with the tape's memory chip to display the contents on screen, determine what files were backed up to which tape, locate the correct tape, load it, and restore the data from the tape. Libraries like this cost in the region of $20,000, pricing them a little out of the hobbyist market. Using a New Tape for the First Time The first time that you try to read or write a new, completely blank tape, the operation will fail. The console messages should be similar to: sa0(ncr1:4:0): NOT READY asc:4,1 sa0(ncr1:4:0): Logical unit is in process of becoming ready The tape does not contain an Identifier Block (block number 0). All QIC tape drives since the adoption of QIC-525 standard write an Identifier Block to the tape. There are two solutions: mt fsf 1 causes the tape drive to write an Identifier Block to the tape. Use the front panel button to eject the tape. Re-insert the tape and dump data to the tape. dump will report DUMP: End of tape detected and the console will show: HARDWARE FAILURE info:280 asc:80,96. rewind the tape using: mt rewind. Subsequent tape operations are successful. Backups to Floppies Can I Use floppies for Backing Up My Data? backup floppies floppy disks Floppy disks are not really a suitable media for making backups as: The media is unreliable, especially over long periods of time. Backing up and restoring is very slow. They have a very limited capacity (the days of backing up an entire hard disk onto a dozen or so floppies has long since passed). However, if you have no other method of backing up your data then floppy disks are better than no backup at all. If you do have to use floppy disks then ensure that you use good quality ones. Floppies that have been lying around the office for a couple of years are a bad choice. Ideally use new ones from a reputable manufacturer. So How Do I Backup My Data to Floppies? The best way to backup to floppy disk is to use &man.tar.1; with the (multi volume) option, which allows backups to span multiple floppies. To backup all the files in the current directory and sub-directory use this (as root): &prompt.root; tar Mcvf /dev/fd0 * When the first floppy is full &man.tar.1; will prompt you to insert the next volume (because &man.tar.1; is media independent it refers to volumes; in this context it means floppy disk). Prepare volume #2 for /dev/fd0 and hit return: This is repeated (with the volume number incrementing) until all the specified files have been archived. Can I Compress My Backups? tar gzip compression Unfortunately, &man.tar.1; will not allow the option to be used for multi-volume archives. You could, of course, &man.gzip.1; all the files, &man.tar.1; them to the floppies, then &man.gunzip.1; the files again! How Do I Restore My Backups? To restore the entire archive use: &prompt.root; tar Mxvf /dev/fd0 There are two ways that you can use to restore only specific files. First, you can start with the first floppy and use: &prompt.root; tar Mxvf /dev/fd0 filename The utility &man.tar.1; will prompt you to insert subsequent floppies until it finds the required file. Alternatively, if you know which floppy the file is on then you can simply insert that floppy and use the same command as above. Note that if the first file on the floppy is a continuation from the previous one then &man.tar.1; will warn you that it cannot restore it, even if you have not asked it to! Backup Basics backup software and basics The three major backup programs are &man.dump.8;, &man.tar.1;, and &man.cpio.1;. Dump and Restore backup software dump / restore dump restore The traditional Unix backup programs are dump and restore. They operate on the drive as a collection of disk blocks, below the abstractions of files, links and directories that are created by the file systems. dump backs up an entire file system on a device. It is unable to backup only part of a file system or a directory tree that spans more than one file system. dump does not write files and directories to tape, but rather writes the raw data blocks that comprise files and directories. If you use dump on your root directory, you would not back up /home, /usr or many other directories since these are typically mount points for other file systems or symbolic links into those file systems. dump has quirks that remain from its early days in Version 6 of AT&T Unix (circa 1975). The default parameters are suitable for 9-track tapes (6250 bpi), not the high-density media available today (up to 62,182 ftpi). These defaults must be overridden on the command line to utilize the capacity of current tape drives. .rhosts It is also possible to backup data across the network to a tape drive attached to another computer with rdump and rrestore. Both programs rely upon rcmd and ruserok to access the remote tape drive. Therefore, the user performing the backup must be listed in the .rhosts file on the remote computer. The arguments to rdump and rrestore must be suitable to use on the remote computer. When rdumping from a FreeBSD computer to an Exabyte tape drive connected to a Sun called komodo, use: &prompt.root; /sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&1 Beware: there are security implications to allowing .rhosts authentication. Evaluate your situation carefully. It is also possible to use dump and restore in a more secure fashion over ssh. Using <command>dump</command> over <application>ssh</application> &prompt.root; /sbin/dump -0uan -f - /usr | gzip -2 | ssh1 -c blowfish \ targetuser@targetmachine.example.com dd of=/mybigfiles/dump-usr-l0.gz <command>tar</command> backup software tar &man.tar.1; also dates back to Version 6 of AT&T Unix (circa 1975). tar operates in cooperation with the file system; tar writes files and directories to tape. tar does not support the full range of options that are available from &man.cpio.1;, but tar does not require the unusual command pipeline that cpio uses. tar Most versions of tar do not support backups across the network. The GNU version of tar, which FreeBSD utilizes, supports remote devices using the same syntax as rdump. To tar to an Exabyte tape drive connected to a Sun called komodo, use: &prompt.root; /usr/bin/tar cf komodo:/dev/nsa8 . 2>&1 For versions without remote device support, you can use a pipeline and rsh to send the data to a remote tape drive. &prompt.root; tar cf - . | rsh hostname dd of=tape-device obs=20b If you are worried about the security of backing up over a network you should use the ssh command instead of rsh. <command>cpio</command> backup software cpio &man.cpio.1; is the original Unix file interchange tape program for magnetic media. cpio has options (among many others) to perform byte-swapping, write a number of different archive formats, and pipe the data to other programs. This last feature makes cpio an excellent choice for installation media. cpio does not know how to walk the directory tree and a list of files must be provided through stdin. cpio cpio does not support backups across the network. You can use a pipeline and rsh to send the data to a remote tape drive. &prompt.root; for f in directory_list; do find $f >> backup.list done &prompt.root; cpio -v -o --format=newc < backup.list | ssh user@host "cat > backup_device" Where directory_list is the list of directories you want to back up, user@host is the user/hostname combination that will be performing the backups, and backup_device is where the backups should be written to (e.g., /dev/nsa0). <command>pax</command> backup software pax pax POSIX IEEE &man.pax.1; is IEEE/POSIX's answer to tar and cpio. Over the years the various versions of tar and cpio have gotten slightly incompatible. So rather than fight it out to fully standardize them, POSIX created a new archive utility. pax attempts to read and write many of the various cpio and tar formats, plus new formats of its own. Its command set more resembles cpio than tar. <application>Amanda</application> backup software Amanda Amanda Amanda (Advanced Maryland Network Disk Archiver) is a client/server backup system, rather than a single program. An Amanda server will backup to a single tape drive any number of computers that have Amanda clients and a network connection to the Amanda server. A common problem at sites with a number of large disks is that the length of time required to backup to data directly to tape exceeds the amount of time available for the task. Amanda solves this problem. Amanda can use a holding disk to backup several file systems at the same time. Amanda creates archive sets: a group of tapes used over a period of time to create full backups of all the file systems listed in Amanda's configuration file. The archive set also contains nightly incremental (or differential) backups of all the file systems. Restoring a damaged file system requires the most recent full backup and the incremental backups. The configuration file provides fine control of backups and the network traffic that Amanda generates. Amanda will use any of the above backup programs to write the data to tape. Amanda is available as either a port or a package, it is not installed by default. Do Nothing Do nothing is not a computer program, but it is the most widely used backup strategy. There are no initial costs. There is no backup schedule to follow. Just say no. If something happens to your data, grin and bear it! If your time and your data is worth little to nothing, then Do nothing is the most suitable backup program for your computer. But beware, Unix is a useful tool, you may find that within six months you have a collection of files that are valuable to you. Do nothing is the correct backup method for /usr/obj and other directory trees that can be exactly recreated by your computer. An example is the files that comprise the HTML or PostScript version of this Handbook. These document formats have been created from SGML input files. Creating backups of the HTML or PostScript files is not necessary. The SGML files are backed up regularly. Which Backup Program Is Best? LISA &man.dump.8; Period. Elizabeth D. Zwicky torture tested all the backup programs discussed here. The clear choice for preserving all your data and all the peculiarities of Unix file systems is dump. Elizabeth created file systems containing a large variety of unusual conditions (and some not so unusual ones) and tested each program by doing a backup and restore of those file systems. The peculiarities included: files with holes, files with holes and a block of nulls, files with funny characters in their names, unreadable and unwritable files, devices, files that change size during the backup, files that are created/deleted during the backup and more. She presented the results at LISA V in Oct. 1991. See torture-testing Backup and Archive Programs. Emergency Restore Procedure Before the Disaster There are only four steps that you need to perform in preparation for any disaster that may occur. disklabel First, print the disklabel from each of your disks (e.g. disklabel da0 | lpr), your file system table (/etc/fstab) and all boot messages, two copies of each. fix-it floppies Second, determine that the boot and fix-it floppies (boot.flp and fixit.flp) have all your devices. The easiest way to check is to reboot your machine with the boot floppy in the floppy drive and check the boot messages. If all your devices are listed and functional, skip on to step three. Otherwise, you have to create two custom bootable floppies which have a kernel that can mount all of your disks and access your tape drive. These floppies must contain: fdisk, disklabel, newfs, mount, and whichever backup program you use. These programs must be statically linked. If you use dump, the floppy must contain restore. Third, create backup tapes regularly. Any changes that you make after your last backup may be irretrievably lost. Write-protect the backup tapes. Fourth, test the floppies (either boot.flp and fixit.flp or the two custom bootable floppies you made in step two.) and backup tapes. Make notes of the procedure. Store these notes with the bootable floppy, the printouts and the backup tapes. You will be so distraught when restoring that the notes may prevent you from destroying your backup tapes (How? In place of tar xvf /dev/sa0, you might accidentally type tar cvf /dev/sa0 and over-write your backup tape). For an added measure of security, make bootable floppies and two backup tapes each time. Store one of each at a remote location. A remote location is NOT the basement of the same office building. A number of firms in the World Trade Center learned this lesson the hard way. A remote location should be physically separated from your computers and disk drives by a significant distance. A Script for Creating a Bootable Floppy /mnt/sbin/init gzip -c -best /sbin/fsck > /mnt/sbin/fsck gzip -c -best /sbin/mount > /mnt/sbin/mount gzip -c -best /sbin/halt > /mnt/sbin/halt gzip -c -best /sbin/restore > /mnt/sbin/restore gzip -c -best /bin/sh > /mnt/bin/sh gzip -c -best /bin/sync > /mnt/bin/sync cp /root/.profile /mnt/root cp -f /dev/MAKEDEV /mnt/dev chmod 755 /mnt/dev/MAKEDEV chmod 500 /mnt/sbin/init chmod 555 /mnt/sbin/fsck /mnt/sbin/mount /mnt/sbin/halt chmod 555 /mnt/bin/sh /mnt/bin/sync chmod 6555 /mnt/sbin/restore # # create the devices nodes # cd /mnt/dev ./MAKEDEV std ./MAKEDEV da0 ./MAKEDEV da1 ./MAKEDEV da2 ./MAKEDEV sa0 ./MAKEDEV pty0 cd / # # create minimum file system table # cat > /mnt/etc/fstab < /mnt/etc/passwd < /mnt/etc/master.passwd < After the Disaster The key question is: did your hardware survive? You have been doing regular backups so there is no need to worry about the software. If the hardware has been damaged. First, replace those parts that have been damaged. If your hardware is okay, check your floppies. If you are using a custom boot floppy, boot single-user (type -s at the boot: prompt). Skip the following paragraph. If you are using the boot.flp and fixit.flp floppies, keep reading. Insert the boot.flp floppy in the first floppy drive and boot the computer. The original install menu will be displayed on the screen. Select the Fixit--Repair mode with CDROM or floppy. option. Insert the fixit.flp when prompted. restore and the other programs that you need are located in /mnt2/stand. Recover each file system separately. mount root partition disklabel newfs Try to mount (e.g. mount /dev/da0a /mnt) the root partition of your first disk. If the disklabel was damaged, use disklabel to re-partition and label the disk to match the label that you printed and saved. Use newfs to re-create the file systems. Re-mount the root partition of the floppy read-write (mount -u -o rw /mnt). Use your backup program and backup tapes to recover the data for this file system (e.g. restore vrf /dev/sa0). Unmount the file system (e.g. umount /mnt). Repeat for each file system that was damaged. Once your system is running, backup your data onto new tapes. Whatever caused the crash or data loss may strike again. Another hour spent now may save you from further distress later. * I did not prepare for the Disaster, What Now? ]]> Marc Fonvieille Reorganized and enhanced by Network, Memory, and File-Backed File Systems virtual disks disks virtual Aside from the disks you physically insert into your computer: floppies, CDs, hard drives, and so forth; other forms of disks are understood by FreeBSD - the virtual disks. NFS Coda disks memory These include network file systems such as the Network File System and Coda, memory-based file systems and file-backed file systems. According to the FreeBSD version you run, you will have to use different tools for creation and use of file-backed and memory-based file systems. The FreeBSD 4.X users will have to use &man.MAKEDEV.8; to create the required devices. FreeBSD 5.0 and later use &man.devfs.5; to allocate device nodes transparently for the user. File-Backed File System under FreeBSD 4.X disks file-backed (4.X) The utility &man.vnconfig.8; configures and enables vnode pseudo-disk devices. A vnode is a representation of a file, and is the focus of file activity. This means that &man.vnconfig.8; uses files to create and operate a file system. One possible use is the mounting of floppy or CD images kept in files. To use &man.vnconfig.8;, you need &man.vn.4; support in your kernel configuration file: pseudo-device vn To mount an existing file system image: Using vnconfig to mount an Existing File System Image under FreeBSD 4.X &prompt.root; vnconfig vn0 diskimage &prompt.root; mount /dev/vn0c /mnt To create a new file system image with &man.vnconfig.8;: Creating a New File-Backed Disk with <command>vnconfig</command> &prompt.root; dd if=/dev/zero of=newimage bs=1k count=5k 5120+0 records in 5120+0 records out &prompt.root; vnconfig -s labels -c vn0 newimage &prompt.root; disklabel -r -w vn0 auto &prompt.root; newfs vn0c Warning: 2048 sector(s) in last cylinder unallocated /dev/vn0c: 10240 sectors in 3 cylinders of 1 tracks, 4096 sectors 5.0MB in 1 cyl groups (16 c/g, 32.00MB/g, 1280 i/g) super-block backups (for fsck -b #) at: 32 &prompt.root; mount /dev/vn0c /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/vn0c 4927 1 4532 0% /mnt File-Backed File System under FreeBSD 5.X disks file-backed (5.X) The utility &man.mdconfig.8; is used to configure and enable memory disks, &man.md.4;, under FreeBSD 5.X. To use &man.mdconfig.8;, you have to load &man.md.4; module or to add the support in your kernel configuration file: device md The &man.mdconfig.8; command supports three kinds of memory backed virtual disks: memory disks allocated with &man.malloc.9;, memory disks using a file or swap space as backing. One possible use is the mounting of floppy or CD images kept in files. To mount an existing file system image: Using <command>mdconfig</command> to mount an Existing File System Image under FreeBSD 5.X &prompt.root; mdconfig -a -t vnode -f diskimage -u 0 &prompt.root; mount /dev/md0c /mnt To create a new file system image with &man.mdconfig.8;: Creating a New File-Backed Disk with <command>mdconfig</command> &prompt.root; dd if=/dev/zero of=newimage bs=1k count=5k 5120+0 records in 5120+0 records out &prompt.root; mdconfig -a -t vnode -f newimage -u 0 &prompt.root; disklabel -r -w md0 auto &prompt.root; newfs md0c /dev/md0c: 5.0MB (10240 sectors) block size 16384, fragment size 2048 using 4 cylinder groups of 1.27MB, 81 blks, 256 inodes. super-block backups (for fsck -b #) at: 32, 2624, 5216, 7808 &prompt.root; mount /dev/md0c /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md0c 4846 2 4458 0% /mnt If you do not specify the unit number with the option, &man.mdconfig.8; will use the &man.md.4; automatic allocation to select an unused device. The name of the allocated unit will be output on stdout like md4. For more details about &man.mdconfig.8;, please refer to the manual page. The utility &man.mdconfig.8; is very useful, however it asks many command lines to create a file-backed file system. FreeBSD 5.0 also comes with a tool called &man.mdmfs.8;, this program configures a &man.md.4; disk using &man.mdconfig.8;, puts a UFS file system on it using &man.newfs.8;, and mounts it using &man.mount.8;. For example, if you want to create and mount the same file system image as above, simply type the following: &prompt.root; dd if=/dev/zero of=newimage bs=1k count=5k 5120+0 records in 5120+0 records in 5120+0 records out &prompt.root; mdmfs -F newimage -s 5m md0 /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md0 4846 2 4458 0% /mnt If you use the option without unit number, &man.mdmfs.8; will use &man.md.4; auto-unit feature to automatically select an unused device. For more details about &man.mdmfs.8;, please refer to the manual page. Memory-Based File System under FreeBSD 4.X disks memory file system (4.X) The &man.md.4; driver is a simple, efficient means to create memory file systems under FreeBSD 4.X. &man.malloc.9; is used to allocate the memory. Simply take a file system you have prepared with, for example, &man.vnconfig.8;, and: md Memory Disk under FreeBSD 4.X &prompt.root; dd if=newimage of=/dev/md0 5120+0 records in 5120+0 records out &prompt.root; mount /dev/md0c /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md0c 4927 1 4532 0% /mnt For more details, please refer to &man.md.4; manual page. Memory-Based File System under FreeBSD 5.X disks memory file system (5.X) The same tools are used for memory-based and file-backed file systems: &man.mdconfig.8; or &man.mdmfs.8;. The storage for memory-based file system is allocated with &man.malloc.9;. Creating a New Memory-Based Disk with <command>mdconfig</command> &prompt.root; mdconfig -a -t malloc -s 5m -u 1 &prompt.root; newfs -U md1 /dev/md1: 5.0MB (10240 sectors) block size 16384, fragment size 2048 using 4 cylinder groups of 1.27MB, 81 blks, 256 inodes. with soft updates super-block backups (for fsck -b #) at: 32, 2624, 5216, 7808 &prompt.root; mount /dev/md1 /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md1 4846 2 4458 0% /mnt Creating a New Memory-Based Disk with <command>mdmfs</command> &prompt.root; mdmfs -M -s 5m md2 /mnt &prompt.root; df /mnt Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md2 4846 2 4458 0% /mnt Instead of using a &man.malloc.9; backed file system, it is possible to use swap, for that just replace with in the command line of &man.mdconfig.8;. The &man.mdmfs.8; utility by default (without ) creates a swap-based disk. For more details, please refer to &man.mdconfig.8; and &man.mdmfs.8; manual pages. Detaching a Memory Disk from the System disks detaching a memory disk When a memory-based or file-based file system is not used, you should release all resources to the system. The first thing to do is to unmount the file system, then use &man.mdconfig.8; to detach the disk from the system and release the resources. For example to detach and free all resources used by /dev/md4: &prompt.root; mdconfig -d -u 4 It is possible to list information about configured &man.md.4; devices in using the command mdconfig -l. For FreeBSD 4.X, &man.vnconfig.8; is used to detach the device. For example to detach and free all resources used by /dev/vn4: &prompt.root; vnconfig -u vn4 Tom Rhodes Contributed by File System Snapshots file systems snapshots FreeBSD 5.0 offers a new feature in conjunction with Soft Updates: File system snapshots. Snapshots allow a user to create images of specified file systems, and treat them as a file. Snapshot files must be created in the file system that the action is performed on, and a user may create no more than 20 snapshots per file system. Active snapshots are recorded in the superblock so they are persistent across unmount and remount operations along with system reboots. When a snapshot is no longer required, it can be removed with the standard &man.rm.1; command. Snapshots may be removed in any order, however all the used space may not be acquired because another snapshot will possibly claim some of the released blocks. During initial creation, the flag (see the &man.chflags.1; manual page) is set to ensure that even root cannot write to the snapshot. The &man.unlink.1; command makes an exception for snapshot files since it allows them to be removed with the flag set, so it is not necessary to clear the flag before removing a snapshot file. Snapshots are created with the &man.mount.8; command. To place a snapshot of /var in the file /var/snapshot/snap use the following command: &prompt.root; mount -u -o snapshot /var/snapshot/snap /var Once a snapshot has been created, they have several uses: Some administrators will use a snapshot file for backup purposes, because the snapshot can be transfered to CDs or tape. File integrity, &man.fsck.8; may be ran on the snapshot. Assuming that the file system was clean when it was mounted, you should always get a clean (and unchanging) result. This is essentially what the background &man.fsck.8; process does. Run the &man.dump.8; utility on the snapshot. A dump will be returned that is consistent with the file system and the timestamp of the snapshot. &man.dump.8; can also take a snapshot, create a dump image and then remove the snapshot in one command using the flag. &man.mount.8; the snapshot as a frozen image of the file system. To &man.mount.8; the snapshot /var/snapshot/snap run: &prompt.root; mdconfig -a -t vnode -f /var/snapshot/snap -u 4 &prompt.root; mount -r /dev/md4 /mnt You can now walk the hierarchy of your frozen /var file system mounted at /mnt. Everything will be in the same state it was during the snapshot creation time. The only exception is that any earlier snapshots will appear as zero length files. When the use of a snapshot has delimited, it can be unmounted with: &prompt.root; umount /mnt &prompt.root; mdconfig -d -u 4 For more information about and file system snapshots, including technical papers, you can visit Marshall Kirk McKusick's website at http://www.mckusick.com. File System Quotas accounting disk space disk quotas Quotas are an optional feature of the operating system that allow you to limit the amount of disk space and/or the number of files a user or members of a group may allocate on a per-file system basis. This is used most often on timesharing systems where it is desirable to limit the amount of resources any one user or group of users may allocate. This will prevent one user or group of users from consuming all of the available disk space. Configuring Your System to Enable Disk Quotas Before attempting to use disk quotas, it is necessary to make sure that quotas are configured in your kernel. This is done by adding the following line to your kernel configuration file: options QUOTA The stock GENERIC kernel does not have this enabled by default, so you will have to configure, build and install a custom kernel in order to use disk quotas. Please refer to for more information on kernel configuration. Next you will need to enable disk quotas in /etc/rc.conf. This is done by adding the line: enable_quotas="YES" disk quotas checking For finer control over your quota startup, there is an additional configuration variable available. Normally on bootup, the quota integrity of each file system is checked by the &man.quotacheck.8; program. The &man.quotacheck.8; facility insures that the data in the quota database properly reflects the data on the file system. This is a very time consuming process that will significantly affect the time your system takes to boot. If you would like to skip this step, a variable in /etc/rc.conf is made available for the purpose: check_quotas="NO" If you are running FreeBSD prior to 3.2-RELEASE, the configuration is simpler, and consists of only one variable. Set the following in your /etc/rc.conf: check_quotas="YES" Finally you will need to edit /etc/fstab to enable disk quotas on a per-file system basis. This is where you can either enable user or group quotas or both for all of your file systems. To enable per-user quotas on a file system, add the option to the options field in the /etc/fstab entry for the file system you want to enable quotas on. For example: /dev/da1s2g /home ufs rw,userquota 1 2 Similarly, to enable group quotas, use the option instead of . To enable both user and group quotas, change the entry as follows: /dev/da1s2g /home ufs rw,userquota,groupquota 1 2 By default, the quota files are stored in the root directory of the file system with the names quota.user and quota.group for user and group quotas respectively. See &man.fstab.5; for more information. Even though the &man.fstab.5; manual page says that you can specify an alternate location for the quota files, this is not recommended because the various quota utilities do not seem to handle this properly. At this point you should reboot your system with your new kernel. /etc/rc will automatically run the appropriate commands to create the initial quota files for all of the quotas you enabled in /etc/fstab, so there is no need to manually create any zero length quota files. In the normal course of operations you should not be required to run the &man.quotacheck.8;, &man.quotaon.8;, or &man.quotaoff.8; commands manually. However, you may want to read their manual pages just to be familiar with their operation. Setting Quota Limits disk quotas limits Once you have configured your system to enable quotas, verify that they really are enabled. An easy way to do this is to run: &prompt.root; quota -v You should see a one line summary of disk usage and current quota limits for each file system that quotas are enabled on. You are now ready to start assigning quota limits with the &man.edquota.8; command. You have several options on how to enforce limits on the amount of disk space a user or group may allocate, and how many files they may create. You may limit allocations based on disk space (block quotas) or number of files (inode quotas) or a combination of both. Each of these limits are further broken down into two categories: hard and soft limits. hard limit A hard limit may not be exceeded. Once a user reaches his hard limit he may not make any further allocations on the file system in question. For example, if the user has a hard limit of 500 blocks on a file system and is currently using 490 blocks, the user can only allocate an additional 10 blocks. Attempting to allocate an additional 11 blocks will fail. soft limit Soft limits, on the other hand, can be exceeded for a limited amount of time. This period of time is known as the grace period, which is one week by default. If a user stays over his or her soft limit longer than the grace period, the soft limit will turn into a hard limit and no further allocations will be allowed. When the user drops back below the soft limit, the grace period will be reset. The following is an example of what you might see when you run the &man.edquota.8; command. When the &man.edquota.8; command is invoked, you are placed into the editor specified by the EDITOR environment variable, or in the vi editor if the EDITOR variable is not set, to allow you to edit the quota limits. &prompt.root; edquota -u test Quotas for user test: /usr: blocks in use: 65, limits (soft = 50, hard = 75) inodes in use: 7, limits (soft = 50, hard = 60) /usr/var: blocks in use: 0, limits (soft = 50, hard = 75) inodes in use: 0, limits (soft = 50, hard = 60) You will normally see two lines for each file system that has quotas enabled. One line for the block limits, and one line for inode limits. Simply change the value you want updated to modify the quota limit. For example, to raise this user's block limit from a soft limit of 50 and a hard limit of 75 to a soft limit of 500 and a hard limit of 600, change: /usr: blocks in use: 65, limits (soft = 50, hard = 75) to: /usr: blocks in use: 65, limits (soft = 500, hard = 600) The new quota limits will be in place when you exit the editor. Sometimes it is desirable to set quota limits on a range of UIDs. This can be done by use of the option on the &man.edquota.8; command. First, assign the desired quota limit to a user, and then run edquota -p protouser startuid-enduid. For example, if user test has the desired quota limits, the following command can be used to duplicate those quota limits for UIDs 10,000 through 19,999: &prompt.root; edquota -p test 10000-19999 For more information see &man.edquota.8; manual page. Checking Quota Limits and Disk Usage disk quotas checking You can use either the &man.quota.1; or the &man.repquota.8; commands to check quota limits and disk usage. The &man.quota.1; command can be used to check individual user or group quotas and disk usage. A user may only examine his own quota, and the quota of a group he is a member of. Only the super-user may view all user and group quotas. The &man.repquota.8; command can be used to get a summary of all quotas and disk usage for file systems with quotas enabled. The following is some sample output from the quota -v command for a user that has quota limits on two file systems. Disk quotas for user test (uid 1002): Filesystem blocks quota limit grace files quota limit grace /usr 65* 50 75 5days 7 50 60 /usr/var 0 50 75 0 50 60 grace period On the /usr file system in the above example, this user is currently 15 blocks over the soft limit of 50 blocks and has 5 days of the grace period left. Note the asterisk * which indicates that the user is currently over his quota limit. Normally file systems that the user is not using any disk space on will not show up in the output from the &man.quota.1; command, even if he has a quota limit assigned for that file system. The option will display those file systems, such as the /usr/var file system in the above example. Quotas over NFS NFS Quotas are enforced by the quota subsystem on the NFS server. The &man.rpc.rquotad.8; daemon makes quota information available to the &man.quota.1; command on NFS clients, allowing users on those machines to see their quota statistics. Enable rpc.rquotad in /etc/inetd.conf like so: rquotad/1 dgram rpc/udp wait root /usr/libexec/rpc.rquotad rpc.rquotad Now restart inetd: &prompt.root; kill -HUP `cat /var/run/inetd.pid` Lucky Green Contributed by
shamrock@cypherpunks.to
 Encrypting Disk Partitions disks encrypting FreeBSD offers excellent online protections against unauthorized data access. File permissions and Mandatory Access Control (MAC) (see ) help prevent unauthorized third-parties from accessing data while the operating system is active and the computer is powered up. However, the permissions enforced by the operating system are irrelevant if an attacker has physical access to a computer and can simply move the computer's hard drive to another system to copy and analyze the sensitive data. Regardless of how an attacker may have come into possession of a hard drive or powered-down computer, GEOM Based Disk Encryption (gbde) can protect the data on the computer's file systems against even highly-motivated attackers with significant resources. Unlike cumbersome encryption methods that encrypt only individual files, gbde transparently encrypts entire file systems. No cleartext ever touches the hard drive's platter. Enabling gbde in the Kernel Become <username>root</username> Configuring gbde requires super-user privileges. &prompt.user; su - Password: Verify the operating system version &man.gbde.4; requires FreeBSD 5.0 or higher. &prompt.root; uname -r 5.0-RELEASE Add &man.gbde.4; support to the kernel configuration file Using your favorite text editor, add the following line to your kernel configuration file: options GEOM_BDE Configure, recompile, and install the FreeBSD kernel. This process is described in . Reboot into the new kernel. Preparing the Encrypted Hard Drive The following example assumes that you are adding a new hard drive to your system that will hold a single encrypted partition. This partition will be mounted as /private. gbde can also be used to encrypt /home and /var/mail, but this requires more complex instructions which exceed the scope of this introduction. Add the new hard drive Install the new drive to the system as explained in . For the purposes of this example, a new hard drive partition has been added as /dev/ad4s1c. The /dev/ad0s1* devices represent existing standard FreeBSD partitions on the example system. &prompt.root; ls /dev/ad* /dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 /dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c /dev/ad0s1a /dev/ad0s1d /dev/ad4 Create a directory to hold gbde lock files &prompt.root; mkdir /etc/gbde The gbde lock file contains information that gbde requires to access encrypted partitions. Without access to the lock file, gbde will not be able to decrypt the data contained in the encrypted partition without significant manual intervention which is not supported by the software. Each encrypted partition uses a separate lock file. Initialize the gbde partition A gbde partition must be initialized before it can be used. This initialization needs to be performed only once: &prompt.root; gbde init /dev/ad4s1c -i -L /etc/gbde/ad4s1c &man.gbde.8; will open your editor, permitting you to set various configuration options in a template. For use with UFS1 or UFS2, set the sector_size to 2048: $FreeBSD: src/sbin/gbde/template.txt,v 1.1 2002/10/20 11:16:13 phk Exp $ # # Sector size is the smallest unit of data which can be read or written. # Making it too small decreases performance and decreases available space. # Making it too large may prevent filesystems from working. 512 is the # minimum and always safe. For UFS, use the fragment size # sector_size = 2048 [...] &man.gbde.8; will ask you twice to type the passphrase that should be used to secure the data. The passphrase must be the same both times. gbde's ability to protect your data depends entirely on the quality of the passphrase that you choose. For tips on how to select a secure passphrase that is easy to remember, see the Diceware Passphrase website. The gbde init command creates a lock file for your gbde partition that in this example is stored as /etc/gbde/ad4s1c. gbde lock files must be backed up together with the contents of any encrypted partitions. While deleting a lock file alone cannot prevent a determined attacker from decrypting a gbde partition, without the lock file, the legitimate owner will be unable to access the data on the encrypted partition without a significant amount of work that is totally unsupported by &man.gbde.8; and its designer. Attach the encrypted partition to the kernel &prompt.root; gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c You will be asked to provide the passphrase that you selected during the initialization of the encrypted partition. The new encrypted device will show up in /dev as /dev/device_name.bde: &prompt.root; ls /dev/ad* /dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 /dev/ad0s1 /dev/ad0s1c /dev/ad0s1f /dev/ad4s1c /dev/ad0s1a /dev/ad0s1d /dev/ad4 /dev/ad4s1c.bde Create a file system on the encrypted device Once the encrypted device has been attached to the kernel, you can create a file system on the device. To create a file system on the encrypted device, use &man.newfs.8;. Since it is much faster to initialize a new UFS2 file system than it is to initialize the old UFS1 file system, using &man.newfs.8; with the option is recommended. The option is the default with &os; 5.1-RELEASE and later. &prompt.root; newfs -U -O2 /dev/ad4s1c.bde The &man.newfs.8; command must be performed on an attached gbde partition which is identified by a *.bde extension to the device name. Mount the encrypted partition Create a mount point for the encrypted file system. &prompt.root; mkdir /private Mount the encrypted file system. &prompt.root; mount /dev/ad4s1c.bde /private Verify that the encrypted file system is available The encrypted file system should now be visible to &man.df.1; and be available for use. &prompt.user; df -H Filesystem Size Used Avail Capacity Mounted on /dev/ad0s1a 1037M 72M 883M 8% / /devfs 1.0K 1.0K 0B 100% /dev /dev/ad0s1f 8.1G 55K 7.5G 0% /home /dev/ad0s1e 1037M 1.1M 953M 0% /tmp /dev/ad0s1d 6.1G 1.9G 3.7G 35% /usr /dev/ad4s1c.bde 150G 4.1K 138G 0% /private Mounting Existing Encrypted File Systems After each boot, any encrypted file systems must be re-attached to the kernel, checked for errors, and mounted, before the file systems can be used. The required commands must be executed as user root. Attach the gbde partition to the kernel &prompt.root; gbde attach /dev/ad4s1c -l /etc/gbde/ad4s1c You will be asked to provide the passphrase that you selected during initialization of the encrypted gbde partition. Check the file system for errors Since encrypted file systems cannot yet be listed in /etc/fstab for automatic mounting, the file systems must be checked for errors by running &man.fsck.8; manually before mounting. &prompt.root; fsck -p -t ffs /dev/ad4s1c.bde Mount the encrypted file system &prompt.root; mount /dev/ad4s1c.bde /private The encrypted file system is now available for use. Automatically Mounting Encrypted Partitions It is possible to create a script to automatically attach, check, and mount an encrypted partition, but for security reasons the script should not contain the &man.gbde.8; password. Instead, it is recommended that such scripts be run manually while providing the password via the console or &man.ssh.1;. Cryptographic Protections Employed by gbde &man.gbde.8; encrypts the sector payload using 128-bit AES in CBC mode. Each sector on the disk is encrypted with a different AES key. For more information on gbde's cryptographic design, including how the sector keys are derived from the user-supplied passphrase, see &man.gbde.4;. Compatibility Issues &man.sysinstall.8; is incompatible with gbde-encrypted devices. All *.bde devices must be detached from the kernel before starting &man.sysinstall.8; or it will crash during its initial probing for devices. To detach the encrypted device used in our example, use the following command: &prompt.root; gbde detach /dev/ad4s1c diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml index b8e586503d..621f7d2ab6 100644 --- a/en_US.ISO8859-1/books/handbook/x11/chapter.sgml +++ b/en_US.ISO8859-1/books/handbook/x11/chapter.sgml @@ -1,1644 +1,1644 @@ The X Window System Synopsis FreeBSD uses XFree86 to provide users with a powerful graphical user interface. XFree86 is an open-source implementation of the X Window System. This chapter will cover installation and configuration of XFree86 on a FreeBSD system. For more information on XFree86 and video hardware that it supports, check the XFree86 web site. After reading this chapter, you will know: The various components of the X Window System, and how they interoperate. How to install and configure XFree86. How to install and use different window managers. How to use TrueType fonts in XFree86. How to setup your system for graphical logins (XDM). Before reading this chapter, you should: Know how to install additional third-party software (). Understanding X Using X for the first time can be somewhat of a shock to someone familiar with other graphical environments, such as Microsoft Windows or MacOS. It is not necessary to understand all of the details of various X components and how they interact; however, some basic knowledge makes it possible to take advantage of X's strengths. Why X? X is not the first window system written for Unix, but it is the most popular. X's original development team had worked on another window system before writing X. That system's name was W (for Window). X is just the next letter in the Roman alphabet. X can be called X, X Window System, X11, and other terms. Calling X11 X Windows can offend some people; see &man.X.1; for a bit more insight on this. The X Client/Server Model X was designed from the beginning to be network-centric, and adopts a client-server model. In the X model, the X server runs on the computer that has the keyboard, monitor, and mouse attached. The server is responsible for managing the display, handling input from the keyboard and mouse, and so on. Each X application (such as XTerm, or Netscape) 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. If there is only one computer involved, such as in a home or small office environment, the X server and the X clients will be running on the same computer. However, it is perfectly possible to run the X server on a less powerful desktop computer, and run X applications (the clients) on, say, the powerful and expensive machine that serves the office. In this scenario the communication between the X client and server takes place over the network. 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. Remember that the X server is the machine with the monitor and keyboard, and the X clients are the programs that display the windows. There is nothing in the protocol that forces the client and server machines to be running the same operating system, or even to be running on the same type of computer. It is certainly possible to run an X server on Microsoft Windows or Apple's MacOS, and there are various free and commercial applications available that do exactly that. The X server that ships with FreeBSD is called XFree86, and is available for free, under a license very similar to the FreeBSD license. Commercial X servers for FreeBSD are also available. The Window Manager The X design philosophy is much like the Unix design philosophy, tools, not policy. This means that X does not try to dictate how a task is to be accomplished. Instead, tools are provided to the user, and it is the user's responsibility to decide how to use those tools. This philosophy extends to X not dictating what windows should look like on screen, how to move them around with the mouse, what keystrokes should be used to move between windows (i.e., Alt Tab , in the case of Microsoft 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 an application called a Window Manager. There are dozens of window managers available for X: AfterStep, Blackbox, ctwm, Enlightenment, fvwm, Sawfish, twm, Window Maker, and more. Each of these window managers provides a different look and feel; some of them support virtual desktops; some of them allow customized keystrokes to manage the desktop; some have a Start button or similar device; some are themeable, allowing a complete change of look-and-feel by applying a new theme. These window managers, and many more, are available in the x11-wm category of the Ports Collection. In addition, the KDE and GNOME desktop environments both have their own window managers which integrate with the desktop. Each window manager also has a different configuration mechanism; some expect configuration file written by hand, others feature GUI tools for most of the configuration tasks; at least one (sawfish) has a configuration file written in a dialect of the Lisp language. Focus Policy Another feature the window manager is responsible for is the mouse focus policy. Every windowing system needs some means of choosing a window to be actively receiving keystrokes, and should visibly indicate which window is active as well. A familiar focus policy is called click-to-focus. This is the model utilized by Microsoft Windows, in which a window becomes active upon receiving a mouse click. X does not support any particular focus policy. Instead, the window manager controls which window has the focus at any one time. Different window managers will support different focus methods. All of them support click to focus, and the majority of them support several others. The most popular focus policies are: focus-follows-mouse The window that is under the mouse pointer is the window that has the focus. This may not necessarily be the window that is on top of all the other windows. The focus is changed by pointing at another window, there is no need to click in it as well. sloppy-focus This policy is a small extension to focus-follows-mouse. With focus-follows-mouse, if the mouse is moved over the root window (or background) then no window has the focus, and keystrokes are simply lost. With sloppy-focus, focus is only changed when the cursor enters a new window, and not when exiting the current window. click-to-focus 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. Many window managers support other policies, as well as variations on these. Be sure to consult the documentation for the window manager itself. Widgets The X approach of providing tools and not policy extends to the widgets that seen on screen in each application. Widget is a term for all the items in the user interface that can be clicked or manipulated in some way; buttons, check boxes, radio buttons, icons, lists, and so on. Microsoft Windows calls these controls. Microsoft Windows and Apple's MacOS both have a very rigid widget policy. Application developers are supposed to ensure that their applications share a common look and feel. With X, it was not considered sensible to mandate a particular graphical style, or set of widgets to adhere to. As a result, do not expect X applications to have a common look and feel. There are several popular widget sets and variations, including the original Athena widget set from MIT, Motif (on which the widget set in Microsoft Windows was modeled, all bevelled edges and three shades of grey), OpenLook, and others. Most newer X applications today will use a modern-looking widget set, either Qt, used by KDE, or GTK, used by the GNOME project. In this respect, there is some convergence in look-and-feel of the Unix desktop, which certainly makes things easier for the novice user. Installing XFree86 Before installing XFree86, decide on which version to run. XFree86 3.X is a maintenance branch of XFree86 development. It is very stable, and it supports a huge number of graphics cards. However, no new development is being done on the software. XFree86 4.X is a complete redesign of the system with many new features such as better support for fonts and anti-aliasing. Unfortunately this new architecture requires that the video drivers be rewritten, and some of the older cards that were supported in 3.X are not yet supported in 4.X. As all new developments and support for new graphics cards are done on that branch, XFree86 4.X is now the default version of the X Window System on FreeBSD. The FreeBSD setup program offers users the opportunity to install and configure XFree86 4.X during installation (covered in ). To install and run XFree86 3.X, wait until after the base FreeBSD system is installed, and then install XFree86. For example, to build and install XFree86 3.X from the ports collection: &prompt.root; cd /usr/ports/x11/XFree86 &prompt.root; make all install clean Alternatively, either version of XFree86 can be installed directly from the FreeBSD binaries provided on the XFree86 web site. A binary package to use with &man.pkg.add.1; tool is also available for XFree86 4.X. When the remote fetching feature of &man.pkg.add.1; is used, the version number of the package must be removed. &man.pkg.add.1; will automatically fetch the latest version of the application. So to fetch and install the package of XFree86 4.X, simply type: &prompt.root; pkg_add -r XFree86 You can also use the ports collection to install XFree86 4.X, for that you simply need to type the following commands: &prompt.root; cd /usr/ports/x11/XFree86-4 &prompt.root; make install clean The rest of this chapter will explain how to configure XFree86, and how to setup a productive desktop environment. Christopher Shumway Contributed by XFree86 Configuration XFree86 4.X XFree86 Before Starting Before configuration of XFree86 4.X, the following information about the target system is needed: Monitor specifications Video Adapter chipset Video Adapter memory horizontal scan rate vertical scan rate The specifications for the monitor are used by XFree86 to determine the resolution and refresh rate to run at. These specifications can usually be obtained from the documentation that came with the monitor or from the manufacturer's website. There are two ranges of numbers that are needed, the horizontal scan rate and the vertical synchronization rate. The video adapter's chipset defines what driver module XFree86 uses to talk to the graphics hardware. With most chipsets, this can be automatically determined, but it is still useful to know in case the automatic detection does not work correctly. Video memory on the graphic adapter determines the resolution and color depth which the system can run at. This is important to know so the user knows the limitations of the system. Configuring XFree86 4.X Configuration of XFree86 4.X is a multi-step process. The first step is to build an initial configuration file with the option to XFree86. As the super user, simply run: &prompt.root; XFree86 -configure This will generate a skeleton XFree86 configuration file in the /root directory called XF86Config.new (in fact the directory used is the one covered by the environment variable $HOME, and it will depend from the way you got the superuser rights). The XFree86 program will attempt to probe the graphics hardware on the system and will write a configuration file to load the proper drivers for the detected hardware on the target system. The next step is to test the existing configuration to verify that XFree86 can work with the graphics hardware on the target system. To perform this task, the user needs to run: &prompt.root; XFree86 -xf86config XF86Config.new If a black and grey grid and an X mouse cursor appear, the configuration was successful. To exit the test, just press Ctrl Alt Backspace simultaneously. If the mouse does not work, be sure the device has been configured. See in the &os; install chapter. XFree86 4 Tuning Next, tune the XF86Config.new configuration file to taste. Open the file in a text editor such as &man.emacs.1; or &man.ee.1;. First, add the frequencies for the target system's monitor. These are usually expressed as a horizontal and vertical synchronization rate. These values are added to the XF86Config.new file under the "Monitor" section: Section "Monitor" Identifier "Monitor0" VendorName "Monitor Vendor" ModelName "Monitor Model" HorizSync 30-107 VertRefresh 48-120 EndSection The HorizSync and VertRefresh keywords may not exist in the configuration file. If they do not, they need to be added, with the correct horizontal synchronization rate placed after the Horizsync keyword and the vertical synchronization rate after the VertRefresh keyword. In the example above the target monitor's rates were entered. 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" XF86Config While the XF86Config.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" Depth 24 Modes "1024x768" EndSubSection EndSection The DefaultDepth keyword describes the color depth to run at by default. This can be overridden with the -bpp command line switch to &man.XFree86.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 one thousand twenty-four pixels by seven hundred and sixty-eight pixels. Finally, write the configuration file and test it using the test mode given above. If all is well, the configuration file needs to be installed in a common location where &man.XFree86.1; can find it. This is typically /etc/X11/XF86Config or /usr/X11R6/etc/X11/XF86Config. &prompt.root; cp XF86Config.new /etc/X11/XF86Config Once the configuration file has been placed in a common location, configuration is complete. In order to start XFree86 4.X with &man.startx.1;, install the x11/wrapper port. XFree86 4.X can also be started with &man.xdm.1;. Advanced Configuration Topics Configuration with Intel i810 Graphics Chipsets Intel i810 graphic chipset Configuration with Intel i810 integrated chipsets requires the agpgart AGP programming interface for XFree86 to drive the card. The &man.agp.4; driver is in the GENERIC kernel since releases 4.8-RELEASE and 5.0-RELEASE. On prior releases, you will have to add the following line: device agp in your kernel configuration file and rebuild a new kernel. Instead, you may want to load the agp.ko kernel module automatically with the &man.loader.8; at boot time. For that, simply add this line to /boot/loader.conf: agp_load="YES" Next, if you are running FreeBSD 4.X or earlier, a device node needs to be created for the programming interface. To create the AGP device node, run &man.MAKEDEV.8; in the /dev directory: &prompt.root; cd /dev &prompt.root; sh MAKEDEV agpgart FreeBSD 5.X or later will use &man.devfs.5; to allocate device nodes transparently, therefore the &man.MAKEDEV.8; step is not required. 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. If you are using XFree86 4.1.0 (or later) and messages about unresolved symbols like fbPictureInit appear, try adding the following line after Driver "i810" in the XFree86 configuration file: Option "NoDDC" Murray Stokely Contributed by Using Fonts in XFree86 Type1 Fonts The default fonts that ship with XFree86 are less than ideal for typical desktop publishing applications. Large presentation fonts show up jagged and unprofessional looking, and small fonts in Netscape are almost completely unintelligible. However, there are several free, high quality Type1 (PostScript) fonts available which can be readily used with XFree86, either version 3.X or version 4.X. For instance, the URW font collection (x11-fonts/urwfonts) includes high quality versions of standard type1 fonts (Times Roman, Helvetica, Palatino and others). The Freefont collection (x11-fonts/freefont) 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, XFree86 can be configured to use TrueType fonts with a minimum of effort: see the section on TrueType fonts later. 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 tell the X server that these fonts exist, add an appropriate line to the XF86Config file (in /etc/ for XFree86 version 3, or in /etc/X11/ for version 4), which reads: FontPath "/usr/X11R6/lib/X11/fonts/URW/" Alternatively, at the command line in the X session run: &prompt.user; xset fp+ /usr/X11R6/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 XftConfig file: see the section on anti-aliasing. TrueType Fonts TrueType Fonts fonts TrueType XFree86 4.X 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/XF86Config file. Load "freetype" For XFree86 3.3.X, a separate TrueType font server is needed. Xfstt is commonly used for this purpose. To install Xfstt, simply install the port x11-servers/Xfstt. Now make a directory for the TrueType fonts (for example, /usr/X11R6/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/DOS/Windows format for use by XFree86. 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/X11R6/lib/X11/fonts/TrueType &prompt.root; ttmkfdir > 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/X11R6/lib/X11/fonts/TrueType &prompt.user; xset fp rehash or add a line to the XF86Config file. That's it. Now Netscape, Gimp, StarOffice, 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. Joe Marcus Clarke Updated for XFree86 4.3 by Anti-Aliased Fonts anti-aliased fonts fonts anti-aliased Anti-aliasing has been available in XFree86 since 4.0.2. However, font configuration was cumbersome before the introduction of XFree86 4.3.0. Starting in version 4.3.0, all fonts in /usr/X11R6/lib/X11/fonts/ and ~/.fonts/ are automatically made available for anti-aliasing to Xft-aware applications. Not all applications are Xft-aware yet, but many have received Xft support. Examples of Xft-aware applications include Qt 2.3 and higher (the toolkit for the KDE desktop), Gtk+ 2.0 and higher (the toolkit for the GNOME desktop), and Mozilla 1.2 and higher. 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/X11R6/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/X11R6/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/X11R6/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&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 point 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> 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 such as Mozilla 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. The default font set that comes with XFree86 is not very desirable when it comes to anti-aliasing. A much better set of default fonts can be found in the x11-fonts/bitstream-vera port. This port will install a /usr/X11R6/etc/fonts/local.conf file if one does not exist already. If the file does exist, the port will create a /usr/X11R6/etc/fonts/local.conf-vera file. Merge the contents of this file into /usr/X11R6/etc/fonts/local.conf, and the Bitstream fonts will automatically replace the default XFree86 Serif, Sans Serif, and Monospaced fonts. 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. Mozilla web browsers Mozilla Mozilla Anti-aliasing should be enabled the next time the X server is started. However, programs must know how to take advantage of it. At present, the Qt toolkit does, so the entire KDE environment can use anti-aliased fonts (see on KDE for details). Gtk+ and GNOME can also be made to use anti-aliasing via the Font capplet (see for details). By default, Mozilla 1.2 and greater will automatically use anti-aliasing. To disable this, rebuild Mozilla with the -DWITHOUT_XFT flag. Seth Kingsley Contributed by 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 The XDM daemon program is located in /usr/X11R6/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/X11R6/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/X11R6/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 setup 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. By default, it allows any client to connect, but that does not matter unless the xdm-config is changed to listen for remote connections. Xresources This is an application-defaults file for the display chooser and the login screens. This is where the appearance of the login program can be modified. The format is identical to the app-defaults file described in the XFree86 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, 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. Replacements for XDM Several replacements for the default XDM program exist. One of them, KDM (bundled with KDE) is described later in this chapter. KDM 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. Valentino Vaschetto Contributed by 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, and a set of conventions that make it easy for applications to cooperate and be consistent with each other. Users of other operating systems or environments should feel right at home using the powerful graphics-driven environment that GNOME provides. More information regarding GNOME on FreeBSD can be found on the FreeBSD GNOME Project's web site. Installing GNOME The easiest way to install GNOME is through the Desktop Configuration menu during the FreeBSD installation process as described in of Chapter 2. It can also 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 To build GNOME from source, use the ports tree: &prompt.root; cd /usr/ports/x11/gnome2 &prompt.root; make install clean Once GNOME is installed, the X server must be told to start GNOME instead of a default window manager. If a custom .xinitrc is already in place, simply replace the line that starts the current window manager with one that starts /usr/X11R6/bin/gnome-session instead. If nothing special has been done to configuration file, then it is enough to simply type: &prompt.user; echo "/usr/X11R6/bin/gnome-session" > ~/.xinitrc Next, type startx, and the GNOME desktop environment will be started. If a 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/X11R6/bin/gnome-session: &prompt.user; echo "#!/bin/sh" > ~/.xsession &prompt.user; echo "/usr/X11R6/bin/gnome-session" >> ~/.xsession &prompt.user; chmod +x ~/.xsession 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. Anti-aliased fonts with GNOME GNOME anti-aliased fonts Starting with version 4.0.2, XFree86 supports anti-aliasing via its RENDER extension. Gtk+ 2.0 and greater (the toolkit used by GNOME) can make use of this functionality. Configuring anti-aliasing is described in . So, with up-to-date software, anti-aliasing is possible within the GNOME desktop. Just go to Applications -> Desktop Preferences -> Font, and select either Best shapes, Best contrast, or Subpixel smoothing (LCDs). For a Gtk+ application that is not part of the GNOME desktop, set the environment variable GDK_USE_XFT to 1 before launching the program. 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 40 languages Centralized consisted dialog driven desktop configuration A great number of useful KDE applications KDE has an office application suite based on KDE's KParts technology consisting of a spread-sheet, a presentation application, an organizer, a news client and more. KDE also comes with a web browser called Konqueror, which represents 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 informations and resources on KDE, consult the FreeBSD-KDE team's website. Installing KDE Just as with GNOME or any other desktop environment, the easiest way to install KDE is through the Desktop Configuration menu during the FreeBSD installation process as described in of Chapter 2. Once again, the software can be easily installed from a package or from the ports collection: To install the KDE package from the network, simply type: &prompt.root; pkg_add -r kde &man.pkg.add.1; will automatically fetch the latest version of the application. To build KDE from source, use the ports tree: &prompt.root; cd /usr/ports/x11/kde3 &prompt.root; make install clean 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 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. To begin with, run the KDE control panel, kcontrol, as root. It is generally considered unsafe to run the entire X environment as root. Instead, run the window manager as a normal user, open a terminal window (such as xterm or KDE's konsole), become root with su (the user must be in the wheel group in /etc/group for this), and then type kcontrol. Click on the icon on the left marked System, then on Login manager. On the right there are various configurable options, which the KDE manual will explain in greater detail. Click on sessions on the right. Click New type to add various window managers and desktop environments. These are just labels, so they can say KDE and GNOME rather than startkde or gnome-session. Include a label failsafe. Play with the other menus as well, they are mainly cosmetic and self-explanatory. When you are done, click on Apply at the bottom, and quit the control center. To make sure kdm understands what the labels (KDE, GNOME etc) mean, edit the files used by xdm. In KDE 2.2 this has changed: kdm now uses its own configuration files. Please see the KDE 2.2 documentation for details. In a terminal window, as root, edit the file /usr/X11R6/lib/X11/xdm/Xsession. There is a section in the middle like this: case $# in 1) case $1 in failsafe) exec xterm -geometry 80x24-0-0 ;; esac esac A few lines need to be added to this section. Assuming the labels from used were KDE and GNOME, use the following: case $# in 1) case $1 in kde) exec /usr/local/bin/startkde ;; GNOME) exec /usr/X11R6/bin/gnome-session ;; failsafe) exec xterm -geometry 80x24-0-0 ;; esac esac For the KDE login-time desktop background to be honored, the following line needs to be added to /usr/X11R6/lib/X11/xdm/Xsetup_0: /usr/local/bin/kdmdesktop Now, make sure kdm is listed in /etc/ttys to be started at the next bootup. To do this, simply follow the instructions from the previous section on xdm and replace references to the /usr/X11R6/bin/xdm program with /usr/local/bin/kdm. Anti-aliased Fonts KDE anti-aliased fonts Starting with version 4.0.2, XFree86 supports anti-aliasing via its RENDER extension, and starting with version 2.3, Qt (the toolkit used by KDE) supports this extension. Configuring this is described in on antialiasing X11 fonts. So, with up-to-date software, anti-aliasing is possible on a KDE desktop. Just go to the KDE menu, go to Preferences -> Look and Feel -> Fonts, and click on the check box Use Anti-Aliasing for Fonts and Icons. For a Qt application which is not part of KDE, the environment variable QT_XFT needs to be set to true before starting the program. 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 app launchers Integrated window manager, file manager, sound manager, GNOME compliance module, and other things 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 A binary package for XFce exists (at the time of writing). To install, simply type: &prompt.root; pkg_add -r xfce Alternatively, to build from source, use the ports collection: &prompt.root; cd /usr/ports/x11-wm/xfce &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/X11R6/bin/startxfce" > ~/.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/X11R6/bin/startxfce command; or, configure the display manager to allow choosing a desktop at login time, as explained in the section on kdm.