diff --git a/en_US.ISO8859-1/articles/console-server/article.sgml b/en_US.ISO8859-1/articles/console-server/article.sgml index 3847c630b8..a3faa6f3c0 100644 --- a/en_US.ISO8859-1/articles/console-server/article.sgml +++ b/en_US.ISO8859-1/articles/console-server/article.sgml @@ -1,1475 +1,1475 @@ %articles.ent; ]>
Console Server Gregory Bond
gnb@itga.com.au
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.cisco; &tm-attrib.intel; &tm-attrib.lantronix; &tm-attrib.microsoft; &tm-attrib.opengroup; &tm-attrib.sun; &tm-attrib.general; This document describes how you can use &os; to set up a console server. A console server is a machine that you can use to monitor the consoles of many other machines, instead of a bunch of serial terminals. console-server The Problem You have a computer room with lots of &unix; server machines and lots of communications hardware. Each of these machines needs a serial console. But serial terminals are hard to find and quite expensive (especially compared to a much more capable PC). And they take up a lot of precious space in the computer room. You need access to the console because when things break, that is where error messages go. And some tasks have to be done on the console (e.g. boot problems or OS installs/upgrades). Some &unix; systems allow the console to break out to the ROM monitor which can sometimes be the only way to unstick a hung machine. This is often done with a LINE BREAK sent on the console serial port. If we are going to play about with consoles, then there are a couple of other things that would be great: Remote access. Even in the same office, it would be convenient to access all the consoles from your desk without walking into the computer room. But often the machines are off-site, perhaps even in another country. Logging. If something has gone wrong, you would like to be able to have a look at the previous console output to see what is up. Ordinary console screens give you the last 25 lines. More would be better. Network Independence. The solution needs to work even if the network is down. After all, a failed network is when you need consoles the most! Even better is network independence with remote access. No single-point failure. A console system that crashes every machine when it fails is no use. This is particularly tricky with Sun &unix; hosts as they will interpret a powered-off terminal as a BREAK, and drop back to the ROM monitor. Interface with a pager or some similar alerter device. Ability to power-cycle machines remotely. Not be too expensive. Free is even better! Possible Solutions If you use PC hardware for your servers, then a so-called KVM switch is one possible solution. A KVM switch allows the use of a single keyboard, video screen and mouse for multiple boxes. This cuts down on the space problem, but only works for PC hardware (not any communications gear you might have), and is not accessible from outside the computer room. Nor does it have much scroll-back or logging, and you have to handle alerting some other way. The big downside is that it will not work for serial-only devices, such as communications hardware. This means that even with a room full of PC-based servers, you are probably still going to need some sort of serial console solution. Actually, Doug Schache has pointed out that you can get KVM switches that also do serial consoles or Sun compatible KVM switching as well as PCs, but they are - expensive. See Avocent + expensive. See Avocent for example.) You might be tempted to do without a console terminal, but when things go pear-shaped you really need to see what is on the console. And you have to use the console to boot the machine and do things like OS upgrades or installs. You might try having a single console terminal and switching from server to server as needed, either with a serial switch or just by patching it into the required machine. Serial switches are also hard to come by and not cheap, and may cause problems with sending BREAK when they switch. And (if your computer room is anything like ours) you never seem to have the right combination of patch leads to connect to the machine you need to, and even if the leads are there you can never work out exactly which combination of DTE/DCE headshells goes with which lead goes with which hardware. So you spend the first 10 minutes fooling around with breakout boxes and a box of leads, all while the server is down and the users are screaming. Of course this does not deal with the logging or remote access requirements. And inevitably the console is not switched to the machine you need so you lose all the console messages that might tell you what is going on. One popular solution is to use terminal server hardware. Typically, the serial ports are connected to the various machine consoles, and set up for reverse telnet access. This means a user can telnet to a given IP/port and be connected to the appropriate console. This can be very cost-effective, as suitable old terminal servers can be picked up fairly cheaply (assuming you do not have a couple lying around). And it is of course network-accessible so suitable for remote access. But it suffers from one major drawback: if the network is down, then you have no access to any console, even if you are standing right next to the machine. (This may be partially alleviated by having a suitable terminal connected to one of the terminal server ports and connecting from there, but the terminal server software may not support that.) Also there is no logging or replay of console messages. But with a bit of work, and the addition of some software such as conserver (described below), this can be made to work pretty well. A possibility suggested by Bron Gondwana is similar to the above solution. If you use servers with multiple serial ports, you can connect each spare serial port to the console port of the next server, creating a ring of console connections (in some sort of order). This can be made to work reasonably well with the aid of the conserver software, but can be a bit confusing otherwise (i.e. remembering which port is connected to which console). And you are stuck if you need to use serial ports for other things (such as modems) or you have machines without spare ports. Or, if your budget exceeds your willingness to hack, you can buy an off-the-shelf solution. These vary in price and capability. See, for example, Lightwave, Perle, Avocent or Black Box. These solutions can be quite expensive - typically $USD100 - $USD400 per port. Our Solution In light of the above requirements, we chose a solution based on a dedicated PC running &unix; with a multiport serial card, and some software designed to handle serial consoles. It includes the following elements: A surplus PC. We used a &pentium; 166, with a PCI bus, 2Gbyte hard disk and 64Mb of RAM. This is a massive overkill for this task, and P-100, 500Mb, 32Mb would be more than enough. A PC &unix; system. We used &os; 4.3 as that is used for + url="&url.base;/index.html">&os; 4.3 as that is used for other tasks within our office. A multi-port serial card. We chose the &easyio; PCI - 8-port card from Stallion + url="http://www.stallion.com/html/products/easyio.html">&easyio; PCI + 8-port card from Stallion Technologies. This cost us about $AUD740, or under - $100/port, from Harris + $100/port, from Harris Technologies (which has lots of stuff but is by no means the cheapest place in town - shop around and you might get it a lot cheaper). This card has a big DB80 connector on the back, and a cable plugs into that which has a block with 8 RJ-45 sockets on it. (We chose the RJ-45 version as our entire cable plant is RJ-45. This allows us to patch connections from the required box to the console server without any special cables.) This is the only thing we needed to buy to make this all happen. We build two servers, one for each computer room, with 8 ports in one and 16 ports (via two &easyio; PCI cards) in the other. If we needed more than 16 ports, then another of the Stallion cards would be more cost-effective. We could conceivably support 128 ports in each server (with 2 EasyConnect 8/64 host cards and 8 16 port RJ-45 modules) for about $AUD12,000. A modem for remote access to the console server host when the network is down. We have not done this yet as the computer room is next door, but when we put a server in Sydney we will add the modem. The idea is that when the network is down, you can dial up and log into the server machine and run the console program locally. For security, we will probably leave the modem powered off and ask the gopher in Sydney to turn on the well-labelled button when we need it. A program called conserver. This program + url="http://www.conserver.com/">conserver. This program does all the magic required to enable remote access to consoles, and do the replaying and logging etc. It comes in two parts: a server called conserver that runs as a daemon and connects to the serial ports, handles logging etc, and a client program called console that can connect to the server, display console messages, send keystrokes (and BREAK), etc. This design covers all the major requirements except remote power cycling: Remote access comes because the console client program works across the network. Logging is handled by the conserver program. If the network is down, then we can use the console on the PC to run the console client locally. For remote sites, we can add a modem for dial-in access to the the server command line to run the client. By patching the &solaris; servers (see ), we can avoid pranging the whole computer room when the console server PC crashes (or the power supply fails, or whatever). We already have pager alerts from another system we have installed, but the console server has all the required log info so that could easily be implemented if we needed. And it even has a modem for calling the pager company! We do not currently support remote power cycling. Some versions of the conserver program support this, but it does require specialised serial-controlled power boards. We have no immediate need for remote power cycling (we have a gopher in each remote office who can do it by remote control) so this is not a major problem, and we could add it easily should we ever see the need and get the appropriate hardware. This solution was very cheap. Total cost for the 9-port server was $AUD750 for the IO card, as we re-used a surplus PC and already owned the hardware for the special cables. If we had to buy everything, then it would still only cost around $AUD1500 for the 8-port server. Setting Up The Server Checking the Stallion driver &os; has adequate support for modern Stallion cards since 4.4 release. If you are running an older version of &os;, you will need to upgrade to a more modern version of &os; (which you should do anyway, to make sure your system is not vulnerable to known security issues). See the &os; Handbook for information about updating your system. Configuring a new kernel The Stallion driver is not included in the default GENERIC kernel, so you will need to create a kernel config file with the appropriate entries. See &man.stl.4; and the appropriate section of the &os; + url="&url.books.handbook;/kernelconfig.html">&os; Handbook. Making The Devices You will need to make the device notes for the Stallion card (which are not made by default). A new version of /dev/MAKEDEV with Stallion support will have been created by the mergemaster run during the above procedure. If you have a Stallion card with more than 8 ports, then you will need to edit /dev/MAKEDEV and change the definition of maxport at about line 250. By default, MAKEDEV only makes device nodes for 8 ports to keep the size of the /dev directory down. Run a command like: &prompt.root; cd /dev/ && sh MAKEDEV cuaE0 to create dial-out devices for the first Stallion card. See the comments in MAKEDEV and the &man.stl.4; man page for more details. Compiling conserver See the section on conserver versions ; the version I use is available in the &os; ports collection; however, it is not the only one.) There are two ways to install conserver. You can either compile from the source or use the &os; ports framework. Using the ports framework Using the ports is a bit cleaner, as the package system can then keep track of installed software and cleanly delete them when not being used. I recommend using the comms/conserver-com port. Change into the port directory and (as root) type: &prompt.root; make DEFAULTHOST=consolehost install where consolehost is the name of the machine running the console server. Specifying this when the binary is compiled will avoid having to either specify it each time the program is run on remote hosts or having to maintain a conserver.cf file on every host. This command will fetch, patch, configure, compile and install the conserver application. You can then run make package to create a binary package that can be installed on all the other &os; hosts with &man.pkg.add.1;. For extra style points, you can make a two versions of the package: one for the console server machine without a DEFAULTHOST argument, and one for all the other hosts with a DEFAULTHOST argument. This will mean the console client program on the console server machine will default to localhost, which will work in the absence of name servers when the network is busted, and also allow trusted (i.e. no password required) connections via the localhost IP address for users logged into the console server machine (either via the console screen or the emergency backup modem). The version for the other machines with a DEFAULTHOST argument means users can just use the console client without specifying a hostname every time, and without needing to configure the conserver.cf file on every machine. From the source tarball If you prefer, you can download conserver and compile it yourself. You might need to do this if you want to install the console client on non-&os; systems. We run the client on our &solaris; hosts and it inter-operates with the &os;-hosted server with no problems. This allows anyone in the whole company (many of whom have PCs and no &os; host access on their desk) to access the console server. Download the file from the conserver.com + url="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">conserver.com FTP site. Extract it into a handy directory then configure it by running &prompt.user; ./configure The argument avoids having to specify the master server every time the client is run remotely (or keeping up-to-date config files on all remote hosts). The argument avoids having to update on every machine. Then type make and, as root, make install. Configuring conserver The conserver program is configured via a file called conserver.cf. This file usually lives in /usr/local/etc and is documented in the &man.conserver.cf.5; manual page. Our config file looks like this: LOGDIR=/var/log/consoles gallows:/dev/cuaE0:9600p:&: roo:/dev/cuaE1:9600p:&: kanga:/dev/cuaE2:9600p:&: %% allow: itga.com.au trusted: 127.0.0.1 buzz The first line means all the console log files by default go into the /var/log/consoles directory. The & in each line says the log file for that machine will be /var/log/consoles/machine. The next three lines show three machines to which we need to connect. We use the cuaEx devices rather than the ttyEx devices because console ports typically do not show carrier. This means that opening ttyEx would hang and conserver would never connect. Using the cuaEx device avoids this problem. Another solution would be to use the ttyEx devices and enable soft carrier on these ports, perhaps by setting this using the ttyiEx device in the /etc/rc.serial file. See the comments in this file for more details. Also see &man.sio.4; for information on the initial-state and locked-state devices. (The Stallion driver also supports these conventions). And see the &man.stty.1; for details on setting device modes. The last section shows that any user logged into the server machine has passwordless access to all consoles. We do this because there are no user accounts on this machine and it is safely isolated from the wide world behind our firewall. The allow line allows anyone on a machine inside our organisation to access the console server if they provide their password, which is recorded in the conserver.passwd file (see next section). Setting conserver passwords The conserver.passwd file contains the encrypted version of the password that each user. The file is documented in the conserver.cf(5) manual page. The only tricky bit is loading the file with encoded passwords. It appeared in &os; that was is no obvious way to generate an encrypted password for inclusion in another file (but see below). So I put together a quick hack perl script to do this: @rands = (); foreach (0..4) { push(@rands, rand 64); } $salt = join '', ('.', '/', 0..9, 'A'..'Z', 'a'..'z')[@rands]; $salt = '$1$' . $salt . '$'; print 'Enter password: '; `stty -echo`; $cleartext = <>; `stty echo`; chop($cleartext); print crypt($cleartext, $salt), "\n"; This uses the &os; MD5-style encrypted passwords. Running this on other &unix; variants, or on &os; with DES passwords, will likely need a different style of salt. &a.kris; has since pointed out you can get the same effect using the openssl passwd command: &prompt.user; openssl passwd -1 Password: password $1$VTd27V2G$eFu23iHpLvCBM5nQtNlKj/ Starting <application>conserver</application> at system boot time There are two ways this can be done. Firstly, you could start up conserver from init by including an entry in /etc/ttys that is similar to this: cuaE0 "/usr/local/sbin/conserver" unknown on insecure This has two advantages: init will restart the master console server if it ever crashes for any reason (but we have not noticed any crashes so far), and it arranges for standard output of the conserver process to be directed to the named tty (in this case cuaE0). This is useful because you can plug a terminal into this port, and the conserver program will show all console output not otherwise captured by a client console connection. This is useful as a general monitoring tool to see if anything is going on. We set this terminal up in the computer room but visible from the main office. It is a very handy feature. The downside of running conserver from the ttys file is that it cannot run in daemon mode (else &man.init.8; would continually restart it). This means conserver will not write a PID file, which makes it hard to rotate the log files. So we start conserver from an rc.d script. If you installed conserver via the port, there will be a conserver.sh.sample file installed in /usr/local/etc/rc.d. Copy and/or rename this to conserver.sh to enable conserver to start at boot time. In fact we use a modified version of this script which also connects conserver to a terminal via a tty device so we can monitor unwatched console output. Our conserver.sh script looks like this: #!/bin/sh # # Startup for conserver # PATH=/usr/bin:/usr/local/bin case "$1" in 'start') TTY=/dev/cuaE7 conserver -d > $TTY # get NL->CR+NL mapping so msgs look right stty < /dev/cuaE7 opost onlcr echo -n ' conserver' ;; 'stop') kill `cat /var/run/conserver.pid` && echo -n ' conserver' ;; *) echo "Usage: $0 { start | stop }" ;; esac exit 0 Note the use of cuaE0 device and the need to set tty modes for proper NL-<CR handling). Keeping the log files trimmed &os; has a program called newsyslog that will automatically handle log file trimming. Just add some lines to the configuration file /etc/newsyslog.conf for the console logs: # # The log files from conserver /var/log/consoles/gallows 644 10 1000 * Z /var/run/conserver.pid /var/log/consoles/kanga 644 10 1000 * Z /var/run/conserver.pid /var/log/consoles/roo 644 10 1000 * Z /var/run/conserver.pid This tells newsyslog (which is run from cron every hour on the hour) that the console log files should be archived and compressed once they reach 1Mb, that we should keep 10 of them, and that to signal the server program you send a SIGHUP to the process whose PID is in the conserver.pid file. This is the master server, and it will arrange to signal all the child processes. Yes, this will send a HUP to all clients whenever a single log file needs rotating, but that is quite cheap. See &man.newsyslog.8; for details. Cabling This is always the hardest part of this kind of problem. We had only a dozen or so cables/headshells to build, and we already had a collection of the appropriate crimping tools and hardware, so we did it ourselves. But if you are not set up for this, or you have a large number of cables to make, then you might consider getting some cables custom made. Look in the yellow pages, there are a surprising number of places that do this! Getting custom-made cabling is good, and you can get much more professional results, but can be expensive. For example, the RJ-45 to DB-25 adapter kits described below are about $10 each; custom-made headshells are about twice that (and take a couple of weeks to arrive). Similarly, crimping custom RJ-45 to RJ-45 leads is quite cheap (say, $5 each) but it takes a fair amount of time. Custom made RJ-45 socket to RJ-45 plug converters cost about $25 each. We have settled on RJ-45 Cat-V cabling for all our office and computer room cabling needs. This included patching between racks in the computer room. For serial connections, we use patchable headshells that have RJ-45 sockets on the back. This allows us to patch whatever RJ-45–DB-25 connections we need. Which is just as well, because there are many incompatible ways to represent serial connections on the RJ-45 plug. So the cabling has to be very careful to use the right mapping. RJ-45 colors RJ-45 cables and plugs have 8 pins/conductors. These are used as 4 matched pairs. There are a couple of conventions about how the pairs are mapped onto pins, but 100baseT uses the most common (known as EIA 586B). There are three common color-coding conventions for the individual conductors in RJ-45 cables. They are: <!-- XXX: Add title for this table --> Pin Scheme 1 Scheme 2 (EIA 568B) Scheme 3 (EIA 568A) Pair 1 Blue White+Green White+Orange 2+ 2 Orange Green Orange 2- 3 Black White+Orange White+Green 3+ 4 Red Blue Blue 1+ 5 Green White+Blue White+Blue 1- 6 Yellow Orange Green 3- 7 Brown White+Brown White+Brown 4+ 8 White or Grey Brown Brown 4-
Note EIA 468A and EIA 568B are very similar, simply swapping the colors assigned to pair 2 and pair 3. See for example the Cabletron + url="http://www.cabletron.com/support/techtips/tk0231-9.html">Cabletron Tech Support Site for more details. The pins in the RJ-45 plug are numbered from 1 to 8. Holding a patch lead with the cable pointing down and the clip away from you, pin 1 is at the left. Or, looking into an RJ-45 socket with the clip to the top, pin 1 is on the right. The following illustration (shamelessly lifted from the Cabletron web site above) shows it pretty well: We have four classes of equipment to deal with in our setup: Sun servers Sun servers operate as DTE (i.e. send data on TxD and read RxD, and assert DTR) with a female DB-25 socket on board. So we need to create a headshell for the Stallion that operates as DCE and has a male DB-25 plug (i.e. acts as a null modem cable as well as converts from RJ-45 to DB-25). We use headshells that have an RJ-45 socket in them and 8 short flyleads with DB-25 pins on the end. These pins can be inserted into the DB-25 plug as required. This allows us to create a custom RJ-45-DB-25 mapping. We used a couple of different sorts, including the - MOD-TAP + MOD-TAP part no. 06-9888-999-00 + url="http://www.molexpn.com.au/products/index.nsx/1/7/0/0/id=340">06-9888-999-00 and the FA730 + url="http://www.blackbox.com/faxbacks/12000/12654.PDF">FA730 series from - Black + Black Box. On our version of the headshells, these flyleads had the following colours (from Pin 1-8): Blue, Orange, Black, Red, Green, Yellow, Brown, White. (Looking into an RJ-45 socket, with the clip towards the top, pin 1 is on the right.) This is how they are connected to the DB-25 socket: <!-- XXX: Add a title here --> Stallion RJ-45 Pin Colour Signal Sun DB-25 Male Pin RS232 Signal 1 Blue DCD 20 DTR 2 Orange RTS 5 CTS 3 Black Chassis Gnd 1 Chassis Gnd 4 Red TxD 3 RxD 5 Green RxD 2 TxD 6 Yellow Signal Gnd 7 Signal Gnd 7 Brown CTS 4 RTS 8 White RTS 8 DCD
Note that colours may be different for your cables/headshells. In particular, pin 8 may be grey instead of white. Remember to label the headshell clearly, in a way that will not fade/fall off/rub off with time! Cisco 16xx/26xx/36xx Routers I think that all Cisco gear that has RJ-45 console ports and runs &ios; will have the same cable requirements. But best to check first. We have tried this on 1600s and 2600s only. Both the Stallion card and the 2600 have RJ-45 connections, but of course they are not compatible. So you need to crimp up a special RJ-45-RJ-45 cable. And this cable must be plugged in the right way round! We use normal RJ-45 flyleads from the router to the patch panel, then the special flylead from the patch panel to the Stallion card. We built two special Stallion-Cisco leads by cutting in half a 2m flylead and crimping an RJ-45 with the appropriate pinouts to each free end. The original connector will be the Cisco end of the cable, the new crimped connector will be the Stallion end. Holding the RJ-45 connector on the flylead with the cable pointing down and the clip pointing away, this is the order of the colours of the cables in our flylead (pins 1-8, from L to R): white/green, green, white/orange, blue, white/blue, orange, white/brown, brown. For the Stallion end, trim and discard the brown/white+brown and green/white+green pairs. Then holding the RJ-45 plug in the same manner (cable down, clip away), the connections should be (from L to R): None, None, Blue, Orange, White/Orange, White/Blue, None, None, as shown: <!-- XXX: add title for this table --> Cisco RJ-45 Pin Colour Cisco Signal Stallion RJ-45 Pin Stallion Signal 1 White/Green RTS N/C   2 Green DTR N/C   3 White/Orange TxD 5 RxD 4 Blue Gnd 3 Gnd 5 White/Blue Gnd 6 Gnd 6 Orange RxD 4 TxD 7 White/Brown DSR N/C   8 Brown CTS N/C  
Note again that colours may be different for your cables/headshells. Carefully label the cable, and each end of the cable, and test it. If it does not work, testing is really hard as they do not make RJ-45 serial line testers! Let me state this more strongly: Be very sure that you label this cable in a way that is easily, instantly and permanently recognisable as a special cable and not easily confused with normal drop cables. Some suggestions (from Hugh Irvine): Make them out of different coloured cable. For marking the ends, clear heat-shrink tubing slipped over printed labels *before* putting on the connectors is the best way I have seen for marking what they are. You can also use Panduit or similar tags that you put on with nylon tie straps, but I find the ink wears off the tags. Cisco &catalyst; switches Astoundingly, the pinout on the console ports of the &catalyst; switches is actually different to the pinout used on the 26xx-series Cisco hardware. I think the way to tell which is which is by considering the operating software. If it uses &ios;, then the previous pinout is required. If it uses the switch software, then this pinout is required. Fortunately, while the pinouts are different, the &catalyst; pinout is simply a mirror image of the pinout for the 2600. Even more fortunately, the Ciscos (both &catalyst; switches and 2600s) seem to ship with a special rollover cable, which is exactly what is required in this case. We use the rollover cable from the &catalyst; switches to the patch panel, then the same cable as above for the 2600s from the patch panel to the Stallion card, and it all works just fine. This rollover cable is an RJ-45-RJ-45 cable and is intended to be used with the shipped (hardwired) RJ-45 - DB-25 and RJ-45–DB-9 headshells for console connections. Ours are 2m long, either light blue or black, and are quite flat. Attempts to use them for 100baseT Ethernet will fail miserably! You can tell it is a rollover cable by holding both ends with the cable pointing down and the clip pointing away from you. Check the colour of the leads in each pin in the two connectors, they should be mirror images. (In our case, one goes grey-orange-black-red-green-yellow-blue-brown, the other brown-blue-yellow-green-red-black-orange-grey). This is a rollover cable. If you do not have a rollover cable present, then you can use the same cable as for the 26xx except plug it in the other way around (i.e. original 8-pin plug goes into the Stallion, the new crimped plug with only 4 active wires goes into the &catalyst; switch). &os; servers (or any other &i386; PC systems using a serial console) We run &os; 4 on a couple of &i386; PCs for various peripheral uses. &os; usually uses a screen and keyboard for the console, but can be configured to use a serial port (usually the first serial port known as COM1 in DOS/&windows; or ttyd0 in &unix;). The cabling for these servers depends on the PC harware. If the PC has DB-25 female socket on board (as most older PCs do), then the same headshell as works for the Sun server above will work fine. If the PC has DB-9 male plug on board (as more recent PCs tend to do), then there are two choices. Either use a DB-9 to DB-25 converter (this is not recommended as it can lead to unreliable connections over the long term as the adapter is bumped/works loose), or build an RJ-45 to DB-9 cable as follows: <!-- XXX: add title for this table --> Stallion RJ-45 Pin Colour Signal PC DB-9 Female Pin RS232 Signal 1 Blue DCD 4 DTR 2 Orange RTS 8 CTS 3 Black Chassis Gnd N/C   4 Red TxD 2 RxD 5 Green RxD 3 TxD 6 Yellow Signal Gnd 5 Signal Gnd 7 Brown CTS 7 RTS 8 White RTS 1 DCD
See for tips on configuring &os; to use a serial console. On Sun Systems And Break Anyone who has turned off a terminal used as a console for a Sun system will know what happens and why this is a problem. Sun hardware recognises a serial BREAK as a command to halt the OS and return to the ROM monitor prompt. A serial BREAK is an out-of-band signal on an RS-232 serial port that involves making the TX DATA line active (i.e. pulled down to less than -5v) for more than two whole character times (or about 2ms on a 9600bps line). Alas, this BREAK signal is all to easily generated by serial hardware during power-on or power-off. And the Stallion card does, in fact, generate breaks when the power to the PC fails. Unless fixed, this problem would mean that every Sun box connected to the console server would be halted whenever the power failed (due to dead power supplies, or fat-fingered operators unplugging it, or whatever). This is clearly not an acceptable situation. Fortunately, Sun have come up with a set of fixes for this. For &solaris; 2.6 and later, the kbd(1) command can be used to disable the ROM-on-BREAK behaviour. This is a good start, but leaves you out of luck in the situation where a break is needed to get into a broken machine. Starting with &solaris; 8, the kbd command can also be used to enable an alternate break sequence using the kbd -a alternate command. When this is set, the key sequence ReturnTildeCtrlB (within 5 seconds) will drop to the ROM. You can enable this permanently by editing the /etc/default/kbd file; see the kbd(1) man page. Note that this alternate break sequence is only active once the kernel has started running multiuser and processed the default file. While the ROM is active (during power-on and during the boot process) and while running single-user, you still need to use a BREAK to get to the ROM prompt. The console client can cause the server to send a BREAK using the escape sequence Esccl1. If you have a Sun software support contract, there are patches available for &solaris; 2.6 and 2.7 that add the alternate break capability integrated into &solaris; 2.8. &solaris; 2.6 requires patch 105924-10 or higher. &solaris; 2.7 requires patch 107589-02 or higher. We have added this patch to all our &solaris; 2.6 servers, and added it (and the entry in the /etc/default/kbd file) to our jumpstart configuration so it will automatically be added to every new install. We have confirmed by direct testing that neither the Cisco 16xx, 26xx, or &catalyst; hardware suffers from the BREAK sent when the Stallion card loses power. Contemporary Cisco software listens for BREAK signal only for first 30 seconds after power-on or reboot. Using a Serial Console on &os; The procedure for doing this is described in detail in the - &os; + &os; Handbook. This is a quick summary. Check the kernel configuration Check that the kernel configuration file has flags 0x10 in the config line for the sio0 device. This signals this device (known as COM1 in DOS/&windows; or /dev/ttyd0 in &os;) can be used as a console. This flag is set on the GENERIC and LINT sample configs, so is likely to be set in your kernel. Create the <filename>/boot.conf</filename> file This file should be created containing a single line containing just -h (minus the quotes). This tells the &os; boot blocks to use the serial console. Edit <filename>/etc/ttys</filename> Edit this file and make the following changes. If you are not going to have any keyboard/video screen on this server at all, you should find all the lines for ttyv devices like ttyv1 "/usr/libexec/getty Pc" cons25 on secure Change the on to off. This will stop login screens being run on the useless video consoles. Find the line containing ttyd0. Change it from ttyd0 "/usr/libexec/getty std.9600" dialup off secure to ttyd0 "/usr/libexec/getty std.9600" vt100 on secure (replacing vt100 with the term type of your console. The xterms terminal type might be a good choice). This allows you to log in to the console port once the system is running multi-user. Reboot and off you go! Security Implications The client-server protocol for conserver requires the user of the console client to enter a password. This password is passed across the net in cleartext! This means conserver is not really suitable for use across untrusted networks (such as the Internet). Use of conserver-only passwords (in the conserver.passwd file) slightly mitigate this problem, but anyone sniffing a conserver connection can easily get console access, and from there prang your machine using the console break sequence. For operating across the Internet, use something secure like SSH to log into to the server machine, and run the console client there. On Conserver Versions The conserver program has fractured into a number of versions. The home page referenced below seems to be the latest and most featureful version around, and for July 2004 carries a version number of 8.1.9. This is maintained by Bryan Stansell bryan@conserver.com, who has brought together the work of many people (listed on his webpage). The &os; ports collection contains a port for version 8.5 of conserver at comms/conserver. This seems to be older and less featureful than the 8.1.9 version (in particular, it does not support consoles connected to terminal server ports and does not support a conserver.passwd file), and is written in a fairly idiosyncratic manner (using a preprocessor to generate C code). Version 8.5 is maintained by Kevin S. Braunsdorf ksb+conserver@sa.fedex.com who did most of the original work on conserver, and whose work Bryan Stansell is building on. The 8.5 version does support one feature not in the 8.1.9 version (controlling power to remote machines via a specific serial-interfaced power controller hardware). Beginning with December 2001, Brian's version (currently 8.1.9) is also presented in ports collection at comms/conserver-com. We therefore recommend you to use this version as it is much more appropriate for console server building. Links - + Homepage for the latest version of conserver. - ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz + ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz The source tarball for version 8.1.9 of conserver. - + Homepage of Stallion Technologies. - + Davis Harris' Minor Scroll of Console Knowledge contains a heap of useful information on serial consoles and serial communications in general. - + The Greater Scroll of Console Knowledge contains even more specific information on connecting devices to various other devices. Oh the joy of standards! - + Doug Hughes has a similar console server, based on the screen program and an old &sunos; host. - + The Real Weasel company makes a ISA or PCI video card that looks like a PC video card but actually talks to a serial port. This can be used to implement serial consoles on PC hardware for operating systems that can not be forced to use serial console ports early enough. Manual Pages - console(8) + console(8) - conserver(8) + conserver(8) - conserver.cf(5) + conserver.cf(5)
diff --git a/en_US.ISO8859-1/articles/contributing/article.sgml b/en_US.ISO8859-1/articles/contributing/article.sgml index 0082d9daae..a3af0f837e 100644 --- a/en_US.ISO8859-1/articles/contributing/article.sgml +++ b/en_US.ISO8859-1/articles/contributing/article.sgml @@ -1,554 +1,554 @@ %articles.ent; ]>
Contributing to FreeBSD $FreeBSD$ This article describes the different ways in which an individual or organization may contribute to the FreeBSD Project. Jordan Hubbard Contributed by &tm-attrib.freebsd; &tm-attrib.ieee; &tm-attrib.general; contributing So you want to contribute to FreeBSD? That is great! FreeBSD relies on the contributions of its user base to survive. Your contributions are not only appreciated, they are vital to FreeBSD's continued growth. Contrary to what some people might have you believe, you do not need to be a hot-shot programmer or a close personal friend of the FreeBSD core team to have your contributions accepted. A large and growing number of international contributors, of greatly varying ages and areas of technical expertise, develop FreeBSD. There is always more work to be done than there are people available to do it, and more help is always appreciated. The FreeBSD project is responsible for an entire operating system environment, rather than just a kernel or a few scattered utilities. As such, our TODO lists span a very wide range of tasks: from documentation, beta testing and presentation, to the system installer and highly specialized types of kernel development. People of any skill level, in almost any area, can almost certainly help the project. Commercial entities engaged in FreeBSD-related enterprises are also encouraged to contact us. Do you need a special extension to make your product work? You will find us receptive to your requests, given that they are not too outlandish. Are you working on a value-added product? Please let us know! We may be able to work cooperatively on some aspect of it. The free software world is challenging many existing assumptions about how software is developed, sold, and maintained, and we urge you to at least give it a second look. What Is Needed The following list of tasks and sub-projects represents something of an amalgam of various TODO lists and user requests. Ongoing Non-Programmer Tasks Many people who are involved in FreeBSD are not programmers. The Project includes documentation writers, Web designers, and support people. All that these people need to contribute is an investment of time and a willingness to learn. Read through the FAQ and Handbook periodically. If anything is badly explained, out of date or even just completely wrong, let us know. Even better, send us a fix (SGML is not difficult to learn, but there is no objection to ASCII submissions). Help translate FreeBSD documentation into your native language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date. First take a look at the Translations FAQ in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this — as a volunteer, you can do as much or as little translation as you desire. Once someone begins translating, others almost always join the effort. If you only have the time or energy to translate one part of the documentation, please translate the installation instructions. Read the &a.questions; and &ng.misc; occasionally (or even regularly). It can be very satisfying to share your expertise and help people solve their problems; sometimes you may even learn something new yourself! These forums can also be a source of ideas for things to work on. Ongoing Programmer Tasks Most of the tasks listed here require either a considerable investment of time, or an in-depth knowledge of the FreeBSD kernel, or both. However, there are also many useful tasks which are suitable for weekend hackers. If you run FreeBSD-CURRENT and have a good Internet connection, there is a machine current.FreeBSD.org which builds a full release once a day—every now and again, try to install the latest release from it and report any failures in the process. Read the &a.bugs;. There might be a problem you can comment constructively on or with patches you can test. Or you could even try to fix one of the problems yourself. If you know of any bug fixes which have been successfully applied to -CURRENT but have not been merged into -STABLE after a decent interval (normally a couple of weeks), send the committer a polite reminder. Move contributed software to src/contrib in the source tree. Make sure code in src/contrib is up to date. Build the source tree (or just part of it) with extra warnings enabled and clean up the warnings. Fix warnings for ports which do deprecated things like using gets() or including malloc.h. If you have contributed any ports, send your patches back to the original authors (this will make your life easier when they bring out the next version). Get copies of formal standards like &posix;. You can get some links about these standards at the FreeBSD C99 & POSIX Standards Conformance Project web site. Compare FreeBSD's behavior to that required by the standard. If the behavior differs, particularly in subtle or obscure corners of the specification, send in a PR about it. If you are able, figure out how to fix it and include a patch in the PR. If you think the standard is wrong, ask the standards body to consider the question. Suggest further tasks for this list! Work through the PR Database problem reports database The FreeBSD PR list shows all the current active problem reports and requests for enhancement that have been submitted by FreeBSD users. The PR database includes both programmer and non-programmer tasks. Look through the open PRs, and see if anything there takes your interest. Some of these might be very simple tasks that just need an extra pair of eyes to look over them and confirm that the fix in the PR is a good one. Others might be much more complex, or might not even have a fix included at all. Start with the PRs that have not been assigned to anyone else. If a PR is assigned to someone else, but it looks like something you can handle, email the person it is assigned to and ask if you can work on it—they might already have a patch ready to be tested, or further ideas that you can discuss with them. How to Contribute Contributions to the system generally fall into one or more of the following 5 categories: Bug Reports and General Commentary An idea or suggestion of general technical interest should be mailed to the &a.hackers;. Likewise, people with an interest in such things (and a tolerance for a high volume of mail!) may subscribe to the &a.hackers;. See The FreeBSD Handbook for more information about this and other mailing lists. If you find a bug or are submitting a specific change, please report it using the &man.send-pr.1; program or its WEB-based equivalent. Try to fill-in each field of the bug report. Unless they exceed 65KB, include any patches directly in the report. If the patch is suitable to be applied to the source tree put [PATCH] in the synopsis of the report. When including patches, do not use cut-and-paste because cut-and-paste turns tabs into spaces and makes them unusable. Consider compressing patches and using &man.uuencode.1; if they exceed 20KB. After filing a report, you should receive confirmation along with a tracking number. Keep this tracking number so that you can update us with details about the problem by sending mail to FreeBSD-gnats-submit@FreeBSD.org. Use the number as the message subject, e.g. "Re: kern/3377". Additional information for any bug report should be submitted this way. If you do not receive confirmation in a timely fashion (3 days to a week, depending on your email connection) or are, for some reason, unable to use the &man.send-pr.1; command, then you may ask someone to file it for you by sending mail to the &a.bugs;. See also this + url="&url.articles.problem-reports;/article.html">this article on how to write good problem reports. Changes to the Documentation documentation submissions Changes to the documentation are overseen by the &a.doc;. Please look at the FreeBSD Documentation Project Primer for complete instructions. Send submissions and changes (even small ones are welcome!) using &man.send-pr.1; as described in Bug Reports and General Commentary. Changes to Existing Source Code FreeBSD-CURRENT An addition or change to the existing source code is a somewhat trickier affair and depends a lot on how far out of date you are with the current state of FreeBSD development. There is a special on-going release of FreeBSD known as FreeBSD-CURRENT which is made available in a variety of ways for the convenience of developers working actively on the system. See The FreeBSD Handbook for more information about getting and using FreeBSD-CURRENT. Working from older sources unfortunately means that your changes may sometimes be too obsolete or too divergent for easy re-integration into FreeBSD. Chances of this can be minimized somewhat by subscribing to the &a.announce; and the &a.current; lists, where discussions on the current state of the system take place. Assuming that you can manage to secure fairly up-to-date sources to base your changes on, the next step is to produce a set of diffs to send to the FreeBSD maintainers. This is done with the &man.diff.1; command. The preferred &man.diff.1; format for submitting patches is the unified output format generated by diff -u. However, for patches that substantially change a region of code, a context output format diff generated by diff -c may be more readable and thus preferable. diff For example: &prompt.user; diff -c oldfile newfile or &prompt.user; diff -c -r olddir newdir would generate such a set of context diffs for the given source file or directory hierarchy. Likewise, &prompt.user; diff -u oldfile newfile or &prompt.user; diff -u -r olddir newdir would do the same, except in the unified diff format. See the manual page for &man.diff.1; for more details. Once you have a set of diffs (which you may test with the &man.patch.1; command), you should submit them for inclusion with FreeBSD. Use the &man.send-pr.1; program as described in Bug Reports and General Commentary. Do not just send the diffs to the &a.hackers; or they will get lost! We greatly appreciate your submission (this is a volunteer project!); because we are busy, we may not be able to address it immediately, but it will remain in the PR database until we do. Indicate your submission by including [PATCH] in the synopsis of the report. uuencode If you feel it appropriate (e.g. you have added, deleted, or renamed files), bundle your changes into a tar file and run the &man.uuencode.1; program on it. Archives created with &man.shar.1; are also welcome. If your change is of a potentially sensitive nature, e.g. you are unsure of copyright issues governing its further distribution or you are simply not ready to release it without a tighter review first, then you should send it to &a.core; directly rather than submitting it with &man.send-pr.1;. The &a.core; reaches a much smaller group of people who do much of the day-to-day work on FreeBSD. Note that this group is also very busy and so you should only send mail to them where it is truly necessary. Please refer to &man.intro.9; and &man.style.9; for some information on coding style. We would appreciate it if you were at least aware of this information before submitting code. New Code or Major Value-Added Packages In the case of a significant contribution of a large body work, or the addition of an important new feature to FreeBSD, it becomes almost always necessary to either send changes as uuencoded tar files or upload them to a web or FTP site for other people to access. If you do not have access to a web or FTP site, ask on an appropriate FreeBSD mailing list for someone to host the changes for you. When working with large amounts of code, the touchy subject of copyrights also invariably comes up. Acceptable copyrights for code included in FreeBSD are: BSD copyright The BSD copyright. This copyright is most preferred due to its no strings attached nature and general attractiveness to commercial enterprises. Far from discouraging such commercial use, the FreeBSD Project actively encourages such participation by commercial interests who might eventually be inclined to invest something of their own into FreeBSD. GPLGNU General Public License GNU General Public License The GNU General Public License, or GPL. This license is not quite as popular with us due to the amount of extra effort demanded of anyone using the code for commercial purposes, but given the sheer quantity of GPL'd code we currently require (compiler, assembler, text formatter, etc) it would be silly to refuse additional contributions under this license. Code under the GPL also goes into a different part of the tree, that being /sys/gnu or /usr/src/gnu, and is therefore easily identifiable to anyone for whom the GPL presents a problem. Contributions coming under any other type of copyright must be carefully reviewed before their inclusion into FreeBSD will be considered. Contributions for which particularly restrictive commercial copyrights apply are generally rejected, though the authors are always encouraged to make such changes available through their own channels. To place a BSD-style copyright on your work, include the following text at the very beginning of every source code file you wish to protect, replacing the text between the %% with the appropriate information: Copyright (c) %%proper_years_here%% %%your_name_here%%, %%your_state%% %%your_zip%%. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY %%your_name_here%% ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL %%your_name_here%% BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. $Id$ For your convenience, a copy of this text can be found in /usr/share/examples/etc/bsd-style-copyright. Money, Hardware or Internet Access We are always very happy to accept donations to further the cause of the FreeBSD Project and, in a volunteer effort like ours, a little can go a long way! Donations of hardware are also very important to expanding our list of supported peripherals since we generally lack the funds to buy such items ourselves. <anchor id="donations">Donating Funds The FreeBSD Foundation is a non-profit, tax-exempt foundation established to further the goals of the FreeBSD Project. As a 501(c)3 entity, the Foundation is generally exempt from US federal income tax as well as Colorado State income tax. Donations to a tax-exempt entity are often deductible from taxable federal income. Donations may be sent in check form to:
The FreeBSD Foundation 7321 Brockway Dr. Boulder, CO 80303 USA
The FreeBSD Foundation is now able to accept donations through the web with PayPal. To place a donation, please visit the Foundation web site. More information about the FreeBSD Foundation can be found in The FreeBSD Foundation -- an Introduction. To contact the Foundation by email, write to bod@FreeBSDFoundation.org. Donating Hardware donations The FreeBSD Project happily accepts donations of hardware that it can find good use for. If you are interested in donating hardware, please contact the Donations Liaison Office. Donating Internet Access We can always use new mirror sites for FTP, WWW or cvsup. If you would like to be such a mirror, please see the Mirroring FreeBSD article for more information.
diff --git a/en_US.ISO8859-1/articles/dialup-firewall/article.sgml b/en_US.ISO8859-1/articles/dialup-firewall/article.sgml index a007de13bf..66bf36dd46 100644 --- a/en_US.ISO8859-1/articles/dialup-firewall/article.sgml +++ b/en_US.ISO8859-1/articles/dialup-firewall/article.sgml @@ -1,318 +1,318 @@ %articles.ent; ]>
Dialup firewalling with FreeBSD Marc Silver
marcs@draenor.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.general; This article documents how to set up a firewall using a PPP dialup with FreeBSD and IPFW, and specifically with firewalling over a dialup with a dynamically assigned IP address. This document does not include information on setting up an initial PPP connection. For more information on setting up a PPP connection, consult the &man.ppp.8; manual page. Preface Dialup Firewalling with FreeBSD This document outlines the steps required to set up firewalling with FreeBSD when an IP address is assigned dynamically by your ISP. While every effort has been made to make this document as informative and correct as possible, you are welcome to mail any corrections, comments or suggestions to the author at marcs@draenor.org. Kernel Options In order to use IPFW, support for it must be compiled into the kernel. For more information on how to recompile the kernel, please see the kernel configuration + url="&url.books.handbook;/kernelconfig.html">kernel configuration section in the Handbook. The following options must be added into your kernel configuration file for IPFW support: options IPFIREWALL Enables the kernel firewall code. This document assumes that you are running &os; 5.X. Users running &os; 4.X will need to recompile their kernels with IPFW2 support. &os; 4.X users should consult the &man.ipfw.8; manual page for more information on using IPFW2 on their systems, and should pay particular attention to the USING IPFW2 IN FreeBSD-STABLE section. options IPFIREWALL_VERBOSE Sends logged packets to the system logger. options IPFIREWALL_VERBOSE_LIMIT=500 Limits the number of times a matching entry may be logged. This allows you to log firewall activity without the risk of syslog flooding in the event of a denial of service attack. 500 is a reasonable number to use, but may be adjusted based on your requirements. Once the kernel recompile has been completed, do not reboot your system. Doing so may result in you being locked out of your own system. You must only reboot once the ruleset is in place and all the relevant configuration files have been updated. Changing <filename>/etc/rc.conf</filename> to load the firewall /etc/rc.conf needs to be slightly modified in order to tell the system about the firewall and to specify the location for our rules file. Add the following lines to /etc/rc.conf: firewall_enable="YES" firewall_script="/etc/firewall/fwrules" For more information on the functions of these statements take a look at /etc/defaults/rc.conf and read &man.rc.conf.5; Enable PPP's network address translation In order to allow clients on your network to connect via your gateway, you will need to enable PPP's network address translation (NAT). In order to use PPP's NAT functions, add the following lines to /etc/rc.conf: ppp_enable="YES" ppp_mode="auto" ppp_nat="YES" ppp_profile="your_profile" Take care to change your_profile to the name of your own dialup profile. The rule set for the firewall This is the point where we define the firewall rules for your system. The ruleset that we're about to describe is a generic template for most dialup users. While it will not suit the exact needs of every user, it provides you with a basic idea of how IPFW works and should be fairly easy to customize. First, let's start with the basics of closed firewalling. Closed firewalling is based on the idea that everything is denied by default. The system administrator may then explicitly add rules for traffic that he or she would like to allow. Rules should be in the order of allow first, and then deny. The premise is that you add the rules for everything you would like to allow, and then everything else is automatically denied. Following that, let's create the directory where we will store our firewall rules. In this example, we'll use /etc/firewall. Change into the directory and edit the file fwrules as we specified in rc.conf. Please note that you can change this filename to anything you wish. This guide merely gives an example of a filename you may want to use. Now, let's look at a nicely commented sample firewall file. # Define the firewall command (as in /etc/rc.firewall) for easy # reference. Helps to make it easier to read. fwcmd="/sbin/ipfw" # Define our outside interface. With userland-ppp this # defaults to tun0. oif="tun0" # Define our inside interface. This is usually your network # card. Be sure to change this to match your own network # interface. iif="fxp0" # Force a flushing of the current rules before we reload. $fwcmd -f flush # Check the state of all packets. $fwcmd add check-state # Stop spoofing on the outside interface. $fwcmd add deny ip from any to any in via $oif not verrevpath # Allow all connections that we initiate, and keep their state. # but deny established connections that don't have a dynamic rule. $fwcmd add allow ip from me to any out via $oif keep-state $fwcmd add deny tcp from any to any established in via $oif # Allow all connections within our network. $fwcmd add allow ip from any to any via $iif # Allow all local traffic. $fwcmd add allow all from any to any via lo0 $fwcmd add deny all from any to 127.0.0.0/8 $fwcmd add deny ip from 127.0.0.0/8 to any # Allow internet users to connect to the port 22 and 80. # This example specifically allows connections to the sshd and a # webserver. $fwcmd add allow tcp from any to me dst-port 22,80 in via $oif setup keep-state # Allow ICMP packets: remove type 8 if you don't want your host # to be pingable. $fwcmd add allow icmp from any to any via $oif icmptypes 0,3,8,11,12 # Deny and log all the rest. $fwcmd add deny log ip from any to any You now have a fully functional firewall that only allows connections to ports 22 and 80 and will log any other connection attempts. You may now safely reboot and the firewall should be automatically started and the ruleset loaded. If you find this incorrect in any way or experience any problems, or have any suggestions to improve this page, please email me. Questions I get messages like limit 500 reached on entry 2800 and after that I my machine stops logging denied packets that match that rule number. Is my firewall still working? This merely means that the maximum logging count for the rule has been reached. The rule itself is still working, but it will no longer log until such time as you reset the logging counters. An example of how to clear your counters can be found below: &prompt.root; ipfw resetlog Alternatively, you may increase the log limit in your kernel configuration with the option as described above. You may also change this limit (without recompiling your kernel and having to reboot) by using the net.inet.ip.fw.verbose_limit &man.sysctl.8; value. There must be something wrong. I followed your instructions to the letter and now I am locked out. This tutorial assumes that you are running userland-ppp, therefore the supplied rule set operates on the tun0 interface, which corresponds to the first connection made with &man.ppp.8; (a.k.a. user-ppp). Additional connections would use tun1, tun2 and so on. You should also note that &man.pppd.8; uses the ppp0 interface instead, so if you start the connection with &man.pppd.8; you must substitute tun0 for ppp0. A quick way to edit the firewall rules to reflect this change is shown below. The original rule set is backed up as fwrules_tun0. &prompt.user; cd /etc/firewall /etc/firewall&prompt.user; su Password: /etc/firewall&prompt.root; mv fwrules fwrules_tun0 /etc/firewall&prompt.root; cat fwrules_tun0 | sed s/tun0/ppp0/g > fwrules To know whether you are currently using &man.ppp.8; or &man.pppd.8; you can examine the output of &man.ifconfig.8; once the connection is up. E.g., for a connection made with &man.pppd.8; you would see something like this (showing only the relevant lines): &prompt.user; ifconfig (skipped...) ppp0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524 inet xxx.xxx.xxx.xxx --> xxx.xxx.xxx.xxx netmask 0xff000000 (skipped...) On the other hand, for a connection made with &man.ppp.8; (user-ppp) you should see something similar to this: &prompt.user; ifconfig (skipped...) ppp0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 (skipped...) tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524 (IPv6 stuff skipped...) inet xxx.xxx.xxx.xxx --> xxx.xxx.xxx.xxx netmask 0xffffff00 Opened by PID xxxxx (skipped...)
diff --git a/en_US.ISO8859-1/articles/fonts/article.sgml b/en_US.ISO8859-1/articles/fonts/article.sgml index ae33695464..6130925e28 100644 --- a/en_US.ISO8859-1/articles/fonts/article.sgml +++ b/en_US.ISO8859-1/articles/fonts/article.sgml @@ -1,979 +1,979 @@ %articles.ent; ]>
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 .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 .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 (.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 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 & + url="http://www.ora.com/">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 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 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 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 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 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 (.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: 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? Can xditview and devX?? devices be set up 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 e514e59254..18746cb746 100644 --- a/en_US.ISO8859-1/articles/formatting-media/article.sgml +++ b/en_US.ISO8859-1/articles/formatting-media/article.sgml @@ -1,630 +1,630 @@ %articles.ent; ]>
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 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 &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 + url="http://stampede.cs.berkeley.edu/ccd/">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 + 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/freebsd-questions/article.sgml b/en_US.ISO8859-1/articles/freebsd-questions/article.sgml index 931959097c..820a729d42 100644 --- a/en_US.ISO8859-1/articles/freebsd-questions/article.sgml +++ b/en_US.ISO8859-1/articles/freebsd-questions/article.sgml @@ -1,627 +1,627 @@ %articles.ent; ]>
How to get best results from the FreeBSD-questions mailing list Greg Lehey
grog@FreeBSD.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.microsoft; &tm-attrib.netscape; &tm-attrib.opengroup; &tm-attrib.qualcomm; &tm-attrib.general; This document provides useful information for people looking to prepare an e-mail to the FreeBSD-questions mailing list. Advice and hints are given that will maximize the chance that the reader will receive useful replies. This document is regularly posted to the FreeBSD-questions mailing list. Introduction FreeBSD-questions is a mailing list maintained by the FreeBSD project to help people who have questions about the normal use of FreeBSD. Another group, FreeBSD-hackers, discusses more advanced questions such as future development work. The term hacker has nothing to do with breaking into other people's computers. The correct term for the latter activity is cracker, but the popular press has not found out yet. The FreeBSD hackers disapprove strongly of cracking security, and have nothing to do with it. For a longer description of hackers, see Eric Raymond's How To Become A Hacker This is a regular posting aimed to help both those seeking advice from FreeBSD-questions (the newcomers), and also those who answer the questions (the hackers). Inevitably there is some friction, which stems from the different viewpoints of the two groups. The newcomers accuse the hackers of being arrogant, stuck-up, and unhelpful, while the hackers accuse the newcomers of being stupid, unable to read plain English, and expecting everything to be handed to them on a silver platter. Of course, there is an element of truth in both these claims, but for the most part these viewpoints come from a sense of frustration. In this document, I would like to do something to relieve this frustration and help everybody get better results from FreeBSD-questions. In the following section, I recommend how to submit a question; after that, we will look at how to answer one. How to subscribe to FreeBSD-questions FreeBSD-questions is a mailing list, so you need mail access. Point your WWW browser to FreeBSD-question Info Page. In the section titled Subscribing to freebsd-questions fill in the Your email address field; the other fields are optional. The password fields in the subscription form provide only mild security, but should prevent others from messing with your subscription. Do not use a valuable password as it will occasionally be emailed back to you in cleartext. You will receive a confirmation message from mailman; follow the included instructions to complete your subscription. Finally, when you get the Welcome message from mailman telling you the details of the list and subscription area password, please save it. If you ever should want to leave the list, you will need the information there. See the next section for more details. How to unsubscribe from FreeBSD-questions When you subscribed to FreeBSD-questions, you got a welcome message from mailman. In this message, amongst other things, it told you how to unsubscribe. Here is a typical message: Welcome to the freebsd-questions@freebsd.org mailing list! To post to this list, send your email to: freebsd-questions@freebsd.org General information about the mailing list is at: http://lists.freebsd.org/mailman/listinfo/freebsd-questions If you ever want to unsubscribe or change your options (e.g., switch to or from digest mode, change your password, etc.), visit your subscription page at: http://lists.freebsd.org/mailman/options/freebsd-questions/grog%40lemsi.de You can also make such adjustments via email by sending a message to: freebsd-questions-request@freebsd.org with the word `help' in the subject or body (don't include the quotes), and you will get back a message with instructions. You must know your password to change your options (including changing the password, itself) or to unsubscribe. It is: 12345 Normally, Mailman will remind you of your freebsd.org mailing list passwords once every month, although you can disable this if you prefer. This reminder will also include instructions on how to unsubscribe or change your account options. There is also a button on your options page that will email your current password to you. From the URL specified in your Welcome message you may visit the Account management page and enter a request to Unsubscribe you from FreeBSD-questions mailing list. A confirmation message will be sent to you from mailman; follow the included instructions to finish unsubscribing. If you have done this, and you still can not figure out what is going on, send a message to freebsd-questions-request@FreeBSD.org, and they will sort things out for you. Do not send a message to FreeBSD-questions: they can not help you. Should I ask <literal>-questions</literal> or <literal>-hackers</literal>? Two mailing lists handle general questions about FreeBSD, FreeBSD-questions and FreeBSD-hackers. In some cases, it is not really clear which group you should ask. The following criteria should help for 99% of all questions, however: If the question is of a general nature, ask FreeBSD-questions. Examples might be questions about installing FreeBSD or the use of a particular &unix; utility. If you think the question relates to a bug, but you are not sure, or you do not know how to look for it, send the message to FreeBSD-questions. If the question relates to a bug, and you are sure that it is a bug (for example, you can pinpoint the place in the code where it happens, and you maybe have a fix), then send the message to FreeBSD-hackers. If the question relates to enhancements to FreeBSD, and you can make suggestions about how to implement them, then send the message to FreeBSD-hackers. There are also a number of other specialized mailing lists, for example FreeBSD-isp, which caters to the interests of ISPs (Internet Service Providers) who run FreeBSD. If you happen to be an ISP, this does not mean you should automatically send your questions to FreeBSD-isp. The criteria above still apply, and it is in your interest to stick to them, since you are more likely to get good results that way. Before submitting a question You can (and should) do some things yourself before asking a question on one of the mailing lists: Try solving the problem on your own. If you post a question which shows that you have tried to solve the problem, your question will generally attract more positive attention from people reading it. Trying to solve the problem yourself will also enhance your understanding of FreeBSD, and will eventually let you use your knowledge to help others by answering questions posted to the mailing lists. Read the manual pages, and the FreeBSD documentation (either installed in /usr/doc or accessible via WWW at - ), especially the - handbook - and the FAQ. + ), especially the + handbook + and the FAQ. Browse and/or search the archives for the mailing list, to see if your question or a similar one has been asked (and possibly answered) on the list. You can browse and/or search the mailing list archives - at - and + at + and respectively. This can be done at other WWW sites as well, for example - at . + at . - Use a search engine such as Google - or Yahoo to find answers to your question. + Use a search engine such as Google + or Yahoo to find answers to your question. Google even has a BSD-specific search interface. + url="http://www.google.com/bsd">BSD-specific search interface. How to submit a question When submitting a question to FreeBSD-questions, consider the following points: Remember that nobody gets paid for answering a FreeBSD question. They do it of their own free will. You can influence this free will positively by submitting a well-formulated question supplying as much relevant information as possible. You can influence this free will negatively by submitting an incomplete, illegible, or rude question. It is perfectly possible to send a message to FreeBSD-questions and not get an answer even if you follow these rules. It is much more possible to not get an answer if you do not. In the rest of this document, we will look at how to get the most out of your question to FreeBSD-questions. Not everybody who answers FreeBSD questions reads every message: they look at the subject line and decide whether it interests them. Clearly, it is in your interest to specify a subject. FreeBSD problem or Help are not enough. If you provide no subject at all, many people will not bother reading it. If your subject is not specific enough, the people who can answer it may not read it. Format your message so that it is legible, and PLEASE DO NOT SHOUT!!!!!. We appreciate that a lot of people do not speak English as their first language, and we try to make allowances for that, but it is really painful to try to read a message written full of typos or without any line breaks. Do not underestimate the effect that a poorly formatted mail message has, not just on the FreeBSD-questions mailing list. Your mail message is all people see of you, and if it is poorly formatted, one line per paragraph, badly spelt, or full of errors, it will give people a poor impression of you. A lot of badly formatted messages come from bad mailers or badly configured mailers. The following mailers are known to send out badly formatted messages without you finding out about them: cc:Mail &eudora; exmh µsoft; Exchange µsoft; Internet Mail µsoft; &outlook; &netscape; As you can see, the mailers in the Microsoft world are frequent offenders. If at all possible, use a &unix; mailer. If you must use a mailer under Microsoft environments, make sure it is set up correctly. Try not to use MIME: a lot of people use mailers which do not get on very well with MIME. Make sure your time and time zone are set correctly. This may seem a little silly, since your message still gets there, but many of the people you are trying to reach get several hundred messages a day. They frequently sort the incoming messages by subject and by date, and if your message does not come before the first answer, they may assume they missed it and not bother to look. Do not include unrelated questions in the same message. Firstly, a long message tends to scare people off, and secondly, it is more difficult to get all the people who can answer all the questions to read the message. Specify as much information as possible. This is a difficult area, and we need to expand on what information you need to submit, but here is a start: In nearly every case, it is important to know the version of FreeBSD you are running. This is particularly the case for FreeBSD-CURRENT, where you should also specify the date of the sources, though of course you should not be sending questions about -CURRENT to FreeBSD-questions. With any problem which could be hardware related, tell us about your hardware. In case of doubt, assume it is possible that it is hardware. What kind of CPU are you using? How fast? What motherboard? How much memory? What peripherals? There is a judgement call here, of course, but the output of the &man.dmesg.8; command can frequently be very useful, since it tells not just what hardware you are running, but what version of FreeBSD as well. If you get error messages, do not say I get error messages, say (for example) I get the error message 'No route to host'. If your system panics, do not say My system panicked, say (for example) my system panicked with the message 'free vnode isn't'. If you have difficulty installing FreeBSD, please tell us what hardware you have. In particular, it is important to know the IRQs and I/O addresses of the boards installed in your machine. If you have difficulty getting PPP to run, describe the configuration. Which version of PPP do you use? What kind of authentication do you have? Do you have a static or dynamic IP address? What kind of messages do you get in the log file? A lot of the information you need to supply is the output of programs, such as &man.dmesg.8;, or console messages, which usually appear in /var/log/messages. Do not try to copy this information by typing it in again; it is a real pain, and you are bound to make a mistake. To send log file contents, either make a copy of the file and use an editor to trim the information to what is relevant, or cut and paste into your message. For the output of programs like &man.dmesg.8;, redirect the output to a file and include that. For example, &prompt.user; dmesg > /tmp/dmesg.out This redirects the information to the file /tmp/dmesg.out. If you do all this, and you still do not get an answer, there could be other reasons. For example, the problem is so complicated that nobody knows the answer, or the person who does know the answer was offline. If you do not get an answer after, say, a week, it might help to re-send the message. If you do not get an answer to your second message, though, you are probably not going to get one from this forum. Resending the same message again and again will only make you unpopular. To summarize, let's assume you know the answer to the following question (yes, it is the same one in each case). You choose which of these two questions you would be more prepared to answer: Message 1 Subject: HELP!!?!?? I just can't get hits damn silly FereBSD system to workd, and Im really good at this tsuff, but I have never seen anythign sho difficult to install, it jst wont work whatever I try so why don't you guys tell me what I doing wrong. Message 2 Subject: Problems installing FreeBSD I've just got the FreeBSD 2.1.5 CDROM from Walnut Creek, and I'm having a lot of difficulty installing it. I have a 66 MHz 486 with 16 MB of memory and an Adaptec 1540A SCSI board, a 1.2GB Quantum Fireball disk and a Toshiba 3501XA CDROM drive. The installation works just fine, but when I try to reboot the system, I get the message Missing Operating System. How to follow up to a question Often you will want to send in additional information to a question you have already sent. The best way to do this is to reply to your original message. This has three advantages: You include the original message text, so people will know what you are talking about. Do not forget to trim unnecessary text out, though. The text in the subject line stays the same (you did remember to put one in, did you not?). Many mailers will sort messages by subject. This helps group messages together. The message reference numbers in the header will refer to the previous message. Some mailers, such as mutt, can thread messages, showing the exact relationships between the messages. How to answer a question Before you answer a question to FreeBSD-questions, consider: A lot of the points on submitting questions also apply to answering questions. Read them. Has somebody already answered the question? The easiest way to check this is to sort your incoming mail by subject: then (hopefully) you will see the question followed by any answers, all together. If somebody has already answered it, it does not automatically mean that you should not send another answer. But it makes sense to read all the other answers first. Do you have something to contribute beyond what has already been said? In general, Yeah, me too answers do not help much, although there are exceptions, like when somebody is describing a problem he is having, and he does not know whether it is his fault or whether there is something wrong with the hardware or software. If you do send a me too answer, you should also include any further relevant information. Are you sure you understand the question? Very frequently, the person who asks the question is confused or does not express himself very well. Even with the best understanding of the system, it is easy to send a reply which does not answer the question. This does not help: you will leave the person who submitted the question more frustrated or confused than ever. If nobody else answers, and you are not too sure either, you can always ask for more information. Are you sure your answer is correct? If not, wait a day or so. If nobody else comes up with a better answer, you can still reply and say, for example, I do not know if this is correct, but since nobody else has replied, why don't you try replacing your ATAPI CDROM with a frog?. Unless there is a good reason to do otherwise, reply to the sender and to FreeBSD-questions. Many people on the FreeBSD-questions are lurkers: they learn by reading messages sent and replied to by others. If you take a message which is of general interest off the list, you are depriving these people of their information. Be careful with group replies; lots of people send messages with hundreds of CCs. If this is the case, be sure to trim the Cc: lines appropriately. Include relevant text from the original message. Trim it to the minimum, but do not overdo it. It should still be possible for somebody who did not read the original message to understand what you are talking about. Use some technique to identify which text came from the original message, and which text you add. I personally find that prepending > to the original message works best. Leaving white space after the > and leave empty lines between your text and the original text both make the result more readable. Put your response in the correct place (after the text to which it replies). It is very difficult to read a thread of responses where each reply comes before the text to which it replies. Most mailers change the subject line on a reply by prepending a text such as Re: . If your mailer does not do it automatically, you should do it manually. If the submitter did not abide by format conventions (lines too long, inappropriate subject line), please fix it. In the case of an incorrect subject line (such as HELP!!??), change the subject line to (say) Re: Difficulties with sync PPP (was: HELP!!??). That way other people trying to follow the thread will have less difficulty following it. In such cases, it is appropriate to say what you did and why you did it, but try not to be rude. If you find you can not answer without being rude, do not answer. If you just want to reply to a message because of its bad format, just reply to the submitter, not to the list. You can just send him this message in reply, if you like.
diff --git a/en_US.ISO8859-1/articles/mh/article.sgml b/en_US.ISO8859-1/articles/mh/article.sgml index ddafc966e8..a8a25c4000 100644 --- a/en_US.ISO8859-1/articles/mh/article.sgml +++ b/en_US.ISO8859-1/articles/mh/article.sgml @@ -1,815 +1,815 @@ %articles.ent; ]>
An <application>MH</application> Primer Matt Midboe
matt@garply.com
v1.0, 16 January 1996 &tm-attrib.freebsd; &tm-attrib.opengroup; &tm-attrib.general; This document contains an introduction to using MH on FreeBSD Introduction MH started back in 1977 at the RAND Corporation, where the initial philosophies behind MH were developed. MH is not so much a monolithic email program but a philosophy about how best to develop tools for reading email. The MH developers have done a great job adhering to the KISS principle: Keep It Simple Stupid. Rather than have one large program for reading, sending and handling email they have written specialized programs for each part of your email life. One might liken MH to the specialization that one finds in insects and nature. Each tool in MH does one thing, and does it very well. Beyond just the various tools that one uses to handle their email MH has done an excellent job keeping the configuration of each of these tools consistent and uniform. In fact, if you are not quite sure how something is supposed to work or what the arguments for some command are supposed to be, then you can generally guess and be right. Each MH command is consistent about how it handles reading the configuration files and how it takes arguments on the command line. One useful thing to remember is that you can always add a to the command to have it display the options for that command. The first thing that you need to do is to make sure that you have installed the MH package on your FreeBSD machine. If you installed from CDROM you should be able to execute the following to load MH: &prompt.root; pkg_add /cdrom/packages/mh-6.8.3.tgz You will notice that it created a /usr/local/lib/mh directory for you as well as adding several binaries to the /usr/local/bin directory. If you would prefer to compile it yourself then you can anonymous ftp it from ftp.ics.uci.edu or louie.udel.edu. + url="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu or louie.udel.edu. This primer is not a full comprehensive explanation of how MH works. This is just intended to get you started on the road to happier, faster mail reading. You should read the manual pages for the various commands. You might also want to read the comp.mail.mh newsgroup. Also you + url="news:comp.mail.mh">comp.mail.mh newsgroup. Also you can read the FAQ for + url="http://www.faqs.org/faqs/mail/mh-faq/">FAQ for MH. The best resource for MH is Jerry Peek's + url="http://www.ics.uci.edu/~mh/book/">Jerry Peek's MH & nmh: Email for Users & Programmers. Reading Mail This section covers how to use inc, show, scan, next, prev, rmm, rmf, and msgchk. One of the best things about MH is the consistent interface between programs. One thing to keep in mind when using these commands is how to specify message lists. In the case of inc this does not really make any sense but with commands like show it is useful to know. A message list can consist of something like 23 20 16 which will act on messages 23, 20 and 16. This is fairly simple but you can do more useful things like 23-30 which will act on all the messages between 23 and 30. You can also specify something like cur:10 which will act on the current message and the next 9 messages. The cur, last, and first messages are special messages that refer to the current, last or first message in the folder. <command>inc</command>, <command>msgchk</command>—read in your new email or check it If you just type in inc and hit return you will be well on your way to getting started with MH. The first time you run inc it will set up your account to use all the MH defaults and ask you about creating a Mail directory under your HOME directory. If you have mail waiting to be downloaded you will see something that looks like: 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa This is the same thing you will see from a scan (see ). If you just run inc with no arguments it will look on your computer for email that is supposed to be coming to you. A lot of people like to use POP for grabbing their email. MH can do POP to grab your email. You will need to give inc a few command line arguments. &prompt.user; inc -host mail.pop.org -user username -norpop That tells inc to go to mail.pop.org to download your email, and that your username on their system is username. The option tells inc to use plain POP3 for downloading your email. MH has support for a few different dialects of POP. More than likely you will never ever need to use them though. While you can do more complex things with inc such as audit files and scan format files this will get you going. The msgchk command is used to get information on whether or not you have new email. msgchk takes the same and options that inc takes. <command>show</command>, <command>next</command> and <command>prev</command>—displaying and moving through email show is to show a letter in your current folder. Like inc, show is a fairly straightforward command. If you just type show and hit return then it displays the current message. You can also give specific message numbers to show: &prompt.user; show 32 45 56 This would display message numbers 32, 45 and 56 right after each other. Unless you change the default behavior show basically just does a more on the email message. next is used to move onto the next message and prev will go to the previous message. Both commands have an implied show command so that when you go to the next message it automatically displays it. <command>scan</command>—shows you a scan of your messages scan will display a brief listing of the messages in your current folder. This is an example of what the scan command will give you. 30+ 01/16 Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea 32 01/16 Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa Like just about everything in MH this display is very configurable. This is the typical default display. It gives you the message number, the date on the email, the sender, the subject line, and a sentence fragment from the very beginning of the email if it can fit it. The + means that message is the current message, so if you do a show it will display that message. One useful option for scan is the option. This will list your messages with the highest message number first and lowest message number last. Another useful option with scan is to have it read from a file. If you want to scan your incoming mailbox on FreeBSD without having to inc it you can do scan -file /var/mail/username. This can be used with any file that is in the mbox format. <command>rmm</command> and <command>rmf</command>—remove the current message or folder rmm is used to remove a mail message. The default is typically to not actually remove the message but to rename the file to one that is ignored by the MH commands. You will periodically need to go through and physically delete the removed messages. The rmf command is used to remove folders. This does not just rename the files but actually removes the from the hard drive so you should be careful when you use this command. A typical session of reading with MH The first thing that you will want to do is inc your new mail. So at a shell prompt just type in inc and hit return. &prompt.user; inc Incorporating new mail into inbox... 36+ 01/19 Stephen L. Lange Request...<<Please remove me as contact for pind 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl 38 01/19 Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In &prompt.user; This shows you the new email that has been added to your mailbox. So the next thing to do is show the email and move around. &prompt.user; show Received: by sashimi.wwa.com (Smail3.1.29.1 #2) id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) From: "Stephen L. Lange" <stvlange@wwa.com> To: matt@garply.com Subject: Request... Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Please remove me as contact for pindat.com &prompt.user; rmm &prompt.user; next Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 .6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro tocol To: hsu@clinet.fi Cc: hackers@FreeBSD.org Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet boards) In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." <199601182318.AA11772@Sysiphos> X-Mailer: exmh version 1.5omega 10/6/94 Date: Fri, 19 Jan 1996 17:56:40 +0000 From: Matt Thomas <matt@lkg.dec.com> Sender: owner-hackers@FreeBSD.org Precedence: bulk This is due to a typo in pcireg.h (to which I am probably the guilty party). The rmm removed the current message and the next command moved me on to the next message. Now if I wanted to look at ten most recent messages so I could read one of them here is what I would do: &prompt.user; scan last:10 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl 38 01/19 Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In &prompt.user; Then if I wanted to read message number 27 I would do a show 27 and it would be displayed. As you can probably tell from this sample session MH is pretty easy to use and looking through emails and displaying them is fairly intuitive and easy. Folders and Mail Searching Anybody who gets lots of email definitely wants to be able to prioritize, stamp, brief, de-brief, and number their emails in a variety of different ways. MH can do this better than just about anything. One thing that we have not really talked about is the concept of folders. You have undoubtedly come across the folders concept using other email programs. MH has folders too. MH can even do sub-folders of a folder. One thing you should keep in mind with MH is that when you ran inc for the first time and it asked you if it could create a Mail directory it began storing everything in that directory. If you look at that directory you will find a directory named inbox. The inbox directory houses all of your incoming mail that has not been thrown anywhere else. Whenever you create a new folder a new directory is going to be created underneath your MH Mail directory, and messages in that folder are going to be stored in that directory. When a new email message comes, it is thrown into your inbox directory with a file name that is equivalent to the message number. So even if you did not have any of the MH tools to read your email you could still use standard &unix; commands to munge around in those directories and just more your files. It is this simplicity that really gives you a lot of power with what you can do with your email. Just as you can use message lists like 23 16 42 with most MH commands there is a folder option you can specify with just about every MH command. If you do a scan +freebsd it will scan your freebsd folder, and your current folder will be changed to freebsd. If you do a show +freebsd 23 16 42, show is going to switch to your freebsd folder and display messages 23, 16 and 42. So remember that syntax. You will need to make sure you use it to make commands process different folders. Remember you default folder for mail is inbox so doing a folder +inbox should always get you back to your mail. Of course, in MH's infinite flexibility this can be changed but most places have probably left it as inbox. <command>pick</command>—search email that matches certain criteria pick is one of the more complex commands in the MH system. So you might want to read the pick1 man page for a more thorough understanding. At its simplest level you can do something like &prompt.user; pick -search pci 15 42 55 56 57 This will tell pick to look through every single line in every message in your current folder and tell you which message numbers it found the word pci in. You can then show those messages and read them if you wish or rmm them. You would have to specify something like show 15 42 55-57 to display them though. A slightly more useful thing to do is this: &prompt.user; pick -search pci -seq pick 5 hits &prompt.user; show pick This will show you the same messages you just did not have to work as hard to do it. The option is really an abbreviation of and pick is just a sequence which contains the message numbers that matched. You can use sequences with just about any MH command. So you could have done an rmm pick and all those messages would be removed instead. You sequence can be named anything. If you run pick again it will overwrite the old sequence if you use the same name. Doing a pick -search can be a bit more time consuming than just searching for message from someone, or to someone. So pick allows you to use the following predefined search criteria: search based upon who the message is to search based on who is in the Cc: list search for who sent the message search for emails with this subject find emails with a matching date search for any other component in the header. (i.e. to find all emails with a certain reply-to in the header) This allows you to do things like &prompt.user; pick -to freebsd-hackers@FreeBSD.org -seq hackers to get a list of all the email send to the FreeBSD hackers mailing list. pick also allows you to group these criteria in different ways using the following options: … … … … … … These commands allow you to do things like &prompt.user; pick -to freebsd-hackers -or -cc freebsd-hackers That will grab all the email in your inbox that was sent to freebsd-hackers or cc'd to that list. The brace options allow you to group search criteria together. This is sometimes very necessary as in the following example &prompt.user; pick -lbrace -to freebsd-hackers -and -not -cc freebsd-questions -rbrace -and -subject pci Basically this says pick (to freebsd-hackers and not cc'd on freebsd-questions) and the subject is pci. It should look through your folder and find all messages sent to the freebsd-hackers list that are not cc'd to the freebsd-questions list and contain pci in the subject line. Ordinarily you might have to worry about something called operator precedence. Remember in math how you evaluate from left to right and you do multiplication and division first and addition and subtraction second? MH has the same type of rules for pick. It is fairly complex so you might want to study the manual page. This document is just to help you get acquainted with MH. <command>folder</command>, <command>folders</command>, <command>refile</command>—three useful programs for folder maintenance There are three programs which are primarily just for manipulating your folders. The folder program is used to switch between folders, pack them, and list them. At its simplest level you can do a folder +newfolder and you will be switched into newfolder. From there on out all your MH commands like comp, repl, scan, and show will act on that newfolder folder. Sometimes when you are reading and deleting messages you will develop holes in your folders. If you do a scan you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do a folder -pack this will renumber all your messages so that there are no holes. It does not actually delete any messages though. So you may need to periodically go through and physically delete rmm'd messages. If you need statistics on your folders you can do a folders or folder -all to list all your folders, how many messages they have, what the current message is in each one and so on. This line of stats it displays for all your folders is the same one you get when you change to a folder with folder +foldername. A folders command looks like this: Folder # of messages ( range ); cur msg (other files) announce has 1 message ( 1- 1). drafts has no messages. f-hackers has 43 messages ( 1- 43). f-questions has 16 messages ( 1- 16). inbox+ has 35 messages ( 1- 38); cur= 37. lists has 8 messages ( 1- 8). netfuture has 1 message ( 1- 1). out has 31 messages ( 1- 31). personal has 6 messages ( 1- 6). todo has 58 messages ( 1- 58); cur= 1. TOTAL= 199 messages in 13 folders. The refile command is what you use to move messages between folders. When you do something like refile 23 +netfuture message number 23 is moved into the netfuture folder. You could also do something like refile 23 +netfuture/latest which would put message number 23 in a subfolder called latest under the netfuture folder. If you want to keep a message in the current folder and link it you can do a refile -link 23 +netfuture which would keep 23 in your current inbox but also list in your netfuture folder. You are probably beginning to realize some of the really powerful things you can do with MH. Sending Mail Email is a two way street for most people so you want to be able to send something back. The way MH handles sending mail can be a bit difficult to follow at first, but it allows for incredible flexibility. The first thing MH does is to copy a components file into your outgoing email. A components file is basically a skeleton email letter with stuff like the To: and Subject: headers already in it. You are then sent into your editor where you fill in the header information and then type the body of your message below the dashed lines in the message. When you leave the editor, the whatnow program is run. When you are at the What now? prompt you can tell it to send, list, edit, push, and quit. Most of these commands are self-explanatory. So the message sending process involves copying a component file, editing your email, and then telling the whatnow program what to do with your email. <command>comp</command>, <command>forw</command>, <command>reply</command>—compose, forward or reply to a message to someone The comp program has a few useful command line options. The most important one to know right now is the option. When MH is installed the default editor is usually a program called prompter which comes with MH. It is not a very exciting editor and basically just gets the job done. So when you go to compose a message to someone you might want to use comp -editor /usr/bin/vi or comp -editor /usr/local/bin/pico instead. Once you have run comp you are in your editor and you see something that looks like this: To: cc: Subject: -------- You need to put the person you are sending the mail to after the To: line. It works the same way for the other headers also, so you would need to put your subject after the Subject: line. Then you would just put the body of your message after the dashed lines. It may seem a bit simplistic since a lot of email programs have special requesters that ask you for this information but there really is no point to that. Plus this really gives you excellent flexibility. To:freebsd-rave@FreeBSD.org cc: Subject:And on the 8th day God created the FreeBSD core team -------- Wow this is an amazing operating system. Thanks! You can now save this message and exit your editor. You will see the What now? prompt and you can type in send or s and hit return. Then the FreeBSD core team will receive their just rewards. As I mentioned earlier, you can also use other commands at the What now? prompt. For example you can use quit, if you do not want to send the message. The forw command is stunningly similar. The big difference being that the message you are forwarding is automatically included in the outgoing message. When you run forw it will forward your current message. You can always tell it to forward something else by doing something like forw 23 and then message number 23 will be put in your outgoing message instead of the current message. Beyond those small differences forw functions exactly the same as comp. You go through the exact same message sending process. The repl command will reply to the current message, unless you give it a different message to reply to. repl will do its best to go ahead and fill in some of the email headers already. So you will notice that the To: header already has the address of the recipient in there. Also the Subject: line will already be filled in. You then go about the normal message composition process and you are done. One useful command line option to know here is the option. You can use all, to, cc, me after the option to have repl automatically add the various addresses to the Cc: list in the message. You have probably noticed that the original message is not included. This is because most MH setups are configured to do this from the start. <filename>components</filename>, and <filename>replcomps</filename>—components files for <command>comp</command> and <command>repl</command> The components file is usually in /usr/local/lib/mh. You can copy that file into your MH Mail directory and edit to contain what you want it to contain. It is a fairly basic file. You have various email headers at the top, a dashed line and then nothing. The comp command just copies this components file and then edits it. You can add any kind of valid RFC822 header you want. For instance you could have something like this in your components file: To: Fcc: out Subject: X-Mailer: MH 6.8.3 X-Home-Page: http://www.FreeBSD.org/ ------- MH would then copy this components file and throw you into your editor. The components file is fairly simple. If you wanted to have a signature on those messages you would just put your signature in that components file. The replcomps file is a bit more complex. The default replcomps looks like this: %(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ %<(nonnull)%(void(width))%(putaddr To: )\n%>\ %(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ %<(nonnull)%(void(width))%(putaddr cc: )\n%>\ %<{fcc}Fcc: %{fcc}\n%>\ %<{subject}Subject: Re: %{subject}\n%>\ %<{date}In-reply-to: Your message of "\ %<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} %{message-id}%>\n%>\ -------- It is in the same basic format as the components file but it contains quite a few extra formatting codes. The %(lit) command makes room for the address. The %(formataddr) is a function that returns a proper email address. The next part is %< which means if and the {reply-to} means the reply-to field in the original message. So that might be translated this way: %<if {reply-to} the original message has a reply-to then give that to formataddr, %? else {from} take the from address, %? else {sender} take the sender address, %? else {return-path} take the return-path from the original message, %> endif. As you can tell MH formatting can get rather involved. You can probably decipher what most of the other functions and variables mean. All of the information on writing these format strings is in the MH-Format manual page. The really nice thing is that once you have built your customized replcomps file you will not need to touch it again. No other email program really gives you the power and flexibility that MH gives you.
diff --git a/en_US.ISO8859-1/articles/multi-os/article.sgml b/en_US.ISO8859-1/articles/multi-os/article.sgml index ebe8653557..926303aec2 100644 --- a/en_US.ISO8859-1/articles/multi-os/article.sgml +++ b/en_US.ISO8859-1/articles/multi-os/article.sgml @@ -1,752 +1,752 @@ %articles.ent; ]>
Installing and Using FreeBSD With Other Operating Systems Jay Richmond
jayrich@sysc.com
6 August 1996 &tm-attrib.freebsd; &tm-attrib.ibm; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.powerquest; &tm-attrib.general; This document discusses how to make FreeBSD coexist nicely with other popular operating systems such as Linux, &ms-dos;, &os2;, and &windows; 95. Special thanks to: Annelise Anderson andrsn@stanford.edu, Randall Hopper rhh@ct.picker.com, and &a.jkh;. Overview Most people can not fit these operating systems together comfortably without having a larger hard disk, so special information on large EIDE drives is included. Because there are so many combinations of possible operating systems and hard disk configurations, the section may be of the most use to you. It contains descriptions of specific working computer setups that use multiple operating systems. This document assumes that you have already made room on your hard disk for an additional operating system. Any time you repartition your hard drive, you run the risk of destroying the data on the original partitions. However, if your hard drive is completely occupied by DOS, you might find the FIPS utility (included on the FreeBSD CDROM in the \TOOLS directory or via ftp) + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/">ftp) useful. It lets you repartition your hard disk without destroying the data already on it. There is also a commercial program available called &partitionmagic;, which lets you size and delete partitions without consequence. Overview of Boot Managers These are just brief descriptions of some of the different boot managers you may encounter. Depending on your computer setup, you may find it useful to use more than one of them on the same system. Boot Easy This is the default boot manager used with FreeBSD. It has the ability to boot most anything, including BSD, &os2; (HPFS), &windows; 95 (FAT and FAT32), and Linux. Partitions are selected with the function keys. &os2; Boot Manager This will boot FAT, FAT32, HPFS, FFS (FreeBSD), and EXT2 (Linux). Partitions are selected using arrow keys. The &os2; Boot Manager is the only one to use its own separate partition, unlike the others which use the master boot record (MBR). Therefore, it must be installed below the 1024th cylinder to avoid booting problems. It can boot Linux using LILO when it is part of the boot sector, not the MBR. Go to Linux + url="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux HOWTOs on the World Wide Web for more information on booting Linux with the &os2; boot manager. OS-BS This is an alternative to Boot Easy. It gives you more control over the booting process, with the ability to set the default partition to boot and the booting timeout. The beta version of this programs allows you to boot by selecting the OS with your arrow keys. It is included on the FreeBSD CD in the \TOOLS directory, and via ftp. + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/">ftp. LILO, or LInux LOader This is a limited boot manager. It will boot FreeBSD, though some customization work is required in the LILO configuration file. About FAT32 FAT32 is the replacement to the FAT filesystem included in Microsoft's OEM SR2 Beta release, which started replacing FAT on computers pre-loaded with &windows; 95 towards the end of 1996. It converts the normal FAT filesystem and allows you to use smaller cluster sizes for larger hard drives. FAT32 also modifies the traditional FAT boot sector and allocation table, making it incompatible with some boot managers. A Typical Installation Let's say I have two large EIDE hard drives, and I want to install FreeBSD, Linux, and &windows; 95 on them. Here is how I might do it using these hard disks: /dev/wd0 (first physical hard disk) /dev/wd1 (second hard disk) Both disks have 1416 cylinders. I boot from a &ms-dos; or &windows; 95 boot disk that contains the FDISK.EXE utility and make a small 50 MB primary partition (35-40 for &windows; 95, plus a little breathing room) on the first disk. Also create a larger partition on the second hard disk for my &windows; applications and data. I reboot and install &windows; 95 (easier said than done) on the C: partition. The next thing I do is install Linux. I am not sure - about all the distributions of Linux, but Slackware includes + about all the distributions of Linux, but Slackware includes LILO (see ). When I am partitioning out my hard disk with Linux fdisk, I would put all of Linux on the first drive (maybe 300 MB for a nice root partition and some swap space). After I install Linux, and are prompted about installing LILO, make sure that I install it on the boot sector of my root Linux partition, not in the MBR (master boot record). The remaining hard disk space can go to FreeBSD. I also make sure that my FreeBSD root slice does not go beyond the 1024th cylinder. (The 1024th cylinder is 528 MB into the disk with our hypothetical 720 MB disks). I will use the rest of the hard drive (about 270 MB) for the /usr and / slices if I wish. The rest of the second hard disk (size depends on the amount of my &windows; application/data partition that I created in step 1) can go to the /usr/src slice and swap space. When viewed with the &windows; 95 fdisk utility, my hard drives should now look something like this: --------------------------------------------------------------------- Display Partition Information Current fixed disk drive: 1 Partition Status Type Volume_Label Mbytes System Usage C: 1 A PRI DOS 50 FAT** 7% 2 A Non-DOS (Linux) 300 43% Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) Press Esc to continue --------------------------------------------------------------------- Display Partition Information Current fixed disk drive: 2 Partition Status Type Volume_Label Mbytes System Usage D: 1 A PRI DOS 420 FAT** 60% Total disk space is 696 Mbytes (1 Mbyte = 1048576 bytes) Press Esc to continue --------------------------------------------------------------------- ** May say FAT16 or FAT32 if you are using the OEM SR2 update. See . Install FreeBSD. I make sure to boot with my first hard disk set at NORMAL in the BIOS. If it is not, I will have the enter my true disk geometry at boot time (to get this, boot &windows; 95 and consult Microsoft Diagnostics (MSD.EXE), or check your BIOS) with the parameter hd0=1416,16,63 where 1416 is the number of cylinders on my hard disk, 16 is the number of heads per track, and 63 is the number of sectors per track on the drive. When partitioning out the hard disk, I make sure to install Boot Easy on the first disk. I do not worry about the second disk, nothing is booting off of it. When I reboot, Boot Easy should recognize my three bootable partitions as DOS (&windows; 95), Linux, and BSD (FreeBSD). Special Considerations Most operating systems are very picky about where and how they are placed on the hard disk. &windows; 95 and DOS need to be on the first primary partition on the first hard disk. &os2; is the exception. It can be installed on the first or second disk in a primary or extended partition. If you are not sure, keep the beginning of the bootable partitions below the 1024th cylinder. If you install &windows; 95 on an existing BSD system, it will destroy the MBR, and you will have to reinstall your previous boot manager. Boot Easy can be reinstalled by using the BOOTINST.EXE utility included in the \TOOLS directory on the CDROM, and via ftp. + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/tools/">ftp. You can also re-start the installation process and go to the partition editor. From there, mark the FreeBSD partition as bootable, select Boot Manager, and then type W to (W)rite out the information to the MBR. You can now reboot, and Boot Easy should then recognize &windows; 95 as DOS. Please keep in mind that &os2; can read FAT and HPFS partitions, but not FFS (FreeBSD) or EXT2 (Linux) partitions. Likewise, &windows; 95 can only read and write to FAT and FAT32 (see ) partitions. FreeBSD can read most filesystems, but currently cannot read HPFS partitions. Linux can read HPFS partitions, but can not write to them. Recent versions of the Linux kernel (2.x) can read and write to &windows; 95 VFAT partitions (VFAT is what gives &windows; 95 long file names - it is pretty much the same as FAT). Linux can read and write to most filesystems. Got that? I hope so. Examples (section needs work, please send your example to jayrich@sysc.com). FreeBSD + &windows; 95: If you installed FreeBSD after &windows; 95, you should see DOS on the Boot Easy menu. This is &windows; 95. If you installed &windows; 95 after FreeBSD, read above. As long as your hard disk does not have 1024 cylinders you should not have a problem booting. If one of your partitions goes beyond the 1024th cylinder however, and you get messages like invalid system disk under DOS (&windows; 95) and FreeBSD will not boot, try looking for a setting in your BIOS called > 1024 cylinder support or NORMAL/LBA mode. DOS may need LBA (Logical Block Addressing) in order to boot correctly. If the idea of switching BIOS settings every time you boot up does not appeal to you, you can boot FreeBSD through DOS via the FBSDBOOT.EXE utility on the CD (It should find your FreeBSD partition and boot it.) FreeBSD + &os2; + &windows; 95: Nothing new here. The &os2; boot manager can boot all of these operating systems, so that should not be a problem. FreeBSD + Linux: You can also use Boot Easy to boot both operating systems. FreeBSD + Linux + &windows; 95: (see ) Other Sources of Help There are many Linux + url="http://www.linuxresources.com/LDP/HOWTO/HOWTO-INDEX.html">Linux HOW-TOs that deal with multiple operating systems on the same hard disk. The Linux+DOS+Win95+OS2 + url="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+DOS+Win95+OS2.html">Linux+DOS+Win95+OS2 mini-HOWTO offers help on configuring the &os2; boot manager, and the Linux+FreeBSD + url="http://www.linuxresources.com/LDP/HOWTO/mini/Linux+FreeBSD.html">Linux+FreeBSD mini-HOWTO might be interesting as well. The Linux-HOWTO + url="http://www.in.net/~jkatz/win95/Linux-HOWTO.html">Linux-HOWTO is also helpful. The &windowsnt; + url="http://www.tburke.net/info/ntldr/ntldr_hacking_guide.htm">&windowsnt; Loader Hacking Guide provides good information on multibooting &windowsnt;, &windows; 95, and DOS with other operating systems. And Hale Landis's How It Works document pack contains some good info on all sorts of disk geometry and booting related topics. You can find it at . Finally, do not overlook FreeBSD's kernel documentation on the booting procedure, available in the kernel source distribution (it unpacks to /usr/src/sys/i386/boot/biosboot/README.386BSD. + url="file://localhost/usr/src/sys/i386/boot/biosboot/README.386BSD">/usr/src/sys/i386/boot/biosboot/README.386BSD. Technical Details (Contributed by Randall Hopper, rhh@ct.picker.com) This section attempts to give you enough basic information about your hard disks and the disk booting process so that you can troubleshoot most problems you might encounter when getting set up to boot several operating systems. It starts in pretty basic terms, so you may want to skim down in this section until it begins to look unfamiliar and then start reading. Disk Primer Three fundamental terms are used to describe the location of data on your hard disk: Cylinders, Heads, and Sectors. It is not particularly important to know what these terms relate to except to know that, together, they identify where data is physically on your disk. Your disk has a particular number of cylinders, number of heads, and number of sectors per cylinder-head (a cylinder-head also known now as a track). Collectively this information defines the physical disk geometry for your hard disk. There are typically 512 bytes per sector, and 63 sectors per track, with the number of cylinders and heads varying widely from disk to disk. Thus you can figure the number of bytes of data that will fit on your own disk by calculating: (# of cylinders) × (# heads) × (63 sectors/track) × (512 bytes/sect) For example, on my 1.6 Gig Western Digital AC31600 EIDE hard disk, that is: (3148 cyl) × (16 heads) × (63 sectors/track) × (512 bytes/sect) which is 1,624,670,208 bytes, or around 1.6 Gig. You can find out the physical disk geometry (number of cylinders, heads, and sectors/track counts) for your hard disks using ATAID or other programs off the net. Your hard disk probably came with this information as well. Be careful though: if you are using BIOS LBA (see ), you can not use just any program to get the physical geometry. This is because many programs (e.g. MSD.EXE or FreeBSD fdisk) do not identify the physical disk geometry; they instead report the translated geometry (virtual numbers from using LBA). Stay tuned for what that means. One other useful thing about these terms. Given 3 numbers—a cylinder number, a head number, and a sector-within-track number—you identify a specific absolute sector (a 512 byte block of data) on your disk. Cylinders and Heads are numbered up from 0, and Sectors are numbered up from 1. For those that are interested in more technical details, information on disk geometry, boot sectors, BIOSes, etc. can be found all over the net. Query Lycos, Yahoo, etc. for boot sector or master boot record. Among the useful info you will find are Hale Landis's How It Works document pack. See the section for a few pointers to this pack. Ok, enough terminology. We are talking about booting here. The Booting Process On the first sector of your disk (Cyl 0, Head 0, Sector 1) lives the Master Boot Record (MBR). It contains a map of your disk. It identifies up to 4 partitions, each of which is a contiguous chunk of that disk. FreeBSD calls partitions slices to avoid confusion with its own partitions, but we will not do that here. Each partition can contain its own operating system. Each partition entry in the MBR has a Partition ID, a Start Cylinder/Head/Sector, and an End Cylinder/Head/Sector. The Partition ID tells what type of partition it is (what OS) and the Start/End tells where it is. lists a smattering of some common Partition IDs. Partition IDs ID (hex) Description 01 Primary DOS12 (12-bit FAT) 04 Primary DOS16 (16-bit FAT) 05 Extended DOS 06 Primary big DOS (> 32MB) 0A &os2; 83 Linux (EXT2FS) A5 FreeBSD, NetBSD, 386BSD (UFS)
Note that not all partitions are bootable (e.g. Extended DOS). Some are—some are not. What makes a partition bootable is the configuration of the Partition Boot Sector that exists at the beginning of each partition. When you configure your favorite boot manager, it looks up the entries in the MBR partition tables of all your hard disks and lets you name the entries in that list. Then when you boot, the boot manager is invoked by special code in the Master Boot Sector of the first probed hard disk on your system. It looks at the MBR partition table entry corresponding to the partition choice you made, uses the Start Cylinder/Head/Sector information for that partition, loads up the Partition Boot Sector for that partition, and gives it control. That Boot Sector for the partition itself contains enough information to start loading the operating system on that partition. One thing we just brushed past that is important to know. All of your hard disks have MBRs. However, the one that is important is the one on the disk that is first probed by the BIOS. If you have only IDE hard disks, it is the first IDE disk (e.g. primary disk on first controller). Similarly for SCSI only systems. If you have both IDE and SCSI hard disks though, the IDE disk is typically probed first by the BIOS, so the first IDE disk is the first probed disk. The boot manager you will install will be hooked into the MBR on this first probed hard disk that we have just described. Booting Limitations and Warnings Now the interesting stuff that you need to watch out for. The dreaded 1024 cylinder limit and how BIOS LBA helps The first part of the booting process is all done through the BIOS, (if that is a new term to you, the BIOS is a software chip on your system motherboard which provides startup code for your computer). As such, this first part of the process is subject to the limitations of the BIOS interface. The BIOS interface used to read the hard disk during this period (INT 13H, Subfunction 2) allocates 10 bits to the Cylinder Number, 8 bits to the Head Number, and 6 bits to the Sector Number. This restricts users of this interface (i.e. boot managers hooked into your disk's MBR as well as OS loaders hooked into the Boot Sectors) to the following limits: 1024 cylinders, max 256 heads, max 64 sectors/track, max (actually 63, 0 is not available) Now big hard disks have lots of cylinders but not a lot of heads, so invariably with big hard disks the number of cylinders is greater than 1024. Given this and the BIOS interface as is, you can not boot off just anywhere on your hard disk. The boot code (the boot manager and the OS loader hooked into all bootable partitions' Boot Sectors) has to reside below cylinder 1024. In fact, if your hard disk is typical and has 16 heads, this equates to: 1024 cyl/disk × 16 heads/disk × 63 sect/(cyl-head) × 512 bytes/sector which is around the often-mentioned 528MB limit. This is where BIOS LBA (Logical Block Addressing) comes in. BIOS LBA gives the user of the BIOS API calls access to physical cylinders above 1024 though the BIOS interfaces by redefining a cylinder. That is, it remaps your cylinders and heads, making it appear through the BIOS as though the disk has fewer cylinders and more heads than it actually does. In other words, it takes advantage of the fact that hard disks have relatively few heads and lots of cylinders by shifting the balance between number of cylinders and number of heads so that both numbers lie below the above-mentioned limits (1024 cylinders, 256 heads). With BIOS LBA, the hard disk size limitation is virtually removed (well, pushed up to 8 Gigabytes anyway). If you have an LBA BIOS, you can put FreeBSD or any OS anywhere you want and not hit the 1024 cylinder limit. To use my 1.6 Gig Western Digital as an example again, its physical geometry is: (3148 cyl, 16 heads, 63 sectors/track, 512 bytes/sector) However, my BIOS LBA remaps this to: (787 cyl, 64 heads, 63 sectors/track, 512 bytes/sector) giving the same effective size disk, but with cylinder and head counts within the BIOS API's range (Incidentally, I have both Linux and FreeBSD existing on one of my hard disks above the 1024th physical cylinder, and both operating systems boot fine, thanks to BIOS LBA). Boot Managers and Disk Allocation Another gotcha to watch out when installing boot managers is allocating space for your boot manager. It is best to be aware of this issue up front to save yourself from having to reinstall one or more of your OSs. If you followed the discussion in about the Master Boot Sector (where the MBR is), Partition Boot Sectors, and the booting process, you may have been wondering just exactly where on your hard disk that nifty boot manager is going to live. Well, some boot managers are small enough to fit entirely within the Master Boot Sector (Cylinder 0, Head 0, Sector 0) along with the partition table. Others need a bit more room and actually extend a few sectors past the Master Boot Sector in the Cylinder 0 Head 0 track, since that is typically free…typically. That is the catch. Some operating systems (FreeBSD included) let you start their partitions right after the Master Boot Sector at Cylinder 0, Head 0, Sector 2 if you want. In fact, if you give FreeBSD's sysinstall a disk with an empty chunk up front or the whole disk empty, that is where it will start the FreeBSD partition by default (at least it did when I fell into this trap). Then when you go to install your boot manager, if it is one that occupies a few extra sectors after the MBR, it will overwrite the front of the first partition's data. In the case of FreeBSD, this overwrites the disk label, and renders your FreeBSD partition unbootable. The easy way to avoid this problem (and leave yourself the flexibility to try different boot managers later) is just to always leave the first full track on your disk unallocated when you partition your disk. That is, leave the space from Cylinder 0, Head 0, Sector 2 through Cylinder 0, Head 0, Sector 63 unallocated, and start your first partition at Cylinder 0, Head 1, Sector 1. For what it is worth, when you create a DOS partition at the front of your disk, DOS leaves this space open by default (this is why some boot managers assume it is free). So creating a DOS partition up at the front of your disk avoids this problem altogether. I like to do this myself, creating 1 Meg DOS partition up front, because it also avoids my primary DOS drive letters shifting later when I repartition. For reference, the following boot managers use the Master Boot Sector to store their code and data: OS-BS 1.35 Boot Easy LILO These boot managers use a few additional sectors after the Master Boot Sector: OS-BS 2.0 Beta 8 (sectors 2-5) The &os2; boot manager What if your machine will not boot? At some point when installing boot managers, you might leave the MBR in a state such that your machine will not boot. This is unlikely, but possible when re-FDISKing underneath an already-installed boot manager. If you have a bootable DOS partition on your disk, you can boot off a DOS floppy, and run: A:\> FDISK /MBR to put the original, simple DOS boot code back into the system. You can then boot DOS (and DOS only) off the hard drive. Alternatively, just re-run your boot manager installation program off a bootable floppy.
diff --git a/en_US.ISO8859-1/articles/new-users/article.sgml b/en_US.ISO8859-1/articles/new-users/article.sgml index 3264a92b85..a256e10f15 100644 --- a/en_US.ISO8859-1/articles/new-users/article.sgml +++ b/en_US.ISO8859-1/articles/new-users/article.sgml @@ -1,1059 +1,1059 @@ %articles.ent; ]>
For People New to Both FreeBSD and &unix; Annelise Anderson
andrsn@andrsn.stanford.edu
 August 15, 1997 &tm-attrib.freebsd; &tm-attrib.ibm; &tm-attrib.microsoft; &tm-attrib.netscape; &tm-attrib.opengroup; &tm-attrib.general; Congratulations on installing FreeBSD! This introduction is for people new to both FreeBSD and &unix;—so it starts with basics. It assumes you are using version 2.0.5 or later of &os; as distributed by &os;.org, your system (for now) has a single user (you)—and you are probably pretty good with DOS/&windows; or &os2;. Logging in and Getting Out Log in (when you see login:) as a user you created during installation or as root. (Your FreeBSD installation will already have an account for root; who can go anywhere and do anything, including deleting essential files, so be careful!) The symbols &prompt.user; and &prompt.root; in the following stand for the prompt (yours may be different), with &prompt.user; indicating an ordinary user and &prompt.root; indicating root. To log out (and get a new login: prompt) type &prompt.root; exit as often as necessary. Yes, press enter after commands, and remember that &unix; is case-sensitive—exit, not EXIT. To shut down the machine type &prompt.root; /sbin/shutdown -h now Or to reboot type &prompt.root; /sbin/shutdown -r now or &prompt.root; /sbin/reboot You can also reboot with CtrlAltDelete. Give it a little time to do its work. This is equivalent to /sbin/reboot in recent releases of FreeBSD and is much, much better than hitting the reset button. You do not want to have to reinstall this thing, do you? Adding A User with Root Privileges If you did not create any users when you installed the system and are thus logged in as root, you should probably create a user now with &prompt.root; adduser The first time you use adduser, it might ask for some defaults to save. You might want to make the default shell &man.csh.1; instead of &man.sh.1;, if it suggests sh as the default. Otherwise just press enter to accept each default. These defaults are saved in /etc/adduser.conf, an editable file. Suppose you create a user jack with full name Jack Benimble. Give jack a password if security (even kids around who might pound on the keyboard) is an issue. When it asks you if you want to invite jack into other groups, type wheel Login group is ``jack''. Invite jack into other groups: wheel This will make it possible to log in as jack and use the &man.su.1; command to become root. Then you will not get scolded any more for logging in as root. You can quit adduser any time by typing CtrlC, and at the end you will have a chance to approve your new user or simply type n for no. You might want to create a second new user so that when you edit jack's login files, you will have a hot spare in case something goes wrong. Once you have done this, use exit to get back to a login prompt and log in as jack. In general, it is a good idea to do as much work as possible as an ordinary user who does not have the power—and risk—of root. If you already created a user and you want the user to be able to su to root, you can log in as root and edit the file /etc/group, adding jack to the first line (the group wheel). But first you need to practice &man.vi.1;, the text editor—or use the simpler text editor, &man.ee.1;, installed on recent versions of FreeBSD. To delete a user, use the rmuser command. Looking Around Logged in as an ordinary user, look around and try out some commands that will access the sources of help and information within FreeBSD. Here are some commands and what they do: id Tells you who you are! pwd Shows you where you are—the current working directory. ls Lists the files in the current directory. ls Lists the files in the current directory with a * after executables, a / after directories, and an @ after symbolic links. ls Lists the files in long format—size, date, permissions. ls Lists hidden dot files with the others. If you are root, the dot files show up without the switch. cd Changes directories. cd .. backs up one level; note the space after cd. cd /usr/local goes there. cd ~ goes to the home directory of the person logged in—e.g., /usr/home/jack. Try cd /cdrom, and then ls, to find out if your CDROM is mounted and working. view filename Lets you look at a file (named filename) without changing it. Try view /etc/fstab. Type :q to quit. cat filename Displays filename on screen. If it is too long and you can see only the end of it, press ScrollLock and use the up-arrow to move backward; you can use ScrollLock with manual pages too. Press ScrollLock again to quit scrolling. You might want to try cat on some of the dot files in your home directory—cat .cshrc, cat .login, cat .profile. You will notice aliases in .cshrc for some of the ls commands (they are very convenient). You can create other aliases by editing .cshrc. You can make these aliases available to all users on the system by putting them in the system-wide csh configuration file, /etc/csh.cshrc. Getting Help and Information Here are some useful sources of help. Text stands for something of your choice that you type in—usually a command or filename. apropos text Everything containing string text in the whatis database. man text The manual page for text. The major source of documentation for &unix; systems. man ls will tell you all the ways to use the ls command. Press Enter to move through text, CtrlB to go back a page, CtrlF to go forward, q or CtrlC to quit. which text Tells you where in the user's path the command text is found. locate text All the paths where the string text is found. whatis text Tells you what the command text does and its manual page. Typing whatis * will tell you about all the binaries in the current directory. whereis text Finds the file text, giving its full path. You might want to try using whatis on some common useful commands like cat, more, grep, mv, find, tar, chmod, chown, date, and script. more lets you read a page at a time as it does in DOS, e.g., ls -l | more or more filename. The * works as a wildcard—e.g., ls w* will show you files beginning with w. Are some of these not working very well? Both &man.locate.1; and &man.whatis.1; depend on a database that is rebuilt weekly. If your machine is not going to be left on over the weekend (and running FreeBSD), you might want to run the commands for daily, weekly, and monthly maintenance now and then. Run them as root and, for now, give each one time to finish before you start the next one. &prompt.root; periodic daily output omitted &prompt.root; periodic weekly output omitted &prompt.root; periodic monthly output omitted If you get tired of waiting, press AltF2 to get another virtual console, and log in again. After all, it is a multi-user, multi-tasking system. Nevertheless these commands will probably flash messages on your screen while they are running; you can type clear at the prompt to clear the screen. Once they have run, you might want to look at /var/mail/root and /var/log/messages. Running such commands is part of system administration—and as a single user of a &unix; system, you are your own system administrator. Virtually everything you need to be root to do is system administration. Such responsibilities are not covered very well even in those big fat books on &unix;, which seem to devote a lot of space to pulling down menus in windows managers. You might want to get one of the two leading books on systems administration, either Evi Nemeth et.al.'s UNIX System Administration Handbook (Prentice-Hall, 1995, ISBN 0-13-15051-7)—the second edition with the red cover; or Æleen Frisch's Essential System Administration (O'Reilly & Associates, 2002, ISBN 0-596-00343-9). I used Nemeth. Editing Text To configure your system, you need to edit text files. Most of them will be in the /etc directory; and you will need to su to root to be able to change them. You can use the easy ee, but in the long run the text editor vi is worth learning. There is an excellent tutorial on vi in /usr/src/contrib/nvi/docs/tutorial, if you have the system sources installed. Before you edit a file, you should probably back it up. Suppose you want to edit /etc/rc.conf. You could just use cd /etc to get to the /etc directory and do: &prompt.root; cp rc.conf rc.conf.orig This would copy rc.conf to rc.conf.orig, and you could later copy rc.conf.orig to rc.conf to recover the original. But even better would be moving (renaming) and then copying back: &prompt.root; mv rc.conf rc.conf.orig &prompt.root; cp rc.conf.orig rc.conf because the mv command preserves the original date and owner of the file. You can now edit rc.conf. If you want the original back, you would then mv rc.conf rc.conf.myedit (assuming you want to preserve your edited version) and then &prompt.root; mv rc.conf.orig rc.conf to put things back the way they were. To edit a file, type &prompt.root; vi filename Move through the text with the arrow keys. Esc (the escape key) puts vi in command mode. Here are some commands: x delete letter the cursor is on dd delete the entire line (even if it wraps on the screen) i insert text at the cursor a insert text after the cursor Once you type i or a, you can enter text. Esc puts you back in command mode where you can type :w to write your changes to disk and continue editing :wq to write and quit :q! to quit without saving changes /text to move the cursor to text; /Enter (the enter key) to find the next instance of text. G to go to the end of the file nG to go to line n in the file, where n is a number CtrlL to redraw the screen Ctrlb and Ctrlf go back and forward a screen, as they do with more and view. Practice with vi in your home directory by creating a new file with vi filename and adding and deleting text, saving the file, and calling it up again. vi delivers some surprises because it is really quite complex, and sometimes you will inadvertently issue a command that will do something you do not expect. (Some people actually like vi—it is more powerful than DOS EDIT—find out about the :r command.) Use Esc one or more times to be sure you are in command mode and proceed from there when it gives you trouble, save often with :w, and use :q! to get out and start over (from your last :w) when you need to. Now you can cd to /etc, su to root, use vi to edit the file /etc/group, and add a user to wheel so the user has root privileges. Just add a comma and the user's login name to the end of the first line in the file, press Esc, and use :wq to write the file to disk and quit. Instantly effective. (You did not put a space after the comma, did you?) Printing Files from DOS At this point you probably do not have the printer working, so here is a way to create a file from a manual page, move it to a floppy, and then print it from DOS. Suppose you want to read carefully about changing permissions on files (pretty important). You can use man chmod to read about it. The command &prompt.user; man chmod | col -b > chmod.txt will remove formatting codes and send the manual page to the chmod.txt file instead of showing it on your screen. Now put a dos-formatted diskette in your floppy drive a, su to root, and type &prompt.root; /sbin/mount -t msdos /dev/fd0 /mnt to mount the floppy drive on /mnt. Now (you no longer need to be root, and you can type exit to get back to being user jack) you can go to the directory where you created chmod.txt and copy the file to the floppy with: &prompt.user; cp chmod.txt /mnt and use ls /mnt to get a directory listing of /mnt, which should show the file chmod.txt. You might especially want to make a file from /sbin/dmesg by typing &prompt.user; /sbin/dmesg > dmesg.txt and copying dmesg.txt to the floppy. /sbin/dmesg is the boot log record, and it is useful to understand it because it shows what FreeBSD found when it booted up. If you ask questions on the &a.questions; or on a USENET group—like FreeBSD is not finding my tape drive, what do I do?—people will want to know what dmesg has to say. You can now unmount the floppy drive (as root) to get the disk out with &prompt.root; /sbin/umount /mnt and reboot to go to DOS. Copy these files to a DOS directory, call them up with DOS EDIT, &windows; Notepad or Wordpad, or a word processor, make a minor change so the file has to be saved, and print as you normally would from DOS or Windows. Hope it works! manual pages come out best if printed with the DOS print command. (Copying files from FreeBSD to a mounted DOS partition is in some cases still a little risky.) Getting the printer printing from FreeBSD involves creating an appropriate entry in /etc/printcap and creating a matching spool directory in /var/spool/output. If your printer is on lpt0 (what DOS calls LPT1), you may only need to go to /var/spool/output and (as root) create the directory lpd by typing: mkdir lpd, if it does not already exist. Then the printer should respond if it is turned on when the system is booted, and lp or lpr should send a file to the printer. Whether or not the file actually prints depends on configuring it, which is covered in the FreeBSD + url="&url.books.handbook;/index.html">FreeBSD handbook. Other Useful Commands df shows file space and mounted systems. ps aux shows processes running. ps ax is a narrower form. rm filename remove filename. rm -R dir removes a directory dir and all subdirectories—careful! ls -R lists files in the current directory and all subdirectories; I used a variant, ls -AFR > where.txt, to get a list of all the files in / and (separately) /usr before I found better ways to find files. passwd to change user's password (or root's password) man hier manual page on the &unix; filesystem Use find to locate filename in /usr or any of its subdirectories with &prompt.user; find /usr -name "filename" You can use * as a wildcard in "filename" (which should be in quotes). If you tell find to search in / instead of /usr it will look for the file(s) on all mounted filesystems, including the CDROM and the DOS partition. An excellent book that explains &unix; commands and utilities is Abrahams & Larson, Unix for the Impatient (2nd ed., Addison-Wesley, 1996). There is also a lot of &unix; information on the Internet. Next Steps You should now have the tools you need to get around and edit files, so you can get everything up and running. There is a great deal of information in the FreeBSD handbook (which is probably on your hard drive) and FreeBSD's web site. A + url="&url.base;/index.html">FreeBSD's web site. A wide variety of packages and ports are on the CDROM as well as the web site. The handbook tells you more about how to use them (get the package if it exists, with pkg_add /cdrom/packages/All/packagename, where packagename is the filename of the package). The CDROM has lists of the packages and ports with brief descriptions in cdrom/packages/index, cdrom/packages/index.txt, and cdrom/ports/index, with fuller descriptions in /cdrom/ports/*/*/pkg/DESCR, where the *s represent subdirectories of kinds of programs and program names respectively. If you find the handbook too sophisticated (what with lndir and all) on installing ports from the CDROM, here is what usually works: Find the port you want, say kermit. There will be a directory for it on the CDROM. Copy the subdirectory to /usr/local (a good place for software you add that should be available to all users) with: &prompt.root; cp -R /cdrom/ports/comm/kermit /usr/local This should result in a /usr/local/kermit subdirectory that has all the files that the kermit subdirectory on the CDROM has. Next, create the directory /usr/ports/distfiles if it does not already exist using mkdir. Now check /cdrom/ports/distfiles for a file with a name that indicates it is the port you want. Copy that file to /usr/ports/distfiles; in recent versions you can skip this step, as FreeBSD will do it for you. In the case of kermit, there is no distfile. Then cd to the subdirectory of /usr/local/kermit that has the file Makefile. Type &prompt.root; make all install During this process the port will FTP to get any compressed files it needs that it did not find on the CDROM or in /usr/ports/distfiles. If you do not have your network running yet and there was no file for the port in /cdrom/ports/distfiles, you will have to get the distfile using another machine and copy it to /usr/ports/distfiles from a floppy or your DOS partition. Read Makefile (with cat or more or view) to find out where to go (the master distribution site) to get the file and what its name is. Its name will be truncated when downloaded to DOS, and after you get it into /usr/ports/distfiles you will have to rename it (with the mv command) to its original name so it can be found. (Use binary file transfers!) Then go back to /usr/local/kermit, find the directory with Makefile, and type make all install. The other thing that happens when installing ports or packages is that some other program is needed. If the installation stops with a message can't find unzip or whatever, you might need to install the package or port for unzip before you continue. Once it is installed type rehash to make FreeBSD reread the files in the path so it knows what is there. (If you get a lot of path not found messages when you use whereis or which, you might want to make additions to the list of directories in the path statement in .cshrc in your home directory. The path statement in &unix; does the same kind of work it does in DOS, except the current directory is not (by default) in the path for security reasons; if the command you want is in the directory you are in, you need to type ./ before the command to make it work; no space after the slash.) You might want to get the most recent version of &netscape; - from their FTP site. + from their FTP site. (&netscape; requires the X Window System.) There is now a FreeBSD version, so look around carefully. Just use gunzip filename and tar xvf filename on it, move the binary to /usr/local/bin or some other place binaries are kept, rehash, and then put the following lines in .cshrc in each user's home directory or (easier) in /etc/csh.cshrc, the system-wide csh start-up file: setenv XKEYSYMDB /usr/X11R6/lib/X11/XKeysymDB setenv XNLSPATH /usr/X11R6/lib/X11/nls This assumes that the file XKeysymDB and the directory nls are in /usr/X11R6/lib/X11; if they are not, find them and put them there. If you originally got &netscape; as a port using the CDROM (or FTP), do not replace /usr/local/bin/netscape with the new netscape binary; this is just a shell script that sets up the environment variables for you. Instead rename the new binary to netscape.bin and replace the old binary, which is /usr/local/netscape/netscape. Your Working Environment Your shell is the most important part of your working environment. In DOS, the usual shell is command.com. The shell is what interprets the commands you type on the command line, and thus communicates with the rest of the operating system. You can also write shell scripts, which are like DOS batch files: a series of commands to be run without your intervention. Two shells come installed with FreeBSD: csh and sh. csh is good for command-line work, but scripts should be written with sh (or bash). You can find out what shell you have by typing echo $SHELL. The csh shell is okay, but tcsh does everything csh does and more. It allows you to recall commands with the arrow keys and edit them. It has tab-key completion of filenames (csh uses the Esc key), and it lets you switch to the directory you were last in with cd -. It is also much easier to alter your prompt with tcsh. It makes life a lot easier. Here are the three steps for installing a new shell: Install the shell as a port or a package, just as you would any other port or package. Use rehash and which tcsh (assuming you are installing tcsh) to make sure it got installed. As root, edit /etc/shells, adding a line in the file for the new shell, in this case /usr/local/bin/tcsh, and save the file. (Some ports may do this for you.) Use the chsh command to change your shell to tcsh permanently, or type tcsh at the prompt to change your shell without logging in again. It can be dangerous to change root's shell to something other than sh or csh on early versions of FreeBSD and many other versions of &unix;; you may not have a working shell when the system puts you into single user mode. The solution is to use su -m to become root, which will give you the tcsh as root, because the shell is part of the environment. You can make this permanent by adding it to your .tcshrc file as an alias with: alias su su -m When tcsh starts up, it will read the /etc/csh.cshrc and /etc/csh.login files, as does csh. It will also read the .login file in your home directory and the .cshrc file as well, unless you provide a .tcshrc file. This you can do by simply copying .cshrc to .tcshrc. Now that you have installed tcsh, you can adjust your prompt. You can find the details in the manual page for tcsh, but here is a line to put in your .tcshrc that will tell you how many commands you have typed, what time it is, and what directory you are in. It also produces a > if you are an ordinary user and a # if you are root, but tsch will do that in any case: set prompt = "%h %t %~ %# " This should go in the same place as the existing set prompt line if there is one, or under "if($?prompt) then" if not. Comment out the old line; you can always switch back to it if you prefer it. Do not forget the spaces and quotes. You can get the .tcshrc reread by typing source .tcshrc. You can get a listing of other environmental variables that have been set by typing env at the prompt. The result will show you your default editor, pager, and terminal type, among possibly many others. A useful command if you log in from a remote location and can not run a program because the terminal is not capable is setenv TERM vt100. Other As root, you can unmount the CDROM with /sbin/umount /cdrom, take it out of the drive, insert another one, and mount it with /sbin/mount_cd9660 /dev/cd0a /cdrom assuming cd0a is the device name for your CDROM drive. The most recent versions of FreeBSD let you mount the CDROM with just /sbin/mount /cdrom. Using the live filesystem—the second of FreeBSD's CDROM disks—is useful if you have got limited space. What is on the live filesystem varies from release to release. You might try playing games from the CDROM. This involves using lndir, which gets installed with the X Window System, to tell the program(s) where to find the necessary files, because they are in the /cdrom file system instead of in /usr and its subdirectories, which is where they are expected to be. Read man lndir. Comments Welcome If you use this guide I would be interested in knowing where it was unclear and what was left out that you think should be included, and if it was helpful. My thanks to Eugene W. Stark, professor of computer science at SUNY-Stony Brook, and John Fieber for helpful comments. Annelise Anderson, andrsn@andrsn.stanford.edu
diff --git a/en_US.ISO8859-1/articles/problem-reports/article.sgml b/en_US.ISO8859-1/articles/problem-reports/article.sgml index f65c18cdea..d17652e365 100644 --- a/en_US.ISO8859-1/articles/problem-reports/article.sgml +++ b/en_US.ISO8859-1/articles/problem-reports/article.sgml @@ -1,879 +1,879 @@ %articles.ent; ]>
Writing &os; Problem Reports $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.cvsup; &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 &os; 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 &os; 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. To make matters worse, often these kinds of bugs are actually caused by failing hard drives or overheating processors — you should always try to rule out these causes, whenever possible, before submitting a PR.
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 &os;, this means: The &os; - Frequently Asked + Frequently Asked Questions (FAQ) list. The FAQ attempts to provide answers for a wide range of questions, such as those concerning - hardware + hardware compatibility, - user + user applications, - and kernel + and kernel configuration. The mailing + url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">mailing lists—if you are not subscribed, use the + url="http://www.FreeBSD.org/search/search.html#mailinglists">the searchable archives on the &os; 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 - + &os; PR database (GNATS). Unless your problem is recent or obscure, there is a fair chance it has already been reported. Most importantly, you should attempt to see if existing documentation in the source base addresses your problem. For the base &os; code, you should carefully study the contents of the /usr/src/UPDATING file on your system or its latest version at - . + . (This is vital information if you are upgrading from one version to another—especially if you are upgrading to the &os.current; branch). However, if the problem is in something that was installed as a part of the &os; Ports Collection, you should refer to /usr/ports/UPDATING (for individual ports) or /usr/ports/CHANGES (for changes that affect the entire Ports Collection). - + and - + are also available via CVSweb. 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 &os; 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 &os;; 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 &os; port has not been updated yet. The second catch is that &os;'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 &os; 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 you definitely should set the Class of your PR to maintainer-update. This way any committer that handles your PR will not have to check. Be specific. The more information you supply about what problem you are having, the better your chance of getting a response. Include the version of &os; you are running (there is a place to put that, see below) and on which architecture. You should include whether you are running from a release (e.g. from a CDROM or download), or from a system maintained by &man.cvsup.1; (and, if so, how recently you updated). If you are tracking the &os.current; branch, that is the very first thing someone will ask, because fixes (especially for high-profile problems) tend to get committed very quickly, and &os.current; users are expected to keep up. Include which global options you have specified in your make.conf. Note: specifying -O2 and above to &man.gcc.1; is known to be buggy in many situations. While the &os; developers will accept patches, they are generally unwilling to investigate such issues due to simple lack of time and volunteers, and may instead respond that this just is not supported. If this is a kernel problem, then be prepared to supply the following information. (You do not have to include these by default, which only tends to fill up the database, but you should include excerpts that you think might be relevant): your kernel configuration (including which hardware devices you have installed) whether or not you have debugging options enabled (such as WITNESS), and if so, whether the problem persists when you change the sense of that option a backtrace, if one was generated the fact that you have read src/UPDATING and that your problem is not listed there (someone is guaranteed to ask) whether or not you can run any other kernel as a fallback (this is to rule out hardware-related issues such as failing disks and overheating CPUs, which can masquerade as kernel problems) If this is a ports problem, then be prepared to supply the following information. (You do not have to include these by default, which only tends to fill up the database, but you should include excerpts that you think might be relevant): which ports you have installed any environment variables that override the defaults in bsd.port.mk, such as PORTSDIR the fact that you have read ports/UPDATING and that your problem is not listed there (someone is guaranteed to ask) 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 + 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 &os;, see the Electronic Mail chapter of the &os; 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. For problems with the kernel or the base utilities, a patch against &os.current; (the 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 &os.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 &os.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 &os; 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 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) or serious unless it is something that will affect many users (problems with particular device drivers or system utilities). &os; developers will not neccesarily work on your problem faster if you inflate its importance since there are so many other people who have done exactly that — in fact, some developers pay little attention to this field, and the next, because of this. Priority: One of low, medium or high. high should be reserved for problems that will affect practically every user of &os; and medium for something that will affect many users. Category: Choose one of the following (taken from /usr/gnats/gnats-adm/categories): advocacy: problems relating to &os;'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. ia64: problems specific to the ia64 platform. java: problems related to &java;. kern: problems with the kernel or (non-platform-specific) device drivers. 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. sparc64: problems specific to the &sparc64; platform. standards: Standards conformance issues. threads: problems related to the &os; threads implementation (especially on &os.current;). www: Changes or enhancements to the &os; 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 &os; 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, please use one of two methods to submit your followup: The easiest way is to use the followup link on the individual PR's web page, which you can reach from the - + PR search page. Clicking on this link will bring up an an email window with the correct To: and Subject: lines filled in (if your browser is configured to do this). Alternatively, you can 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 you do not include the tracking number, GNATS will become confused and create an entirely new PR which it then assigns to the GNATS administrator, and then your followup will become lost until someone comes in to clean up the mess, which could be days or weeks afterwards. Wrong way: Subject: that PR I sent Right way: Subject: Re: ports/12345: compilation problem with foo/bar 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-&os;-specific) problem reports. Problem Report Handling Guidelines—valuable insight into how problem reports are handled by the &os; developers.
diff --git a/en_US.ISO8859-1/books/arch-handbook/book.sgml b/en_US.ISO8859-1/books/arch-handbook/book.sgml index 06a645e210..093768e8f0 100644 --- a/en_US.ISO8859-1/books/arch-handbook/book.sgml +++ b/en_US.ISO8859-1/books/arch-handbook/book.sgml @@ -1,210 +1,210 @@ %books.ent; %chapters; %mac-entities; ]> &os; Architecture Handbook The FreeBSD Documentation Project August 2000 2000 2001 2002 2003 2004 The FreeBSD Documentation Project &bookinfo.trademarks; &bookinfo.legalnotice; Welcome to the &os; Architecture Handbook. This manual is a work in progress and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available - from the FreeBSD World + from the FreeBSD World Wide Web server. It may also be downloaded in a variety of formats and compression options from the FreeBSD FTP server or one of the numerous mirror sites. Kernel &chap.boot; &chap.locking; &chap.kobj; &chap.jail; &chap.sysinit; &chap.mac; &chap.vm; &chap.smp; * UFS UFS, FFS, Ext2FS, JFS, inodes, buffer cache, labeling, locking, metadata, soft-updates, LFS, portalfs, procfs, vnodes, memory sharing, memory objects, TLBs, caching * AFS AFS, NFS, SANs, etc. * Syscons Syscons, tty, PCVT, serial console, screen savers, etc. * Compatibility Layers * Linux Linux, SVR4, etc. Device Drivers &chap.driverbasics; &chap.isa; &chap.pci; &chap.scsi; &chap.usb; &chap.newbus; &chap.snd; &chap.pccard; Appendices Marshall Kirk McKusick Keith Bostic Michael J Karels John S Quarterman 1996Addison-Wesley Publishing Company, Inc. 0-201-54979-4 Addison-Wesley Publishing Company, Inc. The Design and Implementation of the 4.4 BSD Operating System 1-2 diff --git a/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml index 79cddbeb80..bc15b992ac 100644 --- a/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml +++ b/en_US.ISO8859-1/books/developers-handbook/secure/chapter.sgml @@ -1,525 +1,525 @@ Murray Stockely Contributed by Secure Programming Synopsis This chapter describes some of the security issues that have plagued &unix; programmers for decades and some of the new tools available to help programmers avoid writing exploitable code. Secure Design Methodology Writing secure applications takes a very scrutinous and pessimistic outlook on life. Applications should be run with the principle of least privilege so that no process is ever running with more than the bare minimum access that it needs to accomplish its function. Previously tested code should be reused whenever possible to avoid common mistakes that others may have already fixed. One of the pitfalls of the &unix; environment is how easy it is to make assumptions about the sanity of the environment. Applications should never trust user input (in all its forms), system resources, inter-process communication, or the timing of events. &unix; processes do not execute synchronously so logical operations are rarely atomic. Buffer Overflows Buffer Overflows have been around since the very beginnings of the Von-Neuman architecture. buffer overflow Von-Neuman They first gained widespread notoriety in 1988 with the Morris Internet worm. Unfortunately, the same basic attack remains Morris Internet worm effective today. Of the 17 CERT security advisories of 1999, 10 CERTsecurity advisories of them were directly caused by buffer-overflow software bugs. By far the most common type of buffer overflow attack is based on corrupting the stack. stack arguments Most modern computer systems use a stack to pass arguments to procedures and to store local variables. A stack is a last in first out (LIFO) buffer in the high memory area of a process image. When a program invokes a function a new "stack frame" is LIFO process image stack pointer created. This stack frame consists of the arguments passed to the function as well as a dynamic amount of local variable space. The "stack pointer" is a register that holds the current stack frame stack pointer location of the top of the stack. Since this value is constantly changing as new values are pushed onto the top of the stack, many implementations also provide a "frame pointer" that is located near the beginning of a stack frame so that local variables can more easily be addressed relative to this value. The return address for function frame pointer process image frame pointer return address stack-overflow calls is also stored on the stack, and this is the cause of stack-overflow exploits since overflowing a local variable in a function can overwrite the return address of that function, potentially allowing a malicious user to execute any code he or she wants. Although stack-based attacks are by far the most common, it would also be possible to overrun the stack with a heap-based (malloc/free) attack. The C programming language does not perform automatic bounds checking on arrays or pointers as many other languages do. In addition, the standard C library is filled with a handful of very dangerous functions. strcpy(char *dest, const char *src) May overflow the dest buffer strcat(char *dest, const char *src) May overflow the dest buffer getwd(char *buf) May overflow the buf buffer gets(char *s) May overflow the s buffer [vf]scanf(const char *format, ...) May overflow its arguments. realpath(char *path, char resolved_path[]) May overflow the path buffer [v]sprintf(char *str, const char *format, ...) May overflow the str buffer. Example Buffer Overflow The following example code contains a buffer overflow designed to overwrite the return address and skip the instruction immediately following the function call. (Inspired by ) #include stdio.h void manipulate(char *buffer) { char newbuffer[80]; strcpy(newbuffer,buffer); } int main() { char ch,buffer[4096]; int i=0; while ((buffer[i++] = getchar()) != '\n') {}; i=1; manipulate(buffer); i=2; printf("The value of i is : %d\n",i); return 0; } Let us examine what the memory image of this process would look like if we were to input 160 spaces into our little program before hitting return. [XXX figure here!] Obviously more malicious input can be devised to execute actual compiled instructions (such as exec(/bin/sh)). Avoiding Buffer Overflows The most straightforward solution to the problem of stack-overflows is to always use length restricted memory and string copy functions. strncpy and strncat are part of the standard C library. string copy functions strncpy string copy functions strncat These functions accept a length value as a parameter which should be no larger than the size of the destination buffer. These functions will then copy up to `length' bytes from the source to the destination. However there are a number of problems with these functions. Neither function guarantees NUL termination if the size of the input buffer is as large as the NUL termination destination. The length parameter is also used inconsistently between strncpy and strncat so it is easy for programmers to get confused as to their proper usage. There is also a significant performance loss compared to strcpy when copying a short string into a large buffer since strncpy NUL fills up the size specified. In OpenBSD, another memory copy implementation has been OpenBSD created to get around these problem. The strlcpy and strlcat functions guarantee that they will always null terminate the destination string when given a non-zero length argument. For more information about these functions see . The OpenBSD strlcpy and strlcat instructions have been in FreeBSD since 3.3. string copy functions strlcpy string copy functions strlcat Compiler based run-time bounds checking bounds checking compiler-based Unfortunately there is still a very large assortment of code in public use which blindly copies memory around without using any of the bounded copy routines we just discussed. Fortunately, there is another solution. Several compiler add-ons and libraries exist to do Run-time bounds checking in C/C++. StackGuard gcc StackGuard is one such add-on that is implemented as a small patch to the gcc code generator. From the StackGuard + url="http://immunix.org/stackguard.html">StackGuard website:
"StackGuard detects and defeats stack smashing attacks by protecting the return address on the stack from being altered. StackGuard places a "canary" word next to the return address when a function is called. If the canary word has been altered when the function returns, then a stack smashing attack has been attempted, and the program responds by emitting an intruder alert into syslog, and then halts."
"StackGuard is implemented as a small patch to the gcc code generator, specifically the function_prolog() and function_epilog() routines. function_prolog() has been enhanced to lay down canaries on the stack when functions start, and function_epilog() checks canary integrity when the function exits. Any attempt at corrupting the return address is thus detected before the function returns."
 buffer overflow Recompiling your application with StackGuard is an effective means of stopping most buffer-overflow attacks, but it can still be compromised. Library based run-time bounds checking bounds checking library-based Compiler-based mechanisms are completely useless for binary-only software for which you cannot recompile. For these situations there are a number of libraries which re-implement the unsafe functions of the C-library (strcpy, fscanf, getwd, etc..) and ensure that these functions can never write past the stack pointer. libsafe libverify libparanoia Unfortunately these library-based defenses have a number of shortcomings. These libraries only protect against a very small set of security related issues and they neglect to fix the actual problem. These defenses may fail if the application was compiled with -fomit-frame-pointer. Also, the LD_PRELOAD and LD_LIBRARY_PATH environment variables can be overwritten/unset by the user. SetUID issues seteuid There are at least 6 different IDs associated with any given process. Because of this you have to be very careful with the access that your process has at any given time. In particular, all seteuid applications should give up their privileges as soon as it is no longer required. user IDs real user ID user IDs effective user ID The real user ID can only be changed by a superuser process. The login program sets this when a user initially logs in and it is seldom changed. The effective user ID is set by the exec() functions if a program has its seteuid bit set. An application can call seteuid() at any time to set the effective user ID to either the real user ID or the saved set-user-ID. When the effective user ID is set by exec() functions, the previous value is saved in the saved set-user-ID. Limiting your program's environment chroot() The traditional method of restricting a process is with the chroot() system call. This system call changes the root directory from which all other paths are referenced for a process and any child processes. For this call to succeed the process must have execute (search) permission on the directory being referenced. The new environment does not actually take effect until you chdir() into your new environment. It should also be noted that a process can easily break out of a chroot environment if it has root privilege. This could be accomplished by creating device nodes to read kernel memory, attaching a debugger to a process outside of the jail, or in many other creative ways. The behavior of the chroot() system call can be controlled somewhat with the kern.chroot_allow_open_directories sysctl variable. When this value is set to 0, chroot() will fail with EPERM if there are any directories open. If set to the default value of 1, then chroot() will fail with EPERM if there are any directories open and the process is already subject to a chroot() call. For any other value, the check for open directories will be bypassed completely. FreeBSD's jail functionality jail The concept of a Jail extends upon the chroot() by limiting the powers of the superuser to create a true `virtual server'. Once a prison is set up all network communication must take place through the specified IP address, and the power of "root privilege" in this jail is severely constrained. While in a prison, any tests of superuser power within the kernel using the suser() call will fail. However, some calls to suser() have been changed to a new interface suser_xxx(). This function is responsible for recognizing or denying access to superuser power for imprisoned processes. A superuser process within a jailed environment has the power to: Manipulate credential with setuid, seteuid, setgid, setegid, setgroups, setreuid, setregid, setlogin Set resource limits with setrlimit Modify some sysctl nodes (kern.hostname) chroot() Set flags on a vnode: chflags, fchflags Set attributes of a vnode such as file permission, owner, group, size, access time, and modification time. Bind to privileged ports in the Internet domain (ports < 1024) Jail is a very useful tool for running applications in a secure environment but it does have some shortcomings. Currently, the IPC mechanisms have not been converted to the suser_xxx so applications such as MySQL cannot be run within a jail. Superuser access may have a very limited meaning within a jail, but there is no way to specify exactly what "very limited" means. &posix;.1e Process Capabilities POSIX.1e Process Capabilities TrustedBSD &posix; has released a working draft that adds event auditing, access control lists, fine grained privileges, information labeling, and mandatory access control. This is a work in progress and is the focus of the TrustedBSD project. Some of the initial work has been committed to FreeBSD-current (cap_set_proc(3)). Trust An application should never assume that anything about the users environment is sane. This includes (but is certainly not limited to): user input, signals, environment variables, resources, IPC, mmaps, the filesystem working directory, file descriptors, the # of open files, etc. positive filtering data validation You should never assume that you can catch all forms of invalid input that a user might supply. Instead, your application should use positive filtering to only allow a specific subset of inputs that you deem safe. Improper data validation has been the cause of many exploits, especially with CGI scripts on the world wide web. For filenames you need to be extra careful about paths ("../", "/"), symbolic links, and shell escape characters. Perl Taint mode Perl has a really cool feature called "Taint" mode which can be used to prevent scripts from using data derived outside the program in an unsafe way. This mode will check command line arguments, environment variables, locale information, the results of certain syscalls (readdir(), readlink(), getpwxxx(), and all file input. Race Conditions A race condition is anomalous behavior caused by the unexpected dependence on the relative timing of events. In other words, a programmer incorrectly assumed that a particular event would always happen before another. race conditions signals race conditions access checks race conditions file opens Some of the common causes of race conditions are signals, access checks, and file opens. Signals are asynchronous events by nature so special care must be taken in dealing with them. Checking access with access(2) then open(2) is clearly non-atomic. Users can move files in between the two calls. Instead, privileged applications should seteuid() and then call open() directly. Along the same lines, an application should always set a proper umask before open() to obviate the need for spurious chmod() calls. diff --git a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml index 333162834f..13be068eff 100644 --- a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml +++ b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.sgml @@ -1,2358 +1,2358 @@ James Raynard Contributed by Murray Stokely Programming Tools Synopsis This chapter is an introduction to using some of the programming tools supplied with FreeBSD, although much of it will be applicable to many other versions of &unix;. It does not attempt to describe coding in any detail. Most of the chapter assumes little or no previous programming knowledge, although it is hoped that most programmers will find something of value in it. Introduction FreeBSD offers an excellent development environment. Compilers for C, C++, and Fortran and an assembler come with the basic system, not to mention a Perl interpreter and classic &unix; tools such as sed and awk. If that is not enough, there are many more compilers and interpreters in the Ports collection. FreeBSD is very compatible with standards such as &posix; and ANSI C, as well with its own BSD heritage, so it is possible to write applications that will compile and run with little or no modification on a wide range of platforms. However, all this power can be rather overwhelming at first if you have never written programs on a &unix; platform before. This document aims to help you get up and running, without getting too deeply into more advanced topics. The intention is that this document should give you enough of the basics to be able to make some sense of the documentation. Most of the document requires little or no knowledge of programming, although it does assume a basic competence with using &unix; and a willingness to learn! Introduction to Programming A program is a set of instructions that tell the computer to do various things; sometimes the instruction it has to perform depends on what happened when it performed a previous instruction. This section gives an overview of the two main ways in which you can give these instructions, or commands as they are usually called. One way uses an interpreter, the other a compiler. As human languages are too difficult for a computer to understand in an unambiguous way, commands are usually written in one or other languages specially designed for the purpose. Interpreters With an interpreter, the language comes as an environment, where you type in commands at a prompt and the environment executes them for you. For more complicated programs, you can type the commands into a file and get the interpreter to load the file and execute the commands in it. If anything goes wrong, many interpreters will drop you into a debugger to help you track down the problem. The advantage of this is that you can see the results of your commands immediately, and mistakes can be corrected readily. The biggest disadvantage comes when you want to share your programs with someone. They must have the same interpreter, or you must have some way of giving it to them, and they need to understand how to use it. Also users may not appreciate being thrown into a debugger if they press the wrong key! From a performance point of view, interpreters can use up a lot of memory, and generally do not generate code as efficiently as compilers. In my opinion, interpreted languages are the best way to start if you have not done any programming before. This kind of environment is typically found with languages like Lisp, Smalltalk, Perl and Basic. It could also be argued that the &unix; shell (sh, csh) is itself an interpreter, and many people do in fact write shell scripts to help with various housekeeping tasks on their machine. Indeed, part of the original &unix; philosophy was to provide lots of small utility programs that could be linked together in shell scripts to perform useful tasks. Interpreters available with FreeBSD Here is a list of interpreters that are available as FreeBSD + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/">FreeBSD packages, with a brief discussion of some of the more popular interpreted languages. To get one of these packages, all you need to do is to click on the hotlink for the package, to download the package and then install the package by running: &prompt.root; pkg_add package name as root. Obviously, you will need to have a fully functional FreeBSD 2.1.0 or later system for the package to work! BASIC Short for Beginner's All-purpose Symbolic Instruction Code. Developed in the 1950s for teaching University students to program and provided with every self-respecting personal computer in the 1980s, BASIC has been the first programming language for many programmers. It is also the foundation for Visual Basic. The Bywater + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/bwbasic.tgz">Bywater Basic Interpreter and the Phil + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/pbasic.tgz">Phil Cockroft's Basic Interpreter (formerly Rabbit Basic) are available as FreeBSD + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/">FreeBSD packages. Lisp A language that was developed in the late 1950s as an alternative to the number-crunching languages that were popular at the time. Instead of being based on numbers, Lisp is based on lists; in fact the name is short for List Processing. Very popular in AI (Artificial Intelligence) circles. Lisp is an extremely powerful and sophisticated language, but can be rather large and unwieldy. Various implementations of Lisp that can run on &unix; systems are available as packages for FreeBSD. - GNU Common Lisp, - CLISP + GNU Common Lisp, + CLISP by Bruno Haible and Michael Stoll, - CMUCL + CMUCL which includes a highly-optimizing compiler too, or simpler Lisp implementations, like - SLisp + SLisp which implements most of the Common Lisp constructs in a few hundred lines of C code. Perl Very popular with system administrators for writing scripts; also often used on World Wide Web servers for writing CGI scripts. Perl is available as a package + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/perl.tgz">package for all FreeBSD releases, and is installed as /usr/bin/perl in the base system of 4.x releases. Scheme A dialect of Lisp that is rather more compact and cleaner than Common Lisp. Popular in Universities as it is simple enough to teach to undergraduates as a first language, while it has a high enough level of abstraction to be used in research work. FreeBSD has packages of the Elk + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/elk.tgz">Elk Scheme Interpreter, the MIT + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/mit-scheme.tgz">MIT Scheme Interpreter and the SCM + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/scm.tgz">SCM Scheme Interpreter. Icon Icon is a high-level language with extensive facilities for processing strings and structures. A package + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/icon.tgz">package is available for FreeBSD. Logo Logo is a language that is easy to learn, and has been used as an introductory programming language in various courses. It is an excellent tool to work with when teaching programming in small ages, as it makes the creation of elaborate geometric shapes an easy task even for very small children. A package is available for FreeBSD of Brian Harvey's LOGO + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/Latest/ucblogo.tgz">LOGO Interpreter. Python Python is an Object-Oriented, interpreted language. Its advocates argue that it is one of the best languages to start programming with, since it is relatively easy to start with, but is not limited in comparison to other popular interpreted languages that are used for the development of large, complex applications (Perl and Tcl are two other languages that are popular for such tasks). A package of the latest version of Python for FreeBSD is available - here. + here. Tcl and Tk Tcl is an embeddable, interpreted language, that has become widely used and became popular mostly because of its portability to many platforms. It can be used both for quickly writing small, prototype applications, or (when combined with Tk, a GUI toolkit) fully-fledged, featureful programs. Various versions of Tcl are available as packages for FreeBSD. The latest version is, as of this writing, - Tcl + Tcl version 8.3. Compilers Compilers are rather different. First of all, you write your code in a file (or files) using an editor. You then run the compiler and see if it accepts your program. If it did not compile, grit your teeth and go back to the editor; if it did compile and gave you a program, you can run it either at a shell command prompt or in a debugger to see if it works properly. If you run it in the shell, you may get a core dump. Obviously, this is not quite as direct as using an interpreter. However it allows you to do a lot of things which are very difficult or even impossible with an interpreter, such as writing code which interacts closely with the operating system—or even writing your own operating system! It is also useful if you need to write very efficient code, as the compiler can take its time and optimize the code, which would not be acceptable in an interpreter. Moreover, distributing a program written for a compiler is usually more straightforward than one written for an interpreter—you can just give them a copy of the executable, assuming they have the same operating system as you. Compiled languages include Pascal, C and C++. C and C++ are rather unforgiving languages, and best suited to more experienced programmers; Pascal, on the other hand, was designed as an educational language, and is quite a good language to start with. FreeBSD does not include Pascal support in the base system, but both GNU Pascal Compiler (GPC) and the Free Pascal Compiler are available in the ports collection as lang/gpc and lang/fpc. As the edit-compile-run-debug cycle is rather tedious when using separate programs, many commercial compiler makers have produced Integrated Development Environments (IDEs for short). FreeBSD does not include an IDE in the base system, but devel/kdevelop is available in the ports tree and many use Emacs for this purpose. Using Emacs as an IDE is discussed in . Compiling with <command>cc</command> This section deals only with the GNU compiler for C and C++, since that comes with the base FreeBSD system. It can be invoked by either cc or gcc. The details of producing a program with an interpreter vary considerably between interpreters, and are usually well covered in the documentation and on-line help for the interpreter. Once you have written your masterpiece, the next step is to convert it into something that will (hopefully!) run on FreeBSD. This usually involves several steps, each of which is done by a separate program. Pre-process your source code to remove comments and do other tricks like expanding macros in C. Check the syntax of your code to see if you have obeyed the rules of the language. If you have not, it will complain! Convert the source code into assembly language—this is very close to machine code, but still understandable by humans. Allegedly. To be strictly accurate, cc converts the source code into its own, machine-independent p-code instead of assembly language at this stage. Convert the assembly language into machine code—yep, we are talking bits and bytes, ones and zeros here. Check that you have used things like functions and global variables in a consistent way. For example, if you have called a non-existent function, it will complain. If you are trying to produce an executable from several source code files, work out how to fit them all together. Work out how to produce something that the system's run-time loader will be able to load into memory and run. Finally, write the executable on the filesystem. The word compiling is often used to refer to just steps 1 to 4—the others are referred to as linking. Sometimes step 1 is referred to as pre-processing and steps 3-4 as assembling. Fortunately, almost all this detail is hidden from you, as cc is a front end that manages calling all these programs with the right arguments for you; simply typing &prompt.user; cc foobar.c will cause foobar.c to be compiled by all the steps above. If you have more than one file to compile, just do something like &prompt.user; cc foo.c bar.c Note that the syntax checking is just that—checking the syntax. It will not check for any logical mistakes you may have made, like putting the program into an infinite loop, or using a bubble sort when you meant to use a binary sort. In case you did not know, a binary sort is an efficient way of sorting things into order and a bubble sort is not. There are lots and lots of options for cc, which are all in the manual page. Here are a few of the most important ones, with examples of how to use them. The output name of the file. If you do not use this option, cc will produce an executable called a.out. The reasons for this are buried in the mists of history. &prompt.user; cc foobar.c executable is a.out &prompt.user; cc -o foobar foobar.c executable is foobar Just compile the file, do not link it. Useful for toy programs where you just want to check the syntax, or if you are using a Makefile. &prompt.user; cc -c foobar.c This will produce an object file (not an executable) called foobar.o. This can be linked together with other object files into an executable. Create a debug version of the executable. This makes the compiler put information into the executable about which line of which source file corresponds to which function call. A debugger can use this information to show the source code as you step through the program, which is very useful; the disadvantage is that all this extra information makes the program much bigger. Normally, you compile with while you are developing a program and then compile a release version without when you are satisfied it works properly. &prompt.user; cc -g foobar.c This will produce a debug version of the program. Note, we did not use the flag to specify the executable name, so we will get an executable called a.out. Producing a debug version called foobar is left as an exercise for the reader! Create an optimized version of the executable. The compiler performs various clever tricks to try to produce an executable that runs faster than normal. You can add a number after the to specify a higher level of optimization, but this often exposes bugs in the compiler's optimizer. For instance, the version of cc that comes with the 2.1.0 release of FreeBSD is known to produce bad code with the option in some circumstances. Optimization is usually only turned on when compiling a release version. &prompt.user; cc -O -o foobar foobar.c This will produce an optimized version of foobar. The following three flags will force cc to check that your code complies to the relevant international standard, often referred to as the ANSI standard, though strictly speaking it is an ISO standard. Enable all the warnings which the authors of cc believe are worthwhile. Despite the name, it will not enable all the warnings cc is capable of. Turn off most, but not all, of the non-ANSI C features provided by cc. Despite the name, it does not guarantee strictly that your code will comply to the standard. Turn off all cc's non-ANSI C features. Without these flags, cc will allow you to use some of its non-standard extensions to the standard. Some of these are very useful, but will not work with other compilers—in fact, one of the main aims of the standard is to allow people to write code that will work with any compiler on any system. This is known as portable code. Generally, you should try to make your code as portable as possible, as otherwise you may have to completely rewrite the program later to get it to work somewhere else—and who knows what you may be using in a few years time? &prompt.user; cc -Wall -ansi -pedantic -o foobar foobar.c This will produce an executable foobar after checking foobar.c for standard compliance. Specify a function library to be used during when linking. The most common example of this is when compiling a program that uses some of the mathematical functions in C. Unlike most other platforms, these are in a separate library from the standard C one and you have to tell the compiler to add it. The rule is that if the library is called libsomething.a, you give cc the argument . For example, the math library is libm.a, so you give cc the argument . A common gotcha with the math library is that it has to be the last library on the command line. &prompt.user; cc -o foobar foobar.c -lm This will link the math library functions into foobar. If you are compiling C++ code, you need to add , or if you are using FreeBSD 2.2 or later, to the command line argument to link the C++ library functions. Alternatively, you can run c++ instead of cc, which does this for you. c++ can also be invoked as g++ on FreeBSD. &prompt.user; cc -o foobar foobar.cc -lg++ For FreeBSD 2.1.6 and earlier &prompt.user; cc -o foobar foobar.cc -lstdc++ For FreeBSD 2.2 and later &prompt.user; c++ -o foobar foobar.cc Each of these will both produce an executable foobar from the C++ source file foobar.cc. Note that, on &unix; systems, C++ source files traditionally end in .C, .cxx or .cc, rather than the &ms-dos; style .cpp (which was already used for something else). gcc used to rely on this to work out what kind of compiler to use on the source file; however, this restriction no longer applies, so you may now call your C++ files .cpp with impunity! Common <command>cc</command> Queries and Problems I am trying to write a program which uses the sin() function and I get an error like this. What does it mean? /var/tmp/cc0143941.o: Undefined symbol `_sin' referenced from text segment When using mathematical functions like sin(), you have to tell cc to link in the math library, like so: &prompt.user; cc -o foobar foobar.c -lm All right, I wrote this simple program to practice using . All it does is raise 2.1 to the power of 6. #include <stdio.h> int main() { float f; f = pow(2.1, 6); printf("2.1 ^ 6 = %f\n", f); return 0; } and I compiled it as: &prompt.user; cc temp.c -lm like you said I should, but I get this when I run it: &prompt.user; ./a.out 2.1 ^ 6 = 1023.000000 This is not the right answer! What is going on? When the compiler sees you call a function, it checks if it has already seen a prototype for it. If it has not, it assumes the function returns an int, which is definitely not what you want here. So how do I fix this? The prototypes for the mathematical functions are in math.h. If you include this file, the compiler will be able to find the prototype and it will stop doing strange things to your calculation! #include <math.h> #include <stdio.h> int main() { ... After recompiling it as you did before, run it: &prompt.user; ./a.out 2.1 ^ 6 = 85.766121 If you are using any of the mathematical functions, always include math.h and remember to link in the math library. I compiled a file called foobar.c and I cannot find an executable called foobar. Where's it gone? Remember, cc will call the executable a.out unless you tell it differently. Use the option: &prompt.user; cc -o foobar foobar.c OK, I have an executable called foobar, I can see it when I run ls, but when I type in foobar at the command prompt it tells me there is no such file. Why can it not find it? Unlike &ms-dos;, &unix; does not look in the current directory when it is trying to find out which executable you want it to run, unless you tell it to. Either type ./foobar, which means run the file called foobar in the current directory, or change your PATH environment variable so that it looks something like bin:/usr/bin:/usr/local/bin:. The dot at the end means look in the current directory if it is not in any of the others. I called my executable test, but nothing happens when I run it. What is going on? Most &unix; systems have a program called test in /usr/bin and the shell is picking that one up before it gets to checking the current directory. Either type: &prompt.user; ./test or choose a better name for your program! I compiled my program and it seemed to run all right at first, then there was an error and it said something about core dumped. What does that mean? The name core dump dates back to the very early days of &unix;, when the machines used core memory for storing data. Basically, if the program failed under certain conditions, the system would write the contents of core memory to disk in a file called core, which the programmer could then pore over to find out what went wrong. Fascinating stuff, but what I am supposed to do now? Use gdb to analyze the core (see ). When my program dumped core, it said something about a segmentation fault. What is that? This basically means that your program tried to perform some sort of illegal operation on memory; &unix; is designed to protect the operating system and other programs from rogue programs. Common causes for this are: Trying to write to a NULL pointer, eg char *foo = NULL; strcpy(foo, "bang!"); Using a pointer that has not been initialized, eg char *foo; strcpy(foo, "bang!"); The pointer will have some random value that, with luck, will point into an area of memory that is not available to your program and the kernel will kill your program before it can do any damage. If you are unlucky, it will point somewhere inside your own program and corrupt one of your data structures, causing the program to fail mysteriously. Trying to access past the end of an array, eg int bar[20]; bar[27] = 6; Trying to store something in read-only memory, eg char *foo = "My string"; strcpy(foo, "bang!"); &unix; compilers often put string literals like "My string" into read-only areas of memory. Doing naughty things with malloc() and free(), eg char bar[80]; free(bar); or char *foo = malloc(27); free(foo); free(foo); Making one of these mistakes will not always lead to an error, but they are always bad practice. Some systems and compilers are more tolerant than others, which is why programs that ran well on one system can crash when you try them on an another. Sometimes when I get a core dump it says bus error. It says in my &unix; book that this means a hardware problem, but the computer still seems to be working. Is this true? No, fortunately not (unless of course you really do have a hardware problem…). This is usually another way of saying that you accessed memory in a way you should not have. This dumping core business sounds as though it could be quite useful, if I can make it happen when I want to. Can I do this, or do I have to wait until there is an error? Yes, just go to another console or xterm, do &prompt.user; ps to find out the process ID of your program, and do &prompt.user; kill -ABRT pid where pid is the process ID you looked up. This is useful if your program has got stuck in an infinite loop, for instance. If your program happens to trap SIGABRT, there are several other signals which have a similar effect. Alternatively, you can create a core dump from inside your program, by calling the abort() function. See the manual page of &man.abort.3; to learn more. If you want to create a core dump from outside your program, but do not want the process to terminate, you can use the gcore program. See the manual page of &man.gcore.1; for more information. Make What is <command>make</command>? When you are working on a simple program with only one or two source files, typing in &prompt.user; cc file1.c file2.c is not too bad, but it quickly becomes very tedious when there are several files—and it can take a while to compile, too. One way to get around this is to use object files and only recompile the source file if the source code has changed. So we could have something like: &prompt.user; cc file1.o file2.o … file37.c … if we had changed file37.c, but not any of the others, since the last time we compiled. This may speed up the compilation quite a bit, but does not solve the typing problem. Or we could write a shell script to solve the typing problem, but it would have to re-compile everything, making it very inefficient on a large project. What happens if we have hundreds of source files lying about? What if we are working in a team with other people who forget to tell us when they have changed one of their source files that we use? Perhaps we could put the two solutions together and write something like a shell script that would contain some kind of magic rule saying when a source file needs compiling. Now all we need now is a program that can understand these rules, as it is a bit too complicated for the shell. This program is called make. It reads in a file, called a makefile, that tells it how different files depend on each other, and works out which files need to be re-compiled and which ones do not. For example, a rule could say something like if fromboz.o is older than fromboz.c, that means someone must have changed fromboz.c, so it needs to be re-compiled. The makefile also has rules telling make how to re-compile the source file, making it a much more powerful tool. Makefiles are typically kept in the same directory as the source they apply to, and can be called makefile, Makefile or MAKEFILE. Most programmers use the name Makefile, as this puts it near the top of a directory listing, where it can easily be seen. They do not use the MAKEFILE form as block capitals are often used for documentation files like README. Example of using <command>make</command> Here is a very simple make file: foo: foo.c cc -o foo foo.c It consists of two lines, a dependency line and a creation line. The dependency line here consists of the name of the program (known as the target), followed by a colon, then whitespace, then the name of the source file. When make reads this line, it looks to see if foo exists; if it exists, it compares the time foo was last modified to the time foo.c was last modified. If foo does not exist, or is older than foo.c, it then looks at the creation line to find out what to do. In other words, this is the rule for working out when foo.c needs to be re-compiled. The creation line starts with a tab (press the tab key) and then the command you would type to create foo if you were doing it at a command prompt. If foo is out of date, or does not exist, make then executes this command to create it. In other words, this is the rule which tells make how to re-compile foo.c. So, when you type make, it will make sure that foo is up to date with respect to your latest changes to foo.c. This principle can be extended to Makefiles with hundreds of targets—in fact, on FreeBSD, it is possible to compile the entire operating system just by typing make world in the appropriate directory! Another useful property of makefiles is that the targets do not have to be programs. For instance, we could have a make file that looks like this: foo: foo.c cc -o foo foo.c install: cp foo /home/me We can tell make which target we want to make by typing: &prompt.user; make target make will then only look at that target and ignore any others. For example, if we type make foo with the makefile above, make will ignore the install target. If we just type make on its own, make will always look at the first target and then stop without looking at any others. So if we typed make here, it will just go to the foo target, re-compile foo if necessary, and then stop without going on to the install target. Notice that the install target does not actually depend on anything! This means that the command on the following line is always executed when we try to make that target by typing make install. In this case, it will copy foo into the user's home directory. This is often used by application makefiles, so that the application can be installed in the correct directory when it has been correctly compiled. This is a slightly confusing subject to try to explain. If you do not quite understand how make works, the best thing to do is to write a simple program like hello world and a make file like the one above and experiment. Then progress to using more than one source file, or having the source file include a header file. The touch command is very useful here—it changes the date on a file without you having to edit it. Make and include-files C code often starts with a list of files to include, for example stdio.h. Some of these files are system-include files, some of them are from the project you are now working on: #include <stdio.h> #include "foo.h" int main(.... To make sure that this file is recompiled the moment foo.h is changed, you have to add it in your Makefile: foo: foo.c foo.h The moment your project is getting bigger and you have more and more own include-files to maintain, it will be a pain to keep track of all include files and the files which are depending on it. If you change an include-file but forget to recompile all the files which are depending on it, the results will be devastating. gcc has an option to analyze your files and to produce a list of include-files and their dependencies: . If you add this to your Makefile: depend: gcc -E -MM *.c > .depend and run make depend, the file .depend will appear with a list of object-files, C-files and the include-files: foo.o: foo.c foo.h If you change foo.h, next time you run make all files depending on foo.h will be recompiled. Do not forget to run make depend each time you add an include-file to one of your files. FreeBSD Makefiles Makefiles can be rather complicated to write. Fortunately, BSD-based systems like FreeBSD come with some very powerful ones as part of the system. One very good example of this is the FreeBSD ports system. Here is the essential part of a typical ports Makefile: MASTER_SITES= ftp://freefall.cdrom.com/pub/FreeBSD/LOCAL_PORTS/ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz .include <bsd.port.mk> Now, if we go to the directory for this port and type make, the following happens: A check is made to see if the source code for this port is already on the system. If it is not, an FTP connection to the URL in MASTER_SITES is set up to download the source. The checksum for the source is calculated and compared it with one for a known, good, copy of the source. This is to make sure that the source was not corrupted while in transit. Any changes required to make the source work on FreeBSD are applied—this is known as patching. Any special configuration needed for the source is done. (Many &unix; program distributions try to work out which version of &unix; they are being compiled on and which optional &unix; features are present—this is where they are given the information in the FreeBSD ports scenario). The source code for the program is compiled. In effect, we change to the directory where the source was unpacked and do make—the program's own make file has the necessary information to build the program. We now have a compiled version of the program. If we wish, we can test it now; when we feel confident about the program, we can type make install. This will cause the program and any supporting files it needs to be copied into the correct location; an entry is also made into a package database, so that the port can easily be uninstalled later if we change our mind about it. Now I think you will agree that is rather impressive for a four line script! The secret lies in the last line, which tells make to look in the system makefile called bsd.port.mk. It is easy to overlook this line, but this is where all the clever stuff comes from—someone has written a makefile that tells make to do all the things above (plus a couple of other things I did not mention, including handling any errors that may occur) and anyone can get access to that just by putting a single line in their own make file! If you want to have a look at these system makefiles, they are in /usr/share/mk, but it is probably best to wait until you have had a bit of practice with makefiles, as they are very complicated (and if you do look at them, make sure you have a flask of strong coffee handy!) More advanced uses of <command>make</command> Make is a very powerful tool, and can do much more than the simple example above shows. Unfortunately, there are several different versions of make, and they all differ considerably. The best way to learn what they can do is probably to read the documentation—hopefully this introduction will have given you a base from which you can do this. The version of make that comes with FreeBSD is the Berkeley make; there is a tutorial for it in /usr/share/doc/psd/12.make. To view it, do &prompt.user; zmore paper.ascii.gz in that directory. Many applications in the ports use GNU make, which has a very good set of info pages. If you have installed any of these ports, GNU make will automatically have been installed as gmake. It is also available as a port and package in its own right. To view the info pages for GNU make, you will have to edit the dir file in the /usr/local/info directory to add an entry for it. This involves adding a line like * Make: (make). The GNU Make utility. to the file. Once you have done this, you can type info and then select make from the menu (or in Emacs, do C-h i). Debugging The Debugger The debugger that comes with FreeBSD is called gdb (GNU debugger). You start it up by typing &prompt.user; gdb progname although most people prefer to run it inside Emacs. You can do this by: M-x gdb RET progname RET Using a debugger allows you to run the program under more controlled circumstances. Typically, you can step through the program a line at a time, inspect the value of variables, change them, tell the debugger to run up to a certain point and then stop, and so on. You can even attach to a program that is already running, or load a core file to investigate why the program crashed. It is even possible to debug the kernel, though that is a little trickier than the user applications we will be discussing in this section. gdb has quite good on-line help, as well as a set of info pages, so this section will concentrate on a few of the basic commands. Finally, if you find its text-based command-prompt style off-putting, there is a graphical front-end for it (xxgdb) in the ports + url="&url.base;/ports/devel.html">xxgdb) in the ports collection. This section is intended to be an introduction to using gdb and does not cover specialized topics such as debugging the kernel. Running a program in the debugger You will need to have compiled the program with the option to get the most out of using gdb. It will work without, but you will only see the name of the function you are in, instead of the source code. If you see a line like: … (no debugging symbols found) … when gdb starts up, you will know that the program was not compiled with the option. At the gdb prompt, type break main. This will tell the debugger to skip over the preliminary set-up code in the program and start at the beginning of your code. Now type run to start the program—it will start at the beginning of the set-up code and then get stopped by the debugger when it calls main(). (If you have ever wondered where main() gets called from, now you know!). You can now step through the program, a line at a time, by pressing n. If you get to a function call, you can step into it by pressing s. Once you are in a function call, you can return from stepping into a function call by pressing f. You can also use up and down to take a quick look at the caller. Here is a simple example of how to spot a mistake in a program with gdb. This is our program (with a deliberate mistake): #include <stdio.h> int bazz(int anint); main() { int i; printf("This is my program\n"); bazz(i); return 0; } int bazz(int anint) { printf("You gave me %d\n", anint); return anint; } This program sets i to be 5 and passes it to a function bazz() which prints out the number we gave it. When we compile and run the program we get &prompt.user; cc -g -o temp temp.c &prompt.user; ./temp This is my program anint = 4231 That was not what we expected! Time to see what is going on! &prompt.user; gdb temp GDB is free software and you are welcome to distribute copies of it under certain conditions; type "show copying" to see the conditions. There is absolutely no warranty for GDB; type "show warranty" for details. GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. (gdb) break main Skip the set-up code Breakpoint 1 at 0x160f: file temp.c, line 9. gdb puts breakpoint at main() (gdb) run Run as far as main() Starting program: /home/james/tmp/temp Program starts running Breakpoint 1, main () at temp.c:9 gdb stops at main() (gdb) n Go to next line This is my program Program prints out (gdb) s step into bazz() bazz (anint=4231) at temp.c:17 gdb displays stack frame (gdb) Hang on a minute! How did anint get to be 4231? Did we not we set it to be 5 in main()? Let's move up to main() and have a look. (gdb) up Move up call stack #1 0x1625 in main () at temp.c:11 gdb displays stack frame (gdb) p i Show us the value of i $1 = 4231 gdb displays 4231 Oh dear! Looking at the code, we forgot to initialize i. We meant to put … main() { int i; i = 5; printf("This is my program\n"); … but we left the i=5; line out. As we did not initialize i, it had whatever number happened to be in that area of memory when the program ran, which in this case happened to be 4231. gdb displays the stack frame every time we go into or out of a function, even if we are using up and down to move around the call stack. This shows the name of the function and the values of its arguments, which helps us keep track of where we are and what is going on. (The stack is a storage area where the program stores information about the arguments passed to functions and where to go when it returns from a function call). Examining a core file A core file is basically a file which contains the complete state of the process when it crashed. In the good old days, programmers had to print out hex listings of core files and sweat over machine code manuals, but now life is a bit easier. Incidentally, under FreeBSD and other 4.4BSD systems, a core file is called progname.core instead of just core, to make it clearer which program a core file belongs to. To examine a core file, start up gdb in the usual way. Instead of typing break or run, type (gdb) core progname.core If you are not in the same directory as the core file, you will have to do dir /path/to/core/file first. You should see something like this: &prompt.user; gdb a.out GDB is free software and you are welcome to distribute copies of it under certain conditions; type "show copying" to see the conditions. There is absolutely no warranty for GDB; type "show warranty" for details. GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. (gdb) core a.out.core Core was generated by `a.out'. Program terminated with signal 11, Segmentation fault. Cannot access memory at address 0x7020796d. #0 0x164a in bazz (anint=0x5) at temp.c:17 (gdb) In this case, the program was called a.out, so the core file is called a.out.core. We can see that the program crashed due to trying to access an area in memory that was not available to it in a function called bazz. Sometimes it is useful to be able to see how a function was called, as the problem could have occurred a long way up the call stack in a complex program. The bt command causes gdb to print out a back-trace of the call stack: (gdb) bt #0 0x164a in bazz (anint=0x5) at temp.c:17 #1 0xefbfd888 in end () #2 0x162c in main () at temp.c:11 (gdb) The end() function is called when a program crashes; in this case, the bazz() function was called from main(). Attaching to a running program One of the neatest features about gdb is that it can attach to a program that is already running. Of course, that assumes you have sufficient permissions to do so. A common problem is when you are stepping through a program that forks, and you want to trace the child, but the debugger will only let you trace the parent. What you do is start up another gdb, use ps to find the process ID for the child, and do (gdb) attach pid in gdb, and then debug as usual. That is all very well, you are probably thinking, but by the time I have done that, the child process will be over the hill and far away. Fear not, gentle reader, here is how to do it (courtesy of the gdb info pages): … if ((pid = fork()) < 0) /* _Always_ check this */ error(); else if (pid == 0) { /* child */ int PauseMode = 1; while (PauseMode) sleep(10); /* Wait until someone attaches to us */ … } else { /* parent */ … Now all you have to do is attach to the child, set PauseMode to 0, and wait for the sleep() call to return! Using Emacs as a Development Environment Emacs Unfortunately, &unix; systems do not come with the kind of everything-you-ever-wanted-and-lots-more-you-did-not-in-one-gigantic-package integrated development environments that other systems have. Some powerful, free IDEs now exist, such as KDevelop in the ports collection. However, it is possible to set up your own environment. It may not be as pretty, and it may not be quite as integrated, but you can set it up the way you want it. And it is free. And you have the source to it. The key to it all is Emacs. Now there are some people who loathe it, but many who love it. If you are one of the former, I am afraid this section will hold little of interest to you. Also, you will need a fair amount of memory to run it—I would recommend 8MB in text mode and 16MB in X as the bare minimum to get reasonable performance. Emacs is basically a highly customizable editor—indeed, it has been customized to the point where it is more like an operating system than an editor! Many developers and sysadmins do in fact spend practically all their time working inside Emacs, leaving it only to log out. It is impossible even to summarize everything Emacs can do here, but here are some of the features of interest to developers: Very powerful editor, allowing search-and-replace on both strings and regular expressions (patterns), jumping to start/end of block expression, etc, etc. Pull-down menus and online help. Language-dependent syntax highlighting and indentation. Completely customizable. You can compile and debug programs within Emacs. On a compilation error, you can jump to the offending line of source code. Friendly-ish front-end to the info program used for reading GNU hypertext documentation, including the documentation on Emacs itself. Friendly front-end to gdb, allowing you to look at the source code as you step through your program. You can read Usenet news and mail while your program is compiling. And doubtless many more that I have overlooked. Emacs can be installed on FreeBSD using the Emacs + url="&url.base;/ports/editors.html">the Emacs port. Once it is installed, start it up and do C-h t to read an Emacs tutorial—that means hold down the control key, press h, let go of the control key, and then press t. (Alternatively, you can you use the mouse to select Emacs Tutorial from the Help menu). Although Emacs does have menus, it is well worth learning the key bindings, as it is much quicker when you are editing something to press a couple of keys than to try to find the mouse and then click on the right place. And, when you are talking to seasoned Emacs users, you will find they often casually throw around expressions like M-x replace-s RET foo RET bar RET so it is useful to know what they mean. And in any case, Emacs has far too many useful functions for them to all fit on the menu bars. Fortunately, it is quite easy to pick up the key-bindings, as they are displayed next to the menu item. My advice is to use the menu item for, say, opening a file until you understand how it works and feel confident with it, then try doing C-x C-f. When you are happy with that, move on to another menu command. If you can not remember what a particular combination of keys does, select Describe Key from the Help menu and type it in—Emacs will tell you what it does. You can also use the Command Apropos menu item to find out all the commands which contain a particular word in them, with the key binding next to it. By the way, the expression above means hold down the Meta key, press x, release the Meta key, type replace-s (short for replace-string—another feature of Emacs is that you can abbreviate commands), press the return key, type foo (the string you want replaced), press the return key, type bar (the string you want to replace foo with) and press return again. Emacs will then do the search-and-replace operation you have just requested. If you are wondering what on earth the Meta key is, it is a special key that many &unix; workstations have. Unfortunately, PC's do not have one, so it is usually the alt key (or if you are unlucky, the escape key). Oh, and to get out of Emacs, do C-x C-c (that means hold down the control key, press x, press c and release the control key). If you have any unsaved files open, Emacs will ask you if you want to save them. (Ignore the bit in the documentation where it says C-z is the usual way to leave Emacs—that leaves Emacs hanging around in the background, and is only really useful if you are on a system which does not have virtual terminals). Configuring Emacs Emacs does many wonderful things; some of them are built in, some of them need to be configured. Instead of using a proprietary macro language for configuration, Emacs uses a version of Lisp specially adapted for editors, known as Emacs Lisp. Working with Emacs Lisp can be quite helpful if you want to go on and learn something like Common Lisp. Emacs Lisp has many features of Common Lisp, although it is considerably smaller (and thus easier to master). The best way to learn Emacs Lisp is to download the Emacs + url="ftp://ftp.gnu.org/old-gnu/emacs/elisp-manual-19-2.4.tar.gz">Emacs Tutorial However, there is no need to actually know any Lisp to get started with configuring Emacs, as I have included a sample .emacs file, which should be enough to get you started. Just copy it into your home directory and restart Emacs if it is already running; it will read the commands from the file and (hopefully) give you a useful basic setup. A sample <filename>.emacs</filename> file Unfortunately, there is far too much here to explain it in detail; however there are one or two points worth mentioning. Everything beginning with a ; is a comment and is ignored by Emacs. In the first line, the -*- Emacs-Lisp -*- is so that we can edit the .emacs file itself within Emacs and get all the fancy features for editing Emacs Lisp. Emacs usually tries to guess this based on the filename, and may not get it right for .emacs. The tab key is bound to an indentation function in some modes, so when you press the tab key, it will indent the current line of code. If you want to put a tab character in whatever you are writing, hold the control key down while you are pressing the tab key. This file supports syntax highlighting for C, C++, Perl, Lisp and Scheme, by guessing the language from the filename. Emacs already has a pre-defined function called next-error. In a compilation output window, this allows you to move from one compilation error to the next by doing M-n; we define a complementary function, previous-error, that allows you to go to a previous error by doing M-p. The nicest feature of all is that C-c C-c will open up the source file in which the error occurred and jump to the appropriate line. We enable Emacs's ability to act as a server, so that if you are doing something outside Emacs and you want to edit a file, you can just type in &prompt.user; emacsclient filename and then you can edit the file in your Emacs! Many Emacs users set their EDITOR environment to emacsclient so this happens every time they need to edit a file. A sample <filename>.emacs</filename> file ;; -*-Emacs-Lisp-*- ;; This file is designed to be re-evaled; use the variable first-time ;; to avoid any problems with this. (defvar first-time t "Flag signifying this is the first time that .emacs has been evaled") ;; Meta (global-set-key "\M- " 'set-mark-command) (global-set-key "\M-\C-h" 'backward-kill-word) (global-set-key "\M-\C-r" 'query-replace) (global-set-key "\M-r" 'replace-string) (global-set-key "\M-g" 'goto-line) (global-set-key "\M-h" 'help-command) ;; Function keys (global-set-key [f1] 'manual-entry) (global-set-key [f2] 'info) (global-set-key [f3] 'repeat-complex-command) (global-set-key [f4] 'advertised-undo) (global-set-key [f5] 'eval-current-buffer) (global-set-key [f6] 'buffer-menu) (global-set-key [f7] 'other-window) (global-set-key [f8] 'find-file) (global-set-key [f9] 'save-buffer) (global-set-key [f10] 'next-error) (global-set-key [f11] 'compile) (global-set-key [f12] 'grep) (global-set-key [C-f1] 'compile) (global-set-key [C-f2] 'grep) (global-set-key [C-f3] 'next-error) (global-set-key [C-f4] 'previous-error) (global-set-key [C-f5] 'display-faces) (global-set-key [C-f8] 'dired) (global-set-key [C-f10] 'kill-compilation) ;; Keypad bindings (global-set-key [up] "\C-p") (global-set-key [down] "\C-n") (global-set-key [left] "\C-b") (global-set-key [right] "\C-f") (global-set-key [home] "\C-a") (global-set-key [end] "\C-e") (global-set-key [prior] "\M-v") (global-set-key [next] "\C-v") (global-set-key [C-up] "\M-\C-b") (global-set-key [C-down] "\M-\C-f") (global-set-key [C-left] "\M-b") (global-set-key [C-right] "\M-f") (global-set-key [C-home] "\M-<") (global-set-key [C-end] "\M->") (global-set-key [C-prior] "\M-<") (global-set-key [C-next] "\M->") ;; Mouse (global-set-key [mouse-3] 'imenu) ;; Misc (global-set-key [C-tab] "\C-q\t") ; Control tab quotes a tab. (setq backup-by-copying-when-mismatch t) ;; Treat 'y' or <CR> as yes, 'n' as no. (fset 'yes-or-no-p 'y-or-n-p) (define-key query-replace-map [return] 'act) (define-key query-replace-map [?\C-m] 'act) ;; Load packages (require 'desktop) (require 'tar-mode) ;; Pretty diff mode (autoload 'ediff-buffers "ediff" "Intelligent Emacs interface to diff" t) (autoload 'ediff-files "ediff" "Intelligent Emacs interface to diff" t) (autoload 'ediff-files-remote "ediff" "Intelligent Emacs interface to diff") (if first-time (setq auto-mode-alist (append '(("\\.cpp$" . c++-mode) ("\\.hpp$" . c++-mode) ("\\.lsp$" . lisp-mode) ("\\.scm$" . scheme-mode) ("\\.pl$" . perl-mode) ) auto-mode-alist))) ;; Auto font lock mode (defvar font-lock-auto-mode-list (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'lisp-mode 'perl-mode 'scheme-mode) "List of modes to always start in font-lock-mode") (defvar font-lock-mode-keyword-alist '((c++-c-mode . c-font-lock-keywords) (perl-mode . perl-font-lock-keywords)) "Associations between modes and keywords") (defun font-lock-auto-mode-select () "Automatically select font-lock-mode if the current major mode is in font-lock-auto-mode-list" (if (memq major-mode font-lock-auto-mode-list) (progn (font-lock-mode t)) ) ) (global-set-key [M-f1] 'font-lock-fontify-buffer) ;; New dabbrev stuff ;(require 'new-dabbrev) (setq dabbrev-always-check-other-buffers t) (setq dabbrev-abbrev-char-regexp "\\sw\\|\\s_") (add-hook 'emacs-lisp-mode-hook '(lambda () (set (make-local-variable 'dabbrev-case-fold-search) nil) (set (make-local-variable 'dabbrev-case-replace) nil))) (add-hook 'c-mode-hook '(lambda () (set (make-local-variable 'dabbrev-case-fold-search) nil) (set (make-local-variable 'dabbrev-case-replace) nil))) (add-hook 'text-mode-hook '(lambda () (set (make-local-variable 'dabbrev-case-fold-search) t) (set (make-local-variable 'dabbrev-case-replace) t))) ;; C++ and C mode... (defun my-c++-mode-hook () (setq tab-width 4) (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) (define-key c++-mode-map "\C-ce" 'c-comment-edit) (setq c++-auto-hungry-initial-state 'none) (setq c++-delete-function 'backward-delete-char) (setq c++-tab-always-indent t) (setq c-indent-level 4) (setq c-continued-statement-offset 4) (setq c++-empty-arglist-indent 4)) (defun my-c-mode-hook () (setq tab-width 4) (define-key c-mode-map "\C-m" 'reindent-then-newline-and-indent) (define-key c-mode-map "\C-ce" 'c-comment-edit) (setq c-auto-hungry-initial-state 'none) (setq c-delete-function 'backward-delete-char) (setq c-tab-always-indent t) ;; BSD-ish indentation style (setq c-indent-level 4) (setq c-continued-statement-offset 4) (setq c-brace-offset -4) (setq c-argdecl-indent 0) (setq c-label-offset -4)) ;; Perl mode (defun my-perl-mode-hook () (setq tab-width 4) (define-key c++-mode-map "\C-m" 'reindent-then-newline-and-indent) (setq perl-indent-level 4) (setq perl-continued-statement-offset 4)) ;; Scheme mode... (defun my-scheme-mode-hook () (define-key scheme-mode-map "\C-m" 'reindent-then-newline-and-indent)) ;; Emacs-Lisp mode... (defun my-lisp-mode-hook () (define-key lisp-mode-map "\C-m" 'reindent-then-newline-and-indent) (define-key lisp-mode-map "\C-i" 'lisp-indent-line) (define-key lisp-mode-map "\C-j" 'eval-print-last-sexp)) ;; Add all of the hooks... (add-hook 'c++-mode-hook 'my-c++-mode-hook) (add-hook 'c-mode-hook 'my-c-mode-hook) (add-hook 'scheme-mode-hook 'my-scheme-mode-hook) (add-hook 'emacs-lisp-mode-hook 'my-lisp-mode-hook) (add-hook 'lisp-mode-hook 'my-lisp-mode-hook) (add-hook 'perl-mode-hook 'my-perl-mode-hook) ;; Complement to next-error (defun previous-error (n) "Visit previous compilation error message and corresponding source code." (interactive "p") (next-error (- n))) ;; Misc... (transient-mark-mode 1) (setq mark-even-if-inactive t) (setq visible-bell nil) (setq next-line-add-newlines nil) (setq compile-command "make") (setq suggest-key-bindings nil) (put 'eval-expression 'disabled nil) (put 'narrow-to-region 'disabled nil) (put 'set-goal-column 'disabled nil) (if (>= emacs-major-version 21) (setq show-trailing-whitespace t)) ;; Elisp archive searching (autoload 'format-lisp-code-directory "lispdir" nil t) (autoload 'lisp-dir-apropos "lispdir" nil t) (autoload 'lisp-dir-retrieve "lispdir" nil t) (autoload 'lisp-dir-verify "lispdir" nil t) ;; Font lock mode (defun my-make-face (face color &optional bold) "Create a face from a color and optionally make it bold" (make-face face) (copy-face 'default face) (set-face-foreground face color) (if bold (make-face-bold face)) ) (if (eq window-system 'x) (progn (my-make-face 'blue "blue") (my-make-face 'red "red") (my-make-face 'green "dark green") (setq font-lock-comment-face 'blue) (setq font-lock-string-face 'bold) (setq font-lock-type-face 'bold) (setq font-lock-keyword-face 'bold) (setq font-lock-function-name-face 'red) (setq font-lock-doc-string-face 'green) (add-hook 'find-file-hooks 'font-lock-auto-mode-select) (setq baud-rate 1000000) (global-set-key "\C-cmm" 'menu-bar-mode) (global-set-key "\C-cms" 'scroll-bar-mode) (global-set-key [backspace] 'backward-delete-char) ; (global-set-key [delete] 'delete-char) (standard-display-european t) (load-library "iso-transl"))) ;; X11 or PC using direct screen writes (if window-system (progn ;; (global-set-key [M-f1] 'hilit-repaint-command) ;; (global-set-key [M-f2] [?\C-u M-f1]) (setq hilit-mode-enable-list '(not text-mode c-mode c++-mode emacs-lisp-mode lisp-mode scheme-mode) hilit-auto-highlight nil hilit-auto-rehighlight 'visible hilit-inhibit-hooks nil hilit-inhibit-rebinding t) (require 'hilit19) (require 'paren)) (setq baud-rate 2400) ; For slow serial connections ) ;; TTY type terminal (if (and (not window-system) (not (equal system-type 'ms-dos))) (progn (if first-time (progn (keyboard-translate ?\C-h ?\C-?) (keyboard-translate ?\C-? ?\C-h))))) ;; Under UNIX (if (not (equal system-type 'ms-dos)) (progn (if first-time (server-start)))) ;; Add any face changes here (add-hook 'term-setup-hook 'my-term-setup-hook) (defun my-term-setup-hook () (if (eq window-system 'pc) (progn ;; (set-face-background 'default "red") ))) ;; Restore the "desktop" - do this as late as possible (if first-time (progn (desktop-load-default) (desktop-read))) ;; Indicate that this file has been read at least once (setq first-time nil) ;; No need to debug anything now (setq debug-on-error nil) ;; All done (message "All done, %s%s" (user-login-name) ".") Extending the Range of Languages Emacs Understands Now, this is all very well if you only want to program in the languages already catered for in the .emacs file (C, C++, Perl, Lisp and Scheme), but what happens if a new language called whizbang comes out, full of exciting features? The first thing to do is find out if whizbang comes with any files that tell Emacs about the language. These usually end in .el, short for Emacs Lisp. For example, if whizbang is a FreeBSD port, we can locate these files by doing &prompt.user; find /usr/ports/lang/whizbang -name "*.el" -print and install them by copying them into the Emacs site Lisp directory. On FreeBSD 2.1.0-RELEASE, this is /usr/local/share/emacs/site-lisp. So for example, if the output from the find command was /usr/ports/lang/whizbang/work/misc/whizbang.el we would do &prompt.root; cp /usr/ports/lang/whizbang/work/misc/whizbang.el /usr/local/share/emacs/site-lisp Next, we need to decide what extension whizbang source files have. Let's say for the sake of argument that they all end in .wiz. We need to add an entry to our .emacs file to make sure Emacs will be able to use the information in whizbang.el. Find the auto-mode-alist entry in .emacs and add a line for whizbang, such as: … ("\\.lsp$" . lisp-mode) ("\\.wiz$" . whizbang-mode) ("\\.scm$" . scheme-mode) … This means that Emacs will automatically go into whizbang-mode when you edit a file ending in .wiz. Just below this, you will find the font-lock-auto-mode-list entry. Add whizbang-mode to it like so: ;; Auto font lock mode (defvar font-lock-auto-mode-list (list 'c-mode 'c++-mode 'c++-c-mode 'emacs-lisp-mode 'whizbang-mode 'lisp-mode 'perl-mode 'scheme-mode) "List of modes to always start in font-lock-mode") This means that Emacs will always enable font-lock-mode (ie syntax highlighting) when editing a .wiz file. And that is all that is needed. If there is anything else you want done automatically when you open up a .wiz file, you can add a whizbang-mode hook (see my-scheme-mode-hook for a simple example that adds auto-indent). Further Reading Brian Harvey and Matthew Wright Simply Scheme MIT 1994. ISBN 0-262-08226-8 Randall Schwartz Learning Perl O'Reilly 1993 ISBN 1-56592-042-2 Patrick Henry Winston and Berthold Klaus Paul Horn Lisp (3rd Edition) Addison-Wesley 1989 ISBN 0-201-08319-1 Brian W. Kernighan and Rob Pike The Unix Programming Environment Prentice-Hall 1984 ISBN 0-13-937681-X Brian W. Kernighan and Dennis M. Ritchie The C Programming Language (2nd Edition) Prentice-Hall 1988 ISBN 0-13-110362-8 Bjarne Stroustrup The C++ Programming Language Addison-Wesley 1991 ISBN 0-201-53992-6 W. Richard Stevens Advanced Programming in the Unix Environment Addison-Wesley 1992 ISBN 0-201-56317-7 W. Richard Stevens Unix Network Programming Prentice-Hall 1990 ISBN 0-13-949876-1 diff --git a/en_US.ISO8859-1/books/faq/book.sgml b/en_US.ISO8859-1/books/faq/book.sgml index 411ab9d474..da93261d34 100644 --- a/en_US.ISO8859-1/books/faq/book.sgml +++ b/en_US.ISO8859-1/books/faq/book.sgml @@ -1,12472 +1,12472 @@ %books.ent; ]> Frequently Asked Questions for FreeBSD 2.X, 3.X, 4.X and 5.X The FreeBSD Documentation Project $FreeBSD$ 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 The FreeBSD Documentation Project &bookinfo.legalnotice; &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.adobe; &tm-attrib.creative; &tm-attrib.cvsup; &tm-attrib.ibm; &tm-attrib.ieee; &tm-attrib.intel; &tm-attrib.iomega; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.mips; &tm-attrib.netscape; &tm-attrib.opengroup; &tm-attrib.oracle; &tm-attrib.sgi; &tm-attrib.sparc; &tm-attrib.sun; &tm-attrib.usrobotics; &tm-attrib.xfree86; &tm-attrib.general; This is the FAQ for FreeBSD versions 2.X, 3.X, 4.X and 5.X. All entries are assumed to be relevant to FreeBSD 2.0.5 and later, unless otherwise noted. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the FreeBSD + url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/index.html">FreeBSD World Wide Web server. It may also be downloaded as - one large HTML file with HTTP + one large HTML file with HTTP or as plain text, &postscript;, PDF, etc. from the FreeBSD FTP + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP server. You may also want to Search the + url="&url.base;/search/index.html">Search the FAQ. Introduction Welcome to the FreeBSD 2.X-5.X FAQ! As is usual with Usenet FAQs, this document aims to cover the most frequently asked questions concerning the FreeBSD operating system (and of course answer them!). Although originally intended to reduce bandwidth and avoid the same old questions being asked over and over again, FAQs have become recognized as valuable information resources. Every effort has been made to make this FAQ as informative as possible; if you have any suggestions as to how it may be improved, please feel free to mail them to the &a.doc;. What is FreeBSD? Briefly, FreeBSD is a &unix; like operating system for the &i386;, IA-64, PC-98, Alpha/AXP, and &ultrasparc; platforms based on U.C. Berkeley's 4.4BSD-Lite release, with some 4.4BSD-Lite2 enhancements. It is also based indirectly on William Jolitz's port of U.C. Berkeley's Net/2 to the &i386;, known as 386BSD, though very little of the 386BSD code remains. A fuller description of what FreeBSD is and how it can work for you may be found on - the FreeBSD home + the FreeBSD home page. FreeBSD is used by companies, Internet Service Providers, researchers, computer professionals, students and home users all over the world in their work, education and recreation. For more detailed information on FreeBSD, please see the - FreeBSD + FreeBSD Handbook. What is the goal of the FreeBSD Project? The goal of the FreeBSD Project is to provide software that may be used for any purpose and without strings attached. Many of us have a significant investment in the code (and project) and would certainly not mind a little financial compensation now and then, but we definitely do not insist on it. We believe that our first and foremost mission is to provide code to any and all comers, and for whatever purpose, so that the code gets the widest possible use and provides the widest possible benefit. This is, we believe, one of the most fundamental goals of Free Software and one that we enthusiastically support. That code in our source tree which falls under the GNU General Public License (GPL) or GNU Library General Public License (LGPL) comes with slightly more strings attached, though at least on the side of enforced access rather than the usual opposite. Due to the additional complexities that can evolve in the commercial use of GPL software, we do, however, endeavor to replace such software with submissions under the more relaxed FreeBSD license whenever possible. Does the FreeBSD license have any restrictions? Yes. Those restrictions do not control how you use the code, merely how you treat the FreeBSD Project itself. If you have serious license concerns, read the actual license. For the simply curious, the license can be summarized like this. Do not claim that you wrote this. Do not sue us if it breaks. Can FreeBSD replace my current operating system? For most people, yes. But this question is not quite that cut-and-dried. Most people do not actually use an operating system. They use applications. The applications are what really use the operating system. FreeBSD is designed to provide a robust and full-featured environment for applications. It supports a wide variety of web browsers, office suites, email readers, graphics programs, programming environments, network servers, and just about everything else you might want. Most of these applications can be managed through the Ports Collection. If you need to use an application that is only available on one operating system, you simply cannot replace that operating system. Chances are there is a very similar application on FreeBSD, however. If you want a solid office or Internet server, a reliable workstation, or just the ability to do your job without interruptions, FreeBSD will almost certainly do everything you need. Many computer users across the world, including both novices and experienced &unix; administrators, use FreeBSD as their only desktop operating system. If you are migrating to FreeBSD from some other &unix; environment, you already know most of what you need to. If your background is in graphic-driven operating systems such as &windows; and older versions of &macos;, expect to invest additional time learning the &unix; way of doing things. This FAQ and the FreeBSD Handbook are excellent places to start. Why is it called FreeBSD? It may be used free of charge, even by commercial users. Full source for the operating system is freely available, and the minimum possible restrictions have been placed upon its use, distribution and incorporation into other work (commercial or non-commercial). Anyone who has an improvement or bug fix is free to submit their code and have it added to the source tree (subject to one or two obvious provisions). It is worth pointing out that the word free is being used in two ways here, one meaning at no cost, the other meaning you can do whatever you like. Apart from one or two things you cannot do with the FreeBSD code, for example pretending you wrote it, you can really do whatever you like with it. What are the differences between FreeBSD and NetBSD, OpenBSD, and other open source BSD operating systems? James Howard wrote a good explanation of the history and differences between the various projects for DaemonNews, called The BSD Family Tree which goes a fair way to answering this question. What is the latest version of FreeBSD? At this point in FreeBSD's development, there are two parallel development branches; releases are being made from both branches. The 4.X series of releases is being made from the -STABLE branch and the 5.X series of releases is being made from -CURRENT. Version &rel.current; + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/">&rel.current; is the latest release from the -CURRENT branch; it was released in &rel.current.date;. Version &rel2.current; + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">&rel2.current; is the latest release from the -STABLE branch; it was released in &rel2.current.date;. Briefly, -STABLE is aimed at the ISP, corporate user, or any user who wants stability and a minimal number of changes compared to the new (and possibly unstable) features of the latest -CURRENT snapshot. Releases can come from either branch, but -CURRENT should only be used if you are prepared for its increased volatility (relative to -STABLE, that is). Releases are made every few months. While many people stay more up-to-date with the FreeBSD sources (see the questions on FreeBSD-CURRENT and FreeBSD-STABLE) than that, doing so is more of a commitment, as the sources are a moving target. More information on FreeBSD releases can be found on the Release Engineering page on the FreeBSD Web site. What is FreeBSD-CURRENT? FreeBSD-CURRENT + url="&url.books.handbook;/cutting-edge.html#CURRENT">FreeBSD-CURRENT is the development version of the operating system, which will in due course become the new &os.stable; branch. This is expected to happen around 5.3-RELEASE. As such, it is really only of interest to developers working on the system and die-hard hobbyists. See the relevant + url="&url.books.handbook;/cutting-edge.html#CURRENT">relevant section in the handbook for details + url="&url.books.handbook;/index.html">handbook for details on running -CURRENT. If you are not familiar with the operating system or are not capable of identifying the difference between a real problem and a temporary problem, you should not use FreeBSD-CURRENT. This branch sometimes evolves quite quickly and can be un-buildable for a number of days at a time. People that use FreeBSD-CURRENT are expected to be able to analyze any problems and only report them if they are deemed to be mistakes rather than glitches. Questions such as make world produces some error about groups on the -CURRENT mailing list may be treated with contempt. Every day, snapshot + url="&url.base;/releases/snapshots.html">snapshot releases are made based on the current state of the -CURRENT and -STABLE branches. Distributions of the occasional snapshot are made available. The goals behind each snapshot release are: To test the latest version of the installation software. To give people who would like to run -CURRENT or -STABLE but who do not have the time or bandwidth to follow it on a day-to-day basis an easy way of bootstrapping it onto their systems. To preserve a fixed reference point for the code in question, just in case we break something really badly later. (Although CVS normally prevents anything horrible like this happening :) To ensure that all new features and fixes in need of testing have the greatest possible number of potential testers. No claims are made that any -CURRENT snapshot can be considered production quality for any purpose. If you want to run a stable and fully tested system, you will have to stick to full releases, or use the -STABLE snapshots. Snapshot releases are directly available from + url="ftp://current.FreeBSD.org/pub/FreeBSD/snapshots/"> ftp://current.FreeBSD.org/pub/FreeBSD/snapshots/. 3-STABLE snapshots are no longer being produced. Snapshots are generated, on the average, daily for all actively developed branches. What is the FreeBSD-STABLE concept? Back when FreeBSD 2.0.5 was released, FreeBSD development branched in two. One branch was named -STABLE, + url="&url.books.handbook;/current-stable.html#STABLE">-STABLE, one -CURRENT. + url="&url.books.handbook;/current-stable.html#CURRENT">-CURRENT. FreeBSD-STABLE is intended for Internet Service Providers and other commercial enterprises for whom sudden shifts or experimental features are quite undesirable. It receives only well-tested bug fixes and other small incremental enhancements. FreeBSD-CURRENT, on the other hand, has been one unbroken line since 2.0 was released, leading towards 5.2.1-RELEASE (and beyond). At 5.3-RELEASE, the 5-STABLE branch is expected to be created, and &os.current; will become 6-CURRENT. If a little ASCII art would help, this is how it looks: 2.0 | | | [2.1-STABLE] *BRANCH* 2.0.5 -> 2.1 -> 2.1.5 -> 2.1.6 -> 2.1.7.1 [2.1-STABLE ends] | (Mar 1997) | | | [2.2-STABLE] *BRANCH* 2.2.1 -> 2.2.2-RELEASE -> 2.2.5 -> 2.2.6 -> 2.2.7 -> 2.2.8 [end] | (Mar 1997) (Oct 97) (Apr 98) (Jul 98) (Dec 98) | | 3.0-SNAPs (started Q1 1997) | | 3.0-RELEASE (Oct 1998) | | [3.0-STABLE] *BRANCH* 3.1-RELEASE (Feb 1999) -> 3.2 -> 3.3 -> 3.4 -> 3.5 -> 3.5.1 | (May 1999) (Sep 1999) (Dec 1999) (June 2000) (July 2000) | | [4.0-STABLE] *BRANCH* 4.0 (Mar 2000) -> 4.1 -> 4.1.1 -> 4.2 -> 4.3 -> 4.4 -> ... later 4.X releases ... | | (July 2000) (Sep 2000) (Nov 2000) 5.0-RELEASE (Jan 2003) | | 5.1-RELEASE (Jun 2003) | | 5.2-RELEASE (Jan 2004) | | 5.2.1-RELEASE (Feb 2004) | \|/ + [5-CURRENT continues] The 2.2-STABLE branch was retired with the release of 2.2.8. The 3-STABLE branch has ended with the release of 3.5.1, the final 3.X release. The only changes made to either of these branches will be, for the most part, security-related bug fixes. 4-STABLE is the actively developed -STABLE branch. The latest release on the 4-STABLE branch is &rel2.current;-RELEASE, which was released in &rel2.current.date;. The 5-CURRENT branch is slowly progressing toward the creation of a 5-STABLE branch. See What is FreeBSD-CURRENT? for more information on this branch. When are FreeBSD releases made? The &a.re; releases a new version of FreeBSD about every four months, on average. Release dates are announced well in advance, so that the people working on the system know when their projects need to be finished and tested. A testing period precedes each release, in order to ensure that the addition of new features does not compromise the stability of the release. Many users regard this caution as one of the best things about FreeBSD, even though waiting for all the latest goodies to reach -STABLE can be a little frustrating. More information on the release engineering process (including a schedule of upcoming releases) can be found on the release engineering pages on the FreeBSD Web site. For people who need or want a little more excitement, binary snapshots are made daily as discussed above. Who is responsible for FreeBSD? The key decisions concerning the FreeBSD project, such as the overall direction of the project and who is allowed to add code to the source tree, are made by a core + url="&url.articles.contributors;/article.html#STAFF-CORE">core team of 9 people. There is a much larger team of more than 300 committers + url="&url.articles.contributors;/article.html#STAFF-COMMITTERS">committers who are authorized to make changes directly to the FreeBSD source tree. However, most non-trivial changes are discussed in advance in the mailing lists, and there are no restrictions on who may take part in the discussion. Where can I get FreeBSD? Every significant release of FreeBSD is available via anonymous FTP from the + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/"> FreeBSD FTP site: For the current 3.X-STABLE release, 3.5.1-RELEASE, see the 3.5.1-RELEASE + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/3.5.1-RELEASE/">3.5.1-RELEASE directory. The latest 5.X release, &rel.current;-RELEASE can be found in the &rel.current;-RELEASE directory. + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/">&rel.current;-RELEASE directory. The latest 4-STABLE release, &rel2.current;-RELEASE can be found in the &rel2.current;-RELEASE directory. + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">&rel2.current;-RELEASE directory. 4.X + url="ftp://current.FreeBSD.org/pub/FreeBSD/snapshots/">4.X snapshots are usually made daily. + url="ftp://current.FreeBSD.org/pub/FreeBSD/"> 5.X Snapshot releases are made daily for the -CURRENT branch, these being of service purely to bleeding-edge testers and developers. Information about obtaining FreeBSD on CD, DVD, and other media can be found in the Handbook. How do I set up a FreeBSD mirror? Information on setting up a FreeBSD mirror can be found in the Mirroring FreeBSD article. How do I access the Problem Report database? The Problem Report database of all user change requests may be queried by using our web-based PR + url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> query interface. The &man.send-pr.1; command can be used to submit problem reports and change requests via electronic mail. The web-based problem report submission interface is currently disabled due to persistent abuse. Before submitting a problem report, please read Writing + url="&url.articles.problem-reports;/article.html">Writing FreeBSD Problem Reports, an article on how to write good problem reports. How do I become a FreeBSD Web mirror? There are multiple ways to mirror the Web pages. You can retrieve the formatted files from a FreeBSD CVSup server using the application net/cvsup. The file /usr/share/examples/cvsup/www-supfile contains an example CVSup configuration file for web mirrors. You can download the web site source code from any FreeBSD FTP server using your favorite ftp mirror tool. Keep in mind that you have to build these sources before publishing them. Start mirroring at - . + . What other sources of information are there? Please check the Documentation list on the main FreeBSD web site. Documentation and Support What good books are there about FreeBSD? The project produces a wide range of documentation, available online from this link: . The same documents are available as packages, that you can easily install on your FreeBSD system. More details on documentation packages can be found in the next paragraphs. In addition, the Bibliography at the end of this FAQ, and the one in the Handbook reference other recommended books. Is the documentation available in other formats, such as plain text (ASCII), or &postscript;? Yes. The documentation is available in a number of different formats and compression schemes on the FreeBSD FTP site, in the /pub/FreeBSD/doc/ + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">/pub/FreeBSD/doc/ directory. The documentation is categorized in a number of different ways. These include: The document's name, such as faq, or handbook. The document's language and encoding. These are based on the locale names you will find under /usr/share/locale on your FreeBSD system. The current languages and encodings that we have for documentation are as follows: Name Meaning en_US.ISO8859-1 US English de_DE.ISO8859-1 German es_ES.ISO8859-1 Spanish fr_FR.ISO8859-1 French ja_JP.eucJP Japanese (EUC encoding) ru_RU.KOI8-R Russian (KOI8-R encoding) zh_TW.Big5 Chinese (Big5 encoding) Some documents may not be available in all languages. The document's format. We produce the documentation in a number of different output formats. Each format has its own advantages and disadvantages. Some formats are better suited for online reading, while others are meant to be aesthetically pleasing when printed on paper. Having the documentation available in any of these formats ensures that our readers will be able to read the parts they are interested in, either on their monitor, or on paper after printing the documents. The currently available formats are: Format Meaning html-split A collection of small, linked, HTML files. html One large HTML file containing the entire document pdb Palm Pilot database format, for use with the - iSilo + iSilo reader. pdf Adobe's Portable Document Format ps &postscript; rtf Microsoft's Rich Text Format Page numbers are not automatically updated when loading this format into Word. Press CTRLA, CTRLEND, F9 after loading the document, to update the page numbers. txt Plain text The compression and packaging scheme. There are three of these currently in use. Where the format is html-split, the files are bundled up using &man.tar.1;. The resulting .tar file is then compressed using the compression schemes detailed in the next point. All the other formats generate one file, called book.format (i.e., book.pdb, book.html, and so on). These files are then compressed using two compression schemes. Scheme Description zip The Zip format. If you want to uncompress this on FreeBSD you will need to install the archivers/unzip port first. bz2 The BZip2 format. Less widespread than Zip, but generally gives smaller files. Install the archivers/bzip2 port to uncompress these files. So the &postscript; version of the Handbook, compressed using BZip2 will be stored in a file called book.ps.bz2 in the handbook/ directory. After choosing the format and compression mechanism that you want to download, you must then decide whether or not you want to download the document as a FreeBSD package. The advantage of downloading and installing the package is that the documentation can then be managed using the normal FreeBSD package management comments, such as &man.pkg.add.1; and &man.pkg.delete.1;. If you decide to download and install the package then you must know the filename to download. The documentation-as-packages files are stored in a directory called packages. Each package file looks like document-name.lang.encoding.format.tgz. For example, the FAQ, in English, formatted as PDF, is in the package called faq.en_US.ISO8859-1.pdf.tgz. Knowing this, you can use the following command to install the English PDF FAQ package. &prompt.root; pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/packages/faq.en_US.ISO8859-1.pdf.tgz Having done that, you can use &man.pkg.info.1; to determine where the file has been installed. &prompt.root; pkg_info -f faq.en_US.ISO8859-1.pdf Information for faq.en_US.ISO8859-1.pdf: Packing list: Package name: faq.en_US.ISO8859-1.pdf CWD to /usr/share/doc/en_US.ISO8859-1/books/faq File: book.pdf CWD to . File: +COMMENT (ignored) File: +DESC (ignored) As you can see, book.pdf will have been installed into /usr/share/doc/en_US.ISO8859-1/books/faq. If you do not want to use the packages then you will have to download the compressed files yourself, uncompress them, and then copy the appropriate documents into place. For example, the split HTML version of the FAQ, compressed using &man.bzip2.1;, can be found in the doc/en_US.ISO8859-1/books/faq/book.html-split.tar.bz2 file. To download and uncompress that file you would have to do this. &prompt.root; fetch ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/faq/book.html-split.tar.bz2 &prompt.root; bzip2 -d book.html-split.tar.bz2 &prompt.root; tar xvf book.html-split.tar You will be left with a collection of .html files. The main one is called index.html, which will contain the table of contents, introductory material, and links to the other parts of the document. You can then copy or move these to their final location as necessary. Where do I find info on the FreeBSD mailing lists? You can find full information in the Handbook + url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">Handbook entry on mailing-lists. Where do I find the FreeBSD Y2K info? You can find full information in the FreeBSD Y2K page. + url="&url.base;/y2kbug.html">FreeBSD Y2K page. What FreeBSD news groups are available? You can find full information in the Handbook entry on + url="&url.books.handbook;/eresources-news.html">Handbook entry on newsgroups. Are there FreeBSD IRC (Internet Relay Chat) channels? Yes, most major IRC networks host a FreeBSD chat channel: Channel #FreeBSD on - EFNet + EFNet is a FreeBSD forum, but do not go there for tech support or try to get folks there to help you avoid the pain of reading manual pages or doing your own research. It is a chat channel, first and foremost, and topics there are just as likely to involve sex, sports or nuclear weapons as they are FreeBSD. You Have Been Warned! Available at server irc.chat.org. Channel #FreeBSDhelp on - EFNet + EFNet is a channel dedicated to helping FreeBSD users. They are much more sympathetic to questions than #FreeBSD is. Channel #FreeBSD on - DALNET + DALNET is available at irc.dal.net in the US and irc.eu.dal.net in Europe. Channel #FreeBSD on - UNDERNET + UNDERNET is available at us.undernet.org in the US and eu.undernet.org in Europe. Since it is a help channel, be prepared to read the documents you are referred to. Channel #FreeBSD on HybNet. This channel is a help channel. A list of servers can be found on the HybNet web site. Each of these channels are distinct and are not connected to each other. Their chat styles also differ, so you may need to try each to find one suited to your chat style. As with all types of IRC traffic, if you are easily offended or cannot deal with lots of young people (and more than a few older ones) doing the verbal equivalent of jello wrestling, do not even bother with it. Where can I get commercial FreeBSD training and support? DaemonNews provides commercial training and support for FreeBSD. More information can be found at their BSD Mall site. FreeBSD Services Ltd provide commercial support for FreeBSD in the UK (as well as selling FreeBSD on DVD). See their web site for more information. The FreeBSD Mall provides commercial FreeBSD support. You can get more information at their web site. Any other organizations providing training and support should contact the project in order to be listed here. Nik Clayton
nik@FreeBSD.org
 Installation Which file do I download to get FreeBSD? Prior to release 3.1, you only needed one floppy image to install FreeBSD, namely floppies/boot.flp. However, since release 3.1 the Project has added out-of-the-box support for a wide variety of hardware, which takes up more space. For 3.X and later you need two floppy images: floppies/kernel.flp and floppies/mfsroot.flp. These images need to be copied onto floppies by tools like fdimage or &man.dd.1;. If you need to download the distributions yourself (for a DOS filesystem install, for instance), below are some recommendations for distributions to grab: bin/ manpages/ compat*/ doc/ src/ssys.* Full instructions on this procedure and a little bit more about installation issues in general can be found in the - Handbook entry on + Handbook entry on installing FreeBSD. What do I do if the floppy images does not fit on a single floppy? A 3.5 inch (1.44MB) floppy can accommodate 1474560 bytes of data. The boot image is exactly 1474560 bytes in size. Common mistakes when preparing the boot floppy are: Not downloading the floppy image in binary mode when using FTP. Some FTP clients default their transfer mode to ascii and attempt to change any end-of-line characters received to match the conventions used by the client's system. This will almost invariably corrupt the boot image. Check the size of the downloaded boot image: if it is not exactly that on the server, then the download process is suspect. To workaround: type binary at the FTP command prompt after getting connected to the server and before starting the download of the image. Using the DOS copy command (or equivalent GUI tool) to transfer the boot image to floppy. Programs like copy will not work as the boot image has been created to be booted into directly. The image has the complete content of the floppy, track for track, and is not meant to be placed on the floppy as a regular file. You have to transfer it to the floppy raw, using the low-level tools (e.g. fdimage or rawrite) described in the installation guide to + url="&url.books.handbook;/install.html">installation guide to FreeBSD. Where are the instructions for installing FreeBSD? Installation instructions can be found in the - Handbook entry on installing FreeBSD. + Handbook entry on installing FreeBSD. What do I need in order to run FreeBSD? You will need a 386 or better PC, with 5 MB or more of RAM and at least 60 MB of hard disk space. It can run with a low end MDA graphics card but to run X11R6, a VGA or better video card is needed. See also . I have only 4 MB of RAM. Can I install FreeBSD? FreeBSD 2.1.7 was the last version of FreeBSD that could be installed on a 4MB system. FreeBSD 2.2 and later needs at least 5MB to install on a new system. All versions of FreeBSD will run in 4MB of RAM, they just cannot run the installation program in 4MB. You can add extra memory for the install process, if you like, and then after the system is up and running, go back to 4MB. Or you could swap your disk into a system which has >4MB, install onto the disk and then swap it back. After the installation, if you build a custom kernel, it will run in 4 MB. Someone has even successfully booted with 2 MB, although the system was almost unusable. How can I make my own custom install floppy? Currently there is no way to just make a custom install floppy. You have to cut a whole new release, which will include your install floppy. To make a custom release, follow the instructions in the Release Engineering article. Can I have more than one operating system on my PC? Have a look at - + the multi-OS page. Can &windows; 95/98 co-exist with FreeBSD? Install &windows; 95/98 first, after that FreeBSD. FreeBSD's boot manager will then manage to boot Win95/98 and FreeBSD. If you install &windows; 95/98 second, it will boorishly overwrite your boot manager without even asking. If that happens, see the next section. &windows; 95/98 killed my boot manager! How do I get it back? You can reinstall the boot manager FreeBSD comes with in one of three ways: Running DOS, go into the tools/ directory of your FreeBSD distribution and look for bootinst.exe. You run it like so: ...\TOOLS> bootinst.exe boot.bin and the boot manager will be reinstalled. Boot the FreeBSD boot floppy again and go to the Custom installation menu item. Choose Partition. Select the drive which used to contain your boot manager (likely the first one) and when you come to the partition editor for it, as the very first thing (e.g. do not make any changes) select (W)rite. This will ask for confirmation, say yes, and when you get the Boot Manager selection prompt, be sure to select Boot Manager. This will re-write the boot manager to disk. Now quit out of the installation menu and reboot off the hard disk as normal. Boot the FreeBSD boot floppy (or CDROM) and choose the Fixit menu item. Select either the Fixit floppy or CDROM #2 (the live filesystem option) as appropriate and enter the fixit shell. Then execute the following command: Fixit# fdisk -B -b /boot/boot0 bootdevice substituting bootdevice for your real boot device such as ad0 (first IDE disk), ad4 (first IDE disk on auxiliary controller), da0 (first SCSI disk), etc. My A, T, or X series IBM Thinkpad locks up when I first booted up my FreeBSD installation. How can I solve this? A bug in early revisions of IBM's BIOS on these machines mistakenly identifies the FreeBSD partition as a potential FAT suspend-to-disk partition. When the BIOS tries to parse the FreeBSD partition it hangs. According to IBMIn an e-mail from Keith Frechette kfrechet@us.ibm.com., the following model/BIOS release numbers incorporate the fix. Model BIOS revision T20 IYET49WW or later T21 KZET22WW or later A20p IVET62WW or later A20m IWET54WW or later A21p KYET27WW or later A21m KXET24WW or later A21e KUET30WW It has been reported that later IBM BIOS revisions may have reintroduced the bug. This message from Jacques Vidrine to the &a.mobile; describes a procedure which may work if your newer IBM laptop does not boot FreeBSD properly, and you can upgrade or downgrade the BIOS. If you have an earlier BIOS, and upgrading is not an option a workaround is to install FreeBSD, change the partition ID FreeBSD uses, and install new boot blocks that can handle the different partition ID. First, you will need to restore the machine to a state where it can get through its self-test screen. Doing this requires powering up the machine without letting it find a FreeBSD partition on its primary disk. One way is to remove the hard disk and temporarily move it to an older ThinkPad (such as a ThinkPad 600) or a desktop PC with an appropriate conversion cable. Once it is there, you can delete the FreeBSD partition and move the hard disk back. The ThinkPad should now be in a bootable state again. With the machine functional again, you can use the workaround procedure described here to get a working FreeBSD installation. Download boot1 and boot2 from . Put these files somewhere you will be able to retrieve them later. Install FreeBSD as normal on to the ThinkPad. Do not use Dangerously Dedicated mode. Do not reboot when the install has finished. Either switch to the Emergency Holographic Shell (ALT F4) or start a fixit shell. Use &man.fdisk.8; to change the FreeBSD partition ID from 165 to 166 (this is the type used by OpenBSD). Bring the boot1 and boot2 files to the local filesystem. Use &man.disklabel.8; to write boot1 and boot2 to your FreeBSD slice. &prompt.root; disklabel -B -b boot1 -s boot2 ad0sn n is the number of the slice where you installed FreeBSD. Reboot. At the boot prompt you will be given the option of booting OpenBSD. This will actually boot FreeBSD. Getting this to work in the case where you want to dual boot OpenBSD and FreeBSD on the same laptop is left as an exercise for the reader. Can I install on a disk with bad blocks? Prior to 3.0, FreeBSD included a utility known as bad144, which automatically remapped bad blocks. Because modern IDE drives perform this function themselves, bad144 has been removed from the FreeBSD source tree. If you wish to install FreeBSD 3.0 or later, we strongly suggest you purchase a newer disk drive. If you do not wish to do this, you must run FreeBSD 2.X. If you are seeing bad block errors with a modern IDE drive, chances are the drive is going to die very soon (the drive's internal remapping functions are no longer sufficient to fix the bad blocks, which means the disk is heavily corrupted); we suggest you buy a new hard drive. If you have a SCSI drive with bad blocks, see this answer. I have just upgraded from 3.X to 4.X, and my first boot failed with bad sector table not supported FreeBSD 3.X and earlier supported bad144, which automatically remapped bad blocks. FreeBSD 4.X and later do not support this, as modern IDE drives include this functionality. See this question for more information. To fix this after an upgrade, you need to physically place the drive in a working system and use &man.disklabel.8; as discussed in the following questions. How do I tell if a drive has bad144 information on it before I try to upgrade to FreeBSD 4.0 and it fails? Use &man.disklabel.8; for this. disklabel -r drive device will give you the contents of your disk label. Look for a flags field. If you see flags: badsect, this drive is using bad144. For example, the following drive has bad144 enabled.: &prompt.root; disklabel -r wd0 # /dev/rwd0c: type: ESDI disk: wd0s1 label: flags: badsect bytes/sector: 512 sectors/track: 63 How do I remove bad144 from my pre-4.X system so I can upgrade safely? Use disklabel -e -rwd0 to edit the disklabel in place. Just remove the word badsect from the flags field, save, and exit. The bad144 file will still take up some space on your drive, but the disk itself will be usable. We still recommend you purchase a new disk if you have a large number of bad blocks. Strange things happen when I boot the install floppy! What is happening? If you are seeing things like the machine grinding to a halt or spontaneously rebooting when you try to boot the install floppy, here are three questions to ask yourself:- Did you use a new, freshly-formatted, error-free floppy (preferably a brand-new one straight out of the box, as opposed to the magazine cover disk that has been lying under the bed for the last three years)? Did you download the floppy image in binary (or image) mode? (do not be embarrassed, even the best of us have accidentally downloaded a binary file in ASCII mode at least once!) If you are using &windows; 95 or 98 did you run fdimage or rawrite in pure DOS mode? These operating systems can interfere with programs that write directly to hardware, which the disk creation program does; even running it inside a DOS shell in the GUI can cause this problem. There have also been reports of &netscape; causing problems when downloading the boot floppy, so it is probably best to use a different FTP client if you can. I booted from my ATAPI CDROM, but the install program says no CDROM is found. Where did it go? The usual cause of this problem is a mis-configured CDROM drive. Many PCs now ship with the CDROM as the slave device on the secondary IDE controller, with no master device on that controller. This is illegal according to the ATAPI specification, but &windows; plays fast and loose with the specification, and the BIOS ignores it when booting. This is why the BIOS was able to see the CDROM to boot from it, but why FreeBSD cannot see it to complete the install. Reconfigure your system so that the CDROM is either the master device on the IDE controller it is attached to, or make sure that it is the slave on an IDE controller that also has a master device. Can I install on my laptop over PLIP (Parallel Line IP)? Yes. Use a standard Laplink cable. If necessary, you can check out the PLIP section of the Handbook for details on parallel port networking. If you are running FreeBSD 3.X or earlier, also look at the Mobile Computing page. Which geometry should I use for a disk drive? By the geometry of a disk, we mean the number of cylinders, heads and sectors/track on a disk. We will refer to this as C/H/S for convenience. This is how the PC's BIOS works out which area on a disk to read/write from. This causes a lot of confusion among new system administrators. First of all, the physical geometry of a SCSI drive is totally irrelevant, as FreeBSD works in term of disk blocks. In fact, there is no such thing as the physical geometry, as the sector density varies across the disk. What manufacturers claim is the physical geometry is usually the geometry that they have determined wastes the least space. For IDE disks, FreeBSD does work in terms of C/H/S, but all modern drives internally convert this into block references. All that matters is the logical geometry. This is the answer that the BIOS gets when it asks the drive what is your geometry? It then uses this geometry to access the disk. As FreeBSD uses the BIOS when booting, it is very important to get this right. In particular, if you have more than one operating system on a disk, they must all agree on the geometry. Otherwise you will have serious problems booting! For SCSI disks, the geometry to use depends on whether extended translation support is turned on in your controller (this is often referred to as support for DOS disks >1GB or something similar). If it is turned off, then use N cylinders, 64 heads and 32 sectors/track, where N is the capacity of the disk in MB. For example, a 2GB disk should pretend to have 2048 cylinders, 64 heads and 32 sectors/track. If it is turned on (it is often supplied this way to get around certain limitations in &ms-dos;) and the disk capacity is more than 1GB, use M cylinders, 63 sectors per track (not 64), and 255 heads, where 'M' is the disk capacity in MB divided by 7.844238 (!). So our example 2GB drive would have 261 cylinders, 63 sectors per track and 255 heads. If you are not sure about this, or FreeBSD fails to detect the geometry correctly during installation, the simplest way around this is usually to create a small DOS partition on the disk. The BIOS should then detect the correct geometry, and you can always remove the DOS partition in the partition editor if you do not want to keep it. You might want to leave it around for programming network cards and the like, however. Alternatively, there is a freely available utility distributed with FreeBSD called pfdisk.exe. You can find it in the tools subdirectory on the FreeBSD CDROM or on the various FreeBSD FTP sites. This program can be used to work out what geometry the other operating systems on the disk are using. You can then enter this geometry in the partition editor. Are there any restrictions on how I divide the disk up? Yes. You must make sure that your root partition is below 1024 cylinders so the BIOS can boot the kernel from it. (Note that this is a limitation in the PC's BIOS, not FreeBSD). For a SCSI drive, this will normally imply that the root partition will be in the first 1024MB (or in the first 4096MB if extended translation is turned on - see previous question). For IDE, the corresponding figure is 504MB. Is FreeBSD compatible with any disk managers? FreeBSD recognizes the Ontrack Disk Manager and makes allowances for it. Other disk managers are not supported. If you just want to use the disk with FreeBSD you do not need a disk manager. Just configure the disk for as much space as the BIOS can deal with (usually 504 megabytes), and FreeBSD should figure out how much space you really have. If you are using an old disk with an MFM controller, you may need to explicitly tell FreeBSD how many cylinders to use. If you want to use the disk with FreeBSD and another operating system, you may be able to do without a disk manager: just make sure the FreeBSD boot partition and the slice for the other operating system are in the first 1024 cylinders. If you are reasonably careful, a 20 megabyte boot partition should be plenty. When I boot FreeBSD I get Missing Operating System. What is happening? This is classically a case of FreeBSD and DOS or some other OS conflicting over their ideas of disk geometry. You will have to reinstall FreeBSD, but obeying the instructions given above will almost always get you going. Why can I not get past the boot manager's F? prompt? This is another symptom of the problem described in the preceding question. Your BIOS geometry and FreeBSD geometry settings do not agree! If your controller or BIOS supports cylinder translation (often marked as >1GB drive support), try toggling its setting and reinstalling FreeBSD. Do I need to install the complete sources? In general, no. However, we would strongly recommend that you install, at a minimum, the base source kit, which includes several of the files mentioned here, and the sys (kernel) source kit, which includes sources for the kernel. There is nothing in the system which requires the presence of the sources to operate, however, except for the kernel-configuration program &man.config.8;. With the exception of the kernel sources, our build structure is set up so that you can read-only mount the sources from elsewhere via NFS and still be able to make new binaries (due to the kernel-source restriction, we recommend that you not mount this on /usr/src directly, but rather in some other location with appropriate symbolic links to duplicate the top-level structure of the source tree). Having the sources on-line and knowing how to build a system with them will make it much easier for you to upgrade to future releases of FreeBSD. To actually select a subset of the sources, use the Custom menu item when you are in the Distributions menu of the system installation tool. Do I need to build a kernel? Building a new kernel was originally pretty much a required step in a FreeBSD installation, but more recent releases have benefited from the introduction of a much friendlier kernel configuration tool. When at the FreeBSD boot prompt (boot:), use the flag and you will be dropped into a visual configuration screen which allows you to configure the kernel's settings for most common ISA cards. It is still recommended that you eventually build a new kernel containing just the drivers that you need, just to save a bit of RAM, but it is no longer a strict requirement for most systems. Should I use DES, Blowfish, or MD5 passwords and how do I specify which form my users receive? The default password format on FreeBSD is to use MD5-based passwords. These are believed to be more secure than the traditional &unix; password format, which used a scheme based on the DES algorithm. DES passwords are still available if you need to share your password file with legacy operating systems which still use the less secure password format (they are available if you choose to install the crypto distribution in sysinstall, or by installing the crypto sources if building from source). Installing the crypto libraries will also allow you to use the Blowfish password format, which is more secure. Which password format to use for new passwords is controlled by the passwd_format login capability in /etc/login.conf, which takes values of des, blf (if these are available) or md5. See the &man.login.conf.5; manual page for more information about login capabilities. Why does the boot floppy start, but hang at the Probing Devices... screen? If you have a IDE &iomegazip; or &jaz; drive installed, remove it and try again. The boot floppy can get confused by the drives. After the system is installed you can reconnect the drive. Hopefully this will be fixed in a later release. Why do I get a panic: can't mount root error when rebooting the system after installation? This error comes from confusion between the boot block's and the kernel's understanding of the disk devices. The error usually manifests on two-disk IDE systems, with the hard disks arranged as the master or single device on separate IDE controllers, with FreeBSD installed on the secondary IDE controller. The boot blocks think the system is installed on wd1 (the second BIOS disk) while the kernel assigns the first disk on the secondary controller device wd2. After the device probing, the kernel tries to mount what the boot blocks think is the boot disk, wd1, while it is really wd2, and fails. To fix the problem, do one of the following: For FreeBSD 3.3 and later, reboot the system and hit Enter at the Booting kernel in 10 seconds; hit [Enter] to interrupt prompt. This will drop you into the boot loader. Then type set root_disk_unit="disk_number" . disk_number will be 0 if FreeBSD is installed on the master drive on the first IDE controller, 1 if it is installed on the slave on the first IDE controller, 2 if it is installed on the master of the second IDE controller, and 3 if it is installed on the slave of the second IDE controller. Then type boot, and your system should boot correctly. To make this change permanent (ie so you do not have to do this every time you reboot or turn on your FreeBSD machine), put the line root_disk_unit="disk_number" in /boot/loader.conf.local . If using FreeBSD 3.2 or earlier, at the Boot: prompt, enter 1:wd(2,a)kernel and press Enter. If the system starts, then run the command echo "1:wd(2,a)kernel" > /boot.config to make it the default boot string. Move the FreeBSD disk onto the primary IDE controller, so the hard disks are consecutive. - Rebuild + Rebuild your kernel, modify the wd configuration lines to read: controller wdc0 at isa? port "IO_WD1" bio irq 14 vector wdintr disk wd0 at wdc0 drive 0 # disk wd1 at wdc0 drive 1 # comment out this line controller wdc1 at isa? port "IO_WD2" bio irq 15 vector wdintr disk wd1 at wdc1 drive 0 # change from wd2 to wd1 disk wd2 at wdc1 drive 1 # change from wd3 to wd2 Install the new kernel. If you moved your disks and wish to restore the previous configuration, replace the disks in the desired configuration and reboot. Your system should boot successfully. What are the limits for memory? For memory, the limit is 4 gigabytes. If you plan to install this much memory into a machine, you need to be careful. You will probably want to use ECC memory and to reduce capacitive loading use 9 chip memory modules versus 18 chip memory modules. What are the limits for ffs filesystems? For ffs filesystems, the maximum theoretical limit is 8 terabytes (2G blocks), or 16TB for the default block size of 8K. In practice, there is a soft limit of 1 terabyte, but with modifications filesystems with 4 terabytes are possible (and exist). The maximum size of a single ffs file is approximately 1G blocks, or 4TB with a block size of 4K. Maximum file sizes fs block size 2.2.7-stable 3.0-current works should work 4K 4T-1 4T-1 4T-1 >4T 8K >32G 8T-1 >32G 32T-1 16K >128G 16T-1 >128G 32T-1 32K >512G 32T-1 >512G 64T-1 64K >2048G 64T-1 >2048G 128T-1
When the fs block size is 4K, triple indirect blocks work and everything should be limited by the maximum fs block number that can be represented using triple indirect blocks (approx. 1K^3 + 1K^2 + 1K), but everything is limited by a (wrong) limit of 1G-1 on fs block numbers. The limit on fs block numbers should be 2G-1. There are some bugs for fs block numbers near 2G-1, but such block numbers are unreachable when the fs block size is 4K. For block sizes of 8K and larger, everything should be limited by the 2G-1 limit on fs block numbers, but is actually limited by the 1G-1 limit on fs block numbers, except under -STABLE triple indirect blocks are unreachable, so the limit is the maximum fs block number that can be represented using double indirect blocks (approx. (blocksize/4)^2 + (blocksize/4)), and under -CURRENT exceeding this limit may cause problems. Using the correct limit of 2G-1 blocks does cause problems. Why do I get an error message, archsw.readin.failed after compiling and booting a new kernel? You can boot by specifying the kernel directly at the second stage, pressing any key when the | shows up before loader is started. More specifically, you have upgraded the source for your kernel, and installed a new kernel builtin from them without making world. This is not supported. Make world. What are these security profiles? A security profile is a set of configuration options that attempts to achieve the desired ratio of security to convenience by enabling and disabling certain programs and other settings. For full details, see the Security Profile section of the Handbook's post-install chapter. Hardware compatibility General I want to get a piece of hardware for my FreeBSD system. Which model/brand/type is best? This is discussed continually on the FreeBSD mailing lists. Since hardware changes so quickly, however, we expect this. We still strongly recommend that you read through the Hardware notes for &os; - &rel.current; + &rel.current; or - &rel2.current; + &rel2.current; and search the mailing list - + archives before asking about the latest and greatest hardware. Chances are a discussion about the type of hardware you are looking for took place just last week. If you are looking for a laptop, check the FreeBSD-mobile mailing list archives. Otherwise, you probably want the archives for FreeBSD-questions, or possibly a specific mailing list for a particular hardware type. Architectures and processors Does FreeBSD support architectures other than the x86? Yes. FreeBSD currently runs on the Intel x86 and DEC (now Compaq) Alpha architectures. As of FreeBSD 5.0, the IA-64, AMD-64 and &sparc64; architectures are also supported. Upcoming platforms are &mips; and &powerpc;, join the &a.ppc; or the &a.mips; respectively for more information about ongoing work on these platforms. For general discussion on new architectures, join the &a.platforms;. If your machine has a different architecture and you need something right now, we suggest you look at NetBSD or OpenBSD. + url="http://www.netbsd.org/">NetBSD or OpenBSD. Does FreeBSD support Symmetric Multiprocessing (SMP)? Yes. SMP is not enabled in the GENERIC kernel, so you must recompile your kernel to enable SMP. Take a look at /sys/i386/conf/LINT to learn what options to put in your kernel config file. I do not have a math co-processor - is that bad? This will only affect 386/486SX/486SLC owners - other machines will have one built into the CPU. In general this will not cause any problems, but there are circumstances where you will take a hit, either in performance or accuracy of the math emulation code (see the section on FP emulation). In particular, drawing arcs in X will be VERY slow. It is highly recommended that you buy a math co-processor; it is well worth it. Some math co-processors are better than others. It pains us to say it, but nobody ever got fired for buying Intel. Unless you are sure it works with FreeBSD, beware of clones. Hard drives, tape drives, and CD and DVD drives What kind of hard drives does FreeBSD support? FreeBSD supports EIDE and SCSI drives (with a compatible controller; see the next section), and all drives using the original Western Digital interface (MFM, RLL, ESDI, and of course IDE). A few ESDI controllers that use proprietary interfaces may not work: stick to WD1002/3/6/7 interfaces and clones. Which SCSI controllers are supported? See the complete list in the Hardware Notes for &os; - &rel.current; or - &rel2.current;. + &rel.current; or + &rel2.current;. What types of tape drives are supported? FreeBSD supports SCSI and QIC-36 (with a QIC-02 interface). This includes 8-mm (aka Exabyte) and DAT drives. Some of the early 8-mm drives are not quite compatible with SCSI-2, and may not work well with FreeBSD. Does FreeBSD support tape changers? FreeBSD supports SCSI changers using the &man.ch.4; device and the &man.chio.1; command. The details of how you actually control the changer can be found in the &man.chio.1; manual page. If you are not using AMANDA or some other product that already understands changers, remember that they only know how to move a tape from one point to another, so you need to keep track of which slot a tape is in, and which slot the tape currently in the drive needs to go back to. Which CDROM drives are supported by FreeBSD? Any SCSI drive connected to a supported controller is supported. The following proprietary CDROM interfaces are also supported: Mitsumi LU002 (8bit), LU005 (16bit) and FX001D (16bit 2x Speed). Sony CDU 31/33A Sound Blaster Non-SCSI CDROM Matsushita/Panasonic CDROM ATAPI compatible IDE CDROMs All non-SCSI cards are known to be extremely slow compared to SCSI drives, and some ATAPI CDROMs may not work. The official FreeBSD CDROM ISO, and CDROMs from Daemon News and FreeBSD Mall, support booting directly from the CD. Which CD-RW drives are supported by FreeBSD? FreeBSD supports any ATAPI-compatible IDE CD-R or CD-RW drive. For FreeBSD versions 4.0 and later, see the manual page for &man.burncd.8;. For earlier FreeBSD versions, see the examples in /usr/share/examples/atapi. FreeBSD also supports any SCSI CD-R or CD-RW drives. Install and use the cdrecord command from the ports or packages system, and make sure that you have the pass device compiled in your kernel. Does FreeBSD support &iomegazip; drives? FreeBSD supports SCSI and ATAPI (IDE) &iomegazip; drives out of the box, of course. SCSI ZIP drives can only be set to run at SCSI target IDs 5 or 6, but if your SCSI host adapter's BIOS supports it you can even boot from it. It is not clear which host adapters support booting from targets other than 0 or 1, so you will have to consult your adapter's documentation if you would like to use this feature. FreeBSD also supports Parallel Port Zip Drives. Check that your kernel contains the scbus0, da0, ppbus0, and vp0 drivers (the GENERIC kernel contains everything except vp0). With all these drivers present, the Parallel Port drive should be available as /dev/da0s4. Disks can be mounted using mount /dev/da0s4 /mnt OR (for dos disks) mount_msdos /dev/da0s4 /mnt as appropriate. Also check out the FAQ on removable drives later in this chapter, and the note on formattingin the Administration chapter. Does FreeBSD support &jaz;, EZ and other removable drives? Apart from the IDE version of the EZ drive, these are all SCSI devices, so they should all look like SCSI disks to FreeBSD, and the IDE EZ should look like an IDE drive. I am not sure how well FreeBSD supports changing the media out while running. You will of course need to dismount the drive before swapping media, and make sure that any external units are powered on when you boot the system so FreeBSD can see them. See this note on formatting. Keyboards and mice Does FreeBSD support my USB keyboard? FreeBSD 4.X and later supports USB keyboards out-of-the-box. Preliminary USB device support appeared in FreeBSD 3.1, but might not always work as of version 3.2. If you want to experiment with the USB keyboard support in FreeBSD 3.X, follow the procedure described below. Use a version of FreeBSD 3.X later than 3.2. Add the following lines to your kernel configuration file, and rebuild the kernel. controller uhci0 controller ohci0 controller usb0 controller ukbd0 options KBD_INSTALL_CDEV Go to the /dev directory and create device nodes as follows: &prompt.root; cd /dev &prompt.root; ./MAKEDEV kbd0 kbd1 Edit /etc/rc.conf and add the following lines: usbd_enable="YES" usbd_flags="" If you want to use a USB keyboard in FreeBSD 4.X or later, you just need to enable USB support in /etc/rc.conf. Once you have USB keyboard support enabled on your system, the AT keyboard becomes /dev/kbd0 and the USB keyboard becomes /dev/kbd1, if both are connected to the system. If there is the USB keyboard only, it will be /dev/ukbd0. If you want to use the USB keyboard in the console, you have to explicitly tell the console driver to use the existing USB keyboard. This can be done by running the following command as a part of system initialization. &prompt.root; kbdcontrol -k /dev/kbd1 < /dev/ttyv0 > /dev/null Note that if the USB keyboard is the only keyboard, it is accessed as /dev/kbd0, thus, the command should look like: &prompt.root; kbdcontrol -k /dev/kbd0 < /dev/ttyv0 > /dev/null /etc/rc.i386 is a good place to add the above command. Once this is done, the USB keyboard should work in the X environment as well without any special settings. Hot-plugging and unplugging of the USB keyboard may not work quite right yet. We recommend connecting the keyboard before starting the system and leaving it connected until the system is shutdown to avoid troubles. See the &man.ukbd.4; manual page for more information. I have an unusual bus mouse. How do I set it up? FreeBSD supports the bus mouse and the InPort bus mouse from such manufactures as Microsoft, Logitech and ATI. The bus device driver is compiled in the GENERIC kernel by default in FreeBSD versions 2.X, but not included in version 3.0 or later. If you are building a custom kernel with the bus mouse driver, make sure to add the following line to the kernel config file In FreeBSD 3.0 or before, add: device mse0 at isa? port 0x23c tty irq5 vector mseintr In FreeBSD 3.X, the line should be: device mse0 at isa? port 0x23c tty irq5 And in FreeBSD 4.X and later, the line should read: device mse0 at isa? port 0x23c irq5 Bus mice usually comes with dedicated interface cards. These cards may allow you to set the port address and the IRQ number other than shown above. Refer to the manual of your mouse and the &man.mse.4; manual page for more information. How do I use my PS/2 (mouse port or keyboard) mouse? The PS/2 mouse is supported out-of-the-box in all recent versions of FreeBSD. The necessary device driver, psm, is included in the GENERIC kernel. If your custom kernel does not have this, add the appropriate following line to your kernel configuration file and compile a new kernel. In FreeBSD 3.0 or earlier, the line should be: device psm0 at isa? port "IO_KBD" conflicts tty irq 12 vector psmintr In FreeBSD 3.1 or later, the line should be: device psm0 at isa? tty irq 12 In FreeBSD 4.0 or later, the line should be: device psm0 at atkbdc? irq 12 Once the kernel detects psm0 correctly at boot time, make sure that an entry for psm0 exists in /dev. You can do this by typing: &prompt.root; cd /dev; sh MAKEDEV psm0 when logged in as root. You can omit this step if you are running FreeBSD 5.0-RELEASE or newer with &man.devfs.5; enabled, since the proper device nodes will be created automatically under /dev. Is it possible to use a mouse in any way outside the X Window system? If you are using the default console driver, &man.syscons.4;, you can use a mouse pointer in text consoles to cut & paste text. Run the mouse daemon, &man.moused.8;, and turn on the mouse pointer in the virtual console: &prompt.root; moused -p /dev/xxxx -t yyyy &prompt.root; vidcontrol -m on Where xxxx is the mouse device name and yyyy is a protocol type for the mouse. The mouse daemon can automatically determine the protocol type of most mice, except old serial mice. Specify the auto protocol to invoke automatic detection. If automatic detection does not work, see the &man.moused.8; manual page for a list of supported protocol types. If you have a PS/2 mouse, just add moused_enable="YES" to /etc/rc.conf to start the mouse daemon at boot-time. Additionally, if you would like to use the mouse daemon on all virtual terminals instead of just the console, add allscreens_flags="-m on" to /etc/rc.conf. When the mouse daemon is running, access to the mouse must be coordinated between the mouse daemon and other programs such as X Windows. Refer to the FAQ Why does my mouse not work with X? for more details on this issue. How do I cut and paste text with a mouse in the text console? Once you get the mouse daemon running (see the previous section), hold down the button 1 (left button) and move the mouse to select a region of text. Then, press the button 2 (middle button) to paste it at the text cursor. Pressing button 3 (right button) will extend the selected region of text. If your mouse does not have a middle button, you may wish to emulate one or remap buttons using mouse daemon options. See the &man.moused.8; manual page for details. Does FreeBSD support any USB mice? Preliminary USB device support was added to FreeBSD 3.1. It did not always work through early versions of 3.X. As of FreeBSD 4.0, USB devices should work out of the box. If you want to experiment with the USB mouse support under FreeBSD 3.X, follow the procedure described below. Use FreeBSD 3.2 or later. Add the following lines to your kernel configuration file, and rebuild the kernel. device uhci device ohci device usb device ums In versions of FreeBSD before 4.0, use this instead: controller uhci0 controller ohci0 controller usb0 device ums0 Go to the /dev directory and create a device node as follows: &prompt.root; cd /dev &prompt.root; ./MAKEDEV ums0 You can omit this step if you are running FreeBSD 5.0-RELEASE or newer with &man.devfs.5; enabled, since the proper device nodes will be created automatically under /dev. Edit /etc/rc.conf and add the following lines: moused_enable="YES" moused_type="auto" moused_port="/dev/ums0" moused_flags="" usbd_enable="YES" usbd_flags="" See the previous section for more detailed discussion on moused. In order to use the USB mouse in the X session, edit XF86Config. If you are using &xfree86; 3.3.2 or later, be sure to have the following lines in the Pointer section: Device "/dev/sysmouse" Protocol "Auto" If you are using earlier versions of &xfree86;, be sure to have the following lines in the Pointer section: Device "/dev/sysmouse" Protocol "SysMouse" Refer to another section on the mouse support in the X environment. Hot-plugging and unplugging of the USB mouse may not work quite right yet. It is a good idea connect the mouse before you start the system and leave it connected until the system is shutdown to avoid trouble. My mouse has a fancy wheel and buttons. Can I use them in FreeBSD? The answer is, unfortunately, It depends. These mice with additional features require specialized driver in most cases. Unless the mouse device driver or the user program has specific support for the mouse, it will act just like a standard two, or three button mouse. For the possible usage of wheels in the X Window environment, refer to that section. How do I use the mouse/trackball/touchpad on my laptop? Please refer to the answer to the previous question. Also check out the Mobile Computing page. Networking and serial devices Which network cards does FreeBSD support? See the Hardware Notes supplied with each release of FreeBSD for a more complete list. Why is FreeBSD not finding my internal Plug & Play modem? You will need to add the modem's PnP ID to the PnP ID list in the serial driver. To enable Plug & Play support, compile a new kernel with controller pnp0 in the configuration file, then reboot the system. The kernel will print the PnP IDs of all the devices it finds. Copy the PnP ID from the modem to the table in /sys/i386/isa/sio.c, at about line 2777. Look for the string SUP1310 in the structure siopnp_ids[] to find the table. Build the kernel again, install, reboot, and your modem should be found. You may have to manually configure the PnP devices using the pnp command in the boot-time configuration with a command like pnp 1 0 enable os irq0 3 drq0 0 port0 0x2f8 to make the modem show. Does FreeBSD support software modems, such as Winmodems? FreeBSD supports many software modems via add-on software. The comms/ltmdm port adds support for modems based on the very popular Lucent LT chipset. The comms/mwavem port supports the modem in IBM Thinkpad 600 and 700 laptops. You cannot install FreeBSD via a software modem; this software must be installed after the OS is installed. Is there a native driver for the Broadcom 43xx cards? No, and there is not likely to be. Broadcom refuses to publically release programming information for their wireless chipsets, most likely because they use software controlled radios. In order to get FCC type acceptance for their parts, they have to ensure that users cannot arbitrarily set things like operating frequencies, modulation parameters and power output. But without knowing how to program the chipsets, it is nearly impossible to write a driver. Which multi-port serial cards are supported by FreeBSD? There is a list of these in the Miscellaneous + url="&url.books.handbook;/install.html#INSTALL-MISC">Miscellaneous devices section of the handbook. Some unnamed clone cards have also been known to work, especially those that claim to be AST compatible. Check the &man.sio.4; manual page to get more information on configuring such cards. How do I get the boot: prompt to show on the serial console? Build a kernel with options COMCONSOLE. Create /boot.config and place as the only text in the file. Unplug the keyboard from the system. See /usr/src/sys/i386/boot/biosboot/README.serial for information. Sound devices Which sound cards are supported by FreeBSD? FreeBSD supports the &soundblaster;, &soundblaster; Pro, &soundblaster; 16, Pro Audio Spectrum 16, AdLib and Gravis UltraSound sound cards. There is also limited support for MPU-401 and compatible MIDI cards. Cards conforming to the µsoft; Sound System specification are also supported through the pcm driver. This is only for sound! This driver does not support CDROMs, SCSI or joysticks on these cards, except for the &soundblaster;. The &soundblaster; SCSI interface and some non-SCSI CDROMs are supported, but you cannot boot off this device. Workarounds for no sound from es1370 with pcm driver? You can run the following command every time the machine booted up: &prompt.root; mixer pcm 100 vol 100 cd 100 Other hardware What other devices does FreeBSD support? See the Handbook + url="&url.books.handbook;/install.html#INSTALL-MISC">Handbook for the list of other devices supported. Does FreeBSD support power management on my laptop? FreeBSD supports APM on certain machines. Please look in the LINT kernel config file, searching for the APM keyword. Further information can be found in &man.apm.4;. Why does my Micron system hang at boot time? Certain Micron motherboards have a non-conforming PCI BIOS implementation that causes grief when FreeBSD boots because PCI devices do not get configured at their reported addresses. Disable the Plug and Play Operating System flag in the BIOS to work around this problem. More information can be found at + url="http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron"> http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron The boot floppy hangs on a system with an ASUS K7V motherboard. How do I fix this? Go into the BIOS setup and disable the boot virus protection. Why does my &tm.3com; PCI network card not work with my Micron computer? Certain Micron motherboards have a non-conforming PCI BIOS implementation that does not configure PCI devices at the addresses reported. This causes grief when FreeBSD boots. To work around this problem, disable the Plug and Play Operating System flag in the BIOS. More information on this problem is available at URL: - + Troubleshooting What do I do when I have bad blocks on my hard drive? With SCSI drives, the drive should be capable of re-mapping these automatically. However, many drives are shipped with this feature disabled, for some mysterious reason... To enable this, you will need to edit the first device page mode, which can be done on FreeBSD by giving the command (as root) &prompt.root; camcontrol modepage sd0 -m 1 -e -P 3 and changing the values of AWRE and ARRE from 0 to 1:- AWRE (Auto Write Reallocation Enbld): 1 ARRE (Auto Read Reallocation Enbld): 1 The following paragraphs were submitted by Ted Mittelstaedt tedm@toybox.placo.com: For IDE drives, any bad block is usually a sign of potential trouble. All modern IDE drives come with internal bad-block remapping turned on. All IDE hard drive manufacturers today offer extensive warranties and will replace drives with bad blocks on them. If you still want to attempt to rescue an IDE drive with bad blocks, you can attempt to download the IDE drive manufacturer's IDE diagnostic program, and run this against the drive. Sometimes these programs can be set to force the drive electronics to rescan the drive for bad blocks and lock them out. For ESDI, RLL and MFM drives, bad blocks are a normal part of the drive and are no sign of trouble, generally. With a PC, the disk drive controller card and BIOS handle the task of locking out bad sectors. This is fine for operating systems like DOS that use BIOS code to access the disk. However, FreeBSD's disk driver does not go through BIOS, therefore a mechanism, bad144, exists that replaces this functionality. bad144 only works with the wd driver (which means it is not supported in FreeBSD 4.0), it is NOT able to be used with SCSI. bad144 works by entering all bad sectors found into a special file. One caveat with bad144 - the bad block special file is placed on the last track of the disk. As this file may possibly contain a listing for a bad sector that would occur near the beginning of the disk, where the /kernel file might be located, it therefore must be accessible to the bootstrap program that uses BIOS calls to read the kernel file. This means that the disk with bad144 used on it must not exceed 1024 cylinders, 16 heads, and 63 sectors. This places an effective limit of 500MB on a disk that is mapped with bad144. To use bad144, simply set the Bad Block scanning to ON in the FreeBSD fdisk screen during the initial install. This works up through FreeBSD 2.2.7. The disk must have less than 1024 cylinders. It is generally recommended that the disk drive has been in operation for at least 4 hours prior to this to allow for thermal expansion and track wandering. If the disk has more than 1024 cylinders (such as a large ESDI drive) the ESDI controller uses a special translation mode to make it work under DOS. The wd driver understands about these translation modes, IF you enter the translated geometry with the set geometry command in fdisk. You must also NOT use the dangerously dedicated mode of creating the FreeBSD partition, as this ignores the geometry. Also, even though fdisk will use your overridden geometry, it still knows the true size of the disk, and will attempt to create a too large FreeBSD partition. If the disk geometry is changed to the translated geometry, the partition MUST be manually created with the number of blocks. A quick trick to use is to set up the large ESDI disk with the ESDI controller, boot it with a DOS disk and format it with a DOS partition. Then, boot the FreeBSD install and in the fdisk screen, read off and write down the blocksize and block numbers for the DOS partition. Then, reset the geometry to the same that DOS uses, delete the DOS partition, and create a cooperative FreeBSD partition using the blocksize you recorded earlier. Then, set the partition bootable and turn on bad block scanning. During the actual install, bad144 will run first, before any filesystems are created (you can view this with an AltF2). If it has any trouble creating the badsector file, you have set too large a disk geometry - reboot the system and start all over again (including repartitioning and reformatting with DOS). If remapping is enabled and you are seeing bad blocks, consider replacing the drive. The bad blocks will only get worse as time goes on. Why does FreeBSD not recognize my Bustek 742a EISA SCSI controller? This info is specific to the 742a but may also cover other Buslogic cards. (Bustek = Buslogic) There are 2 general versions of the 742a card. They are hardware revisions A-G, and revisions H - onwards. The revision letter is located after the Assembly number on the edge of the card. The 742a has 2 ROM chips on it, one is the BIOS chip and the other is the Firmware chip. FreeBSD does not care what version of BIOS chip you have but it does care about what version of firmware chip. Buslogic will send upgrade ROMs out if you call their tech support dept. The BIOS and Firmware chips are shipped as a matched pair. You must have the most current Firmware ROM in your adapter card for your hardware revision. The REV A-G cards can only accept BIOS/Firmware sets up to 2.41/2.21. The REV H- up cards can accept the most current BIOS/Firmware sets of 4.70/3.37. The difference between the firmware sets is that the 3.37 firmware supports round robin. The Buslogic cards also have a serial number on them. If you have an old hardware revision card you can call the Buslogic RMA department and give them the serial number and attempt to exchange the card for a newer hardware revision. If the card is young enough they will do so. FreeBSD 2.1 only supports Firmware revisions 2.21 onward. If you have a Firmware revision older than this your card will not be recognized as a Buslogic card. It may be recognized as an &adaptec; 1540, however. The early Buslogic firmware contains an AHA1540 emulation mode. This is not a good thing for an EISA card, however. If you have an old hardware revision card and you obtain the 2.21 firmware for it, you will need to check the position of jumper W1 to B-C, the default is A-B. Why does FreeBSD not detect my HP Netserver's SCSI controller? This is basically a known problem. The EISA on-board SCSI controller in the HP Netserver machines occupies EISA slot number 11, so all the true EISA slots are in front of it. Alas, the address space for EISA slots >= 10 collides with the address space assigned to PCI, and FreeBSD's auto-configuration currently cannot handle this situation very well. So now, the best you can do is to pretend there is no address range clash :), by bumping the kernel option EISA_SLOTS to a value of 12. Configure and compile a kernel, as described in the Handbook entry on + url="&url.books.handbook;/kernelconfig.html">Handbook entry on configuring the kernel. Of course, this does present you with a chicken-and-egg problem when installing on such a machine. In order to work around this problem, a special hack is available inside UserConfig. Do not use the visual interface, but the plain command-line interface there. Simply type eisa 12 quit at the prompt, and install your system as usual. While it is recommended you compile and install a custom kernel anyway. Hopefully, future versions will have a proper fix for this problem. You cannot use a dangerously dedicated disk with an HP Netserver. See this note for more info. I keep seeing messages like ed1: timeout. What do these messages mean? This is usually caused by an interrupt conflict (e.g., two boards using the same IRQ). FreeBSD prior to 2.0.5R used to be tolerant of this, and the network driver would still function in the presence of IRQ conflicts. However, with 2.0.5R and later, IRQ conflicts are no longer tolerated. Boot with the -c option and change the ed0/de0/... entry to match your board. If you are using the BNC connector on your network card, you may also see device timeouts because of bad termination. To check this, attach a terminator directly to the NIC (with no cable) and see if the error messages go away. Some NE2000 compatible cards will give this error if there is no link on the UTP port or if the cable is disconnected. Why did my &tm.3com; 3C509 card stop working for no apparent reason? This card has a bad habit of losing its configuration information. Refresh your card's settings with the DOS utility 3c5x9.exe. My parallel printer is ridiculously slow. What can I do? If the only problem is that the printer is terribly slow, try changing your printer port mode as discussed in the Printer Setup section of the Handbook. Why do my programs occasionally die with Signal 11 errors? Signal 11 errors are caused when your process has attempted to access memory which the operating system has not granted it access to. If something like this is happening at seemingly random intervals then you need to start investigating things very carefully. These problems can usually be attributed to either: If the problem is occurring only in a specific application that you are developing yourself it is probably a bug in your code. If it is a problem with part of the base FreeBSD system, it may also be buggy code, but more often than not these problems are found and fixed long before us general FAQ readers get to use these bits of code (that is what -current is for). In particular, a dead giveaway that this is not a FreeBSD bug is if you see the problem when you are compiling a program, but the activity that the compiler is carrying out changes each time. For example, suppose you are running make buildworld, and the compile fails while trying to compile ls.c into ls.o. If you then run make buildworld again, and the compile fails in the same place then this is a broken build -- try updating your sources and try again. If the compile fails elsewhere then this is almost certainly hardware. What you should do: In the first case you can use a debugger e.g. gdb to find the point in the program which is attempting to access a bogus address and then fix it. In the second case you need to verify that it is not your hardware at fault. Common causes of this include: Your hard disks might be overheating: Check the fans in your case are still working, as your disk (and perhaps other hardware might be overheating). The processor running is overheating: This might be because the processor has been overclocked, or the fan on the processor might have died. In either case you need to ensure that you have hardware running at what it is specified to run at, at least while trying to solve this problem. i.e. Clock it back to the default settings. If you are overclocking then note that it is far cheaper to have a slow system than a fried system that needs replacing! Also the wider community is not often sympathetic to problems on overclocked systems, whether you believe it is safe or not. Dodgy memory: If you have multiple memory SIMMS/DIMMS installed then pull them all out and try running the machine with each SIMM or DIMM individually and narrow the problem down to either the problematic DIMM/SIMM or perhaps even a combination. Over-optimistic Motherboard settings: In your BIOS settings, and some motherboard jumpers you have options to set various timings, mostly the defaults will be sufficient, but sometimes, setting the wait states on RAM too low, or setting the RAM Speed: Turbo option, or similar in the BIOS will cause strange behavior. A possible idea is to set to BIOS defaults, but it might be worth noting down your settings first! Unclean or insufficient power to the motherboard. If you have any unused I/O boards, hard disks, or CDROMs in your system, try temporarily removing them or disconnecting the power cable from them, to see if your power supply can manage a smaller load. Or try another power supply, preferably one with a little more power (for instance, if your current power supply is rated at 250 Watts try one rated at 300 Watts). You should also read the SIG11 FAQ (listed below) which has excellent explanations of all these problems, albeit from a &linux; viewpoint. It also discusses how memory testing software or hardware can still pass faulty memory. Finally, if none of this has helped it is possible that you have just found a bug in FreeBSD, and you should follow the instructions to send a problem report. There is an extensive FAQ on this at + url="http://www.bitwizard.nl/sig11/"> the SIG11 problem FAQ My system crashes with either Fatal trap 12: page fault in kernel mode, or panic:, and spits out a bunch of information. What should I do? The FreeBSD developers are very interested in these errors, but need some more information than just the error you see. Copy your full crash message. Then consult the FAQ section on kernel panics, build a debugging kernel, and get a backtrace. This might sound difficult, but you do not need any programming skills; you just have to follow the instructions. Why does the screen go black and lose sync when I boot? This is a known problem with the ATI Mach 64 video card. The problem is that this card uses address 2e8, and the fourth serial port does too. Due to a bug (feature?) in the &man.sio.4; driver it will touch this port even if you do not have the fourth serial port, and even if you disable sio3 (the fourth port) which normally uses this address. Until the bug has been fixed, you can use this workaround: Enter at the boot prompt. (This will put the kernel into configuration mode). Disable sio0, sio1, sio2 and sio3 (all of them). This way the sio driver does not get activated -> no problems. Type exit to continue booting. If you want to be able to use your serial ports, you will have to build a new kernel with the following modification: in /usr/src/sys/i386/isa/sio.c find the one occurrence of the string 0x2e8 and remove that string and the preceding comma (keep the trailing comma). Now follow the normal procedure of building a new kernel. Even after applying these workarounds, you may still find that the X Window System does not work properly. If this is the case, make sure that the &xfree86; version you are using is at least &xfree86; 3.3.3 or higher. This version and upwards has built-in support for the Mach64 cards and even a dedicated X server for those cards. Why does FreeBSD only use 64 MB of RAM when my system has 128 MB of RAM installed? Due to the manner in which FreeBSD gets the memory size from the BIOS, it can only detect 16 bits worth of Kbytes in size (65535 Kbytes = 64MB) (or less... some BIOSes peg the memory size to 16M). If you have more than 64MB, FreeBSD will attempt to detect it; however, the attempt may fail. To work around this problem, you need to use the kernel option specified below. There is a way to get complete memory information from the BIOS, but we do not have room in the bootblocks to do it. Someday when lack of room in the bootblocks is fixed, we will use the extended BIOS functions to get the full memory information...but for now we are stuck with the kernel option. options "MAXMEM=n" Where n is your memory in Kilobytes. For a 128 MB machine, you would want to use 131072. Why does FreeBSD 2.0 panic with kmem_map too small!? The message may also be mb_map too small! The panic indicates that the system ran out of virtual memory for network buffers (specifically, mbuf clusters). You can increase the amount of VM available for mbuf clusters by adding: options "NMBCLUSTERS=n" to your kernel config file, where n is a number in the range 512-4096, depending on the number of concurrent TCP connections you need to support. I would recommend trying 2048 - this should get rid of the panic completely. You can monitor the number of mbuf clusters allocated/in use on the system with netstat -m (see &man.netstat.1;). The default value for NMBCLUSTERS is 512 + MAXUSERS * 16. Why do I get the error /kernel: proc: table is full? The FreeBSD kernel will only allow a certain number of processes to exist at one time. The number is based on the MAXUSERS option in the kernel configuration. MAXUSERS also affects various other in-kernel limits, such as network buffers (see this earlier question). If your machine is heavily loaded, you probably want to increase MAXUSERS. This will increase these other system limits in addition to the maximum number of processes. After FreeBSD 4.4, MAXUSERS became a tunable value that could be set with kern.maxusers in /boot/loader.conf. In earlier versions of FreeBSD, you need to adjust MAXUSERS in your kernel configuration. If your machine is lightly loaded, and you are simply running a very large number of processes, you can adjust this with the kern.maxproc sysctl. If these processes are being run by a single user, you will also need to adjust kern.maxprocperuid to be one less than your new kern.maxproc value. (It must be at least one less because one system program, &man.init.8;, must always be running.) To make a sysctl permanent across reboots, set this in /etc/sysctl.conf in recent versions of FreeBSD, or /etc/rc.local in older versions. Why do I get an error reading CMAP busy when rebooting with a new kernel? The logic that attempts to detect an out of date /var/db/kvm_*.db files sometimes fails and using a mismatched file can sometimes lead to panics. If this happens, reboot single-user and do: &prompt.root; rm /var/db/kvm_*.db What does the message ahc0: brkadrint, Illegal Host Access at seqaddr 0x0 mean? This is a conflict with an Ultrastor SCSI Host Adapter. During the boot process enter the kernel configuration menu and disable uha0, which is causing the problem. When I boot my system, I get the error ahc0: illegal cable configuration. My cabling is correct. What is going on? Your motherboard lacks the external logic to support automatic termination. Switch your SCSI BIOS to specify the correct termination for your configuration rather than automatic termination. The AIC7XXX driver cannot determine if the external logic for cable detection (and thus auto-termination) is available. The driver simply assumes that this support must exist if the configuration contained in the serial EEPROM is set to "automatic termination". Without the external cable detection logic the driver will often configure termination incorrectly, which can compromise the reliability of the SCSI bus. Why does Sendmail give me an error reading mail loops back to myself? This is answered in the sendmail FAQ as follows:- * I'm getting "Local configuration error" messages, such as: 553 relay.domain.net config error: mail loops back to myself 554 <user@domain.net>... Local configuration error How can I solve this problem? You have asked mail to the domain (e.g., domain.net) to be forwarded to a specific host (in this case, relay.domain.net) by using an MX record, but the relay machine does not recognize itself as domain.net. Add domain.net to /etc/mail/local-host-names (if you are using FEATURE(use_cw_file)) or add "Cw domain.net" to /etc/mail/sendmail.cf. The current version of the sendmail + url="ftp://rtfm.mit.edu/pub/usenet/news.answers/mail/sendmail-faq">sendmail FAQ is no longer maintained with the sendmail release. It is however regularly posted to comp.mail.sendmail, - comp.mail.misc, comp.mail.smail, comp.answers, and news.answers. You can also + url="news:comp.mail.sendmail">comp.mail.sendmail, + comp.mail.misc, comp.mail.smail, comp.answers, and news.answers. You can also receive a copy via email by sending a message to mail-server@rtfm.mit.edu with the command send usenet/news.answers/mail/sendmail-faq as the body of the message. Why do full screen applications on remote machines misbehave? The remote machine may be setting your terminal type to something other than the cons25 terminal type required by the FreeBSD console. There are a number of possible work-arounds for this problem: After logging on to the remote machine, set your TERM shell variable to ansi or sco if the remote machine knows about these terminal types. Use a VT100 emulator like screen at the FreeBSD console. screen offers you the ability to run multiple concurrent sessions from one terminal, and is a neat program in its own right. Each screen window behaves like a VT100 terminal, so the TERM variable at the remote end should be set to vt100. Install the cons25 terminal database entry on the remote machine. The way to do this depends on the operating system on the remote machine. The system administration manuals for the remote system should be able to help you here. Fire up an X server at the FreeBSD end and login to the remote machine using an X based terminal emulator such as xterm or rxvt. The TERM variable at the remote host should be set to xterm or vt100. Why does my machine print calcru: negative time...? This can be caused by various hardware or software ailments relating to interrupts. It may be due to bugs but can also happen by nature of certain devices. Running TCP/IP over the parallel port using a large MTU is one good way to provoke this problem. Graphics accelerators can also get you here, in which case you should check the interrupt setting of the card first. A side effect of this problem are dying processes with the message SIGXCPU exceeded cpu time limit. For FreeBSD 3.0 and later from Nov 29, 1998 forward: If the problem cannot be fixed otherwise the solution is to set this sysctl variable: &prompt.root; sysctl -w kern.timecounter.method=1 The option of &man.sysctl.8; is deprecated and silently ignored in &os; 4.4-RELEASE and all newer versions. You can safely ommit it when setting options with sysctl as shown above. This means a performance impact, but considering the cause of this problem, you probably will not notice. If the problem persists, keep the sysctl set to one and set the NTIMECOUNTER option in your kernel to increasingly large values. If by the time you have reached NTIMECOUNTER=20 the problem is not solved, interrupts are too hosed on your machine for reliable time keeping. I see pcm0 not found or my sound card is found as pcm1 but I have device pcm0 in my kernel config file. What is going on? This occurs in FreeBSD 3.X with PCI sound cards. The pcm0 device is reserved exclusively for ISA-based cards so, if you have a PCI card, then you will see this error, and your card will appear as pcm1. You cannot remove the warning by simply changing the line in the kernel config file to device pcm1 as this will result in pcm1 being reserved for ISA cards and your PCI card being found as pcm2 (along with the warning pcm1 not found). If you have a PCI sound card you will also have to make the snd1 device rather than snd0: &prompt.root; cd /dev &prompt.root; ./MAKEDEV snd1 You can omit this step if you are running FreeBSD 5.0-RELEASE or newer with &man.devfs.5; enabled, since the proper device nodes will be created automatically under /dev. This situation does not arise in FreeBSD 4.X as a lot of work has been done to make it more PnP-centric and the pcm0 device is no longer reserved exclusively for ISA cards Why is my PnP card no longer found (or found as unknown) since upgrading to FreeBSD 4.X? FreeBSD 4.X is now much more PnP-centric and this has had the side effect of some PnP devices (e.g. sound cards and internal modems) not working even though they worked under FreeBSD 3.X. The reasons for this behavior are explained by the following e-mail, posted to the freebsd-questions mailing list by Peter Wemm, in answer to a question about an internal modem that was no longer found after an upgrade to FreeBSD 4.X (the comments in [] have been added to clarify the context. The contents of this quotation has been updated from its original text.
The PNP bios preconfigured it [the modem] and left it laying around in port space, so [in 3.X] the old-style ISA probes found it there. Under 4.0, the ISA code is much more PnP-centric. It was possible [in 3.X] for an ISA probe to find a stray device and then for the PNP device id to match and then fail due to resource conflicts. So, it disables the programmable cards first so this double probing cannot happen. It also means that it needs to know the PnP id's for supported PnP hardware. Making this more user tweakable is on the TODO list.
To get the device working again requires finding its PnP id and adding it to the list that the ISA probes use to identify PnP devices. This is obtained using &man.pnpinfo.8; to probe the device, for example this is the output from &man.pnpinfo.8; for an internal modem: &prompt.root; pnpinfo Checking for Plug-n-Play devices... Card assigned CSN #1 Vendor ID PMC2430 (0x3024a341), Serial Number 0xffffffff PnP Version 1.0, Vendor Version 0 Device Description: Pace 56 Voice Internal Plug & Play Modem Logical Device ID: PMC2430 0x3024a341 #0 Device supports I/O Range Check TAG Start DF I/O Range 0x3f8 .. 0x3f8, alignment 0x8, len 0x8 [16-bit addr] IRQ: 4 - only one type (true/edge) [more TAG lines elided] TAG End DF End Tag Successfully got 31 resources, 1 logical fdevs -- card select # 0x0001 CSN PMC2430 (0x3024a341), Serial Number 0xffffffff Logical device #0 IO: 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 0x03e8 IRQ 5 0 DMA 4 0 IO range check 0x00 activate 0x01 The information you require is in the Vendor ID line at the start of the output. The hexadecimal number in parentheses (0x3024a341 in this example) is the PnP id and the string immediately before this (PMC2430) is a unique ASCII id. Alternatively, if &man.pnpinfo.8; does not list the card in question, &man.pciconf.8; can be used instead. This is part of the output from pciconf -vl for an onboard sound chip: &prompt.root; pciconf -vl chip1@pci0:31:5: class=0x040100 card=0x00931028 chip=0x24158086 rev=0x02 hdr=0x00 vendor = 'Intel Corporation' device = '82801AA 8xx Chipset AC'97 Audio Controller' class = multimedia subclass = audio Here, you would use the chip value, 0x24158086. This information (Vendor ID or chip value) needs adding to the file /usr/src/sys/isa/sio.c. You should first make a backup of sio.c just in case things go wrong. You will also need it to make the patch to submit with your PR (you are going to submit a PR, are you not?) then edit sio.c and search for the line static struct isa_pnp_id sio_ids[] = { then scroll down to find the correct place to add the entry for your device. The entries look like this, and are sorted on the ASCII Vendor ID string which should be included in the comment to the right of the line of code along with all (if it will fit) or part of the Device Description from the output of &man.pnpinfo.8;: {0x0f804f3f, NULL}, /* OZO800f - Zoom 2812 (56k Modem) */ {0x39804f3f, NULL}, /* OZO8039 - Zoom 56k flex */ {0x3024a341, NULL}, /* PMC2430 - Pace 56 Voice Internal Modem */ {0x1000eb49, NULL}, /* ROK0010 - Rockwell ? */ {0x5002734a, NULL}, /* RSS0250 - 5614Jx3(G) Internal Modem */ Add the hexadecimal Vendor ID for your device in the correct place, save the file, rebuild your kernel, and reboot. Your device should now be found as an sio device as it was under FreeBSD 3.X Why do I get the error nlist failed when running, for example, top or systat? The problem is that the application you are trying to run is looking for a specific kernel symbol, but, for whatever reason, cannot find it; this error stems from one of two problems: Your kernel and userland are not synchronized (i.e., you built a new kernel but did not do an installworld, or vice versa), and thus the symbol table is different from what the user application thinks it is. If this is the case, simply complete the upgrade process (see /usr/src/UPDATING for the correct sequence). You are not using /boot/loader to load your kernel, but doing it directly from boot2 (see &man.boot.8;). While there is nothing wrong with bypassing /boot/loader, it generally does a better job of making the kernel symbols available to user applications. Why does it take so long to connect to my computer via ssh or telnet? The symptom: there is a long delay between the time the TCP connection is established and the time when the client software asks for a password (or, in &man.telnet.1;'s case, when a login prompt appears). The problem: more likely than not, the delay is caused by the server software trying to resolve the client's IP address into a hostname. Many servers, including the Telnet and SSH servers that come with FreeBSD, do this in order to, among other things, store the hostname in a log file for future reference by the administrator. The remedy: if the problem occurs whenever you connect from your computer (the client) to any server, the problem is with the client; likewise, if the problem only occurs when someone connects to your computer (the server) the problem is with the server. If the problem is with the client, the only remedy is to fix the DNS so the server can resolve it. If this is on a local network, consider it a server problem and keep reading; conversely, if this is on the global Internet, you will most likely need to contact your ISP and ask them to fix it for you. If the problem is with the server, and this is on a local network, you need to configure the server to be able to resolve address-to-hostname queries for your local address range. See the &man.hosts.5; and &man.named.8; manual pages for more information. If this is on the global Internet, the problem may be that your server's resolver is not functioning correctly. To check, try to look up another host--say, www.yahoo.com. If it does not work, that is your problem. What does stray IRQ mean? Stray IRQs are indications of hardware IRQ glitches, mostly from hardware that removes its interrupt request in the middle of the interrupt request acknowledge cycle. One has three options for dealing with this: Live with the warnings. All except the first 5 per irq are suppressed anyway. Break the warnings by changing 5 to 0 in isa_strayintr() so that all the warnings are suppressed. Break the warnings by installing parallel port hardware that uses irq 7 and the PPP driver for it (this happens on most systems), and install an ide drive or other hardware that uses irq 15 and a suitable driver for it. Why does file: table is full show up repeatedly in dmesg? This error message indicates you have exhausted the number of available file descriptors on your system. Please see the kern.maxfiles section of the Tuning Kernel Limits section of the Handbook for a discussion and solution. Why does the clock on my laptop keep incorrect time? Your laptop has two or more clocks, and FreeBSD has chosen to use the wrong one. Run &man.dmesg.8;, and check for lines that contain Timecounter. The last line printed is the one that FreeBSD chose, and will almost certainly be TSC. &prompt.root; dmesg | grep Timecounter Timecounter "i8254" frequency 1193182 Hz Timecounter "TSC" frequency 595573479 Hz You can confirm this by checking the kern.timecounter.hardware &man.sysctl.3;. &prompt.root; sysctl kern.timecounter.hardware kern.timecounter.hardware: TSC The BIOS may modify the TSC clock—perhaps to change the speed of the processor when running from batteries, or going into a power saving mode, but FreeBSD is unaware of these adjustments, and appears to gain or lose time. In this example, the i8254 clock is also available, and can be selected by writing its name to the kern.timecounter.hardware &man.sysctl.3;. &prompt.root; sysctl -w kern.timecounter.hardware=i8254 kern.timecounter.hardware: TSC -> i8254 Your laptop should now start keeping more accurate time. To have this change automatically run at boot time, add the following line to /etc/sysctl.conf. kern.timecounter.hardware=i8254 Why did my laptop fail to correctly probe PC cards? This problem is common on laptops that boot more than one operating system. Some non-BSD operating systems leave PC card hardware in an inconsistent state. pccardd will detect the card as "(null)""(null)" instead of its actual model. You must remove all power from the PC card slot to fully reset the hardware. Completely power off the laptop. (Don't suspend it, don't let it go into standby; the power needs to be completely off.) Wait a few moments, and reboot. Your PC card should work now. Some laptop hardware lies when it claims to be off. If the above does not work shut down, remove the battery, wait a moment, replace the battery, and reboot. Why does FreeBSD's boot loader display Read error and stop after the BIOS screen? FreeBSD's boot loader is incorrectly recognizing the hard drive's geometry. This must be manually set within fdisk when creating or modifying FreeBSD's slice. The correct drive geometry values can be found within the machine's BIOS. Look for the number of cylinders, heads and sectors for the particular drive. Within &man.sysinstall.8;'s fdisk, hit G to set the drive geometry. A dialog will pop up requesting the number of cylinders, heads and sectors. Type the numbers found from the BIOS separates by forward slashes. 5000 cylinders, 250 sectors and 60 sectors would be entered as 5000/250/60 Press enter to set the values, and hit W to write the new partition table to the drive. Another operating system destroyed my Boot Manager. How do I get it back? Enter &man.sysinstall.8; and choose Configure, then Fdisk. Select the disk the Boot Manager resided on with the space key. Press W to write changes to the drive. A prompt will appear asking which boot loader to install. Select this, and it will be restored. What does the error swap_pager: indefinite wait buffer: mean? This means that a process is trying to page memory to disk, and the page attempt has hung trying to access the disk for more than 20 seconds. It might be caused by bad blocks on the disk drive, disk wiring, cables, or any other disk I/O-related hardware. If the drive itself is actually bad, you will also see disk errors in /var/log/messages and in the output of dmesg. Otherwise, check your cables and connections. What are UDMA ICRC errors, and how do I fix them? The &man.ata.4; driver reports UDMA ICRC errors when a DMA transfer to or from a drive is corrupted. The driver will retry the operation a few times. Should the retries fail, it will switch from DMA to the slower PIO mode of communication with the device. The problem can be caused by many factors, although perhaps the most common cause is faulty or incorrect cabling. Check that the ATA cables are undamaged and rated for the Ultra DMA mode in use. If you're using removable drive trays, they must also be compatible. Be sure that all connections are making good contact. Problems have also been noticed when an old drive is installed on the same ATA channel as an Ultra DMA 66 (or faster) drive. Lastly, these errors can indicate that the drive is failing. Most drive vendors provide testing software for their drives, so test your drive, and, if necessary, back up your data and replace it. The &man.atacontrol.8; utility can be used to show and select the DMA or PIO modes used for each ATA device. In particular, atacontrol mode channel will show the modes in use on a particular ATA channel, where the primary channel is numbered 0, and so on. What is a lock order reversal? &a.rwatson; answered this question very succinctly on the freebsd-current list in a thread entitled lock order reversals - what do they mean?
&a.rwatson; on freebsd-current, December 14, 2003 These warnings are generated by Witness, a run-time lock diagnostic system found in FreeBSD 5-CURRENT kernels (but removed in releases). You can read more about Witness in the &man.witness.4; man page, which talks about its capabilities. Among other things, Witness performs run-time lock order verification using a combination of hard coded lock orders, and run-time detected lock orders, and generates console warnings when lock orders are violated. The intent of this is to detect the potential for deadlocks due to lock order violations; it's worth observing that Witness is actually slightly conservative, and so it's possible to get false positives. In the event that Witness is accurately reporting a lock order problem, it's basically saying "If you were unlucky, a deadlock would have happened here". There are a couple of "well known" false positives, which we need to do a better job of documenting to prevent spurious reports. The non-well-known ones typically correspond to bugs in newly added locking, as lock order reversals usually get fixed pretty quickly because Witness is busy generating warnings :-).
See Bjoern Zeeb's lock order reversal page for the status of known lock order reversals. Commercial Applications This section is still very sparse, though we are hoping, of course, that companies will add to it! :) The FreeBSD group has no financial interest in any of the companies listed here but simply lists them as a public service (and feels that commercial interest in FreeBSD can have very positive effects on FreeBSD's long-term viability). We encourage commercial software vendors to send their entries here for inclusion. See the + url="&url.base;/commercial/index.html">the Vendors page for a longer list. Where can I get an Office Suite for FreeBSD? The FreeBSD Mall offers a FreeBSD native version of VistaSource ApplixWare 5. ApplixWare is a rich full-featured, commercial Office Suite for FreeBSD containing a word processor, spreadsheet, presentation program, vector drawing package, and other applications. ApplixWare is offered as part of the FreeBSD Mall's BSD Desktop Edition. The &linux; version of StarOffice works flawlessly on FreeBSD. The easiest way to install the &linux; version of StarOffice is through the FreeBSD Ports collection. Future versions of the open-source OpenOffice suite should work as well. Where can I get &motif; for FreeBSD? The Open Group has released the source code to &motif; 2.1.30. You can install the open-motif package, or compile it from ports. Refer to the ports section of the Handbook for more information on how to do this. The Open &motif; distribution only allows redistribution if it is running on an open source operating system. In addition, there are commercial distributions of the &motif; software available. These, however, are not for free, but their license allows them to be used in closed-source software. Contact Apps2go for the least expensive ELF &motif; 2.1.20 distribution for FreeBSD (either &i386; or Alpha). There are two distributions, the development edition and the runtime edition (for much less). These distributions includes: OSF/&motif; manager, xmbind, panner, wsm. Development kit with uil, mrm, xm, xmcxx, include and Imake files. Static and dynamic ELF libraries (for use with FreeBSD 3.0 and above). Demonstration applets. Be sure to specify that you want the FreeBSD version of &motif; when ordering (do not forget to mention the architecture you want too)! Versions for NetBSD and OpenBSD are also sold by Apps2go. This is currently a FTP only download. More info - + Apps2go WWW page or sales@apps2go.com or support@apps2go.com or phone (817) 431 8775 or +1 817 431-8775 Contact Metro Link for an either ELF or a.out &motif; 2.1 distribution for FreeBSD. This distribution includes: OSF/&motif; manager, xmbind, panner, wsm. Development kit with uil, mrm, xm, xmcxx, include and Imake files. Static and dynamic libraries (specify ELF for use with FreeBSD 3.0 and later; or a.out for use with FreeBSD 2.2.8 and earlier). Demonstration applets. Preformatted manual pages. Be sure to specify that you want the FreeBSD version of &motif; when ordering! Versions for &linux; are also sold by Metro Link. This is available on either a CDROM or for FTP download. Contact Xi Graphics for an a.out &motif; 2.0 distribution for FreeBSD. This distribution includes: OSF/&motif; manager, xmbind, panner, wsm. Development kit with uil, mrm, xm, xmcxx, include and Imake files. Static and dynamic libraries (for use with FreeBSD 2.2.8 and earlier). Demonstration applets. Preformatted manual pages. Be sure to specify that you want the FreeBSD version of &motif; when ordering! Versions for BSDI and &linux; are also sold by Xi Graphics. This is currently a 4 diskette set... in the future this will change to a unified CD distribution like their CDE. Where can I get CDE for FreeBSD? Xi Graphics used to sell CDE for FreeBSD, but no longer do. - KDE is an open + KDE is an open source X11 desktop which is similar to CDE in many respects. You might also like the look and feel of xfce. KDE and xfce are both - in the ports + url="http://www.xfce.org/">xfce. KDE and xfce are both + in the ports system. Are there any commercial high-performance X servers? - Yes, Xi Graphics - and Metro Link + Yes, Xi Graphics + and Metro Link sell Accelerated-X product for FreeBSD and other Intel based systems. The Metro Link offering is a high performance X Server that offers easy configuration using the FreeBSD Package suite of tools, support for multiple concurrent video boards and is distributed in binary form only, in a convenient FTP download. Not to mention the Metro Link offering is available at the very reasonable price of $39. Metro Link also sells both ELF and a.out &motif; for FreeBSD (see above). More info - + Metro Link WWW page or sales@metrolink.com or tech@metrolink.com or phone (954) 938-0283 or +1 954 938-0283 The Xi Graphics offering is a high performance X Server that offers easy configuration, support for multiple concurrent video boards and is distributed in binary form only, in a unified diskette distribution for FreeBSD and &linux;. Xi Graphics also offers a high performance X Server tailored for laptop support. There is a free compatibility demo of version 5.0 available. Xi Graphics also sells &motif; and CDE for FreeBSD (see above). More info - + Xi Graphics WWW page or sales@xig.com or support@xig.com or phone (800) 946 7433 or +1 303 298-7478. Are there any Database systems for FreeBSD? Yes! See the + url="&url.base;/commercial/software_bycat.html#CATEGORY_DATABASE"> Commercial Vendors section of FreeBSD's Web site. Also see the + url="&url.base;/ports/databases.html"> Databases section of the Ports collection. Can I run &oracle; on FreeBSD? Yes. The following pages tell you exactly how to set up &linux;-&oracle; on FreeBSD: + url="http://www.scc.nl/~marcel/howto-oracle.html"> http://www.scc.nl/~marcel/howto-oracle.html + url="http://www.lf.net/lf/pi/oracle/install-linux-oracle-on-freebsd"> http://www.lf.net/lf/pi/oracle/install-linux-oracle-on-freebsd User Applications So, where are all the user applications? Please take a look at the ports page + url="&url.base;/ports/index.html">the ports page for info on software packages ported to FreeBSD. The list currently tops &os.numports; and is growing daily, so come back to check often or subscribe to the freebsd-announce mailing list for periodic updates on new entries. Most ports should work on the 4.X and 5.X branches. Each time a FreeBSD release is made, a snapshot of the ports tree at the time of release in also included in the ports/ directory. We also support the concept of a package, essentially no more than a gzipped binary distribution with a little extra intelligence embedded in it for doing whatever custom installation work is required. A package can be installed and uninstalled again easily without having to know the gory details of which files it includes. Use the package installation menu in /stand/sysinstall (under the post-configuration menu item) or invoke the &man.pkg.add.1; command on the specific package files you are interested in installing. Package files can usually be identified by their .tgz suffix and CDROM distribution people will have a packages/All directory on their CD which contains such files. They can also be downloaded over the net for various versions of FreeBSD at the following locations: for 4.X-RELEASE/4-STABLE + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-4-stable/"> ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-4-stable/ for 5.X-CURRENT + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-5-current/"> ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/packages-5-current or your nearest local mirror site. Note that all ports may not be available as packages since new ones are constantly being added. It is always a good idea to check back periodically to see which packages are available at the ftp.FreeBSD.org + url="ftp://ftp.FreeBSD.org/pub/FreeBSD/">ftp.FreeBSD.org master site. Why does ghostscript give lots of errors with my 386/486SX? You do not have a math co-processor, right? You will need to add the alternative math emulator to your kernel; you do this by adding the following to your kernel config file and it will be compiled in. options GPL_MATH_EMULATE You will need to remove the MATH_EMULATE option when you do this. How do I configure INN (Internet News) for my machine? After installing the news/inn package or port, an excellent place to start is Dave + url="http://www.cis.ohio-state.edu/~barr/INN.html">Dave Barr's INN Page where you will find the INN FAQ. What version of µsoft; FrontPage should I get? Use the Port, Luke! A pre-patched version of Apache, www/apache13-fp, is available in the ports tree. Does FreeBSD support &java;? Yes. Please see + url="&url.base;/java/index.html"> http://www.FreeBSD.org/java/. Why can I not build this port on my 3.X-STABLE machine? If you are running a FreeBSD version that lags significantly behind -CURRENT or -STABLE, you may need a ports - upgrade kit from + upgrade kit from http://www.FreeBSD.org/ports/. If you are up to date, then someone might have committed a change to the port which works for -CURRENT but which broke the port for -STABLE. Please submit a bug report on this with the &man.send-pr.1; command, since the ports collection is supposed to work for both the -CURRENT and -STABLE branches. I just tried to build INDEX using make index, and it failed. Why? First, always make sure that you have a completely up-to-date Ports Collection. Errors that affect building INDEX from an up-to-date copy of the Ports Collection are high-visibility and are thus almost always fixed immediately. However, if you are up-to-date, perhaps you are seeing another problem. make index has a known bug in dealing with incomplete copies of the Ports Collection. It assumes that you have a local copy of every single port that every other port that you have a local copy of depends on. To explain, if you have a copy of foo/bar on your disk, and foo/bar depends on baz/quux, then you must also have a copy of baz/quux on your disk, and the ports baz/quux depends on, and so on. Otherwise, make index has insufficient information to create its dependency tree. This is particularly a problem for &os; users who utilize &man.cvsup.1; to track the Ports Collection but choose not to install certain categories by specifying them in refuse. In theory, one should be able to refuse categories, but in practice there are too many ports that depend on ports in other categories. Until someone comes up with a solution for this problem, the general rule is is that if you want to build INDEX, you must have a complete copy of the Ports Collection. There are rare cases where INDEX will not build due to odd cases involving WITH_* or WITHOUT_* variables being set in make.conf. If you suspect that this is the case, please try to make INDEX with those Makevars turned off before reporting it to &a.ports;. Where do I find ld.so? a.out applications like &netscape.navigator; require a.out libraries. A version of FreeBSD built with ELF libraries does not install them by default. You will get complaints about not having /usr/libexec/ld.so if this is the case on your system. These libraries are available as an add-on in the compat22 distribution. Use &man.sysinstall.8; to install them. You can also install them from the FreeBSD source code: &prompt.root; cd /usr/src/lib/compat/compat22 &prompt.root; make install clean If you want to install the latest compat22 libraries whenever you run make world, edit /etc/make.conf to include COMPAT22=YES. Old compatibility libraries change rarely, if ever, so this is not generally needed. Also see the ERRATAs for 3.1-RELEASE and 3.2-RELEASE. I updated the sources, now how do I update my installed ports? FreeBSD does not include a port upgrading tool, but it does have some tools to make the upgrade process somewhat easier. You can also install additional tools to simplify port handling. The &man.pkg.version.1; command can generate a script that will update installed ports to the latest version in the ports tree. &prompt.root; pkg_version -c > /tmp/myscript The output script must be edited by hand before you use it. Recent versions of &man.pkg.version.1; force this by inserting an &man.exit.1; at the beginning of the script. You should save the output of the script, as it will note packages that depend on the one that has been updated. These may or may not need to be updated as well. The usual case where they need to be updated is that a shared library has changed version numbers, so the ports that used that library need to be rebuilt to use the new version. Beginning with FreeBSD 5.0 (and higher revisions), &man.pkg.version.1; no longer supports the option. If you have the disk space, you can use the portupgrade tool to automate all of this. portupgrade includes various tools to simplify package handling. It is available under sysutils/portupgrade. Since it is written in Ruby, portupgrade is an unlikely candidate for integration with the main FreeBSD tree. That should not stop anyone from using it, however. If your system is up full time, the &man.periodic.8; system can be used to generate a weekly list of ports that might need updating by setting weekly_status_pkg_enable="YES" in /etc/periodic.conf. Why is /bin/sh so minimal? Why does FreeBSD not use bash or another shell? Because &posix; says that there shall be such a shell. The more complicated answer: many people need to write shell scripts which will be portable across many systems. That is why &posix; specifies the shell and utility commands in great detail. Most scripts are written in Bourne shell, and because several important programming interfaces (&man.make.1;, &man.system.3;, &man.popen.3;, and analogues in higher-level scripting languages like Perl and Tcl) are specified to use the Bourne shell to interpret commands. Because the Bourne shell is so often and widely used, it is important for it to be quick to start, be deterministic in its behavior, and have a small memory footprint. The existing implementation is our best effort at meeting as many of these requirements simultaneously as we can. In order to keep /bin/sh small, we have not provided many of the convenience features that other shells have. That is why the Ports Collection includes more featureful shells like bash, scsh, tcsh, and zsh. (You can compare for yourself the memory utilization of all these shells by looking at the VSZ and RSS columns in a ps -u listing.) Why do &netscape; and Opera take so long to start? The usual answer is that DNS on your system is misconfigured. Both &netscape; and Opera perform DNS checks when starting up. The browser will not appear on your desktop until the program either gets a response or determines that the system has no network connection. I updated parts of the Ports Collection using CVSup, and now many ports fail to build with mysterious error messages! What happened? Is the Ports Collection broken in some major way? If you only update parts of the Ports Collection, using one of its CVSup subcollections and not the ports-all CVSup collection, you should always update the ports-base subcollection too! The reasons are described in the Handbook. How do I create audio CDs from my MIDI files? To create audio CDs from MIDI files, first install audio/timidity++ from ports then install manually the GUS patches set by Eric A. Welsh, available at . After timidity++ has been installed properly, midi files may be converted to wav's with the following command line: &prompt.user; timidity -Ow -s 44100 -o /tmp/juke/01.wav 01.mid The wav files can then be converted to other formats or burned onto audio CDs, as described in the FreeBSD Handbook. Kernel Configuration I would like to customize my kernel. Is it difficult? Not at all! Check out the + url="&url.books.handbook;/kernelconfig.html"> kernel config section of the Handbook. We recommend that you make a dated snapshot of your new /kernel called /kernel.YYMMDD after you get it working properly. Also back up your new /modules directory to /modules.YYMMDD. That way, if you make a mistake the next time you play with your configuration you can boot the backup kernel instead of having to fall back to kernel.GENERIC. This is particularly important if you are now booting from a controller that GENERIC does not support. My kernel compiles fail because _hw_float is missing. How do I solve this problem? Let me guess. You removed npx0 (see &man.npx.4;) from your kernel configuration file because you do not have a math co-processor, right? Wrong! :-) The npx0 is MANDATORY. Even if you do not have a mathematic co-processor, you must include the npx0 device. Why is my kernel so big (over 10MB)? Chances are, you compiled your kernel in debug mode. Kernels built in debug mode contain many symbols that are used for debugging, thus greatly increasing the size of the kernel. Note that if you running a FreeBSD 3.0 or later system, there will be little or no performance decrease from running a debug kernel, and it is useful to keep one around in case of a system panic. However, if you are running low on disk space, or you simply do not want to run a debug kernel, make sure that both of the following are true: You do not have a line in your kernel configuration file that reads: makeoptions DEBUG=-g You are not running &man.config.8; with the option. Both of the above situations will cause your kernel to be built in debug mode. As long as you make sure you follow the steps above, you can build your kernel normally, and you should notice a fairly large size decrease; most kernels tend to be around 1.5MB to 2MB. Why do I get interrupt conflicts with multi-port serial code? When I compile a kernel with multi-port serial code, it tells me that only the first port is probed and the rest skipped due to interrupt conflicts. How do I fix this? The problem here is that FreeBSD has code built-in to keep the kernel from getting trashed due to hardware or software conflicts. The way to fix this is to leave out the IRQ settings on all but one port. Here is an example: # # Multiport high-speed serial line - 16550 UARTS # device sio2 at isa? port 0x2a0 tty irq 5 flags 0x501 vector siointr device sio3 at isa? port 0x2a8 tty flags 0x501 vector siointr device sio4 at isa? port 0x2b0 tty flags 0x501 vector siointr device sio5 at isa? port 0x2b8 tty flags 0x501 vector siointr Why does every kernel I try to build fail to compile, even GENERIC? There are a number of possible causes for this problem. They are, in no particular order: You are not using the new make buildkernel and make installkernel targets, and your source tree is different from the one used to build the currently running system (e.g., you are compiling 4.3-RELEASE on a 4.0-RELEASE system). If you are attempting an upgrade, please read the /usr/src/UPDATING file, paying particular attention to the COMMON ITEMS section at the end. You are using the new make buildkernel and make installkernel targets, but you failed to assert the completion of the make buildworld target. The make buildkernel target relies on files generated by the make buildworld target to complete its job correctly. Even if you are trying to build FreeBSD-STABLE, it is possible that you fetched the source tree at a time when it was either being modified, or broken for other reasons; only releases are absolutely guaranteed to be buildable, although FreeBSD-STABLE builds fine the majority of the time. If you have not already done so, try re-fetching the source tree and see if the problem goes away. Try using a different server in case the one you are using is having problems. How can I verify which scheduler is in use on a running system? Just type: &prompt.root; sysctl kern.quantum If you see unknown oid 'kern.quantum' it means that the current scheduler is SCHED_ULE, however, if you see kern.quantum: 100000 then the original scheduler SCHED_4BSD is the current selection. What is 'kern.quantum'? kern.quantum is the maximum number of ticks a process can run without being preempted. It is specific to the 4BSD scheduler, so you can use its presence or absence to determine which scheduler is in use. Disks, Filesystems, and Boot Loaders How can I add my new hard disk to my FreeBSD system? See the Disk Formatting Tutorial at + url="&url.articles.formatting-media;/index.html"> www.FreeBSD.org. How do I move my system over to my huge new disk? The best way is to reinstall the OS on the new disk, then move the user data over. This is highly recommended if you have been tracking -STABLE for more than one release, or have updated a release instead of installing a new one. You can install booteasy on both disks with &man.boot0cfg.8;, and dual boot them until you are happy with the new configuration. Skip the next paragraph to find out how to move the data after doing this. Should you decide not to do a fresh install, you need to partition and label the new disk with either /stand/sysinstall, or &man.fdisk.8; and &man.disklabel.8;. You should also install booteasy on both disks with &man.boot0cfg.8;, so that you can dual boot to the old or new system after the copying is done. See the formatting-media article for details on this process. Now you have the new disk set up, and are ready to move the data. Unfortunately, you cannot just blindly copy the data. Things like device files (in /dev), flags, and links tend to screw that up. You need to use tools that understand these things, which means &man.dump.8;. Although it is suggested that you move the data in single user mode, it is not required. You should never use anything but &man.dump.8; and &man.restore.8; to move the root filesystem. The &man.tar.1; command may work - then again, it may not. You should also use &man.dump.8; and &man.restore.8; if you are moving a single partition to another empty partition. The sequence of steps to use dump to move a partitions data to a new partition is: newfs the new partition. mount it on a temporary mount point. cd to that directory. dump the old partition, piping output to the new one. For example, if you are going to move root to /dev/ad1s1a, with /mnt as the temporary mount point, it is: &prompt.root; newfs /dev/ad1s1a &prompt.root; mount /dev/ad1s1a /mnt &prompt.root; cd /mnt &prompt.root; dump 0af - / | restore xf - Rearranging your partitions with dump takes a bit more work. To merge a partition like /var into its parent, create the new partition large enough for both, move the parent partition as described above, then move the child partition into the empty directory that the first move created: &prompt.root; newfs /dev/ad1s1a &prompt.root; mount /dev/ad1s1a /mnt &prompt.root; cd /mnt &prompt.root; dump 0af - / | restore xf - &prompt.root; cd var &prompt.root; dump 0af - /var | restore xf - To split a directory from its parent, say putting /var on its own partition when it was not before, create both partitions, then mount the child partition on the appropriate directory in the temporary mount point, then move the old single partition: &prompt.root; newfs /dev/ad1s1a &prompt.root; newfs /dev/ad1s1d &prompt.root; mount /dev/ad1s1a /mnt &prompt.root; mkdir /mnt/var &prompt.root; mount /dev/ad1s1d /mnt/var &prompt.root; cd /mnt &prompt.root; dump 0af - / | restore xf - You might prefer &man.cpio.1;, &man.pax.1;, &man.tar.1; to &man.dump.8; for user data. At the time of this writing, these are known to lose file flag information, so use them with caution. Will a dangerously dedicated disk endanger my health? The installation procedure allows you to chose two different methods in partitioning your hard disk(s). The default way makes it compatible with other operating systems on the same machine, by using fdisk table entries (called slices in FreeBSD), with a FreeBSD slice that employs partitions of its own. Optionally, one can chose to install a boot-selector to switch between the possible operating systems on the disk(s). The alternative uses the entire disk for FreeBSD, and makes no attempt to be compatible with other operating systems. So why it is called dangerous? A disk in this mode does not contain what normal PC utilities would consider a valid fdisk table. Depending on how well they have been designed, they might complain at you once they are getting in contact with such a disk, or even worse, they might damage the BSD bootstrap without even asking or notifying you. In addition, the dangerously dedicated disk's layout is known to confuse many BIOSes, including those from AWARD (e.g. as found in HP Netserver and Micronics systems as well as many others) and Symbios/NCR (for the popular 53C8xx range of SCSI controllers). This is not a complete list, there are more. Symptoms of this confusion include the read error message printed by the FreeBSD bootstrap when it cannot find itself, as well as system lockups when booting. Why have this mode at all then? It only saves a few kbytes of disk space, and it can cause real problems for a new installation. Dangerously dedicated mode's origins lie in a desire to avoid one of the most common problems plaguing new FreeBSD installers - matching the BIOS geometry numbers for a disk to the disk itself. Geometry is an outdated concept, but one still at the heart of the PC's BIOS and its interaction with disks. When the FreeBSD installer creates slices, it has to record the location of these slices on the disk in a fashion that corresponds with the way the BIOS expects to find them. If it gets it wrong, you will not be able to boot. Dangerously dedicated mode tries to work around this by making the problem simpler. In some cases, it gets it right. But it is meant to be used as a last-ditch alternative - there are better ways to solve the problem 99 times out of 100. So, how do you avoid the need for DD mode when you are installing? Start by making a note of the geometry that your BIOS claims to be using for your disks. You can arrange to have the kernel print this as it boots by specifying at the boot: prompt, or using boot -v in the loader. Just before the installer starts, the kernel will print a list of BIOS geometries. Do not panic - wait for the installer to start and then use scrollback to read the numbers. Typically the BIOS disk units will be in the same order that FreeBSD lists your disks, first IDE, then SCSI. When you are slicing up your disk, check that the disk geometry displayed in the FDISK screen is correct (ie. it matches the BIOS numbers); if it is wrong, use the g key to fix it. You may have to do this if there is absolutely nothing on the disk, or if the disk has been moved from another system. Note that this is only an issue with the disk that you are going to boot from; FreeBSD will sort itself out just fine with any other disks you may have. Once you have got the BIOS and FreeBSD agreeing about the geometry of the disk, your problems are almost guaranteed to be over, and with no need for DD mode at all. If, however, you are still greeted with the dreaded read error message when you try to boot, it is time to cross your fingers and go for it - there is nothing left to lose. To return a dangerously dedicated disk for normal PC use, there are basically two options. The first is, you write enough NULL bytes over the MBR to make any subsequent installation believe this to be a blank disk. You can do this for example with &prompt.root; dd if=/dev/zero of=/dev/rda0 count=15 Alternatively, the undocumented DOS feature C:\> fdisk /mbr will to install a new master boot record as well, thus clobbering the BSD bootstrap. Which partitions can safely use Soft Updates? I have heard that Soft Updates on / can cause problems. Short answer: you can usually use Soft Updates safely on all partitions. Long answer: There used to be some concern over using Soft Updates on the root partition. Soft Updates has two characteristics that caused this. First, a Soft Updates partition has a small chance of losing data during a system crash. (The partition will not be corrupted; the data will simply be lost.) Also, Soft Updates can cause temporary space shortages. When using Soft Updates, the kernel can take up to thirty seconds to actually write changes to the physical disk. If you delete a large file, the file still resides on disk until the kernel actually performs the deletion. This can cause a very simple race condition. Suppose you delete one large file and immediately create another large file. The first large file is not yet actually removed from the physical disk, so the disk might not have enough room for the second large file. You get an error that the partition does not have enough space, although you know perfectly well that you just released a large chunk of space! When you try again mere seconds later, the file creation works as you expect. This has left more than one user scratching his head and doubting his sanity, the FreeBSD filesystem, or both. If a system should crash after the kernel accepts a chunk of data for writing to disk, but before that data is actually written out, data could be lost or corrupted. This risk is extremely small, but generally manageable. Use of IDE write caching greatly increases this risk; it is strongly recommended that you disable IDE write caching when using Soft Updates. These issues affect all partitions using Soft Updates. So, what does this mean for the root partition? Vital information on the root partition changes very rarely. Files such as /kernel and the contents of /etc only change during system maintenance, or when users change their passwords. If the system crashed during the thirty-second window after such a change is made, it is possible that data could be lost. This risk is negligible for most applications, but you should be aware that it exists. If your system cannot tolerate this much risk, do not use Soft Updates on the root filesystem! / is traditionally one of the smallest partitions. By default, FreeBSD puts the /tmp directory on /. If you have a busy /tmp, you might see intermittent space problems. Symlinking /tmp to /var/tmp will solve this problem. What is inappropriate about my ccd? The symptom of this is: &prompt.root; ccdconfig -C ccdconfig: ioctl (CCDIOCSET): /dev/ccd0c: Inappropriate file type or format This usually happens when you are trying to concatenate the c partitions, which default to type unused. The ccd driver requires the underlying partition type to be FS_BSDFFS. Edit the disklabel of the disks you are trying to concatenate and change the types of partitions to 4.2BSD. Why can I not edit the disklabel on my ccd? The symptom of this is: &prompt.root; disklabel ccd0 (it prints something sensible here, so let us try to edit it) &prompt.root; disklabel -e ccd0 (edit, save, quit) disklabel: ioctl DIOCWDINFO: No disk label on disk; use "disklabel -r" to install initial label This is because the disklabel returned by ccd is actually a fake one that is not really on the disk. You can solve this problem by writing it back explicitly, as in: &prompt.root; disklabel ccd0 > /tmp/disklabel.tmp &prompt.root; disklabel -Rr ccd0 /tmp/disklabel.tmp &prompt.root; disklabel -e ccd0 (this will work now) Can I mount other foreign filesystems under FreeBSD? Digital UNIX UFS CDROMs can be mounted directly on FreeBSD. Mounting disk partitions from Digital UNIX and other systems that support UFS may be more complex, depending on the details of the disk partitioning for the operating system in question. &linux; FreeBSD supports ext2fs partitions. See &man.mount.ext2fs.8; for more information. &windowsnt; FreeBSD includes a read-only NTFS driver. For more information, see &man.mount.ntfs.8;. Any other information on this subject would be appreciated. How do I mount a secondary DOS partition? The secondary DOS partitions are found after ALL the primary partitions. For example, if you have an E partition as the second DOS partition on the second SCSI drive, you need to create the special files for slice 5 in /dev, then mount /dev/da1s5: &prompt.root; cd /dev &prompt.root; sh MAKEDEV da1s5 &prompt.root; mount -t msdos /dev/da1s5 /dos/e You can omit this step if you are running FreeBSD 5.0-RELEASE or newer with &man.devfs.5; enabled. Is there a cryptographic filesystem for &os;? Yes; see the security/cfs port. How can I use the &windowsnt; loader to boot FreeBSD? The general idea is that you copy the first sector of your native root FreeBSD partition into a file in the DOS/&windowsnt; partition. Assuming you name that file something like c:\bootsect.bsd (inspired by c:\bootsect.dos), you can then edit the c:\boot.ini file to come up with something like this: [boot loader] timeout=30 default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS [operating systems] multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT" C:\BOOTSECT.BSD="FreeBSD" C:\="DOS" If FreeBSD is installed on the same disk as the &windowsnt; boot partition simply copy /boot/boot1 to C:\BOOTSECT.BSD. However, if FreeBSD is installed on a different disk /boot/boot1 will not work, /boot/boot0 is needed. /boot/boot0 needs to be installed using sysinstall by selecting the FreeBSD boot manager on the screen which asks if you wish to use a boot manager. This is because /boot/boot0 has the partition table area filled with NULL characters but sysinstall copies the partition table before copying /boot/boot0 to the MBR. Do not simply copy /boot/boot0 instead of /boot/boot1; you will overwrite your partition table and render your computer un-bootable! When the FreeBSD boot manager runs it records the last OS booted by setting the active flag on the partition table entry for that OS and then writes the whole 512-bytes of itself back to the MBR so if you just copy /boot/boot0 to C:\BOOTSECT.BSD then it writes an empty partition table, with the active flag set on one entry, to the MBR. How do I boot FreeBSD and &linux; from LILO? If you have FreeBSD and &linux; on the same disk, just follow LILO's installation instructions for booting a non-&linux; operating system. Very briefly, these are: Boot &linux;, and add the following lines to /etc/lilo.conf: other=/dev/hda2 table=/dev/hda label=FreeBSD (the above assumes that your FreeBSD slice is known to &linux; as /dev/hda2; tailor to suit your setup). Then, run lilo as root and you should be done. If FreeBSD resides on another disk, you need to add loader=/boot/chain.b to the LILO entry. For example: other=/dev/dab4 table=/dev/dab loader=/boot/chain.b label=FreeBSD In some cases you may need to specify the BIOS drive number to the FreeBSD boot loader to successfully boot off the second disk. For example, if your FreeBSD SCSI disk is probed by BIOS as BIOS disk 1, at the FreeBSD boot loader prompt you need to specify: Boot: 1:da(0,a)/kernel On FreeBSD 2.2.5 and later, you can configure &man.boot.8; to automatically do this for you at boot time. The + url="http://sunsite.unc.edu/LDP/HOWTO/mini/Linux+FreeBSD.html"> &linux;+FreeBSD mini-HOWTO is a good reference for FreeBSD and &linux; interoperability issues. How do I boot FreeBSD and &linux; using BootEasy? Install LILO at the start of your &linux; boot partition instead of in the Master Boot Record. You can then boot LILO from BootEasy. If you are running &windows; 95 and &linux; this is recommended anyway, to make it simpler to get &linux; booting again if you should need to reinstall &windows; 95 (which is a Jealous Operating System, and will bear no other Operating Systems in the Master Boot Record). How do I change the boot prompt from ??? to something more meaningful? You can not do that with the standard boot manager without rewriting it. There are a number of other boot managers in the sysutils ports category that provide this functionality. I have a new removable drive, how do I use it? Whether it is a removable drive like a &iomegazip; or an EZ drive (or even a floppy, if you want to use it that way), or a new hard disk, once it is installed and recognized by the system, and you have your cartridge/floppy/whatever slotted in, things are pretty much the same for all devices. (this section is based on + url="http://www.vmunix.com/mark/FreeBSD/ZIP-FAQ.html"> Mark Mayo's ZIP FAQ) If it is a ZIP drive or a floppy, you have already got a DOS filesystem on it, you can use a command like this: &prompt.root; mount -t msdos /dev/fd0c /floppy if it is a floppy, or this: &prompt.root; mount -t msdos /dev/da2s4 /zip for a ZIP disk with the factory configuration. For other disks, see how they are laid out using &man.fdisk.8; or &man.sysinstall.8;. The rest of the examples will be for a ZIP drive on da2, the third SCSI disk. Unless it is a floppy, or a removable you plan on sharing with other people, it is probably a better idea to stick a BSD filesystem on it. You will get long filename support, at least a 2X improvement in performance, and a lot more stability. First, you need to redo the DOS-level partitions/filesystems. You can either use &man.fdisk.8; or /stand/sysinstall, or for a small drive that you do not want to bother with multiple operating system support on, just blow away the whole FAT partition table (slices) and just use the BSD partitioning: &prompt.root; dd if=/dev/zero of=/dev/rda2 count=2 &prompt.root; disklabel -Brw da2 auto You can use disklabel or /stand/sysinstall to create multiple BSD partitions. You will certainly want to do this if you are adding swap space on a fixed disk, but it is probably irrelevant on a removable drive like a ZIP. Finally, create a new filesystem, this one is on our ZIP drive using the whole disk: &prompt.root; newfs /dev/rda2c and mount it: &prompt.root; mount /dev/da2c /zip and it is probably a good idea to add a line like this to /etc/fstab (see &man.fstab.5;) so you can just type mount /zip in the future: /dev/da2c /zip ffs rw,noauto 0 0 Why do I get Incorrect super block when mounting a CDROM? You have to tell &man.mount.8; the type of the device that you want to mount. This is described in the Handbook section on + url="&url.books.handbook;/creating-cds.html"> Handbook section on optical media, specifically the section Using Data + url="&url.books.handbook;/creating-cds.html#MOUNTING-CD">Using Data CDs. Why do I get Device not configured when mounting a CDROM? This generally means that there is no CDROM in the CDROM drive, or the drive is not visible on the bus. Please see the Using Data + url="&url.books.handbook;/creating-cds.html#MOUNTING-CD">Using Data CDs section of the Handbook for a detailed discussion of this issue. Why do all non-English characters in filenames show up as ? on my CDs when mounted in FreeBSD? Your CDROM probably uses the Joliet extension for storing information about files and directories. This is discussed in the Handbook chapter on - creating and + creating and using CDROMs, specifically the section on Using Data + url="&url.books.handbook;/creating-cds.html#MOUNTING-CD">Using Data CDROMs. I burned a CD under FreeBSD and now I can not read it under any other operating system. Why? You most likely burned a raw file to your CD, rather than creating an ISO 9660 filesystem. Take a look at the - Handbook + Handbook chapter on creating CDROMs, particularly the section on burning raw + url="&url.books.handbook;/creating-cds.html#RAWDATA-CD">burning raw data CDs. How can I create an image of a data CD? This is discussed in the Handbook section on duplicating data CDs. For more on working with CDROMs, see the Creating CDs Section in the Storage chapter in the Handbook. Why can I not mount an audio CD? If you try to mount an audio CD, you will get an error like cd9660: /dev/acd0c: Invalid argument. This is because mount only works on filesystems. Audio CDs do not have filesystems; they just have data. You need a program that reads audio CDs, such as the audio/xmcd port. How do I mount a multi-session CD? By default, &man.mount.8; will attempt to mount the last data track (session) of a CD. If you would like to load an earlier session, you must use the command line argument. Please see &man.mount.cd9660.8; for specific examples. How do I let ordinary users mount floppies, CDROMs and other removable media? Ordinary users can be permitted to mount devices. Here is how: As root set the sysctl variable vfs.usermount to 1. &prompt.root; sysctl -w vfs.usermount=1 As root assign the appropriate permissions to the block device associated with the removable media. For example, to allow users to mount the first floppy drive, use: &prompt.root; chmod 666 /dev/fd0 To allow users in the group operator to mount the CDROM drive, use: &prompt.root; chgrp operator /dev/cd0c &prompt.root; chmod 640 /dev/cd0c Finally, add the line vfs.usermount=1 to the file /etc/sysctl.conf so that it is reset at system boot time. All users can now mount the floppy /dev/fd0 onto a directory that they own: &prompt.user; mkdir ~/my-mount-point &prompt.user; mount -t msdos /dev/fd0 ~/my-mount-point Users in group operator can now mount the CDROM /dev/cd0c onto a directory that they own: &prompt.user; mkdir ~/my-mount-point &prompt.user; mount -t cd9660 /dev/cd0c ~/my-mount-point Unmounting the device is simple: &prompt.user; umount ~/my-mount-point Enabling vfs.usermount, however, has negative security implications. A better way to access &ms-dos; formatted media is to use the mtools + url="http://www.FreeBSD.org/cgi/ports.cgi?query=%5Emtools-&stype=name">mtools package in the ports collection. The du and df commands show different amounts of disk space available. What is going on? You need to understand what du and df really do. du goes through the directory tree, measures how large each file is, and presents the totals. df just asks the filesystem how much space it has left. They seem to be the same thing, but a file without a directory entry will affect df but not du. When a program is using a file, and you delete the file, the file is not really removed from the filesystem until the program stops using it. The file is immediately deleted from the directory listing, however. You can see this easily enough with a program such as more. Assume you have a file large enough that its presence affects the output of du and df. (Since disks can be so large today, this might be a very large file!) If you delete this file while using more on it, more does not immediately choke and complain that it cannot view the file. The entry is simply removed from the directory so no other program or user can access it. du shows that it is gone — it has walked the directory tree and the file is not listed. df shows that it is still there, as the filesystem knows that more is still using that space. Once you end the more session, du and df will agree. Note that Soft Updates can delay the freeing of disk space; you might need to wait up to 30 seconds for the change to be visible! This situation is common on web servers. Many people set up a FreeBSD web server and forget to rotate the log files. The access log fills up /var. The new administrator deletes the file, but the system still complains that the partition is full. Stopping and restarting the web server program would free the file, allowing the system to release the disk space. To prevent this from happening, set up &man.newsyslog.8;. How can I add more swap space? In the Configuration and Tuning section of the Handbook, you will find a section describing how to do this. How is it possible for a partition to be more than 100% full? A portion of each UFS partition (8%, by default) is reserved for use by the operating system and the root user. &man.df.1; does not count that space when calculating the Capacity column, so it can exceed 100%. Also, you'll notice that the Blocks column is always greater than the sum of the Used and Avail columns, usually by a factor of 8%. For more details, look up the option in &man.tunefs.8;. System Administration Where are the system start-up configuration files? The primary configuration file is /etc/defaults/rc.conf (see &man.rc.conf.5;) System startup scripts such as /etc/rc and /etc/rc.d (see &man.rc.8;) just include this file. Do not edit this file! Instead, if there is any entry in /etc/defaults/rc.conf that you want to change, you should copy the line into /etc/rc.conf and change it there. For example, if you wish to start named, the included DNS server, all you need to do is: &prompt.root; echo named_enable="YES" >> /etc/rc.conf To start up local services, place shell scripts in the /usr/local/etc/rc.d directory. These shell scripts should be set executable, and end with a .sh. How do I add a user easily? Use the &man.adduser.8; command, or the &man.pw.8; command for more complicated situations. To remove the user, use the &man.rmuser.8; command or, if necessary, &man.pw.8;. Why do I keep getting messages like root: not found after editing my crontab file? This is normally caused by editing the system crontab (/etc/crontab) and then using &man.crontab.1; to install it: &prompt.root; crontab /etc/crontab This is not the correct way to do things. The system crontab has a different format to the per-user crontabs which &man.crontab.1; updates (the &man.crontab.5; manual page explains the differences in more detail). If this is what you did, the extra crontab is simply a copy of /etc/crontab in the wrong format it. Delete it with the command: &prompt.root; crontab -r Next time, when you edit /etc/crontab, you should not do anything to inform &man.cron.8; of the changes, since it will notice them automatically. If you want something to be run once per day, week, or month, it is probably better to add shell scripts /usr/local/etc/periodic, and let the &man.periodic.8; command run from the system cron schedule it with the other periodic system tasks. The actual reason for the error is that the system crontab has an extra field, specifying which user to run the command as. In the default system crontab provided with FreeBSD, this is root for all entries. When this crontab is used as the root user's crontab (which is not the same as the system crontab), &man.cron.8; assumes the string root is the first word of the command to execute, but no such command exists. Why do I get the error, you are not in the correct group to su root when I try to su to root? This is a security feature. In order to su to root (or any other account with superuser privileges), you must be in the wheel group. If this feature were not there, anybody with an account on a system who also found out root's password would be able to gain superuser level access to the system. With this feature, this is not strictly true; &man.su.1; will prevent them from even trying to enter the password if they are not in wheel. To allow someone to su to root, simply put them in the wheel group. I made a mistake in rc.conf, or another startup file, and now I cannot edit it because the filesystem is read-only. What should I do? When you get the prompt to enter the shell pathname, simply press ENTER, and run mount / to re-mount the root filesystem in read/write mode. You may also need to run mount -a -t ufs to mount the filesystem where your favourite editor is defined. If your favourite editor is on a network filesystem, you will need to either configure the network manually before you can mount network filesystems, or use an editor which resides on a local filesystem, such as &man.ed.1;. If you intend to use a full screen editor such as &man.vi.1; or &man.emacs.1;, you may also need to run export TERM=cons25 so that these editors can load the correct data from the &man.termcap.5; database. Once you have performed these steps, you can edit /etc/rc.conf as you usually would to fix the syntax error. The error message displayed immediately after the kernel boot messages should tell you the number of the line in the file which is at fault. Why am I having trouble setting up my printer? Please have a look at the Handbook entry on printing. It should cover most of your problem. See the + url="&url.books.handbook;/printing.html"> Handbook entry on printing. Some printers require a host-based driver to do any kind of printing. These so-called WinPrinters are not natively supported by FreeBSD. If your printer does not work in DOS or &windowsnt; 4.0, it is probably a WinPrinter. Your only hope of getting one of these to work is to check if the print/pnm2ppa port supports it. How can I correct the keyboard mappings for my system? Please see the Handbook section on using localization, specifically the section on console setup. Why do I get messages like: unknown: <PNP0303> can't assign resources on boot? The following is an excerpt from a post to the freebsd-current mailing list.
&a.wollman;, 24 April 2001 The can't assign resources messages indicate that the devices are legacy ISA devices for which a non-PnP-aware driver is compiled into the kernel. These include devices such as keyboard controllers, the programmable interrupt controller chip, and several other bits of standard infrastructure. The resources cannot be assigned because there is already a driver using those addresses.
Why can I not get user quotas to work properly? Do not turn on quotas on /, Put the quota file on the filesystem that the quotas are to be enforced on. ie: Filesystem Quota file /usr /usr/admin/quotas /home /home/admin/quotas … … Does FreeBSD support System V IPC primitives? Yes, FreeBSD supports System V-style IPC, including shared memory, messages and semaphores. Versions of FreeBSD later than 3.2 support System V IPC in the GENERIC kernel. In earlier versions of FreeBSD, enable this support by adding the following lines to your kernel config. options SYSVSHM # enable shared memory options SYSVSEM # enable for semaphores options SYSVMSG # enable for messaging Recompile and install your kernel. What other mail-server software can I use, instead of Sendmail? Sendmail is the default mail-server software for FreeBSD, but you can easily replace it with one of the other MTA (for instance, an MTA installed from the ports). There are various alternative MTA's in the ports tree already, with mail/exim, mail/postfix, mail/qmail, mail/zmailer, being some of the most popular choices. Diversity is nice, and the fact that you have many different mail-servers to chose from is considered a good thing; therefore try to avoid asking questions like Is Sendmail better than Qmail? in the mailing lists. If you do feel like asking, first check the mailing list archives. The advantages and disadvantages of each and every one of the available MTA's have already been discussed a few times. I have forgotten the root password! What do I do? Do not Panic! Simply restart the system, type boot -s at the Boot: prompt (just -s for FreeBSD releases before 3.2) to enter Single User mode. At the question about the shell to use, hit ENTER. You will be dropped to a &prompt.root; prompt. Enter mount -u / to remount your root filesystem read/write, then run mount -a to remount all the filesystems. Run passwd root to change the root password then run &man.exit.1; to continue booting. How do I keep ControlAltDelete from rebooting the system? If you are using syscons (the default console driver) build and install a new kernel with the following option. options SC_DISABLE_REBOOT in the configuration file. If you use the PCVT console driver, use the following kernel configuration line instead. options PCVT_CTRL_ALT_DEL How do I reformat DOS text files to &unix; ones? Simply use this perl command: &prompt.user; perl -i.bak -npe 's/\r\n/\n/g' file ... file is the file(s) to process. The modification is done in-place, with the original file stored with a .bak extension. Alternatively you can use the &man.tr.1; command: &prompt.user; tr -d '\r' < dos-text-file > unix-file dos-text-file is the file containing DOS text while unix-file will contain the converted output. This can be quite a bit faster than using perl. How do I kill processes by name? Use &man.killall.1;. Why is su bugging me about not being in root's ACL? The error comes from the Kerberos distributed authentication system. The problem is not fatal but annoying. You can either run su with the -K option, or uninstall Kerberos as described in the next question. How do I uninstall Kerberos? To remove Kerberos from the system, reinstall the bin distribution for the release you are running. If you have the CDROM, you can mount the cd (we will assume on /cdrom) and run &prompt.root; cd /cdrom/bin &prompt.root; ./install.sh Alternately, you can remove all MAKE_KERBEROS options from /etc/make.conf and rebuild world. What happened to /dev/MAKEDEV? FreeBSD 5.X uses the &man.devfs.8; device-on-demand system. Device drivers automatically create new device nodes as they are needed, obsoleting /dev/MAKEDEV. If you are running FreeBSD 4.X or earlier and /dev/MAKEDEV is missing, then you really do have a problem. Grab a copy from the system source code, probably in /usr/src/etc/MAKEDEV. How do I add pseudoterminals to the system? If you have lots of telnet, ssh, X, or screen users, you will probably run out of pseudoterminals. Here is how to add more: Build and install a new kernel with the line pseudo-device pty 256 in the configuration file. Run the commands &prompt.root; cd /dev &prompt.root; sh MAKEDEV pty{1,2,3,4,5,6,7} to make 256 device nodes for the new terminals. Edit /etc/ttys and add lines for each of the 256 terminals. They should match the form of the existing entries, i.e. they look like ttyqc none network The order of the letter designations is tty[pqrsPQRS][0-9a-v], using a regular expression. Reboot the system with the new kernel and you are ready to go. Why can I not create the snd0 device? There is no snd device. The name is used as a shorthand for the various devices that make up the FreeBSD sound driver, such as mixer, sequencer, and dsp. To create these devices you should &prompt.root; cd /dev &prompt.root; sh MAKEDEV snd0 You can omit this step if you are running FreeBSD 5.0-RELEASE or newer with &man.devfs.5; enabled. How do I re-read /etc/rc.conf and re-start /etc/rc without a reboot? Go into single user mode and then back to multi user mode. On the console do: &prompt.root; shutdown now (Note: without -r or -h) &prompt.root; return &prompt.root; exit I tried to update my system to the latest -STABLE, but got -RC or -PRERELEASE! What is going on? Short answer: it is just a name. RC stands for Release Candidate. It signifies that a release is imminent. In FreeBSD, -PRERELEASE is typically synonymous with the code freeze before a release. (For some releases, the -BETA label was used in the same way as -PRERELEASE.) Long answer: FreeBSD derives its releases from one of two places. Major, dot-zero, releases, such as 3.0-RELEASE and 4.0-RELEASE, are branched from the head of the development stream, commonly referred to as -CURRENT. Minor releases, such as 3.1-RELEASE or 4.2-RELEASE, have been snapshots of the active -STABLE branch. Starting with 4.3-RELEASE, each release also now has its own branch which can be tracked by people requiring an extremely conservative rate of development (typically only security advisories). When a release is about to be made, the branch from which it will be derived from has to undergo a certain process. Part of this process is a code freeze. When a code freeze is initiated, the name of the branch is changed to reflect that it is about to become a release. For example, if the branch used to be called 4.5-STABLE, its name will be changed to 4.6-PRERELEASE to signify the code freeze and signify that extra pre-release testing should be happening. Bug fixes can still be committed to be part of the release. When the source code is in shape for the release the name will be changed to 4.6-RC to signify that a release is about to be made from it. Once in the RC stage, only the most critical bugs found can be fixed. Once the release (4.6-RELEASE in this example) and release branch have been made, the branch will be renamed to 4.6-STABLE. For more information on version numbers and the various CVS branches, refer to the Release Engineering article. I tried to install a new kernel, and the chflags failed. How do I get around this? Short answer: You are probably at security level greater than 0. Reboot directly to single user mode to install the kernel. Long answer: FreeBSD disallows changing system flags at security levels greater than 0. You can check your security level with the command: &prompt.root; sysctl kern.securelevel You cannot lower the security level; you have to boot to single mode to install the kernel, or change the security level in /etc/rc.conf then reboot. See the &man.init.8; manual page for details on securelevel, and see /etc/defaults/rc.conf and the &man.rc.conf.5; manual page for more information on rc.conf. I cannot change the time on my system by more than one second! How do I get around this? Short answer: You are probably at security level greater than 1. Reboot directly to single user mode to change the date. Long answer: FreeBSD disallows changing the time by more that one second at security levels greater than 1. You can check your security level with the command: &prompt.root; sysctl kern.securelevel You cannot lower the security level; you have to boot to single mode to change the date, or change the security level in /etc/rc.conf then reboot. See the &man.init.8; manual page for details on securelevel, and see /etc/defaults/rc.conf and the &man.rc.conf.5; manual page for more information on rc.conf. Why is rpc.statd using 256 megabytes of memory? No, there is no memory leak, and it is not using 256 Mbytes of memory. It simply likes to (i.e., always does) map an obscene amount of memory into its address space for convenience. There is nothing terribly wrong with this from a technical standpoint; it just throws off things like &man.top.1; and &man.ps.1;. &man.rpc.statd.8; maps its status file (resident on /var) into its address space; to save worrying about remapping it later when it needs to grow, it maps it with a generous size. This is very evident from the source code, where one can see that the length argument to &man.mmap.2; is 0x10000000, or one sixteenth of the address space on an IA32, or exactly 256MB. Why can I not unset the schg file flag? You are running at an elevated (i.e., greater than 0) securelevel. Lower the securelevel and try again. For more information, see the FAQ entry on securelevel and the &man.init.8; manual page. Why does SSH authentication through .shosts not work by default in recent versions of FreeBSD? The reason why .shosts authentication does not work by default in more recent versions of FreeBSD is because &man.ssh.1; is not installed suid root by default. To fix this, you can do one of the following: As a permanent fix, set ENABLE_SUID_SSH to true in /etc/make.conf and rebuild ssh (or run make world). As a temporary fix, change the mode on /usr/bin/ssh to 4555 by running chmod 4555 /usr/bin/ssh as root. Then add ENABLE_SUID_SSH= true to /etc/make.conf so the change takes effect the next time make world is run. What is vnlru? vnlru flushes and frees vnodes when the system hits the kern.maxvnodes limit. This kernel thread sits mostly idle, and only activates if you have a huge amount of RAM and are accessing tens of thousands of tiny files. What do the various memory states displayed by top mean? Active: pages recently statistically used. Inactive: pages recently statistically unused. Cache: (most often) pages that have percolated from inactive to a status where they maintain their data, but can often be immediately reused (either with their old association, or reused with a new association.) There can be certain immediate transition from active to 'cache' state if the page is known to be clean (unmodified), but that transition is a matter of policy, depending upon the algorithm choice of the VM system maintainer. Free: pages without data content, and can be immediately used in certain circumstances where cache pages might be ineligible. Free pages can be reused at interrupt or process state. Wired: pages that are fixed into memory, usually for kernel purposes, but also sometimes for special use in processes. Pages are most often written to disk (sort of a VM sync) when they are in the 'inactive' state, but 'active' pages can also be synced (but requires the availability of certain CPU features.) This depends upon the CPU tracking of the 'modified' bit being available, and in certain situations there can be an advantage for a block of VM pages to be synced, whether they are active or inactive. In most common cases, it is best to think of the 'inactive' queue to be a queue of relatively unused pages that might or might not be in the process of being written to disk. 'Cached' pages are already 'synced', not mapped, but available for immediate process use with their old association or with a new association. Free pages are available at interrupt level, but cached or free pages can be used at process state for reuse. Cache pages aren't adequately locked to be available at interrupt level. There are some other flags (e.g. Busy flag or busy count) that might modify some of the rules that I described. How much free memory is available? There are a couple of kinds of free memory. One kind is the amount of memory immediately available without paging anything else out. That is approximately the size of cache queue + size of free queue (with a derating factor, depending upon system tuning.) Another kind of free memory is the total amount of VM space. That can be complex, but is dependent upon the amount of swap space and memory. Other kinds of free memory descriptions are also possible, but it is relatively useless to define these, but rather it is important to make sure that the paging rate is kept low, and to avoid running out of swap space. What is /var/empty? I can not delete it! /var/empty is a directory that the &man.sshd.8; program uses when performing privilege separation. The /var/empty directory is empty, owned by root and has the schg flag set. Although it is not recommended to delete this directory, to do so you will need to unset the schg flag first. See the &man.chflags.1; manual page for more information (and bear in mind the answer to the question on unsetting the schg flag). The X Window System and Virtual Consoles What is the X Window System? The X Window System is the most widely available windowing system capable of running on &unix; or &unix; like systems, including &os;. X.org administers the X protocol standards. The current release of the specification is 11.6, so you will often see references shortened to X11R6 or even just X11. Many implementations are available for different architectures and operating systems. For instance, an implementation of the server-side code is properly known as an X server. Which X implementations are available for &os;? Historically, the default implementation of X on &os; has been &xfree86; which is maintained by The XFree86 Project, Inc. This software was installed by default on &os; versions up until 4.10 and 5.2. Although X.org itself maintained an implementation during that time period, it was basically only provided as a reference platform, as it had suffered greatly from bitrot over the years. However, early in 2004, some XFree86 developers left that project over issues including the pace of code changes, future directions, and interpersonal conflicts, and are now contributing code directly to X.org instead. At that time, X.org updated its source tree to the last &xfree86; release before its subsequent licensing change (XFree86 version 4.3.99.903), incorporated many changes that had previously been maintained separately, and has released that software as X11R6.7.0. A separate but related project, freedesktop.org (or fd.o for short), is working on rearchitecting the original &xfree86; code to offload more work onto the graphics cards (with the goal of increased performance) and make it more modular (with the goal of increased maintainability, and thus faster releases as well as easier configuration). X.org intends to incorporate the freedesktop.org changes in its future releases. As of July 2004, in &os.current;, &xfree86; has been replaced with x.org as the default implementation. The &xfree86; ports (x11/XFree86-4 and subports) remain in the ports collection and are still the default for &os.stable;. The above describes the default X implementation installed. It is still possible to install either implementation by following the instructions in the entry for 20040723 in /usr/ports/UPDATING. It is not currently possible to mix-and-match pieces of each implementation; one must choose one or the other. The following paragraphs refer to the &xfree86; implementation, but most should also be applicable to the x.org implementation as well. While the default configuration filename for the x.org implementation is xorg.conf, it will search for XF86Config if it cannot find it. Will my existing applications run with the X.org suite? The X.org software is written to the same X11R6 specification that &xfree86; is, so basic applications should work unchanged. A few lesser-used protocols have been deprecated (XIE, PEX, and lbxproxy), but in the first two cases, the &os; port of &xfree86; did not support them either. Why did the X projects split, anyway? The answer to this question is outside the scope of this FAQ. Note that there are voluminous postings in various mailing list archives on the Internet; please use your favorite search engine to investigate the history instead of asking this question on the &os; mailing lists. It may even be the case that only the participants will ever know for certain. Why did &os; choose to go with the X.org ports by default? The X.org developers claim that their goal is to release more often and incorporate new features more quickly. If they are able to do so, this will be very attractive. Also, their software still uses the traditional X license, while &xfree86; is now using their modified one. This decision is still controversial. Only time will tell which implementation proves technically superior. Each &os; user should decide which they prefer. I want to run X, how do I go about it? The easiest way is to simply specify that you want to run X during the installation process. Then read and follow the documentation on the xf86config tool, which assists you in configuring &xfree86; for your particular graphics card/mouse/etc. You may also wish to investigate the Xaccel server. See the section on Xi Graphics or Metro Link for more details. I tried to run X, but I get an KDENABIO failed (Operation not permitted) error when I type startx. What do I do now? Your system is probably running at a raised securelevel. It is not possible to start X at a raised securelevel. To see why, look at the &man.init.8; manual page. So the question is what else you should do instead, and you basically have two choices: set your securelevel back down to zero (usually from /etc/rc.conf), or run &man.xdm.1; at boot time (before the securelevel is raised). See for more information about running &man.xdm.1; at boot time. Why does my mouse not work with X? If you are using syscons (the default console driver), you can configure FreeBSD to support a mouse pointer on each virtual screen. In order to avoid conflicting with X, syscons supports a virtual device called /dev/sysmouse. All mouse events received from the real mouse device are written to the sysmouse device via moused. If you wish to use your mouse on one or more virtual consoles, and use X, see and set up moused. Then edit /etc/XF86Config and make sure you have the following lines. Section Pointer Protocol "SysMouse" Device "/dev/sysmouse" ..... The above example is for &xfree86; 3.3.2 or later. For earlier versions, the Protocol should be MouseSystems. Some people prefer to use /dev/mouse under X. To make this work, /dev/mouse should be linked to /dev/sysmouse (see &man.sysmouse.4;): &prompt.root; cd /dev &prompt.root; rm -f mouse &prompt.root; ln -s sysmouse mouse My mouse has a fancy wheel. Can I use it in X? Yes. But you need to customize X client programs. See + url="http://www.inria.fr/koala/colas/mouse-wheel-scroll/"> Colas Nahaboo's web page (http://www.inria.fr/koala/colas/mouse-wheel-scroll/) . If you want to use the imwheel program, just follow these simple steps. Translate the Wheel Events The imwheel program works by translating mouse button 4 and mouse button 5 events into key events. Thus, you have to get the mouse driver to translate mouse wheel events to button 4 and 5 events. There are two ways of doing this, the first way is to have &man.moused.8; do the translation. The second way is for the X server itself to do the event translation. Using &man.moused.8; to Translate Wheel Events To have &man.moused.8; perform the event translations, simply add to the command line used to start &man.moused.8;. For example, if you normally start &man.moused.8; via moused -p /dev/psm0 you would start it by entering moused -p /dev/psm0 -z 4 instead. If you start &man.moused.8; automatically during bootup via /etc/rc.conf, you can simply add to the moused_flags variable in /etc/rc.conf. You now need to tell X that you have a 5 button mouse. To do this, simply add the line Buttons 5 to the Pointer section of /etc/XF86Config. For example, you might have the following Pointer section in /etc/XF86Config. <quote>Pointer</quote> Section for Wheeled Mouse in &xfree86; 3.3.x series XF86Config with moused Translation Section "Pointer" Protocol "SysMouse" Device "/dev/sysmouse" Buttons 5 EndSection <quote>InputDevice</quote> Section for Wheeled Mouse in &xfree86; 4.x series XF86Config with X Server Translation Section "InputDevice" Identifier "Mouse1" Driver "mouse" Option "Protocol" "auto" Option "Device" "/dev/sysmouse" Option "Buttons" "5" EndSection <quote>.emacs</quote> example for naive page scrolling with Wheeled Mouse ;; wheel mouse (global-set-key [mouse-4] 'scroll-down) (global-set-key [mouse-5] 'scroll-up) Using Your X Server to Translate the Wheel Events If you are not running &man.moused.8;, or if you do not want &man.moused.8; to translate your wheel events, you can have the X server do the event translation instead. This requires a couple of modifications to your /etc/XF86Config file. First, you need to choose the proper protocol for your mouse. Most wheeled mice use the &intellimouse; protocol. However, &xfree86; does support other protocols, such as MouseManPlusPS/2 for the Logitech MouseMan+ mice. Once you have chosen the protocol you will use, you need to add a Protocol line to the Pointer section. Secondly, you need to tell the X server to remap wheel scroll events to mouse buttons 4 and 5. This is done with the ZAxisMapping option. For example, if you are not using &man.moused.8;, and you have an &intellimouse; attached to the PS/2 mouse port you would use the following in /etc/XF86Config. <quote>Pointer</quote> Section for Wheeled Mouse in <filename>XF86Config</filename> with X Server Translation Section "Pointer" Protocol "IntelliMouse" Device "/dev/psm0" ZAxisMapping 4 5 EndSection <quote>InputDevice</quote> Section for Wheeled Mouse in &xfree86; 4.x series XF86Config with X Server Translation Section "InputDevice" Identifier "Mouse1" Driver "mouse" Option "Protocol" "auto" Option "Device" "/dev/psm0" Option "ZAxisMapping" "4 5" EndSection <quote>.emacs</quote> example for naive page scrolling with Wheeled Mouse ;; wheel mouse (global-set-key [mouse-4] 'scroll-down) (global-set-key [mouse-5] 'scroll-up) Install imwheel Next, install imwheel from the Ports collection. It can be found in the x11 category. This program will map the wheel events from your mouse into keyboard events. For example, it might send Page Up to a program when you scroll the wheel forwards. Imwheel uses a configuration file to map the wheel events to key presses so that it can send different keys to different applications. The default imwheel configuration file is installed in /usr/X11R6/etc/imwheelrc. You can copy it to ~/.imwheelrc and then edit it if you wish to customize imwheel's configuration. The format of the configuration file is documented in &man.imwheel.1;. Configure Emacs to Work with Imwheel (optional) If you use emacs or XEmacs, then you need to add a small section to your ~/.emacs file. For emacs, add the following: <application>Emacs</application> Configuration for <application>Imwheel</application> ;;; For imwheel (setq imwheel-scroll-interval 3) (defun imwheel-scroll-down-some-lines () (interactive) (scroll-down imwheel-scroll-interval)) (defun imwheel-scroll-up-some-lines () (interactive) (scroll-up imwheel-scroll-interval)) (global-set-key [?\M-\C-\)] 'imwheel-scroll-up-some-lines) (global-set-key [?\M-\C-\(] 'imwheel-scroll-down-some-lines) ;;; end imwheel section For XEmacs, add the following to your ~/.emacs file instead: <application>XEmacs</application> Configuration for <application>Imwheel</application> ;;; For imwheel (mwheel-install) (setq mwheel-follow-mouse t) ;;; end imwheel section Run Imwheel You can just type imwheel in an xterm to start it up once it is installed. It will background itself and take effect immediately. If you want to always use imwheel, simply add it to your .xinitrc or .xsession file. You can safely ignore any warnings imwheel displays about PID files. Those warnings only apply to the &linux; version of imwheel. How do I use remote X displays? For security reasons, the default setting is to not allow a machine to remotely open a window. To enable this feature, simply start X with the optional argument: &prompt.user; startx -listen_tcp Why do X Window menus and dialog boxes not work right? Try turning off the Num Lock key. If your Num Lock key is on by default at boot-time, you may add the following line in the Keyboard section of the XF86Config file. # Let the server do the NumLock processing. This should only be # required when using pre-R6 clients ServerNumLock What is a virtual console and how do I make more? Virtual consoles, put simply, enable you to have several simultaneous sessions on the same machine without doing anything complicated like setting up a network or running X. When the system starts, it will display a login prompt on the monitor after displaying all the boot messages. You can then type in your login name and password and start working (or playing!) on the first virtual console. At some point, you will probably wish to start another session, perhaps to look at documentation for a program you are running or to read your mail while waiting for an FTP transfer to finish. Just do AltF2 (hold down the Alt key and press the F2 key), and you will find a login prompt waiting for you on the second virtual console! When you want to go back to the original session, do AltF1. The default FreeBSD installation has three virtual consoles enabled (8 starting with 3.3-RELEASE), and AltF1, AltF2, and AltF3 will switch between these virtual consoles. To enable more of them, edit /etc/ttys (see &man.ttys.5;) and add entries for ttyv4 to ttyvc after the comment on Virtual terminals: # Edit the existing entry for ttyv3 in /etc/ttys and change # "off" to "on". ttyv3 "/usr/libexec/getty Pc" cons25 on secure ttyv4 "/usr/libexec/getty Pc" cons25 on secure ttyv5 "/usr/libexec/getty Pc" cons25 on secure ttyv6 "/usr/libexec/getty Pc" cons25 on secure ttyv7 "/usr/libexec/getty Pc" cons25 on secure ttyv8 "/usr/libexec/getty Pc" cons25 on secure ttyv9 "/usr/libexec/getty Pc" cons25 on secure ttyva "/usr/libexec/getty Pc" cons25 on secure ttyvb "/usr/libexec/getty Pc" cons25 on secure Use as many or as few as you want. The more virtual terminals you have, the more resources that are used; this can be important if you have 8MB RAM or less. You may also want to change the secure to insecure. If you want to run an X server you must leave at least one virtual terminal unused (or turned off) for it to use. That is to say that if you want to have a login prompt pop up for all twelve of your Alt-function keys, you are out of luck - you can only do this for eleven of them if you also want to run an X server on the same machine. The easiest way to disable a console is by turning it off. For example, if you had the full 12 terminal allocation mentioned above and you wanted to run X, you would change settings for virtual terminal 12 from: ttyvb "/usr/libexec/getty Pc" cons25 on secure to: ttyvb "/usr/libexec/getty Pc" cons25 off secure If your keyboard has only ten function keys, you would end up with: ttyv9 "/usr/libexec/getty Pc" cons25 off secure ttyva "/usr/libexec/getty Pc" cons25 off secure ttyvb "/usr/libexec/getty Pc" cons25 off secure (You could also just delete these lines.) Once you have edited /etc/ttys, the next step is to make sure that you have enough virtual terminal devices. The easiest way to do this is: &prompt.root; cd /dev &prompt.root; sh MAKEDEV vty12 On FreeBSD 5.X you do not have to create devices manually if you are using DEVFS, since the proper device nodes will be automatically created under /dev. Next, the easiest (and cleanest) way to activate the virtual consoles is to reboot. However, if you really do not want to reboot, you can just shut down the X Window system and execute (as root): &prompt.root; kill -HUP 1 It is imperative that you completely shut down X Window if it is running, before running this command. If you do not, your system will probably appear to hang/lock up after executing the kill command. How do I access the virtual consoles from X? Use Ctrl Alt Fn to switch back to a virtual console. Ctrl Alt F1 would return you to the first virtual console. Once you are back to a text console, you can then use Alt Fn as normal to move between them. To return to the X session, you must switch to the virtual console running X. If you invoked X from the command line, (e.g., using startx) then the X session will attach to the next unused virtual console, not the text console from which it was invoked. If you have eight active virtual terminals then X will be running on the ninth, and you would use Alt F9 to return. How do I start XDM on boot? There are two schools of thought on how to start + url="http://www.FreeBSD.org/cgi/man.cgi?manpath=xfree86&query=xdm"> xdm. One school starts xdm from /etc/ttys (see &man.ttys.5;) using the supplied example, while the other simply runs xdm from rc.local (see &man.rc.8;) or from a X.sh script in /usr/local/etc/rc.d. Both are equally valid, and one may work in situations where the other does not. In both cases the result is the same: X will pop up a graphical login: prompt. The ttys method has the advantage of documenting which vty X will start on and passing the responsibility of restarting the X server on logout to init. The rc.local method makes it easy to kill xdm if there is a problem starting the X server. If loaded from rc.local, xdm should be started without any arguments (i.e., as a daemon). xdm must start AFTER getty runs, or else getty and xdm will conflict, locking out the console. The best way around this is to have the script sleep 10 seconds or so then launch xdm. If you are to start xdm from /etc/ttys, there still is a chance of conflict between xdm and &man.getty.8;. One way to avoid this is to add the vt number in the /usr/X11R6/lib/X11/xdm/Xservers file. :0 local /usr/X11R6/bin/X vt4 The above example will direct the X server to run in /dev/ttyv3. Note the number is offset by one. The X server counts the vty from one, whereas the FreeBSD kernel numbers the vty from zero. Why do I get Couldn't open console when I run xconsole? If you start X with startx, the permissions on /dev/console will not get changed, resulting in things like xterm -C and xconsole not working. This is because of the way console permissions are set by default. On a multi-user system, one does not necessarily want just any user to be able to write on the system console. For users who are logging directly onto a machine with a VTY, the &man.fbtab.5; file exists to solve such problems. In a nutshell, make sure an uncommented line of the form /dev/ttyv0 0600 /dev/console is in /etc/fbtab (see &man.fbtab.5;) and it will ensure that whomever logs in on /dev/ttyv0 will own the console. Before, I was able to run &xfree86; as a regular user. Why does it now say that I must be root? All X servers need to be run as root in order to get direct access to your video hardware. Older versions of &xfree86; (<= 3.3.6) installed all bundled servers to be automatically run as root (setuid to root). This is obviously a security hazard because X servers are large, complicated programs. Newer versions of &xfree86; do not install the servers setuid to root for just this reason. Obviously, running an X server as the root user is not acceptable, nor a good idea security-wise. There are two ways to be able to use X as a regular user. The first is to use xdm or another display manager (e.g., kdm); the second is to use the Xwrapper. xdm is a daemon that handles graphical logins. It is usually started at boot time, and is responsible for authenticating users and starting their sessions; it is essentially the graphical counterpart of &man.getty.8; and &man.login.1;. For more information on xdm see the &xfree86; documentation, and the the FAQ entry on it. Xwrapper is the X server wrapper; it is a small utility to enable one to manually run an X server while maintaining reasonable safety. It performs some sanity checks on the command line arguments given, and if they pass, runs the appropriate X server. If you do not want to run a display manger for whatever reason, this is for you. If you have installed the complete ports collection, you can find the port in /usr/ports/x11/wrapper. Why does my PS/2 mouse misbehave under X? Your mouse and the mouse driver may have somewhat become out of synchronization. In rare cases the driver may erroneously report synchronization problem and you may see the kernel message: psmintr: out of sync (xxxx != yyyy) and notice that your mouse does not work properly. If this happens, disable the synchronization check code by setting the driver flags for the PS/2 mouse driver to 0x100. Enter UserConfig by giving the option at the boot prompt: boot: -c Then, in the UserConfig command line, type: UserConfig> flags psm0 0x100 UserConfig> quit Why does my PS/2 mouse from MouseSystems not work? There have been some reports that certain model of PS/2 mouse from MouseSystems works only if it is put into the high resolution mode. Otherwise, the mouse cursor may jump to the upper-left corner of the screen every so often. Specify the flags 0x04 to the PS/2 mouse driver to put the mouse into the high resolution mode. Enter UserConfig by giving the option at the boot prompt: boot: -c Then, in the UserConfig command line, type: UserConfig> flags psm0 0x04 UserConfig> quit See the previous section for another possible cause of mouse problems. When building an X app, imake cannot find Imake.tmpl. Where is it? Imake.tmpl is part of the Imake package, a standard X application building tool. Imake.tmpl, as well as several header files that are required to build X apps, is contained in the X prog distribution. You can install this from sysinstall or manually from the X distribution files. An X app I am building depends on &xfree86; 3.3.X, but I have &xfree86; 4.X installed. What should I do? To tell the port build to link to the &xfree86; 4.X libraries, add the following to /etc/make.conf, (if you do not have this file, create it): XFREE86_VERSION= 4 How do I reverse the mouse buttons? Run the command xmodmap -e "pointer = 3 2 1" from your .xinitrc or .xsession. How do I install a splash screen and where do I find them? Just prior to the release of FreeBSD 3.1, a new feature was added to allow the display of splash screens during the boot messages. The splash screens currently must be a 256 color bitmap (*.BMP) or ZSoft PCX (*.PCX) file. In addition, they must have a resolution of 320x200 or less to work on standard VGA adapters. If you compile VESA support into your kernel, then you can use larger bitmaps up to 1024x768. The actual VESA support can either be compiled directly into the kernel with the VESA kernel config option or by loading the VESA kld module during bootup. To use a splash screen, you need to modify the startup files that control the boot process for FreeBSD. The files for this changed prior to the release of FreeBSD 3.2, so there are now two ways of loading a splash screen: FreeBSD 3.1 The first step is to find a bitmap version of your splash screen. Release 3.1 only supports &windows; bitmap splash screens. Once you have found your splash screen of choice copy it to /boot/splash.bmp. Next, you need to have a /boot/loader.rc file that contains the following lines: load kernel load -t splash_image_data /boot/splash.bmp load splash_bmp autoboot FreeBSD 3.2+ In addition to adding support for PCX splash screens, FreeBSD 3.2 includes a nicer way of configuring the boot process. If you wish, you can use the method listed above for FreeBSD 3.1. If you do and you want to use PCX, replace splash_bmp with splash_pcx. If, on the other hand, you want to use the newer boot configuration, you need to create a /boot/loader.rc file that contains the following lines: include /boot/loader.4th start and a /boot/loader.conf that contains the following: splash_bmp_load="YES" bitmap_load="YES" This assumes you are using /boot/splash.bmp for your splash screen. If you would rather use a PCX file, copy it to /boot/splash.pcx, create a /boot/loader.rc as instructed above, and create a /boot/loader.conf that contains: splash_pcx_load="YES" bitmap_load="YES" bitmap_name="/boot/splash.pcx" Now all you need is a splash screen. For that you can surf on over to the gallery at . Can I use the &windows; keys on my keyboard in X? Yes. All you need to do is use &man.xmodmap.1; to define what function you wish them to perform. Assuming all &windows; keyboards are standard then the keycodes for the 3 keys are 115 - &windows; key, between the left-hand Ctrl and Alt keys 116 - &windows; key, to the right of the AltGr key 117 - Menu key, to the left of the right-hand Ctrl key To have the left &windows; key print a comma, try this. &prompt.root; xmodmap -e "keycode 115 = comma" You will probably have to re-start your window manager to see the result. To have the &windows; key-mappings enabled automatically every time you start X either put the xmodmap commands in your ~/.xinitrc file or, preferably, create a file ~/.xmodmaprc and include the xmodmap options, one per line, then add the line xmodmap $HOME/.xmodmaprc to your ~/.xinitrc. For example, you could map the 3 keys to be F13, F14, and F15, respectively. This would make it easy to map them to useful functions within applications or your window manager, as demonstrated further down. To do this put the following in ~/.xmodmaprc. keycode 115 = F13 keycode 116 = F14 keycode 117 = F15 If you use fvwm2, for example, you could map the keys so that F13 iconifies (or de-iconifies) the window the cursor is in, F14 brings the window the cursor is in to the front or, if it is already at the front, pushes it to the back, and F15 pops up the main Workplace (application) menu even if the cursor is not on the desktop, which is useful if you do not have any part of the desktop visible (and the logo on the key matches its functionality). The following entries in ~/.fvwmrc implement the aforementioned setup: Key F13 FTIWS A Iconify Key F14 FTIWS A RaiseLower Key F15 A A Menu Workplace Nop How can I get 3D hardware acceleration for &opengl;? The availability of 3D acceleration depends on the version of &xfree86; you are using and the type of video chip you have. If you have an NVIDIA chip, you can use the binary drivers provided for FreeBSD 4.7 on the Drivers section of their website. For other cards with &xfree86;-4, including the Matrox G200/G400, ATI Rage 128/Radeon, and 3dfx Voodoo 3, 4, 5, and Banshee, information on hardware acceleration is available on the XFree86-4 Direct Rendering on FreeBSD page. Users of &xfree86; version 3.3 can use the Utah-GLX port found in graphics/utah-glx to get limited accelerated &opengl; on the Matrox Gx00, ATI Rage Pro, SiS 6326, i810, Savage, and older NVIDIA chips. Networking Where can I get information on diskless booting? Diskless booting means that the FreeBSD box is booted over a network, and reads the necessary files from a server instead of its hard disk. For full details, - please read the + please read the Handbook entry on diskless booting Can a FreeBSD box be used as a dedicated network router? Yes. Please see the Handbook entry on advanced networking, specifically the section on routing and gateways. Can I connect my &windows; box to the Internet via FreeBSD? Typically, people who ask this question have two PC's at home, one with FreeBSD and one with some version of &windows; the idea is to use the FreeBSD box to connect to the Internet and then be able to access the Internet from the &windows; box through the FreeBSD box. This is really just a special case of the previous question and works perfectly well. If you're using dialup to connect to the Internet user-mode &man.ppp.8; contains a option. If you run &man.ppp.8; with the option, set gateway_enable to YES in /etc/rc.conf, and configure your &windows; machine correctly, this should work fine. For more information, please see the &man.ppp.8; manual page or the Handbook entry on user PPP. If you are using kernel-mode PPP or have an Ethernet connection to the Internet, you need to use &man.natd.8;. Please look at the natd section of the Handbook for a tutorial. Does FreeBSD support SLIP and PPP? Yes. See the manual pages for &man.slattach.8;, &man.sliplogin.8;, &man.ppp.8;, and &man.pppd.8;. &man.ppp.8; and &man.pppd.8; provide support for both incoming and outgoing connections, while &man.sliplogin.8; deals exclusively with incoming connections, and &man.slattach.8; deals exclusively with outgoing connections. For more information on how to use these, please see the Handbook chapter on PPP and SLIP. If you only have access to the Internet through a shell account, you may want to have a look at the net/slirp package. It can provide you with (limited) access to services such as ftp and http direct from your local machine. Does FreeBSD support NAT or Masquerading? Yes. If you want to use NAT over a user PPP connection, please see the Handbook entry on user PPP. If you want to use NAT over some other sort of network connection, please look at the natd section of the Handbook. How do I connect two FreeBSD systems over a parallel line using PLIP? Please see the PLIP section of the Handbook. Why can I not create a /dev/ed0 device? Because they aren't necessary. In the Berkeley networking framework, network interfaces are only directly accessible by kernel code. Please see the /etc/rc.network file and the manual pages for the various network programs mentioned there for more information. If this leaves you totally confused, then you should pick up a book describing network administration on another BSD-related operating system; with few significant exceptions, administering networking on FreeBSD is basically the same as on &sunos; 4.0 or Ultrix. How can I set up Ethernet aliases? If the alias is on the same subnet as an address already configured on the interface, then add netmask 0xffffffff to your &man.ifconfig.8; command-line, as in the following: &prompt.root; ifconfig ed0 alias 192.0.2.2 netmask 0xffffffff Otherwise, just specify the network address and netmask as usual: &prompt.root; ifconfig ed0 alias 172.16.141.5 netmask 0xffffff00 How do I get my 3C503 to use the other network port? If you want to use the other ports, you will have to specify an additional parameter on the &man.ifconfig.8; command line. The default port is link0. To use the AUI port instead of the BNC one, use link2. These flags should be specified using the ifconfig_* variables in /etc/rc.conf (see &man.rc.conf.5;). Why am I having trouble with NFS and FreeBSD? Certain PC network cards are better than others (to put it mildly) and can sometimes cause problems with network intensive applications like NFS. - See + See the Handbook entry on NFS for more information on this topic. Why can I not NFS-mount from a &linux; box? Some versions of the &linux; NFS code only accept mount requests from a privileged port; try &prompt.root; mount -o -P linuxbox:/blah /mnt Why can I not NFS-mount from a Sun box? &sun; workstations running &sunos; 4.X only accept mount requests from a privileged port; try &prompt.root; mount -o -P sunbox:/blah /mnt Why does mountd keep telling me it can't change attributes and that I have a bad exports list on my FreeBSD NFS server? The most frequent problem is not understanding the correct format of /etc/exports. Please review &man.exports.5; and the NFS entry in the Handbook, especially the section on configuring NFS. Why am I having problems talking PPP to NeXTStep machines? Try disabling the TCP extensions in /etc/rc.conf (see &man.rc.conf.5;) by changing the following variable to NO: tcp_extensions=NO Xylogic's Annex boxes are also broken in this regard and you must use the above change to connect through them. How do I enable IP multicast support? FreeBSD supports multicast host operations by default. If you want your box to run as a multicast router, you need to recompile your kernel with the MROUTING option and run &man.mrouted.8;. FreeBSD will start &man.mrouted.8; at boot time if the flag mrouted_enable is set to "YES" in /etc/rc.conf. MBONE tools are available in their own ports category, mbone. If you are looking for the conference tools vic and vat, look there! Which network cards are based on the DEC PCI chipset? Here is a list compiled by Glen Foster gfoster@driver.nsta.org, with some more modern additions: Network cards based on the DEC PCI chipset Vendor Model ASUS PCI-L101-TB Accton ENI1203 Cogent EM960PCI Compex ENET32-PCI D-Link DE-530 Dayna DP1203, DP2100 DEC DE435, DE450 Danpex EN-9400P3 JCIS Condor JC1260 Linksys EtherPCI Mylex LNP101 SMC EtherPower 10/100 (Model 9332) SMC EtherPower (Model 8432) TopWare TE-3500P Znyx (2.2.x) ZX312, ZX314, ZX342, ZX345, ZX346, ZX348 Znyx (3.x) ZX345Q, ZX346Q, ZX348Q, ZX412Q, ZX414, ZX442, ZX444, ZX474, ZX478, ZX212, ZX214 (10mbps/hd)
Why do I have to use the FQDN for hosts on my site? You will probably find that the host is actually in a different domain; for example, if you are in foo.example.org and you wish to reach a host called mumble in the example.org domain, you will have to refer to it by the fully-qualified domain name, mumble.example.org, instead of just mumble. Traditionally, this was allowed by BSD BIND resolvers. However the current version of bind (see &man.named.8;) that ships with FreeBSD no longer provides default abbreviations for non-fully qualified domain names other than the domain you are in. So an unqualified host mumble must either be found as mumble.foo.example.org, or it will be searched for in the root domain. This is different from the previous behavior, where the search continued across mumble.example.org, and mumble.edu. Have a look at RFC 1535 for why this was considered bad practice, or even a security hole. As a good workaround, you can place the line search foo.example.org example.org instead of the previous domain foo.example.org into your /etc/resolv.conf file (see &man.resolv.conf.5;). However, make sure that the search order does not go beyond the boundary between local and public administration, as RFC 1535 calls it. Why do I get an error, Permission denied, for all networking operations? If you have compiled your kernel with the IPFIREWALL option, you need to be aware that the default policy is to deny all packets that are not explicitly allowed. If you had unintentionally misconfigured your system for firewalling, you can restore network operability by typing the following while logged in as root: &prompt.root; ipfw add 65534 allow all from any to any You can also set firewall_type="open" in /etc/rc.conf. For further information on configuring a FreeBSD - firewall, see the + firewall, see the Handbook section. How much overhead does IPFW incur? Please see the Handbook's Firewalls section, specifically the section on IPFW Overhead & Optimization. Why is my ipfw fwd rule to redirect a service to another machine not working? Possibly because you want to do network address translation (NAT) and not just forward packets. A fwd rule does exactly what it says; it forwards packets. It does not actually change the data inside the packet. Say we have a rule like: 01000 fwd 10.0.0.1 from any to foo 21 When a packet with a destination address of foo arrives at the machine with this rule, the packet is forwarded to 10.0.0.1, but it still has the destination address of foo! The destination address of the packet is not changed to 10.0.0.1. Most machines would probably drop a packet that they receive with a destination address that is not their own. Therefore, using a fwd rule does not often work the way the user expects. This behavior is a feature and not a bug. See the FAQ about redirecting services, the &man.natd.8; manual, or one of the several port redirecting utilities in the ports collection for a correct way to do this. How can I redirect service requests from one machine to another? You can redirect FTP (and other service) request with the socket package, available in the ports tree in category sysutils. Simply replace the service's command line to call socket instead, like so: ftp stream tcp nowait nobody /usr/local/bin/socket socket ftp.example.com ftp where ftp.example.com and ftp are the host and port to redirect to, respectively. Where can I get a bandwidth management tool? There are three bandwidth management tools available for FreeBSD. &man.dummynet.4; is integrated into FreeBSD (or more specifically, &man.ipfw.4;); ALTQ + url="http://www.csl.sony.co.jp/person/kjc/programs.html">ALTQ is available for free; Bandwidth Manager from Emerging Technologies is a + url="http://www.etinc.com/">Emerging Technologies is a commercial product. Why do I get /dev/bpf0: device not configured? You are running a program that requires the Berkeley Packet Filter (&man.bpf.4;), but it is not in your kernel. Add this to your kernel config file and build a new kernel: pseudo-device bpf # Berkeley Packet Filter On FreeBSD 4.X and earlier, you must also create the device node. After rebooting, go to the /dev directory and run: &prompt.root; sh MAKEDEV bpf0 Please see the Handbook entry + url="&url.books.handbook;/kernelconfig-nodes.html"> Handbook entry on device nodes for more information on managing devices. How do I mount a disk from a &windows; machine that is on my network, like smbmount in &linux;? Use the SMBFS toolset. It includes a set of kernel modifications and a set of userland programs. The programs and information are available as net/smbfs in the ports collection, or in the base system as of 4.5-RELEASE and later. What are these messages about icmp-response bandwidth limit 300/200 pps in my log files? This is the kernel telling you that some activity is provoking it to send more ICMP or TCP reset (RST) responses than it thinks it should. ICMP responses are often generated as a result of attempted connections to unused UDP ports. TCP resets are generated as a result of attempted connections to unopened TCP ports. Among others, these are the kinds of activities which may cause these messages: Brute-force denial of service (DoS) attacks (as opposed to single-packet attacks which exploit a specific vulnerability). Port scans which attempt to connect to a large number of ports (as opposed to only trying a few well-known ports). The first number in the message tells you how many packets the kernel would have sent if the limit was not in place, and the second number tells you the limit. You can control the limit using the net.inet.icmp.icmplim sysctl variable like this, where 300 is the limit in packets per second: &prompt.root; sysctl -w net.inet.icmp.icmplim=300 If you do not want to see messages about this in your log files, but you still want the kernel to do response limiting, you can use the net.inet.icmp.icmplim_output sysctl variable to disable the output like this: &prompt.root; sysctl -w net.inet.icmp.icmplim_output=0 Finally, if you want to disable response limiting, you can set the net.inet.icmp.icmplim sysctl variable (see above for an example) to 0. Disabling response limiting is discouraged for the reasons listed above. What are these arp: unknown hardware address format error messages? This means that some device on your local Ethernet is using a MAC address in a format that FreeBSD does not recognize. This is probably caused by someone experimenting with an Ethernet card somewhere else on the network. You will see this most commonly on cable modem networks. It is harmless, and should not affect the performance of your FreeBSD machine. I've just installed CVSup but trying to execute it produces errors. What is wrong? First, see if the error message you are receiving is like the one shown below. /usr/libexec/ld-elf.so.1: Shared object "libXaw.so.6" not found Errors like these are caused by installing the net/cvsup port on a machine which does not have the &xfree86; suite. If you want to use the GUI included with CVSup you will need to install &xfree86; now. Alternatively if you just wish to use CVSup from a command line you should delete the package previously installed. Then install the net/cvsup-without-gui port. This is covered in more detail in the CVSup section of the Handbook. Security What is a sandbox? Sandbox is a security term. It can mean two things: A process which is placed inside a set of virtual walls that are designed to prevent someone who breaks into the process from being able to break into the wider system. The process is said to be able to play inside the walls. That is, nothing the process does in regards to executing code is supposed to be able to breech the walls so you do not have to do a detailed audit of its code to be able to say certain things about its security. The walls might be a userid, for example. This is the definition used in the security and named man pages. Take the ntalk service, for example (see /etc/inetd.conf). This service used to run as userid root. Now it runs as userid tty. The tty user is a sandbox designed to make it more difficult for someone who has successfully hacked into the system via ntalk from being able to hack beyond that user id. A process which is placed inside a simulation of the machine. This is more hard-core. Basically it means that someone who is able to break into the process may believe that he can break into the wider machine but is, in fact, only breaking into a simulation of that machine and not modifying any real data. The most common way to accomplish this is to build a simulated environment in a subdirectory and then run the processes in that directory chroot'd (i.e. / for that process is this directory, not the real / of the system). Another common use is to mount an underlying filesystem read-only and then create a filesystem layer on top of it that gives a process a seemingly writeable view into that filesystem. The process may believe it is able to write to those files, but only the process sees the effects - other processes in the system do not, necessarily. An attempt is made to make this sort of sandbox so transparent that the user (or hacker) does not realize that he is sitting in it. &unix; implements two core sandboxes. One is at the process level, and one is at the userid level. Every &unix; process is completely firewalled off from every other &unix; process. One process cannot modify the address space of another. This is unlike &windows; where a process can easily overwrite the address space of any other, leading to a crash. A &unix; process is owned by a particular userid. If the userid is not the root user, it serves to firewall the process off from processes owned by other users. The userid is also used to firewall off on-disk data. What is securelevel? The securelevel is a security mechanism implemented in the kernel. Basically, when the securelevel is positive, the kernel restricts certain tasks; not even the superuser (i.e., root) is allowed to do them. At the time of this writing, the securelevel mechanism is capable of, among other things, limiting the ability to, unset certain file flags, such as schg (the system immutable flag), write to kernel memory via /dev/mem and /dev/kmem, load kernel modules, and alter &man.ipfirewall.4; rules. To check the status of the securelevel on a running system, simply execute the following command: &prompt.root; sysctl kern.securelevel The output will contain the name of the &man.sysctl.8; variable (in this case, kern.securelevel) and a number. The latter is the current value of the securelevel. If it is positive (i.e., greater than 0), at least some of the securelevel's protections are enabled. You cannot lower the securelevel of a running system; being able to do that would defeat its purpose. If you need to do a task that requires that the securelevel be non-positive (e.g., an installworld or changing the date), you will have to change the securelevel setting in /etc/rc.conf (you want to look for the kern_securelevel and kern_securelevel_enable variables) and reboot. For more information on securelevel and the specific things all the levels do, please consult the &man.init.8; manual page. Securelevel is not a silver bullet; it has many known deficiencies. More often than not, it provides a false sense of security. One of its biggest problems is that in order for it to be at all effective, all files used in the boot process up until the securelevel is set must be protected. If an attacker can get the system to execute their code prior to the securelevel being set (which happens quite late in the boot process since some things the system must do at start-up cannot be done at an elevated securelevel), its protections are invalidated. While this task of protecting all files used in the boot process is not technically impossible, if it is achieved, system maintenance will become a nightmare since one would have to take the system down, at least to single-user mode, to modify a configuration file. This point and others are often discussed on the mailing lists, particularly the &a.security;. Please search the archives here for an extensive discussion. Some people are hopeful that securelevel will soon go away in favor of a more fine-grained mechanism, but things are still hazy in this respect. Consider yourself warned. BIND (named) is listening on port 53 and some other high-numbered port. What is going on? FreeBSD 3.0 and later use a version of BIND that uses a random high-numbered port for outgoing queries. If you want to use port 53 for outgoing queries, either to get past a firewall or to make yourself feel better, you can try the following in /etc/namedb/named.conf: options { query-source address * port 53; }; You can replace the * with a single IP address if you want to tighten things further. Congratulations, by the way. It is good practice to read your &man.sockstat.1; output and notice odd things! Sendmail is listening on port 587 as well as the standard port 25! What is going on? Recent versions of Sendmail support a mail submission feature that runs over port 587. This is not yet widely supported, but is growing in popularity. What is this UID 0 toor account? Have I been compromised? Do not worry. toor is an alternative superuser account (toor is root spelt backwards). Previously it was created when the &man.bash.1; shell was installed but now it is created by default. It is intended to be used with a non-standard shell so you do not have to change root's default shell. This is important as shells which are not part of the base distribution (for example a shell installed from ports or packages) are likely to be installed in /usr/local/bin which, by default, resides on a different filesystem. If root's shell is located in /usr/local/bin and /usr (or whatever filesystem contains /usr/local/bin) is not mounted for some reason, root will not be able to log in to fix a problem (although if you reboot into single user mode you will be prompted for the path to a shell). Some people use toor for day-to-day root tasks with a non-standard shell, leaving root, with a standard shell, for single user mode or emergencies. By default you cannot log in using toor as it does not have a password, so log in as root and set a password for toor if you want to use it. Why is suidperl not working properly? For security reasons, suidperl is installed without the suid bit by default. The system administrator can enable suid behavior with the following command. &prompt.root; chmod u+s /usr/bin/suidperl If you want suidperl to be built suid during upgrades from source, edit /etc/make.conf and add ENABLE_SUIDPERL=true before you run make buildworld. PPP I cannot make &man.ppp.8; work. What am I doing wrong? You should first read the &man.ppp.8; manual page and - the + the PPP section of the handbook. Enable logging with the command set log Phase Chat Connect Carrier lcp ipcp ccp command This command may be typed at the &man.ppp.8; command prompt or it may be entered in the /etc/ppp/ppp.conf configuration file (the start of the default section is the best place to put it). Make sure that /etc/syslog.conf (see &man.syslog.conf.5;) contains the lines !ppp *.* /var/log/ppp.log and that the file /var/log/ppp.log exists. You can now find out a lot about what is going on from the log file. Do not worry if it does not all make sense. If you need to get help from someone, it may make sense to them. If your version of &man.ppp.8; does not understand the set log command, you should download the - + latest version. It will build on FreeBSD version 2.1.5 and higher. Why does &man.ppp.8; hang when I run it? This is usually because your hostname will not resolve. The best way to fix this is to make sure that /etc/hosts is consulted by your resolver first by editing /etc/host.conf and putting the hosts line first. Then, simply put an entry in /etc/hosts for your local machine. If you have no local network, change your localhost line: 127.0.0.1 foo.example.com foo localhost Otherwise, simply add another entry for your host. Consult the relevant manual pages for more details. You should be able to successfully ping -c1 `hostname` when you are done. Why will &man.ppp.8; not dial in -auto mode? First, check that you have got a default route. By running netstat -rn (see &man.netstat.1;), you should see two entries like this: Destination Gateway Flags Refs Use Netif Expire default 10.0.0.2 UGSc 0 0 tun0 10.0.0.2 10.0.0.1 UH 0 0 tun0 This is assuming that you have used the addresses from the handbook, the manual page or from the ppp.conf.sample file. If you do not have a default route, it may be because you are running an old version of &man.ppp.8; that does not understand the word HISADDR in the ppp.conf file. If your version of &man.ppp.8; is from before FreeBSD 2.2.5, change the add 0 0 HISADDR line to one saying add 0 0 10.0.0.2 Another reason for the default route line being missing is that you have mistakenly set up a default router in your /etc/rc.conf (see &man.rc.conf.5;) file (this file was called /etc/sysconfig prior to release 2.2.2), and you have omitted the line saying delete ALL from ppp.conf. If this is the case, go back to the Final + url="&url.books.handbook;/ppp-and-slip.html#USERPPP-FINAL"> Final system configuration section of the handbook. What does No route to host mean? This error is usually due to a missing MYADDR: delete ALL add 0 0 HISADDR section in your /etc/ppp/ppp.linkup file. This is only necessary if you have a dynamic IP address or do not know the address of your gateway. If you are using interactive mode, you can type the following after entering packet mode (packet mode is indicated by the capitalized PPP in the prompt): delete ALL add 0 0 HISADDR Refer to the + url="&url.books.handbook;/ppp-and-slip.html#USERPPP-DYNAMICIP"> PPP and Dynamic IP addresses section of the handbook for further details. Why does my connection drop after about 3 minutes? The default PPP timeout is 3 minutes. This can be adjusted with the line set timeout NNN where NNN is the number of seconds of inactivity before the connection is closed. If NNN is zero, the connection is never closed due to a timeout. It is possible to put this command in the ppp.conf file, or to type it at the prompt in interactive mode. It is also possible to adjust it on the fly while the line is active by connecting to ppp's server socket using &man.telnet.1; or &man.pppctl.8;. Refer to the &man.ppp.8; man page for further details. Why does my connection drop under heavy load? If you have Link Quality Reporting (LQR) configured, it is possible that too many LQR packets are lost between your machine and the peer. Ppp deduces that the line must therefore be bad, and disconnects. Prior to FreeBSD version 2.2.5, LQR was enabled by default. It is now disabled by default. LQR can be disabled with the line disable lqr Why does my connection drop after a random amount of time? Sometimes, on a noisy phone line or even on a line with call waiting enabled, your modem may hang up because it thinks (incorrectly) that it lost carrier. There is a setting on most modems for determining how tolerant it should be to temporary losses of carrier. On a USR &sportster; for example, this is measured by the S10 register in tenths of a second. To make your modem more forgiving, you could add the following send-expect sequence to your dial string: set dial "...... ATS10=10 OK ......" Refer to your modem manual for details. Why does my connection hang after a random amount of time? Many people experience hung connections with no apparent explanation. The first thing to establish is which side of the link is hung. If you are using an external modem, you can simply try using &man.ping.8; to see if the TD light is flashing when you transmit data. If it flashes (and the RD light does not), the problem is with the remote end. If TD does not flash, the problem is local. With an internal modem, you will need to use the set server command in your ppp.conf file. When the hang occurs, connect to &man.ppp.8; using &man.pppctl.8;. If your network connection suddenly revives (PPP was revived due to the activity on the diagnostic socket) or if you cannot connect (assuming the set socket command succeeded at startup time), the problem is local. If you can connect and things are still hung, enable local async logging with set log local async and use &man.ping.8; from another window or terminal to make use of the link. The async logging will show you the data being transmitted and received on the link. If data is going out and not coming back, the problem is remote. Having established whether the problem is local or remote, you now have two possibilities: If the problem is remote, read on entry . If the problem is local, read on entry . The remote end is not responding. What can I do? There is very little you can do about this. Most ISPs will refuse to help if you are not running a Microsoft OS. You can enable lqr in your ppp.conf file, allowing &man.ppp.8; to detect the remote failure and hang up, but this detection is relatively slow and therefore not that useful. You may want to avoid telling your ISP that you are running user-PPP... First, try disabling all local compression by adding the following to your configuration: disable pred1 deflate deflate24 protocomp acfcomp shortseq vj deny pred1 deflate deflate24 protocomp acfcomp shortseq vj Then reconnect to ensure that this makes no difference. If things improve or if the problem is solved completely, determine which setting makes the difference through trial and error. This will provide good ammunition when you contact your ISP (although it may make it apparent that you are not running a Microsoft product). Before contacting your ISP, enable async logging locally and wait until the connection hangs again. This may use up quite a bit of disk space. The last data read from the port may be of interest. It is usually ascii data, and may even describe the problem (Memory fault, core dumped?). If your ISP is helpful, they should be able to enable logging on their end, then when the next link drop occurs, they may be able to tell you why their side is having a problem. Feel free to send the details to &a.brian;, or even to ask your ISP to contact me directly. &man.ppp.8; has hung. What can I do? Your best bet here is to rebuild &man.ppp.8; by adding CFLAGS+=-g and STRIP= to the end of the Makefile, then doing a make clean && make && make install. When &man.ppp.8; hangs, find the &man.ppp.8; process id with ps ajxww | fgrep ppp and run gdb ppp PID. From the gdb prompt, you can then use bt to get a stack trace. Send the results to &a.brian;. Why does nothing happen after the Login OK! message? Prior to FreeBSD version 2.2.5, once the link was established, &man.ppp.8; would wait for the peer to initiate the Line Control Protocol (LCP). Many ISPs will not initiate negotiations and expect the client to do so. To force &man.ppp.8; to initiate the LCP, use the following line: set openmode active It usually does no harm if both sides initiate negotiation, so openmode is now active by default. However, the next section explains when it does do some harm. I keep seeing errors about magic being the same. What does it mean? Occasionally, just after connecting, you may see messages in the log that say magic is the same. Sometimes, these messages are harmless, and sometimes one side or the other exits. Most PPP implementations cannot survive this problem, and even if the link seems to come up, you will see repeated configure requests and configure acknowledgments in the log file until &man.ppp.8; eventually gives up and closes the connection. This normally happens on server machines with slow disks that are spawning a getty on the port, and executing &man.ppp.8; from a login script or program after login. I have also heard reports of it happening consistently when using slirp. The reason is that in the time taken between &man.getty.8; exiting and &man.ppp.8; starting, the client-side &man.ppp.8; starts sending Line Control Protocol (LCP) packets. Because ECHO is still switched on for the port on the server, the client &man.ppp.8; sees these packets reflect back. One part of the LCP negotiation is to establish a magic number for each side of the link so that reflections can be detected. The protocol says that when the peer tries to negotiate the same magic number, a NAK should be sent and a new magic number should be chosen. During the period that the server port has ECHO turned on, the client &man.ppp.8; sends LCP packets, sees the same magic in the reflected packet and NAKs it. It also sees the NAK reflect (which also means &man.ppp.8; must change its magic). This produces a potentially enormous number of magic number changes, all of which are happily piling into the server's tty buffer. As soon as &man.ppp.8; starts on the server, it is flooded with magic number changes and almost immediately decides it has tried enough to negotiate LCP and gives up. Meanwhile, the client, who no longer sees the reflections, becomes happy just in time to see a hangup from the server. This can be avoided by allowing the peer to start negotiating with the following line in your ppp.conf file: set openmode passive This tells &man.ppp.8; to wait for the server to initiate LCP negotiations. Some servers however may never initiate negotiations. If this is the case, you can do something like: set openmode active 3 This tells &man.ppp.8; to be passive for 3 seconds, and then to start sending LCP requests. If the peer starts sending requests during this period, &man.ppp.8; will immediately respond rather than waiting for the full 3 second period. LCP negotiations continue until the connection is closed. What is wrong? There is currently an implementation mis-feature in &man.ppp.8; where it does not associate LCP, CCP & IPCP responses with their original requests. As a result, if one PPP implementation is more than 6 seconds slower than the other side, the other side will send two additional LCP configuration requests. This is fatal. Consider two implementations, A and B. A starts sending LCP requests immediately after connecting and B takes 7 seconds to start. When B starts, A has sent 3 LCP REQs. We are assuming the line has ECHO switched off, otherwise we would see magic number problems as described in the previous section. B sends a REQ, then an ACK to the first of A's REQs. This results in A entering the OPENED state and sending and ACK (the first) back to B. In the meantime, B sends back two more ACKs in response to the two additional REQs sent by A before B started up. B then receives the first ACK from A and enters the OPENED state. A receives the second ACK from B and goes back to the REQ-SENT state, sending another (forth) REQ as per the RFC. It then receives the third ACK and enters the OPENED state. In the meantime, B receives the forth REQ from A, resulting in it reverting to the ACK-SENT state and sending another (second) REQ and (forth) ACK as per the RFC. A gets the REQ, goes into REQ-SENT and sends another REQ. It immediately receives the following ACK and enters OPENED. This goes on until one side figures out that they are getting nowhere and gives up. The best way to avoid this is to configure one side to be passive - that is, make one side wait for the other to start negotiating. This can be done with the set openmode passive command. Care should be taken with this option. You should also use the set stopped N command to limit the amount of time that &man.ppp.8; waits for the peer to begin negotiations. Alternatively, the set openmode active N command (where N is the number of seconds to wait before starting negotiations) can be used. Check the manual page for details. Why does &man.ppp.8; lock up shortly after connection? Prior to version 2.2.5 of FreeBSD, it was possible that your link was disabled shortly after connection due to &man.ppp.8; mis-handling Predictor1 compression negotiation. This would only happen if both sides tried to negotiate different Compression Control Protocols (CCP). This problem is now corrected, but if you are still running an old version of &man.ppp.8; the problem can be circumvented with the line disable pred1 Why does &man.ppp.8; lock up when I shell out to test it? When you execute the shell or ! command, &man.ppp.8; executes a shell (or if you have passed any arguments, &man.ppp.8; will execute those arguments). Ppp will wait for the command to complete before continuing. If you attempt to use the PPP link while running the command, the link will appear to have frozen. This is because &man.ppp.8; is waiting for the command to complete. If you wish to execute commands like this, use the !bg command instead. This will execute the given command in the background, and &man.ppp.8; can continue to service the link. Why does &man.ppp.8; over a null-modem cable never exit? There is no way for &man.ppp.8; to automatically determine that a direct connection has been dropped. This is due to the lines that are used in a null-modem serial cable. When using this sort of connection, LQR should always be enabled with the line enable lqr LQR is accepted by default if negotiated by the peer. Why does &man.ppp.8; dial for no reason in -auto mode? If &man.ppp.8; is dialing unexpectedly, you must determine the cause, and set up Dial filters (dfilters) to prevent such dialing. To determine the cause, use the following line: set log +tcp/ip This will log all traffic through the connection. The next time the line comes up unexpectedly, you will see the reason logged with a convenient timestamp next to it. You can now disable dialing under these circumstances. Usually, this sort of problem arises due to DNS lookups. To prevent DNS lookups from establishing a connection (this will not prevent &man.ppp.8; from passing the packets through an established connection), use the following: set dfilter 1 deny udp src eq 53 set dfilter 2 deny udp dst eq 53 set dfilter 3 permit 0/0 0/0 This is not always suitable, as it will effectively break your demand-dial capabilities - most programs will need a DNS lookup before doing any other network related things. In the DNS case, you should try to determine what is actually trying to resolve a host name. A lot of the time, &man.sendmail.8; is the culprit. You should make sure that you tell sendmail not to do any DNS lookups in its configuration file. See the section on using email with a + url="&url.books.handbook;/smtp-dialup.html">using email with a dialup connection in the FreeBSD Handbook for details on how to create your own configuration file and what should go into it. You may also want to add the following line to your .mc file: define(`confDELIVERY_MODE', `d')dnl This will make sendmail queue everything until the queue is run (usually, sendmail is invoked with , telling it to run the queue every 30 minutes) or until a sendmail -q is done (perhaps from your ppp.linkup file). What do these CCP errors mean? I keep seeing the following errors in my log file: CCP: CcpSendConfigReq CCP: Received Terminate Ack (1) state = Req-Sent (6) This is because &man.ppp.8; is trying to negotiate Predictor1 compression, and the peer does not want to negotiate any compression at all. The messages are harmless, but if you wish to remove them, you can disable Predictor1 compression locally too: disable pred1 Why does &man.ppp.8; not log my connection speed? In order to log all lines of your modem conversation, you must enable the following: set log +connect This will make &man.ppp.8; log everything up until the last requested expect string. If you wish to see your connect speed and are using PAP or CHAP (and therefore do not have anything to chat after the CONNECT in the dial script - no set login script), you must make sure that you instruct &man.ppp.8; to expect the whole CONNECT line, something like this: set dial "ABORT BUSY ABORT NO\\sCARRIER TIMEOUT 4 \ \"\" ATZ OK-ATZ-OK ATDT\\T TIMEOUT 60 CONNECT \\c \\n" Here, we get our CONNECT, send nothing, then expect a line-feed, forcing &man.ppp.8; to read the whole CONNECT response. Why does &man.ppp.8; ignore the \ character in my chat script? Ppp parses each line in your config files so that it can interpret strings such as set phone "123 456 789" correctly and realize that the number is actually only one argument. In order to specify a " character, you must escape it using a backslash (\). When the chat interpreter parses each argument, it re-interprets the argument in order to find any special escape sequences such as \P or \T (see the manual page). As a result of this double-parsing, you must remember to use the correct number of escapes. If you wish to actually send a \ character to (say) your modem, you would need something like: set dial "\"\" ATZ OK-ATZ-OK AT\\\\X OK" resulting in the following sequence: ATZ OK AT\X OK or set phone 1234567 set dial "\"\" ATZ OK ATDT\\T" resulting in the following sequence: ATZ OK ATDT1234567 Why does &man.ppp.8; get a seg-fault, but I see no ppp.core file? Ppp (or any other program for that matter) should never dump core. Because &man.ppp.8; runs with an effective user id of 0, the operating system will not write &man.ppp.8;'s core image to disk before terminating it. If, however &man.ppp.8; is actually terminating due to a segmentation violation or some other signal that normally causes core to be dumped, and you are sure you are using the latest version (see the start of this section), then you should do the following: &prompt.user; tar xfz ppp-*.src.tar.gz &prompt.user; cd ppp*/ppp &prompt.user; echo STRIP= >>Makefile &prompt.user; echo CFLAGS+=-g >>Makefile &prompt.user; make clean all &prompt.user; su &prompt.root; make install &prompt.root; chmod 555 /usr/sbin/ppp You will now have a debuggable version of &man.ppp.8; installed. You will have to be root to run &man.ppp.8; as all of its privileges have been revoked. When you start &man.ppp.8;, take a careful note of what your current directory was at the time. Now, if and when &man.ppp.8; receives the segmentation violation, it will dump a core file called ppp.core. You should then do the following: &prompt.user; su &prompt.root; gdb /usr/sbin/ppp ppp.core (gdb) bt ..... (gdb) f 0 .... (gdb) i args .... (gdb) l ..... All of this information should be given alongside your question, making it possible to diagnose the problem. If you are familiar with gdb, you may wish to find out some other bits and pieces such as what actually caused the dump and the addresses & values of the relevant variables. Why does the process that forces a dial in auto mode never connect? This was a known problem with &man.ppp.8; set up to negotiate a dynamic local IP number with the peer in auto mode. It is fixed in the latest version - search the manual page for iface. The problem was that when that initial program calls &man.connect.2;, the IP number of the tun interface is assigned to the socket endpoint. The kernel creates the first outgoing packet and writes it to the tun device. &man.ppp.8; then reads the packet and establishes a connection. If, as a result of &man.ppp.8;'s dynamic IP assignment, the interface address is changed, the original socket endpoint will be invalid. Any subsequent packets sent to the peer will usually be dropped. Even if they are not, any responses will not route back to the originating machine as the IP number is no longer owned by that machine. There are several theoretical ways to approach this problem. It would be nicest if the peer would re-assign the same IP number if possible :-) The current version of &man.ppp.8; does this, but most other implementations do not. The easiest method from our side would be to never change the tun interface IP number, but instead to change all outgoing packets so that the source IP number is changed from the interface IP to the negotiated IP on the fly. This is essentially what the iface-alias option in the latest version of &man.ppp.8; is doing (with the help of &man.libalias.3; and &man.ppp.8;'s switch) - it is maintaining all previous interface addresses and NATing them to the last negotiated address. Another alternative (and probably the most reliable) would be to implement a system call that changes all bound sockets from one IP to another. &man.ppp.8; would use this call to modify the sockets of all existing programs when a new IP number is negotiated. The same system call could be used by dhcp clients when they are forced to re-bind() their sockets. Yet another possibility is to allow an interface to be brought up without an IP number. Outgoing packets would be given an IP number of 255.255.255.255 up until the first SIOCAIFADDR ioctl is done. This would result in fully binding the socket. It would be up to &man.ppp.8; to change the source IP number, but only if it is set to 255.255.255.255, and only the IP number and IP checksum would need to change. This, however is a bit of a hack as the kernel would be sending bad packets to an improperly configured interface, on the assumption that some other mechanism is capable of fixing things retrospectively. Why do most games not work with the -nat switch? The reason games and the like do not work when libalias is in use is that the machine on the outside will try to open a connection or send (unsolicited) UDP packets to the machine on the inside. The NAT software does not know that it should send these packets to the interior machine. To make things work, make sure that the only thing running is the software that you are having problems with, then either run tcpdump on the tun interface of the gateway or enable &man.ppp.8; tcp/ip logging (set log +tcp/ip) on the gateway. When you start the offending software, you should see packets passing through the gateway machine. When something comes back from the outside, it will be dropped (that is the problem). Note the port number of these packets then shut down the offending software. Do this a few times to see if the port numbers are consistent. If they are, then the following line in the relevant section of /etc/ppp/ppp.conf will make the software functional: nat port proto internalmachine:port port where proto is either tcp or udp, internalmachine is the machine that you want the packets to be sent to and port is the destination port number of the packets. You will not be able to use the software on other machines without changing the above command, and running the software on two internal machines at the same time is out of the question - after all, the outside world is seeing your entire internal network as being just a single machine. If the port numbers are not consistent, there are three more options: Submit support in libalias. Examples of special cases can be found in /usr/src/lib/libalias/alias_*.c (alias_ftp.c is a good prototype). This usually involves reading certain recognised outgoing packets, identifying the instruction that tells the outside machine to initiate a connection back to the internal machine on a specific (random) port and setting up a route in the alias table so that the subsequent packets know where to go. This is the most difficult solution, but it is the best and will make the software work with multiple machines. Use a proxy. The application may support socks5 for example, or (as in the cvsup case) may have a passive option that avoids ever requesting that the peer open connections back to the local machine. Redirect everything to the internal machine using nat addr. This is the sledge-hammer approach. Has anybody made a list of useful port numbers? Not yet, but this is intended to grow into such a list (if any interest is shown). In each example, internal should be replaced with the IP number of the machine playing the game. Asheron's Call nat port udp internal :65000 65000 Manually change the port number within the game to 65000. If you have got a number of machines that you wish to play on assign a unique port number for each (i.e. 65001, 65002, etc) and add a nat port line for each one. Half Life nat port udp internal:27005 27015 PCAnywhere 8.0 nat port udp internal:5632 5632 nat port tcp internal:5631 5631 Quake nat port udp internal:6112 6112 Alternatively, you may want to take a look at + url="http://www.battle.net/support/proxy/"> www.battle.net for Quake proxy support. Quake 2 nat port udp internal:27901 27910 nat port udp internal:60021 60021 nat port udp internal:60040 60040 Red Alert nat port udp internal:8675 8675 nat port udp internal:5009 5009 What are FCS errors? FCS stands for Frame Check Sequence. Each PPP packet has a checksum attached to ensure that the data being received is the data being sent. If the FCS of an incoming packet is incorrect, the packet is dropped and the HDLC FCS count is increased. The HDLC error values can be displayed using the show hdlc command. If your link is bad (or if your serial driver is dropping packets), you will see the occasional FCS error. This is not usually worth worrying about although it does slow down the compression protocols substantially. If you have an external modem, make sure your cable is properly shielded from interference - this may eradicate the problem. If your link freezes as soon as you have connected and you see a large number of FCS errors, this may be because your link is not 8 bit clean. Make sure your modem is not using software flow control (XON/XOFF). If your datalink must use software flow control, use the command set accmap 0x000a0000 to tell &man.ppp.8; to escape the ^Q and ^S characters. Another reason for seeing too many FCS errors may be that the remote end has stopped talking PPP. You may want to enable async logging at this point to determine if the incoming data is actually a login or shell prompt. If you have a shell prompt at the remote end, it is possible to terminate &man.ppp.8; without dropping the line by using the close lcp command (a following term command will reconnect you to the shell on the remote machine. If nothing in your log file indicates why the link might have been terminated, you should ask the remote administrator (your ISP?) why the session was terminated. Why do &macos; and &windows; 98 connections freeze when running PPPoE on the gateway? Thanks to Michael Wozniak mwozniak@netcom.ca for figuring this out and Dan Flemming danflemming@mac.com for the Mac solution: This is due to what is called a Black Hole router. &macos; and &windows; 98 (and maybe other Microsoft OSs) send TCP packets with a requested segment size too big to fit into a PPPoE frame (MTU is 1500 by default for Ethernet) and have the do not fragment bit set (default of TCP) and the Telco router is not sending ICMP must fragment back to the www site you are trying to load. (Alternatively, the router is sending the ICMP packet correctly, but the firewall at the www site is dropping it.) When the www server is sending you frames that do not fit into the PPPoE pipe the Telco router drops them on the floor and your page does not load (some pages/graphics do as they are smaller than a MSS.) This seems to be the default of most Telco PPPoE configurations (if only they knew how to program a router... sigh...) One fix is to use regedit on your 95/98 boxes to add the following registry entry... HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Class\NetTrans\0000\MaxMTU It should be a string with a value 1436, as some ADSL routers are reported to be unable to deal with packets larger than this. This registry key has been changed to Tcpip\Parameters\Interfaces\ID for adapter\MTU in &windows; 2000 and becomes a DWORD. Refer to the Microsoft Knowledge Base documents Q158474 - Windows TCPIP Registry Entries and Q120642 - TCPIP & NBT Configuration Parameters for &windowsnt; for more information on changing &windows; MTU to work with a NAT router. Another regedit possibility under &windows; 2000 is to set the Tcpip\Parameters\Interfaces\ID for adapter\EnablePMTUBHDetect DWORD to 1 as mentioned in the Microsoft document 120642 mentioned above. Unfortunately, &macos; does not provide an interface for changing TCP/IP settings. However, there is commercial software available, such as OTAdvancedTuner (OT for OpenTransport, the &macos; TCP/IP stack) by Sustainable Softworks, + url="http://www.softworks.com/">Sustainable Softworks, that will allow users to customize TCP/IP settings. &macos; NAT users should select ip_interface_MTU from the drop-down menu, enter 1450 instead of 1500 in the box, click the box next to Save as Auto Configure, and click Make Active. The latest version of &man.ppp.8; (2.3 or greater) has an enable tcpmssfixup command that will automatically adjust the MSS to an appropriate value. This facility is enabled by default. If you are stuck with an older version of &man.ppp.8;, you may want to look at the tcpmssd port. None of this helps - I am desperate! What can I do? If all else fails, send as much information as you can, including your config files, how you are starting &man.ppp.8;, the relevant parts of your log file and the output of the netstat -rn command (before and after connecting) to the &a.questions; or - the + the comp.unix.bsd.freebsd.misc news group, and someone should point you in the right direction. Serial Communications This section answers common questions about serial communications with FreeBSD. PPP and SLIP are covered in the Networking section. How do I tell if FreeBSD found my serial ports? As the FreeBSD kernel boots, it will probe for the serial ports in your system for which the kernel was configured. You can either watch your system closely for the messages it prints or run the command &prompt.user; dmesg | grep sio after your system is up and running. Here is some example output from the above command: sio0 at 0x3f8-0x3ff irq 4 on isa sio0: type 16550A sio1 at 0x2f8-0x2ff irq 3 on isa sio1: type 16550A This shows two serial ports. The first is on irq 4, is using port address 0x3f8, and has a 16550A-type UART chip. The second uses the same kind of chip but is on irq 3 and is at port address 0x2f8. Internal modem cards are treated just like serial ports---except that they always have a modem attached to the port. The GENERIC kernel includes support for two serial ports using the same irq and port address settings in the above example. If these settings are not right for your system, or if you have added modem cards or have more serial ports than your kernel is configured for, just reconfigure your kernel. See section about building a kernel for more details. How do I tell if FreeBSD found my modem cards? Refer to the answer to the previous question. How do I access the serial ports on FreeBSD? The third serial port, sio2 (see &man.sio.4;, known as COM3 in DOS), is on /dev/cuaa2 for dial-out devices, and on /dev/ttyd2 for dial-in devices. What is the difference between these two classes of devices? You use ttydX for dial-ins. When opening /dev/ttydX in blocking mode, a process will wait for the corresponding cuaaX device to become inactive, and then wait for the carrier detect line to go active. When you open the cuaaX device, it makes sure the serial port is not already in use by the ttydX device. If the port is available, it steals it from the ttydX device. Also, the cuaaX device does not care about carrier detect. With this scheme and an auto-answer modem, you can have remote users log in and you can still dial out with the same modem and the system will take care of all the conflicts. How do I enable support for a multiport serial card? Again, the section on kernel configuration provides information about configuring your kernel. For a multiport serial card, place an &man.sio.4; line for each serial port on the card in the kernel configuration file. But place the irq and vector specifiers on only one of the entries. All of the ports on the card should share one irq. For consistency, use the last serial port to specify the irq. Also, specify the COM_MULTIPORT option. The following example is for an AST 4-port serial card on irq 7: options "COM_MULTIPORT" device sio4 at isa? port 0x2a0 tty flags 0x781 device sio5 at isa? port 0x2a8 tty flags 0x781 device sio6 at isa? port 0x2b0 tty flags 0x781 device sio7 at isa? port 0x2b8 tty flags 0x781 irq 7 vector siointr The flags indicate that the master port has minor number 7 (0x700), diagnostics enabled during probe (0x080), and all the ports share an irq (0x001). Can FreeBSD handle multiport serial cards sharing irqs? Not yet. You will have to use a different irq for each card. Can I set the default serial parameters for a port? The ttydX (or cuaaX) device is the regular device you will want to open for your applications. When a process opens the device, it will have a default set of terminal I/O settings. You can see these settings with the command &prompt.root; stty -a -f /dev/ttyd1 When you change the settings to this device, the settings are in effect until the device is closed. When it is reopened, it goes back to the default set. To make changes to the default set, you can open and adjust the settings of the initial state device. For example, to turn on CLOCAL mode, 8 bits, and XON/XOFF flow control by default for ttyd5, do: &prompt.root; stty -f /dev/ttyid5 clocal cs8 ixon ixoff A good place to do this is in /etc/rc.serial. Now, an application will have these settings by default when it opens ttyd5. It can still change these settings to its liking, though. You can also prevent certain settings from being changed by an application by making adjustments to the lock state device. For example, to lock the speed of ttyd5 to 57600 bps, do &prompt.root; stty -f /dev/ttyld5 57600 Now, an application that opens ttyd5 and tries to change the speed of the port will be stuck with 57600 bps. Naturally, you should make the initial state and lock state devices writable only by root. The &man.MAKEDEV.8; script does NOT do this when it creates the device entries. How can I enable dialup logins on my modem? So you want to become an Internet service provider, eh? First, you will need one or more modems that can auto-answer. Your modem will need to assert carrier-detect when it detects a carrier and not assert it all the time. It will need to hang up the phone and reset itself when the data terminal ready (DTR) line goes from on to off. It should probably use RTS/CTS flow control or no local flow control at all. Finally, it must use a constant speed between the computer and itself, but (to be nice to your callers) it should negotiate a speed between itself and the remote modem. For many Hayes command-set--compatible modems, this command will make these settings and store them in nonvolatile memory: AT &C1 &D3 &K3 &Q6 S0=1 &W See the section on sending AT commands below for information on how to make these settings without resorting to an &ms-dos; terminal program. Next, make an entry in /etc/ttys (see &man.ttys.5;) for the modem. This file lists all the ports on which the operating system will await logins. Add a line that looks something like this: ttyd1 "/usr/libexec/getty std.57600" dialup on insecure This line indicates that the second serial port (/dev/ttyd1) has a modem connected running at 57600 bps and no parity (std.57600, which comes from the file /etc/gettytab, see &man.gettytab.5;). The terminal type for this port is dialup. The port is on and is insecure---meaning root logins on the port are not allowed. For dialin ports like this one, use the ttydX entry. It is common practice to use dialup as the terminal type. Many users set up in their .profile or .login files a prompt for the actual terminal type if the starting type is dialup. The example shows the port as insecure. To become root on this port, you have to login as a regular user, then &man.su.1; to become root. If you use secure then root can login in directly. After making modifications to /etc/ttys, you need to send a hangup or HUP signal to the &man.init.8; process: &prompt.root; kill -HUP 1 This forces the &man.init.8; process to reread /etc/ttys. The init process will then start getty processes on all on ports. You can find out if logins are available for your port by typing &prompt.user; ps -ax | grep '[t]tyd1' You should see something like: 747 ?? I 0:00.04 /usr/libexec/getty std.57600 ttyd1 How can I connect a dumb terminal to my FreeBSD box? If you are using another computer as a terminal into your FreeBSD system, get a null modem cable to go between the two serial ports. If you are using an actual terminal, see its accompanying instructions. Then, modify /etc/ttys (see &man.ttys.5;), like above. For example, if you are hooking up a WYSE-50 terminal to the fifth serial port, use an entry like this: ttyd4 "/usr/libexec/getty std.38400" wyse50 on secure This example shows that the port on /dev/ttyd4 has a wyse50 terminal connected at 38400 bps with no parity (std.38400 from /etc/gettytab, see &man.gettytab.5;) and root logins are allowed (secure). Why can I not run tip or cu? On your system, the programs &man.tip.1; and &man.cu.1; are probably executable only by uucp and group dialer. You can use the group dialer to control who has access to your modem or remote systems. Just add yourself to group dialer. Alternatively, you can let everyone on your system run &man.tip.1; and &man.cu.1; by typing: &prompt.root; chmod 4511 /usr/bin/cu &prompt.root; chmod 4511 /usr/bin/tip My stock Hayes modem is not supported---what can I do? Actually, the manual page for &man.tip.1; is out of date. There is a generic Hayes dialer already built in. Just use at=hayes in your /etc/remote (see &man.remote.5;) file. The Hayes driver is not smart enough to recognize some of the advanced features of newer modems---messages like BUSY, NO DIALTONE, or CONNECT 115200 will just confuse it. You should turn those messages off when you use &man.tip.1; (using ATX0&W). Also, the dial timeout for &man.tip.1; is 60 seconds. Your modem should use something less, or else tip will think there is a communication problem. Try ATS7=45&W. Actually, as shipped &man.tip.1; does not yet support it fully. The solution is to edit the file tipconf.h in the directory /usr/src/usr.bin/tip/tip. Obviously you need the source distribution to do this. Edit the line #define HAYES 0 to #define HAYES 1. Then make and make install. Everything works nicely after that. How am I expected to enter these AT commands? Make what is called a direct entry in your /etc/remote file (see &man.remote.5;). For example, if your modem is hooked up to the first serial port, /dev/cuaa0, then put in the following line: cuaa0:dv=/dev/cuaa0:br#19200:pa=none Use the highest bps rate your modem supports in the br capability. Then, type tip cuaa0 (see &man.tip.1;) and you will be connected to your modem. If there is no /dev/cuaa0 on your system, do this: &prompt.root; cd /dev &prompt.root; sh MAKEDEV cuaa0 Or use cu as root with the following command: &prompt.root; cu -lline -sspeed with line being the serial port (e.g. /dev/cuaa0) and speed being the speed (e.g.57600). When you are done entering the AT commands hit ~. to exit. Why does the <@> sign for the pn capability not work? The <@> sign in the phone number capability tells tip to look in /etc/phones for a phone number. But the <@> sign is also a special character in capability files like /etc/remote. Escape it with a backslash: pn=\@ How can I dial a phone number on the command line? Put what is called a generic entry in your /etc/remote file (see &man.remote.5;). For example: tip115200|Dial any phone number at 115200 bps:\ :dv=/dev/cuaa0:br#115200:at=hayes:pa=none:du: tip57600|Dial any phone number at 57600 bps:\ :dv=/dev/cuaa0:br#57600:at=hayes:pa=none:du: Then you can do something like tip -115200 5551234. If you prefer &man.cu.1; over &man.tip.1;, use a generic cu entry: cu115200|Use cu to dial any number at 115200bps:\ :dv=/dev/cuaa1:br#57600:at=hayes:pa=none:du: and type cu 5551234 -s 115200. Do I have to type in the bps rate every time I do that? Put in an entry for tip1200 or cu1200, but go ahead and use whatever bps rate is appropriate with the br capability. &man.tip.1; thinks a good default is 1200 bps which is why it looks for a tip1200 entry. You do not have to use 1200 bps, though. How can I more easily access a number of hosts through a terminal server? Rather than waiting until you are connected and typing CONNECT host each time, use tip's cm capability. For example, these entries in /etc/remote (see &man.remote.5;): pain|pain.deep13.com|Forrester's machine:\ :cm=CONNECT pain\n:tc=deep13: muffin|muffin.deep13.com|Frank's machine:\ :cm=CONNECT muffin\n:tc=deep13: deep13:Gizmonics Institute terminal server:\ :dv=/dev/cuaa2:br#38400:at=hayes:du:pa=none:pn=5551234: will let you type tip pain or tip muffin to connect to the hosts pain or muffin; and tip deep13 to get to the terminal server. Can tip try more than one line for each site? This is often a problem where a university has several modem lines and several thousand students trying to use them... Make an entry for your university in /etc/remote (see &man.remote.5;) and use <\@> for the pn capability: big-university:\ :pn=\@:tc=dialout dialout:\ :dv=/dev/cuaa3:br#9600:at=courier:du:pa=none: Then, list the phone numbers for the university in /etc/phones (see &man.phones.5;): big-university 5551111 big-university 5551112 big-university 5551113 big-university 5551114 &man.tip.1; will try each one in the listed order, then give up. If you want to keep retrying, run &man.tip.1; in a while loop. Why do I have to hit CTRLP twice to send CTRLP once? CTRLP is the default force character, used to tell &man.tip.1; that the next character is literal data. You can set the force character to any other character with the ~s escape, which means set a variable. Type ~sforce=single-char followed by a newline. single-char is any single character. If you leave out single-char, then the force character is the nul character, which you can get by typing CTRL2 or CTRLSPACE. A pretty good value for single-char is SHIFTCTRL6, which I have seen only used on some terminal servers. You can have the force character be whatever you want by specifying the following in your $HOME/.tiprc file: force=single-char Why is everything I type suddenly in UPPER CASE? You must have pressed CTRLA, &man.tip.1; raise character, specially designed for people with broken Caps Lock keys. Use ~s as above and set the variable raisechar to something reasonable. In fact, you can set it to the same as the force character, if you never expect to use either of these features. Here is a sample .tiprc file perfect for Emacs users who need to type CTRL2 and CTRLA a lot: force=^^ raisechar=^^ The ^^ is SHIFTCTRL6. How can I do file transfers with tip? If you are talking to another &unix; system, you can send and receive files with ~p (put) and ~t (take). These commands run &man.cat.1; and &man.echo.1; on the remote system to accept and send files. The syntax is: ~p <local-file> [<remote-file>] ~t <remote-file> [<local-file>] There is no error checking, so you probably should use another protocol, like zmodem. How can I run zmodem with tip? First, install one of the zmodem programs from the ports collection (such as one of the two from the comms category, lrzsz or rzsz. To receive files, start the sending program on the remote end. Then, press enter and type ~C rz (or ~C lrz if you installed lrzsz) to begin receiving them locally. To send files, start the receiving program on the remote end. Then, press enter and type ~C sz files (or ~C lsz files) to send them to the remote system. Miscellaneous Questions FreeBSD uses far more swap space than &linux;. Why? FreeBSD only appears to use more swap than &linux;. In actual fact, it does not. The main difference between FreeBSD and &linux; in this regard is that FreeBSD will proactively move entirely idle, unused pages of main memory into swap in order to make more main memory available for active use. &linux; tends to only move pages to swap as a last resort. The perceived heavier use of swap is balanced by the more efficient use of main memory. Note that while FreeBSD is proactive in this regard, it does not arbitrarily decide to swap pages when the system is truly idle. Thus you will not find your system all paged out when you get up in the morning after leaving it idle overnight. Why does top show very little free memory even when I have very few programs running? The simple answer is that free memory is wasted memory. Any memory that your programs do not actively allocate is used within the FreeBSD kernel as disk cache. The values shown by &man.top.1; labeled as Inact, Cache, and Buf are all cached data at different aging levels. This cached data means the system does not have to access a slow disk again for data it has accessed recently, thus increasing overall performance. In general, a low value shown for Free memory in &man.top.1; is good, provided it is not very low. Why will chmod not change the permissions on symlinks? Symlinks do not have permissions, and by default, &man.chmod.1; will not follow symlinks to change the permissions on the target file. So if you have a file, foo, and a symlink to that file, bar, then this command will always succeed. &prompt.user; chmod g-w bar However, the permissions on foo will not have changed. You have to use either or together with the option to make this work. See the &man.chmod.1; and &man.symlink.7; manual pages for more info. The option does a RECURSIVE &man.chmod.1;. Be careful about specifying directories or symlinks to directories to &man.chmod.1;. If you want to change the permissions of a directory referenced by a symlink, use &man.chmod.1; without any options and follow the symlink with a trailing slash (/). For example, if foo is a symlink to directory bar, and you want to change the permissions of foo (actually bar), you would do something like: &prompt.user; chmod 555 foo/ With the trailing slash, &man.chmod.1; will follow the symlink, foo, to change the permissions of the directory, bar. Can I run DOS binaries under FreeBSD? Yes, you can use the integrated doscmd DOS emulation program to run a subset of DOS commands. If doscmd will not suffice, the add-on utility emulators/pcemu emulates an 8088 and enough BIOS services to run many DOS text mode applications. It requires the X Window System. What do I need to do to translate a FreeBSD document into my native language? See the Translation FAQ in the FreeBSD Documentation Project Primer. Why does my email to any address at FreeBSD.org bounce? The FreeBSD.org mail system implements some of the stricter Postfix checks on incoming mail and rejects mail that is either misconfigured or is potential spam. Your mail might bounce for one of the following reasons: The email is being sent from a known spam domain or IP block. The FreeBSD mail servers reject email from known spam sources. If you have service through a company or domain who generates or relays spam, please switch to a service provider who does not. The body of the email only contains HTML. Mail should be sent in plain text only. Please configure your mail user agent to send plain text. The mailer at FreeBSD.org cannot resolve the IP address of the connecting host back to a symbolic name. Working reverse DNS is a standard requirement for accepting mail from a host. Set up reverse DNS for your mail server's IP address. Many home services (DSL, cable, dialup, etc.) will not give you this option. In this case, relay your email through your service provider's mail server. The hostname given in the EHLO/HELO part of the SMTP exchange cannot be resolved to an IP address. A fully qualified, resolvable host name is necessary in this part of the SMTP dialogue before mail will be accepted. If you do not have a host name that is registered in the DNS, then you should use your service provider's mail server to relay your mail. Your message had a message ID ending with the string localhost. Some mail user agents generate bad message IDs which will not be accepted. You will need to persuade your mail user agent to generate a valid message ID or else configure your mail transfer agent to rewrite them. Where can I find a free FreeBSD account? While FreeBSD does not provide open access to any of their servers, others do provide open access &unix; systems. The charge varies and limited services may be available. - Arbornet, + Arbornet, Inc, also known as M-Net, has been providing open access to &unix; systems since 1983. Starting on an Altos running System III, the site switched to BSD/OS in 1991. In June of 2000, the site switched again to FreeBSD. M-Net can be accessed via telnet and SSH and provides basic access to the entire FreeBSD software suite. However, network access is limited to members and patrons who donate to the system, which is run as a non-profit organization. M-Net also provides an bulletin board system and interactive chat. - Grex provides a + Grex provides a site very similar to M-Net including the same bulletin board and interactive chat software. However, the machine is a &sun; 4M and is running &sunos;. What is sup, and how do I use it? - + SUP stands for Software Update Protocol, and was developed by CMU for keeping their development trees in sync. We used it to keep remote sites in sync with our central development sources. SUP is not bandwidth friendly, and has been retired. The current recommended method to keep your sources up to - date is + date is CVSup What is the cute little red guy's name? He does not have one, and is just called the BSD daemon. If you insist upon using a name, call him beastie. Note that beastie is pronounced BSD. You can learn more about the BSD daemon on his home page. Can I use the BSD daemon image? Perhaps. The BSD daemon is copyrighted by Marshall Kirk McKusick. You will want to check his Statement on the Use of the BSD Daemon Figure for detailed usage terms. In summary, you are free to use the image in a tasteful manner, for personal use, so long as appropriate credit is given. If you want to use him commercially, you must contact Kirk McKusick. More details are available on the BSD Daemon's home page. Do you have any BSD daemon images I could use? You will find eps and Xfig drawings under /usr/share/examples/BSD_daemon/. What does MFC mean? MFC is an acronym for Merged From -CURRENT. It is used in the CVS logs to denote when a change was migrated from the CURRENT to the STABLE branches. What does BSD mean? It stands for something in a secret language that only members can know. It does not translate literally but it is ok to tell you that BSD's translation is something between, Formula-1 Racing Team, Penguins are tasty snacks, and We have a better sense of humor than &linux;. :-) Seriously, BSD is an acronym for Berkeley Software Distribution, which is the name the Berkeley CSRG (Computer Systems Research Group) chose for their &unix; distribution way back when. What does POLA mean? Principle of Least Astonishment. It means that as FreeBSD evolves, changes visible to the user should be kept as unsurprising as possible. For example, arbitrarily rearranging system startup variables in /etc/defaults/rc.conf violates POLA. Developers consider POLA when contemplating user-visible system changes. What is a repo-copy? A repo-copy (which is a short form of repository copy) refers to the direct copying of files within the CVS repository. Without a repo-copy, if a file needed to be copied or moved to another place in the repository, the committer would run cvs add to put the file in its new location, and then cvs rm on the old file if the old copy was being removed. The disadvantage of this method is that the history (i.e. the entries in the CVS logs) of the file would not be copied to the new location. As the FreeBSD Project considers this history very useful, a repository copy is often used instead. This is a process where one of the repository meisters will copy the files directly within the repository, rather than using the &man.cvs.1; program. Why should I care what color the bikeshed is? The really, really short answer is that you should not. The somewhat longer answer is that just because you are capable of building a bikeshed does not mean you should stop others from building one just because you do not like the color they plan to paint it. This is a metaphor indicating that you need not argue about every little feature just because you know enough to do so. Some people have commented that the amount of noise generated by a change is inversely proportional to the complexity of the change. The longer and more complete answer is that after a very long argument about whether &man.sleep.1; should take fractional second arguments, &a.phk; posted a long message entitled A bike shed (any colour will do) on greener grass.... The appropriate portions of that message are quoted below.
&a.phk; on freebsd-hackers, October 2, 1999 What is it about this bike shed? Some of you have asked me. It is a long story, or rather it is an old story, but it is quite short actually. C. Northcote Parkinson wrote a book in the early 1960s, called Parkinson's Law, which contains a lot of insight into the dynamics of management. [snip a bit of commentary on the book] In the specific example involving the bike shed, the other vital component is an atomic power-plant, I guess that illustrates the age of the book. Parkinson shows how you can go into the board of directors and get approval for building a multi-million or even billion dollar atomic power plant, but if you want to build a bike shed you will be tangled up in endless discussions. Parkinson explains that this is because an atomic plant is so vast, so expensive and so complicated that people cannot grasp it, and rather than try, they fall back on the assumption that somebody else checked all the details before it got this far. Richard P. Feynmann gives a couple of interesting, and very much to the point, examples relating to Los Alamos in his books. A bike shed on the other hand. Anyone can build one of those over a weekend, and still have time to watch the game on TV. So no matter how well prepared, no matter how reasonable you are with your proposal, somebody will seize the chance to show that he is doing his job, that he is paying attention, that he is here. In Denmark we call it setting your fingerprint. It is about personal pride and prestige, it is about being able to point somewhere and say There! I did that. It is a strong trait in politicians, but present in most people given the chance. Just think about footsteps in wet cement.
The FreeBSD Funnies How cool is FreeBSD? Q. Has anyone done any temperature testing while running FreeBSD? I know &linux; runs cooler than DOS, but have never seen a mention of FreeBSD. It seems to run really hot. A. No, but we have done numerous taste tests on blindfolded volunteers who have also had 250 micrograms of LSD-25 administered beforehand. 35% of the volunteers said that FreeBSD tasted sort of orange, whereas &linux; tasted like purple haze. Neither group mentioned any significant variances in temperature. We eventually had to throw the results of this survey out entirely anyway when we found that too many volunteers were wandering out of the room during the tests, thus skewing the results. We think most of the volunteers are at Apple now, working on their new scratch and sniff GUI. It is a funny old business we are in! Seriously, both FreeBSD and &linux; use the HLT (halt) instruction when the system is idle thus lowering its energy consumption and therefore the heat it generates. Also if you have APM (advanced power management) configured, then FreeBSD can also put the CPU into a low power mode. Who is scratching in my memory banks?? Q. Is there anything odd that FreeBSD does when compiling the kernel which would cause the memory to make a scratchy sound? When compiling (and for a brief moment after recognizing the floppy drive upon startup, as well), a strange scratchy sound emanates from what appears to be the memory banks. A. Yes! You will see frequent references to daemons in the BSD documentation, and what most people do not know is that this refers to genuine, non-corporeal entities that now possess your computer. The scratchy sound coming from your memory is actually high-pitched whispering exchanged among the daemons as they best decide how to deal with various system administration tasks. If the noise gets to you, a good fdisk /mbr from DOS will get rid of them, but do not be surprised if they react adversely and try to stop you. In fact, if at any point during the exercise you hear the satanic voice of Bill Gates coming from the built-in speaker, take off running and do not ever look back! Freed from the counterbalancing influence of the BSD daemons, the twin demons of DOS and &windows; are often able to re-assert total control over your machine to the eternal damnation of your soul. Now that you know, given a choice you would probably prefer to get used to the scratchy noises, no? How many FreeBSD hackers does it take to change a lightbulb? One thousand, one hundred and sixty-nine: Twenty-three to complain to -CURRENT about the lights being out; Four to claim that it is a configuration problem, and that such matters really belong on -questions; Three to submit PRs about it, one of which is misfiled under doc and consists only of it's dark; One to commit an untested lightbulb which breaks buildworld, then back it out five minutes later; Eight to flame the PR originators for not including patches in their PRs; Five to complain about buildworld being broken; Thirty-one to answer that it works for them, and they must have cvsupped at a bad time; One to post a patch for a new lightbulb to -hackers; One to complain that he had patches for this three years ago, but when he sent them to -CURRENT they were just ignored, and he has had bad experiences with the PR system; besides, the proposed new lightbulb is non-reflexive; Thirty-seven to scream that lightbulbs do not belong in the base system, that committers have no right to do things like this without consulting the Community, and WHAT IS -CORE DOING ABOUT IT!? Two hundred to complain about the color of the bicycle shed; Three to point out that the patch breaks &man.style.9;; Seventeen to complain that the proposed new lightbulb is under GPL; Five hundred and eighty-six to engage in a flame war about the comparative advantages of the GPL, the BSD license, the MIT license, the NPL, and the personal hygiene of unnamed FSF founders; Seven to move various portions of the thread to -chat and -advocacy; One to commit the suggested lightbulb, even though it shines dimmer than the old one; Two to back it out with a furious flame of a commit message, arguing that FreeBSD is better off in the dark than with a dim lightbulb; Forty-six to argue vociferously about the backing out of the dim lightbulb and demanding a statement from -core; Eleven to request a smaller lightbulb so it will fit their Tamagotchi if we ever decide to port FreeBSD to that platform; Seventy-three to complain about the SNR on -hackers and -chat and unsubscribe in protest; Thirteen to post unsubscribe, How do I unsubscribe?, or Please remove me from the list, followed by the usual footer; One to commit a working lightbulb while everybody is too busy flaming everybody else to notice; Thirty-one to point out that the new lightbulb would shine 0.364% brighter if compiled with TenDRA (although it will have to be reshaped into a cube), and that FreeBSD should therefore switch to TenDRA instead of GCC; One to complain that the new lightbulb lacks fairings; Nine (including the PR originators) to ask what is MFC?; Fifty-seven to complain about the lights being out two weeks after the bulb has been changed. &a.nik; adds: I was laughing quite hard at this. And then I thought, Hang on, shouldn't there be '1 to document it.' in that list somewhere? And then I was enlightened :-) Where does data written to /dev/null go? It goes into a special data sink in the CPU where it is converted to heat which is vented through the heatsink / fan assembly. This is why CPU cooling is increasingly important; as people get used to faster processors, they become careless with their data and more and more of it ends up in /dev/null, overheating their CPUs. If you delete /dev/null (which effectively disables the CPU data sink) your CPU may run cooler but your system will quickly become constipated with all that excess data and start to behave erratically. If you have a fast network connection you can cool down your CPU by reading data out of /dev/random and sending it off somewhere; however you run the risk of overheating your network connection and / or angering your ISP, as most of the data will end up getting converted to heat by their equipment, but they generally have good cooling, so if you do not overdo it you should be OK. Paul Robinson adds: There are other methods. As every good sysadmin knows, it is part of standard practise to send data to the screen of interesting variety to keep all the pixies that make up your picture happy. Screen pixies (commonly mis-typed or re-named as 'pixels') are categorised by the type of hat they wear (red, green or blue) and will hide or appear (thereby showing the colour of their hat) whenever they receive a little piece of food. Video cards turn data into pixie-food, and then send them to the pixies - the more expensive the card, the better the food, so the better behaved the pixies are. They also need constant stimulation - this is why screen savers exist. To take your suggestions further, you could just throw the random data to console, thereby letting the pixies consume it. This causes no heat to be produced at all, keeps the pixies happy and gets rid of your data quite quickly, even if it does make things look a bit messy on your screen. Incidentally, as an ex-admin of a large ISP who experienced many problems attempting to maintain a stable temperature in a server room, I would strongly discourage people sending the data they do not want out to the network. The fairies who do the packet switching and routing get annoyed by it as well. Advanced Topics How can I learn more about FreeBSD's internals? At this time, there is no book on FreeBSD-specific OS internals. Much general &unix; knowledge is directly applicable to FreeBSD, however. Additionally, there are BSD-specific books that are still relevant. For a list, please check the Handbook's Operating + url="&url.books.handbook;/bibliography-osinternals.html">Operating System Internals Bibliography. How can I contribute to FreeBSD? Please see the article on Contributing to FreeBSD for specific advice on how to do this. Assistance is more than welcome! What are SNAPs and RELEASEs? There are currently three active/semi-active branches in the FreeBSD CVS + url="http://www.FreeBSD.org/cgi/cvsweb.cgi"> CVS Repository. (Earlier branches are only changed very rarely, which is why there are only three active branches of development): RELENG_3 AKA 3.X-STABLE RELENG_4 AKA 4-STABLE HEAD AKA -CURRENT AKA 5.X-CURRENT HEAD is not an actual branch tag, like the other two; it is simply a symbolic constant for the current, non-branched development stream which we simply refer to as -CURRENT. Right now, -CURRENT is the 5.X development stream and the 4-STABLE branch, RELENG_4, forked off from -CURRENT in Mar 2000. How do I make my own custom release? Please see the Release Engineering article. Why does make world clobber my existing installed binaries? Yes, this is the general idea; as its name might suggest, make world rebuilds every system binary from scratch, so you can be certain of having a clean and consistent environment at the end (which is why it takes so long). If the environment variable DESTDIR is defined while running make world or make install, the newly-created binaries will be deposited in a directory tree identical to the installed one, rooted at ${DESTDIR}. Some random combination of shared libraries modifications and program rebuilds can cause this to fail in make world however. Why isn't cvsup.FreeBSD.org a round robin DNS entry to share the load amongst the various CVSup servers? While CVSup mirrors update from the master CVSup server hourly, this update might happen at any time during the hour. This means that some servers have newer code than others, even though all servers have code that is less than an hour old. If cvsup.FreeBSD.org was a round robin DNS entry that simply redirected users to a random CVSup server, running CVSup twice in a row could download code older than the code already on the system. Why does my system say (bus speed defaulted) when it boots? The Adaptec 1542 SCSI host adapters allow the user to configure their bus access speed in software. Previous versions of the 1542 driver tried to determine the fastest usable speed and set the adapter to that. We found that this breaks some users' systems, so you now have to define the TUNE_1542 kernel configuration option in order to have this take place. Using it on those systems where it works may make your disks run faster, but on those systems where it does not, your data could be corrupted. Can I follow -CURRENT with limited Internet access? Yes, you can do this without downloading the whole source tree by using the CTM facility. + url="&url.books.handbook;/synching.html#CTM">CTM facility. How did you split the distribution into 240k files? Newer BSD based systems have a option to &man.split.1; that allows them to split files on arbitrary byte boundaries. Here is an example from /usr/src/Makefile. bin-tarball: (cd ${DISTDIR}; \ tar cf - . \ gzip --no-name -9 -c | \ split -b 240640 - \ ${RELEASEDIR}/tarballs/bindist/bin_tgz.) I have written a kernel extension, who do I send it to? Please take a look at the article on Contributing + url="&url.articles.contributing;/article.html">Contributing to FreeBSD to learn how to submit code. And thanks for the thought! How are Plug N Play ISA cards detected and initialized? By: Frank Durda IV uhclem@nemesis.lonestar.org In a nutshell, there a few I/O ports that all of the PnP boards respond to when the host asks if anyone is out there. So when the PnP probe routine starts, it asks if there are any PnP boards present, and all the PnP boards respond with their model # to a I/O read of the same port, so the probe routine gets a wired-OR yes to that question. At least one bit will be on in that reply. Then the probe code is able to cause boards with board model IDs (assigned by Microsoft/Intel) lower than X to go off-line. It then looks to see if any boards are still responding to the query. If the answer was 0, then there are no boards with IDs above X. Now probe asks if there are any boards below X. If so, probe knows there are boards with a model numbers below X. Probe then asks for boards greater than X-(limit/4) to go off-line. If repeats the query. By repeating this semi-binary search of IDs-in-range enough times, the probing code will eventually identify all PnP boards present in a given machine with a number of iterations that is much lower than what 2^64 would take. The IDs are two 32-bit fields (hence 2ˆ64) + 8 bit checksum. The first 32 bits are a vendor identifier. They never come out and say it, but it appears to be assumed that different types of boards from the same vendor could have different 32-bit vendor ids. The idea of needing 32 bits just for unique manufacturers is a bit excessive. The lower 32 bits are a serial #, Ethernet address, something that makes this one board unique. The vendor must never produce a second board that has the same lower 32 bits unless the upper 32 bits are also different. So you can have multiple boards of the same type in the machine and the full 64 bits will still be unique. The 32 bit groups can never be all zero. This allows the wired-OR to show non-zero bits during the initial binary search. Once the system has identified all the board IDs present, it will reactivate each board, one at a time (via the same I/O ports), and find out what resources the given board needs, what interrupt choices are available, etc. A scan is made over all the boards to collect this information. This info is then combined with info from any ECU files on the hard disk or wired into the MLB BIOS. The ECU and BIOS PnP support for hardware on the MLB is usually synthetic, and the peripherals do not really do genuine PnP. However by examining the BIOS info plus the ECU info, the probe routines can cause the devices that are PnP to avoid those devices the probe code cannot relocate. Then the PnP devices are visited once more and given their I/O, DMA, IRQ and Memory-map address assignments. The devices will then appear at those locations and remain there until the next reboot, although there is nothing that says you cannot move them around whenever you want. There is a lot of oversimplification above, but you should get the general idea. Microsoft took over some of the primary printer status ports to do PnP, on the logic that no boards decoded those addresses for the opposing I/O cycles. I found a genuine IBM printer board that did decode writes of the status port during the early PnP proposal review period, but MS said tough. So they do a write to the printer status port for setting addresses, plus that use that address + 0x800, and a third I/O port for reading that can be located anywhere between 0x200 and 0x3ff. Can you assign a major number for a device driver I have written? &os.current; after February 2003 has a facility for dynamically and automatically allocating major numbers for device drivers at runtime. This mechanism is highly preferred to the older procedure of statically allocating device numbers. Some comments on this subject can be found in src/sys/conf/majors. If you are forced for some reason to use a static major number, the procedure for obtaining one depends on whether or not you plan on making the driver publicly available. If you do, then please send us a copy of the driver source code, plus the appropriate modifications to files.i386, a sample configuration file entry, and the appropriate &man.MAKEDEV.8; code to create any special files your device uses. If you do not, or are unable to because of licensing restrictions, then character major number 32 and block major number 8 have been reserved specifically for this purpose; please use them. In any case, we would appreciate hearing about your driver on the &a.hackers;. What about alternative layout policies for directories? In answer to the question of alternative layout policies for directories, the scheme that is currently in use is unchanged from what I wrote in 1983. I wrote that policy for the original fast filesystem, and never revisited it. It works well at keeping cylinder groups from filling up. As several of you have noted, it works poorly for find. Most filesystems are created from archives that were created by a depth first search (aka ftw). These directories end up being striped across the cylinder groups thus creating a worst possible scenario for future depth first searches. If one knew the total number of directories to be created, the solution would be to create (total / fs_ncg) per cylinder group before moving on. Obviously, one would have to create some heuristic to guess at this number. Even using a small fixed number like say 10 would make an order of magnitude improvement. To differentiate restores from normal operation (when the current algorithm is probably more sensible), you could use the clustering of up to 10 if they were all done within a ten second window. Anyway, my conclusion is that this is an area ripe for experimentation. Kirk McKusick, September 1998 How can I make the most of the data I see when my kernel panics? [This section was extracted from a mail written by &a.wpaul; on the freebsd-current mailing list by &a.des;, who fixed a few typos and added the bracketed comments] From: Bill Paul <wpaul@skynet.ctr.columbia.edu> Subject: Re: the fs fun never stops To: Ben Rosengart Date: Sun, 20 Sep 1998 15:22:50 -0400 (EDT) Cc: current@FreeBSD.org Ben Rosengart posted the following panic message] > Fatal trap 12: page fault while in kernel mode > fault virtual address = 0x40 > fault code = supervisor read, page not present > instruction pointer = 0x8:0xf014a7e5 ^^^^^^^^^^ > stack pointer = 0x10:0xf4ed6f24 > frame pointer = 0x10:0xf4ed6f28 > code segment = base 0x0, limit 0xfffff, type 0x1b > = DPL 0, pres 1, def32 1, gran 1 > processor eflags = interrupt enabled, resume, IOPL = 0 > current process = 80 (mount) > interrupt mask = > trap number = 12 > panic: page fault [When] you see a message like this, it is not enough to just reproduce it and send it in. The instruction pointer value that I highlighted up there is important; unfortunately, it is also configuration dependent. In other words, the value varies depending on the exact kernel image that you are using. If you are using a GENERIC kernel image from one of the snapshots, then it is possible for somebody else to track down the offending function, but if you are running a custom kernel then only you can tell us where the fault occurred. What you should do is this: Write down the instruction pointer value. Note that the 0x8: part at the beginning is not significant in this case: it is the 0xf0xxxxxx part that we want. When the system reboots, do the following: &prompt.user; nm -n /kernel.that.caused.the.panic | grep f0xxxxxx where f0xxxxxx is the instruction pointer value. The odds are you will not get an exact match since the symbols in the kernel symbol table are for the entry points of functions and the instruction pointer address will be somewhere inside a function, not at the start. If you do not get an exact match, omit the last digit from the instruction pointer value and try again, i.e.: &prompt.user; nm -n /kernel.that.caused.the.panic | grep f0xxxxx If that does not yield any results, chop off another digit. Repeat until you get some sort of output. The result will be a possible list of functions which caused the panic. This is a less than exact mechanism for tracking down the point of failure, but it is better than nothing. I see people constantly show panic messages like this but rarely do I see someone take the time to match up the instruction pointer with a function in the kernel symbol table. The best way to track down the cause of a panic is by capturing a crash dump, then using &man.gdb.1; to generate a stack trace on the crash dump. In any case, the method I normally use is this: Set up a kernel config file, optionally adding options DDB if you think you need the kernel debugger for something. (I use this mainly for setting breakpoints if I suspect an infinite loop condition of some kind.) Use config -g KERNELCONFIG to set up the build directory. cd /sys/compile/ KERNELCONFIG; make Wait for kernel to finish compiling. make install reboot The &man.make.1; process will have built two kernels. kernel and kernel.debug. kernel was installed as /kernel, while kernel.debug can be used as the source of debugging symbols for &man.gdb.1;. To make sure you capture a crash dump, you need edit /etc/rc.conf and set dumpdev to point to your swap partition. This will cause the &man.rc.8; scripts to use the &man.dumpon.8; command to enable crash dumps. You can also run &man.dumpon.8; manually. After a panic, the crash dump can be recovered using &man.savecore.8;; if dumpdev is set in /etc/rc.conf, the &man.rc.8; scripts will run &man.savecore.8; automatically and put the crash dump in /var/crash. FreeBSD crash dumps are usually the same size as the physical RAM size of your machine. That is, if you have 64MB of RAM, you will get a 64MB crash dump. Therefore you must make sure there is enough space in /var/crash to hold the dump. Alternatively, you run &man.savecore.8; manually and have it recover the crash dump to another directory where you have more room. It is possible to limit the size of the crash dump by using options MAXMEM=(foo) to set the amount of memory the kernel will use to something a little more sensible. For example, if you have 128MB of RAM, you can limit the kernel's memory usage to 16MB so that your crash dump size will be 16MB instead of 128MB. Once you have recovered the crash dump, you can get a stack trace with &man.gdb.1; as follows: &prompt.user; gdb -k /sys/compile/KERNELCONFIG/kernel.debug /var/crash/vmcore.0 (gdb) where Note that there may be several screens worth of information; ideally you should use &man.script.1; to capture all of them. Using the unstripped kernel image with all the debug symbols should show the exact line of kernel source code where the panic occurred. Usually you have to read the stack trace from the bottom up in order to trace the exact sequence of events that lead to the crash. You can also use &man.gdb.1; to print out the contents of various variables or structures in order to examine the system state at the time of the crash. Now, if you are really insane and have a second computer, you can also configure &man.gdb.1; to do remote debugging such that you can use &man.gdb.1; on one system to debug the kernel on another system, including setting breakpoints, single-stepping through the kernel code, just like you can do with a normal user-mode program. I have not played with this yet as I do not often have the chance to set up two machines side by side for debugging purposes. [Bill adds: "I forgot to mention one thing: if you have DDB enabled and the kernel drops into the debugger, you can force a panic (and a crash dump) just by typing 'panic' at the ddb prompt. It may stop in the debugger again during the panic phase. If it does, type 'continue' and it will finish the crash dump." -ed] Why has dlsym() stopped working for ELF executables? The ELF toolchain does not, by default, make the symbols defined in an executable visible to the dynamic linker. Consequently dlsym() searches on handles obtained from calls to dlopen(NULL, flags) will fail to find such symbols. If you want to search, using dlsym(), for symbols present in the main executable of a process, you need to link the executable using the option to the ELF linker (&man.ld.1;). How can I increase or reduce the kernel address space? By default, the kernel address space is 256 MB on FreeBSD 3.X and 1 GB on FreeBSD 4.X. If you run a network-intensive server (e.g. a large FTP or HTTP server), you might find that 256 MB is not enough. So how do you increase the address space? There are two aspects to this. First, you need to tell the kernel to reserve a larger portion of the address space for itself. Second, since the kernel is loaded at the top of the address space, you need to lower the load address so it does not bump its head against the ceiling. The first goal is achieved by increasing the value of NKPDE in src/sys/i386/include/pmap.h. Here is what it looks like for a 1 GB address space: #ifndef NKPDE #ifdef SMP #define NKPDE 254 /* addressable number of page tables/pde's */ #else #define NKPDE 255 /* addressable number of page tables/pde's */ #endif /* SMP */ #endif To find the correct value of NKPDE, divide the desired address space size (in megabytes) by four, then subtract one for UP and two for SMP. To achieve the second goal, you need to compute the correct load address: simply subtract the address space size (in bytes) from 0x100100000; the result is 0xc0100000 for a 1 GB address space. Set LOAD_ADDRESS in src/sys/i386/conf/Makefile.i386 to that value; then set the location counter in the beginning of the section listing in src/sys/i386/conf/kernel.script to the same value, as follows: OUTPUT_FORMAT("elf32-i386", "elf32-i386", "elf32-i386") OUTPUT_ARCH(i386) ENTRY(btext) SEARCH_DIR(/usr/lib); SEARCH_DIR(/usr/obj/elf/home/src/tmp/usr/i386-unknown-freebsdelf/lib); SECTIONS { /* Read-only sections, merged into text segment: */ . = 0xc0100000 + SIZEOF_HEADERS; .interp : { *(.interp) } Then reconfig and rebuild your kernel. You will probably have problems with &man.ps.1; &man.top.1; and the like; make world should take care of it (or a manual rebuild of libkvm, &man.ps.1; and &man.top.1; after copying the patched pmap.h to /usr/include/vm/. NOTE: the size of the kernel address space must be a multiple of four megabytes. [&a.dg; adds: I think the kernel address space needs to be a power of two, but I am not certain about that. The old(er) boot code used to monkey with the high order address bits and I think expected at least 256MB granularity.] Acknowledgments
FreeBSD Core Team If you see a problem with this FAQ, or wish to submit an entry, please mail the &a.doc;. We appreciate your feedback, and cannot make this a better FAQ without your help!
&a.jkh; Occasional fits of FAQ-reshuffling and updating. &a.dwhite; Services above and beyond the call of duty on freebsd-questions &a.joerg; Services above and beyond the call of duty on Usenet &a.wollman; Networking and formatting Jim Lowe Multicast information &a.pds; FreeBSD FAQ typing machine slavey The FreeBSD Team Kvetching, moaning, submitting data And to any others we have forgotten, apologies and heartfelt thanks! &bibliography; diff --git a/en_US.ISO8859-1/books/porters-handbook/book.sgml b/en_US.ISO8859-1/books/porters-handbook/book.sgml index 2f615e46f1..de58fe1a2e 100644 --- a/en_US.ISO8859-1/books/porters-handbook/book.sgml +++ b/en_US.ISO8859-1/books/porters-handbook/book.sgml @@ -1,8317 +1,8317 @@ %books.ent; ]> FreeBSD Porter's Handbook The FreeBSD Documentation Project April 2000 2000 2001 2002 2003 2004 The FreeBSD Documentation Project &bookinfo.trademarks; &bookinfo.legalnotice; Introduction The FreeBSD ports collection is the way almost everyone installs applications ("ports") on FreeBSD. Like everything else about FreeBSD, it is primarily a volunteer effort. It is important to keep this in mind when reading this document. In FreeBSD, anyone may submit a new port, or volunteer to maintain an existing port if it is unmaintained—you do not need any special commit privileges to do so. Making a port yourself So, you are interested in making your own port or upgrading an existing one? Great! What follows are some guidelines for creating a new port for FreeBSD. If you want to upgrade an existing port, you should read this and then read . When this document is not sufficiently detailed, you should refer to /usr/ports/Mk/bsd.port.mk, which all port Makefiles include. Even if you do not hack Makefiles daily, it is well commented, and you will still gain much knowledge from it. Additionally, you may send specific questions to the &a.ports;. Only a fraction of the variables (VAR) that can be overridden are mentioned in this document. Most (if not all) are documented at the start of /usr/ports/Mk/bsd.port.mk; the others probably ought to be. Note that this file uses a non-standard tab setting: Emacs and Vim should recognize the setting on loading the file. Both &man.vi.1; and &man.ex.1; can be set to use the correct value by typing :set tabstop=4 once the file has been loaded. Quick Porting This section tells you how to do a quick port. In many cases, it is not sufficient, so you will have to read further on into the document. First, get the original tarball and put it into DISTDIR, which defaults to /usr/ports/distfiles. The following assumes that the software compiled out-of-the-box, i.e., there was absolutely no change required for the port to work on your FreeBSD box. If you needed to change something, you will have to refer to the next section too. Writing the <filename>Makefile</filename> The minimal Makefile would look something like this: # New ports collection makefile for: oneko # Date created: 5 December 1994 # Whom: asami # # $FreeBSD$ # PORTNAME= oneko PORTVERSION= 1.1b CATEGORIES= games MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ MAINTAINER= asami@FreeBSD.org COMMENT= A cat chasing a mouse all over the screen MAN1= oneko.1 MANCOMPRESSED= yes USE_IMAKE= yes .include <bsd.port.mk> See if you can figure it out. Do not worry about the contents of the $FreeBSD$ line, it will be filled in automatically by CVS when the port is imported to our main ports tree. You can find a more detailed example in the sample Makefile section. Writing the description files There are two description files that are required for any port, whether they actually package or not. They are pkg-descr and pkg-plist. Their pkg- prefix distinguishes them from other files. <filename>pkg-descr</filename> This is a longer description of the port. One to a few paragraphs concisely explaining what the port does is sufficient. This is not a manual or an in-depth description on how to use or compile the port! Please be careful if you are copying from the README or manpage; too often they are not a concise description of the port or are in an awkward format (e.g., manpages have justified spacing). If the ported software has an official WWW homepage, you should list it here. Prefix one of the websites with WWW: so that automated tools will work correctly. It is recommended that you sign your name at the end of this file, as in: This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (etc.) WWW: http://www.oneko.org/ - Satoshi asami@cs.berkeley.edu <filename>pkg-plist</filename> This file lists all the files installed by the port. It is also called the packing list because the package is generated by packing the files listed here. The pathnames are relative to the installation prefix (usually /usr/local or /usr/X11R6). If you are using the MANn variables (as you should be), do not list any manpages here. Here is a small example: bin/oneko lib/X11/app-defaults/Oneko lib/X11/oneko/cat1.xpm lib/X11/oneko/cat2.xpm lib/X11/oneko/mouse.xpm @dirrm lib/X11/oneko Refer to the &man.pkg.create.1; manual page for details on the packing list. You should list all the files, but not the name directories, in the list. Also, if the port creates directories for itself during installation, make sure to add @dirrm lines as necessary to remove them when the port is deleted. It is recommended that you keep all the filenames in this file sorted alphabetically. It will make verifying the changes when you upgrade the port much easier. Creating a packing list manually can be a very tedious task. If the port installs a large numbers of files, creating the packing list automatically might save time. There is only one case when pkg-plist can be omitted from a port. If the port installs just a handful of files, and perhaps directories, the files and directories may be listed in the variables PLIST_FILES and PLIST_DIRS, respectively, within the port's Makefile. For instance, we could get along without pkg-plist in the above oneko port by adding the following lines to the Makefile: PLIST_FILES= bin/oneko \ lib/X11/app-defaults/Oneko \ lib/X11/oneko/cat1.xpm \ lib/X11/oneko/cat2.xpm \ lib/X11/oneko/mouse.xpm PLIST_DIRS= lib/X11/oneko Of course, PLIST_DIRS should be left unset if a port installs no directories of its own. The price for this way of listing port's files and directories is that you cannot use command sequences described in &man.pkg.create.1;. Therefore, it is suitable only for simple ports and makes them even simpler. At the same time, it has the advantage of reducing the number of files in the ports collection. Please consider using this technique before you resort to pkg-plist. Later we will see how pkg-plist and PLIST_FILES can be used to fulfil more sophisticated tasks. Creating the checksum file Just type make makesum. The ports make rules will automatically generate the file distinfo. Testing the port You should make sure that the port rules do exactly what you want them to do, including packaging up the port. These are the important points you need to verify. pkg-plist does not contain anything not installed by your port pkg-plist contains everything that is installed by your port Your port can be installed multiple times using the reinstall target Your port cleans up after itself upon deinstall Recommended test ordering make install make package make deinstall pkg_add package-name make deinstall make reinstall make package Make sure that there are not any warnings issued in any of the package and deinstall stages. After step 3, check to see if all the new directories are correctly deleted. Also, try using the software after step 4, to ensure that it works correctly when installed from a package. Checking your port with <command>portlint</command> Please use portlint to see if your port conforms to our guidelines. The portlint program is part of the ports collection. In particular, you may want to check if the Makefile is in the right shape and the package is named appropriately. Submitting the port First, make sure you have read the DOs and DON'Ts section. Now that you are happy with your port, the only thing remaining is to put it in the main FreeBSD ports tree and make everybody else happy about it too. We do not need your work directory or the pkgname.tgz package, so delete them now. Next, simply include the output of shar `find port_dir` in a bug report and send it with the &man.send-pr.1; program (see Bug Reports and General Commentary for more information about &man.send-pr.1;). If the uncompressed port is larger than 20KB, you should compress it into a tarfile and use &man.uuencode.1; before including it in the bug report (uuencoded tarfiles are acceptable even if the bug report is smaller than 20KB but are not preferred). Be sure to classify the bug report as category ports and class change-request (Do not mark the report confidential!). Also add a short description of the program you ported to the Description field of the PR and the shar or uuencoded tarfile to the Fix field. You can make our work a lot easier, if you use a good description in the synopsis of the problem report. We prefer something like New port: <category>/<portname> <short description of the port> for new ports and Update port: <category>/<portname> <short description of the update> for port updates. If you stick to this scheme, the chance that someone will take a look at your PR soon is much better. One more time, do not include the original source distfile, the work directory, or the package you built with make package. After you have submitted your port, please be patient. Sometimes it can take a few months before a port is included in FreeBSD, although it might only take a few days. You can view the list of ports waiting to be committed to FreeBSD. Once we have looked at your port, we will get back to you if necessary, and put it in the tree. Your name will also appear in the list of Additional FreeBSD Contributors and other files. Isn't that great?!? :-) Slow Porting Ok, so it was not that simple, and the port required some modifications to get it to work. In this section, we will explain, step by step, how to modify it to get it to work with the ports paradigm. How things work First, this is the sequence of events which occurs when the user first types make in your port's directory. You may find that having bsd.port.mk in another window while you read this really helps to understand it. But do not worry if you do not really understand what bsd.port.mk is doing, not many people do... :-> The fetch target is run. The fetch target is responsible for making sure that the tarball exists locally in DISTDIR. If fetch cannot find the required files in DISTDIR it will look up the URL MASTER_SITES, which is set in the Makefile, as well as our main FTP site at , where we put sanctioned distfiles as backup. It will then attempt to fetch the named distribution file with FETCH, assuming that the requesting site has direct access to the Internet. If that succeeds, it will save the file in DISTDIR for future use and proceed. The extract target is run. It looks for your port's distribution file (typically a gzip'd tarball) in DISTDIR and unpacks it into a temporary subdirectory specified by WRKDIR (defaults to work). The patch target is run. First, any patches defined in PATCHFILES are applied. Second, if any patch files named patch-* are found in PATCHDIR (defaults to the files subdirectory), they are applied at this time in alphabetical order. The configure target is run. This can do any one of many different things. If it exists, scripts/configure is run. If HAS_CONFIGURE or GNU_CONFIGURE is set, WRKSRC/configure is run. If USE_IMAKE is set, XMKMF (default: xmkmf -a) is run. The build target is run. This is responsible for descending into the port's private working directory (WRKSRC) and building it. If USE_GMAKE is set, GNU make will be used, otherwise the system make will be used. The above are the default actions. In addition, you can define targets pre-something or post-something, or put scripts with those names, in the scripts subdirectory, and they will be run before or after the default actions are done. For example, if you have a post-extract target defined in your Makefile, and a file pre-build in the scripts subdirectory, the post-extract target will be called after the regular extraction actions, and the pre-build script will be executed before the default build rules are done. It is recommended that you use Makefile targets if the actions are simple enough, because it will be easier for someone to figure out what kind of non-default action the port requires. The default actions are done by the bsd.port.mk targets do-something. For example, the commands to extract a port are in the target do-extract. If you are not happy with the default target, you can fix it by redefining the do-something target in your Makefile. The main targets (e.g., extract, configure, etc.) do nothing more than make sure all the stages up to that one are completed and call the real targets or scripts, and they are not intended to be changed. If you want to fix the extraction, fix do-extract, but never ever change the way extract operates! Now that you understand what goes on when the user types make, let us go through the recommended steps to create the perfect port. Getting the original sources Get the original sources (normally) as a compressed tarball (foo.tar.gz or foo.tar.Z) and copy it into DISTDIR. Always use mainstream sources when and where you can. You will need to set the variable MASTER_SITES to reflect where the original tarball resides. You will find convenient shorthand definitions for most mainstream sites in bsd.sites.mk. Please use these sites—and the associated definitions—if at all possible, to help avoid the problem of having the same information repeated over again many times in the source base. As these sites tend to change over time, this becomes a maintenance nightmare for everyone involved. If you cannot find a FTP/HTTP site that is well-connected to the net, or can only find sites that have irritatingly non-standard formats, you might want to put a copy on a reliable FTP or HTTP server that you control (e.g., your home page). If you cannot find somewhere convenient and reliable to put the distfile we can house it ourselves on ftp.FreeBSD.org; however, this is the least-preferred solution. The distfile must be placed into ~/public_distfiles/ of someone's freefall account. Ask the person who commits your port to do this. This person will also set MASTER_SITES to MASTER_SITE_LOCAL and MASTER_SITE_SUBDIR to their freefall username. If your port's distfile changes all the time without any kind of version update by the author, consider putting the distfile on your home page and listing it as the first MASTER_SITES. If you can, try to talk the port author out of doing this; it really does help to establish some kind of source code control. Hosting your own version will prevent users from getting checksum mismatch errors, and also reduce the workload of maintainers of our FTP site. Also, if there is only one master site for the port, it is recommended that you house a backup at your site and list it as the second MASTER_SITES. If your port requires some additional `patches' that are available on the Internet, fetch them too and put them in DISTDIR. Do not worry if they come from a site other than where you got the main source tarball, we have a way to handle these situations (see the description of PATCHFILES below). Modifying the port Unpack a copy of the tarball in a private directory and make whatever changes are necessary to get the port to compile properly under the current version of FreeBSD. Keep careful track of everything you do, as you will be automating the process shortly. Everything, including the deletion, addition, or modification of files should be doable using an automated script or patch file when your port is finished. If your port requires significant user interaction/customization to compile or install, you should take a look at one of Larry Wall's classic Configure scripts and perhaps do something similar yourself. The goal of the new ports collection is to make each port as plug-and-play as possible for the end-user while using a minimum of disk space. Unless explicitly stated, patch files, scripts, and other files you have created and contributed to the FreeBSD ports collection are assumed to be covered by the standard BSD copyright conditions. Patching In the preparation of the port, files that have been added or changed can be picked up with a recursive &man.diff.1; for later feeding to &man.patch.1;. Each set of patches you wish to apply should be collected into a file named patch-* where * denotes the sequence in which the patches will be applied — these are done in alphabetical order, thus aa first, ab second and so on. If you wish, you can use names that indicate the pathnames of the files that are patched, such as patch-Imakefile or patch-src-config.h. These files should be stored in PATCHDIR, from where they will be automatically applied. All patches should be relative to WRKSRC (generally the directory your port's tarball unpacks itself into, that being where the build is done). To make fixes and upgrades easier, you should avoid having more than one patch fix the same file (e.g., patch-aa and patch-ab both changing WRKSRC/foobar.c). Do not put RCS strings in patches. CVS will mangle them when we put the files into the ports tree, and when we check them out again, they will come out different and the patch will fail. RCS strings are surrounded by dollar ($) signs, and typically start with $Id or $RCS. Using the recurse () option to &man.diff.1; to generate patches is fine, but please take a look at the resulting patches to make sure you do not have any unnecessary junk in there. In particular, diffs between two backup files, Makefiles when the port uses Imake or GNU configure, etc., are unnecessary and should be deleted. If you had to edit configure.in and run autoconf to regenerate configure, do not take the diffs of configure (it often grows to a few thousand lines!); define USE_AUTOCONF_VER=213 and take the diffs of configure.in. Quite often, there is a situation when the software being ported, especially if it is primarily developed on &windows;, uses the CR/LF convention for most of its source files. This may cause problems with further patching, compiler warnings, scripts execution (/bin/sh^M not found), etc. To quickly convert those files from CR/LF to just LF, you can do something like this: USE_REINPLACE= yes post-extract: @${FIND} -E ${WRKDIR} -type f -iregex ".*\.(c|cpp|h|txt)" -print0 | \ ${XARGS} -0 ${REINPLACE_CMD} -e 's/[[:cntrl:]]*$$//' '{}' \; Of course, if you need to process each and every file, above can be omitted. Be aware that this piece of code will strip all trailing control characters from each line of processed file (except \n). Also, if you had to delete a file, then you can do it in the post-extract target rather than as part of the patch. Once you are happy with the resulting diff, please split it up into one source file per patch file. Configuring Include any additional customization commands in your configure script and save it in the scripts subdirectory. As mentioned above, you can also do this with Makefile targets and/or scripts with the name pre-configure or post-configure. Handling user input If your port requires user input to build, configure, or install, you must set IS_INTERACTIVE in your Makefile. This will allow overnight builds to skip your port if the user sets the variable BATCH in his environment (and if the user sets the variable INTERACTIVE, then only those ports requiring interaction are built). This will save a lot of wasted time on the set of machines that continually build ports (see below). It is also recommended that if there are reasonable default answers to the questions, you check the PACKAGE_BUILDING variable and turn off the interactive script when it is set. This will allow us to build the packages for CDROMs and FTP. Configuring the Makefile Configuring the Makefile is pretty simple, and again we suggest that you look at existing examples before starting. Also, there is a sample Makefile in this handbook, so take a look and please follow the ordering of variables and sections in that template to make your port easier for others to read. Now, consider the following problems in sequence as you design your new Makefile: The original source Does it live in DISTDIR as a standard gzip'd tarball named something like foozolix-1.2.tar.gz? If so, you can go on to the next step. If not, you should look at overriding any of the DISTNAME, EXTRACT_CMD, EXTRACT_BEFORE_ARGS, EXTRACT_AFTER_ARGS, EXTRACT_SUFX, or DISTFILES variables, depending on how alien a format your port's distribution file is. (The most common case is EXTRACT_SUFX=.tar.Z, when the tarball is condensed by regular compress, not gzip.) In the worst case, you can simply create your own do-extract target to override the default, though this should be rarely, if ever, necessary. Naming The first part of the port's Makefile names the port, describes its version number, and lists it in the correct category. <makevar>PORTNAME</makevar> and <makevar>PORTVERSION</makevar> You should set PORTNAME to the base name of your port, and PORTVERSION to the version number of the port. <makevar>PORTREVISION</makevar> and <makevar>PORTEPOCH</makevar> <makevar>PORTREVISION</makevar> The PORTREVISION variable is a monotonically increasing value which is reset to 0 with every increase of PORTVERSION (i.e. every time a new official vendor release is made), and appended to the package name if non-zero. Changes to PORTREVISION are used by automated tools (e.g. &man.pkg.version.1;) to highlight the fact that a new package is available. PORTREVISION should be increased each time a change is made to the port which significantly affects the content or structure of the derived package. Examples of when PORTREVISION should be bumped: Addition of patches to correct security vulnerabilities, bugs, or to add new functionality to the port. Changes to the port Makefile to enable or disable compile-time options in the package. Changes in the packing list or the install-time behavior of the package (e.g. change to a script which generates initial data for the package, like ssh host keys). Version bump of a port's shared library dependency (in this case, someone trying to install the old package after installing a newer version of the dependency will fail since it will look for the old libfoo.x instead of libfoo.(x+1)). Silent changes to the port distfile which have significant functional differences, i.e. changes to the distfile requiring a correction to distinfo with no corresponding change to PORTVERSION, where a diff -ru of the old and new versions shows non-trivial changes to the code. Examples of changes which do not require a PORTREVISION bump: Style changes to the port skeleton with no functional change to what appears in the resulting package. Changes to MASTER_SITES or other functional changes to the port which do not affect the resulting package. Trivial patches to the distfile such as correction of typos, which are not important enough that users of the package should go to the trouble of upgrading. Build fixes which cause a package to become compilable where it was previously failing (as long as the changes do not introduce any functional change on any other platforms on which the port did previously build). Since PORTREVISION reflects the content of the package, if the package was not previously buildable then there is no need to increase PORTREVISION to mark a change. A rule of thumb is to ask yourself whether a change committed to a port is something which everyone would benefit from having (either because of an enhancement, fix, or by virtue that the new package will actually work at all), and weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. If yes, the PORTREVISION should be bumped. <makevar>PORTEPOCH</makevar> From time to time a software vendor or FreeBSD porter will do something silly and release a version of their software which is actually numerically less than the previous version. An example of this is a port which goes from foo-20000801 to foo-1.0 (the former will be incorrectly treated as a newer version since 20000801 is a numerically greater value than 1). In situations such as this, the PORTEPOCH version should be increased. If PORTEPOCH is nonzero it is appended to the package name as described in section 0 above. PORTEPOCH must never be decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail (i.e. the package would not be detected as out of date): the new version number (e.g. 1.0,1 in the above example) is still numerically less than the previous version (20000801), but the ,1 suffix is treated specially by automated tools and found to be greater than the implied suffix ,0 on the earlier package. Dropping or resetting PORTEPOCH incorrectly leads to no end of grief; if you do not understand the above discussion, please keep after it until you do, or ask questions on the mailing lists. It is expected that PORTEPOCH will not be used for the majority of ports, and that sensible use of PORTVERSION can often pre-empt it becoming necessary if a future release of the software should change the version structure. However, care is needed by FreeBSD porters when a vendor release is made without an official version number — such as a code snapshot release. The temptation is to label the release with the release date, which will cause problems as in the example above when a new official release is made. For example, if a snapshot release is made on the date 20000917, and the previous version of the software was version 1.2, the snapshot release should be given a PORTVERSION of 1.2.20000917 or similar, not 20000917, so that the succeeding release, say 1.3, is still a numerically greater value. Example of <makevar>PORTREVISION</makevar> and <makevar>PORTEPOCH</makevar> usage The gtkmumble port, version 0.10, is committed to the ports collection: PORTNAME= gtkmumble PORTVERSION= 0.10 PKGNAME becomes gtkmumble-0.10. A security hole is discovered which requires a local FreeBSD patch. PORTREVISION is bumped accordingly. PORTNAME= gtkmumble PORTVERSION= 0.10 PORTREVISION= 1 PKGNAME becomes gtkmumble-0.10_1 A new version is released by the vendor, numbered 0.2 (it turns out the author actually intended 0.10 to actually mean 0.1.0, not what comes after 0.9 - oops, too late now). Since the new minor version 2 is numerically less than the previous version 10, the PORTEPOCH must be bumped to manually force the new package to be detected as newer. Since it is a new vendor release of the code, PORTREVISION is reset to 0 (or removed from the Makefile). PORTNAME= gtkmumble PORTVERSION= 0.2 PORTEPOCH= 1 PKGNAME becomes gtkmumble-0.2,1 The next release is 0.3. Since PORTEPOCH never decreases, the version variables are now: PORTNAME= gtkmumble PORTVERSION= 0.3 PORTEPOCH= 1 PKGNAME becomes gtkmumble-0.3,1 If PORTEPOCH were reset to 0 with this upgrade, someone who had installed the gtkmumble-0.10_1 package would not detect the gtkmumble-0.3 package as newer, since 3 is still numerically less than 10. Remember, this is the whole point of PORTEPOCH in the first place. <makevar>PKGNAMEPREFIX</makevar> and <makevar>PKGNAMESUFFIX</makevar> Two optional variables, PKGNAMEPREFIX and PKGNAMESUFFIX, are combined with PORTNAME and PORTVERSION to form PKGNAME as ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure this conforms to our guidelines for a good package name. In particular, you are not allowed to use a hyphen (-) in PORTVERSION. Also, if the package name has the language- or the -compiled.specifics part (see below), use PKGNAMEPREFIX and PKGNAMESUFFIX, respectively. Do not make them part of PORTNAME. Package Naming Conventions The following are the conventions you should follow in naming your packages. This is to have our package directory easy to scan, as there are already thousands of packages and users are going to turn away if they hurt their eyes! The package name should look like language_region-name-compiled.specifics-version.numbers. The package name is defined as ${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}. Make sure to set the variables to conform to that format. FreeBSD strives to support the native language of its users. The language- part should be a two letter abbreviation of the natural language defined by ISO-639 if the port is specific to a certain language. Examples are ja for Japanese, ru for Russian, vi for Vietnamese, zh for Chinese, ko for Korean and de for German. If the port is specific to a certain region within the language area, add the two letter country code as well. Examples are en_US for US English and fr_CH for Swiss French. The language- part should be set in the PKGNAMEPREFIX variable. The first letter of name part should be lowercase. (The rest of the name can contain capital letters, so use your own discretion when you are converting a software name that has some capital letters in it.) There is a tradition of naming perl 5 modules by prepending p5- and converting the double-colon separator to a hyphen; for example, the Data::Dumper module becomes p5-Data-Dumper. If the software in question has numbers, hyphens, or underscores in its name, you may include them as well (like kinput2). If the port can be built with different hardcoded defaults (usually part of the directory name in a family of ports), the -compiled.specifics part should state the compiled-in defaults (the hyphen is optional). Examples are papersize and font units. The -compiled.specifics part should be set in the PKGNAMESUFFIX variable. The version string should follow a dash (-) and be a period-separated list of integers and single lowercase alphabetics. In particular, it is not permissible to have another dash inside the version string. The only exception is the string pl (meaning patchlevel), which can be used only when there are no major and minor version numbers in the software. If the software version has strings like alpha, beta, rc, or pre, take the first letter and put it immediately after a period. If the version string continues after those names, the numbers should follow the single alphabet without an extra period between them. The idea is to make it easier to sort ports by looking at the version string. In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the yyyy.mm.dd format, not dd.mm.yyyy or the non-Y2K compliant yy.mm.dd format. Here are some (real) examples on how to convert the name as called by the software authors to a suitable package name: Distribution Name PKGNAMEPREFIX PORTNAME PKGNAMESUFFIX PORTVERSION Reason mule-2.2.2 (empty) mule (empty) 2.2.2 No changes required XFree86-3.3.6 (empty) XFree86 (empty) 3.3.6 No changes required EmiClock-1.0.2 (empty) emiclock (empty) 1.0.2 No uppercase names for single programs rdist-1.3alpha (empty) rdist (empty) 1.3.a No strings like alpha allowed es-0.9-beta1 (empty) es (empty) 0.9.b1 No strings like beta allowed mailman-2.0rc3 (empty) mailman (empty) 2.0.r3 No strings like rc allowed v3.3beta021.src (empty) tiff (empty) 3.3 What the heck was that anyway? tvtwm (empty) tvtwm (empty) pl11 Version string always required piewm (empty) piewm (empty) 1.0 Version string always required xvgr-2.10pl1 (empty) xvgr (empty) 2.10.1 pl allowed only when no major/minor version numbers gawk-2.15.6 ja- gawk (empty) 2.15.6 Japanese language version psutils-1.13 (empty) psutils -letter 1.13 Papersize hardcoded at package build time pkfonts (empty) pkfonts 300 1.0 Package for 300dpi fonts If there is absolutely no trace of version information in the original source and it is unlikely that the original author will ever release another version, just set the version string to 1.0 (like the piewm example above). Otherwise, ask the original author or use the date string (yyyy.mm.dd) as the version. Categorization <makevar>CATEGORIES</makevar> When a package is created, it is put under /usr/ports/packages/All and links are made from one or more subdirectories of /usr/ports/packages. The names of these subdirectories are specified by the variable CATEGORIES. It is intended to make life easier for the user when he is wading through the pile of packages on the FTP site or the CDROM. Please take a look at the current list of categories and pick the ones that are suitable for your port. This list also determines where in the ports tree the port is imported. If you put more than one category here, it is assumed that the port files will be put in the subdirectory with the name in the first category. See below for more discussion about how to pick the right categories. If your port truly belongs to something that is different from all the existing ones, you can even create a new category name. In that case, please send mail to the &a.ports; to propose a new category. However, in general, until there are more than a handful of ports which could be reclassified into the category you propose, you will probably be turned down. Occasionally someone proposes reorganizing the categories with either a 2-level structure, or some other kind of keyword structure. To date, nothing has come of any of these proposals because, while they are very easy to make, the effort involved to retrofit the entire existing ports collection with any kind of reorganization is daunting to say the very least. Please read the history of these proposals in the mailing list archives before you post this idea; furthermore, you should be prepared to be challenged to offer a working prototype. Current list of categories Here is the current list of port categories. Those marked with an asterisk (*) are virtual categories—those that do not have a corresponding subdirectory in the ports tree. They are only used as secondary categories, and only for search purposes. For non-virtual categories, you will find a one-line description in the COMMENT in that subdirectory's Makefile. Category Description Notes accessibility Ports to help disabled users. afterstep* Ports to support the AfterStep window manager. arabic Arabic language support. archivers Archiving tools. astro Astronomical ports. audio Sound support. benchmarks Benchmarking utilities. biology Biology-related software. cad Computer aided design tools. chinese Chinese language support. comms Communication software. Mostly software to talk to your serial port. converters Character code converters. databases Databases. deskutils Things that used to be on the desktop before computers were invented. devel Development utilities. Do not put libraries here just because they are libraries—unless they truly do not belong anywhere else, they should not be in this category. dns DNS-related software. editors General editors. Specialized editors go in the section for those tools (e.g., a mathematical-formula editor will go in math). elisp* Emacs-lisp ports. emulators Emulators for other operating systems. Terminal emulators do not belong here—X-based ones should go to x11 and text-based ones to either comms or misc, depending on the exact functionality. finance Monetary, financial and related applications. french French language support. ftp FTP client and server utilities. If your port speaks both FTP and HTTP, put it in ftp with a secondary category of www. games Games. german German language support. gnome* Ports from the GNOME Project. graphics Graphics utilities. haskell* Software related to the Haskell language. hebrew Hebrew language support. hungarian Hungarian language support. ipv6* IPv6 related software. irc Internet Relay Chat utilities. japanese Japanese language support. java Software related to the Java language. kde* Ports from the K Desktop Environment (KDE) Project. korean Korean language support. lang Programming languages. linux* Linux applications and support utilities. lisp* Software related to the Lisp language. mail Mail software. math Numerical computation software and other utilities for mathematics. mbone MBone applications. misc Miscellaneous utilities Basically things that do not belong anywhere else. If at all possible, try to find a better category for your port than misc, as ports tend to get overlooked in here. multimedia Multimedia software. net Miscellaneous networking software. net-mgmt Networking management software. news USENET news software. offix* Ports from the OffiX suite. palm Software support for the Palm™ series. parallel* Applications dealing with parallelism in computing. pear* Ports related to the Pear PHP framework. perl5* Ports that require Perl version 5 to run. picobsd Ports to support PicoBSD. plan9* Various programs from Plan9. polish Polish language support. portuguese Portuguese language support. print Printing software. Desktop publishing tools (previewers, etc.) belong here too. python* Software related to the Python language. ruby* Software related to the Ruby language. russian Russian language support. science Scientific ports that do not fit into other categories such as astro, biology and math. security Security utilities. shells Command line shells. sysutils System utilities. tcl76* Ports that use Tcl version 7.6 to run. tcl80* Ports that use Tcl version 8.0 to run. tcl81* Ports that use Tcl version 8.1 to run. tcl82* Ports that use Tcl version 8.2 to run. tcl83* Ports that use Tcl version 8.3 to run. textproc Text processing utilities. It does not include desktop publishing tools, which go to print. tk42* Ports that use Tk version 4.2 to run. tk80* Ports that use Tk version 8.0 to run. tk81* Ports that use Tk version 8.1 to run. tk82* Ports that use Tk version 8.2 to run. tk83* Ports that use Tk version 8.3 to run. tkstep80* Ports that use TkSTEP version 8.0 to run. ukrainian Ukrainian language support. vietnamese Vietnamese language support. windowmaker* Ports to support the WindowMaker window manager. www Software related to the World Wide Web. HTML language support belongs here too. x11 The X Window System and friends. This category is only for software that directly supports the window system. Do not put regular X applications here; most of them should go into other x11-* categories (see below). If your port is an X application, define USE_XLIB (implied by USE_IMAKE) and put it in the appropriate category. x11-clocks X11 clocks. x11-fm X11 file managers. x11-fonts X11 fonts and font utilities. x11-servers X11 servers. x11-toolkits X11 toolkits. x11-wm X11 window managers. zope* Zope support. Choosing the right category As many of the categories overlap, you often have to choose which of the categories should be the primary category of your port. There are several rules that govern this issue. Here is the list of priorities, in decreasing order of precedence: The first category must be a physical category (see above). This is necessary to make the packaging work. Virtual categories and physical categories may be intermixed after that. Language specific categories always come first. For example, if your port installs Japanese X11 fonts, then your CATEGORIES line would read japanese x11-fonts. Specific categories are listed before less-specific ones. For instance, an HTML editor should be listed as www editors, not the other way around. Also, you should not list net when the port belongs to any of irc, mail, mbone, news, security, or www, as net is included implicitly. x11 is used as a secondary category only when the primary category is a natural language. In particular, you should not put x11 in the category line for X applications. Emacs modes should be placed in the same ports category as the application supported by the mode, not in editors. For example, an Emacs mode to edit source files of some programming language should go into lang. misc should not appear with any other non-virtual category. If you have misc with something else in your CATEGORIES line, that means you can safely delete misc and just put the port in that other subdirectory! If your port truly does not belong anywhere else, put it in misc. If you are not sure about the category, please put a comment to that effect in your &man.send-pr.1; submission so we can discuss it before we import it. If you are a committer, send a note to the &a.ports; so we can discuss it first. Too often, new ports are imported to the wrong category only to be moved right away. This causes unnecessary and undesirable bloat in the master source repository. The distribution files The second part of the Makefile describes the files that must be downloaded in order to build the port, and where they can be downloaded from. <makevar>DISTNAME</makevar> DISTNAME is the name of the port as called by the authors of the software. DISTNAME defaults to ${PORTNAME}-${PORTVERSION}, so override it only if necessary. DISTNAME is only used in two places. First, the distribution file list (DISTFILES) defaults to ${DISTNAME}${EXTRACT_SUFX}. Second, the distribution file is expected to extract into a subdirectory named WRKSRC, which defaults to work/${DISTNAME}. PKGNAMEPREFIX and PKGNAMESUFFIX do not affect DISTNAME. Also note that if WRKSRC is equal to work/${PORTNAME}-${PORTVERSION} while the original source archive is named something other than ${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}, you should probably leave DISTNAME alone— you are better off defining DISTFILES than having to set both DISTNAME and WRKSRC (and possibly EXTRACT_SUFX). <makevar>MASTER_SITES</makevar> Record the directory part of the FTP/HTTP-URL pointing at the original tarball in MASTER_SITES. Do not forget the trailing slash (/)! The make macros will try to use this specification for grabbing the distribution file with FETCH if they cannot find it already on the system. It is recommended that you put multiple sites on this list, preferably from different continents. This will safeguard against wide-area network problems. We are even planning to add support for automatically determining the closest master site and fetching from there; having multiple sites will go a long way towards helping this effort. If the original tarball is part of one of the popular archives such as X-contrib, GNU, or Perl CPAN, you may be able refer to those sites in an easy compact form using MASTER_SITE_* (e.g., MASTER_SITE_XCONTRIB and MASTER_SITE_PERL_GNU). Simply set MASTER_SITES to one of these variables and MASTER_SITE_SUBDIR to the path within the archive. Here is an example: MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications These variables are defined in /usr/ports/Mk/bsd.sites.mk. There are new entries added all the time, so make sure to check the latest version of this file before submitting a port. The user can also set the MASTER_SITE_* variables in /etc/make.conf to override our choices, and use their favorite mirrors of these popular archives instead. <makevar>EXTRACT_SUFX</makevar> If you have one distribution file, and it uses an odd suffix to indicate the compression mechanism, set EXTRACT_SUFX. For example, if the distribution file was named foo.tgz instead of the more normal foo.tar.gz, you would write: DISTNAME= foo EXTRACT_SUFX= .tgz The USE_BZIP2 and USE_ZIP variables automatically set EXTRACT_SUFX to .bz2 or .zip as necessary. If neither of these are set then EXTRACT_SUFX defaults to .tar.gz. You never need to set both EXTRACT_SUFX and DISTFILES. <makevar>DISTFILES</makevar> Sometimes the names of the files to be downloaded have no resemblance to the name of the port. For example, it might be called source.tar.gz or similar. In other cases the application's source code might be in several different archives, all of which must be downloaded. If this is the case, set DISTFILES to be a space separated list of all the files that must be downloaded. DISTFILES= source1.tar.gz source2.tar.gz If not explicitly set, DISTFILES defaults to ${DISTNAME}${EXTRACT_SUFX}. <makevar>EXTRACT_ONLY</makevar> If only some of the DISTFILES must be extracted—for example, one of them is the source code, while another is an uncompressed document—list the filenames that must be extracted in EXTRACT_ONLY. DISTFILES= source.tar.gz manual.html EXTRACT_ONLY= source.tar.gz If none of the DISTFILES should be uncompressed then set EXTRACT_ONLY to the empty string. EXTRACT_ONLY= <makevar>PATCHFILES</makevar> If your port requires some additional patches that are available by FTP or HTTP, set PATCHFILES to the names of the files and PATCH_SITES to the URL of the directory that contains them (the format is the same as MASTER_SITES). If the patch is not relative to the top of the source tree (i.e., WRKSRC) because it contains some extra pathnames, set PATCH_DIST_STRIP accordingly. For instance, if all the pathnames in the patch have an extra foozolix-1.0/ in front of the filenames, then set PATCH_DIST_STRIP=-p1. Do not worry if the patches are compressed; they will be decompressed automatically if the filenames end with .gz or .Z. If the patch is distributed with some other files, such as documentation, in a gzip'd tarball, you cannot just use PATCHFILES. If that is the case, add the name and the location of the patch tarball to DISTFILES and MASTER_SITES. Then, use the EXTRA_PATCHES variable to point to those files and bsd.port.mk will automatically apply them for you. In particular, do not copy patch files into the PATCHDIR directory—that directory may not be writable. The tarball will have been extracted alongside the regular source by then, so there is no need to explicitly extract it if it is a regular gzip'd or compress'd tarball. If you do the latter, take extra care not to overwrite something that already exists in that directory. Also, do not forget to add a command to remove the copied patch in the pre-clean target. Multiple distribution files or patches from different sites and subdirectories (<literal>MASTER_SITES:n</literal>) (Consider this to be a somewhat advanced topic; those new to this document may wish to skip this section at first). This section has information on the fetching mechanism known as both MASTER_SITES:n and MASTER_SITES_NN. We will refer to this mechanism as MASTER_SITES:n hereon. A little background first. OpenBSD has a neat feature inside both DISTFILES and PATCHFILES variables, both files and patches can be postfixed with :n identifiers where n both can be [0-9] and denote a group designation. For example: DISTFILES= alpha:0 beta:1 In OpenBSD, distribution file alpha will be associated with variable MASTER_SITES0 instead of our common MASTER_SITES and beta with MASTER_SITES1. This is a very interesting feature which can decrease that endless search for the correct download site. Just picture 2 files in DISTFILES and 20 sites in MASTER_SITES, the sites slow as hell where beta is carried by all sites in MASTER_SITES, and alpha can only be found in the 20th site. It would be such a waste to check all of them if maintainer knew this beforehand, would it not? Not a good start for that lovely weekend! Now that you have the idea, just imagine more DISTFILES and more MASTER_SITES. Surely our distfiles survey meister would appreciate the relief to network strain that this would bring. In the next sections, information will follow on the FreeBSD implementation of this idea. We improved a bit on OpenBSD's concept. Simplified information This section tells you how to quickly prepare fine grained fetching of multiple distribution files and patches from different sites and subdirectories. We describe here a case of simplified MASTER_SITES:n usage. This will be sufficient for most scenarios. However, if you need further information, you will have to refer to the next section. Some applications consist of multiple distribution files that must be downloaded from a number of different sites. For example, Ghostscript consists of the core of the program, and then a large number of driver files that are used depending on the user's printer. Some of these driver files are supplied with the core, but many others must be downloaded from a variety of different sites. To support this, each entry in DISTFILES may be followed by a colon and a tag name. Each site listed in MASTER_SITES is then followed by a colon, and the tag that indicates which distribution files should be downloaded from this site. For example, consider an application with the source split in two parts, source1.tar.gz and source2.tar.gz, which must be downloaded from two different sites. The port's Makefile would include lines like . Simplified use of <literal>MASTER_SITES:n</literal> with 1 file per site MASTER_SITES= ftp://ftp.example1.com/:source1 \ ftp://ftp.example2.com/:source2 DISTFILES= source1.tar.gz:source1 \ source2.tar.gz:source2 Multiple distribution files can have the same tag. Continuing the previous example, suppose that there was a third distfile, source3.tar.gz, that should be downloaded from ftp.example2.com. The Makefile would then be written like . Simplified use of <literal>MASTER_SITES:n</literal> with more than 1 file per site MASTER_SITES= ftp://ftp.example1.com/:source1 \ ftp://ftp.example2.com/:source2 DISTFILES= source1.tar.gz:source1 \ source2.tar.gz:source2 \ source3.tar.gz:source2 Detailed information Okay, so the previous section example did not reflect your needs? In this section we will explain in detail how the fine grained fetching mechanism MASTER_SITES:n works and how you can modify your ports to use it. Elements can be postfixed with :n where n is [^:,]+, i.e., n could conceptually be any alphanumeric string but we will limit it to [a-zA-Z_][0-9a-zA-Z_]+ for now. Moreover, string matching is case sensitive; i.e., n is different from N. However, the following words cannot be used for postfixing purposes since they yield special meaning: default, all and ALL (they are used internally in item ). Furthermore, DEFAULT is a special purpose word (check item ). Elements postfixed with :n belong to the group n, :m belong to group m and so forth. Elements without a postfix are groupless, i.e., they all belong to the special group DEFAULT. If you postfix any elements with DEFAULT, you are just being redundant unless you want to have an element belonging to both DEFAULT and other groups at the same time (check item ). The following examples are equivalent but the first one is preferred: MASTER_SITES= alpha MASTER_SITES= alpha:DEFAULT Groups are not exclusive, an element may belong to several different groups at the same time and a group can either have either several different elements or none at all. Repeated elements within the same group will be simply that, repeated elements. When you want an element to belong to several groups at the same time, you can use the comma operator (,). Instead of repeating it several times, each time with a different postfix, we can list several groups at once in a single postfix. For instance, :m,n,o marks an element that belongs to group m, n and o. All the following examples are equivalent but the last one is preferred: MASTER_SITES= alpha alpha:SOME_SITE MASTER_SITES= alpha:DEFAULT alpha:SOME_SITE MASTER_SITES= alpha:SOME_SITE,DEFAULT MASTER_SITES= alpha:DEFAULT,SOME_SITE All sites within a given group are sorted according to MASTER_SORT_AWK. All groups within MASTER_SITES and PATCH_SITES are sorted as well. Group semantics can be used in any of the following variables MASTER_SITES, PATCH_SITES, MASTER_SITE_SUBDIR, PATCH_SITE_SUBDIR, DISTFILES, and PATCHFILES according to the following syntax: All MASTER_SITES, PATCH_SITES, MASTER_SITE_SUBDIR and PATCH_SITE_SUBDIR elements must be terminated with the forward slash / character. If any elements belong to any groups, the group postfix :n must come right after the terminator /. The MASTER_SITES:n mechanism relies on the existence of the terminator / to avoid confusing elements where a :n is a valid part of the element with occurrences where :n denotes group n. For compatibility purposes, since the / terminator was not required before in both MASTER_SITE_SUBDIR and PATCH_SITE_SUBDIR elements, if the postfix immediate preceding character is not a / then :n will be considered a valid part of the element instead of a group postfix even if an element is postfixed with :n. See both and . Detailed use of <literal>MASTER_SITES:n</literal> in <makevar>MASTER_SITE_SUBDIR</makevar> MASTER_SITE_SUBDIR= old:n new/:NEW Directories within group DEFAULT -> old:n Directories within group NEW -> new Detailed use of <literal>MASTER_SITES:n</literal> with comma operator, multiple files, multiple sites and multiple subdirectories MASTER_SITES= http://site1/%SUBDIR%/ http://site2/:DEFAULT \ http://site3/:group3 http://site4/:group4 \ http://site5/:group5 http://site6/:group6 \ http://site7/:DEFAULT,group6 \ http://site8/%SUBDIR%/:group6,group7 \ http://site9/:group8 DISTFILES= file1 file2:DEFAULT file3:group3 \ file4:group4,group5,group6 file5:grouping \ file6:group7 MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ directory-one/:group6,DEFAULT \ directory The previous example results in the following fine grained fetching. Sites are listed in the exact order they will be used. file1 will be fetched from MASTER_SITE_OVERRIDE http://site1/directory/ http://site1/directory-one/ http://site1/directory-trial:1/ http://site2/ http://site7/ MASTER_SITE_BACKUP file2 will be fetched exactly as file1 since they both belong to the same group MASTER_SITE_OVERRIDE http://site1/directory/ http://site1/directory-one/ http://site1/directory-trial:1/ http://site2/ http://site7/ MASTER_SITE_BACKUP file3 will be fetched from MASTER_SITE_OVERRIDE http://site3/ MASTER_SITE_BACKUP file4 will be fetched from MASTER_SITE_OVERRIDE http://site4/ http://site5/ http://site6/ http://site7/ http://site8/directory-one/ MASTER_SITE_BACKUP file5 will be fetched from MASTER_SITE_OVERRIDE MASTER_SITE_BACKUP file6 will be fetched from MASTER_SITE_OVERRIDE http://site8/directory-one/ MASTER_SITE_BACKUP How do I group one of the special variables from bsd.sites.mk, e.g., MASTER_SITE_SOURCEFORGE? See . Detailed use of <literal>MASTER_SITES:n</literal> with <makevar>MASTER_SITE_SOURCEFORGE</makevar> MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/} DISTFILES= something.tar.gz:sourceforge something.tar.gz will be fetched from all sites within MASTER_SITE_SOURCEFORGE. How do I use this with PATCH* variables? All examples were done with MASTER* variables but they work exactly the same for PATCH* ones as can be seen in . Simplified use of <literal>MASTER_SITES:n</literal> with <makevar>PATCH_SITES</makevar>. PATCH_SITES= http://site1/ http://site2/:test PATCHFILES= patch1:test What does change for ports? What does not? All current ports remain the same. The MASTER_SITES:n feature code is only activated if there are elements postfixed with :n like elements according to the aforementioned syntax rules, especially as shown in item . The port targets remain the same: checksum, makesum, patch, configure, build, etc. With the obvious exceptions of do-fetch, fetch-list, master-sites and patch-sites. do-fetch: deploys the new grouping postfixed DISTFILES and PATCHFILES with their matching group elements within both MASTER_SITES and PATCH_SITES which use matching group elements within both MASTER_SITE_SUBDIR and PATCH_SITE_SUBDIR. Check . fetch-list: works like old fetch-list with the exception that it groups just like do-fetch. master-sites and patch-sites: (incompatible with older versions) only return the elements of group DEFAULT; in fact, they execute targets master-sites-default and patch-sites-default respectively. Furthermore, using target either master-sites-all or patch-sites-all is preferred to directly checking either MASTER_SITES or PATCH_SITES. Also, directly checking is not guaranteed to work in any future versions. Check item for more information on these new port targets. New port targets There are master-sites-n and patch-sites-n targets which will list the elements of the respective group n within MASTER_SITES and PATCH_SITES respectively. For instance, both master-sites-DEFAULT and patch-sites-DEFAULT will return the elements of group DEFAULT, master-sites-test and patch-sites-test of group test, and thereon. There are new targets master-sites-all and patch-sites-all which do the work of the old master-sites and patch-sites ones. They return the elements of all groups as if they all belonged to the same group with the caveat that it lists as many MASTER_SITE_BACKUP and MASTER_SITE_OVERRIDE as there are groups defined within either DISTFILES or PATCHFILES; respectively for master-sites-all and patch-sites-all. <makevar>DIST_SUBDIR</makevar> Do not let your port clutter /usr/ports/distfiles. If your port requires a lot of files to be fetched, or contains a file that has a name that might conflict with other ports (e.g., Makefile), set DIST_SUBDIR to the name of the port (${PORTNAME} or ${PKGNAMEPREFIX}${PORTNAME} should work fine). This will change DISTDIR from the default /usr/ports/distfiles to /usr/ports/distfiles/DIST_SUBDIR, and in effect puts everything that is required for your port into that subdirectory. It will also look at the subdirectory with the same name on the backup master site at ftp.FreeBSD.org. (Setting DISTDIR explicitly in your Makefile will not accomplish this, so please use DIST_SUBDIR.) This does not affect the MASTER_SITES you define in your Makefile. <makevar>MAINTAINER</makevar> Set your mail-address here. Please. :-) Note that only a single address without the comment part is allowed as a MAINTAINER value. The format used should be user@hostname.domain. Please do not include any descriptive text such as your real name in this entry—that merely confuses bsd.port.mk. Instead, put that information into your pkg-descr. For a detailed description of the responsibilities of maintainers, refer to the MAINTAINER on Makefiles section. If the maintainer of a port does not respond to an update request from a user after two weeks (excluding major public holidays), then that is considered a maintainer timeout, and the update may be made without explicit maintainer approval. If the maintainer does not respond within three months, then that maintainer is considered absent without leave, and can be replaced as the maintainer of the particular port in question. Exceptions to this are anything maintained by the &a.portmgr;, or the &a.security-officer;. No unauthorized commits may ever be made to ports maintained by those groups. The &a.portmgr; reserves the right to revoke or override anyone's maintainership for any reason, and the &a.security-officer; reserves the right to revoke or override maintainership for security reasons. <makevar>COMMENT</makevar> This is a one-line description of the port. Please do not include the package name (or version number of the software) in the comment. The comment should begin with a capital and end without a period. Here is an example: COMMENT= A cat chasing a mouse all over the screen The COMMENT variable should immediately follow the MAINTAINER variable in the Makefile. Please try to keep the COMMENT line less than 70 characters, as it is displayed to users as a one-line summary of the port. Dependencies Many ports depend on other ports. There are seven variables that you can use to ensure that all the required bits will be on the user's machine. There are also some pre-supported dependency variables for common cases, plus a few more to control the behavior of dependencies. <makevar>LIB_DEPENDS</makevar> This variable specifies the shared libraries this port depends on. It is a list of lib:dir:target tuples where lib is the name of the shared library, dir is the directory in which to find it in case it is not available, and target is the target to call in that directory. For example, LIB_DEPENDS= jpeg.9:${PORTSDIR}/graphics/jpeg:install will check for a shared jpeg library with major version 9, and descend into the graphics/jpeg subdirectory of your ports tree to build and install it if it is not found. The target part can be omitted if it is equal to DEPENDS_TARGET (which defaults to install). The lib part is an argument given to ldconfig -r | grep -wF. There shall be no regular expressions in this variable. The dependency is checked twice, once from within the extract target and then from within the install target. Also, the name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system. <makevar>RUN_DEPENDS</makevar> This variable specifies executables or files this port depends on during run-time. It is a list of path:dir:target tuples where path is the name of the executable or file, dir is the directory in which to find it in case it is not available, and target is the target to call in that directory. If path starts with a slash (/), it is treated as a file and its existence is tested with test -e; otherwise, it is assumed to be an executable, and which -s is used to determine if the program exists in the user's search path. For example, RUN_DEPENDS= ${LOCALBASE}/etc/innd:${PORTSDIR}/news/inn \ wish8.0:${PORTSDIR}/x11-toolkits/tk80 will check if the file or directory /usr/local/etc/innd exists, and build and install it from the news/inn subdirectory of the ports tree if it is not found. It will also see if an executable called wish8.0 is in your search path, and descend into the x11-toolkits/tk80 subdirectory of your ports tree to build and install it if it is not found. In this case, innd is actually an executable; if an executable is in a place that is not expected to be in a normal user's search path, you should use the full pathname. The dependency is checked from within the install target. Also, the name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system. The target part can be omitted if it is the same as DEPENDS_TARGET. <makevar>BUILD_DEPENDS</makevar> This variable specifies executables or files this port requires to build. Like RUN_DEPENDS, it is a list of path:dir:target tuples. For example, BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip will check for an executable called unzip, and descend into the archivers/unzip subdirectory of your ports tree to build and install it if it is not found. build here means everything from extraction to compilation. The dependency is checked from within the extract target. The target part can be omitted if it is the same as DEPENDS_TARGET <makevar>FETCH_DEPENDS</makevar> This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of path:dir:target tuples. For example, FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2 will check for an executable called ncftp2, and descend into the net/ncftp2 subdirectory of your ports tree to build and install it if it is not found. The dependency is checked from within the fetch target. The target part can be omitted if it is the same as DEPENDS_TARGET. <makevar>EXTRACT_DEPENDS</makevar> This variable specifies executables or files this port requires for extraction. Like the previous, it is a list of path:dir:target tuples. For example, EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip will check for an executable called unzip, and descend into the archivers/unzip subdirectory of your ports tree to build and install it if it is not found. The dependency is checked from within the extract target. The target part can be omitted if it is the same as DEPENDS_TARGET. Use this variable only if the extraction does not already work (the default assumes gzip) and cannot be made to work using USE_ZIP or USE_BZIP2 described in . <makevar>PATCH_DEPENDS</makevar> This variable specifies executables or files this port requires to patch. Like the previous, it is a list of path:dir:target tuples. For example, PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract will descend into the java/jfc subdirectory of your ports tree to build and install it if it is not found. The dependency is checked from within the patch target. The target part can be omitted if it is the same as DEPENDS_TARGET. <makevar>DEPENDS</makevar> If there is a dependency that does not fall into either of the above categories, or your port requires having the source of the other port extracted in addition to having it installed, then use this variable. This is a list of dir:target, as there is nothing to check, unlike the previous four. The target part can be omitted if it is the same as DEPENDS_TARGET. <makevar>USE_<replaceable>*</replaceable></makevar> A number of variables exist in order to encapsulate common dependencies that many ports have. Although their use is optional, they can help to reduce the verbosity of the port Makefiles. Each of them is styled as USE_*. The usage of these variables is restricted to the port Makefiles and ports/Mk/bsd.*.mk and is not designed to encapsulate user-settable options — use WITH_* and WITHOUT_* for that purpose. It is always incorrect to set any USE_* in /etc/make.conf. For instance, setting USE_GCC=3.2 would adds a dependency on gcc32 for every port, including gcc32 itself! The <makevar>USE_<replaceable>*</replaceable></makevar> variables Variable Means USE_BZIP2 The port's tarballs are compressed with bzip2. USE_ZIP The port's tarballs are compressed with zip. USE_GMAKE The port requires gmake to build. USE_PERL5 The port requires perl 5 to build and install. See for additional variables that can be set relating to perl. USE_X_PREFIX The port installs in to X11BASE rather than PREFIX. See for additional variables that can be set relating to X11. USE_AUTOMAKE_VER The port uses GNU automake as part of its build process. See for additional variables that can be set relating to automake. USE_AUTOCONF_VER The port uses GNU autoconf as part of its build process. See for additional variables that can be set relating to autoconf. USE_LIBTOOL_VER The port uses GNU libtool as part of its build process. See for additional variables that can be set relating to libtool. GMAKE The full path for gmake if it is not in the PATH. USE_BISON The port uses bison for building. USE_SDL The port uses SDL for building and running. See on how to use USE_SDL. NO_INSTALL_MANPAGES Do not use the install.man target.
Define USE_XLIB=yes if your port requires the X Window System to be installed (it is implied by USE_IMAKE). Define USE_GMAKE=yes if your port requires GNU make instead of BSD make. Define USE_AUTOCONF_VER=213 if your port requires GNU autoconf to be run. Define USE_QT_VER=3 if your port uses the latest Qt toolkit. Use USE_PERL5=yes if your port requires version 5 of the perl language. (The last is especially important since some versions of FreeBSD have perl5 as part of the base system while others do not.) Notes on dependencies As mentioned above, the default target to call when a dependency is required is DEPENDS_TARGET. It defaults to install. This is a user variable; it is never defined in a port's Makefile. If your port needs a special way to handle a dependency, use the :target part of the *_DEPENDS variables instead of redefining DEPENDS_TARGET. When you type make clean, its dependencies are automatically cleaned too. If you do not wish this to happen, define the variable NOCLEANDEPENDS in your environment. This may be particularly desirable if the port has something that takes a long time to rebuild in its dependency list, such as KDE, GNOME or Mozilla. To depend on another port unconditionally, use the variable ${NONEXISTENT} as the first field of BUILD_DEPENDS or RUN_DEPENDS. Use this only when you need to get the source of the other port. You can often save compilation time by specifying the target too. For instance BUILD_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/graphics/jpeg:extract will always descend to the jpeg port and extract it. Do not use DEPENDS unless there is no other way the behavior you want can be accomplished. It will cause the other port to always be built (and installed, by default), and the dependency will go into the packages as well. If this is really what you need, you should probably write it as BUILD_DEPENDS and RUN_DEPENDS instead—at least the intention will be clear. Circular dependencies are fatal Do not introduce any circular dependencies into the ports tree! The ports building technology does not tolerate circular dependencies. If you introduce one, you will have someone, somewhere in the world, whose FreeBSD installation will break almost immediately, with many others quickly to follow. These can really be hard to detect; if in doubt, before you make that change, make sure you have done the following: cd /usr/ports; make index. That process can be quite slow on older machines, but you may be able to save a large number of people—including yourself— a lot of grief in the process. Makefile Options Some large applications can be built in a number of configurations, adding functionality if one of a number of libraries or applications is available. Examples include choice of natural (human) language, GUI versus command-line, or type of database to support. Since not all users want those libraries or applications, the ports system provides hooks that the port author can use to control which configuration should be built. Supporting these properly will make users happy, and effectively provide 2 or more ports for the price of one. <makevar>WITH_<replaceable>*</replaceable></makevar> and <makevar>WITHOUT_<replaceable>*</replaceable></makevar> These variables are designed to be set by the system administrator. There are many that are standardized in ports/Mk/bsd.*.mk; others are not, which can be confusing. If you need to add such a configuration variable, please consider using one of the ones from the following list. You should not assume that a WITH_* necessarily has a corresponding WITHOUT_* variable and vice versa. In general, the default is simply assumed. Unless otherwise specified, these variables are only tested for being set or not set, rather than being set to some kind of variable such as YES or NO. The <makevar>WITH_<replaceable>*</replaceable></makevar> and <makevar>WITHOUT_<replaceable>*</replaceable></makevar> variables Variable Means WITH_APACHE2 If set, use www/apache2 instead of the default of www/apache. WITH_BERKELEY_DB Define this variable to specify the ability to use a variant of the Berkeley database package such as databases/db41. An associated variable, WITH_BDB_VER, may be set to values such as 2, 3, 4, 41 or 42. WITH_MYSQL Define this variable to specify the ability to use a variant of the MySQL database package such as databases/mysql40-server. An associated variable, WANT_MYSQL_VER, may be set to values such as 323, 40, 41, or 50. WITHOUT_NLS If set, says that internationalization is not needed, which can save compile time. By default, internalization is used. WITH_OPENSSL_BASE Use the version of OpenSSL in the base system. WITH_OPENSSL_PORT Use the version of OpenSSL from security/openssh, overwriting the version that was originally installed in the base system. WITH_POSTGRESQL Define this variable to specify the ability to use a variant of the PostGreSQL database package such as databases/postgresql72. WITHOUT_X11 If the port can be built both with and without X support, then it should normally be built with with X support. If this variable is defined, then then the version that does not have X support should be built instead.
Specifying the working directory Each port is extracted in to a working directory, which must be writable. The ports system defaults to having the DISTFILES unpack in to a directory called ${DISTNAME}. In other words, if you have set: PORTNAME= foo PORTVERSION= 1.0 then the port's distribution files contain a top-level directory, foo-1.0, and the rest of the files are located under that directory. There are a number of variables you can override if that is not the case. <makevar>WRKSRC</makevar> The variable lists the name of the directory that is created when the application's distfiles are extracted. If our previous example extracted into a directory called foo (and not foo-1.0) you would write: WRKSRC= ${WRKDIR}/foo or possibly WRKSRC= ${WRKDIR}/${PORTNAME} <makevar>NO_WRKSUBDIR</makevar> If the port does not extract in to a subdirectory at all then you should set NO_WRKSUBDIR to indicate that. NO_WRKSUBDIR= yes <makevar>CONFLICTS</makevar> If your package cannot coexist with other packages (because of file conflicts, runtime incompatibility, etc.), list the other package names in the CONFLICTS variable. You can use shell globs like * and ? here. Packages names should be enumerated the same way they appear in /var/db/pkg. Please make sure that CONFLICTS does not match this port's package itself, or else forcing its installation with FORCE_PKG_REGISTER will no longer work. Building mechanisms If your package uses GNU make, set USE_GMAKE=yes. If your package uses configure, set HAS_CONFIGURE=yes. If your package uses GNU configure, set GNU_CONFIGURE=yes (this implies HAS_CONFIGURE). If you want to give some extra arguments to configure (the default argument list --prefix=${PREFIX} for GNU configure and empty for non-GNU configure), set those extra arguments in CONFIGURE_ARGS. If your package uses GNU autoconf, set USE_AUTOCONF_VER=213. This implies GNU_CONFIGURE, and will cause autoconf to be run before configure. If your package uses GNU configure, and the resulting executable file has a strange name like i386-portbld-freebsd4.7-appname, you will need to additionally override the CONFIGURE_TARGET variable to specify the target in the way required by scripts generated by recent versions of autoconf. Add the following line immediately after the GNU_CONFIGURE=yes line in your Makefile: CONFIGURE_TARGET=--build=${MACHINE_ARCH}-portbld-freebsd${OSREL} If your package is an X application that creates Makefiles from Imakefiles using imake, then set USE_IMAKE=yes. This will cause the configure stage to automatically do an xmkmf -a. If the flag is a problem for your port, set XMKMF=xmkmf. If the port uses imake but does not understand the install.man target, NO_INSTALL_MANPAGES=yes should be set. In addition, the author of the original port should be shot. :-> If your port's source Makefile has something else than all as the main build target, set ALL_TARGET accordingly. Same goes for install and INSTALL_TARGET. Special considerations There are some more things you have to take into account when you create a port. This section explains the most common of those. Shared Libraries If your port installs one or more shared libraries, define a INSTALLS_SHLIB make variable, which will instruct a bsd.port.mk to run ${LDCONFIG} -m on the directory where the new library is installed (usually PREFIX/lib) during post-install target to register it into the shared library cache. This variable, when defined, will also facilitate addition of an appropriate @exec /sbin/ldconfig -m and @unexec /sbin/ldconfig -R pair into your pkg-plist file, so that a user who installed the package can start using the shared library immediately and de-installation will not cause the system to still believe the library is there. If you need, you can override the default location where the new library is installed by defining the LDCONFIG_DIRS make variable, which should contain a list of directories into which shared libraries are to be installed. For example if your port installs shared libraries into PREFIX/lib/foo and PREFIX/lib/bar directories you could use the following in your Makefile: INSTALLS_SHLIB= yes LDCONFIG_DIRS= %%PREFIX%%/lib/foo %%PREFIX%%/lib/bar Note that content of LDCONFIG_DIRS is passed through &man.sed.1; just like the rest of pkg-plist, so PLIST_SUB substitutions also apply here. It is recommended that you use %%PREFIX%% for PREFIX, %%LOCALBASE%% for LOCALBASE and %%X11BASE%% for X11BASE. Ports with distribution restrictions Licenses vary, and some of them place restrictions on how the application can be packaged, whether it can be sold for profit, and so on. It is your responsibility as a porter to read the licensing terms of the software and make sure that the FreeBSD project will not be held accountable for violating them by redistributing the source or compiled binaries either via FTP/HTTP or CD-ROM. If in doubt, please contact the &a.ports;. In situations like this, the variables described in the following sections can be set. <makevar>NO_PACKAGE</makevar> This variable indicates that we may not generate a binary package of the application. For instance, the license may disallow binary redistribution, or it may prohibit distribution of packages created from patched sources. However, the port's DISTFILES may be freely mirrored on FTP/HTTP. They may also be distributed on a CD-ROM (or similar media) unless NO_CDROM is set as well. NO_PACKAGE should also be used if the binary package is not generally useful, and the application should always be compiled from the source code. For example, if the application has configuration information that is site specific hard coded in to it at compile time, set NO_PACKAGE. NO_PACKAGE should be set to a string describing the reason why the package should not be generated. <makevar>NO_CDROM</makevar> This variable alone indicates that, although we are allowed to generate binary packages, we may put neither those packages nor the port's DISTFILES onto a CD-ROM (or similar media) for resale. However, the binary packages and the port's DISTFILES will still be available via FTP/HTTP. If this variable is set along with NO_PACKAGE, then only the port's DISTFILES will be available, and only via FTP/HTTP. NO_CDROM should be set to a string describing the reason why the port cannot be redistributed on CD-ROM. For instance, this should be used if the port's license is for non-commercial use only. <makevar>RESTRICTED</makevar> Set this variable alone if the application's license permits neither mirroring the application's DISTFILES nor distributing the binary package in any way. NO_CDROM or NO_PACKAGE should not be set along with RESTRICTED since the latter variable implies the former ones. RESTRICTED should be set to a string describing the reason why the port cannot be redistributed. Typically, this indicates that the port contains proprietary software and that the user will need to manually download the DISTFILES, possibly after registering for the software or agreeing to accept the terms of an EULA. <makevar>RESTRICTED_FILES</makevar> When RESTRICTED or NO_CDROM is set, this variable defaults to ${DISTFILES} ${PATCHFILES}, otherwise it is empty. If only some of the distribution files are restricted, then set this variable to list them. Note that the port committer should add an entry to /usr/ports/LEGAL for every listed distribution file, describing exactly what the restriction entails. Using <literal>perl</literal> Variables for ports that use <literal>perl</literal> Variable Means USE_PERL5 Says that the port uses perl 5 to build and run. USE_PERL5_BUILD Says that the port uses perl 5 to build. USE_PERL5_RUN Says that the port uses perl 5 to run. PERL The full path of perl 5, either in the system or installed from a port, but without the version number. Use this if you need to replace #!lines in scripts. PERL_CONFIGURE Configure using Perl's MakeMaker. It implies USE_PERL5. Read only variables PERL_VERSION The full version of perl installed (e.g., 5.00503). PERL_VER The short version of perl installed (e.g., 5.005). PERL_LEVEL The installed perl version as an integer of the form MNNNPP (e.g., 500503). PERL_ARCH Where perl stores architecture dependent libraries. Defaults to ${ARCH}-freebsd. PERL_PORT Name of the perl port that is installed (e.g., perl5). SITE_PERL Directory name where site specific perl packages go. This value is added to PLIST_SUB.
Using X11 Variables for ports that use X USE_X_PREFIX The port installs in X11BASE, not PREFIX. USE_XLIB The port uses the X libraries. USE_MOTIF The port uses the Motif toolkit. Implies USE_XPM. USE_IMAKE The port uses imake. Implies USE_X_PREFIX. XMKMF Set to the path of xmkmf if not in the PATH. Defaults to xmkmf -a.
Using <command>automake</command>, <command>autoconf</command>, and <command>libtool</command> Variables for ports that use automake, autoconf or libtool Variable Means AUTOMAKE The full path for automake if it is not in the PATH. USE_AUTOMAKE_VER The port uses automake. Valid values for this variable are 14 and 15, and sets the AUTOMAKE_DIR and ACLOCAL_DIR variables appropriately. AUTOMAKE_ARGS One or more command line arguments to pass to AUTOMAKE if USE_AUTOMAKE_VER is set. AUTOMAKE_ENV One or more environment variables to set (and their values) before running AUTOMAKE. ACLOCAL Set to the path of the GNU aclocal if it is not in the PATH. The default is set according to the USE_AUTOMAKE_VER variable. ACLOCAL_DIR Set to the path of the GNU aclocal shared directory. The default is set according to the USE_AUTOMAKE_VER variable. AUTOMAKE_DIR Set to the path of the GNU automake shared directory. The default is set according to the USE_AUTOMAKE_VER variable. USE_AUTOCONF_VER Specifies that the port uses autoconf. Implies GNU_CONFIGURE. The default value is 213. AUTOCONF Set to the path of GNU autoconf if it is not in the PATH. The default is set according to the USE_AUTOCONF_VER variable. AUTOCONF_ARGS Command line arguments to pass to autoconf. AUTOCONF_ENV Set these variable=value pairs in the environment before running autoconf. USE_AUTOHEADER_VER Specifies that the port uses autoheader. Implies USE_AUTOCONF_VER. The default value is 213. AUTOHEADER Set to the path of GNU autoheader if it is not in the PATH. The default is set according to USE_AUTOCONF_VER. AUTORECONF Set to the path of GNU autoreconf if it is not in the PATH. The default is set according to USE_AUTOCONF_VER. AUTOSCAN Set to the path of GNU autoscan if it is not set in the PATH. The default is set according to USE_AUTOCONF_VER. AUTOIFNAMES Set to the path of GNU autoifnames if it is not set in the PATH. The default is set according to USE_AUTOCONF_VER. USE_LIBTOOL_VER The port uses libtool. Implies GNU_CONFIGURE. The default value is 13. LIBTOOL Set to the path of libtool if it is not set in the PATH. LIBTOOLFILES The files to patch for libtool. Defaults to aclocal.m4 if USE_AUTOCONF is defined, configure otherwise. LIBTOOLFLAGS Additional flags to pass to ltconfig. Defaults to --disable-ltlibs.
Using GNOME The FreeBSD/GNOME project uses its own set of variables to define which GNOME components a particular port uses. A comprehensive list of these variables exists within the FreeBSD/GNOME project's homepage. Using KDE Variables for ports that use KDE USE_QT_VER The port uses the Qt toolkit. Possible values are 1 and 3; each specify the major version of Qt to use. Sets both MOC and QTCPPFLAGSto default appropriate values. USE_KDELIBS_VER The port uses KDE libraries. Possible values are 3; each specify the major version of KDE to use. Implies USE_QT_VER of the appropriate version. USE_KDEBASE_VER The port uses KDE base. Possible values are 3; each specify the major version of KDE to use. Implies USE_KDELIBS_VER of the appropriate version. MOC Set to the path of moc. Default set according to USE_QT_VER value. QTCPPFLAGS Set the CPPFLAGS to use when processing Qt code. Default set according to USE_QT_VER value.
Using Bison This section is yet to be written. Using Java Variable definitions If your port needs a Java™ Development Kit (JDK) to either build, run or even extract the distfile, then it should define USE_JAVA. There are several JDKs in the ports collection, from various vendors, and in several versions. If your port must use one of these versions, you can define which one. The most current version is java/jdk14. Variables that may be set by ports that use Java Variable Means USE_JAVA Should be defined for the remaining variables to have any effect. JAVA_VERSION List of space-separated suitable Java versions for the port. An optional "+" allows you to specify a range of versions (allowed values: 1.1[+] 1.2[+] 1.3[+] 1.4[+]). JAVA_OS List of space-separated suitable JDK port operating systems for the port (allowed values: native linux). JAVA_VENDOR List of space-separated suitable JDK port vendors for the port (allowed values: freebsd bsdjava sun ibm blackdown). JAVA_BUILD When set, it means that the selected JDK port should be added to the build dependencies of the port. JAVA_RUN When set, it means that the selected JDK port should be added to the run dependencies of the port. JAVA_EXTRACT When set, it means that the selected JDK port should be added to the extract dependencies of the port. USE_JIKES Whether the port should or should not use the jikes bytecode compiler to build. When no value is set for this variable, the port will use jikes to build if available. You may also explicitely forbid or enforce the use of jikes (by setting 'no' or 'yes'). In the later case, devel/jikes will be added to build dependencies of the port.
Below is the list of all settings a port will receive after setting USE_JAVA: Variables provided to ports that use Java Variable Value JAVA_PORT The name of the JDK port (e.g. 'java/jdk14'). JAVA_PORT_VERSION The full version of the JDK port (e.g. '1.4.2'). If you only need the first two digits of this version number, use ${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}. JAVA_PORT_OS The operating system used by the JDK port (e.g. 'linux'). JAVA_PORT_VENDOR The vendor of the JDK port (e.g. 'sun'). JAVA_PORT_OS_DESCRIPTION Description of the operating system used by the JDK port (e.g. 'Linux'). JAVA_PORT_VENDOR_DESCRIPTION Description of the vendor of the JDK port (e.g. 'FreeBSD Foundation'). JAVA_HOME Path to the installation directory of the JDK (e.g. '/usr/local/jdk1.3.1'). JAVAC Path to the Java compiler to use (e.g. '/usr/local/jdk1.1.8/bin/javac' or '/usr/local/bin/jikes'). JAR Path to the jar tool to use (e.g. '/usr/local/jdk1.2.2/bin/jar' or '/usr/local/bin/fastjar'). APPLETVIEWER Path to the appletviewer utility (e.g. '/usr/local/linux-jdk1.2.2/bin/appletviewer'). JAVA Path to the java executable. Use this for executing Java programs (e.g. '/usr/local/jdk1.3.1/bin/java'). JAVADOC Path to the javadoc utility program. JAVAH Path to the javah program. JAVAP Path to the javap program. JAVA_KEYTOOL Path to the keytool utility program. This variable is availble only if the JDK is Java 1.2 or higher. JAVA_N2A Path to the native2ascii tool. JAVA_POLICYTOOL Path to the policytool program. This variable is available only if the JDK is Java 1.2 or higher. JAVA_SERIALVER Path to the serialver utility program. RMIC Path to the RMI stub/skeleton generator, rmic. RMIREGISTRY Path to the RMI registry program, rmiregistry. RMID Path to the RMI daemon program rmid. This variable is only available if the JDK is Java 1.2 or higher. JAVA_CLASSES Path to the archive that contains the JDK class files. On JDK 1.2 or later, this is ${JAVA_HOME}/jre/lib/rt.jar. Earlier JDKs used ${JAVA_HOME}/lib/classes.zip.
You may use the java-debug make target to get information for debugging your port. It will display the value of many of the forecited variables. Additionally, the following constants are defined so all Java ports may be installed in a consistent way: Constants defined for ports that use Java Constant Value JAVASHAREDIR The base directory for everything related to Java. Default: ${PREFIX}/share/java. JAVAJARDIR The directory where JAR files should be installed. Default: ${JAVASHAREDIR}/classes.
Best practices When porting a Java library, your port should install the JAR file(s) in ${JAVAJARDIR}, and everything else under ${JAVASHAREDIR}/${PORTNAME} (except for the documentation, see below). In order to reduce the packing file size, you may reference the JAR file(s) directly in the Makefile. Just use the following statement (where myport.jar is the name of the JAR file installed as part of the port): PLIST_FILES+= ${JAVAJARDIR:S,^${PREFIX}/,,}/myport.jar When porting a Java application, the port usually installs everything under a single directory (including its JAR dependencies). The use of ${JAVASHAREDIR}/${PORTNAME} is strongly encouraged in this regard. It is up the porter to decide whether the port should install the additional JAR dependencies under this directory or directly use the already installed ones (from ${JAVAJARDIR}). Regardless of the type of your port (library or application), the additional documentation should be installed in the same location as for any other port. The JavaDoc tool is known to produce a different set of files depending on the version of the JDK that is used. For ports that do not enforce the use of a particular JDK, it is therefore a complex task to specify the packing list (pkg-plist). This is one reason why porters are strongly encouraged to use the PORTDOCS macro. Moreover, even if you can predict the set of files that will be generated by javadoc, the size of the resulting pkg-plist advocates for the use of PORTDOCS. The default value for DATADIR is ${PREFIX}/share/${PORTNAME}. It is a good idea to override DATADIR to ${JAVASHAREDIR}/${PORTNAME} for Java ports. Indeed, DATADIR is automatically addded to PLIST_SUB (documented here) so you may use %%DATADIR%% directly in pkg-plist. As for the choice of building Java ports from source or directly installing them from a binary distribution, there is no defined policy at the time of writing. However, people from the &os; Java Project encourage porters to have their ports built from source whenever it is a trivial task. All the features that have been presented in this section are implemented in bsd.java.mk. If you ever think that your port needs more sophisticated Java support, please first have a look at the bsd.java.mk CVS log as it usually takes some time to document the latest features. Then, if you think the support you are lacking would be beneficial to many other Java ports, feel free to discuss it on the &a.java;. Although there is a java category for PRs, it refers to the JDK porting effort from the &os; Java project. Therefore, you should submit your Java port in the ports category as for any other port, unless the issue you are trying to resolve is related to either a JDK implementation or bsd.java.mk. Using Python This section is yet to be written. Using Emacs This section is yet to be written. Using Ruby This section is yet to be written. Using SDL The USE_SDL variable is used to autoconfigure the dependencies for ports which use an SDL based library like devel/sdl12 and x11-toolkits/sdl_gui. The following SDL libraries are recognized at the moment: sdl: devel/sdl12 gfx: graphics/sdl_gfx gui: x11-toolkits/sdl_gui image: graphics/sdl_image ldbad: devel/sdl_ldbad mixer: audio/sdl_mixer mm: devel/sdlmm net: net/sdl_net sound: audio/sdl_sound ttf: graphics/sdl_ttf Therefore, if a port has a dependency on net/sdl_net and audio/sdl_mixer, the syntax will be: USE_SDL= net mixer The dependency devel/sdl12, which is required by net/sdl_net and audio/sdl_mixer, is automatically added as well. If you use USE_SDL, it will automatically: Add a dependency on sdl12-config to BUILD_DEPENDS Add the variable SDL_CONFIG to CONFIGURE_ENV Add the dependencies of the selected libraries to the LIB_DEPENDS To check whether an SDL library is available, you can do it with the WANT_SDL variable: WANT_SDL=yes .include <bsd.port.pre.mk> .if ${HAVE_SDL:Mmixer}!="" USE_SDL+= mixer .endif .include <bsd.port.post.mk> <makevar>MASTERDIR</makevar> If your port needs to build slightly different versions of packages by having a variable (for instance, resolution, or paper size) take different values, create one subdirectory per package to make it easier for users to see what to do, but try to share as many files as possible between ports. Typically you only need a very short Makefile in all but one of the directories if you use variables cleverly. In the sole Makefile, you can use MASTERDIR to specify the directory where the rest of the files are. Also, use a variable as part of PKGNAMESUFFIX so the packages will have different names. This will be best demonstrated by an example. This is part of japanese/xdvi300/Makefile; PORTNAME= xdvi PORTVERSION= 17 PKGNAMEPREFIX= ja- PKGNAMESUFFIX= ${RESOLUTION} : # default RESOLUTION?= 300 .if ${RESOLUTION} != 118 && ${RESOLUTION} != 240 && \ ${RESOLUTION} != 300 && ${RESOLUTION} != 400 @${ECHO} "Error: invalid value for RESOLUTION: \"${RESOLUTION}\"" @${ECHO} "Possible values are: 118, 240, 300 (default) and 400." @${FALSE} .endif japanese/xdvi300 also has all the regular patches, package files, etc. If you type make there, it will take the default value for the resolution (300) and build the port normally. As for other resolutions, this is the entire xdvi118/Makefile: RESOLUTION= 118 MASTERDIR= ${.CURDIR}/../xdvi300 .include "${MASTERDIR}/Makefile" (xdvi240/Makefile and xdvi400/Makefile are similar). The MASTERDIR definition tells bsd.port.mk that the regular set of subdirectories like FILESDIR and SCRIPTDIR are to be found under xdvi300. The RESOLUTION=118 line will override the RESOLUTION=300 line in xdvi300/Makefile and the port will be built with resolution set to 118. Shared library versions Please read our policy on shared library versioning to understand what to do with shared library versions in general. Do not blindly assume software authors know what they are doing; many of them do not. It is very important that these details are carefully considered, as we have quite a unique situation where we are trying to have dozens of potentially incompatible software pairs co-exist. Careless port imports have caused great trouble regarding shared libraries in the past (ever wondered why the port jpeg-6b has a shared library version of 9?). If in doubt, send a message to the &a.ports;. Most of the time, your job ends by determining the right shared library version and making appropriate patches to implement it. Manpages The MAN[1-9LN] variables will automatically add any manpages to pkg-plist (this means you must not list manpages in the pkg-plist—see generating PLIST for more). It also makes the install stage automatically compress or uncompress manpages depending on the setting of NOMANCOMPRESS in /etc/make.conf. If your port tries to install multiple names for manpages using symlinks or hardlinks, you must use the MLINKS variable to identify these. The link installed by your port will be destroyed and recreated by bsd.port.mk to make sure it points to the correct file. Any manpages listed in MLINKS must not be listed in the pkg-plist. To specify whether the manpages are compressed upon installation, use the MANCOMPRESSED variable. This variable can take three values, yes, no and maybe. yes means manpages are already installed compressed, no means they are not, and maybe means the software already respects the value of NOMANCOMPRESS so bsd.port.mk does not have to do anything special. MANCOMPRESSED is automatically set to yes if USE_IMAKE is set and NO_INSTALL_MANPAGES is not set, and to no otherwise. You do not have to explicitly define it unless the default is not suitable for your port. If your port anchors its man tree somewhere other than PREFIX, you can use the MANPREFIX to set it. Also, if only manpages in certain sections go in a non-standard place, such as some perl modules ports, you can set individual man paths using MANsectPREFIX (where sect is one of 1-9, L or N). If your manpages go to language-specific subdirectories, set the name of the languages to MANLANG. The value of this variable defaults to "" (i.e., English only). Here is an example that puts it all together. MAN1= foo.1 MAN3= bar.3 MAN4= baz.4 MLINKS= foo.1 alt-name.8 MANLANG= "" ja MAN3PREFIX= ${PREFIX}/share/foobar MANCOMPRESSED= yes This states that six files are installed by this port; ${PREFIX}/man/man1/foo.1.gz ${PREFIX}/man/ja/man1/foo.1.gz ${PREFIX}/share/foobar/man/man3/bar.3.gz ${PREFIX}/share/foobar/man/ja/man3/bar.3.gz ${PREFIX}/man/man4/baz.4.gz ${PREFIX}/man/ja/man4/baz.4.gz Additionally ${PREFIX}/man/man8/alt-name.8.gz may or may not be installed by your port. Regardless, a symlink will be made to join the foo(1) manpage and alt-name(8) manpage. Ports that require Motif There are many programs that require a Motif library (available from several commercial vendors, while there is a free clone reported to be able to run many applications in x11-toolkits/lesstif) to compile. Since it is a popular toolkit and their licenses usually permit redistribution of statically linked binaries, we have made special provisions for handling ports that require Motif in a way that we can easily compile binaries linked either dynamically (for people who are compiling from the port) or statically (for people who distribute packages). <makevar>USE_MOTIF</makevar> If your port requires Motif, define this variable in the Makefile. This will prevent people who do not own a copy of Motif from even attempting to build it. <makevar>MOTIFLIB</makevar> This variable will be set by bsd.port.mk to be the appropriate reference to the Motif library. Please patch the source of your port to reference this wherever the Motif library is referenced in the Makefile or Imakefile. There are two common cases: If the port refers to the Motif library as -lXm in its Makefile or Imakefile, simply substitute ${MOTIFLIB} for it. If the port uses XmClientLibs in its Imakefile, change it to ${MOTIFLIB} ${XTOOLLIB} ${XLIB}. Note that MOTIFLIB (usually) expands to -L/usr/X11R6/lib -lXm or /usr/X11R6/lib/libXm.a, so there is no need to add -L or -l in front. X11 fonts If your port installs fonts for the X Window System, put them in X11BASE/lib/X11/fonts/local. This directory was new to XFree86 3.3.3. If it does not exist, please create it, and print out a message urging the user to update their XFree86 to 3.3.3 or newer, or at least add this directory to the font path in /etc/XF86Config. Info files If your package needs to install GNU info files, they should be listed in the INFO variable (without the trailing .info), and appropriate installation/de-installation code will be automatically added to the temporary pkg-plist before package registration. The <filename>pkg-<replaceable>*</replaceable></filename> files There are some tricks we have not mentioned yet about the pkg-* files that come in handy sometimes. <filename>pkg-message</filename> If you need to display a message to the installer, you may place the message in pkg-message. This capability is often useful to display additional installation steps to be taken after a &man.pkg.add.1; or to display licensing information. The pkg-message file does not need to be added to pkg-plist. Also, it will not get automatically printed if the user is using the port, not the package, so you should probably display it from the post-install target yourself. <filename>pkg-install</filename> If your port needs to execute commands when the binary package is installed with &man.pkg.add.1; you can do this via the pkg-install script. This script will automatically be added to the package, and will be run twice by &man.pkg.add.1;: the first time as ${SH} pkg-install ${PKGNAME} PRE-INSTALL and the second time as ${SH} pkg-install ${PKGNAME} POST-INSTALL. $2 can be tested to determine which mode the script is being run in. The PKG_PREFIX environmental variable will be set to the package installation directory. See &man.pkg.add.1; for additional information. This script is not run automatically if you install the port with make install. If you are depending on it being run, you will have to explicitly call it from your port's Makefile. <filename>pkg-deinstall</filename> This script executes when a package is removed. This script will be run twice by &man.pkg.delete.1;. The first time as ${SH} pkg-install ${PKGNAME} DEINSTALL and the second time as ${SH} pkg-install ${PKGNAME} POST-DEINSTALL. <filename>pkg-req</filename> If your port needs to determine if it should install or not, you can create a pkg-req requirements script. It will be invoked automatically at installation/de-installation time to determine whether or not installation/de-installation should proceed. The script will be run at installation time by &man.pkg.add.1; as pkg-req ${PKGNAME} INSTALL. At de-installation time it will be run by &man.pkg.delete.1; as pkg-req ${PKGNAME} DEINSTALL. Changing <filename>pkg-plist</filename> based on make variables Some ports, particularly the p5- ports, need to change their pkg-plist depending on what options they are configured with (or version of perl, in the case of p5- ports). To make this easy, any instances in the pkg-plist of %%OSREL%%, %%PERL_VER%%, and %%PERL_VERSION%% will be substituted for appropriately. The value of %%OSREL%% is the numeric revision of the operating system (e.g., 4.9). %%PERL_VERSION%% is the full version number of perl (e.g., 5.00502) and %%PERL_VER%% is the perl version number minus the patchlevel (e.g., 5.005). Several other %%VARS%% related to port's documentation files are described in the relevant section. If you need to make other substitutions, you can set the PLIST_SUB variable with a list of VAR=VALUE pairs and instances of %%VAR%% will be substituted with VALUE in the pkg-plist. For instance, if you have a port that installs many files in a version-specific subdirectory, you can put something like OCTAVE_VERSION= 2.0.13 PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION} in the Makefile and use %%OCTAVE_VERSION%% wherever the version shows up in pkg-plist. That way, when you upgrade the port, you will not have to change dozens (or in some cases, hundreds) of lines in the pkg-plist. This substitution (as well as addition of any manual pages) will be done between the pre-install and do-install targets, by reading from PLIST and writing to TMPPLIST (default: WRKDIR/.PLIST.mktmp). So if your port builds PLIST on the fly, do so in or before pre-install. Also, if your port needs to edit the resulting file, do so in post-install to a file named TMPPLIST. Another possibility to modify port's packing list is based on setting the variables PLIST_FILES and PLIST_DIRS. The value of each variable is regarded as a list of pathnames to write to TMPPLIST along with PLIST contents. Names listed in PLIST_FILES and PLIST_DIRS are subject to %%VAR%% substitution, as described above. Except for that, names from PLIST_FILES will appear in the final packing list unchanged, while @dirrm will be prepended to names from PLIST_DIRS. To take effect, PLIST_FILES and PLIST_DIRS must be set before TMPPLIST is written, i.e. in pre-install or earlier. Changing the names of <filename>pkg-<replaceable>*</replaceable></filename> files All the names of pkg-* files are defined using variables so you can change them in your Makefile if need be. This is especially useful when you are sharing the same pkg-* files among several ports or have to write to one of the above files (see writing to places other than WRKDIR for why it is a bad idea to write directly into the pkg-* subdirectory). Here is a list of variable names and their default values. (PKGDIR defaults to ${MASTERDIR}.) Variable Default value DESCR ${PKGDIR}/pkg-descr PLIST ${PKGDIR}/pkg-plist PKGINSTALL ${PKGDIR}/pkg-install PKGDEINSTALL ${PKGDIR}/pkg-deinstall PKGREQ ${PKGDIR}/pkg-req PKGMESSAGE ${PKGDIR}/pkg-message Please change these variables rather than overriding PKG_ARGS. If you change PKG_ARGS, those files will not correctly be installed in /var/db/pkg upon install from a port. Testing your port Running <command>make describe</command> Several of the &os; port maintainance tools, such as &man.portupgrade.1;, rely on a database called /usr/ports/INDEX which keeps track of such items as port dependencies. INDEX is created by the top-level ports/Makefile via make index, which descends into each port subdirectory and executes make describe there. Thus, if make describe fails in any port, no one can generate INDEX, and many people will quickly become unhappy. It is important to be able to generate this file no matter what options are present in make.conf, so please avoid doing things such as using .error statements when (for instance) a dependency is not satisfied. How to avoid using <literal>.error</literal> Assume that someone has the line USE_POINTYHAT=yes in make.conf. The first of the next two Makefile snippets will cause make index to fail, while the second one will not: .if USE_POINTYHAT .error "POINTYHAT is not supported" .endif .if USE_POINTYHAT IGNORE=POINTYHAT is not supported .endif If make describe produces a string rather than an error message, you are probably safe. See bsd.port.mk for the meaning of the string produced. Also note that running a recent version of portlint (as specified in the next section) will cause make describe to be run automatically. Portlint Do check your work with portlint before you submit or commit it. portlint warns you about many common errors, both functional and stylistic. For a new (or repocopied) port, portlint -A is the most thorough; for an existing port, portlint -C is sufficient. Since portlint uses heuristics to try to figure out errors, it can produce false positive warnings. In addition, occasionally something that is flagged as a problem really cannot be done in any other way due to limitations in the ports framework. When in doubt, the best thing to do is ask on &a.ports;. <makevar>PREFIX</makevar> Do try to make your port install relative to PREFIX. (The value of this variable will be set to LOCALBASE (default /usr/local), unless USE_X_PREFIX or USE_IMAKE is set, in which case it will be X11BASE (default /usr/X11R6). Avoiding the hard-coding of /usr/local or /usr/X11R6 anywhere in the source will make the port much more flexible and able to cater to the needs of other sites. For X ports that use imake, this is automatic; otherwise, this can often be done by simply replacing the occurrences of /usr/local (or /usr/X11R6 for X ports that do not use imake) in the various scripts/Makefiles in the port to read ${PREFIX}, as this variable is automatically passed down to every stage of the build and install processes. Make sure your application is not installing things in /usr/local instead of PREFIX. A quick test for this is to do this is: &prompt.root; make clean; make package PREFIX=/var/tmp/port-name If anything is installed outside of PREFIX, the package creation process will complain that it cannot find the files. This does not test for the existence of internal references, or correct use of LOCALBASE for references to files from other ports. Testing the installation in /var/tmp/port-name to do that while you have it installed would do that. Do not set USE_X_PREFIX unless your port truly requires it (i.e., it links against X libs or it needs to reference files in X11BASE). The variable PREFIX can be reassigned in your Makefile or in the user's environment. However, it is strongly discouraged for individual ports to set this variable explicitly in the Makefiles. Also, refer to programs/files from other ports with the variables mentioned above, not explicit pathnames. For instance, if your port requires a macro PAGER to be the full pathname of less, use the compiler flag: -DPAGER=\"${PREFIX}/bin/less\" or -DPAGER=\"${LOCALBASE}/bin/less\" if this is an X port, instead of -DPAGER=\"/usr/local/bin/less\". This way it will have a better chance of working if the system administrator has moved the whole /usr/local tree somewhere else. Upgrading When you notice that a port is out of date compared to the latest version from the original authors, you should first ensure that you have the latest port. You can find them in the ports/ports-current directory of the &os; FTP mirror sites. However, if you are working with more than a few ports, you will probably find it easier to use CVSup to keep your whole ports collection up-to-date, as described in the Handbook. This will have the added benefit of tracking all the ports' dependencies. The next step is to see if there is an update already pending. To do this, you have two options. There is a searchable interface to the - + FreeBSD Problem Report (PR) database (also known as GNATS). Select ports in the dropdown, and enter the name of the port. However, sometimes people forget to put the name of the port into the Synopsis field in an unambiguous fashion. In that case, - you can try the + you can try the FreeBSD Ports Monitoring System (also known as portsmon). This system attempts to classify port PRs by portname. To search for PRs about a particular port, - use the + use the Overview of One Port. If there is no pending PR, the next step is to send an email to the port's maintainer, as shown by make maintainer. That person may already be working on an upgrade, or have a reason to not upgrade the port right now (because of, for example, stability problems of the new version); you would not want to duplicate their work. Note that unmaintained ports are listed with a maintainer of ports@FreeBSD.org, which is just the general ports mailing list, so sending mail there probably will not help in this case. If the maintainer asks you to do the upgrade or there is no maintainer, then you have a chance to help out &os; by preparing the update yourself! Please make the changes and save the result of the recursive diff output of the new and old ports directories (e.g., if your modified port directory is called superedit and the original is in our tree as superedit.bak, then save the result of diff -ruN superedit.bak superedit). Either unified or context diff is fine, but port committers generally prefer unified diffs. Note the use of the -N option—this is the accepted way to force diff to properly deal with the case of new files being added or old files being deleted. Before sending us the diff, please examine the output to make sure all the changes make sense. To simplify common operations with patch files, you can use /usr/ports/Tools/scripts/patchtool.py. Before using it, please read /usr/ports/Tools/scripts/README.patchtool. If the port is unmaintained, and you are actively using it yourself, please consider volunteering to become its maintainer. &os; has over 2000 ports without maintainers, and this is an area where more volunteers are always needed. (For a detailed description of the responsibilities of maintainers, refer to the MAINTAINER on Makefiles section.) The best way to send us the diff is by including it via &man.send-pr.1; (category ports). If you are volunteering to maintain the port, be sure to put [maintainer update] at the beginning of your synopsis line and set the Class of your PR to maintainer-update. Otherwise, the Class of your PR should be change-request. Please mention any added or deleted files in the message, as they have to be explicitly specified to &man.cvs.1; when doing a commit. If the diff is more than about 20KB, please compress and uuencode it; otherwise, just include it in the PR as is. Before you &man.send-pr.1;, you should review the Writing the problem report section in the Problem Reports article; it contains far more information about how to write useful problem reports. If your upgrade is motivated by security concerns or a serious fault in the currently committed port, please notify the &a.portmgr; to request immediate rebuilding and redistribution of your port's package. Unsuspecting users of &man.pkg.add.1; will otherwise continue to install the old version via pkg_add -r for several weeks. Once again, please use &man.diff.1; and not &man.shar.1; to send updates to existing ports! Now that you have done all that, you will want to read about how to keep up-to-date in . Ports security Why security is so important Bugs are occasionally introduced to the software. Arguably, the most dangerous of them are those opening security vulnerabilities. From the technical viewpoint, such vulnerabilities are to be closed by exterminating the bugs that caused them. However, the policies for handling mere bugs and security vulnerabilities are very different. A typical small bug affects only those users who have enabled some combination of options triggering the bug. The developer will eventually release a patch followed by a new version of the software, free of the bug, but the majority of users will not take the trouble of upgrading immediately because the bug has never vexed them. A critical bug that may cause data loss represents a graver issue. Nevertheless, prudent users know that a lot of possible accidents, besides software bugs, are likely to lead to data loss, and so they make backups of important data; in addition, a critical bug will be discovered really soon. A security vulnerability is all different. First, it may remain unnoticed for years because often it does not cause software malfunction. Second, a malicious party can use it to gain unauthorized access to a vulnerable system, to destroy or alter sensitive data; and in the worst case the user will not even notice the harm caused. Third, exposing a vulnerable system often assists attackers to break into other systems that could not be compromised otherwise. Therefore closing a vulnerability alone is not enough: the audience should be notified of it in most clear and comprehensive manner, which will allow to evaluate the danger and take appropriate actions. Fixing security vulnerabilities While on the subject of ports and packages, a security vulnerability may initially appear in the original distribution or in the port files. In the former case, the original software developer is likely to release a patch or a new version instantly, and you will only need to update the port promptly with respect to the author's fix. If the fix is delayed for some reason, you should either mark the port as FORBIDDEN or introduce a patch file of your own to the port. In the case of a vulnerable port, just fix the port as soon as possible. In either case, the standard procedure for submitting your change should be followed unless you have rights to commit it directly to the ports tree. Being a ports committer is not enough to commit to an arbitrary port. Remember that ports usually have maintainers, whom you should respect. Please make sure that the port's revision is bumped as soon as the vulnerability has been closed. That is how the users who upgrade installed packages on a regular basis will see they need to run an update. Besides, a new package will be built and distributed over FTP and WWW mirrors, replacing the vulnerable one. PORTREVISION should be bumped unless PORTVERSION has changed in the course of correcting the vulnerability. That is you should bump PORTREVISION if you have added a patch file to the port, but you should not if you have updated the port to the latest software version and thus already touched PORTVERSION. Please refer to the corresponding section for more information. Keeping the community informed The VuXML database A very important and urgent step to take as early as a security vulnerability is discovered is to notify the community of port users about the jeopardy. Such notification serves two purposes. First, should the danger be really severe, it will be wise to apply an instant workaround, e.g., stop the affected network service or even deinstall the port completely, until the vulnerability is closed. Second, a lot of users tend to upgrade installed packages just occasionally. They will know from the notification that they must update the package without delay as soon as a corrected version is available. Given the huge number of ports in the tree, a security advisory cannot be issued on each incident without creating a flood and losing the attention of the audience by the time it comes to really serious matters. Therefore security vulnerabilities found in ports are recorded in the FreeBSD VuXML database. The Security Officer Team members are monitoring it for issues requiring their intervention. If you have committer rights, you can update the VuXML database by yourself. So you will both help the Security Officer Team and deliver the crucial information to the community earlier. However, if you are not a committer, or you believe you have found an exceptionally severe vulnerability, or whatever, please do not hesitate to contact the Security Officer Team directly as described on the FreeBSD Security Information page. All right, you elected the hard way. As it may be obvious from its title, the VuXML database is essentially an XML document. Its source file vuln.xml is kept right inside the port security/vuxml. Therefore the file's full pathname will be PORTSDIR/security/vuxml/vuln.xml. Each time you discover a security vulnerability in a port, please add an entry for it to that file. Until you are familiar with VuXML, the best thing you can do is to find an existing entry fitting your case, then copy it and use as a template. A short introduction to VuXML The full-blown XML is complex and far beyond the scope of this book. However, to gain basic insight on the structure of a VuXML entry, you need only the notion of tags. XML tag names are enclosed in angle brackets. Each opening <tag> must have a matching closing </tag>. Tags may be nested. If nesting, the inner tags must be closed before the outer ones. There is a hierarchy of tags, i.e. more complex rules of nesting them. Sounds very similar to HTML, doesn't it? The major difference is that XML is eXtensible, i.e. based on defining custom tags. Due to its intrinsic structure, XML puts otherwise amorphous data into shape. VuXML is particularly tailored to mark up descriptions of security vulnerabilities. Now let's consider a realistic VuXML entry: <vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <topic>Several vulnerabilities found in Foo</topic> <affects> <package> <name>foo</name> <name>foo-devel</name> <name>ja-foo</name> <range><ge>1.6</ge><lt>1.9</lt></range> <range><ge>2.*</ge><lt>2.4_1</lt></range> <range><eq>3.0b1</eq></range> </package> <package> <name>openfoo</name> <range><lt>1.10_7</lt></range> <range><ge>1.2,1</ge><lt>1.3_1,1</lt></range> </package> </affects> <description> <body xmlns="http://www.w3.org/1999/xhtml"> <p>J. Random Hacker reports:</p> <blockquote cite="http://j.r.hacker.com/advisories/1"> <p>Several issues in the Foo software may be exploited via carefully crafted QUUX requests. These requests will permit the injection of Bar code, mumble theft, and the readability of the Foo administrator account.</p> </blockquote> </body> </description> <references> <freebsdsa>SA-10:75.foo</freebsdsa> <freebsdpr>ports/987654</freebsdpr> <cvename>CAN-2010-0201</cvename> <cvename>CAN-2010-0466</cvename> <bid>96298</bid> <certsa>CA-2010-99</certsa> <certvu>740169</certvu> <uscertsa>SA10-99A</uscertsa> <uscertta>SA10-99A</uscertta> <mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist> <url>http://j.r.hacker.com/advisories/1</url> </references> <dates> <discovery>2010-05-25</discovery> <entry>2010-07-13</entry> <modified>2010-09-17</entry> </dates> </vuln> The tag names are supposed to be self-descriptive, so we shall take a closer look only at fields you will need to fill in by yourself: This is the top-level tag of a VuXML entry. It has a mandatory attribute, vid, specifying a universally unique identifier (UUID) for this entry (in quotes). You should generate a UUID for each new VuXML entry (and don't forget to substitute it for the template UUID unless you are writing the entry from scratch). You can use &man.uuidgen.1; in FreeBSD 5.x, or you may install the port devel/p5-Data-UUID and issue the following command: perl -MData::UUID -le 'print lc new Data::UUID->create_str' This is a one-line description of the issue found. The names of packages affected are listed there. Multiple names can be given since several packages may be based on a single master port or software product. This may include stable and development branches, localized versions, and slave ports featuring different choices of important build-time configuration options. It is your resposibility to find all such related packages when writing a VuXML entry. Keep in mind that make search name=foo is your friend. The primary points to look for are as follows: the foo-devel variant for a foo port; other variants with a suffix like -a4 (for print-related packages), -without-gui (for packages with X support disabled), or similar; jp-, ru-, zh-, and other possible localized variants in the corresponding national categories of the ports collection. Affected versions of the package(s) are specified there as one or more ranges using a combination of <lt>, <le>, <eq>, <ge>, and <gt> elements. The version ranges given should not overlap. In a range specification, * (asterisk) denotes the smallest version number. In particular, 2.* is less than 2.a. Therefore an asterisk may be used for a range to match all possible alpha, beta, and RC versions. For instance, <ge>2.*</ge><lt>3.*</lt> will selectively match every 2.x version while <ge>2.0</ge><lt>3.0</lt> will obviously not since the latter misses 2.r3 and matches 3.b. The above example specifies that affected are versions from 1.6 to 1.9 inclusive, versions 2.x before 2.4_1, and version 3.0b1. Several related package groups (essentially, ports) can be listed in the <affected> section. This can be used if several software products (say FooBar, FreeBar and OpenBar) grow from the same code base and still share its bugs and vulnerabilities. Note the difference from listing multiple names within a single <package> section. The version ranges should allow for PORTEPOCH and PORTREVISION if applicable. Please remember that according to the collation rules, a version with a non-zero PORTEPOCH is greater than any version without PORTEPOCH, e.g., 3.0,1 is greater than 3.1 or even than 8.9. This is a summary of the issue. XHTML is used in this field. At least enclosing <p> and </p> should appear. More complex mark-up may be used, but only for the sake of accuracy and clarity: No eye candy please. This section contains references to relevant documents. As many references as apply are encouraged. This is a FreeBSD security advisory. This is a FreeBSD problem report. This is a Mitre CVE identifier. This is a SecurityFocus Bug ID. This is a US-CERT security advisory. This is a US-CERT vulnerability note. This is a US-CERT Cyber Security Alert. This is a US-CERT Technical Cyber Security Alert. This is a URL to an archived posting in a mailing list. The attribute msgid is optional and may specify the message ID of the posting. This is a generic URL. It should be used only if none of the other reference categories apply. This is the date when the issue was disclosed (YYYY-MM-DD). This is the date when the entry was added (YYYY-MM-DD). This is the date when any information in the entry was last modified (YYYY-MM-DD). New entries must not include this field. It should be added upon editing an existing entry. Testing your changes to the VuXML database Assume you just wrote or filled in an entry for a vulnerability in the package clamav that has been fixed in version 0.65_7. As a prerequisite, you need to install fresh versions of the ports security/portaudit and security/portaudit-db. First, check whether there already is an entry for this vulnerability. If there were such entry, it would match the previous version of the package, 0.65_6: &prompt.user; packaudit &prompt.user; portaudit clamav-0.65_6 To run packaudit, you must have permission to write to its DATABASEDIR, typically /var/db/portaudit. If there is none found, you get the green light to add a new entry for this vulnerability. Now you can generate a brand-new UUID (assume it's 74a9541d-5d6c-11d8-80e3-0020ed76ef5a) and add your new entry to the VuXML database. Please verify its syntax after that as follows: &prompt.user; cd ${PORTSDIR}/security/vuxml && make validate You will need at least one of the following packages installed: textproc/libxml2, textproc/jade. Now rebuild the portaudit database from the VuXML file: &prompt.user; packaudit To verify that the <affected> section of your entry will match correct package(s), issue the following command: &prompt.user; portaudit -f /usr/ports/INDEX -r 74a9541d-5d6c-11d8-80e3-0020ed76ef5a Please refer to &man.portaudit.1; for better understanding of the command syntax. Make sure that your entry produces no spurious matches in the output. Now check whether the right package versions are matched by your entry: &prompt.user; portaudit clamav-0.65_6 clamav-0.65_7 Affected package: clamav-0.65_6 (matched by clamav<0.65_7) Type of problem: clamav remote denial-of-service. Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html> 1 problem(s) found. Obviously, the former version should match while the latter one should not. Finally, verify whether the web page generated from the VuXML database looks like expected: &prompt.user; mkdir -p ~/public_html/portaudit &prompt.user; packaudit &prompt.user; lynx ~/public_html/portaudit/74a9541d-5d6c-11d8-80e3-0020ed76ef5a.html If VuXML still scares you... As an easy alternative to writing VuXML, you may opt to add a single line to a different file with much simpler syntax, PORTSDIR/security/portaudit-db/database/portaudit.txt, which resides within the port security/portaudit-db, and send a request for review to the Security Officer Team as described on the FreeBSD Security Information page. A line in that file consists of four fields separated by |, a pipe character. The first field is a &man.pkg.version.1; pattern expression matching the vulnerable packages. The second field contains URLs to relevant information, separated by space characters. The third field is a one-line description of the issue. The fourth and last field is the entry's UUID. You may want take a closer look at existing entries in portaudit.txt before adding your first line to that file. Dos and Don'ts Introduction Here is a list of common dos and don'ts that you encounter during the porting process. You should check your own port against this list, but you can also check ports in the PR database that others have submitted. Submit any comments on ports you check as described in Bug Reports and General Commentary. Checking ports in the PR database will both make it faster for us to commit them, and prove that you know what you are doing. Stripping Binaries Do not strip binaries manually unless you have to. All binaries should be stripped, but the INSTALL_PROGRAM macro will install and strip a binary at the same time (see the next section). If you need to strip a file, but do not wish to use the INSTALL_PROGRAM macro, ${STRIP_CMD} will strip your program. This is typically done within the post-install target. For example: post-install: ${STRIP_CMD} ${PREFIX}/bin/xdl Use the &man.file.1; command on the installed executable to check whether the binary is stripped or not. If it does not say not stripped, it is stripped. Additionally, &man.strip.1; will not strip a previously stripped program; it will instead exit cleanly. INSTALL_* macros Do use the macros provided in bsd.port.mk to ensure correct modes and ownership of files in your own *-install targets. INSTALL_PROGRAM is a command to install binary executables. INSTALL_SCRIPT is a command to install executable scripts. INSTALL_DATA is a command to install sharable data. INSTALL_MAN is a command to install manpages and other documentation (it does not compress anything). These are basically the install command with all the appropriate flags. See below for an example on how to use them. <makevar>WRKDIR</makevar> Do not write anything to files outside WRKDIR. WRKDIR is the only place that is guaranteed to be writable during the port build (see installing ports from a CDROM for an example of building ports from a read-only tree). If you need to modify one of the pkg-* files, do so by redefining a variable, not by writing over it. <makevar>WRKDIRPREFIX</makevar> Make sure your port honors WRKDIRPREFIX. Most ports do not have to worry about this. In particular, if you are referring to a WRKDIR of another port, note that the correct location is WRKDIRPREFIXPORTSDIR/subdir/name/work not PORTSDIR/subdir/name/work or .CURDIR/../../subdir/name/work or some such. Also, if you are defining WRKDIR yourself, make sure you prepend ${WRKDIRPREFIX}${.CURDIR} in the front. Differentiating operating systems and OS versions You may come across code that needs modifications or conditional compilation based upon what version of Unix it is running under. If you need to make such changes to the code for conditional compilation, make sure you make the changes as general as possible so that we can back-port code to older FreeBSD systems and cross-port to other BSD systems such as 4.4BSD from CSRG, BSD/386, 386BSD, NetBSD, and OpenBSD. The preferred way to tell 4.3BSD/Reno (1990) and newer versions of the BSD code apart is by using the BSD macro defined in <sys/param.h>. Hopefully that file is already included; if not, add the code: #if (defined(__unix__) || defined(unix)) && !defined(USG) #include <sys/param.h> #endif to the proper place in the .c file. We believe that every system that defines these two symbols has sys/param.h. If you find a system that does not, we would like to know. Please send mail to the &a.ports;. Another way is to use the GNU Autoconf style of doing this: #ifdef HAVE_SYS_PARAM_H #include <sys/param.h> #endif Do not forget to add -DHAVE_SYS_PARAM_H to the CFLAGS in the Makefile for this method. Once you have sys/param.h included, you may use: #if (defined(BSD) && (BSD >= 199103)) to detect if the code is being compiled on a 4.3 Net2 code base or newer (e.g. FreeBSD 1.x, 4.3/Reno, NetBSD 0.9, 386BSD, BSD/386 1.1 and below). Use: #if (defined(BSD) && (BSD >= 199306)) to detect if the code is being compiled on a 4.4 code base or newer (e.g. FreeBSD 2.x, 4.4, NetBSD 1.0, BSD/386 2.0 or above). The value of the BSD macro is 199506 for the 4.4BSD-Lite2 code base. This is stated for informational purposes only. It should not be used to distinguish between versions of FreeBSD based only on 4.4-Lite vs. versions that have merged in changes from 4.4-Lite2. The __FreeBSD__ macro should be used instead. Use sparingly: __FreeBSD__ is defined in all versions of FreeBSD. Use it if the change you are making only affects FreeBSD. Porting gotchas like the use of sys_errlist[] vs strerror() are Berkeley-isms, not FreeBSD changes. In FreeBSD 2.x, __FreeBSD__ is defined to be 2. In earlier versions, it is 1. Later versions always bump it to match their major version number. If you need to tell the difference between a FreeBSD 1.x system and a FreeBSD 2.x or above system, usually the right answer is to use the BSD macros described above. If there actually is a FreeBSD specific change (such as special shared library options when using ld) then it is OK to use __FreeBSD__ and #if __FreeBSD__ > 1 to detect a FreeBSD 2.x and later system. If you need more granularity in detecting FreeBSD systems since 2.0-RELEASE you can use the following: #if __FreeBSD__ >= 2 #include <osreldate.h> # if __FreeBSD_version >= 199504 /* 2.0.5+ release specific code here */ # endif #endif In the hundreds of ports that have been done, there have only been one or two cases where __FreeBSD__ should have been used. Just because an earlier port screwed up and used it in the wrong place does not mean you should do so too. __FreeBSD_version values Here is a convenient list of __FreeBSD_version values as defined in sys/param.h: __FreeBSD_version values Release __FreeBSD_version 2.0-RELEASE 119411 2.1-CURRENT 199501, 199503 2.0.5-RELEASE 199504 2.2-CURRENT before 2.1 199508 2.1.0-RELEASE 199511 2.2-CURRENT before 2.1.5 199512 2.1.5-RELEASE 199607 2.2-CURRENT before 2.1.6 199608 2.1.6-RELEASE 199612 2.1.7-RELEASE 199612 2.2-RELEASE 220000 2.2.1-RELEASE 220000 (no change) 2.2-STABLE after 2.2.1-RELEASE 220000 (no change) 2.2-STABLE after texinfo-3.9 221001 2.2-STABLE after top 221002 2.2.2-RELEASE 222000 2.2-STABLE after 2.2.2-RELEASE 222001 2.2.5-RELEASE 225000 2.2-STABLE after 2.2.5-RELEASE 225001 2.2-STABLE after ldconfig -R merge 225002 2.2.6-RELEASE 226000 2.2.7-RELEASE 227000 2.2-STABLE after 2.2.7-RELEASE 227001 2.2-STABLE after &man.semctl.2; change 227002 2.2.8-RELEASE 228000 2.2-STABLE after 2.2.8-RELEASE 228001 3.0-CURRENT before &man.mount.2; change 300000 3.0-CURRENT after &man.mount.2; change 300001 3.0-CURRENT after &man.semctl.2; change 300002 3.0-CURRENT after ioctl arg changes 300003 3.0-CURRENT after ELF conversion 300004 3.0-RELEASE 300005 3.0-CURRENT after 3.0-RELEASE 300006 3.0-STABLE after 3/4 branch 300007 3.1-RELEASE 310000 3.1-STABLE after 3.1-RELEASE 310001 3.1-STABLE after C++ constructor/destructor order change 310002 3.2-RELEASE 320000 3.2-STABLE 320001 3.2-STABLE after binary-incompatible IPFW and socket changes 320002 3.3-RELEASE 330000 3.3-STABLE 330001 3.3-STABLE after adding &man.mkstemp.3; to libc 330002 3.4-RELEASE 340000 3.4-STABLE 340001 3.5-RELEASE 350000 3.5-STABLE 350001 4.0-CURRENT after 3.4 branch 400000 4.0-CURRENT after change in dynamic linker handling 400001 4.0-CURRENT after C++ constructor/destructor order change 400002 4.0-CURRENT after functioning &man.dladdr.3; 400003 4.0-CURRENT after __deregister_frame_info dynamic linker bug fix (also 4.0-CURRENT after EGCS 1.1.2 integration) 400004 4.0-CURRENT after &man.suser.9; API change (also 4.0-CURRENT after newbus) 400005 4.0-CURRENT after cdevsw registration change 400006 4.0-CURRENT after the addition of so_cred for socket level credentials 400007 4.0-CURRENT after the addition of a poll syscall wrapper to libc_r 400008 4.0-CURRENT after the change of the kernel's dev_t type to struct specinfo pointer 400009 4.0-CURRENT after fixing a hole in &man.jail.2; 400010 4.0-CURRENT after the sigset_t datatype change 400011 4.0-CURRENT after the cutover to the GCC 2.95.2 compiler 400012 4.0-CURRENT after adding pluggable linux-mode ioctl handlers 400013 4.0-CURRENT after importing OpenSSL 400014 4.0-CURRENT after the C++ ABI change in GCC 2.95.2 from -fvtable-thunks to -fno-vtable-thunks by default 400015 4.0-CURRENT after importing OpenSSH 400016 4.0-RELEASE 400017 4.0-STABLE after 4.0-RELEASE 400018 4.0-STABLE after the introduction of delayed checksums. 400019 4.0-STABLE after merging libxpg4 code into libc. 400020 4.0-STABLE after upgrading Binutils to 2.10.0, ELF branding changes, and tcsh in the base system. 400021 4.1-RELEASE 410000 4.1-STABLE after 4.1-RELEASE 410001 4.1-STABLE after &man.setproctitle.3; moved from libutil to libc. 410002 4.1.1-RELEASE 411000 4.1.1-STABLE after 4.1.1-RELEASE 411001 4.2-RELEASE 420000 4.2-STABLE after combining libgcc.a and libgcc_r.a, and associated GCC linkage changes. 420001 4.3-RELEASE 430000 4.3-STABLE after wint_t introduction. 430001 4.3-STABLE after PCI powerstate API merge. 430002 4.4-RELEASE 440000 4.4-STABLE after d_thread_t introduction. 440001 4.4-STABLE after mount structure changes (affects filesystem klds). 440002 4.4-STABLE after the userland components of smbfs were imported. 440003 4.5-RELEASE 450000 4.5-STABLE after the usb structure element rename. 450001 4.5-STABLE after the sendmail_enable &man.rc.conf.5; variable was made to take the value NONE. 450004 4.5-STABLE after moving to XFree86 4 by default for package builds. 450005 4.5-STABLE after accept filtering was fixed so that is no longer susceptible to an easy DoS. 450006 4.6-RELEASE 460000 4.6-STABLE &man.sendfile.2; fixed to comply with documentation, not to count any headers sent against the amount of data to be sent from the file. 460001 4.6.2-RELEASE 460002 4.6-STABLE 460100 4.6-STABLE after MFC of `sed -i'. 460101 4.6-STABLE after MFC of many new pkg_install features from the HEAD. 460102 4.7-RELEASE 470000 4.7-STABLE 470100 Start generated __std{in,out,err}p references rather than __sF. This changes std{in,out,err} from a compile time expression to a runtime one. 470101 4.7-STABLE after MFC of mbuf changes to replace m_aux mbufs by m_tag's 470102 4.7-STABLE gets OpenSSL 0.9.7 470103 4.8-RELEASE 480000 4.8-STABLE 480100 4.8-STABLE after &man.realpath.3; has been made thread-safe 480101 4.8-STABLE 3ware API changes to twe. 480102 4.9-RELEASE 490000 4.9-STABLE 490100 4.9-STABLE after e_sid was added to struct kinfo_eproc. 490101 4.9-STABLE after MFC of libmap functionality for rtld. 490102 4.10-RELEASE 491000 4.10-STABLE 491100 5.0-CURRENT 500000 5.0-CURRENT after adding addition ELF header fields, and changing our ELF binary branding method. 500001 5.0-CURRENT after kld metadata changes. 500002 5.0-CURRENT after buf/bio changes. 500003 5.0-CURRENT after binutils upgrade. 500004 5.0-CURRENT after merging libxpg4 code into libc and after TASKQ interface introduction. 500005 5.0-CURRENT after the addition of AGP interfaces. 500006 5.0-CURRENT after Perl upgrade to 5.6.0 500007 5.0-CURRENT after the update of KAME code to 2000/07 sources. 500008 5.0-CURRENT after ether_ifattach() and ether_ifdetach() changes. 500009 5.0-CURRENT after changing mtree defaults back to original variant, adding -L to follow symlinks. 500010 5.0-CURRENT after kqueue API changed. 500011 5.0-CURRENT after &man.setproctitle.3; moved from libutil to libc. 500012 5.0-CURRENT after the first SMPng commit. 500013 5.0-CURRENT after <sys/select.h> moved to <sys/selinfo.h>. 500014 5.0-CURRENT after combining libgcc.a and libgcc_r.a, and associated GCC linkage changes. 500015 5.0-CURRENT after change allowing libc and libc_r to be linked together, deprecating -pthread option. 500016 5.0-CURRENT after switch from struct ucred to struct xucred to stabilize kernel-exported API for mountd et al. 500017 5.0-CURRENT after addition of CPUTYPE make variable for controlling CPU-specific optimizations. 500018 5.0-CURRENT after moving machine/ioctl_fd.h to sys/fdcio.h 500019 5.0-CURRENT after locale names renaming. 500020 5.0-CURRENT after Bzip2 import. Also signifies removal of S/Key. 500021 5.0-CURRENT after SSE support. 500022 5.0-CURRENT after KSE Milestone 2. 500023 5.0-CURRENT after d_thread_t, and moving UUCP to ports. 500024 5.0-CURRENT after ABI change for descriptor and creds passing on 64 bit platforms. 500025 5.0-CURRENT after moving to XFree86 4 by default for package builds, and after the new libc strnstr() function was added. 500026 5.0-CURRENT after the new libc strcasestr() function was added. 500027 5.0-CURRENT after the userland components of smbfs were imported. 500028 5.0-CURRENT after the new C99 specific-width integer types were added. (Not incremented.) 5.0-CURRENT after a change was made in the return value of &man.sendfile.2;. 500029 5.0-CURRENT after the introduction of the type fflags_t, which is the appropriate size for file flags. 500030 5.0-CURRENT after the usb structure element rename. 500031 5.0-CURRENT after the introduction of Perl 5.6.1. 500032 5.0-CURRENT after the sendmail_enable &man.rc.conf.5; variable was made to take the value NONE. 500033 5.0-CURRENT after mtx_init() grew a third argument. 500034 5.0-CURRENT with Gcc 3.1. 500035 5.0-CURRENT without Perl in /usr/src 500036 5.0-CURRENT after the addition of &man.dlfunc.3; 500037 5.0-CURRENT after the types of some struct sockbuf members were changed and the structure was reordered. 500038 5.0-CURRENT after headers stopped using _BSD_FOO_T_ and started using _FOO_T_DECLARED. This value can also be used as a conservative estimate of the start of &man.bzip2.1; package support. 500039 5.0-CURRENT after various changes to disk functions were made in the name of removing dependency on disklabel structure internals. 500040 5.0-CURRENT after the addition of &man.getopt.long.3; to libc. 500041 5.0-CURRENT after Binutils 2.13 upgrade, which included new FreeBSD emulation, vec, and output format. 500042 5.0-CURRENT after adding weak pthread_XXX stubs to libc, obsoleting libXThrStub.so. 5.0-RELEASE. 500043 5.0-CURRENT after branching for RELENG_5_0 500100 <sys/dkstat.h> is empty and should not be included. 500101 5.0-CURRENT after the d_mmap_t interface change. 500102 5.0-CURRENT after taskqueue_swi changed to run without Giant, and taskqueue_swi_giant added to run with Giant. 500103 cdevsw_add() and cdevsw_remove() no longer exists. Appearance of MAJOR_AUTO allocation facility. 500104 5.0-CURRENT after new cdevsw initialization method. 500105 devstat_add_entry() has been replaced by devstat_new_entry() 500106 Devstat interface change; see sys/sys/param.h 1.149 500107 Token-Ring interface changes. 500108 Addition of vm_paddr_t. 500109 5.0-CURRENT after &man.realpath.3; has been made thread-safe 500110 5.0-CURRENT after &man.usbhid.3; has been synced with NetBSD 500111 5.0-CURRENT after new NSS implementation and addition of POSIX.1 getpw*_r, getgr*_r functions 500112 5.0-CURRENT after removal of the old rc system. 500113 5.1-RELEASE. 501000 5.1-CURRENT after branching for RELENG_5_1. 501100 5.1-CURRENT after correcting the semantics of sigtimedwait(2) and sigwaitinfo(2). 501101 5.1-CURRENT after adding the lockfunc and lockfuncarg fields to &man.bus.dma.tag.create.9;. 501102 5.1-CURRENT after GCC 3.3.1-pre 20030711 snapshot integration. 501103 5.1-CURRENT 3ware API changes to twe. 501104 5.1-CURRENT dynamically-linked /bin and /sbin support and movement of libraries to /lib. 501105 5.1-CURRENT after adding kernel support for Coda 6.x. 501106 5.1-CURRENT after 16550 UART constants moved from <dev/sio/sioreg.h> to <dev/ic/ns16550.h>. Also when libmap functionality was unconditionally supported by rtld. 501107 5.1-CURRENT after PFIL_HOOKS API update 501108 5.1-CURRENT after adding kiconv(3) 501109 5.1-CURRENT after changing default operations for open and close in cdevsw 501110 5.1-CURRENT after changed layout of cdevsw 501111 5.1-CURRENT after adding kobj multiple inheritance 501112 5.1-CURRENT after the if_xname change in struct ifnet 501113 5.1-CURRENT after changing /bin and /sbin to be dynamically linked 501114 5.2-RELEASE 502000 5.2.1-RELEASE 502010 5.2-CURRENT after branching for RELENG_5_2 502100 5.2-CURRENT after __cxa_atexit/__cxa_finalize functions were added to libc. 502101 5.2-CURRENT after change of default thread library from libc_r to libpthread. 502102 5.2-CURRENT after device driver API megapatch. 502103 5.2-CURRENT after getopt_long_only() addition. 502104 5.2-CURRENT after NULL is made into ((void *)0) for C, creating more warnings. 502105 5.2-CURRENT after pf is linked to the build and install. 502106 5.2-CURRENT after time_t is changed to a 64-bit value on sparc64. 502107 5.2-CURRENT after Intel C/C++ compiler support in some headers and execve(2) changes to be more strictly conforming to POSIX. 502108 5.2-CURRENT after the introduction of the bus_alloc_resource_any API 502109 5.2-CURRENT after the addition of UTF-8 locales 502110 5.2-CURRENT after the removal of the getvfsent(3) API 502111 5.2-CURRENT after the addition of the .warning directive for make. 502112 5.2-CURRENT after ttyioctl() was made mandatory for serial drivers. 502113 5.2-CURRENT after import of the ALTQ framework. 502114 5.2-CURRENT after changing sema_timedwait(9) to return 0 on success and a non-zero error code on failure. 502115 5.2-CURRENT after changing kernel dev_t to be pointer to struct cdev *. 502116 5.2-CURRENT after changing kernel udev_t to dev_t. 502117 5.2-CURRENT after adding support for CLOCK_VIRTUAL and CLOCK_PROF to clock_gettime(2) and clock_getres(2). 502118 5.2-CURRENT after changing network interface cloning overhaul. 502119 5.2-CURRENT after the update of the package tools to revision 20040629. 502120 5.2-CURRENT after marking Bluetooth code as non-i386 specific. 502121 5.2-CURRENT after the introduction of the KDB debugger framework, the conversion of DDB into a backend and the introduction of the GDB backend. 502122 5.2-CURRENT after change to make VFS_ROOT take a struct thread argument as does vflush. Struct kinfo_proc now has a user data pointer. The switch of the default X implementation to xorg was also made at this time. 502123 5.2-CURRENT after the change to separate the way ports rc.d and legacy scripts are started. 502124 5.2-CURRENT after the backout of the previous change. 502125 5.2-CURRENT after the removal of kmem_alloc_pageable() and the import of gcc 3.4.2. 502126 5.2-CURRENT after the change of the vfs_mount signature as well as global replacement of PRISON_ROOT with SUSER_ALLOWJAIL for the suser(9) API. 502127
Note that 2.2-STABLE sometimes identifies itself as 2.2.5-STABLE after the 2.2.5-RELEASE. The pattern used to be year followed by the month, but we decided to change it to a more straightforward major/minor system starting from 2.2. This is because the parallel development on several branches made it infeasible to classify the releases simply by their real release dates. If you are making a port now, you do not have to worry about old -CURRENTs; they are listed here just for your reference. Writing something after <filename>bsd.port.mk</filename> Do not write anything after the .include <bsd.port.mk> line. It usually can be avoided by including bsd.port.pre.mk somewhere in the middle of your Makefile and bsd.port.post.mk at the end. You need to include either the bsd.port.pre.mk/bsd.port.post.mk pair or bsd.port.mk only; do not mix these two usages. bsd.port.pre.mk only defines a few variables, which can be used in tests in the Makefile, bsd.port.post.mk defines the rest. Here are some important variables defined in bsd.port.pre.mk (this is not the complete list, please read bsd.port.mk for the complete list). Variable Description ARCH The architecture as returned by uname -m (e.g., i386) OPSYS The operating system type, as returned by uname -s (e.g., FreeBSD) OSREL The release version of the operating system (e.g., 2.1.5 or 2.2.7) OSVERSION The numeric version of the operating system; the same as __FreeBSD_version. PORTOBJFORMAT The object format of the system (elf or aout; note that for modern versions of FreeBSD, aout is deprecated.) LOCALBASE The base of the local tree (e.g., /usr/local/) X11BASE The base of the X11 tree (e.g., /usr/X11R6) PREFIX Where the port installs itself (see more on PREFIX). If you have to define the variables USE_IMAKE, USE_X_PREFIX, or MASTERDIR, do so before including bsd.port.pre.mk. Here are some examples of things you can write after bsd.port.pre.mk: # no need to compile lang/perl5 if perl5 is already in system .if ${OSVERSION} > 300003 BROKEN= perl is in system .endif # only one shlib version number for ELF .if ${PORTOBJFORMAT} == "elf" TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR} .else TCL_LIB_FILE= ${TCL_LIB}.${SHLIB_MAJOR}.${SHLIB_MINOR} .endif # software already makes link for ELF, but not for a.out post-install: .if ${PORTOBJFORMAT} == "aout" ${LN} -sf liblinpack.so.1.0 ${PREFIX}/lib/liblinpack.so .endif You did remember to use tab instead of spaces after BROKEN= and TCL_LIB_FILE=, did you not? :-). Install additional documentation If your software has some documentation other than the standard man and info pages that you think is useful for the user, install it under PREFIX/share/doc. This can be done, like the previous item, in the post-install target. Create a new directory for your port. The directory name should reflect what the port is. This usually means PORTNAME. However, if you think the user might want different versions of the port to be installed at the same time, you can use the whole PKGNAME. Make the installation dependent on the variable NOPORTDOCS so that users can disable it in /etc/make.conf, like this: post-install: .if !defined(NOPORTDOCS) ${MKDIR} ${DOCSDIR} ${INSTALL_MAN} ${WRKSRC}/docs/xvdocs.ps ${DOCSDIR} .endif Here are some handy variables and how they are expanded by default when used in the Makefile: DATADIR gets expanded to PREFIX/share/PORTNAME. DOCSDIR gets expanded to PREFIX/share/doc/PORTNAME. EXAMPLESDIR gets expanded to PREFIX/share/examples/PORTNAME. These variables are exported to PLIST_SUB. Their values will appear there as pathnames relative to PREFIX if possible. That is, share/doc/PORTNAME will be substituted for %%DOCSDIR%% in the packing list by default, and so on. (See more on pkg-plist substitution here.) All documentation files and directories installed should be included in pkg-plist with the %%PORTDOCS%% prefix, for example: %%PORTDOCS%%%%DOCSDIR%%/AUTHORS %%PORTDOCS%%%%DOCSDIR%%/CONTACT %%PORTDOCS%%@dirrm %%DOCSDIR%% As an alternative to enumerating the documentation files in pkg-plist, a port can set the variable PORTDOCS to a list of file names and shell glob patterns to add to the final packing list. The names will be relative to DOCSDIR. Therefore, a port that utilizes PORTDOCS and uses a non-default location for its documentation should set DOCSDIR accordingly. If a directory is listed in PORTDOCS or matched by a glob pattern from this variable, the entire subtree of contained files and directories will be registered in the final packing list. PORTDOCS should not be set if NOPORTDOCS is in effect. Installing the documentation at PORTDOCS as shown above remains up to the port itself. A typical example of utilizing PORTDOCS looks as follows: .if !defined(NOPORTDOCS) PORTDOCS= * .endif You can also use the pkg-message file to display messages upon installation. See the section on using pkg-message for details. The pkg-message file does not need to be added to pkg-plist. Subdirectories Try to let the port put things in the right subdirectories of PREFIX. Some ports lump everything and put it in the subdirectory with the port's name, which is incorrect. Also, many ports put everything except binaries, header files and manual pages in the a subdirectory of lib, which does not work well with the BSD paradigm. Many of the files should be moved to one of the following: etc (setup/configuration files), libexec (executables started internally), sbin (executables for superusers/managers), info (documentation for info browser) or share (architecture independent files). See &man.hier.7; for details; the rules governing /usr pretty much apply to /usr/local too. The exception are ports dealing with USENET news. They may use PREFIX/news as a destination for their files. Cleaning up empty directories Do make your ports clean up after themselves when they are de-installed. This is usually accomplished by adding @dirrm lines for all directories that are specifically created by the port. You need to delete subdirectories before you can delete parent directories. : lib/X11/oneko/pixmaps/cat.xpm lib/X11/oneko/sounds/cat.au : @dirrm lib/X11/oneko/pixmaps @dirrm lib/X11/oneko/sounds @dirrm lib/X11/oneko However, sometimes @dirrm will give you errors because other ports also share the same subdirectory. You can call rmdir from @unexec to remove only empty directories without warning. @unexec rmdir %D/share/doc/gimp 2>/dev/null || true This will neither print any error messages nor cause &man.pkg.delete.1; to exit abnormally even if PREFIX/share/doc/gimp is not empty due to other ports installing some files in there. UIDs If your port requires a certain user to be on the installed system, let the pkg-install script call pw to create it automatically. Look at net/cvsup-mirror for an example. If your port must use the same user/group ID number when it is installed as a binary package as when it was compiled, then you must choose a free UID from 50 to 999 and register it below. Look at japanese/Wnn6 for an example. Make sure you do not use a UID already used by the system or other ports. This is the current list of UIDs between 50 and 999. bind:*:53:53:Bind Sandbox:/:/sbin/nologin majordom:*:54:54:Majordomo Pseudo User:/usr/local/majordomo:/nonexistent rdfdb:*:55:55:rdfDB Daemon:/var/db/rdfdb:/bin/sh cyrus:*:60:60:the cyrus mail server:/nonexistent:/nonexistent gnats:*:61:1:GNATS database owner:/usr/local/share/gnats/gnats-db:/bin/sh proxy:*:62:62:Packet Filter pseudo-user:/nonexistent:/nonexistent uucp:*:66:66:UUCP pseudo-user:/var/spool/uucppublic:/usr/libexec/uucp/uucico xten:*:67:67:X-10 daemon:/usr/local/xten:/nonexistent pop:*:68:6:Post Office Owner (popper):/nonexistent:/sbin/nologin wnn:*:69:7:Wnn:/nonexistent:/nonexistent pgsql:*:70:70:PostgreSQL pseudo-user:/usr/local/pgsql:/bin/sh oracle:*:71:71::0:0:Oracle:/usr/local/oracle7:/sbin/nologin ircd:*:72:72:IRC daemon:/nonexistent:/nonexistent ircservices:*:73:73:IRC services:/nonexistent:/nonexistent ifmail:*:75:66:Ifmail user:/nonexistent:/nonexistent www:*:80:80:World Wide Web Owner:/nonexistent:/sbin/nologin alias:*:81:81:QMail user:/var/qmail/alias:/nonexistent qmaild:*:82:81:QMail user:/var/qmail:/nonexistent qmaill:*:83:81:QMail user:/var/qmail:/nonexistent qmailp:*:84:81:QMail user:/var/qmail:/nonexistent qmailq:*:85:82:QMail user:/var/qmail:/nonexistent qmailr:*:86:82:QMail user:/var/qmail:/nonexistent qmails:*:87:82:QMail user:/var/qmail:/nonexistent mysql:*:88:88:MySQL Daemon:/var/db/mysql:/sbin/nologin vpopmail:*:89:89:VPop Mail User:/usr/local/vpopmail:/nonexistent firebird:*:90:90:Firebird Database Administrator:/usr/local/firebird:/bin/sh mailman:*:91:91:Mailman User:/usr/local/mailman:/sbin/nologin gdm:*:92:92:GDM Sandbox:/:/sbin/nologin jabber:*:93:93:Jabber Daemon:/nonexistent:/nonexistent p4admin:*:94:94:Perforce admin:/usr/local/perforce:/sbin/nologin interch:*:95:95:Interchange user:/usr/local/interchange:/sbin/nologin squeuer:*:96:96:SQueuer Owner:/nonexistent:/bin/sh mud:*:97:97:MUD Owner:/usr/local/share/dgd:/bin/sh msql:*:98:98:mSQL-2 pseudo-user:/var/db/msqldb:/bin/sh rscsi:*:99:99:Remote SCSI:/usr/local/rscsi:/usr/local/sbin/rscsi squid:*:100:100:squid caching-proxy pseudo user:/usr/local/squid:/sbin/nologin quagga:*:101:101:Quagga route daemon pseudo user:/usr/local/etc/quagga:/sbin/nologin ganglia:*:102:102:Ganglia User:/nonexistent:/sbin/nologin sgeadmin:*:103:103:Sun Grid Engine Admin:/nonexistent:/sbin/nologin slimserv:*:104:104:Slim Devices SlimServer pseudo-user:/nonexistent:/sbin/nologin dnetc:*:105:105:distributed.net client and proxy pseudo-user:/nonexistent:/sbin/nologin clamav:*:106:106:Clamav Antivirus:/nonexistent:/sbin/nologin cacti:*:107:107:Cacti Sandbox:/nonexistent:/sbin/nologin webkit:*:108:108:WebKit Default User:/usr/local/www/webkit:/bin/sh quickml:*:109:109:quickml Server:/nonexistent:/sbin/nologin fido:*:111:111:Fido System:/usr/local/fido:/bin/sh postfix:*:125:125:Postfix Mail System:/var/spool/postfix:/sbin/nologin rbldns:*:153:153:rbldnsd pseudo-user:/nonexistent:/sbin/nologin sfs:*:171:171:Self-Certifying File System:/nonexistent:/sbin/nologin agk:*:172:172:AquaGateKeeper:/nonexistent:/nonexistent moinmoin:*:192:192:MoinMoin User:/nonexistent:/sbin/nologin ldap:*:389:389:OpenLDAP Server:/nonexistent:/sbin/nologin drweb:*:426:426:Dr.Web Mail Scanner:/nonexistent:/sbin/nologin courier:*:465:465:Courier Mail Server:/nonexistent:/sbin/nologin qtss:*:554:554:Darwin Streaming Server:/nonexistent:/sbin/nologin ircdru:*:555:555:Russian hybrid IRC server:/nonexistent:/bin/sh messagebus:*:556:556:D-BUS Daemon User:/nonexistent:/sbin/nologin bopm:*:717:717:Blitzed Open Proxy Monitor:/nonexistent:/bin/sh bacula:*:910:910:Bacula Daemon:/var/db/bacula:/sbin/nologin This is the current list of reserved GIDs. bind:*:53: rdfdb:*:55: cyrus:*:60: proxy:*:62: authpf:*:63: uucp:*:66: dialer:*:68: network:*:69: pgsql:*:70: www:*:80: qnofiles:*:81: qmail:*:82: mailman:*:91: postfix:*:125: maildrop:*:126: rbldns:*:153: moinmoin:*:192: courier:*:465: qtss:*:554: ircdru:*:555: messagebus:*:556: bopm:*:717: Please include a notice when you submit a port (or an upgrade) that reserves a new UID or GID in this range. This allows us to keep the list of reserved IDs up to date. Do things rationally The Makefile should do things simply and reasonably. If you can make it a couple of lines shorter or more readable, then do so. Examples include using a make .if construct instead of a shell if construct, not redefining do-extract if you can redefine EXTRACT* instead, and using GNU_CONFIGURE instead of CONFIGURE_ARGS += --prefix=${PREFIX}. If you find yourself having to write a lot of new code to try to do something, please go back and review bsd.port.mk to see if it contains an existing implementation of what you are trying to do. While hard to read, there are a great many seemingly-hard problems for which bsd.port.mk already provides a shorthand solution. Respect both <makevar>CC</makevar> and <makevar>CXX</makevar> The port should respect both CC and CXX variables. What we mean by this is that the port should not set the values of these variables absolutely, overriding existing values; instead, it should append whatever values it needs to the existing values. This is so that build options that affect all ports can be set globally. If the port does not respect these variables, please add NO_PACKAGE=ignores either cc or cxx to the Makefile. An example of a Makefile respecting both CC and CXX variables follows. Note the ?=: CC ?= gcc CXX ?= g++ Here is an example which respects neither CC nor CXX variables: CC = gcc CXX = g++ Both CC and CFLAGS variables can be defined on FreeBSD systems in /etc/make.conf. The first example defines a value if it was not previously set in /etc/make.conf, preserving any system-wide definitions. The second example clobbers anything previously defined. Respect <makevar>CFLAGS</makevar> The port should respect the CFLAGS variable. What we mean by this is that the port should not set the value of this variable absolutely, overriding the existing value; instead, it should append whatever values it needs to the existing value. This is so that build options that affect all ports can be set globally. If it does not, please add NO_PACKAGE=ignores cflags to the Makefile. An example of a Makefile respecting the CFLAGS variable follows. Note the +=: CFLAGS += -Wall -Werror Here is an example which does not respect the CFLAGS variable: CFLAGS = -Wall -Werror The CFLAGS variable is defined on FreeBSD systems in /etc/make.conf. The first example appends additional flags to the CFLAGS variable, preserving any system-wide definitions. The second example clobbers anything previously defined. Configuration files If your port requires some configuration files in PREFIX/etc, do not just install them and list them in pkg-plist. That will cause &man.pkg.delete.1; to delete files carefully edited by the user and a new installation to wipe them out. Instead, install sample files with a suffix (filename.sample will work well) and print out a message pointing out that the user has to copy and edit the file before the software can be made to work. Feedback Do send applicable changes/patches to the original author/maintainer for inclusion in next release of the code. This will only make your job that much easier for the next release. <filename>README.html</filename> Do not include the README.html file. This file is not part of the cvs collection but is generated using the make readme command. Marking a port <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or otherwise Invariably there will come a time when a particular port will contain a security vulnerability, will be radically broken and needs many hours of tender loving care, or is generally obsoleted, but for one reason or another should remain in the tree (and get fixed, right?). To designate a port as broken, there are three make variables that can be used in a port's Makefile. The value of the following make variables will be the reason that is given back to users for why the port was marked as broken. Please use the correct make variable as each make variable conveys radically different meanings to both users, and to automated systems that parse Makefiles. BROKEN is reserved for ports that do not work and should not be installed by users. This will prevent users from installing the port. TRYBROKEN is used for ports if you want to attempt a build of a BROKEN port. Ports marked as TRYBROKEN will be also built by the Pointyhat cluster. FORBIDDEN is used for ports that do contain a security vulnerability or induce grave concern regarding the security of a FreeBSD system with a given port installed (ex: a reputably insecure program or a program that provides easily exploitable services). Ports should be marked as FORBIDDEN as soon as a particular piece of software has a vulnerability and there is no released upgrade. Ideally ports should be upgraded as soon as possible when a security vulnerability is discovered so as to reduce the number of vulnerable FreeBSD hosts (we like being known for being secure), however sometimes there is a noticeable time gap between disclosure of a vulnerability and an updated release of the vulnerable software. Do not mark a port FORBIDDEN for any reason other than security. IGNORE is reserved for ports that should not be built for one reason or another. Users and the Pointyhat cluster will not, under any circumstances, build ports marked as IGNORE. If in doubt, do use IGNORE to prevent a port from being built. Do remember that these variables are to be used as a last resort if a port is not upgradeable. Permanently broken ports should be removed from the tree entirely. Necessary workarounds Sometimes it is necessary to work around bugs in software included with older versions of &os;. Some versions of &man.make.1; were broken on at least 4.8 and 5.0 with respect to handling comparisons based on OSVERSION. This would often lead to failures during make describe (and thus, the overall ports make index). The workaround is to enclose the conditional comparison in spaces, e.g.: if ( ${OSVERSION} > 500023 ) Be aware that test-installing a port on 4.9 or 5.2 will not detect this problem. Miscellanea The files pkg-descr and pkg-plist should each be double-checked. If you are reviewing a port and feel they can be worded better, do so. Do not copy more copies of the GNU General Public License into our system, please. Please be careful to note any legal issues! Do not let us illegally distribute software! If you are stuck… Do look at existing examples and the bsd.port.mk file before asking us questions! ;-) Do ask us questions if you have any trouble! Do not just beat your head against a wall! :-) A Sample <filename>Makefile</filename> Here is a sample Makefile that you can use to create a new port. Make sure you remove all the extra comments (ones between brackets)! It is recommended that you follow this format (ordering of variables, empty lines between sections, etc.). This format is designed so that the most important information is easy to locate. We recommend that you use portlint to check the Makefile. [the header...just to make it easier for us to identify the ports.] # New ports collection makefile for: xdvi [the "version required" line is only needed when the PORTVERSION variable is not specific enough to describe the port.] # Date created: 26 May 1995 [this is the person who did the original port to FreeBSD, in particular, the person who wrote the first version of this Makefile. Remember, this should not be changed when upgrading the port later.] # Whom: Satoshi Asami <asami@FreeBSD.org> # # $FreeBSD$ [ ^^^^^^^^^ This will be automatically replaced with RCS ID string by CVS when it is committed to our repository. If upgrading a port, do not alter this line back to "$FreeBSD$". CVS deals with it automatically.] # [section to describe the port itself and the master site - PORTNAME and PORTVERSION are always first, followed by CATEGORIES, and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that. Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then EXTRACT_ONLY, as necessary.] PORTNAME= xdvi PORTVERSION= 18.2 CATEGORIES= print [do not forget the trailing slash ("/")! if you are not using MASTER_SITE_* macros] MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications PKGNAMEPREFIX= ja- DISTNAME= xdvi-pl18 [set this if the source is not in the standard ".tar.gz" form] EXTRACT_SUFX= .tar.Z [section for distributed patches -- can be empty] PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz [maintainer; *mandatory*! This is the person (preferably with commit privileges) whom a user can contact for questions and bug reports - this person should be the porter or someone who can forward questions to the original porter reasonably promptly. If you really do not want to have your address here, set it to "ports@FreeBSD.org".] MAINTAINER= asami@FreeBSD.org COMMENT= A DVI Previewer for the X Window System [dependencies -- can be empty] RUN_DEPENDS= gs:${PORTSDIR}/print/ghostscript LIB_DEPENDS= Xpm.5:${PORTSDIR}/graphics/xpm [this section is for other standard bsd.port.mk variables that do not belong to any of the above] [If it asks questions during configure, build, install...] IS_INTERACTIVE= yes [If it extracts to a directory other than ${DISTNAME}...] WRKSRC= ${WRKDIR}/xdvi-new [If the distributed patches were not made relative to ${WRKSRC}, you may need to tweak this] PATCH_DIST_STRIP= -p1 [If it requires a "configure" script generated by GNU autoconf to be run] GNU_CONFIGURE= yes [If it requires GNU make, not /usr/bin/make, to build...] USE_GMAKE= yes [If it is an X application and requires "xmkmf -a" to be run...] USE_IMAKE= yes [et cetera.] [non-standard variables to be used in the rules below] MY_FAVORITE_RESPONSE= "yeah, right" [then the special rules, in the order they are called] pre-fetch: i go fetch something, yeah post-patch: i need to do something after patch, great pre-install: and then some more stuff before installing, wow [and then the epilogue] .include <bsd.port.mk> Automated package list creation First, make sure your port is almost complete, with only pkg-plist missing. Next, create a temporary directory tree into which your port can be installed, and install any dependencies. port-type should be local for non-X ports and x11-4 or x11 for ports which install into the directory hierarchy of XFree86 4 or an earlier XFree86 release, respectively. &prompt.root; mkdir /var/tmp/port-name &prompt.root; mtree -U -f /etc/mtree/BSD.port-type.dist -d -e -p /var/tmp/port-name &prompt.root; make depends PREFIX=/var/tmp/port-name Store the directory structure in a new file. &prompt.root; (cd /var/tmp/port-name && find -d * -type d) | sort > OLD-DIRS Create an empty pkg-plist file: &prompt.root; touch pkg-plist If your port honors PREFIX (which it should) you can then install the port and create the package list. &prompt.root; make install PREFIX=/var/tmp/port-name &prompt.root; (cd /var/tmp/port-name && find -d * \! -type d) | sort > pkg-plist You must also add any newly created directories to the packing list. &prompt.root; (cd /var/tmp/port-name && find -d * -type d) | sort | comm -13 OLD-DIRS - | sort -r | sed -e 's#^#@dirrm #' >> pkg-plist Finally, you need to tidy up the packing list by hand; it is not all automated. Manual pages should be listed in the port's Makefile under MANn, and not in the package list. User configuration files should be removed, or installed as filename.sample. The info/dir file should not be listed and appropriate install-info lines should be added as noted in the info files section. Any libraries installed by the port should be listed as specified in the shared libraries section. Alternatively, use the plist script in /usr/ports/Tools/scripts/ to build the package list automatically. The first step is the same as above: take the first three lines, that is, mkdir, mtree and make depends. Then build and install the port: &prompt.root; make install PREFIX=/var/tmp/port-name And let plist create the pkg-plist file: &prompt.root; /usr/ports/Tools/scripts/plist -Md -m /etc/mtree/BSD.port-type.dist /var/tmp/port-name > pkg-plist The packing list still have to tidied up the by hand as stated above. Keeping Up The &os; Ports Collection is constantly changing. Here is some information on how to keep up. FreshPorts One of the easiest ways to learn about updates that have already been committed is by subscribing to FreshPorts. You can select multiple ports to monitor. Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any changes that any other &os; committer has made. (These are often necessary to keep up with changes in the underlying ports framework—although it would be most polite to receive an advance heads-up from those committing such changes, sometimes this is overlooked or just simply impractical. Also, in some cases, the changes are very minor in nature. We expect everyone to use their best judgement in these cases.) If you wish to use FreshPorts, all you need is an account. If your registered email address is @FreeBSD.org, you'll see the opt-in link on the right hand side of the webpages. For those of you who already have a FreshPorts account, but are not using your @FreeBSD.org email address, just change your email to @FreeBSD.org, subscribe, then change it back again. FreshPorts also has a sanity test feature which automatically tests each commit to the FreeBSD ports tree. If subscribed to this service, you will be notified of any errors which FreshPorts detects during sanity testing of your commits. The Web Interface to the Source Repository It is possible to browse the files in the source repository by using a web interface. Changes that affect the entire port system are now documented in the CHANGES file. Changes that affect individual ports are now documented in the UPDATING file. However, the definitive answer to any question is undoubtedly to read the source code of bsd.port.mk, and associated files. The &os; Ports Mailing List If you maintain ports, you should consider following the &a.ports;. Important changes to the way ports work will be announced there, and then committed to CHANGES. The &os; Port Building Cluster One of the least-publicized strengths of &os; is that an entire cluster of machines is dedicated to continually building the Ports Collection, for each of the major OS releases and for each Tier-1 architecture. You can find the results of these builds at package building logs and errors. The &os; Port Distfile Survey The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched. However, as the Internet continually changes, distfiles can quickly go missing. The FreeBSD Ports distfiles survey attempts to query every download site for every port to find out if each distfile is still currently available. Maintainers are asked to check this report periodically, not only to speed up the building process for users, but to help avoid wasting bandwidth of the sites that volunteer to host all these distfiles. The &os; Ports Monitoring System Another handy resource is the - + FreeBSD Ports Monitoring System (also known as portsmon). This system comprises a database that processes information from several sources and allows its to be browsed via a web interface. Currently, the ports Problem Reports (PRs), the error logs from the build cluster, and individual files from the ports collection are used. In the future, this will be expanded to include the distfile survey, as well as other sources. To get started, you can view all information about a particular port by using the - + Overview of One Port.