diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml b/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml index 83676bdbb7..98e29afe07 100644 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml +++ b/en_US.ISO8859-1/articles/fbsd-from-scratch/article.sgml @@ -1,571 +1,579 @@ %man; %freebsd; + +%trademarks; FreeBSD From Scratch"> ]>
FreeBSD From Scratch Jens Schweikhardt
schweikh@FreeBSD.org
 2002 Jens Schweikhardt $FreeBSD$ + + + &tm-attrib.freebsd; + &tm-attrib.adobe; + &tm-attrib.general; + This article describes my efforts at &scratch.ap;: a fully automated installation of a customized &os; system compiled from source, including compilation of all your favorite ports and configured to match your idea of the perfect system. If you think make world is a wonderful concept, &scratch.ap; extends it to make evenmore. Introduction Have you ever upgraded your system with make world? There is a problem if you have only one system on your disks. If the installworld fails partway through, you are left with a broken system that might not even boot any longer. Or maybe the installworld runs smoothly but the new kernel does not boot. Then it is time to reach for the Fixit CD and dig for those backups you have taken half a year ago. I believe in the wipe your disks when upgrading systems paradigm. Wiping disks, or rather partitions, makes sure there is no old cruft left lying around, something which most upgrade procedures just do not care about. But wiping the partitions means you have to also recompile/reinstall all your ports and packages and then redo all your carefully crafted configuration tweaks. If you think that this task should be automated as well, read on. Why would I (not) want &scratch.ap;? This is a legitimate question. We have sysinstall and the well known way to compile the kernel and the userland tools. The problem with sysinstall is that it is severely limited in what, where and how it can install. It is normally used to install pre-built distribution sets and packages from some other source (CD, DVD, FTP). It cannot install the result of a make buildworld. It cannot install a second system under a directory in a running system. It cannot install in Vinum partitions. It cannot compile ports, only install precompiled packages. It is hard to script or to make arbitrary post-installation changes. Last but not least, sysinstall is semi-officially at its End-Of-Life. The well known way to build and install the world, as described in the Handbook, by default replaces the existing system. Only the kernel and modules are saved. System binaries, headers and a lot of other files are overwritten; obsolete files are still present and can cause surprises. If the upgrade fails for any reason, it may be hard or even impossible to restore the previous state of the system. &scratch.ap; solves all these problems. The strategy is simple: use a running system to install a new system under an empty directory tree, while new partitions are mounted appropriately in that tree. Many config files can be copied to the appropriate place and &man.mergemaster.8; can take care of those that cannot. Arbitrary post-configuration of the new system can be done from within the old system, up to the point where you can chroot to the new system. In other words, we go through three stages, where each stage consists of either running a shell script or invoke make: stage_1.sh: Create a new bootable system under an empty directory and merge or copy as many files as are necessary. Then boot the new system. stage_2.sh: Install desired ports. stage_3.mk: Do post-configuration for software installed in previous stage. Once you have used &scratch.ap; to build a second system and found it works satisfactorily for a couple of weeks, you can then use it again to reinstall the original system. From now on, whenever you feel like an update is in order, you simply toggle the partitions you want to wipe and reinstall. Maybe you have heard of or even tried Linux From Scratch, or LFS for short. LFS also describes how to build and install a system from scratch in empty partitions using a running system. The focus in LFS seems to be to show the role of each system component (such as kernel, compiler, devices, shell, terminal database, etc) and the details of each component's installation. &scratch.ap; does not go into that much detail. My goal is to provide an automated and complete installation, not explaining all the gory details that go on under the hood when making the world. In case you want to explore &os; at this level of detail, start looking at /usr/src/Makefile and follow the actions of a make buildworld. There are also downsides in the approach taken by &scratch.ap; that you should bear in mind. While compiling the ports during stage two the system can not be used for its usual duties. If you run a production server you have to consider the downtime caused by stage two. The ports compiled by stage_2.sh below require about 4 hours to build on an AMD1800+ SCSI system with 10krpm disks and 1GB of RAM. Prerequisites For going the &scratch.ap; way, you need to have: A running &os; system with sources and a ports tree. At least one unused partition where the new system will be installed. Experience with running &man.mergemaster.8;. Or at least no fear doing so. If you have no or only a slow link to the Internet: the distfiles for your favorite ports. Basic knowledge of shell scripting with the Bourne shell, &man.sh.1;. Finally, you should also be able to tell your boot loader how to boot the new system, either interactively, or by means of a config file. Stage One: System Installation The following is my stage_1.sh. You need to customize it in various places to match your idea of the perfect system. I have tried to extensively comment the places you should adapt. The points to ponder are: Partition layout. I do not subscribe to the idea of a single huge partition for the whole system. My systems generally have at least one partition for /, /usr and /var with /tmp symlinked to /var/tmp. In addition I share the file systems for /home (user homes), /home/ncvs (&os; CVS repository replica), /usr/ports (the ports tree), /src (various checked out src trees) and /share (other shared data without the need for backups, like the news spool). Luxury items. What you want immediately after booting the new system and even before starting stage two. In my case this is shells/zsh because this is the login shell for my account as specified in /etc/passwd. Strictly speaking you can do without luxury items, because all you need to do is log in as root and run the next stage. The reason for not simply installing all my beloved ports during stage one is that in theory and in practice there are bootstrap and consistency issues: stage one has your old kernel running, but the chrooted environment consists of new binaries and headers. If the new system for example supports a new system call (according to its headers), some configure-type script might try to use it and get killed because it executes on the old kernel. I have seen other issues when I tried building lang/perl5. Before you run stage_1.sh make sure you have completed the usual tasks in preparation for make installworld installkernel, like: configured your kernel config file successfully completed make buildworld successfully completed make buildkernel KERNCONF=whatever When you run stage_1.sh for the first time, and the config files copied from your running system to the new system are not up-to-date with respect to what is under /usr/src, mergemaster will ask you how to proceed. I recommend merging the changes. If you get tired of going through the dialogues you can simply update the files on your running system once (Only if this is an option. You probably do not want to do this if one of your systems runs -STABLE and the other -CURRENT. The changes may be incompatible). Subsequent mergemaster invocations will detect that the RCS version IDs match those under /usr/src and skip the file. The stage_1.sh script will stop at the first command that fails (returns a non-zero exit status) due to set -e, so you cannot overlook errors. You should correct any errors in your version of stage_1.sh before you go on. In stage_1.sh we invoke mergemaster. Even if none of the files requires a merge, it will display and ask at the end *** Comparison complete Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] no Please answer no or just hit Enter. The reason is that mergemaster will have left a few zero sized files below /var/tmp/temproot.stage1 which will be copied to the new system later (unless already there). After that it will list the files it installed, making use of a pager (&man.more.1; by default, optionally &man.less.1;): *** You chose the automatic install option for files that did not exist on your system. The following were installed for you: /newroot/etc/defaults/rc.conf ... /newroot/COPYRIGHT (END) Type q to quit the pager. Then you will be informed about login.conf: *** You installed a login.conf file, so make sure that you run '/usr/bin/cap_mkdb /newroot/etc/login.conf' to rebuild your login.conf database Would you like to run it now? y or n [n] The answer does not matter since we will run &man.cap.mkdb.1; in any case. Everything stage_1.sh does is logged to stage_1.log for you to examine if you wish to do so. Here is the author's stage_1.sh, which you need to modify substantially, especially steps 1, 2, 5 and 6. Please pay attention to the &man.newfs.8; commands. While you can not create new file systems on mounted partitions, the script will happily erase any unmounted /dev/da3s1a, /dev/vinum/var_a and /dev/vinum/usr_a. This can be enough to ruin your day, so be sure to modify the device names. Download stage_1.sh. Running this script installs a system that when booted provides: Inherited users and groups. Firewalled Internet connectivity over Ethernet and PPP. Correct time zone and NTP. Some more minor configuration, like /etc/ttys and inetd. Other areas are prepared for configuration, but will not work until stage two is completed. For example we have copied files to configure printing and X11. Printing however is likely to need - applications not found in the base system, like PostScript + applications not found in the base system, like &postscript; utilities. X11 will not run before we have compiled the server, libraries and programs. Stage Two: Ports Installation It is also possible to install the (precompiled) packages at this stage, instead of compiling ports. In this case, stage_2.sh would be nothing more than a list of pkg_add commands. I trust you know how to write such a script. Here we concentrate on the more flexible and traditional way of using the ports. The following stage_2.sh script is how I install my favorite ports. It can be run any number of times and will skip all ports that are already installed. It supports the dryrun option () to just show what would be done. You will certainly want to edit the list of ports, and possibly change a few environment variables. The list of ports consists of lines with two or more space separated words: the category and the port, optionally followed by an installation command that will compile and install the port (default: make install). Empty lines and lines starting with # are ignored. Most of the time it suffices to only name category and port. A few ports however can be fine tuned by specifying make variables, e.g.: www mozilla make WITHOUT_MAILNEWS=yes WITHOUT_CHATZILLA=yes install mail procmail make BATCH=yes install In fact you can specify arbitrary shell commands, so you are not restricted to simple make invocations: java linux-sun-jdk13 yes | make install news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" make install Note that the line for news/inn-stable is an example for a one-shot shell variable assignment to CONFIGURE_ARGS. The port Makefile will use this as an initial value and augment some other essential args. The difference to specifying a make variable on the command line with news inn-stable make CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" install is that the latter will override instead of augment. It depends on the particular port which method you want. Be careful that your ports do not use an interactive install, i.e. they should not try to read from stdin other than what you explicitly give them on stdin. If they do, they will read the next line(s) from your list of ports in the here-document and get confused. If stage_2.sh mysteriously skips a port or stops processing, this is likely the reason. Here is stage_2.sh. It creates a log file named LOGDIR/category+port for each port it actually installs. If you do not have stage_2.sh on a shared partition make sure you copy it to the new system before you boot it. Download stage_2.sh. Stage Three You have installed your beloved ports during stage two. Some ports require a little bit of configuration. This is what stage three, the post-configuration is for. I could have integrated this post-configuration at the end of the stage_2.sh script. However, I think there is a conceptual difference between installing a port and modifying its out-of-the-box configuration that warrants a separate stage. I have chosen to implement stage three as a Makefile because this allows easy selection of what you want to configure simply by running: &prompt.root; make -f stage_3.mk target As with stage_2.sh make sure you have stage_3.mk available after booting the new system, either by putting it on a shared partition or copying it somewhere on the new system. Download stage_3.mk. Limitations The automated installation of a port may prove difficult if it is interactive and does not support make BATCH=YES install. For a few ports the interaction is nothing more than typing yes when asked to accept some license. If such input is read from the standard input, we simply pipe the appropriate answers to the installation command (usually make install; this is how we deal with java/linux-sun-jdk13 in stage_2.sh). This strategy for example does not work for editors/staroffice52, which requires that X11 is running. The installation procedure involves a fair amount of clicking and typing, so it cannot be automated like other ports can. However the following workaround does the trick for me: first I create a staroffice package on the old system with &prompt.root; cd /usr/ports/editors/staroffice52 &prompt.root; make package ===> Building package for staroffice-5.2_1 Creating package /usr/ports/editors/staroffice52/staroffice-5.2_1.tbz Registering depends:. Creating bzip'd tar ball in '/usr/ports/editors/staroffice52/staroffice-5.2_1.tbz' and during stage two I simply use: &prompt.root; pkg_add /usr/ports/editors/staroffice52/staroffice-5.2_1.tbz You should also be aware of upgrade issues for config files. In general you do not know when and if the format or contents of a config file changes. A new group may be added to /etc/group, or /etc/passwd may gain another field. All of this has happened in the past. Simply copying a config file from the old to the new system may be enough most of the time, but in these cases it was not. If you update a system the canonical way (by overwriting the old files) you are expected to use mergemaster to deal with changes where you effectively want to merge your local config with potentially new items. Unfortunately, mergemaster is only available for base system files, not for anything installed by ports. Some third party software seems to be especially designed to keep me on my toes by changing the config file format every fortnight. All you can do is be alert, especially when the major version number bumps. In the past I had to tweak or rewrite files for web servers, news servers and readers. All software actively maintained is a prime candidate for config file scrutiny. I have used &scratch.ap; several times to update a 5-CURRENT to 5-CURRENT, i.e. I have never tried to install a 5-CURRENT from a 4-STABLE system or vice versa. Due to the number of changes between different major release numbers I would expect this process to be a bit more involved. Using &scratch.ap; for upgrades within the realm of 4-STABLE should work painlessly (although I have not yet tried it.) Users of 4-STABLE may want to consider the following areas: If you do not use the device file system (devfs) you may want to create devices for some of your hardware with &man.MAKEDEV.8; in stage one, step six.
diff --git a/en_US.ISO8859-1/articles/filtering-bridges/article.sgml b/en_US.ISO8859-1/articles/filtering-bridges/article.sgml index 129752e61e..ff47bee3d0 100644 --- a/en_US.ISO8859-1/articles/filtering-bridges/article.sgml +++ b/en_US.ISO8859-1/articles/filtering-bridges/article.sgml @@ -1,385 +1,394 @@ %man; + +%trademarks; ]>
Filtering Bridges Alex Dupre
sysadmin@alexdupre.com
 $FreeBSD$ + + &tm-attrib.freebsd; + &tm-attrib.3com; + &tm-attrib.intel; + &tm-attrib.general; + + Often it is useful to divide one physical network (like an Ethernet) into two separate segments without having to create subnets, and use a router to link them together. The device that connects the two networks in this way is called a bridge. A FreeBSD system with two network interfaces is enough in order to act as a bridge. A bridge works by scanning the addresses of MAC level (Ethernet addresses) of the devices connected to each of its network interfaces and then forwarding the traffic between the two networks only if the source and the destination are on different segments. Under many points of view a bridge is similar to an Ethernet switch with only two ports. Why use a filtering bridge? More and more frequently, thanks to the lowering costs of broad band Internet connections (xDSL) and also because of the reduction of available IPv4 addresses, many companies are connected to the Internet 24 hours on 24 and with few (sometimes not even a power of 2) IP addresses. In these situations it is often desirable to have a firewall that filters incoming and outgoing traffic from and towards Internet, but a packet filtering solution based on router may not be applicable, either due to subnetting issues, the router is owned by the connectivity supplier (ISP), or because it does not support such functionalities. In these scenarios the use of a filtering bridge is highly advised. A bridge-based firewall can be configured and inserted between the xDSL router and your Ethernet hub/switch without any IP numbering issues. How to Install Adding bridge functionalities to a FreeBSD system is not difficult. Since 4.5 release it is possible to load such functionalities as modules instead of having to rebuild the kernel, simplifying the procedure a great deal. In the following subsections I will explain both installation ways. Do not follow both instructions: a procedure excludes the other one. Select the best choice according to your needs and abilities. Before going on, be sure to have at least two Ethernet cards that support the promiscuous mode for both reception and transmission, since they must be able to send Ethernet packets with any address, not just their own. Moreover, to have a good throughput, the cards should be PCI - bus mastering cards. The best choices are still the Intel EtherExpress - Pro, followed by the 3Com 3c9xx series. To simplify the firewall + bus mastering cards. The best choices are still the Intel ðerexpress; + Pro, followed by the &t3com; 3c9xx series. To simplify the firewall configuration it may be useful to have two cards of different manufacturers (using different drivers) in order to distinguish clearly which interface is connected to the router and which to the inner network. Kernel Configuration So you have decided to use the older but well tested installation method. To begin, you have to add the following rows to your kernel configuration file: options BRIDGE options IPFIREWALL options IPFIREWALL_VERBOSE The first line is to compile the bridge support, the second one is the firewall and the third one is the logging functions of the firewall. Now it is necessary to build and install the new kernel. You may find detailed instructions in the Building and Installing a Custom Kernel section of the FreeBSD Handbook. Modules Loading If you have chosen to use the new and simpler installation method, the only thing to do now is add the following row to /boot/loader.conf: bridge_load="YES" In this way, during the system startup, the bridge.ko module will be loaded together with the kernel. It is not required to add a similar row for the ipfw.ko module, since it will be loaded automatically after the execution of the steps in the following section. Final Preparation Before rebooting in order to load the new kernel or the required modules (according to the previously chosen installation method), you have to make some changes to the /etc/rc.conf configuration file. The default rule of the firewall is to reject all IP packets. Initially we will set up an firewall, in order to verify its operation without any issue related to packet filtering (in case you are going to execute this procedure remotely, such configuration will avoid you to remain isolated from the network). Put these lines in /etc/rc.conf: firewall_enable="YES" firewall_type="open" firewall_quiet="YES" firewall_logging="YES" The first row will enable the firewall (and will load the module ipfw.ko if it is not compiled in the kernel), the second one to set up it in mode (as explained in /etc/rc.firewall), the third one to not show rules loading and the fourth one to enable logging support. About the configuration of the network interfaces, the most used way is to assign an IP to only one of the network cards, but the bridge will work equally even if both interfaces or none has a configured IP. In the last case (IP-less) the bridge machine will be still more hidden, as inaccessible from the network: to configure it, you have to login from console or through a third network interface separated from the bridge. Sometimes, during the system startup, some programs require network access, say for domain resolution: in this case it is necessary to assign an IP to the external interface (the one connected to Internet, where DNS server resides), since the bridge will be activated at the end of the startup procedure. It means that the fxp0 interface (in our case) must be mentioned in the ifconfig section of the /etc/rc.conf file, while the xl0 is not. Assigning an IP to both the network cards does not make much sense, unless, during the start procedure, applications should access to services on both Ethernet segments. There is another important thing to know. When running IP over Ethernet, there are actually two Ethernet protocols in use: one is IP, the other is ARP. ARP does the conversion of the IP address of a host into its Ethernet address (MAC layer). In order to allow the communication between two hosts separated by the bridge, it is necessary that the bridge will forward ARP packets. Such protocol is not included in the IP layer, since it exists only with IP over Ethernet. The FreeBSD firewall filters exclusively on the IP layer and therefore all non-IP packets (ARP included) will be forwarded without being filtered, even if the firewall is configured to not permit anything. Now it's time to reboot the system and use it as before: there will be some new messages about the bridge and the firewall, but the bridge will not be activated and the firewall, being in mode, will not avoid any operations. If there are any problems, you should sort them out now before proceeding. Enabling the Bridge At this point, to enable the bridge, you have to execute the following commands (having the shrewdness to replace the names of the two network interfaces fxp0 and xl0 with your own ones): &prompt.root; sysctl net.link.ether.bridge_cfg=fxp0:0,xl0:0 &prompt.root; sysctl net.link.ether.bridge_ipfw=1 &prompt.root; sysctl net.link.ether.bridge=1 The first row specifies which interfaces should be activated by the bridge, the second one will enable the firewall on the bridge and finally the third one will enable the bridge. At this point you should be able to insert the machine between two sets of hosts without compromising any communication abilities between them. If so, the next step is to add the net.link.ether.[blah]=[blah] portions of these rows to the /etc/sysctl.conf file, in order to have them execute at startup. Configuring The Firewall Now it is time to create your own file with custom firewall rules, in order to secure the inside network. There will be some complication in doing this because not all of the firewall functionalities are available on bridged packets. Furthermore, there is a difference between the packets that are in the process of being forwarded and packets that are being received by the local machine. In general, incoming packets are run through the firewall only once, not twice as is normally the case; in fact they are filtered only upon receipt, so rules that use or will never match. Personally, I use which is an older syntax, but one that has a sense when you read it. Another limitation is that you are restricted to use only or commands for packets filtered by a bridge. Sophisticated things like , or are not available. Such options can still be used, but only on traffic to or from the bridge machine itself (if it has an IP address). New in FreeBSD 4.0, is the concept of stateful filtering. This is a big improvement for UDP traffic, which typically is a request going out, followed shortly thereafter by a response with the exact same set of IP addresses and port numbers (but with source and destination reversed, of course). For firewalls that have no statekeeping, there is almost no way to deal with this sort of traffic as a single session. But with a firewall that can remember an outgoing UDP packet and, for the next few minutes, allow a response, handling UDP services is trivial. The following example shows how to do it. It's possible to do the same thing with TCP packets. This allows you to avoid some denial of service attacks and other nasty tricks, but it also typically makes your state table grow quickly in size. Let's look at an example setup. Note first that at the top of /etc/rc.firewall there are already standard rules for the loopback interface lo0, so we should not have to care for them anymore. Custom rules should be put in a separate file (say /etc/rc.firewall.local) and loaded at system startup, by modifying the row of /etc/rc.conf where we defined the firewall: firewall_type="/etc/rc.firewall.local" You have to specify the full path, otherwise it will not be loaded with the risk to remain isolated from the network. For our example imagine to have the fxp0 interface connected towards the outside (Internet) and the xl0 towards the inside (LAN). The bridge machine has the IP 1.2.3.4 (it is not possible that your ISP can give you a class A address like this, but for our example it is good). # Things that we have kept state on before get to go through in a hurry add check-state # Throw away RFC 1918 networks add drop all from 10.0.0.0/8 to any in via fxp0 add drop all from 172.16.0.0/12 to any in via fxp0 add drop all from 192.168.0.0/16 to any in via fxp0 # Allow the bridge machine to say anything it wants # (if the machine is IP-less do not include these rows) add pass tcp from 1.2.3.4 to any setup keep-state add pass udp from 1.2.3.4 to any keep-state add pass ip from 1.2.3.4 to any # Allow the inside hosts to say anything they want add pass tcp from any to any in via xl0 setup keep-state add pass udp from any to any in via xl0 keep-state add pass ip from any to any in via xl0 # TCP section # Allow SSH add pass tcp from any to any 22 in via fxp0 setup keep-state # Allow SMTP only towards the mail server add pass tcp from any to relay 25 in via fxp0 setup keep-state # Allow zone transfers only by the slave name server [dns2.nic.it] add pass tcp from 193.205.245.8 to ns 53 in via fxp0 setup keep-state # Pass ident probes. It's better than waiting for them to timeout add pass tcp from any to any 113 in via fxp0 setup keep-state # Pass the "quarantine" range add pass tcp from any to any 49152-65535 in via fxp0 setup keep-state # UDP section # Allow DNS only towards the name server add pass udp from any to ns 53 in via fxp0 keep-state # Pass the "quarantine" range add pass udp from any to any 49152-65535 in via fxp0 keep-state # ICMP section # Pass 'ping' add pass icmp from any to any icmptypes 8 keep-state # Pass error messages generated by 'traceroute' add pass icmp from any to any icmptypes 3 add pass icmp from any to any icmptypes 11 # Everything else is suspect add drop log all from any to any Those of you who have set up firewalls before may notice some things missing. In particular, there are no anti-spoofing rules, in fact we did not add: add deny all from 1.2.3.4/8 to any in via fxp0 That is, drop packets that are coming in from the outside claiming to be from our network. This is something that you would commonly do to be sure that someone does not try to evade the packet filter, by generating nefarious packets that look like they are from the inside. The problem with that is that there is at least one host on the outside interface that you do not want to ignore: the router. But usually, the ISP anti-spoofs at their router, so we do not need to bother that much. The last rule seems to be an exact duplicate of the default rule, that is, do not let anything pass that is not specifically allowed. But there is a difference: all suspected traffic will be logged. There are two rules for passing SMTP and DNS traffic towards the mail server and the name server, if you have them. Obviously the whole rule set should be flavored to personal taste, this is only a specific example (rule format is described accurately in the &man.ipfw.8; man page). Note that in order for relay and ns to work, name service lookups must work before the bridge is enabled. This is an example of making sure that you set the IP on the correct network card. Alternatively it is possible to specify the IP address instead of the host name (required if the machine is IP-less). People that are used to setting up firewalls are probably also used to either having a or a rule for ident packets (TCP port 113). Unfortunately, this is not an applicable option with the bridge, so the best thing is to simply pass them to their destination. As long as that destination machine is not running an ident daemon, this is relatively harmless. The alternative is dropping connections on port 113, which creates some problems with services like IRC (the ident probe must timeout). The only other thing that is a little weird that you may have noticed is that there is a rule to let the bridge machine speak, and another for internal hosts. Remember that this is because the two sets of traffic will take different paths through the kernel and into the packet filter. The inside net will go through the bridge, while the local machine will use the normal IP stack to speak. Thus the two rules to handle the different cases. The in via fxp0 rules work for both paths. In general, if you use rules throughout the filter, you will need to make an exception for locally generated packets, because they did not come in via any of our interfaces. Contributors Many parts of this article have been taken, updated and adapted from an old text about bridging, edited by Nick Sayer. A pair of inspirations are due to an introduction on bridging by Steve Peterson. A big thanks to Luigi Rizzo for the implementation of the bridge code in FreeBSD and for the time he has dedicated to me answering all of my related questions. A thanks goes out also to Tom Rhodes who looked over my job of translation from Italian (the original language of this article) into English.
diff --git a/en_US.ISO8859-1/articles/fonts/article.sgml b/en_US.ISO8859-1/articles/fonts/article.sgml index 45b02e0920..65ee58269b 100644 --- a/en_US.ISO8859-1/articles/fonts/article.sgml +++ b/en_US.ISO8859-1/articles/fonts/article.sgml @@ -1,971 +1,983 @@ %freebsd; %man; + +%trademarks; ]>
Fonts and FreeBSD A Tutorial Dave Bodenstab
imdave@synet.net
Wed Aug 7, 1996 + + &tm-attrib.freebsd; + &tm-attrib.adobe; + &tm-attrib.apple; + &tm-attrib.linux; + &tm-attrib.microsoft; + &tm-attrib.opengroup; + &tm-attrib.general; + + This document contains a description of the various font files that may be used with FreeBSD and the syscons driver, X11, Ghostscript and Groff. Cookbook examples are provided for switching the syscons display to 80x60 mode, and for using type 1 fonts with the above application programs. Introduction There are many sources of fonts available, and one might ask how they might be used with FreeBSD. The answer can be found by carefully searching the documentation for the component that one would like to use. This is very time consuming, so this tutorial is an attempt to provide a shortcut for others who might be interested. Basic terminology There are many different font formats and associated font file suffixes. A few that will be addressed here are: .pfa, .pfb - Postscript type 1 fonts. The + &postscript; type 1 fonts. The .pfa is the Ascii form and .pfb the Binary form. .afm The font metrics associated with a type 1 font. .pfm The printer font metrics associated with a type 1 font. .ttf - A TrueType font + A &truetype; font .fot An indirect reference to a TrueType font (not an actual font) .fon, .fnt Bitmapped screen fonts - The .fot file is used by Windows as - sort of a symbolic link to the actual TrueType font + The .fot file is used by &windows; as + sort of a symbolic link to the actual &truetype; font (.ttf) file. The .fon font files are also used by Windows. I know of no way to use this font format with FreeBSD. What font formats can I use? Which font file format is useful depends on the application being used. FreeBSD by itself uses no fonts. Application programs and/or drivers may make use of the font files. Here is a small cross reference of application/driver to the font type suffixes: Driver syscons .fnt Application Ghostscript .pfa, .pfb, .ttf X11 .pfa, .pfb Groff .pfa, .afm Povray .ttf The .fnt suffix is used quite frequently. I suspect that whenever someone wanted to create a specialized font file for their application, more often than not they chose this suffix. Therefore, it is likely that files with this suffix are not all the same format; specifically, the .fnt files used by syscons under FreeBSD may not be the same format as a .fnt file - one encounters in the MS-DOS/Windows environment. I have not + one encounters in the &ms-dos;/&windows; environment. I have not made any attempt at using other .fnt files other than those provided with FreeBSD. Setting a virtual console to 80x60 line mode First, an 8x8 font must be loaded. To do this, /etc/rc.conf should contain the line (change the font name to an appropriate one for your locale): font8x8="iso-8x8" # font 8x8 from /usr/share/syscons/fonts/* (or NO). The command to actually switch the mode is &man.vidcontrol.1;: &prompt.user; vidcontrol VGA_80x60 Various screen-oriented programs, such as &man.vi.1;, must be able to determine the current screen dimensions. As this is achieved this through ioctl calls to the console driver (such as &man.syscons.4;) they will correctly determine the new screen dimensions. To make this more seamless, one can embed these commands in the startup scripts so it takes place when the system boots. To do this is add this line to /etc/rc.conf allscreens_flags="VGA_80x60" # Set this vidcontrol mode for all virtual screens References: &man.rc.conf.5;, &man.vidcontrol.1;. Using type 1 fonts with X11 X11 can use either the .pfa or the .pfb format fonts. The X11 fonts are located in various subdirectories under /usr/X11R6/lib/X11/fonts. Each font file is cross referenced to its X11 name by the contents of the fonts.dir file in each directory. There is already a directory named Type1. The most straight forward way to add a new font is to put it into this directory. A better way is to keep all new fonts in a separate directory and use a symbolic link to the additional font. This allows one to more easily keep track of ones fonts without confusing them with the fonts that were originally provided. For example: Create a directory to contain the font files &prompt.user; mkdir -p /usr/local/share/fonts/type1 &prompt.user; cd /usr/local/share/fonts/type1 Place the .pfa, .pfb and .afm files here One might want to keep readme files, and other documentation for the fonts here also &prompt.user; cp /cdrom/fonts/atm/showboat/showboat.pfb . &prompt.user; cp /cdrom/fonts/atm/showboat/showboat.afm . Maintain an index to cross reference the fonts &prompt.user; echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX Now, to use a new font with X11, one must make the font file available and update the font name files. The X11 font names look like: -bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 | | | | | | | | | | | | \ \ | | | | | \ \ \ \ \ \ \ +----+- character set | | | | \ \ \ \ \ \ \ +- average width | | | | \ \ \ \ \ \ +- spacing | | | \ \ \ \ \ \ +- vertical res. | | | \ \ \ \ \ +- horizontal res. | | | \ \ \ \ +- points | | | \ \ \ +- pixels | | | \ \ \ foundry family weight slant width additional style A new name needs to be created for each new font. If you have some information from the documentation that accompanied the font, then it could serve as the basis for creating the name. If there is no information, then you can get some idea by using &man.strings.1; on the font file. For example: &prompt.user; strings showboat.pfb | more %!FontType1-1.0: Showboat 001.001 %%CreationDate: 1/15/91 5:16:03 PM %%VMusage: 1024 45747 % Generated by Fontographer 3.1 % Showboat 1991 by David Rakowski. Alle Rechte Vorbehalten. FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup /UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse {save true}{false}ifelse}{false}ifelse 12 dict begin /FontInfo 9 dict dup begin /version (001.001) readonly def /FullName (Showboat) readonly def /FamilyName (Showboat) readonly def /Weight (Medium) readonly def /ItalicAngle 0 def /isFixedPitch false def /UnderlinePosition -106 def /UnderlineThickness 16 def /Notice (Showboat 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def end readonly def /FontName /Showboat def --stdin-- Using this information, a possible name might be: -type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 The components of our name are: Foundry Lets just name all the new fonts type1. Family The name of the font. Weight Normal, bold, medium, semibold, etc. From the &man.strings.1; output above, it appears that this font has a weight of medium. Slant roman, italic, oblique, etc. Since the ItalicAngle is zero, roman will be used. Width Normal, wide, condensed, extended, etc. Until it can be examined, the assumption will be normal. Additional style Usually omitted, but this will indicate that the font contains decorative capital letters. Spacing proportional or monospaced. Proportional is used since isFixedPitch is false. All of these names are arbitrary, but one should strive to be compatible with the existing conventions. A font is referenced by name with possible wild cards by an X11 program, so the name chosen should make some sense. One might begin by simply using …-normal-r-normal-…-p-… as the name, and then use &man.xfontsel.1; to examine it and adjust the name based on the appearance of the font. So, to complete our example: Make the font accessible to X11 &prompt.user; cd /usr/X11R6/lib/X11/fonts/Type1 &prompt.user; ln -s /usr/local/share/fonts/type1/showboat.pfb . Edit fonts.dir and fonts.scale, adding the line describing the font and incrementing the number of fonts which is found on the first line. &prompt.user; ex fonts.dir :1p 25 :1c 26 . :$a showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 . :wq fonts.scale seems to be identical to fonts.dir… &prompt.user; cp fonts.dir fonts.scale Tell X11 that things have changed &prompt.user; xset fp rehash Examine the new font &prompt.user; xfontsel -pattern -type1-* References: &man.xfontsel.1;, &man.xset.1;, The X Windows System in a Nutshell, O'Reilly & Associates. Using type 1 fonts with Ghostscript Ghostscript references a font via its Fontmap file. This must be modified in a similar way to the X11 fonts.dir file. Ghostscript can use either the .pfa or the .pfb format fonts. Using the font from the previous example, here is how to use it with Ghostscript: Put the font in Ghostscript's font directory &prompt.user; cd /usr/local/share/ghostscript/fonts &prompt.user; ln -s /usr/local/share/fonts/type1/showboat.pfb . Edit Fontmap so Ghostscript knows about the font &prompt.user; cd /usr/local/share/ghostscript/4.01 &prompt.user; ex Fontmap :$a /Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat . :wq Use Ghostscript to examine the font &prompt.user; gs prfont.ps Aladdin Ghostscript 4.01 (1996-7-10) Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... /1899520 581354 1300084 13826 0 done. GS>Showboat DoFont Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... 1939688 565415 1300084 16901 0 done. >>showpage, press <return> to continue<< >>showpage, press <return> to continue<< >>showpage, press <return> to continue<< GS>quit References: fonts.txt in the Ghostscript 4.01 distribution Using type 1 fonts with Groff Now that the new font can be used by both X11 and Ghostscript, how can one use the new font with groff? First of - all, since we are dealing with type 1 postscript fonts, the + all, since we are dealing with type 1 &postscript; fonts, the groff device that is applicable is the ps device. A font file must be created for each font that groff can use. A groff font name is just a file in /usr/share/groff_font/devps. With our example, the font file could be /usr/share/groff_font/devps/SHOWBOAT. The file must be created using tools provided by groff. The first tool is afmtodit. This is not normally installed, so it must be retrieved from the source distribution. I found I had to change the first line of the file, so I did: &prompt.user; cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp &prompt.user; ex /tmp/afmtodit.pl :1c #!/usr/bin/perl -P- . :wq This tool will create the groff font file from the metrics file (.afm suffix.) Continuing with our example: Many .afm files are in Mac format… ^M delimited lines We need to convert them to &unix; style ^J delimited lines &prompt.user; cd /tmp &prompt.user; cat /usr/local/share/fonts/type1/showboat.afm | tr '\015' '\012' >showboat.afm Now create the groff font file &prompt.user; cd /usr/share/groff_font/devps &prompt.user; /tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT The font can now be referenced with the name SHOWBOAT. If ghostscript is used to drive the printers on the system, - then nothing more needs to be done. However, if true postscript + then nothing more needs to be done. However, if true PostScript printers are used, then the font must be down loaded to the printer in order for the font to be used (unless the printer happens to have the showboat font built in or on an accessible font disk.) The final step is to create a down loadable font. The pfbtops tool is used to create the .pfa format of the font, and the download file is modified to reference the new font. The download file must reference the internal name of the font. This can easily be determined from the groff font file as illustrated: Create the .pfa font file &prompt.user; pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa Of course, if the .pfa file is already available, just use a symbolic link to reference it. Get the internal font name &prompt.user; fgrep internalname SHOWBOAT internalname Showboat Tell groff that the font must be down loaded &prompt.user; ex download :$a Showboat showboat.pfa . :wq To test the font: &prompt.user; cd /tmp &prompt.user; cat >example.t <<EOF .sp 5 .ps 16 This is an example of the Showboat font: .br .ps 48 .vs (\n(.s+2)p .sp .ft SHOWBOAT ABCDEFGHI .br JKLMNOPQR .br STUVWXYZ .sp .ps 16 .vs (\n(.s+2)p .fp 5 SHOWBOAT .ft R To use it for the first letter of a paragraph, it will look like: .sp 50p \s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the showboat font as its first letter. Additional vertical space must be used to allow room for the larger letter. EOF &prompt.user; groff -Tps example.t >example.ps To use ghostscript/ghostview &prompt.user; ghostview example.ps To print it &prompt.user; lpr -Ppostscript example.ps References: /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man, &man.groff.font.5;, &man.groff.char.7;, &man.pfbtops.1;. - Converting TrueType fonts to a groff/postscript format for + <title>Converting TrueType fonts to a groff/PostScript format for groff This potentially requires a bit of work, simply because it depends on some utilities that are not installed as part of the base system. They are: ttf2pf - TrueType to postscript conversion utilities. This + TrueType to PostScript conversion utilities. This allows conversion of a TrueType font to an ascii font metric (.afm) file. Currently available at . - Note: These files are postscript programs and must be + Note: These files are PostScript programs and must be downloaded to disk by holding down the Shift key when clicking on the link. Otherwise, your browser may try to launch ghostview to view them. The files of interest are: GS_TTF.PS PF2AFM.PS ttf2pf.ps The funny upper/lower case is due to their being intended also for DOS shells. ttf2pf.ps makes use of the others as upper case, so any renaming must be consistent with this. (Actually, GS_TTF.PS and PFS2AFM.PS are supposedly part of the ghostscript distribution, but it is just as easy to use these as an isolated utility. FreeBSD does not seem to include the latter.) You also may want to have these installed to /usr/local/share/groff_font/devps(?). afmtodit Creates font files for use with groff from ascii font metrics file. This usually resides in the directory, /usr/src/contrib/groff/afmtodit, and requires some work to get going. If you are paranoid about working in the /usr/src tree, simply copy the contents of the above directory to a work location. In the work area, you will need to make the utility. Just type: # make -f Makefile.sub afmtodit You may also need to copy /usr/contrib/groff/devps/generate/textmap to /usr/share/groff_font/devps/generate if it does not already exist. Once all these utilities are in place, you are ready to commence: Create the .afm file by typing: % gs -dNODISPLAY -q -- ttf2pf.ps TTF_name PS_font_name AFM_name Where, TTF_name is your TrueType font file, PS_font_name is the file name for the .pfa file, AFM_name is the name you wish for the .afm file. If you do not specify output file names for the .pfa or .afm files, then default names will be generated from the TrueType font file name. This also produces a .pfa file, the - ascii postscript font metrics file + ascii PostScript font metrics file (.pfb is for the binary form). This will not be needed, but could (I think) be useful for a fontserver. For example, to convert the 30f9 Barcode font using the default file names, use the following command: % gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf Aladdin Ghostscript 5.10 (1997-11-23) Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Converting 3of9.ttf to 3of9.pfa and 3of9.afm. If you want the converted fonts to be stored in A.pfa and B.afm, then use this command: % gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B Aladdin Ghostscript 5.10 (1997-11-23) Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Converting 3of9.ttf to A.pfa and B.afm. - Create the groff postscript file: + Create the groff PostScript file: Change directories to /usr/share/groff_font/devps so as to make the following command easier to execute. You will probably need root privileges for this. (Or, if you are paranoid about working there, make sure you reference the files DESC, text.enc and generate/textmap as being in this directory.) % afmtodit -d DESC -e text.enc file.afm \ generate/textmap PS_font_name Where, file.afm is the AFM_name created by ttf2pf.ps above, and PS_font_name is the font name used from that command, as well as the name that &man.groff.1; will use for references to this font. For example, assuming you used the first tiff2pf.ps command above, then the 3of9 Barcode font can be created using the command: % afmtodit -d DESC -e text.enc 3of9.afm \ generate/textmap 3of9 Ensure that the resulting PS_font_name file (e.g., 3of9 in the example above) is located in the directory /usr/share/groff_font/devps by copying or moving it there. Note that if ttf2pf.ps assigns a font name using the one it finds in the TrueType font file and you want to use a different name, you must edit the .afm file prior to running afmtodit. This name must also match the one used in the Fontmap file if you wish to pipe &man.groff.1; into &man.gs.1;. Can TrueType fonts be used with other programs? The TrueType font format is used by Windows, Windows 95, and Mac's. It is quite popular and there are a great number of fonts available in this format. Unfortunately, there are few applications that I am aware of that can use this format: Ghostscript and Povray come to mind. Ghostscript's support, according to the documentation, is rudimentary and the results are likely to be inferior to type 1 fonts. Povray version 3 also has the ability to use TrueType fonts, but I rather doubt many people will be creating documents as a series of raytraced pages :-). This rather dismal situation may soon change. The FreeType Project is currently developing a useful set of FreeType tools: The freetype module is included with XFree86 4.x. For more information please see the FreeBSD Handbook or the XFree86 4.0.2 Fonts page. The xfsft font server for X11 can serve TrueType fonts in addition to regular fonts. Though currently in beta, it is said to be quite usable. See Juliusz Chroboczek's page for further information. Porting instructions for FreeBSD can be found at Stephen Montgomery's software page. xfstt is another font server for X11, available under . A program called ttf2bdf can produce BDF files suitable for use in an X environment from TrueType files. Linux binaries are said to be available from . For people requiring the use of Asian TrueType fonts, the XTT font server may be worth a look. Information about XTT can be found at URL: . and others … The FreeType Projects page is a good starting point for information on these and other free TrueType projects. Where can additional fonts be obtained? Many fonts are available on the Internet. They are either entirely free, or are share-ware. In addition, there are many inexpensive CDROMs available that contain many fonts. Some Internet locations (as of August 1996) are: (Formerly CICA) Additional questions What use are the .pfm files? Can one generate the .afm file from a .pfa or .pfb? How to generate the groff character mapping files for - postscript fonts with non-standard character names? + PostScript fonts with non-standard character names? Can xditview and devX?? devices be setup to access all the new fonts? It would be good to have examples of using TrueType fonts with povray and ghostscript.
diff --git a/en_US.ISO8859-1/articles/formatting-media/article.sgml b/en_US.ISO8859-1/articles/formatting-media/article.sgml index 245017d29f..0cf918caf5 100644 --- a/en_US.ISO8859-1/articles/formatting-media/article.sgml +++ b/en_US.ISO8859-1/articles/formatting-media/article.sgml @@ -1,625 +1,639 @@ %authors; + + +%freebsd; + + +%trademarks; + %man; ]>
Formatting Media For Use With FreeBSD A Tutorial Doug White
dwhite@resnet.uoregon.edu
March 1997 + + &tm-attrib.freebsd; + &tm-attrib.iomega; + &tm-attrib.opengroup; + &tm-attrib.general; + + This document describes how to slice, partition, and format hard disk drives and similar media for use with FreeBSD. The examples given have been tested under FreeBSD 2.2 and should work for other releases. The text has been updated for FreeBSD version 4. Introduction & Definitions Overview Successfully adding disks to an existing system is the mark of an experienced system administrator. Slicing, partitioning, and adding disks requires a careful dance of proper command and name syntax. One slipped finger and an entire disk could disappear in seconds. This document is written in an attempt to simplify this process and avoid accidents. Thankfully, enhancements to existing tools (notably sysinstall) have greatly improved this process in recent releases of FreeBSD. There are two possible modes of disk formatting: compatibility mode: Arranging a disk so that it has a slice table for use with other operating systems. dedicated mode, sometimes called dangerously dedicated mode: Formatting a disk with no slice table. This makes the process of adding disks easier, however non-FreeBSD operating systems may not accept the disk. The term dangerously refers to the danger that the system may not recognize a disk formatted in this manner. For most cases, dedicated mode is the easiest to set up and use in existing systems, as a new disk is usually dedicated entirely to FreeBSD. However, compatibility mode insures optimum interoperability with future installations at a cost of increased complexity. In addition to selecting the mode, two methods of slicing the disk are available. One is using the system installation tool /stand/sysinstall. 2.1.7-RELEASE and later versions of sysinstall contain code to ease setup of disks during normal system operation, mainly allowing access to the Label and Partition editors and a Write feature which will update just the selected disk and slice without affecting other disks. The other method is running the tools manually from a root command line. For dedicated mode, only three or four commands are involved while sysinstall requires some manipulation. Definitions - Unix disk management over the centuries has invented many + &unix; disk management over the centuries has invented many new definitions for old words. The following glossary covers the definitions used in this document and (hopefully) for FreeBSD in general. compatibility mode: Arranging a disk so that it has a slice table for use with other operating systems. Oppose dedicated mode. (dangerously) dedicated mode: Formatting a disk with no slice table. This makes the process of adding disks easier, however non-FreeBSD operating systems may not accept the disk. Oppose compatibility mode. disk: Hard disks, CDROMs, magneto-optical devices and - Zip/Jazz removable media are example of storage devices + &iomegazip;/&jaz; removable media are example of storage devices commonly used today. The basic principle of the way these work is that one or more spinning disks spin by a motor, while a head, moving on a radial path close to the disks, reads from or writes data to the disk. Writing is done by modifying some physical properties of the disk (magnetic flow, reflectivity, etc.) while reading is done by detecting changes to the same physical properties of the disk. slice: A division of a disk. Up to four slices are permitted on one disk in the PC standard. Slices are composed of contiguous sectors. Slices are recorded in a slice table used by the system BIOS to locate bootable partitions. The slice table is usually called the partition table in DOS parlance. Maintained by the fdisk utility. partition: A division of a slice. Usually used in reference to divisions of the FreeBSD slice of a disk. Each filesystem and swap area on a disk resides in a partition. Maintained using the disklabel utility. sector: Smallest subdivision of a disk. One sector usually represents 512 bytes of data. Warnings & Pitfalls Building disks is not something to take lightly. It is quite possible to destroy the contents of other disks in your system if the proper precautions are not taken. Check your work carefully. It is very simple to destroy the incorrect disk when working with these commands. When in doubt consult the kernel boot output for the proper device. Needless to say, we are not responsible for any damage to any data or hardware that you may experience. You work at your own risk! Zip, Jaz, and Other Removables Removable disks can be formatted in the same way as normal hard disks. It is essential to have the disk drive connected to the system and a disk placed in the drive during startup, so the kernel can determine the drive's geometry. Check the dmesg output and make sure your device and the disk's size is listed. If the kernel reports Can't get the size then the disk was not in the drive. In this case, you will need to restart the machine before attempting to format disks. Formatting Disks in Dedicated Mode Introduction This section details how to make disks that are totally dedicated to FreeBSD. Remember, dedicated mode disks sometimes cannot be booted by the PC architecture. Making Dedicated Mode Disks using Sysinstall /stand/sysinstall, the system installation utility, has been expanded in recent versions to make the process of dividing disks properly a less tiring affair. The fdisk and disklabel editors built into sysinstall are GUI tools that remove much of the confusion from slicing disks. For FreeBSD versions 2.1.7 and later, this is perhaps the simplest way to slice disks. Start sysinstall as root by typing &prompt.root; /stand/sysinstall from the command prompt. Select Index. Select Partition. Select the disk to edit with arrow keys and SPACE. If you are using this entire disk for FreeBSD, select A. When asked: Do you want to do this with a true partition entry so as to remain cooperative with any future possible operating systems on the drive(s)? answer No. When asked if you still want to do this, answer Yes. Select Write. When warned about writing on installed systems, answer Yes. Quitthe FDISK Editor and ESCAPE back to the Index menu. Select Label from the Index menu. Label as desired. For a single partition, enter C to Create a partition, accept the default size, partition type Filesystem, and a mountpoint (which is not used). Enter W when done and confirm to continue. The filesystem will be newfs'd for you, unless you select otherwise (for new partitions you will want to do this!). You will get the error: Error mounting /mnt/dev/ad2s1e on /mnt/blah : No such file or directory Ignore. Exit out by repeatedly pressing ESCAPE. Making Dedicated Mode Disks Using the Command Line Execute the following commands, replacing ad2 with the disk name. &prompt.root; dd if=/dev/zero of=/dev/ad2 count=2 &prompt.root; disklabel /dev/ad2 | disklabel -B -R -r ad2 /dev/stdin We only want one partition, so using slice 'c' should be fine: &prompt.root; newfs /dev/ad2c If you need to edit the disklabel to create multiple partitions (such as swap), use the following: &prompt.root; dd if=/dev/zero of=/dev/ad2 count=2 &prompt.root; disklabel /dev/ad2 > /tmp/label Edit disklabel to add partitions: &prompt.root; vi /tmp/label &prompt.root; disklabel -B -R -r ad2 /tmp/label newfs partitions appropriately Your disk is now ready for use. Making Compatibility Mode Disks Introduction The command line is the easiest way to make dedicated disks, and the worst way to make compatibility disks. The command-line fdisk utility requires higher math skills and an in-depth understanding of the slice table, which is more than most people want to deal with. Use sysinstall for compatibility disks, as described below. Making Compatibility Mode Disks Using Sysinstall Start sysinstall as root by typing &prompt.root; /stand/sysinstall from the command prompt. Select Index. Select Partition. Select the disk to edit with arrow keys and SPACE. If you are using this entire disk for FreeBSD, select A. When asked: Do you want to do this with a true partition entry so as to remain cooperative with any future possible operating systems on the drive(s)? answer yes. Select Write. When asked to install the boot manager, select None with SPACE then hit ENTER for OK. Quit the FDISK Editor. You will be asked about the boot manager, select None again. Select Label from the Index menu. Label as desired. For a single partition, accept the default size, type filesystem, and a mountpoint (which is not used). The filesystem will be newfs'd for you, unless you select otherwise (for new partitions you will want to do this!). You will get the error: Error mounting /mnt/dev/ad2s1e on /mnt/blah : No such file or directory Ignore. Exit out by repeatedly pressing ESCAPE. Your new disk is now ready for use. Other Disk Operations Adding Swap Space As a system grows, its need for swap space can also grow. Although adding swap space to existing disks is very difficult, a new disk can be partitioned with additional swap space. To add swap space when adding a disk to a system: When partitioning the disk, edit the disklabel and allocate the amount of swap space to add in partition `b' and the remainder in another partition, such as `a' or `e'. The size is given in 512 byte blocks. When newfsing the drive, do NOT newfs the `c' partition. Instead, newfs the partition where the non-swap space lies. Add an entry to /etc/fstab as follows: /dev/ad0b none swap sw 0 0 Change /dev/ad0b to the device of the newly added space. To make the new space immediately available, use the swapon command. &prompt.root; swapon /dev/da0b swapon: added /dev/da0b as swap space Copying the Contents of Disks Submitted By: Renaud Waldura (renaud@softway.com) To move file from your original base disk to the fresh new one, do: &prompt.root; mount /dev/ad2 /mnt &prompt.root; pax -r -w -p e /usr/home /mnt &prompt.root; umount /mnt &prompt.root; rm -rf /usr/home/* &prompt.root; mount /dev/ad2 /usr/home Creating Striped Disks using CCD Commands Submitted By: Stan Brown (stanb@awod.com) The Concatenated Disk Driver, or CCD, allows you to treat several identical disks as a single disk. Striping can result in increased disk performance by distributing reads and writes across the disks. See the &man.ccd.4; and &man.ccdconfig.8; manual pages or the CCD Homepage for further details. You no longer need to build a special kernel to run ccd. When you run ccdconfig, it will load the KLD for you if the kernel does not contain CCD support. You build CCDs on disk partitions of type 4.2BSD. If you want to use the entire disk, you still need to create a new partition. For example, disklabel -e might show: # size offset fstype [fsize bsize bps/cpg] c: 60074784 0 unused 0 0 0 # (Cyl. 0 - 59597) You should not use partition c for the CCD, since it is of type unused. Instead, create a new partition of exactly the same size, but with type 4.2BSD: # 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) To create a new CCD, execute the following commands. This describes how to add three disks together; simply add or remove devices as necessary. Remember that the disks to be striped must be identical. &prompt.root; cd /dev ; sh MAKDEV ccd0 &prompt.root; disklabel -r -w da0 auto &prompt.root; disklabel -r -w da1 auto &prompt.root; disklabel -r -w da2 auto &prompt.root; disklabel -e da0 Add partition e with type 4.2BSD &prompt.root; disklabel -e da1 Add partition e with type 4.2BSD &prompt.root; disklabel -e da2 Add partition e with type 4.2BSD &prompt.root; ccdconfig ccd0 273 0 /dev/da0e /dev/da1e /dev/da2e &prompt.root; newfs /dev/ccd0c The value 273 is the stripe size. This is the number of disk sectors (of 512 bytes each) in each block of data on the CCD. It should be at least 128 kB, and it should not be not be a power of 2. Now you can mount and use your CCD by referencing device /dev/ccd0c. A more powerful and flexible alternative to CCD is Vinum. See the Vinum Project home page for further details. Credits The author would like to thank the following individuals for their contributions to this project: Darryl Okahata (darrylo@hpnmhjw.sr.hp.com) for his simple dedicated mode setup documentation which I have used repeatedly on FreeBSD-questions. &a.jkh; for making sysinstall useful for this type of task. John Fieber (jfieber@indiana.edu) for making information and examples of the DocBook DTD on which this document is based. &a.grog; for checking my work and pointing out inaccuracies, as well as miscellaneous support.
diff --git a/en_US.ISO8859-1/articles/hubs/article.sgml b/en_US.ISO8859-1/articles/hubs/article.sgml index 48f16d1cc2..4d00d836e8 100644 --- a/en_US.ISO8859-1/articles/hubs/article.sgml +++ b/en_US.ISO8859-1/articles/hubs/article.sgml @@ -1,1131 +1,1139 @@ %man; %authors; %teams; %mailing-lists; + +%trademarks; ]>
Mirroring FreeBSD $FreeBSD$ Jun Kuriyama
kuriyama@FreeBSD.org
 Valentino Vaschetto
logo@FreeBSD.org
 Daniel Lang
dl@leo.org
 Ken Smith
kensmith@cse.buffalo.edu
 + + + &tm-attrib.freebsd; + &tm-attrib.general; + + An in-progress article on how to mirror FreeBSD, aimed at hub administrators. Contact Information The Mirror System Coordinators can be reached through email at mirror-admin@FreeBSD.org. There is also a &a.hubs;. Requirements for FreeBSD mirrors Disk Space Disk space is one of the most important requirements. Depending on the set of releases, architectures, and degree of completeness you want to mirror, a huge amount of disk space may be consumed. Also keep in mind that official mirrors are probably required to be complete. The CVS repository and the web pages should always be mirrored completely. Also note that the numbers stated here are reflecting the current state (at 4.8-RELEASE/5.1-RELEASE). Further development and releases will only increase the required amount. Also make sure to keep some (ca. 10-20%) extra space around just to be sure. Here are some approximate figures: Full FTP Distribution: 126 GB CVS repository: 2.7 GB CTM deltas: 1.8 GB Webpages: 300 MB Network Connection/Bandwidth Of course, you need to be connected to the Internet. The required bandwidth depends on your intended use of the mirror. If you just want to mirror some parts of FreeBSD for local use at your site/intranet, the demand may be much smaller than if you want to make the files publicly available. If you intend to become an official mirror, the bandwidth required will be even higher. We can only give rough estimates here: Local site, no public access: basically no minimum, but < 2 Mbps could make syncing too slow. Unofficial public site: 34 Mbps is probably a good start. Official site: > 100 Mbps is recommended, and your host should be connected as close as possible to your border router. System Requirements, CPU, RAM One thing this depends on the expected number of clients, which is determined by the server's policy. It is also affected by the types of services you want to offer. Plain FTP or HTTP services may not require a huge amount of resources. Watch out if you provide CVSup, rsync or even AnonCVS. This can have a huge impact on CPU and memory requirements. Especially rsync is considered a memory hog, and CVSup does indeed consume some CPU. For AnonCVS it might be a nice idea to set up a memory resident file system (MFS) of at least 300 MB, so you need to take this into account for your memory requirements. The following are just examples to give you a very rough hint. For a moderately visited site that offers rsync, you might consider a current CPU with around 800MHz - 1 GHz, and at least 512MB RAM. This is probably the minimum you want for an official site. For a frequently used site you definitely need more RAM (consider 2GB as a good start) and possibly more CPU, which could also mean that you need to go for a SMP system. You also want to consider a fast disk subsystem. Operations on the CVS repository require a fast disk subsystem (RAID is highly advised). A SCSI controller that has a cache of its own can also speed up things since most of these services incur a large number of small modifications to the disk. You can also experiment with enlarging the portion of system memory which is used for the file system buffer cache. This will also help to reduce the quantity of disk access. This can be done with the BUFCACHEPERCENT kernel option. The default is to use 5% of system memory. Services to offer Every mirror site is required to have a set of core services available. In addition to these required services, there are a number of optional services that server administrators may choose to offer. This section explains which services you can provide and how to go about implementing them. FTP (required for FTP fileset) This is one of the most basic services, and it is required for each mirror offering public FTP distributions. FTP access must be anonymous, and no upload/download ratios are allowed (a ridiculous thing anyway). Upload capability is not required (and must never be allowed for the FreeBSD file space). Also the FreeBSD archive should be available under the path /pub/FreeBSD. There is a lot of software available which can be set up to allow anonymous FTP (in alphabetical order). /usr/libexec/ftpd: FreeBSD's own ftpd can be used. Be sure to read &man.ftpd.8;. ftp/ncftpd: A commercial package, free for educational use. ftp/oftpd: An ftpd designed with security as a main focus. ftp/proftpd: A modular and very flexible ftpd. ftp/pure-ftpd: Another ftpd developed with security in mind. ftp/twoftpd: As above. ftp/vsftpd: The very secure ftpd. ftp/wu-ftpd: The ftpd from Washington University. It has become infamous, because of the huge amount of security issues that have been found in it. If you do choose to use this software be sure to keep it up to date. FreeBSD's ftpd, proftpd, wu-ftpd and maybe ncftpd are among the most commonly ones. The others do not have a large userbase among mirror sites. One thing to consider is that you may need flexibility in limiting how many simultaneous connections are allowed, thus limiting how much network bandwidth and system resources are consumed. RSYNC (optional for FTP fileset) rsync is often offered for access to the contents of the FTP area of FreeBSD, so other mirror sites can use your system as their source. The protocol is different from FTP in many ways. It is much more bandwidth friendly, as only differences between files are transferred instead of whole files when they change. rsync does require a significant amount of memory for each instance. The size depends on the size of the synced module in terms of the number of directories and files. rsync can use rsh and ssh (now default) as a transport, or use it's own protocol for stand-alone access (this is the preferred method for public rsync servers). Authentication, connection limits, and other restrictions may be applied. There is just one software package available: net/rsync HTTP (required for webpages, optional for FTP fileset) If you want to offer the FreeBSD webpages, you need to install a webserver a.k.a. httpd. You may optionally offer the FTP fileset via HTTP. The choice of Webserver software is left up to the mirror administrator. Some of the most popular choices are: www/apache13: Apache is the most widely deployed Webserver on the Internet. It is used extensively by the FreeBSD Project. You may also wish to use the next generation of the Apache Webserver, available in the ports collection as www/apache2. www/thttpd: If you are going to be serving a large amount of static content you may find that using an application such as tHttpd is more efficient than Apache. It is optimized for excellent performance on FreeBSD. www/boa: Boa is another alternative to tHttpd and Apache. It should provide considerably better performance than Apache for purely static content. It does not, at the time of writing, contain the same set of optimizations for FreeBSD that are found in tHttpd. CVSup (desired for CVS repository) CVSup is a very efficient way of distributing files. It works similar to rsync, but was specially designed for use with CVS repositories. If you want to offer the FreeBSD CVS repository, you really want to consider offering it via CVSup. It is possible to offer the CVS repository via AnonCVS, FTP, Rsync or HTTP, but people would benefit much more from CVSup access. CVSup was developed by &a.jdp;. It is a bit tricky to install on non-FreeBSD platforms, since it is written in Modula-3 and therefore requires a Modula-3 environment. John Polstra has built a stripped down version of M3 that is sufficient to run CVSup, and can be installed much easier. See Ezm3 for details. Related ports are: net/cvsup: The native CVSup port (client and server) which requires lang/ezm3 now. net/cvsup-mirror: The CVSup mirror kit, which requires net/cvsup, and configures it mirror-ready. Some site administrators may want a different setup though. There are a few more like net/cvsupit and net/cvsup-without-gui you might want to have a look at. If you prefer a static binary package, take a look here. This page still refers to the S1G bug that was present in CVSup. Maybe John will setup a generic download-site to get static binaries for various platforms. It is possible to use CVSup to offer any kind of fileset, not just CVS repositories, but configuration can be complex. CVSup is known to eat some CPU on both the server and the client, since it needs to compare lots of files. AnonCVS (optional for CVS repository) If you have the CVS repository, you may want to offer anonymous CVS access. A short warning first: There is not much demand for it, it requires some experience, and you need to know what you are doing. Generally there are two ways to access a CVS repository remotely: via pserver or via ssh (we don't consider rsh). For anonymous access, pserver is very well suited, but some still offer ssh access as well. There is a custom crafted wrapper in the CVS repository, to be used as a login-shell for the anonymous ssh account. It does a chroot, and therefore requires the CVS repository to be available under the anonymous user's home-directory. This may not be possible for all sites. If you just offer pserver this restriction does not apply, but you may run with more security risks. You don't need to install any special software, since &man.cvs.1; comes with FreeBSD. You need to enable access via inetd, so add an entry into your /etc/inetd.conf like this: cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --allow-root=/home/ncvs pserver See the manpage for details of the options. Also see the CVS info page about additional ways to make sure access is read-only. It is advised that you create an unprivileged account, preferably called anoncvs. Also you need to create a file passwd in your /home/ncvs/CVSROOT and assign a CVS password (empty or anoncvs) to that user. The directory /anoncvstmp is a special purpose memory based file system. It is not required but advised since &man.cvs.1; creates a shadow directory structure in your /tmp which is not used after the operation but slows things dramatically if real disk operations are required. Here is an excerpt from /etc/fstab, how to set up such a MFS: /dev/da0s1b /anoncvstmp mfs rw,-s=786432,-b=4096,-f=512,-i=560,-c=3,-m=0,nosuid,nodev 0 0 This is (of course) tuned a lot, and was suggested by &a.jdp;. How to Mirror FreeBSD Ok, now you know the requirements and how to offer the services, but not how to get it. :-) This section explains how to actually mirror the various parts of FreeBSD, what tools to use, and where to mirror from. FTP The FTP area is the largest amount of data that needs to be mirrored. It includes the distribution sets required for network installation, the branches which are actually snapshots of checked-out source trees, the ISO Images to write CD-ROMs with the installation distribution, a live file system, lots of packages, the ports tree, distfiles, and a huge amount of packages. All of course for various FreeBSD versions, and various architectures. With FTP mirror You can use a FTP mirror program to get the files. There are a lot around and widely used, like: ftp/mirror ftp/ftpmirror ftp/emirror ftp/spegla ftp/omi some even use ftp/wget ftp/mirror was very popular, but seemed to have some drawbacks, as it is written in &man.perl.1;, and had real problems with mirroring large directories like a FreeBSD site. There are rumors that the current version has fixed this by allowing a different algorithm for comparing the directory structure to be specified. In general FTP is not really good for mirroring. It transfers the whole file if it has changed, and does not create a single data stream which would benefit from a large TCP congestion window. With RSYNC A better way to mirror the FTP area is rsync. You can install the port net/rsync and then use rsync to sync with your upstream host. rsync is already mentioned in . Since rsync access is not required, your preferred upstream site may not allow it. You may need to hunt around a little bit to find a site that allows rsync access. Since the number of rsync clients will have a significant impact on the server machine, most admins impose limitations on their server. For a mirror, you should ask the site maintainer you are syncing from about their policy, and maybe an exception for your host (since you are a mirror). A command line to mirror FreeBSD could look like that: &prompt.user; rsync -vaz --delete ftp4.de.FreeBSD.org::FreeBSD/ /pub/FreeBSD/ Consult the documentation for rsync, which is also available at http://rsync.samba.org/ about the various options to be used with rsync. If you sync the whole module (unlike subdirectories), be aware that the module-directory (here "FreeBSD") will not be created, so you cannot omit the target directory. Also you might want to set up a script framework that calls such a command via &man.cron.8;. With CVSup A few sites, including the one-and-only ftp-master.FreeBSD.org even offer CVSup to mirror the contents of the FTP space. You need to install a cvsup client, preferably from the port net/cvsup. (Also reread .) A sample supfile suitable for ftp-master.FreeBSD.org looks like this: # # FreeBSD archive supfile from master server # *default host=ftp-master.FreeBSD.org *default base=/usr *default prefix=/pub #*default release=all *default delete use-rel-suffix *default umask=002 # If your network link is a T1 or faster, comment out the following line. #*default compress FreeBSD-archive release=all preserve It seems CVSup would be the best way to mirror the archive in terms of efficiency, but it is only available from few sites. Please have look at the CVSup documentation like &man.cvsup.1; and consider using the option, as it can reduce the amount of work to be done a lot. Mirroring the CVS repository Again you have various possibilities, but the most recommended one is to use CVSup. Using CVSup CVSup was already described to some detail in and . Here we just describe an example to set up the supfile: # # FreeBSD CVS supfile from master server # *default host=cvsup-master.FreeBSD.org *default base=/usr *default prefix=/pub/FreeBSD/development/FreeBSD-CVS *default release=cvs *default delete use-rel-suffix *default umask=002 # If your network link is a T1 or faster, comment out the following line. #*default compress cvs-all You should also have a look at /usr/share/examples/cvsup Please do not forget to consider the hint mentioned in this note above. Using other methods Using other methods than CVSup is generally not recommended. We describe them in short here anyway. Since most sites offer the CVS repository as part of the FTP fileset under the path /pub/FreeBSD/development/FreeBSD-CVS, the following methods could be used. FTP RSYNC maybe even HTTP If you find a site that supports it, you could use net/sup. But it is inferior to CVSup and its deficiencies caused John Polstra to develop CVSup in the first place, so it is clearly not recommended. You can NOT use AnonCVS to mirror the CVS repository since CVS does not allow you to access the repository itself, but only checked out versions of the modules. Mirroring the WWW pages The best way is to check out the www distribution from CVS. If you have a local mirror of the CVS repository, it is probably as easy as: &prompt.user; cvs -d /home/ncvs co www and a cronjob, that calls cvs up -d -P on a regular basis, maybe just after your repository was updated. Of course, the files need to remain in a directory available for public WWW access. The installation and configuration of a webserver is not discussed here. For the website to be visible, users must execute the &man.make.1; command in the main www directory. This command will create the standard *.html files for web viewing. For this to work however, the textproc/docproj port must be installed. If you don't have a local repository, you can use CVSup to maintain an up to date copy of the www pages. A sample supfile can be found in /usr/share/examples/cvsup/www-supfile and could look like this: # # WWW module supfile for FreeBSD # *default host=cvsup3.de.FreeBSD.org *default base=/usr *default prefix=/usr/local *default release=cvs tag=. *default delete use-rel-suffix # If your network link is a T1 or faster, comment out the following line. *default compress # This collection retrieves the www/ tree of the FreeBSD repository www Using ftp/wget or other web-mirror tools is probably not recommended. Mirroring the FreeBSD documentation Since the documentation is referenced a lot from the webpages, it is recommended that you mirror the FreeBSD documentation as well. However, this is not as trivial as the www-pages alone. First of all, you should get the doc sources, again preferably via CVSup. Here is a corresponding sample supfile: # # FreeBSD documentation supfile # *default host=cvsup3.de.FreeBSD.org *default base=/usr *default prefix=/usr/share *default release=cvs tag=. *default delete use-rel-suffix # If your network link is a T1 or faster, comment out the following line. #*default compress # This will retrieve the entire doc branch of the FreeBSD repository. # This includes the handbook, FAQ, and translations thereof. doc-all Then you need to install a couple of ports. You are lucky, there is a meta-port: textproc/docproj to do the work for you. You need to set up some environment variables, like SGML_CATALOG_FILES. Also have a look at your /etc/make.conf (copy /etc/defaults/make.conf if you do not have one), and look at the DOC_LANG variable. Now you are probably ready to run make in you doc directory (/usr/share/doc by default) and build the documentation. Again you need to make it accessible for your webserver and make sure the links point to the right location. The building of the documentation, as well as lots of side issues, is documented itself in: fdp-primer. Please read this piece of documentation, especially if you have problems building the documentation. XXX MAYBE THIS CAN BE LINKED FROM WITHIN - NOT USING AN ABSOLUTE URL XXX How often should I mirror? Every mirror should be updated on a regular basis. You will certainly need some script framework for it that will be called by &man.cron.8;. Since nearly every admin does this his own way, we cannot give specific instructions. It could work like this: Put the command to run your mirroring application in a script. Use of a plain /bin/sh script is recommended. Add some output redirections so diagnostic messages are logged to a file. Test if your script works. Check the logs. Use &man.crontab.1; to add the script to the appropriate user's &man.crontab.5;. This should be a different user than what your FTP daemon runs as so that if file permissions inside your FTP area are not world-readable those files can not be accessed by anonymous FTP. This is used to stage releases — making sure all of the official mirror sites have all of the necessary release files on release day. Here are some recommended schedules: FTP fileset: daily CVS repository: daily to hourly WWW pages: daily Where to mirror from This is an important issue. So this section will spend some effort to explain the backgrounds. We will say this several times: under no circumstances should you mirror from ftp.FreeBSD.org. A few words about the organization Mirrors are organized by country. All official mirrors have a DNS entry of the form ftpN.CC.FreeBSD.org. CC (i.e. country code) is the top level domain (TLD) of the country where this mirror is located. N is a number, telling that the host would be the Nth mirror in that country. (Same applies to cvsupN.CC.FreeBSD.org, wwwN.CC.FreeBSD.org, etc.) There are mirrors with no CC part. These are the mirror sites that are very well connected and allow a large number of concurrent users. ftp.FreeBSD.org is actually two machines, one currently located in Denmark and the other in the United States. It is NOT a master site and should never be used to mirror from. Lots of online documentation leads interactiveusers to ftp.FreeBSD.org so automated mirroring systems should find a different machine to mirror from. Additionally there exists a hierarchy of mirrors, which is described in terms of tiers. The master sites are not referred to but can be described as Tier-0. Mirrors that mirror from these sites can be considered Tier-1, mirrors of Tier-1-mirrors, are Tier-2, etc. Official sites are encouraged to be of a low tier, but the lower the tier the higher the requirements in terms as described in . Also access to low-tier-mirrors may be restricted, and access to master sites is definitely restricted. The tier-hierarchy is not reflected by DNS and generally not documented anywhere except for the master sites. However, official mirrors with low numbers like 1-4, are usually Tier-1 (this is just a rough hint, and there is no rule). Ok, but where should I get the stuff now? Under no circumstances should you mirror from ftp.FreeBSD.org. The short answer is: from the site that is closest to you in Internet terms, or gives you the fastest access. I just want to mirror from somewhere! If you have no special intentions or requirements, the statement in applies. This means: Look at available mirrors in your country. The FreeBSD Mirror Database can help you with this. Check for those which provide fastest access (number of hops, round-trip-times) and offer the services you intend to use (like rsync or CVSup). Contact the administrators of your chosen site stating your request, and asking about their terms and policies. Setup your mirror as described above. I'm an official mirror, what is the right site for me? In general the description in still applies. Of course you may want to put some weight on the fact that your upstream should be of a low tier. There are some other considerations about official mirrors that are described in . I want to access the master sites! If you have good reasons and good prerequisites, you may want and get access to one of the master sites. Access to these sites is generally restricted, and there are special policies for access. If you are already an official mirror, this certainly helps you getting access. In any other case make sure your country really needs another mirror. If it already has three or more, ask the zone administrator (hostmaster@CC.freebsd.org) or &a.hubs; first. Whoever helped you become, an official should have helped you gain access to an appropriate upstream host, either one of the master sites or a suitable Tier-1 site. If not, you can send email to mirror-admin@FreeBSD.org to request help with that. There are three master sites for the FTP fileset and one for the CVS repository (the webpages and docs are obtained from CVS, so there is no need for master). ftp-master.FreeBSD.org This is the master site for the FTP fileset. ftp-master.FreeBSD.org provides rsync and CVSup access, rather in addition to ftp protocol. Refer to and how to access via these protocols. Mirrors should be encouraged to also allow rsync access for the FTP contents, since they are Tier-1-mirrors. cvsup-master.FreeBSD.org This is the master site for the CVS repository. cvsup-master.FreeBSD.org provides CVSup access only. See for details. To get access, you need to contact &a.cvsup-master;. Make sure you read FreeBSD CVSup Access Policy first! Set up the required authentication by following these instructions. Make sure you specify the server as freefall.FreeBSD.org on the cvpasswd command line, as described in this document, even when you are contacting cvsup-master.FreeBSD.org Official Mirrors Official mirrors are mirrors that a) have a FreeBSD.org DNS entry (usually a CNAME). b) are listed as an official mirror in the FreeBSD documentation (like handbook). So far to distinguish official mirrors. Official mirrors are not necessarily Tier-1-mirrors. However you probably won't find a Tier-1-mirror, that is not also official. Special Requirements for official (tier-1) mirrors It is not so easy to state requirements for all official mirrors, since the project is sort of tolerant here. It is more easy to say, what official tier-1 mirrors are required to. All other official mirrors can consider this a big should. The following applies mainly to the FTP fileset, since a CVS repository should always be mirrored completely, and the webpages are a case of its own. Tier-1 mirrors are required to: carry the complete fileset allow access to other mirror sites provide FTP and RSYNC access Furthermore, admins should be subscribed to the &a.hubs;. See this link for details, how to subscribe. It is very important for a hub administrator, especially Tier-1 hub admins, to check the release schedule for the next FreeBSD release. This is important because it will tell you when the next release is scheduled to come out, and thus giving you time to prepare for the big spike of traffic which follows it. It is also important that hub administrators try to keep their mirrors as up-to-date as possible (again, even more crucial for Tier-1 mirrors). If Mirror1 doesn't update for a while, lower tier mirrors will begin to mirror old data from Mirror1 and thus begins a downward spiral... Keep your mirrors up to date! How to become official then? An interesting question, especially, since the state of being official comes with some benefits, like a much higher bill from your ISP as more people will be using your site. Also it may be a key requirement to get access to a master site. Before applying, please consider (again) if another official mirror is really needed for your region. Check first with your zone administrator (hostmaster@CC.FreeBSD.org) or, if that fails, ask on the &a.hubs;. Ok, here is how to do it: Get the mirror running in first place (maybe not using a master site, yet). Subscribe to the &a.hubs;. If everything works so far, contact the DNS administrator responsible for your region/country, and ask for a DNS entry for your site. The admin should able to be contacted via hostmaster@CC.FreeBSD.org, where CC is your country code/TLD. Your DNS entry will be as described in . If there is no subdomain set up for your country yet, you should contact mirror-admin@FreeBSD.org, or you can try the &a.hubs; first. Whoever helps you get an official name should send email to mirror-admin@FreeBSD.org so your site will be added to the mirror list in the FreeBSD Handbook. That is it. Some statistics from mirror sites Here are links to the stat pages of your favorite mirrors (a.k.a. the only ones who feel like providing stats). FTP site statistics ftp2.FreeBSD.org - grisha@ispol.com - (Bandwidth) ftp.is.FreeBSD.org - hostmaster@is.FreeBSD.org - (Bandwidth) (FTP processes) (HTTP processes) ftp.cz.FreeBSD.org - cejkar@fit.vutbr.cz - (Bandwidth) (FTP processes) (Rsync processes) ftp4.de.FreeBSD.org - dl@leo.org - (FTP users) (RSYNC users) CVSup site stats cvsup5.FreeBSD.org - staff@blackened.com - (CVSup processes) cvsup[23456].jp.FreeBSD.org - kuriyama@FreeBSD.org - (CVSup processes) cvsup.cz.FreeBSD.org - cejkar@fit.vutbr.cz - (CVSup processes) [cvsup3|anoncvs].de.FreeBSD.org - dl@leo.org - (CVSup processes)
diff --git a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml index f844cc9122..02e8c5487a 100644 --- a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml +++ b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml @@ -1,526 +1,536 @@ %man; %mailing-lists; + +%freebsd; + +%trademarks; ]>
Problem Report Handling Guidelines $FreeBSD$ + + &tm-attrib.freebsd; + &tm-attrib.opengroup; + &tm-attrib.general; + + These guidelines describe recommended handling practices for FreeBSD Problem Reports (PRs). Whilst developed for the FreeBSD PR Database Maintenance Team freebsd-bugbusters@FreeBSD.org, these guidelines should be followed by anyone working with FreeBSD PRs. Dag-Erling Smørgrav Hiten Pandya
Introduction GNATS is a defect management (bug reporting) system used by the FreeBSD Project. As accurate tracking of outstanding software defects is important to FreeBSD's quality, the correct use of GNATS is essential to the forward progress of the Project. Access to GNATS is available to FreeBSD developers, as well as to the wider community. In order to maintain consistency within the database and provide a consistent user experience, guidelines have been established covering common aspects of bug management such as presenting followup, handling close requests, and so forth.
Problem Report Life-cycle The Reporter submits a PR with &man.send-pr.1; and receives a confirmation message. Joe Random Committer takes interest in the PR and assigns it to himself, or Jane Random BugBuster decides that Joe is best suited to handle it and assigns it to him. Joe has a brief exchange with the originator (making sure it all goes into the audit trail) and determines the cause of the problem. He then makes sure the cause is documented in the audit trail, and sets the PRs state to analyzed. Joe pulls an all-nighter and whips up a patch that he thinks fixes the problem, and submits it in a follow-up, asking the originator to test it. He then sets the PRs state to feedback. A couple of iterations later, both Joe and the originator are satisfied with the patch, and Joe commits it to -CURRENT (or directly to -STABLE if the problem does not exist in -CURRENT), making sure to reference the Problem Report in his commit log (and credit the originator if he submitted all or part of the patch) and, if appropriate, start an MFC countdown. If the patch does not need MFCing, Joe then closes the PR. If the patch needs MFCing, Joe leaves the Problem Report in patched state until the patch has been MFCed, then closes it. Many PRs are submitted with very little information about the problem, and some are either very complex to solve, or just scratch the surface of a larger problem; in these cases, it is very important to obtain all the necessary information needed to solve the problem. If the problem contained within cannot be solved, or has occurred again, it is necessary to re-open the PR. The email address used on the PR might not be able to receive mail. In this case, followup to the PR as usual and ask the originator (in the followup) to provide a working email address. This is normally the case when &man.send-pr.1; is used from a system with the mail system disabled or not installed.
Problem Report State It is important to update the state of a PR when certain actions are taken. The state should accurately reflect the current state of work on the PR. A small example on when to change PR state When a PR has been worked on and the developer(s) responsible feel comfortable about the fix, they will submit a followup to the PR and change its state to feedback. At this point, the originator should evaluate the fix in their context and respond indicating whether the defect has indeed been remedied. A Problem Report may be in one of the following states: open Initial state; the problem has been pointed out and it needs reviewing. analyzed The problem has been reviewed and a solution is being sought. feedback Further work requires additional information from the originator or the community; possibly information regarding the proposed solution. patched A patch has been committed, but something (MFC, or maybe confirmation from originator) is still pending. suspended The problem is not being worked on, due to lack of information or resources. This is a prime candidate for somebody who is looking for a project to take on. If the problem cannot be solved at all, it will be closed, rather than suspended. The documentation project uses suspended for wish-list items that entail a significant amount of work which no one currently has time for. closed A problem report is closed when any changes have been integrated, documented, and tested, or when fixing the problem is abandoned. The patched state is directly related to feedback, so you may go directly to closed state if the originator cannot test the patch, and it works in your own testing.
Types of Problem Reports While handling problem reports, either as a developer who has direct access to the GNATS database or as a contributor who browses the database and submits followups with patches, comments, suggestions or change requests, you will come across several different types of PRs. PRs already assigned to someone. Duplicates of existing PRs. Stale PRs Misfiled PRs The following sections describe what each different type of PRs is used for, when a PR belongs to one of these types, and what treatment each different type receives.
Assigned PRs If a PR has the responsible field set to the username of a FreeBSD developer, it means that the PR has been handed over to that particular person for further work. Assigned PRs should not be touched by anyone but the assignee. If you have comments, submit a followup. If for some reason you think the PR should change state or be reassigned, send a message to the assignee. If the assignee does not respond within two weeks, unassign the PR and do as you please.
Duplicate PRs If you find more than one PR that describe the same issue, choose the one that contains the largest amount of useful information and close the others, stating clearly the number of the superseding PR. If several PRs contain non-overlapping useful information, submit all the missing information to one in a followup, including references to the others; then close the other PRs (which are now completely superseded).
Stale PRs A PR is considered stale if it has not been modified in more than six months. Apply the following procedure to deal with stale PRs: If the PR contains sufficient detail, try to reproduce the problem in -CURRENT and -STABLE. If you succeed, submit a followup detailing your findings and try to find someone to assign it to. Set the state to analyzed if appropriate. If the PR describes an issue which you know is the result of a usage error (incorrect configuration or otherwise), submit a followup explaining what the originator did wrong, then close the PR with the reason User error or Configuration error. If the PR describes an error which you know has been corrected in both -CURRENT and -STABLE, close it with a message stating when it was fixed in each branch. If the PR describes an error which you know has been corrected in -CURRENT, but not in -STABLE, try to find out when the person who corrected it is planning to MFC it, or try to find someone else (maybe yourself?) to do it. Set the state to feedback and assign it to whomever will do the MFC. In other cases, ask the originator to confirm if the problem still exists in newer versions. If the originator does not reply within a month, close the PR with the notation Feedback timeout.
Misfiled PRs GNATS is picky about the format of a submitted bug report. This is why a lot of PRs end up being misfiled if the submitter forgets to fill in a field or puts the wrong sort of data in some of the PR fields. This section aims to provide most of the necessary details for FreeBSD developers that can help them to close or refile these PRs. When GNATS cannot deduce what to do with a problem report that reaches the database, it sets the responsible of the PR to gnats-admin and files it under the pending category. This is now a misfiled PR and will not appear in bug report listings, unless someone explicitly asks for a list of all the misfiled PRs. If you have access to the FreeBSD cluster machines, you can use query-pr to view a listing of PRs that have been misfiled: &prompt.user; query-pr -x -q -r gnats-admin 52458 gnats-ad open serious medium Re: declaration clash f 52510 gnats-ad open serious medium Re: lots of sockets in 52557 gnats-ad open serious medium 52570 gnats-ad open serious medium Jigdo maintainer update Commonly PRs like the ones shown above are misfiled for one of the following reasons: A followup to an existing PR, sent through email, has the wrong format on its Subject: header. When completing the &man.send-pr.1; template, the submitter forgot to set the category or class of the PR to a proper value. It is not a real PR, but some random message sent to bug-followup@freebsd.org or freebsd-gnats-submit@freebsd.org.
Followups misfiled as new PRs The first category of misfiled PRs, the one with the wrong subject header, is actually the one that requires the greatest amount of work from developers. These are not real PRs, describing separate problem reports. When a reply is received for an existing PR at one of the addresses that GNATS listens to for incoming messages, the subject of the reply should always be of the form: Subject: Re: category/number: old synopsis text Most mailers will add the Re:  part when you reply to the original mail message of a PR. The category/number:  part is a GNATS-specific convention that you have to manually insert to the subject of your followup reports. Any FreeBSD developer, who has direct access to the GNATS database, can periodically check for PRs of this sort and move interesting bits of the misfiled PR into the audit trail of the original PR (by posting a proper followup to a bug report to the address bug-followup@freebsd.org). Then the misfiled PR can be closed with a message similar to: Your problem report was misfiled. Please use the format "Subject: category/number: original text" when following up to older, existing PRs. I've added the relevant bits from the body of this PR to kern/12345 Searching with query-pr for the original PR, of which a misfiled followup is a reply, is as easy as running: &prompt.user; query-pr -q -y "some text" After you locate the original PR and the misfiled followups, use the option of query-pr to save the full text of all the - relevant PRs in a Unix mailbox file, i.e.: + relevant PRs in a &unix; mailbox file, i.e.: &prompt.user; query-pr -F 52458 52474 > mbox Now you can use any mail user agent to view all the PRs you saved in mbox. Copy the text of all the misfiled PRs in a followup to the original PR and make sure you include the proper Subject: header. Then close the misfiled PRs. When you close the misfiled PRs remember that the submitter receives a mail notification that his PR changed state to closed. Make sure you provide enough details in the log about the reason of this state change. Typically something like the following is ok: Followup to ports/45364 misfiled as a new PR. This was misfiled because the subject didn't have the format: Re: ports/45364: ... This way the submitter of the misfiled PR will know what to avoid the next time a followup to an existing PR is sent.
PRs misfiled because of missing fields The second type of misfiled PRs is usually the result of a submitter forgetting to fill all the necessary fields when writing the original PR. Missing or bogus category or class fields can result in a misfiled report. Developers can use &man.edit-pr.1; to change the category or class of these misfiled PRs to a more appropriate value and save the PR. Another common cause of misfiled PRs because of formatting issues is quoting, changes or removal of the send-pr template, either by the user who edits the template or by mailers which do strange things to plain text messages. This doesn't happen a lot of the time, but it can be fixed with edit-pr too; it does require a bit of work from the developer who refiles the PR, but it's relatively easy to do most of the time.
Misfiled PRs that are not really problem reports Sometimes a user wants to submit a report for a problem and sends a simple email message to GNATS. The GNATS scripts will recognize bug reports that are formatted using the &man.send-pr.1; template. They cannot parse any sort of email though. This is why submissions of bug reports that are sent to freebsd-gnats-submit@freebsd.org have to follow the template of send-pr, but email reports can be sent to &a.bugs;. Developers that come across PRs that look like they should have been posted to &a.bugs.name; or some other list should close the PR, informing the submitter in their state-change log why this is not really a PR and where the message should be posted. The email addresses that GNATS listens to for incoming PRs have been published as part of the FreeBSD documentation, have been announced and listed on the web-site. This means that spammers found them. Every day several messages with advertisements would reach GNATS which promptly files them all under the pending category until someone looks at them. Closing one of these with &man.edit-pr.1; is very annoying though, because GNATS replies to the submitter and the sender's address of spam mail is never valid these days. Bounces will come back for each PR that is closed. Currently, with the installation of some antispam filters that check all submissions to the GNATS database, the amount of spam that reaches the pending state is very small. All developers who have access to the FreeBSD.org cluster machines are encouraged to check for misfiled PRs and immediately close those that are spam mail. Whenever you close one of these PRs it is also a good idea to set its category to junk. Junk PRs are not backed up, so filing spam mail under this category makes it obvious that we do not care to keep it around or waste disk space for it.
Further Reading This is a list of resources relevant to the proper writing and processing of problem reports. It is by no means complete. How to Write FreeBSD Problem Reports—guidelines for PR originators.
diff --git a/en_US.ISO8859-1/articles/problem-reports/article.sgml b/en_US.ISO8859-1/articles/problem-reports/article.sgml index 82bb9a2e84..4b89a435d6 100644 --- a/en_US.ISO8859-1/articles/problem-reports/article.sgml +++ b/en_US.ISO8859-1/articles/problem-reports/article.sgml @@ -1,737 +1,748 @@ %man; %mailing-lists; + +%trademarks; ]>
Writing FreeBSD Problem Reports $FreeBSD$ + + &tm-attrib.freebsd; + &tm-attrib.ibm; + &tm-attrib.intel; + &tm-attrib.sparc; + &tm-attrib.sun; + &tm-attrib.general; + + This article describes how to best formulate and submit a problem report to the FreeBSD Project. Dag-Erling Smørgrav Contributed by problem reports
Introduction One of the most frustrating experiences one can have as a software user is to submit a problem report only to have it summarily closed with a terse and unhelpful explanation like not a bug or bogus PR. Similarly, one of the most frustrating experiences as a software developer is to be flooded with problem reports that are not really problem reports but requests for support, or that contain little or no information about what the problem is and how to reproduce it. This document attempts to describe how to write good problem reports. What, you ask, is a good problem report? Well, to go straight to the bottom line, a good problem report is one that can be analyzed and dealt with swiftly, to the mutual satisfaction of both user and developer. Although the primary focus of this article is on FreeBSD problem reports, most of it should apply quite well to other software projects. Note that this article is organized thematically, not chronologically, so you should read through the entire document before submitting a problem report, rather than treat it as a step-by-step tutorial.
When to submit a problem report There are many types of problems, and not all of them should engender a problem report. Of course, nobody is perfect, and there will be times when you are convinced you have found a bug in a program when in fact you have misunderstood the syntax for a command or made a typographical error in a configuration file (though that in itself may sometimes be indicative of poor documentation or poor error handling in the application). There are still many cases where submitting a problem report is clearly not the right course of action, and will only serve to frustrate you and the developers. Conversely, there are cases where it might be appropriate to submit a problem report about something else than a bug—an enhancement or a feature request, for instance. So how do you determine what is a bug and what is not? As a simple rule of thumb your problem is not a bug if it can be expressed as a question (usually of the form How do I do X? or Where can I find Y?). It is not always quite so black and white, but the question rule covers a large majority of cases. If you are looking for an answer, consider posing your question to the &a.questions;. Some cases where it may be appropriate to submit a problem report about something that is not a bug are: Requests for feature enhancements. It is generally a good idea to air these on the mailing lists before submitting a problem report. Notification of updates to externally maintained software (mainly ports, but also externally maintained base system components such as BIND or various GNU utilities). Another thing is that if the system on which you experienced the bug is not fairly up-to-date, you should seriously consider upgrading and trying to reproduce the problem on an up-to-date system before submitting a problem report. There are few things that will annoy a developer more than receiving a problem report about a bug she has already fixed. Finally, a bug that can not be reproduced can rarely be fixed. If the bug only occurred once and you can not reproduce it, and it does not seem to happen to anybody else, chances are none of the developers will be able to reproduce it or figure out what is wrong. That does not mean it did not happen, but it does mean that the chances of your problem report ever leading to a bug fix are very slim, and you should consider letting the matter drop.
Preparations A good rule to follow is to always do a background search before submitting a problem report. Maybe your problem has already been reported; maybe it is being discussed on the mailing lists, or recently was; it may even already be fixed in a newer version than what you are running. You should therefore check all the obvious places before submitting your problem report. For FreeBSD, this means: The FreeBSD Frequently Asked Questions (FAQ) list. The FAQ attempts to provide answers for a wide range of questions, such as those concerning hardware compatibility, user applications, and kernel configuration. The mailing lists—if you are not subscribed, use the searchable archives on the FreeBSD web site. If your problem has not been discussed on the lists, you might try posting a message about it and waiting a few days to see if someone can spot something you have overlooked. Optionally, the entire web—use your favorite search engine to locate any references to your problem. You may even get hits from archived mailing lists or newsgroups you did not know of or had not thought to search through. Next, the searchable FreeBSD PR database (GNATS). Unless your problem is recent or obscure, there is a fair chance it has already been reported. Finally, if you are upgrading from one version to another—especially if you are upgrading to the -current branch—you should carefully study the contents of the /usr/src/UPDATING file on your system or its latest version at . This file contains many pieces of vital information. Next, you need to make sure your problem report goes to the right people. The first catch here is that if the problem is a bug in third-party software (a port or a package you have installed), you should report the bug to the original author, not to the FreeBSD Project. There are two exceptions to this rule: the first is if the bug does not occur on other platforms, in which case the problem may lie in how the software was ported to FreeBSD; the second is if the original author has already fixed the bug and released a patch or a new version of his software, and the FreeBSD port has not been updated yet. The second catch is that FreeBSD's bug tracking system sorts problem reports according to the category the originator selected. Therefore, if you select the wrong category when you submit your problem report, there is a good chance that it will go unnoticed for a while, until someone re-categorizes it.
Writing the problem report Now that you have decided that your issue merits a problem report, and that it is a FreeBSD problem, it is time to write the actual problem report. Before we get into the mechanics of the program used to generate and submit PRs, here are some tips and tricks to help make sure that your PR will be most effective.
Tips and tricks for writing a good problem report Do not leave the Synopsis line empty. The PRs go both onto a mailing list that goes all over the world (where the Synopsis is used for the Subject: line), but also into a database. Anyone who comes along later and browses the database by synopsis, and finds a PR with a blank subject line, tends just to skip over it. Remember that PRs stay in this database until they are closed by someone; an anonymous one will usually just disappear in the noise. Avoid using a weak Synopsis line. You should not assume that anyone reading your PR has any context for your submission, so the more you provide, the better. For instance, what part of the system does the problem apply to? Do you only see the problem while installing, or while running? To illustrate, instead of Synopsis: portupgrade is broken, see how much more informative this seems: Synopsis: port sysutils/portupgrade coredumps on -current. (In the case of ports, it is especially helpful to have both the category and portname in the Synopsis line.) If you have a patch, say so. A PR with a patch included is much more likely to be looked at than one without. If you are including one, put the string [patch] at the beginning of the Synopsis. (Although it is not mandatory to use that exact string, by convention, that is the one that is used.) If you are a maintainer, say so. If you are maintaining a part of the source code (for instance, a port), you might consider adding the string [maintainer update] at the beginning of your synopsis line and/or set the Class of your PR to maintainer-update. This way any committer that handles your PR will not have to check with the Makefile of the PR every time the PR is viewed to make sure this is an update sent by the maintainer of the port. Be specific. The more information you supply about what problem you are having, the better your chance of getting a response. You should include such things as what version you are running (there is a place to put that, see below); which architecture you are running on; whether you are running from a release CDROM, or from a system maintained by &man.cvsup.1; (and, if so, how recently you updated); and, if a kernel problem, if you have read src/UPDATING (someone is guaranteed to ask). You do not necessarily have to provide your kernel configuration, which ports you have available, and a core dump (including these by default only tends to fill up the database), but you should be prepared to make them available, either privately or publicly, if so asked. Avoid vague requests for features. PRs of the form someone should really implement something that does so-and-so are less likely to get results than very specific requests. Remember, the source is available to everyone, so if you want a feature, the best way to ensure it being included is to get to work! Also consider the fact that many things like this would make a better topic for discussion on freebsd-questions than an entry in the PR database, as discussed above. Make sure no one else has already submitted a similar PR. Although this has already been mentioned above, it bears repeating here. It only take a minute or two to use the web-based search engine at . (Of course, everyone is guilty of forgetting to do this now and then.) Avoid controversial requests. If your PR addresses an area that has been controversial in the past, you should probably be prepared to not only offer patches, but also justification for why the patches are The Right Thing To Do. As noted above, a careful search of the mailing lists using the archives at is always good preparation. Be polite. Almost anyone who would potentially work on your PR is a volunteer. No one likes to be told that they have to do something when they are already doing it for some motivation other than monetary gain. This is a good thing to keep in mind at all times on Open Source projects.
Before you begin Before running the &man.send-pr.1; program, make sure your VISUAL (or EDITOR if VISUAL is not set) environment variable is set to something sensible. You should also make sure that mail delivery works fine. &man.send-pr.1; uses mail messages for the submission and tracking of problem reports. If you cannot post mail messages from the machine you're running &man.send-pr.1; on, your problem report will not reach the GNATS database. For details on the setup of mail on FreeBSD, see the Electronic Mail chapter of the FreeBSD Handbook at .
Attaching patches or files The &man.send-pr.1; program has provisions for attaching files to a problem report. You can attach as many files as you want provided that each has a unique base name (i.e. the name of the file proper, without the path). Just use the command-line option to specify the names of the files you wish to attach: &prompt.user; send-pr -a /var/run/dmesg -a /tmp/errors Do not worry about binary files, they will be automatically encoded so as not to upset your mail agent. If you attach a patch, make sure you use the or option to &man.diff.1; to create a context or unified diff (unified is preferred), and make sure to specify the exact CVS revision numbers of the files you modified so the developers who read your report will be able to apply them easily. A patch against the CURRENT or HEAD CVS branch is preferred since all new code should be applied and tested there first. After appropriate or substantial testing has been done, the code will be merged/migrated to the STABLE branch. If you attach a patch inline, instead of as an attachment, note that the most common problem by far is the tendency of some email programs to render tabs as spaces, which will completely ruin anything intended to be part of a Makefile. Also note that while including small patches in a PR is generally all right—particularly when they fix the problem described in the PR—large patches and especially new code which may require substantial review before committing should be placed on a web or ftp server, and the URL should be included in the PR instead of the patch. Patches in email tend to get mangled, especially when GNATS is involved, and the larger the patch, the harder it will be for interested parties to unmangle it. Also, posting a patch on the web allows you to modify it without having to resubmit the entire patch in a followup to the original PR. You should also take note that unless you explicitly specify otherwise in your PR or in the patch itself, any patches you submit will be assumed to be licensed under the same terms as the original file you modified.
Filling out the template When you run &man.send-pr.1;, you are presented with a template. The template consists of a list of fields, some of which are pre-filled, and some of which have comments explaining their purpose or listing acceptable values. Do not worry about the comments; they will be removed automatically if you do not modify them or remove them yourself. At the top of the template, below the SEND-PR: lines, are the email headers. You do not normally need to modify these, unless you are sending the problem report from a machine or account that can send but not receive mail, in which case you will want to set the From: and Reply-To: to your real email address. You may also want to send yourself (or someone else) a carbon copy of the problem report by adding one or more email addresses to the Cc: header. Next comes a series of single-line fields: Submitter-Id: Do not change this. The default value of current-users is correct, even if you run FreeBSD-STABLE. Originator: This is normally prefilled with the gecos field of the currently logged-in user. Please specify your real name, optionally followed by your email address in angle brackets. Organization: Whatever you feel like. This field is not used for anything significant. Confidential: This is prefilled to no. Changing it makes no sense as there is no such thing as a confidential FreeBSD problem report—the PR database is distributed worldwide by CVSup. Synopsis: Fill this out with a short and accurate description of the problem. The synopsis is used as the subject of the problem report email, and is used in problem report listings and summaries; problem reports with obscure synopses tend to get ignored. As noted above, if your problem report includes a patch, please have the synopsis start with [patch]; if you are a maintainer, you may consider adding [maintainer update] and/or set the Class of your PR to maintainer-update. Severity: One of non-critical, serious or critical. Do not overreact; refrain from labeling your problem critical unless it really is (e.g. root exploit, easily reproducible panic). Developers tend to ignore this and the next field, precisely because problem report submitters tend to overrate their problems. Priority: One of low, medium or high. See above. Category: Choose one of the following: advocacy: problems relating to FreeBSD's public image. Rarely used. alpha: problems specific to the Alpha platform. amd64: problems specific to the AMD64 platform. bin: problems with userland programs in the base system. conf: problems with configuration files, default values etc. docs: problems with manual pages or on-line documentation. gnu: problems with GNU software such as &man.gcc.1; or &man.grep.1;. i386: problems specific to the - i386 platform. + &i386; platform. ia64: problems specific to the ia64 platform. - java: problems related to Java™. + java: problems related to &java;. kern: problems with kernel. misc: anything that does not fit in any of the other categories. (Note that it is easy for things to get lost in this category). ports: problems relating to the ports tree. powerpc: problems specific to the - PowerPC platform. + &powerpc; platform. sparc64: problems specific to the - SPARC platform. + &sparc64; platform. standards: Standards conformance issues. www: Changes or enhancements to the FreeBSD website. Class: Choose one of the following: sw-bug: software bugs. doc-bug: errors in documentation. change-request: requests for additional features or changes in existing features. update: updates to ports or other contributed software. maintainer-update: updates to ports for which you are the maintainer. Release: The version of FreeBSD that you are running. This is filled out automatically by &man.send-pr.1; and need only be changed if you are sending a problem report from a different system than the one that exhibits the problem. Finally, there is a series of multi-line fields: Environment: This should describe, as accurately as possible, the environment in which the problem has been observed. This includes the operating system version, the version of the specific program or file that contains the problem, and any other relevant items such as system configuration, other installed software that influences the problem, etc.—quite simply everything a developer needs to know to reconstruct the environment in which the problem occurs. Description: A complete and accurate description of the problem you are experiencing. Try to avoid speculating about the causes of the problem unless you are certain that you are on the right track, as it may mislead a developer into making incorrect assumptions about the problem. How-To-Repeat: A summary of the actions you need to take to reproduce the problem. Fix: Preferably a patch, or at least a workaround (which not only helps other people with the same problem work around it, but may also help a developer understand the cause for the problem), but if you do not have any firm ideas for either, it is better to leave this field blank than to speculate.
Sending off the problem report Once you are done filling out the template, have saved it, and exit your editor, &man.send-pr.1; will prompt you with s)end, e)dit or a)bort?. You can then hit s to go ahead and submit the problem report, e to restart the editor and make further modifications, or a to abort. If you choose the latter, your problem report will remain on disk (&man.send-pr.1; will tell you the filename before it terminates), so you can edit it at your leisure, or maybe transfer it to a system with better net connectivity, before sending it with the to &man.send-pr.1;: &prompt.user; send-pr -f ~/my-problem-report This will read the specified file, validate the contents, strip comments and send it off.
Follow-up Once your problem report has been filed, you will receive a confirmation by email which will include the tracking number that was assigned to your problem report and a URL you can use to check its status. With a little luck, someone will take an interest in your problem and try to address it, or, as the case may be, explain why it is not a problem. You will be automatically notified of any change of status, and you will receive copies of any comments or patches someone may attach to your problem report's audit trail. If someone requests additional information from you, or you remember or discover something you did not mention in the initial report, just mail it to bug-followup@FreeBSD.org, making sure that the tracking number is included in the subject so the bug tracking system will know what problem report to attach it to. If the problem report remains open after the problem has gone away, just send a follow-up (in the manner prescribed above) saying that the problem report can be closed, and, if possible, explaining how or when the problem was fixed.
Further Reading This is a list of resources relevant to the proper writing and processing of problem reports. It is by no means complete. How to Report Bugs Effectively—an excellent essay by Simon G. Tatham on composing useful (non-FreeBSD-specific) problem reports. Problem Report Handling Guidelines—valuable insight into how problem reports are handled by the FreeBSD developers.